// Copyright 2019 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

library fuchsia.app.agent;

using fuchsia.app;
using fuchsia.app.sessioncontrol;
using fuchsia.io;

/// An agent is a component which provides services in support of modules in a
/// story. Agents cannot show UI directly.
///
/// - An agent is a singleton instance within the scope of a session.
/// - Components can connect to an Agent using the Context service provided to
///   each modular component class (fuchsia.app.agent, fuchsia.app.module,
///   fuchsia.app.storyshell, fuchsia.app.sessionshell).
/// - An agent vends services and resources to components that connect to it over a
///   fuchsia.io.Directory.
/// - An agent is started when someone wants to connect to it, or when a task it
///   has scheduled has triggered.
///
/// This FIDL interface MUST be implemented for agent components.
///
/// For more info see:
/// - peridot/docs/modular/agent.md
/// - fuchsia.app.agent.Context for common methods provided by modular to agents.
/// - fuchsia.app.Lifecycle for how agents receive lifecycle events.
[Discoverable]
protocol Agent {
    /// Called when a client of this agent wishes to acquire a service directory from this agent.
    ///
    /// |client| describes the identity of the client component. See ClientIdentity below.
    ///
    /// |directory_request| should be bound to a fuchsia.io.Directory implementation or closed
    /// if services are denied. The Agent implementation should keep |directory_request| bound
    /// and available until the client closes it. At this point, it must NOT assume that
    /// the client itself is gone, but rather that the client no longer wishes to open new
    /// services connections.
    AcceptConnection(ClientIdentity client, request<fuchsia.io.Directory> directory_request);

    /// Called when a task identified by |task| is scheduled to run. Tasks are scheduled run when
    /// the conditions described in |task.type| become true. Tasks are scheduled using
    /// fuchsia.app.agent.Context/ScheduleTask().
    ///
    /// Agents must return from RunTask() when the task has finished. The Agent may be asked to
    /// terminate in the middle of task execution.
    ///
    /// TODO(MF-321): The current implementation permits the Agent to run a task until its callback
    /// returns, no matter how long. There is no mechanism to cancel an ongoing task.
    RunTask(TaskInfo task) -> ();
};

table ClientIdentity {
    /// The component URL of the requesting client, as formatted at the time of component creation.
    ///
    /// Always set.
    1: fuchsia.app.ComponentUrl component_url;

    /// If the client is a module created by this agent (using
    /// fuchsia.app.sessioncontrol.StoryController), identifies the StoryId the agent specified at
    /// module creation time. Otherwise not set.
    ///
    /// See fuchsia.app.sessioncontrol.StoryController.
    2: fuchsia.app.StoryId story_id;

    /// If the client is a module created by this agent (using
    /// fuchsia.app.sessioncontrol.StoryController), identifies the ModuleId the agent specified at
    /// module creation time. Otherwise not set.
    ///
    /// See fuchsia.app.sessioncontrol.StoryController.
    3: fuchsia.app.sessioncontrol.ModuleId module_id;
};