@silo-code/sdk 0.46.0 → 0.47.0

package/src/agents-service.ts

@@ -1,5 +1,5 @@
 import type { Disposable } from "./types";
-import type { TerminalKind } from "./domain-types";
+import type { TabActivityBinder, TabIconBinder } from "./tab-adornment";
 
 // `ctx.agents` — host-computed coding-agent activity and resume-identity
 // observability. See RFC 0018 (docs/proposals/0018-ctx-agents-surface.md).
@@ -29,10 +29,31 @@ import type { TerminalKind } from "./domain-types";
 export type AgentActivity = "none" | "working" | "idle" | "error" | "dead";
 
 /**
- * Live agent-activity and resume-identity state for one terminal, computed
- * once by the host and shared across every subscriber — never recomputed
- * per-extension. Returned by {@link AgentsService.getState} and
- * {@link AgentsService.getByTerminalId}; delivered to
+ * Which kind of **Agent Session** an {@link AgentInfo} describes (RFC 0038):
+ *
+ * - `"terminal"` — the agent runs in a PTY and draws its own TUI; Silo
+ *   *infers* what it is doing from OSC/output signals, and its identity comes
+ *   from detection (ADR 0028).
+ * - `"chat"` — the agent is an Agent Client Protocol child speaking structured
+ *   JSON-RPC over piped stdio; it *reports* what it is doing and declares its
+ *   identity at `initialize`, and Silo renders the conversation.
+ *
+ * `ctx.agents` reports **one shape regardless of kind** — the promise is
+ * observation parity, not capability parity. Most consumers never need to
+ * branch on this; use {@link AgentsService.reveal} to bring a session into
+ * view without knowing which kind it is.
+ *
+ * @category Core Types
+ * @public
+ * @beta
+ */
+export type AgentSessionKind = "terminal" | "chat";
+
+/**
+ * Live agent-activity and resume-identity state for one **Agent Session**
+ * (RFC 0038), computed once by the host and shared across every subscriber —
+ * never recomputed per-extension. Returned by {@link AgentsService.getState}
+ * and {@link AgentsService.getByTerminalId}; delivered to
  * {@link AgentsService.subscribe} listeners on every change.
  *
  * @category Consumer Services
@@ -40,20 +61,62 @@ export type AgentActivity = "none" | "working" | "idle" | "error" | "dead";
  * @beta
  */
 export interface AgentInfo {
-  /** The terminal record id this state belongs to. */
-  readonly terminalId: string;
-  /** The workspace this terminal belongs to. */
+  /**
+   * Stable id for this Agent Session — the key {@link AgentsService.reveal},
+   * {@link AgentsService.resume}, and {@link AgentsService.acknowledge} take.
+   * For a Terminal session this is the terminal record id; for a Chat session
+   * it is the session handle's id. Prefer this over
+   * {@link AgentInfo.terminalId} for anything that should not care which kind
+   * of session it is.
+   */
+  readonly id: string;
+  /**
+   * The terminal record id backing this session, when there is one — the same
+   * id {@link AgentsService.getByTerminalId} and `ctx.terminals` take.
+   * Present for every `kind: "terminal"` session; absent for a `kind: "chat"`
+   * session, which has no PTY. A consumer that needs a terminal-tab id should
+   * check {@link AgentInfo.kind} first, or use {@link AgentsService.reveal}.
+   */
+  readonly terminalId?: string;
+  /** The workspace this session belongs to. */
   readonly workspaceId: string;
   /**
-   * The terminal's kind at registration time.
+   * The session's display label — host-computed, the same string for either
+   * kind, and the one a consumer should render. A status row, a navigator row
+   * and the session's own dock tab all showing this field is what keeps them
+   * from drifting.
+   *
+   * It is a three-step fallback, and the two kinds are exact parallels:
    *
-   * @deprecated Always `"shell"` after RFC 0033 — the deprecated `"claude"` /
-   * `"pi"` kinds are normalized away at load and nothing creates them, so a
-   * consumer branching on this is reading a constant. Use
-   * {@link AgentInfo.agentId} for which agent is running, and
-   * {@link AgentInfo.isAgent} for whether one is.
+   * | step               | Terminal                            | Chat                              |
+   * | ------------------ | ----------------------------------- | --------------------------------- |
+   * | the agent's words  | the OSC window title                | `session_info_update.title`       |
+   * | the user's name    | `TerminalRecord.customName`   | *(no rename gesture yet)*         |
+   * | fallback           | the terminal's derived name         | declared agent name → profile label |
+   *
+   * The user's name wins where they set one; otherwise the agent's own words
+   * win, with agent **status markers stripped** (Claude's spinner, Cursor's
+   * trailing ` - Working …`) — the status is already structured state on this
+   * same record, so repeating it in the label is noise.
+   *
+   * Not every agent volunteers a title, and whether a given one does is its
+   * own choice — and its adapter's, version to version. A session that never
+   * gets one sits on the fallback, exactly as a terminal tab does for a CLI
+   * that writes no OSC title. Silo does not paper over that by inventing a
+   * summary from the first prompt.
    */
-  readonly kind: TerminalKind;
+  readonly title: string;
+  /**
+   * Which kind of Agent Session this is — `"terminal"` or `"chat"`. See
+   * {@link AgentSessionKind}. `ctx.agents` reports the same fields for both;
+   * this exists for the rare consumer that genuinely needs a PTY tab id or a
+   * transcript panel.
+   *
+   * (This field was the vestigial `TerminalKind` before RFC 0038 — always
+   * `"shell"` and read by nothing — and carries the session discriminator
+   * now.)
+   */
+  readonly kind: AgentSessionKind;
   /**
    * Whether this terminal currently hosts an agent — true if it was created
    * as one, or an agent-specific signal was observed in it (e.g. typing
@@ -102,6 +165,27 @@ export interface AgentInfo {
    * both live and at `activity === "dead"`.
    */
   readonly resumeCommand?: string;
+  /**
+   * Whether this session can be resumed **through Silo** — i.e. whether
+   * {@link AgentsService.resume} will do something for this id.
+   *
+   * - Terminal session: `true` once an exact session id was resolved (a
+   *   Settings → Agents hook, or an agent's native session file), which is
+   *   also when {@link AgentInfo.resumeCommand} becomes exact rather than an
+   *   honest note. `resume()` is still a no-op for a Terminal session in this
+   *   release — the user runs `resumeCommand` themselves; the flag is the
+   *   forward-looking capability signal RFC 0038 replaces the shell-string
+   *   `resumeCommand` contract with.
+   * - Chat session: `true` when the agent advertises `session/load`, so a
+   *   fresh process can reload the transcript after the old one died.
+   *
+   * - Chat session: `true` when the agent advertises **either**
+   *   `sessionCapabilities.resume` or `agentCapabilities.loadSession` (RFC
+   *   0042) — the two are distinct capabilities (see {@link ChatResumeState})
+   *   but either is enough for {@link AgentsService.resume} to bring the
+   *   conversation back.
+   */
+  readonly canResume: boolean;
   /**
    * Human-readable agent name, e.g. `"Claude Code"` or `"Codex CLI"`. Tells
    * you *which* agent CLI is running in this terminal, independent of
@@ -119,8 +203,48 @@ export interface AgentInfo {
    * the same moment and lifecycle as `agentName`.
    */
   readonly agentId?: string;
+  /**
+   * For a `kind: "chat"` session, where it stands in **Chat session
+   * resurrection** (RFC 0042) — absent for a `kind: "terminal"` session, which
+   * has no such lifecycle. See {@link ChatResumeState}.
+   */
+  readonly chatResumeState?: ChatResumeState;
 }
 
