// Copyright 2017 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.modular;

using fuchsia.sys;

/// An agent is a component whose lifecycle is not tied to any Story.
///
/// - An agent is a singleton instance.
/// - Components can connect to an Agent using the
///   fuchsia.modular.ComponentContext capability.
/// - An agent vends services to components that connect to it over a
///   ServiceProvider.
/// - An agent is started when someone wants to connect to it, or when a task it
///   has scheduled has triggered.
///
/// This FIDL interface should be implemented by a component that is meant to be
/// run as an Agent.
///
/// When an agent application implements the |Lifecycle| interface, it can
/// receive a signal for when it should stop. An agent may be stopped for the
/// following reasons:
///
/// (1) All |AgentController| connections associated with this agent are closed.
///
/// (2) The system wants to optimize for resources.
///
/// Once the framework delivers a |Lifecycle.Terminate()|, the agent application
/// may exit itself, or is killed by framework after a timeout.
///
/// For more info see:
/// - fuchsia.modular.AgentContext and fuchsia.modular.ComponentContext for
///   capabilities an agent has.
/// - fuchsia.modular.Lifecycle for how Components get lifecycle events.
[Discoverable] // Created by each agent.
interface Agent {
    /// Called when some component tries to connect to this agent. |requestor_url|
    /// is the identifier for the component which called
    /// |ComponentContext.ConnectToAgent()|. The |services| are provided to that
    /// component.
    1: Connect(string requestor_url, request<fuchsia.sys.ServiceProvider> services);

    /// Called when some task identified by |task_id| is scheduled to run. The task
    /// was first posted by this Agent using |AgentContext.ScheduleTask()|. The
    /// return callback is called by this Agent when all work related to this task
    /// is completed. Note that the framework may call |Lifecycle.Terminate()|
    /// before RunTask returns.
    ///
    /// TODO(alhaad): The current implementation allows the Agent to run a task
    /// until its callback returns. If the task takes a long time to finish, the
    /// framework has no way to signal a request for termination other than to shut
    /// down the entire Agent instance. Instead, we should cap task length with
    /// strategies like budgets. Also, the Task should likely have its own
    /// connection that allows for more signalling.
    2: RunTask(string task_id) -> ();
};