cmdc

defmodule CMDC.Gateway do
  @moduledoc """
  出站事件推送契约。

  Gateway 是 Kernel 与外部系统之间的单向通信抽象层，负责把 Agent 运行时事件
  推送到外部（Web 管理层、监控系统、日志收集等）。

  ## 设计原则

  - **只出不入**：Gateway 只负责向外推事件，不接收外部指令（入站直接调公开 API）
  - **极简抽象**：不做业务逻辑
  - **三种部署模式**：嵌入式（Local）、分布式（Distributed，未来）、HTTP（未来）

  ## 实现示例

      defmodule MyApp.Gateway.Phoenix do
        @behaviour CMDC.Gateway

        @impl true
        def report_event(session_id, %CMDC.Event{} = event) do
          MyApp.Endpoint.broadcast("agents:" <> session_id, "event", event)
        end

        @impl true
        def report_agent_state(session_id, state_info) do
          MyApp.Endpoint.broadcast("agents:" <> session_id, "state", state_info)
        end
      end

  ## `report_agent_state/2` 的 state_info 格式

      %{
        state:        :idle | :running | :streaming | :executing_tools,
        session_id:   String.t(),
        turns:        non_neg_integer(),
        cost_usd:     float(),
        uptime_ms:    non_neg_integer(),
        timestamp_ms: integer()
      }
  """

  @doc """
  上报一个 Agent 运行时事件。

  - `session_id` — 产生事件的会话 ID
  - `event` — `CMDC.Event.t()` struct
  """
  @callback report_event(session_id :: String.t(), event :: CMDC.Event.t()) :: :ok

  @doc """
  上报 Agent 状态变更快照。

  - `session_id` — 产生状态变更的会话 ID
  - `state_info` — 状态信息 map，含 `:state` / `:session_id` / `:turns` /
    `:cost_usd` / `:uptime_ms` / `:timestamp_ms`
  """
  @callback report_agent_state(session_id :: String.t(), state_info :: map()) :: :ok
end