+/**
+ * Where a **Chat** Agent Session stands in Chat session resurrection (RFC
+ * 0042) — bringing its transcript, and the ability to keep talking, back after
+ * its process died with the app.
+ *
+ * - `"dormant"` — known only from persistence: the conversation exists and its
+ *   panel is recorded, but nothing has connected to it this run and no agent
+ *   process is alive. This is what a Chat session in a workspace you have not
+ *   visited since launching looks like — listing it is the point, and opening
+ *   it is what starts the reconnect. Its `activity` is always `"idle"`.
+ * - `"live"` — an ordinary, uninterrupted connection (a plain `session/new`
+ *   this run; never went through the resume machinery).
+ * - `"resuming"` — a restore is in flight: `session/resume` or `session/load`
+ *   is being probed and called.
+ * - `"resumed"` — reconnected: `session/resume` (no replay, the transcript
+ *   comes from the **transcript journal**) or `session/load` (replay,
+ *   reconciled against the journal) succeeded.
+ * - `"journal-only"` — the agent could do neither; the transcript is the
+ *   journal alone and the session cannot be prompted in place — the panel's
+ *   own "Continue in a new session" action is the way forward.
+ * - `"unavailable"` — no session id and no journal; nothing to show.
+ *
+ * @category Consumer Services
+ * @public
+ * @beta
+ */
+export type ChatResumeState =
+  | "dormant"
+  | "live"
+  | "resuming"
+  | "resumed"
+  | "journal-only"
+  | "unavailable";
+
 /**
  * A Catalog Agent's brand mark — SVG path data plus the two theme-dependent
  * hexes. Consumed by {@link AgentIconGlyph}; a single hex cannot have enough
@@ -201,6 +325,22 @@ export interface AgentProfileSummary {
    * `"agent-takes-none"` after the user has already typed one.
    */
   readonly acceptsPrompt: boolean;
