@robota-sdk/agent-transport 3.0.0-beta.100

package/src/wire-messages.ts

@@ -0,0 +1,436 @@
+import type {
+  IToolAppView,
+  IToolExecutionResult,
+  TToolParameters,
+  TUniversalMessagePart,
+} from '@robota-sdk/agent-core';
+import type {
+  IPersonalUsageReport,
+  IPersonalUsageRequest,
+  IUsageBySourceReport,
+} from '@robota-sdk/agent-interface-analytics';
+import type {
+  ICommandListEntry,
+  ICommandResult,
+  ICommandSkillListEntry,
+} from '@robota-sdk/agent-interface-command';
+import type {
+  IBackgroundJobGroupState,
+  IExecutionDetailCursor,
+  IExecutionDetailPage,
+  IExecutionWorkspaceSnapshot,
+  TBackgroundJobGroupEvent,
+} from '@robota-sdk/agent-interface-execution';
+import type {
+  IBackgroundTaskInput,
+  IBackgroundTaskListFilter,
+  IBackgroundTaskLogCursor,
+  IBackgroundTaskLogPage,
+  IBackgroundTaskState,
+  TBackgroundTaskEvent,
+} from '@robota-sdk/agent-interface-execution';
+import type {
+  IAskRequestEvent,
+  IBranchEvent,
+  ICompactEvent,
+  IExecutionResult,
+  IContextFileRefreshedEvent,
+  IModelListGroup,
+  IPermissionRequestEvent,
+  IPromptResolvedEvent,
+  IPlanApprovalEvent,
+  ISessionRenamedEvent,
+  ISettingsSnapshot,
+  IToolState,
+  ISessionListing,
+  ISessionStatusSnapshot,
+  ISessionSwitchedEvent,
+  TSessionChangeRefusalCode,
+  TSessionDeleteRefusalCode,
+  TSettingsPatch,
+  IUiIntentEvent,
+  TPermissionResultValue,
+  TProjectDiffRead,
+  TProjectMemoryRead,
+  TProjectStatusRead,
+  TWaitingLoopStopOutcome,
+} from '@robota-sdk/agent-interface-session';
+import type {
+  ISessionConversationRead,
+  TDriverId,
+  TTurnSource,
+} from '@robota-sdk/agent-interface-session';
+import type { TActionResponse } from '@robota-sdk/agent-interface-transport';
+
+export type TBackgroundControlAction = 'cancel' | 'close' | 'send';
+
+type THistoryEntry = ReturnType<ISessionConversationRead['getFullHistory']>[number];
+
+/**
+ * #3282 §4: one agent the switcher can offer. `definedIn` is a plain-words location — a discovered
+ * file's path, or "Built-in" — never a raw internal id.
+ */
+export interface IWireAgentDefinitionSummary {
+  name: string;
+  description: string;
+  definedIn: string;
+}
+
+/**
+ * #3189: one entry of the session's full history as it crosses the wire. The same record the session
+ * keeps, except that `timestamp` is an ISO 8601 string: a `Date` does not survive JSON, and a
+ * declared `Date` that arrives as a string would let a client call `Date` methods on a string.
+ */
+export interface IWireHistoryEntry extends Omit<THistoryEntry, 'timestamp'> {
+  /** ISO 8601. */
+  timestamp: string;
+}
+
+/**
+ * #3189: a turn's result as it crosses the wire. The session's whole history stays behind: it only
+ * grows, so a client reads it in bounded pages with `get-history` instead.
+ */
+export type TWireExecutionResult = Omit<IExecutionResult, 'history'>;
+
+/** Inbound message from client to server. */
+export type TClientMessage =
+  | { type: 'submit'; prompt: string }
+  // `requestId` is echoed on the command's `command_result` or `protocol_error`, so a client with
+  // several commands in flight knows which one each answer settles.
+  | { type: 'command'; name: string; args?: string; requestId?: string }
+  | { type: 'abort' }
+  | { type: 'cancel-queue' }
+  | { type: 'get-messages' }
+  // #3189: the session's full history — what a client that renders the whole session (the TUI) shows —
+  // one bounded page at a time, from `fromIndex` (default 0). The client asks for the next page
+  // after the previous one arrived, so replies never pile up in the connection.
+  | { type: 'get-history'; fromIndex?: number }
+  // #3189: the permission and ask prompts open now, each sent again as the frame that asked it: a
+  // client that attached after a prompt was asked has not seen it.
+  | { type: 'get-prompts' }
+  | { type: 'get-context' }
+  // #3186: what every client needs beside the conversation — the commands and skills it can offer
+  // (a `/` menu), and the session's status (model, permission mode, effort, context).
+  | { type: 'get-commands' }
+  | { type: 'get-status' }
+  // #3282 §2: the models the GUI's model menu offers, grouped by configured provider profile — so
+  // the GUI never scrapes `/model`'s picker text. Choosing one sends `command` with `name: 'model'`,
+  // the SAME path `/model <id>` runs; this message only reads the choices.
+  | { type: 'list-models'; requestId: string }
+  // #3282 §4: the agent switcher's roster and its currently-selected default — so the GUI never
+  // scrapes `/agent`'s text. Choosing one sends `command` with `name: 'agent'`, the SAME path
+  // `/agent <name>` runs; this message only reads the roster and the current selection.
+  | { type: 'get-agent-definitions'; requestId: string }
+  // #3189: the host's sessions — list them, start a new one, make another current. A refused change
+  // answers `session_change_failed` with the same `requestId`.
+  | { type: 'list-sessions'; requestId: string }
+  | { type: 'new-session'; requestId?: string }
+  | { type: 'switch-session'; sessionId: string; requestId?: string }
+  // #3289 §1: rename a session from the list — current or not. Answered by `session_renamed_in_list`
+  // or `session_rename_failed`, both carrying the same `requestId`.
+  | { type: 'rename-session'; sessionId: string; name: string; requestId: string }
+  // #3289 §1: remove a stored session's record for good. Answered by `session_deleted` or
+  // `session_delete_failed`, both carrying the same `requestId`.
+  | { type: 'delete-session'; sessionId: string; requestId: string }
+  // SELFHOST-004: request the assembled trace/cost read-model (spans + cost-by-source) for the run.
+  | { type: 'get-usage-report' }
+  | {
+      type: 'get-personal-usage-report';
+      requestId: string;
+      period: IPersonalUsageRequest['period'];
+      timezone: string;
+    }
+  | { type: 'get-stored-session-usage-report'; requestId: string; sessionId: string }
+  | { type: 'get-executing' }
+  | { type: 'get-pending' }
+  | { type: 'get-execution-workspace' }
+  // One page of what a workspace entry recorded, from `cursor` (the previous page's `nextCursor`).
+  // Answered by `execution_detail` or `execution_detail_error` with the same `requestId`.
+  | {
+      type: 'read-execution-detail';
+      requestId: string;
+      entryId: string;
+      cursor?: IExecutionDetailCursor;
+    }
+  // Stop the self-paced loop that is waiting for its next wake; answered by `waiting_loop_stop`.
+  | { type: 'stop-waiting-loop'; requestId: string }
+  // #3282 §4c: the Project panel's "Changes" section — this workspace's git status. Answered by
+  // `project_status`, echoing `requestId`.
+  | { type: 'project-status'; requestId: string }
+  // The Project panel's "File diff" section for one file `project_status` reported — `path` exactly
+  // as reported (workspace-relative; the server re-checks it stays inside the workspace). Answered by
+  // `project_diff`.
+  | { type: 'project-diff'; requestId: string; path: string }
+  // The Project panel's "Memory" section — project memory as readable text. Answered by
+  // `project_memory`.
+  | { type: 'project-memory'; requestId: string }
+  // A driving surface invokes one runtime tool for a hosted app view, through the session's
+  // permission gate; a prompt it raises is attributed to that surface's driver. `viewId` names the
+  // view (from a `tool_end`'s `appView`) and limits the call to the tools that view's own source
+  // declared. Answered by `app_tool_result`; a call that decoded but is refused (the view is gone,
+  // the tool is not the view's, the invocation is refused) is answered by `protocol_error` echoing
+  // `requestId`. A frame that does not decode, or one an observer sends, carries no `requestId`.
+  | {
+      type: 'call-app-tool';
+      requestId: string;
+      viewId: string;
+      name: string;
+      arguments: TToolParameters;
+    }
+  // A driving surface reads the view a finished model call named in its `tool_end` (`appView`).
+  // Answered by `app_view`; a read that decoded but cannot be served (gone, or too large to send)
+  // is answered by `protocol_error` echoing `requestId`.
+  | { type: 'read-app-view'; requestId: string; viewId: string }
+  | { type: 'get-background-tasks'; filter?: IBackgroundTaskListFilter }
+  | { type: 'get-background-task'; taskId: string }
+  | { type: 'get-background-job-groups' }
+  | { type: 'get-background-job-group'; groupId: string }
+  | { type: 'wait-background-job-group'; groupId: string }
+  | { type: 'cancel-background-task'; taskId: string; reason?: string }
+  | { type: 'close-background-task'; taskId: string }
+  | { type: 'send-background-task'; taskId: string; input: IBackgroundTaskInput }
+  | { type: 'read-background-task-log'; taskId: string; cursor?: IBackgroundTaskLogCursor }
+  // REMOTE-007: a driving client answers a pending permission/ask prompt by id (first answer wins).
+  | { type: 'permission-response'; id: string; result: TPermissionResultValue }
+  | { type: 'ask-response'; id: string; response: TActionResponse }
+  // REMOTE-013 E4 session-resume: `resume` asks the host to replay the tail after `lastSeq` (the last seq the
+  // client applied); `ack` lets the host free its un-acked buffer up to `seq`. Only meaningful post-E3-accept.
+  | { type: 'resume'; lastSeq: number }
+  | { type: 'ack'; seq: number }
+  // #3282 §4a: the GUI Settings screen. A snapshot fetch and a discriminated single-field patch,
+  // never command text — the server applies a patch through the same function its slash command
+  // uses, so the two paths cannot drift. Answered by `settings` or `settings_error`.
+  | { type: 'get-settings'; requestId: string }
+  | { type: 'update-settings'; requestId: string; patch: TSettingsPatch };
+
+/** Outbound message from server to client. */
+export type TServerMessage =
+  // REMOTE-014 E5: turn-authored events optionally carry the ACTIVE turn's `driverId` (co-drive authorship,
+  // display-only). Stamped at `subscribeSessionEvents` from `getActiveDriverId()`; background/goal/memory/
+  // execution-workspace events are NEVER stamped (they are not authored by a driver turn).
+  | { type: 'text_delta'; delta: string; driverId?: TDriverId }
+  | { type: 'user_message'; content: string; driverId?: TDriverId }
+  | { type: 'tool_start'; state: IToolState; driverId?: TDriverId }
+  | { type: 'tool_end'; state: IToolState; driverId?: TDriverId }
+  | { type: 'thinking'; isThinking: boolean; driverId?: TDriverId }
+  | { type: 'complete'; result: TWireExecutionResult; driverId?: TDriverId }
+  | { type: 'interrupted'; result: TWireExecutionResult; driverId?: TDriverId }
+  | {
+      type: 'error';
+      /** The raw failure text — kept for a "Details" disclosure; never the whole story on its own. */
+      message: string;
+      /**
+       * What kind of failure this was, when it's known — so a renderer can say what happened and
+       * what to do next in plain words instead of showing `message` verbatim (#3289 §3). Additive:
+       * absent for a session error this classification does not recognize (unchanged behavior).
+       */
+      code?: 'auth' | 'rate_limit' | 'model_unavailable' | 'network' | 'provider';
+      /** The provider/profile name the failure came from, when `code` names one. */
+      provider?: string;
+      /** For `code: 'rate_limit'`, how long until a retry may succeed, when the provider said so. */
+      retryAfterSeconds?: number;
+      /**
+       * For `code: 'model_unavailable'`, the model the failed request tried — captured at the moment
+       * of failure so a renderer never has to fall back to whatever model is live by the time it
+       * draws this notice (which may already be a different one the person switched to).
+       */
+      model?: string;
+      driverId?: TDriverId;
+    }
+  | {
+      type: 'command_result';
+      name: string;
+      message: string;
+      success: boolean;
+      data?: ICommandResult['data'];
+      /** The `requestId` of the `command` this answers, when it carried one. */
+      requestId?: string;
+    }
+  | {
+      type: 'messages';
+      messages: ReturnType<ISessionConversationRead['getMessages']>;
+      /**
+       * #3288 §2: the SAME history, projected into display segments (text runs and finished tool
+       * calls, diffs included) — so a reload/reconnect/resume replay shows tool rows instead of bare
+       * text. Optional so an older host that has not grown `getMessagesDisplay()` yet still sends a
+       * valid frame; a client without this field falls back to `messages`-only (text bubbles), the
+       * same as before this existed.
+       */
+      display?: ReturnType<ISessionConversationRead['getMessagesDisplay']>;
+      /**
+       * #3289 §3: this connection's own server-assigned driver id, carried on the first frame every
+       * connection already gets — so a client can tell its OWN turns from a co-driver's instead of
+       * treating everything but the literal `'owner'` id as someone else (REMOTE-014 E5 display-only).
+       */
+      driverId?: TDriverId;
+    }
+  // #3189: one page of the full history. `entries` start at `startIndex` of the `total` the session
+  // holds now, and stop before a page grows past a bounded size (a single larger entry is sent alone).
+  | { type: 'history'; startIndex: number; total: number; entries: IWireHistoryEntry[] }
+  // Sent in reply to `get-context`, and pushed whenever the session's context window changes.
+  | { type: 'context'; state: ReturnType<ISessionConversationRead['getContextState']> }
+  // #3189: the full history gained entries that no streamed frame carries (a compaction, a skill
+  // activation, a memory event). A client that shows the full history re-reads it with `get-history`.
+  | {
+      type: 'history_changed';
+      /** A completed compaction, for clients that do not render the full system history. */
+      compact?: {
+        trigger: ICompactEvent['trigger'];
+        beforeUsedPercentage: number;
+        afterUsedPercentage: number;
+      };
+    }
+  // #3189: where the turn now starting came from (the user, a wake-up, a peer, an external event).
+  | { type: 'turn_source'; source: TTurnSource }
+  | { type: 'commands'; commands: ICommandListEntry[]; skills: ICommandSkillListEntry[] }
+  // Sent in reply to `get-status`, and pushed whenever the session's status changes.
+  | { type: 'session_status'; status: ISessionStatusSnapshot }
+  // #3282 §2: reply to `list-models`, echoing its `requestId`. `groups` is current-profile first;
+  // `currentProfile` is absent only when no provider profile is configured at all.
+  | {
+      type: 'model_list';
+      requestId: string;
+      groups: readonly IModelListGroup[];
+      currentProfile?: string;
+      currentModel: string;
+    }
+  // #3282 §4: reply to `get-agent-definitions`, echoing its `requestId`. `current` is always one of
+  // `agents`' names (the fallback default when nothing was ever selected).
+  | {
+      type: 'agent_definitions';
+      requestId: string;
+      agents: readonly IWireAgentDefinitionSummary[];
+      current: string;
+    }
+  | { type: 'sessions'; requestId: string; listing: ISessionListing }
+  | {
+      type: 'sessions_error';
+      requestId: string;
+      code: 'not_available' | 'list_failed';
+      message: string;
+    }
+  // This client's session is now another one; it re-reads what it shows. A host that binds each
+  // client to its own session sends it only to the client that moved.
+  | { type: 'session_switched'; event: ISessionSwitchedEvent }
+  // #3189: a new-session or switch-session was refused; `code` says why without parsing `message`.
+  | {
+      type: 'session_change_failed';
+      code: TSessionChangeRefusalCode;
+      message: string;
+      requestId?: string;
+    }
+  // #3289 §1: a `rename-session` succeeded (current session or not); the client refreshes its listing.
+  | { type: 'session_renamed_in_list'; requestId: string; sessionId: string; name: string }
+  | { type: 'session_rename_failed'; requestId: string; message: string }
+  // #3289 §1: a `delete-session` succeeded; the client refreshes its listing and, if it was showing
+  // the deleted session, re-reads what it now shows (the host has already switched it away).
+  | { type: 'session_deleted'; requestId: string; sessionId: string }
+  | {
+      type: 'session_delete_failed';
+      requestId: string;
+      code: TSessionDeleteRefusalCode;
+      message: string;
+    }
+  // SELFHOST-004 (P5, TC-08): carry the assembled trace/cost read-model (per-op span timeline +
+  // cost-by-source) across the sidecar boundary — no existing variant carries per-op `durationMs` or
+  // per-source `costUsd`. The GUI renders it renderer-side.
+  | { type: 'usage_report'; report: IUsageBySourceReport }
+  | { type: 'personal_usage_report'; requestId: string; report: IPersonalUsageReport }
+  | {
+      type: 'personal_usage_report_error';
+      requestId: string;
+      code: 'not_available' | 'report_failed';
+      message: string;
+    }
+  | {
+      type: 'stored_session_usage_report';
+      requestId: string;
+      sessionId: string;
+      report: IUsageBySourceReport;
+    }
+  | {
+      type: 'stored_session_usage_report_error';
+      requestId: string;
+      sessionId: string;
+      code: 'not_available' | 'report_failed';
+      message: string;
+    }
+  | { type: 'executing'; executing: boolean }
+  // The next queued prompt and how many wait. Sent in reply to `get-pending`, and to a `submit` once
+  // the host has taken the prompt (queued it behind a running turn, or run it).
+  | { type: 'pending'; pending: string | null; pendingCount?: number }
+  | { type: 'execution_workspace_event'; snapshot: IExecutionWorkspaceSnapshot }
+  | { type: 'execution_detail'; requestId: string; page: IExecutionDetailPage }
+  | { type: 'execution_detail_error'; requestId: string; message: string }
+  | { type: 'waiting_loop_stop'; requestId: string; outcome: TWaitingLoopStopOutcome }
+  // #3282 §4c: the Project panel's reads. Each result crosses the wire UNCHANGED as the session
+  // method's own return value (same convention as `waiting_loop_stop`'s `outcome` above) — the
+  // `kind` discriminant carries the non-repository / outside-workspace / unavailable / failed cases,
+  // so there is no separate `_error` sibling to keep in sync with these.
+  | { type: 'project_status'; requestId: string; result: TProjectStatusRead }
+  | { type: 'project_diff'; requestId: string; result: TProjectDiffRead }
+  | { type: 'project_memory'; requestId: string; result: TProjectMemoryRead }
+  // The outcome of a `call-app-tool`, correlated by `requestId`: the tool's own result, as the
+  // session returned it.
+  | {
+      type: 'app_tool_result';
+      requestId: string;
+      success: boolean;
+      data?: IToolExecutionResult['result'];
+      parts?: TUniversalMessagePart[];
+      error?: string;
+    }
+  // The answer to a `read-app-view`: the whole document, to the surface that asked and no other.
+  | { type: 'app_view'; requestId: string; view: IToolAppView }
+  | { type: 'background_task_event'; event: TBackgroundTaskEvent }
+  | { type: 'background_job_group_event'; event: TBackgroundJobGroupEvent }
+  | { type: 'plan_event'; event: IPlanApprovalEvent }
+  | { type: 'context_file_refreshed'; event: IContextFileRefreshedEvent }
+  | { type: 'branch_event'; event: IBranchEvent }
+  | { type: 'background_tasks'; tasks: IBackgroundTaskState[] }
+  | { type: 'background_task'; taskId: string; task: IBackgroundTaskState | null }
+  | { type: 'background_job_groups'; groups: IBackgroundJobGroupState[] }
+  | { type: 'background_job_group'; groupId: string; group: IBackgroundJobGroupState | null }
+  | { type: 'background_task_log'; taskId: string; page: IBackgroundTaskLogPage }
+  // REMOTE-007: forward the session's transport-neutral prompt events so a remote surface can render +
+  // answer the SAME prompt (permission/ask). `prompt_resolved` dismisses it when another surface won.
+  | { type: 'permission_request'; event: IPermissionRequestEvent }
+  | { type: 'ask_request'; event: IAskRequestEvent }
+  | { type: 'prompt_resolved'; event: IPromptResolvedEvent }
+  // CMD-004 Phase 2: forward command-issued UI intents (same pattern as `ask_request`). The event is
+  // requester-routed — a client renders it only when `event.requesterDriverId` is its own driver id;
+  // an unsupported intent yields an explicit "not available on this surface" notice, never a silent drop.
+  | { type: 'ui_intent'; event: IUiIntentEvent }
+  // CMD-004 Phase 2 Stage E: BROADCAST session events — every attached surface receives them
+  // (co-driving titles/transcripts follow the host-executed rename/clear; never requester-filtered).
+  | { type: 'session_renamed'; event: ISessionRenamedEvent }
+  | { type: 'history_cleared' }
+  | {
+      type: 'background_task_control_result';
+      action: TBackgroundControlAction;
+      taskId: string;
+      success: boolean;
+      message?: string;
+    }
+  // `requestId` names the `command` whose failure this reports; a refusal of anything else has none.
+  | { type: 'protocol_error'; message: string; requestId?: string }
+  // REMOTE-013 E4: sent instead of a replay when the client's `lastSeq` predates the host's retained buffer
+  // (overrun) — the client must do a full `get-messages` refresh rather than accept a silent gap.
+  | { type: 'resume_gap' }
+  // #3282 §4a: the Settings screen's snapshot, in reply to `get-settings` or `update-settings`. The
+  // same type answers both, the way `session_status` answers `get-status` and a status change alike.
+  | { type: 'settings'; requestId: string; settings: ISettingsSnapshot }
+  | {
+      type: 'settings_error';
+      requestId: string;
+      code: 'not_available' | 'invalid' | 'refused' | 'update_failed';
+      message: string;
+    };
+
+/**
+ * REMOTE-013 E4: a server message stamped with its monotonic session sequence number (added by the
+ * {@link SessionResumeBridge} on the reconnectable WebRTC path). Intersecting over the union distributes the
+ * `seq` field onto every variant. The WS localhost path never stamps it (a `type`-dispatching client ignores
+ * an absent/extra `seq`).
+ */
+export type TSeqServerMessage = TServerMessage & { seq: number };