Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

9.9 KB
Raw Blame
/**
 * AMSP (Agent Message Stream Protocol): the wire types.
 *
 * MMSP streams one model call; AMSP streams one run of an Agent — one Task — on a Session the
 * caller continues by id. A run is a `text/event-stream` of `data: <JSON>` blocks, one event
 * each, closed by `data: [DONE]`:
 *
 *   stream  := run.started body* run.done
 *   request := request.started (item | tool_result | approval | hook.fired)* request.done
 *   item    := K.delta* K.done        ; K = thinking | text | tool_call | inline_data | inline_thinking
 *
 * Events are flat objects discriminated by `type`, snake_case on the wire like MMSP and the
 * OmniMessage payloads they are projected from. `run.done` is the one terminal event and always
 * arrives, errors included. Clients must ignore a `type` they do not know: new event types and
 * optional fields are additive within `/v1`; a change to an existing field's meaning is `/v2`.
 *
 * A Request pair brackets the model's output, not the tools: the engine runs a tool as soon as
 * its call is complete, so the approval and the start of the result arrive while the Request is
 * still open, and the result may end after `request.done` (always before the next
 * `request.started` of the same origin). Attribute results by `tool_call_id`. Fragments and
 * complete items are forwarded as the engine produced them and never rebuilt from each other.
 *
 * The server's translator produces these events and imports this file as types; the client
 * consumes them.
 */

// ---- vocabulary shared with OmniMessage (same strings, same meaning) ----
export type StopReason = "completed" | "aborted" | "retryable" | "fatal";
export type Role = "user" | "assistant";
export type ApprovalDecision = "allow" | "deny" | "forbidden";
export type Sender = "user" | "parent_agent" | "harness" | "server";
export type CompactionReason = "context" | "turns" | "manual";
export type CompactionMode = "summarize" | "discard";
export type HookPoint = "stop" | "pre_tool_use" | "user_prompt";
export type HookDecision = "continue" | "stop" | "allow" | "deny";
export type SessionStatus = "idle" | "running" | "compacting";

export interface TokenCounts {
  cache_read: number;
  cache_write: number;
  output: number;
  total: number;
}
/** The one error shape: `code` snake_case and stable (OmniMessage ErrorCode values plus AMSP's own, listed in the protocol reference); `message` raw text. */
export interface AmspError {
  code: string;
  message: string;
}
export interface ToolDefinition {
  name: string;
  description: string;
  parameters?: Record<string, unknown>;
}
export interface McpServerResult {
  server: string;
  transport: "stdio" | "http" | "sse";
  status: StopReason;
  duration_ms: number;
  tools?: number;
  error?: AmspError;
}

interface Base {
  /** ISO 8601 UTC. */
  at: string;
  /** Child-Session chain, outer→inner (OmniMessage `origin`); absent = the main Session. */
  origin?: string[];
}

// ---- run layer ----
export interface RunStarted extends Base {
  type: "run.started";
  session_id: string;
  agent: string /* "<projectId>/<agentId>" */;
}
export interface RunDone extends Base {
  type: "run.done";
  status: StopReason;
  error?: AmspError;
  /** Model Requests this run issued (attempts included). */
  requests: number;
  usage: TokenCounts;
  session_usage: TokenCounts | null;
}

// ---- context / bootstrap ----
/**
 * A new model context the engine streams: a child Session starting (with `origin`) or, between
 * runs, a model switch. The context a compaction opens is recorded in the Trace, not streamed, so
 * none follows `compaction.done`.
 */
export interface ContextOpened extends Base {
  type: "context.opened";
  session_id: string;
  provider: string;
  model_id: string;
  context_window: number | "unknown";
}
export interface McpConnectStarted extends Base {
  type: "mcp_connect.started";
  servers: string[];
}
export interface McpConnectDone extends Base {
  type: "mcp_connect.done";
  status: StopReason;
  results: McpServerResult[];
  error?: AmspError;
}
export interface ToolsReady extends Base {
  type: "tools.ready";
  tools: ToolDefinition[];
}

// ---- request layer ----
export interface RequestStarted extends Base {
  type: "request.started";
  request: number /* 1-based within the run */;
}
/** The Request ended. Results of the tools it called may still follow, before the next `request.started`. */
export interface RequestDone extends Base {
  type: "request.done";
  request: number;
  status: StopReason;
  usage: TokenCounts | null;
  error?: AmspError;
  /** 1-based attempt ordinal; present on retries and failures (OmniMessage `attempt`). */
  attempt?: number;
  /** Present only when the engine will retry this failure within the run. */
  retry_in_ms?: number;
}