+  /**
+   * Which **interface** this profile starts the agent through — the profile's
+   * `launch` arm, expressed in the same {@link AgentSessionKind} vocabulary
+   * `AgentInfo.kind` uses (RFC 0038):
+   *
+   * - `"terminal"` — {@link AgentProfilesService.launch} runs it in a PTY and
+   *   the agent draws its own TUI.
+   * - `"chat"` — {@link AgentSessionsService.connect} speaks the Agent Client
+   *   Protocol to it and *you* render the conversation.
+   *
+   * The two are driven through different services, so a picker must filter on
+   * this rather than offer every profile to both: `launch()`ing a Chat profile
+   * and `connect()`ing a Terminal profile both fail, and the user should never
+   * be offered a profile that cannot work in the surface they are looking at.
+   */
+  readonly interface: AgentSessionKind;
 }
 
 /**
@@ -353,6 +493,844 @@ export interface AgentProfilesService {
   launch(options?: LaunchAgentProfileOptions): LaunchAgentProfileResult;
 }
 
+/**
+ * One block of an outgoing prompt turn for a **Chat session**
+ * ({@link AgentSessionHandle.prompt}). Structured content, never a shell
+ * string — the entire quoting/escaping risk surface of a Terminal session's
+ * opening prompt (RFC 0033 phase 3) does not exist here.
+ *
+ * - `"text"` — a run of plain text. `$HOME`, backticks, quotes and newlines
+ *   are all literal.
+ * - `"resource_link"` — a pointer to a file (or other URI) the agent may read
+ *   if it chooses. `uri` is typically a `file://` path inside the workspace.
+ *   Always accepted — this is a pointer, not embedded content, so it needs no
+ *   {@link AgentPromptCapabilities} gate.
+ * - `"resource"` — the file's own text **inlined** into the prompt, rather
+ *   than a pointer the agent may or may not follow. Only send this to a
+ *   session whose {@link AgentSessionHandle.promptCapabilities} has
+ *   `embeddedContext: true`.
+ *
+ * Images are deferred — no probe has yet checked what each agent actually
+ * accepts for one, and this union grows behind that once one has (RFC 0040
+ * open question 3).
+ *
+ * @category Consumer Services
+ * @public
+ * @beta
+ */
+export type AgentPromptBlock =
+  | { readonly type: "text"; readonly text: string }
+  | {
+      readonly type: "resource_link";
+      readonly uri: string;
+      /** A short display name for the link; defaults to the last path segment. */
+      readonly name?: string;
+    }
+  | {
+      readonly type: "resource";
+      /** The resource's own URI, e.g. a `file://` path. */
+      readonly uri: string;
+      readonly mimeType?: string;
+      /** The embedded text content. Binary (blob) resources are not modelled —
+       *  nothing in Silo has needed to embed one yet. */
+      readonly text: string;
+    };
+
+/**
+ * Why a prompt turn ended, straight from the agent's Agent Client Protocol
+ * stop reason. `"end_turn"` is the normal completion; `"max_tokens"` /
+ * `"max_turn_requests"` are budget cutoffs; `"refusal"` means the agent
+ * declined the request; `"cancelled"` follows {@link AgentSessionHandle.cancel}.
+ *
+ * @category Consumer Services
+ * @public
+ * @beta
+ */
+export type AgentStopReason =
+  | "end_turn"
+  | "max_tokens"
+  | "max_turn_requests"
+  | "refusal"
+  | "cancelled";
+
+/**
+ * What {@link AgentSessionHandle.prompt} resolves to. A prompt that cannot be
+ * delivered — the connection dropped, the agent errored mid-turn — **rejects**
+ * instead, with the agent's own message where there is one.
+ *
+ * @category Consumer Services
+ * @public
+ * @beta
+ */
+export interface AgentPromptResult {
+  readonly stopReason: AgentStopReason;
+}
+
+/**
+ * One piece of agent-authored content — the Agent Client Protocol content
+ * block, which appears both in a streamed message chunk
+ * ({@link AgentSessionUpdate.content}) and inside a tool call's output
+ * ({@link AgentToolCallContent.content}).
+ *
+ * **`type` is deliberately a `string`, not a union.** The protocol names
+ * `"text"`, `"image"`, `"audio"`, `"resource_link"` and `"resource"`, and a
+ * vendor may add its own; the same tolerance rule the rest of this surface
+ * follows applies — render the types you know and **name, rather than drop**,
+ * one you do not, so a transcript never silently loses a block.
+ *
+ * Every field but `type` is optional because which ones arrive depends on the
+ * type _and_ the agent: only `"text"` blocks were seen from Cursor
+ * (2026.09.02) and `claude-agent-acp` (0.75.1) in the 2026-09-08 probe, so
+ * treat the rest as modelled-but-unverified and check before you read.
+ *
+ * @category Consumer Services
+ * @public
+ * @beta
+ */
+export interface AgentContentBlock {
+  /** The protocol's block type — `"text"`, `"image"`, `"audio"`,
+   *  `"resource_link"`, `"resource"`, or a vendor's own. */
+  readonly type: string;
+  /** The text, for a `"text"` block. */
+  readonly text?: string;
+  /** MIME type, for an `"image"` / `"audio"` / `"resource_link"` block. */
+  readonly mimeType?: string;
+  /** Where the content lives, for a `"resource_link"` (or an image given by
+   *  reference rather than inline). Typically a `file://` URI. */
+  readonly uri?: string;
+  /** A short display name, for a `"resource_link"`. */
+  readonly name?: string;
+}
+
+/**
+ * One block of a tool call's content — what the agent wants shown _inside_ the
+ * tool row. The protocol wraps each in a `{ type }` envelope, and the three it
+ * names are `"content"` (an {@link AgentContentBlock}), `"diff"` (a file edit)
+ * and `"terminal"` (output streaming into an agent-side terminal).
+ *
+ * `type` is a `string` for the usual reason: tolerate what you do not know.
+ * The remaining fields are the union's arms flattened, so check `type` before
+ * reading them.
+ *
+ * @category Consumer Services
+ * @public
+ * @beta
+ */
+export interface AgentToolCallContent {
+  /** `"content"`, `"diff"`, `"terminal"`, or a vendor's own. */
+  readonly type: string;
+  /** The content block, when `type` is `"content"`. */
+  readonly content?: AgentContentBlock;
+  /** The file being edited, when `type` is `"diff"`. */
+  readonly path?: string;
+  /** The file's contents before the edit, when `type` is `"diff"`. Absent for
+   *  a file the agent is creating — `claude-agent-acp` 0.75.1 sends `null`
+   *  there, which arrives here as `undefined`. */
+  readonly oldText?: string;
+  /** The file's contents after the edit, when `type` is `"diff"`. */
+  readonly newText?: string;
+  /** The agent-side terminal this call is streaming into, when `type` is
+   *  `"terminal"`. Silo declines `terminal/*` today, so a consumer can name the
+   *  block but cannot read its output. */
+  readonly terminalId?: string;
+}
+
+/**
+ * A file (and optionally a line) a tool call touches — the protocol's
+ * `locations`, which is how an agent says "this call is about _this_ file"
+ * independently of its title. A Chat UI can turn these into "open the file"
+ * affordances.
+ *
+ * Both agents probed on 2026-09-08 send it; only `claude-agent-acp` 0.75.1 was
+ * seen sending `line`.
+ *
+ * @category Consumer Services
+ * @public
+ * @beta
+ */
+export interface AgentToolCallLocation {
+  /** Absolute path to the file. */
+  readonly path: string;
+  /** 1-based line the call is focused on, when the agent named one. */
+  readonly line?: number;
+}
+
+/**
+ * One tool call an agent is making, carried by a `tool_call` (the call opening)
+ * or a `tool_call_update` (a change to one already open) — see
+ * {@link AgentSessionUpdate.toolCall}.
+ *
+ * **Both kinds map to this same type, so only {@link toolCallId} is
+ * guaranteed.** A `tool_call` typically carries `title`, `kind` and `status`;
+ * a `tool_call_update` carries **only the fields that changed** (in the
+ * 2026-09-08 probe, most updates were `{ toolCallId, status }` alone). So a
+ * consumer keys rows by {@link toolCallId} and patches the fields that are
+ * present — never overwrite a title with `undefined`.
+ *
+ * A `tool_call_update` for a call whose opening `tool_call` never arrived is a
+ * real shape; render it rather than dropping it.
+ *
+ * @category Consumer Services
+ * @public
+ * @beta
+ */
+export interface AgentToolCall {
+  /** The call's id — stable across its `tool_call` and every
+   *  `tool_call_update`, and the same id an
+   *  {@link AgentPermissionRequest.toolCallId} refers to. */
+  readonly toolCallId: string;
+  /** Human-readable label, e.g. `"Read notes.md"`. Present on the opening
+   *  `tool_call`, and on an update only when it changed — agents do relabel a
+   *  call as it progresses. */
+  readonly title?: string;
+  /** The protocol's coarse category: `"read"`, `"edit"`, `"delete"`,
+   *  `"move"`, `"search"`, `"execute"`, `"think"`, `"fetch"`,
+   *  `"switch_mode"`, `"other"`, or a vendor's own. Tolerate unknown values;
+   *  do not switch exhaustively. */
+  readonly kind?: string;
+  /** `"pending"`, `"in_progress"`, `"completed"`, `"failed"`, or a vendor's
+   *  own. Not every agent walks the whole ladder — `claude-agent-acp` 0.75.1
+   *  went `pending` → `completed` with no `in_progress`. */
+  readonly status?: string;
+  /** What to show inside the row. Absent on an update that changed something
+   *  else — treat that as "unchanged", not "now empty". */
+  readonly content?: readonly AgentToolCallContent[];
+  /** The files this call touches. */
+  readonly locations?: readonly AgentToolCallLocation[];
+  /** The arguments the agent passed to its own tool, exactly as it sent them.
+   *  **Vendor-shaped by definition** — the protocol places no schema on it, so
+   *  it is typed `unknown`: narrow it yourself, and expect a different shape
+   *  from each agent. */
+  readonly rawInput?: unknown;
+  /** The tool's own result, same caveat as {@link rawInput}. */
+  readonly rawOutput?: unknown;
+}
+
+/**
+ * One row of the agent's plan — the protocol's `plan` update entry.
+ *
+ * @category Consumer Services
+ * @public
+ * @beta
+ */
+export interface AgentPlanEntry {
+  /** What the step is, in the agent's words. */
+  readonly content: string;
+  /** `"pending"`, `"in_progress"`, `"completed"`, or a vendor's own. */
+  readonly status?: string;
+  /** `"high"`, `"medium"`, `"low"`, or a vendor's own, when the agent ranked
+   *  the step. */
+  readonly priority?: string;
+}
+
+/**
+ * One `session/update` notification from a **Chat session**, lightly
+ * normalized. The Agent Client Protocol streams a turn as a sequence of these:
+ * assistant text, agent "thinking", tool-call rows, plan updates, and more.
+ *
+ * **A consumer must tolerate `kind` values it does not recognize** — agents
+ * emit different subsets and vendors add their own (recon §3). Switch on the
+ * kinds you render and ignore the rest; never treat an unknown kind as an
+ * error.
+ *
+ * Everything a Chat UI must draw to render a transcript is a modelled field:
+ * {@link text} / {@link content} for the message kinds, {@link toolCall} for
+ * `tool_call` and `tool_call_update`, {@link plan} for `plan`. {@link raw} is
+ * for what is deliberately left out — see its own note.
+ *
+ * @category Consumer Services
+ * @public
+ * @beta
+ */
+export interface AgentSessionUpdate {
+  /**
+   * The Agent Client Protocol `sessionUpdate` discriminator, e.g.
+   * `"agent_message_chunk"`, `"agent_thought_chunk"`, `"tool_call"`,
+   * `"tool_call_update"`, `"plan"`, `"available_commands_update"`.
+   */
+  readonly kind: string;
+  /**
+   * Text payload for the streaming-text kinds (`agent_message_chunk`,
+   * `agent_thought_chunk`, `user_message_chunk`); `undefined` for every other
+   * kind — and also for a text kind whose block is not text, in which case
+   * read {@link content}.
+   */
+  readonly text?: string;
+  /**
+   * The whole content block a streaming-text kind carried, of which
+   * {@link text} is the `"text"` shorthand. Read it when you want to render an
+   * image or a resource link an agent sent as a message rather than dropping
+   * it. `undefined` for every non-message kind.
+   */
+  readonly content?: AgentContentBlock;
+  /**
+   * Stable id for the run of chunks this update belongs to. Consecutive
+   * same-kind chunks share one — **synthesized by Silo when the agent omits
+   * `messageId`**, which real agents do (recon Finding 7), so a consumer can
+   * group a streamed sentence into one bubble without minting ids itself.
+   */
+  readonly messageId?: string;
+  /**
+   * The tool call, for `kind` `"tool_call"` and `"tool_call_update"`;
+   * `undefined` otherwise. Key rows by {@link AgentToolCall.toolCallId} and
+   * patch in place — an update carries only what changed.
+   */
+  readonly toolCall?: AgentToolCall;
+  /**
+   * The agent's plan **in full**, for `kind` `"plan"`; `undefined` otherwise.
+   * The agent reissues the entire list every time, so replace the plan you are
+   * showing rather than appending to it. May be empty.
+   */
+  readonly plan?: readonly AgentPlanEntry[];
+  /**
+   * The raw Agent Client Protocol `update` object — the **escape hatch**, for
+   * the kinds and fields this surface does not model.
+   *
+   * What is deliberately not modelled, and why: `available_commands_update`
+   * (an agent's slash commands — a menu, not a transcript row),
+   * `usage_update` (token counts, which no agent reports the same way),
+   * `current_mode_update` (already surfaced as
+   * {@link AgentSessionConfigOption.currentValue}), `session_info_update`
+   * (already surfaced as {@link AgentInfo.title}), and vendor extensions such
+   * as `claude-agent-acp`'s `_meta`. None is needed to draw a transcript; all
+   * are readable here.
+   *
+   * **`raw` tracks the protocol, not this SDK's semver.** A field inside it can
+   * change shape, or vanish, when an agent or its adapter changes — no SDK
+   * major required, and that has already happened three times inside one sprint.
+   * Read it defensively, and if you find yourself needing it for something
+   * every Chat UI must render, that is a gap in this surface worth reporting.
+   * Treat it as read-only.
+   */
+  readonly raw: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * One choice offered by an {@link AgentPermissionRequest} — pass its
+ * {@link AgentPermissionOption.optionId} to {@link AgentPermissionRequest.respond}.
+ *
+ * @category Consumer Services
+ * @public
+ * @beta
+ */
+export interface AgentPermissionOption {
+  readonly optionId: string;
+  /** Label to show on the button, e.g. `"Allow"`, `"Allow for this session"`,
+   *  `"Reject"`. */
+  readonly name: string;
+  /** The protocol's coarse category for the option, e.g. `"allow_once"`,
+   *  `"allow_always"`, `"reject_once"` — for styling a set of buttons
+   *  consistently. Tolerate unknown values. */
+  readonly kind: string;
+}
+
+/**
+ * The agent is **blocked on the user**: it wants permission to run a tool and
+ * the turn will not proceed until {@link AgentPermissionRequest.respond} is
+ * called. Delivered to {@link AgentSessionHandle.onPermission}.
+ *
+ * **This is not a safety boundary.** An agent routes a request through here
+ * only if it chooses to; nothing stops it touching the filesystem directly
+ * (recon Finding 1). Do not present this as Silo gating the agent's actions.
+ *
+ * If no `onPermission` listener is registered, Silo answers `cancelled` on the
+ * extension's behalf so the agent is never left hanging.
+ *
+ * @category Consumer Services
+ * @public
+ * @beta
+ */
+export interface AgentPermissionRequest {
+  /** The tool call this permission is for — the same id as the matching
+   *  {@link AgentToolCall.toolCallId} in the update stream. */
+  readonly toolCallId: string;
+  /** A human-readable description of what the agent wants to do. */
+  readonly title: string;
+  /** The choices to present. Always at least one; order is the agent's. */
+  readonly options: readonly AgentPermissionOption[];
+  /**
+   * The call the agent is asking to make, when it sent one — the protocol's
+   * `toolCall` params, the same shape the update stream carries. It is how a
+   * Chat UI can show the diff **before** the user answers rather than only the
+   * title; `claude-agent-acp` 0.75.1 sends a full one including `content`.
+   */
+  readonly toolCall?: AgentToolCall;
+  /** The raw Agent Client Protocol `session/request_permission` params. */
+  readonly raw: Readonly<Record<string, unknown>>;
+  /**
+   * Answer the request with one of {@link AgentPermissionRequest.options}.
+   * Idempotent — the first call wins, later calls are ignored. Passing an
+   * `optionId` that is not in `options` answers `cancelled`.
+   */
+  respond(optionId: string): void;
+}
+
+/**
+ * One selectable value inside an {@link AgentSessionConfigOption}.
+ *
+ * @category Consumer Services
+ * @public
+ * @beta
+ */
+export interface AgentSessionConfigChoice {
+  /** The value to pass to {@link AgentSessionHandle.setConfigOption}. */
+  readonly value: string;
+  /** Label to show, e.g. `"Claude Sonnet"`, `"Plan"`. */
+  readonly name: string;
+  /** A longer explanation, when the agent gave one. */
+  readonly description?: string;
+}
+
+/**
+ * One session-level control the agent advertised at connect — the Agent Client
+ * Protocol `session/new` `configOptions` list (recon 2026-09-08). It is
+ * **self-describing and subsumes** the older `modes` / `models` fields: Cursor
+ * advertises a `"mode"` entry and a `"model"` entry, Claude a single `"mode"`
+ * entry (its permission mode), and a vendor may add its own.
+ *
+ * The write path is **generic too**:
+ * {@link AgentSessionHandle.setConfigOption} goes through the protocol's
+ * `session/set_config_option`, so a category Silo has never heard of still
+ * works — Claude's `"thought_level"` (Effort) has no typed method anywhere in
+ * the protocol and sets fine. Silo keeps `session/set_mode` /
+ * `session/set_model` only as a fallback for an agent that does not implement
+ * the generic setter.
+ *
+ * Render one control per entry and **skip an entry whose {@link type} you do
+ * not recognise** — the same tolerance rule {@link AgentSessionUpdate} follows
+ * for unknown `kind`s. Do not assume every advertised entry is settable: an
+ * adapter may list an id its own handler rejects, so treat a failed
+ * {@link AgentSessionHandle.setConfigOption} as "stop offering this one".
+ *
+ * @category Consumer Services
+ * @public
+ * @beta
+ */
+export interface AgentSessionConfigOption {
+  /** Stable id — pass it to {@link AgentSessionHandle.setConfigOption}. */
+  readonly id: string;
+  /** Label for the control, e.g. `"Mode"`, `"Model"`. */
+  readonly name: string;
+  /** A longer explanation, when the agent gave one. */
+  readonly description?: string;
+  /**
+   * The protocol category that decides how a write is delivered — `"mode"`,
+   * `"model"`, or a vendor's own. {@link AgentSessionHandle.setConfigOption}
+   * rejects a category with no verified writer.
+   */
+  readonly category: string;
+  /**
+   * The control shape. Only `"select"` is modelled today; treat any other
+   * value as "do not render".
+   */
+  readonly type: string;
+  /**
+   * The currently-selected {@link AgentSessionConfigChoice.value}. Kept
+   * current when the agent moves it itself (an ACP `current_mode_update`), so
+   * a bound control always reflects reality — subscribe with
+   * {@link AgentSessionHandle.onConfigOptionsChanged}.
+   */
+  readonly currentValue: string;
+  /** The choices, in the agent's order. */
+  readonly options: readonly AgentSessionConfigChoice[];
+}
+
+/**
+ * One command the agent advertises (Agent Client Protocol
+ * `available_commands_update`, RFC 0040). **Skills arrive in this list too**
+ * — the protocol has no separate skills concept, and the two agents probed
+ * mark them differently: pi prefixes the name (`skill:code-review`), Claude
+ * does not mark them at all outside a `(user)` / `(project)` suffix in
+ * {@link description}'s prose. Splitting them back out would mean
+ * vendor-sniffing a label neither agent is contractually bound to keep, so
+ * this surface deliberately does not try.
+ *
+ * @category Consumer Services
+ * @public
+ * @beta
+ */
+export interface AgentCommand {
+  /** What to send after `/` to invoke it — `prompt([{ type: "text", text:
+   *  "/" + name }])`. There is no separate invocation method. */
+  readonly name: string;
+  /** One-line summary for a palette row. */
+  readonly description?: string;
+  /**
+   * Present when the command takes a free-text argument; `hint` is the
+   * agent's own placeholder, when it gave one. Absent means the command takes
+   * none — normalised at the host boundary, since Claude sends `input: null`
+   * where pi omits the key entirely; this type only ever sees one spelling.
+   */
+  readonly input?: { readonly hint?: string };
+}
+
+/**
+ * What a Chat session accepts as prompt content, read once from `initialize`
+ * and fixed for the session's life (RFC 0040). A UI gates its attachment
+ * affordance on this rather than offering one that fails at prompt time.
+ *
+ * A field the agent's `initialize` response omitted defaults to `false`
+ * rather than being left `undefined` — both `codex-acp` and `claude-agent-acp`
+ * omit `audio` entirely (recon 2026-09-09), so treating an absent field as
+ * "not accepted" is the only reading that doesn't require every consumer to
+ * repeat the same `?? false`.
+ *
+ * @category Consumer Services
+ * @public
+ * @beta
+ */
+export interface AgentPromptCapabilities {
+  /** Image content blocks are accepted. Not yet a sendable
+   *  {@link AgentPromptBlock} — see its doc comment. */
+  readonly image: boolean;
+  /** Audio content blocks are accepted. */
+  readonly audio: boolean;
+  /**
+   * Embedded `"resource"` {@link AgentPromptBlock}s are accepted. A
+   * `"resource_link"` (a pointer the agent may read itself) is always
+   * allowed and is not gated on this.
+   */
+  readonly embeddedContext: boolean;
+}
+
+/**
+ * A live handle to one **Chat session** (RFC 0038) — an Agent Client Protocol
+ * child Silo spawned from a user-authored Chat profile, speaking structured
+ * JSON-RPC over piped stdio. Returned by {@link AgentSessionsService.connect}.
+ *
+ * The same session shows up in {@link AgentsService.getState} as an
+ * {@link AgentInfo} with `kind: "chat"` and this handle's {@link id} — so the
+ * Agents navigator, attention badges and status all work for it exactly as for
+ * a Terminal session, with no extra wiring.
+ *
+ * Drive one turn at a time: call {@link prompt}, await its
+ * {@link AgentPromptResult}, then prompt again.
+ *
+ * @category Consumer Services
+ * @public
+ * @beta
+ */
+export interface AgentSessionHandle {
+  /**
+   * This session's {@link AgentInfo.id} — the key {@link AgentsService.reveal},
+   * {@link AgentsService.resume} and {@link AgentsService.acknowledge} take.
+   * Stable across a {@link AgentsService.resume}.
+   */
+  readonly id: string;
+  /**
+   * The agent's own session id (`session/new`'s `sessionId`, or the fresh id
+   * `session/load` adopted) — what to pass back as
+   * {@link AgentSessionRestore.sessionId} on a future {@link
+   * AgentSessionsService.connect} to restore this conversation (RFC 0042).
+   * Distinct from {@link AgentSessionHandle.id}, which is namespaced for
+   * `ctx.agents` and does not change even when this does (an adopted id after
+   * `session/load`).
+   */
+  readonly sessionId: string;
+  /** The user's asserted catalog agent id for the profile, if any — the same
+   *  value that selects the profile's `+`-menu icon. */
+  readonly agentId?: string;
+  /** Display name for the agent: what it declared at connect (`initialize`),
+   *  falling back to the profile label when it declared none (recon Finding 4). */
+  readonly agentName: string;
+  /**
+   * Whether the agent advertises `session/resume` or `session/load`, i.e.
+   * whether {@link AgentsService.resume} can bring this conversation back
+   * after the process dies. Mirrors {@link AgentInfo.canResume}.
+   */
+  readonly canResume: boolean;
+  /**
+   * How this handle came to be connected (RFC 0042) — see
+   * {@link AgentSessionRestore}:
+   *
+   * - `"new"` — an ordinary `session/new` (no {@link
+   *   AgentSessionConnectOptions.resume} was given, or the persisted session
+   *   had gone stale and `connect()` fell through to a fresh one).
+   * - `"resumed"` — a persisted session reconnected, via `session/resume` or
+   *   `session/load`.
+   * - `"journal-only"` — the agent could do neither. There is no live
+   *   session: {@link prompt} rejects. Reconnect with
+   *   `resume: { sessionId, startFresh: true }` to continue in a new one,
+   *   preserving {@link journal} for continuity.
+   */
+  readonly resumeOutcome: "new" | "resumed" | "journal-only";
+  /**
+   * Prior turns to paint **before** subscribing to {@link onUpdate} — the
+   * **transcript journal** (RFC 0042), read from disk. Empty when
+   * {@link resumeOutcome} is `"new"` and nothing preceded this connection;
+   * populated for `"resumed"` (a `session/resume` reconnect, which itself
+   * replays nothing — this is the only record) and `"journal-only"`. Feed
+   * these through the same reducer as {@link onUpdate} before subscribing to
+   * it, e.g. `journal.reduce(applyUpdate, emptyTranscript)`.
+   */
+  readonly journal: readonly AgentSessionUpdate[];
+  /**
+   * Send a prompt turn and resolve when it ends. Content is structured blocks,
+   * never a shell string. Rejects if the turn cannot be completed (connection
+   * lost, agent error) — with the agent's message where it gave one. Also
+   * rejects immediately when {@link resumeOutcome} is `"journal-only"` — there
+   * is no live agent to prompt.
+   */
+  prompt(blocks: readonly AgentPromptBlock[]): Promise<AgentPromptResult>;
+  /**
+   * Ask the agent to stop the current turn (Agent Client Protocol
+   * `session/cancel`). The in-flight {@link prompt} promise then resolves with
+   * `stopReason: "cancelled"` rather than rejecting.
+   */
+  cancel(): void;
+  /**
+   * Subscribe to the turn's {@link AgentSessionUpdate} stream — streaming text,
+   * tool calls, plans. **Not confined to between {@link prompt} and its
+   * resolution**: some agents send one at connect, before any prompt at all
+   * (pi's own startup banner arrives as an `agent_message_chunk` — recon
+   * 2026-09-09), and a replay of prior turns can follow
+   * {@link AgentsService.resume}. Subscribe before assuming nothing will
+   * arrive yet. Returns a {@link Disposable}.
+   */
+  onUpdate(listener: (update: AgentSessionUpdate) => void): Disposable;
+  /**
+   * Subscribe to {@link AgentPermissionRequest}s. Returns a {@link Disposable}.
+   * With at least one listener registered, answering is your responsibility;
+   * with none, Silo answers `cancelled`.
+   */
+  onPermission(listener: (request: AgentPermissionRequest) => void): Disposable;
+  /**
+   * The session-level controls the agent advertised at connect — mode, model,
+   * and whatever else it offers, each a self-describing
+   * {@link AgentSessionConfigOption}. Empty when it advertised none.
+   *
+   * This is a **live snapshot**: {@link setConfigOption} and a mode the agent
+   * changes itself both update it in place. Subscribe with
+   * {@link onConfigOptionsChanged} and re-read.
+   */
+  readonly configOptions: readonly AgentSessionConfigOption[];
+  /**
+   * Change one advertised control. `id` names an entry in
+   * {@link configOptions}; `value` is one of that entry's
+   * {@link AgentSessionConfigChoice.value}s.
+   *
+   * Works for **any** category the agent advertises, including ones Silo has
+   * never heard of — the host writes through the protocol's generic
+   * `session/set_config_option`, falling back to the typed
+   * `session/set_mode` / `session/set_model` only for an agent that does not
+   * implement it.
+   *
+   * Rejects, with nothing written, on an unknown `id` or a `value` outside
+   * that entry's options — and with the agent's own message when the agent
+   * refuses (an adapter may advertise an entry its own handler does not know).
+   * A rejection is a signal to stop offering that control.
+   *
+   * Resolves once the agent has acknowledged the change. {@link configOptions}
+   * is then replaced from the agent's own updated list — setting one option can
+   * move another — and {@link onConfigOptionsChanged} fires just before it
+   * resolves.
+   */
+  setConfigOption(id: string, value: string): Promise<void>;
+  /**
+   * Fires whenever {@link configOptions} changes — a {@link setConfigOption}
+   * landing, or the agent moving a value on its own (an ACP
+   * `current_mode_update`). Re-read {@link configOptions} from the handle.
+   * Returns a {@link Disposable}.
+   */
+  onConfigOptionsChanged(listener: () => void): Disposable;
+  /**
+   * The commands the agent advertises, live — a `/` palette's data source
+   * (RFC 0040). **Empty until the agent's first
+   * `available_commands_update`**: both agents probed send one at connect,
+   * before any prompt, but nothing in the protocol requires it, and pi took
+   * ~12.5s to get there (behind its startup banner) — `connect()` does not
+   * wait for it. Subscribe with {@link onCommandsChanged} and re-read.
+   *
+   * There is no `runCommand()`. Invoke one the same way you'd send anything
+   * else: `prompt([{ type: "text", text: "/" + command.name }])`.
+   */
+  readonly commands: readonly AgentCommand[];
+  /** Fires whenever {@link commands} is replaced. Returns a
+   *  {@link Disposable}. */
+  onCommandsChanged(listener: () => void): Disposable;
+  /**
+   * What this session accepts as prompt content, read once from `initialize`
+   * and fixed for its life (RFC 0040) — unlike {@link commands}, this never
+   * changes, so there is no change event for it.
+   */
+  readonly promptCapabilities: AgentPromptCapabilities;
+  /**
+   * Tear the session down: kill the agent process and drop it from
+   * {@link AgentsService.getState}. Idempotent. The process is a piped child of
+   * Silo — it does **not** survive this, and closing the workspace or quitting
+   * the app reaps it the same way.
+   */
+  dispose(): void;
+}
+
+/**
+ * Options for {@link AgentSessionsService.connect}.
+ *
+ * @category Consumer Services
+ * @public
+ * @beta
+ */
+export interface AgentSessionConnectOptions {
+  /** Working directory for the agent. Defaults to the workspace folder. */
+  cwd?: string;
+  /** Which workspace the session belongs to (for
+   *  {@link AgentInfo.workspaceId} and `reveal`). Defaults to the active one. */
+  workspaceId?: string;
+  /**
+   * A last-known display title, shown immediately with {@link resume} — before
+   * the connection (`initialize` alone can take several seconds) or a
+   * `session/resume` / `session/load` round trip resolves. Without it, a
+   * restoring session's dock tab, workspace row, and Agents navigator entry
+   * fall back to the profile's plain label for however long reconnecting
+   * takes, even when the agent volunteered a real title before the app
+   * closed. It **outlives the handshake**: it is still the session's title
+   * once the connection is up, until the agent volunteers a real one of its
+   * own (a `session_info_update`). The agent's product name from `initialize`
+   * (`agentInfo.title`, e.g. "Claude Agent") does *not* supersede it — that is
+   * the fallback for a session that has never had a title, not a replacement
+   * for one this conversation already earned. Persist whatever
+   * {@link AgentInfo.title} last was and pass it back here on the next
+   * restore. Ignored without {@link resume} — a fresh session has no prior
+   * title to show early.
+   */
+  title?: string;
+  /**
+   * How to bring **your** UI for this session into view. Silo calls this from
+   * {@link AgentsService.reveal} — after activating the session's workspace —
+   * so a kind-agnostic caller (the Agents navigator, a notification, a
+   * command) can focus a Chat session's transcript without knowing that a
+   * transcript is what it is.
+   *
+   * Implement it with whatever "come to the front" means for your surface: a
+   * dock panel calls `api.setActive()` on its own `DockPanelApi`, a side
+   * panel reveals itself through `ctx.layout`. Called on the main thread,
+   * possibly more than once; keep it cheap and idempotent, and expect it after
+   * an `await` — capture the handle you need in a ref rather than closing over
+   * render-scoped state.
+   *
+   * Omit it and `reveal(id)` still activates the workspace, which is all Silo
+   * can honestly do for a session whose UI it does not own.
+   */
+  reveal?: () => void;
+  /**
+   * Reconnect a previously-persisted session instead of starting a fresh one
+   * — Chat session resurrection (RFC 0042). Pass the {@link
+   * AgentSessionHandle.sessionId} a prior `connect()` on this same profile
+   * returned (what a recorded panel keeps in its `DockPanelState`).
+   *
+   * `connect()` never rejects because the target has gone stale: it probes
+   * `session/resume` and `session/load` separately (`resume` wins when both
+   * are advertised), and falls through to a fresh `session/new` if neither
+   * works and there is no journal to fall back to. See {@link
+   * AgentSessionHandle.resumeOutcome} for which path was taken.
+   */
+  resume?: AgentSessionRestore;
+}
+
+/**
+ * A restore target for {@link AgentSessionConnectOptions.resume} — Chat
+ * session resurrection (RFC 0042).
+ *
+ * @category Consumer Services
+ * @public
+ * @beta
+ */
+export interface AgentSessionRestore {
+  /**
+   * The session id to reconnect — an earlier connection's {@link
+   * AgentSessionHandle.sessionId}.
+   */
+  sessionId: string;
+  /**
+   * Skip probing `session/resume` / `session/load` and start a fresh
+   * `session/new` directly, carrying the **transcript journal** kept under
+   * {@link sessionId} into the new session's — "Continue in a new session"
+   * from a `"journal-only"` {@link AgentSessionHandle.resumeOutcome}. The new
+   * handle's {@link AgentSessionHandle.sessionId} is whatever `session/new`
+   * mints, **not** this `sessionId` — persist that returned id for the next
+   * restore, exactly as after a plain `connect()`. Keeping the original,
+   * already-known-unresumable id instead would mean every future restore
+   * keeps retrying an id the agent will never resume, forever, even while the
+   * new conversation itself works fine turn after turn (found live,
+   * 2026-09-09).
+   */
+  startFresh?: boolean;
+}
+
+/**
+ * Connect to a **Chat session** and drive it — exposed as
+ * `ctx.agents.sessions` (RFC 0038 phase 2). The counterpart to
+ * {@link AgentProfilesService} for the `chat` launch arm: where `profiles`
+ * *starts a terminal and walks away*, this *holds a live connection* an
+ * extension can prompt, watch and cancel.
+ *
+ * **Sourced from user-authored profiles only.** There is deliberately no
+ * "connect to this command" — an extension cannot point Silo at an arbitrary
+ * binary to spawn with pipes. The user defines a Chat profile on
+ * Settings → Agents; an extension names it.
+ *
+ * Needs the **`"agents"` {@link Permission}**, declared in the extension's
+ * `silo.permissions` and granted at install: {@link connect} throws without it.
+ *
+ * @example
+ * ```ts
+ * const session = await ctx.agents.sessions.connect("claude-chat");
+ * const off = session.onUpdate((u) => {
+ *   if (u.kind === "agent_message_chunk") appendToTranscript(u.messageId, u.text);
+ * });
+ * const result = await session.prompt([{ type: "text", text: "Explain this repo." }]);
+ * ctx.log.info(`turn ended: ${result.stopReason}`);
+ * ctx.subscriptions.push(off, { dispose: () => session.dispose() });
+ * ```
+ *
+ * @category Consumer Services
+ * @public
+ * @beta
+ */
+export interface AgentSessionsService {
+  /**
+   * Spawn the agent for the named Chat profile, run the Agent Client Protocol
+   * `initialize` + `session/new` handshake, and resolve with a live
+   * {@link AgentSessionHandle}.
+   *
+   * Rejects when: the extension lacks the `"agents"` permission; no profile has
+   * that id; the profile is a Terminal profile, not a Chat one; there is no
+   * target workspace; the agent needs authentication (its `session/new`
+   * failed); or the agent reported a startup error (the rejection carries its
+   * message).
+   *
+   * With {@link AgentSessionConnectOptions.resume}, `connect()` still never
+   * rejects merely because the target has gone stale — it falls all the way
+   * through to a fresh `session/new` (RFC 0042); see {@link
+   * AgentSessionHandle.resumeOutcome}.
+   *
+   * @param profileId — an {@link AgentProfileSummary.id} whose profile uses the
+   * `chat` launch arm.
+   */
+  connect(
+    profileId: string,
+    options?: AgentSessionConnectOptions,
+  ): Promise<AgentSessionHandle>;
+  /**
+   * Read a session's **transcript journal** (RFC 0042) without connecting —
+   * for painting a restored panel *before* `connect({ resume })` resolves,
+   * which itself also pays for the `session/resume` / `session/load` network
+   * round trip. This is the "paint from journal" half of the restore flow;
+   * `connect()` is the "reconnect the agent" half, and the two run
+   * independently on purpose.
+   *
+   * Resolves `[]` for a session that never wrote a journal entry, or an
+   * unknown id — never rejects on a merely-missing journal. Needs the
+   * `"agents"` {@link Permission}, same as {@link connect}.
+   *
+   * @param sessionId — an {@link AgentSessionHandle.sessionId}.
+   */
+  readJournal(
+    sessionId: string,
+    options?: { workspaceId?: string },
+  ): Promise<readonly AgentSessionUpdate[]>;
+}
+
 /**
  * Host-computed coding-agent observability — exposed as
  * {@link ExtensionContext.agents}. Detection (what OSC/output signals mean
@@ -383,7 +1361,10 @@ export interface AgentsService {
    * instead.
    */
   getState(options?: { allWorkspaces?: boolean }): AgentInfo[];
-  /** Look up {@link AgentInfo} for a specific terminal tab by its record id. */
+  /** Look up {@link AgentInfo} for a specific terminal tab by its record id.
+   *  Only ever resolves a `kind: "terminal"` session — use
+   *  {@link AgentsService.getState} and match on {@link AgentInfo.id} to find a
+   *  Chat session. */
   getByTerminalId(terminalId: string): AgentInfo | undefined;
   /**
    * Subscribe to changes in the active workspace's agent state. Pass
@@ -416,8 +1397,134 @@ export interface AgentsService {
    *   }),
    * );
    * ```
+   *
+   * @param id — an {@link AgentInfo.id}. A terminal record id is one (every
+   * Terminal session's `id` equals its `terminalId`), so existing callers
+   * passing a terminal id keep working; a Chat session's id works too.
+   */
+  acknowledge(id: string): void;
+  /**
+   * The Agent Session the user is currently **looking at** — the one whose
+   * surface is the active tab — or `null` when the active tab is not an agent
+   * at all (an editor, a settings page, nothing).
+   *
+   * Kind-agnostic by construction: a terminal tab reports its Terminal
+   * session, and a dock panel that declared
+   * `DockPanelApi.setAgentSession` reports its Chat session. That is
+   * what lets one consumer implement "clear the badge for the session I'm
+   * watching" or "hide the row for the session I'm already looking at" without
+   * knowing which kind it got.
+   *
+   * @example
+   * ```ts
+   * // Hide the status row for whatever the user is already watching.
+   * const watching = ctx.agents.getActive();
+   * const rows = ctx.agents.getState().filter((a) => a.id !== watching);
+   * ```
+   */
+  getActive(): string | null;
+  /**
+   * Subscribe to changes in {@link AgentsService.getActive} — fired with the
+   * new value (or `null`) whenever the active surface moves. Returns a
+   * {@link Disposable} that cancels the subscription.
+   */
+  subscribeActive(listener: (id: string | null) => void): Disposable;
+  /**
+   * Bind a provider of **activity badges** for Agent Session tabs — the
+   * host-owned `Activity` chrome (spinner / ready / warn / error) on the
+   * trailing edge of a tab.
+   *
+   * The binder's `provide` is handed an {@link AgentInfo.id}, and the host
+   * routes the result to whichever tab is showing that session: a terminal tab
+   * for a Terminal session, or the dock panel that declared
+   * `DockPanelApi.setAgentSession` for a Chat session. One binder,
+   * both kinds — which is the point: the `ctx.terminals` equivalent takes a
+   * *terminal* id, so an extension literally could not badge a Chat session.
+   *
+   * `provide` is called synchronously for every visible tab during render.
+   * Keep it a lookup: no allocation, no async, no work proportional to the
+   * number of sessions.
+   *
+   * @example
+   * ```ts
+   * ctx.subscriptions.push(
+   *   ctx.agents.bindActivity({
+   *     id: "my-ext.agent-badge",
+   *     provide(agentSessionId) {
+   *       const info = ctx.agents
+   *         .getState({ allWorkspaces: true })
+   *         .find((a) => a.id === agentSessionId);
+   *       if (info?.activity !== "working") return null;
+   *       return { activity: "working", tooltip: "Agent working" };
+   *     },
+   *   }),
+   * );
+   * ```
+   */
+  bindActivity(binder: TabActivityBinder): Disposable;
+  /**
+   * Bind a provider of **leading icons** for Agent Session tabs — a brand mark
+   * so a tab running an agent is identifiable at a glance. Same routing and
+   * same synchronous-`provide` contract as
+   * {@link AgentsService.bindActivity}.
+   *
+   * Return `null` for "no icon". Take care that a component which renders
+   * nothing produces `null` here rather than a truthy element descriptor, or
+   * the host reserves tab space for an icon that never appears.
+   */
+  bindIcon(binder: TabIconBinder): Disposable;
+  /**
+   * Re-query every bound {@link AgentsService.bindActivity} /
+   * {@link AgentsService.bindIcon} provider. Call it when something *outside*
+   * the agent snapshot changed what a provider would return — a setting, the
+   * active theme — since the host cannot know about those.
+   */
+  invalidateAdornments(): void;
+  /**
+   * End an Agent Session, either kind: close its terminal tab, or close the
+   * dock panel that declared `DockPanelApi.setAgentSession` for it
+   * (which reaps the agent process as the panel unmounts).
+   *
+   * A no-op for an unknown id, or for a Chat session with no panel mounted —
+   * Silo will not kill a connection whose UI it cannot account for.
+   *
+   * @param id — an {@link AgentInfo.id}.
+   */
+  close(id: string): void;
+  /**
+   * Bring an Agent Session into view: focus its terminal tab if it is a
+   * Terminal session, or its transcript panel if it is a Chat session —
+   * activating the owning workspace first. The caller does not need to know
+   * which kind it is, which is the whole point of the verb (RFC 0038): a
+   * consumer holding an {@link AgentInfo.id} should never have to branch to
+   * `ctx.terminals.focus` vs. some chat-panel API.
+   *
+   * A no-op for an unknown id, or when the session's backing surface is gone
+   * (a closed terminal, a disposed panel).
+   *
+   * @param id — an {@link AgentInfo.id}.
    */
-  acknowledge(terminalId: string): void;
+  reveal(id: string): void;
+  /**
+   * Resume a session **through Silo**, when {@link AgentInfo.canResume} is
+   * `true`.
+   *
+   * - Chat session: spawn a fresh agent process and reconnect the persisted
+   *   id over `session/resume` or `session/load` — whichever the agent
+   *   advertises, `resume` preferred (RFC 0042) — so the transcript and
+   *   context come back after the old process died. Then
+   *   {@link AgentsService.reveal} it.
+   * - Terminal session: currently a no-op — a dead PTY cannot be re-run in
+   *   place, and the resume path stays "the user runs
+   *   {@link AgentInfo.resumeCommand}". Present on the surface so a
+   *   kind-agnostic consumer can call it unconditionally once Chat sessions
+   *   ship (RFC 0038 phase 4).
+   *
+   * A no-op for an unknown id or one whose `canResume` is `false`.
+   *
+   * @param id — an {@link AgentInfo.id}.
+   */
+  resume(id: string): void;
   /**
    * Every coding agent Silo knows about, as read-only
    * {@link CatalogAgentSummary} records. Detection stays sealed (ADR 0028) —
@@ -440,4 +1547,15 @@ export interface AgentsService {
    * @beta
    */
   readonly profiles: AgentProfilesService;
+  /**
+   * Connect to and drive a **Chat session** — a user-authored `chat` profile
+   * spawned as an Agent Client Protocol child (RFC 0038 phase 2). See
+   * {@link AgentSessionsService}. Needs the `"agents"` {@link Permission}:
+   * every `connect()` throws without it.
+   *
+   * @category Consumer Services
+   * @public
+   * @beta
+   */
+  readonly sessions: AgentSessionsService;
 }