// ---- item layer: fragments ----
export interface TextDelta extends Base {
  type: "text.delta";
  role: "assistant";
  text: string;
}
export interface ThinkingDelta extends Base {
  type: "thinking.delta";
  thinking: string;
}
export interface ToolCallDelta extends Base {
  type: "tool_call.delta";
  tool_call_id: string;
  /** Set on the first fragment; may be empty afterwards. */
  name: string;
  /** A piece of the arguments text as the provider streamed it. */
  arguments: string;
}
/** Output a running tool has produced so far; may arrive while the Request that made the call is still open. */
export interface ToolResultDelta extends Base {
  type: "tool_result.delta";
  tool_call_id: string;
  output: string;
  /** Not incremental: one fragment carries the whole set. */
  images?: string[];
}
/**
 * A fragment of a compaction's summary. A streamed summary has no `summary.done`: the engine
 * streams the fragments or delivers the text whole, never both, and nothing rebuilds one from the
 * other.
 */
export interface SummaryDelta extends Base {
  type: "summary.delta";
  text: string;
}

// ---- item layer: complete items ----
export interface TextDone extends Base {
  type: "text.done";
  role: Role;
  text: string;
  stop_reason: StopReason;
  /** On user-role texts the harness injected mid-run. */
  sender?: Sender;
}
export interface ThinkingDone extends Base {
  type: "thinking.done";
  thinking: string;
  stop_reason: StopReason;
}
export interface ToolCallDone extends Base {
  type: "tool_call.done";
  tool_call_id: string;
  name: string;
  /**
   * The complete arguments as a JSON string: the engine's serialization of the parsed call, which
   * the fragments joined need not equal character for character (`{"command": "ls"}` streamed,
   * `{"command":"ls"}` here) but parse to the same object; parse with `parseArguments`. A call cut
   * short (`stop_reason` other than `completed`) carries the text received so far instead.
   */
  arguments: string;
  stop_reason: StopReason;
}
/** The tool's result as the model receives it; may arrive after the call's `request.done`, always before the next `request.started` of the same origin. */
export interface ToolResultDone extends Base {
  type: "tool_result.done";
  tool_call_id: string;
  output: string;
  images?: string[];
  stop_reason: StopReason;
}
export interface InlineDataDone extends Base {
  type: "inline_data.done";
  role: Role;
  mime_type: string;
  /** base64 */
  data: string;
  stop_reason: StopReason;
}
export interface InlineThinkingDone extends Base {
  type: "inline_thinking.done";
  mime_type: string;
  data: string;
  stop_reason: StopReason;
}
export interface ImageUrlDone extends Base {
  type: "image_url.done";
  role: "user";
  image_url: string;
}
/** A compaction's summary delivered whole; absent when the summary was streamed. */
export interface SummaryDone extends Base {
  type: "summary.done";
  text: string;
  stop_reason: StopReason;
}

// ---- approvals ----
/** A tool call waiting for the caller's answer; arrives while the call's Request is still open and carries the whole call. */
export interface ApprovalRequested extends Base {
  type: "approval.requested";
  tool_call: { tool_call_id: string; name: string; arguments: string };
}
export interface ApprovalDecided extends Base {
  type: "approval.decided";
  tool_call_id: string;
  decision: ApprovalDecision;
}

// ---- compaction ----
export interface CompactionStarted extends Base {
  type: "compaction.started";
  reason: CompactionReason;
  mode: CompactionMode;
  context: number;
  turns: number;
}
export interface CompactionDone extends Base {
  type: "compaction.done";
  reason: CompactionReason;
  mode: CompactionMode;
  status: StopReason;
  usage: TokenCounts | null;
  error?: AmspError;
  attempt?: number;
}

// ---- hooks ----
export interface HookFired extends Base {
  type: "hook.fired";
  hook: HookPoint;
  name: string;
  decision?: HookDecision;
  reason?: string;
  output?: Record<string, string | number | boolean>;
}

export type AmspEvent =
  | RunStarted
  | RunDone
  | ContextOpened
  | McpConnectStarted
  | McpConnectDone
  | ToolsReady
  | RequestStarted
  | RequestDone
  | TextDelta
  | ThinkingDelta
  | ToolCallDelta
  | ToolResultDelta
  | SummaryDelta
  | TextDone
  | ThinkingDone
  | ToolCallDone
  | ToolResultDone
  | InlineDataDone
  | InlineThinkingDone
  | ImageUrlDone
  | SummaryDone
  | ApprovalRequested
  | ApprovalDecided
  | CompactionStarted
  | CompactionDone
  | HookFired;

// ---- requests / responses ----
export type InputItem =
  | { type: "text"; text: string }
  | { type: "image_url"; image_url: string /* data: URL or http(s) URL */ };
export interface RunRequest {
  session_id?: string;
  input: string | InputItem[];
}
export interface AgentInfo {
  id: string /* "<projectId>/<agentId>" */;
  name?: string;
  description?: string;
}
export interface AgentResponse {
  agent: AgentInfo;
}
export interface SessionInfo {
  id: string;
  agent: string;
  status: SessionStatus;
  provider: string;
  model_id: string;
  created_at: string;
  last_active_at: string;
}
export interface SessionResponse {
  session: SessionInfo;
}
export interface ApprovalRequest {
  decision: "allow" | "deny";
}
export interface ErrorResponse {
  error: AmspError;
}