@agent-compose/sdk 0.7.0 → 0.8.0

package/src/errors.ts

@@ -1,10 +1,49 @@
+/** Stable machine-readable denial codes on membership/capability-gated
+ *  mutations (ADR-0045). Reads never carry a code — a visibility denial is
+ *  a plain 404, indistinguishable from a missing id. */
+export type AuthzErrorCode =
+  | "role_read_only"
+  | "owner_required"
+  | "capability_required"
+  | "membership_required"
+  | "last_owner"
+  | "approver_only";
+
 /** Thrown by AgentComposeClient when the server returns a non-2xx response. */
 export class AgentComposeError extends Error {
+  /** Parsed `Retry-After` response header, in milliseconds, when the server
+   *  sent one (rate-limit 429s do). Pollers use it to honor the server's own
+   *  estimate of when the limit window clears instead of guessing. */
+  readonly retryAfterMs?: number;
+  /** Stable error code on gated-mutation 403s (ADR-0045) — one of
+   *  `AuthzErrorCode` when the denial is a membership/capability gate;
+   *  undefined otherwise. */
+  readonly code?: string;
+  /** The missing capability on a `capability_required` denial
+   *  (e.g. "write", "invoke", "see_runs"). */
+  readonly capability?: string;
+
   constructor(
     public readonly status: number,
     message: string,
+    opts?: { retryAfterMs?: number; code?: string; capability?: string },
   ) {
     super(message);
     this.name = "AgentComposeError";
+    if (opts?.retryAfterMs !== undefined) this.retryAfterMs = opts.retryAfterMs;
+    if (opts?.code !== undefined) this.code = opts.code;
+    if (opts?.capability !== undefined) this.capability = opts.capability;
   }
 }
+
+/** Parse a `Retry-After` header into milliseconds. Accepts both RFC 9110
+ *  forms — delta-seconds (`"120"`) and HTTP-date — and returns `undefined`
+ *  for anything unparseable so callers fall back to their own backoff. */
+export function parseRetryAfterMs(header: string | null | undefined): number | undefined {
+  if (!header) return undefined;
+  const seconds = Number(header);
+  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000);
+  const date = Date.parse(header);
+  if (!Number.isNaN(date)) return Math.max(0, date - Date.now());
+  return undefined;
+}

package/src/index.ts

@@ -16,7 +16,6 @@
 // Factory functions
 export { defineRuntime } from "./types/runtime.js";
 export { defineWorkflow } from "./types/workflow.js";
-export type { WorkflowDefinition } from "./types/workflow.js";
 export { defineSandboxEnvironment } from "./types/sandbox-environment.js";
 export type { SandboxEnvironmentDefinition } from "./types/sandbox-environment.js";
 
@@ -31,8 +30,6 @@ export type {
 
 // Workflow types and runtime utilities
 export type {
-  WorkflowFn,
-  WorkflowCtx,
   WorkflowRun,
   AgentBudget,
   WorkflowHooks,
@@ -46,7 +43,7 @@ export type { ConnectorRequestRules } from "./types/workflow-metadata.js";
 
 // Snapshot entry type re-exported for consumers (dashboard, CLI).
 export type { RunSnapshotEntry } from "./client.js";
-export type { WorkflowPlan, WorkflowStepPlan } from "./types/workflow-plan.js";
+export type { WorkflowPlan, WorkflowStepPlan, WorkflowStepDeliverable } from "./types/workflow-plan.js";
 export type { BaseExecutionContext, InvokeChild } from "./types/execution-context.js";
 
 // Request context — per-run typed bag (tenant identity + freeform).
@@ -108,6 +105,8 @@ export type {
 export type {
   SandboxProvider,
   DesktopSandboxProvider,
+  SandboxPtyOpts,
+  SandboxPtyHandle,
 } from "./types/sandbox.js";
 
 // HTTP client
@@ -122,6 +121,8 @@ export type {
   TeamMember, Mention, CreateMentionsInput,
   EventSubjectType, EventRow, ReportEventInput, ListEventsOptions, ListEventsResult,
   RunLogLine, ListRunLogsOptions,
+  RunListEntry, ListRunsOptions, RunDetail,
+  FundingLane, RunFundingStamp, RunFundingUsageRow, RunFundingResponse,
   RegisteredRuntime, RunState, RunStatus, FactoryRow, SnapshotListEntry, SnapshotListResponse,
   ApiKey, ApiKeyCreated,
   UsageRollupRow, UsageResponse,
@@ -130,13 +131,73 @@ export type {
   SendAgentMessageOptions, SendAgentMessageResponse,
   AnswerSteerOptions,
   ResumePauseOptions, ResumePauseResponse, ResumePauseSuccess, ResumePausePending, ResumePauseActor,
+  ConversationMessagePart, ConversationRow, ConversationMessageRow,
+  ConversationsPage, ConversationDetail, ConversationThread,
+  ConversationPageContext, SendConversationMessageInput, SendConversationMessageResult,
+  ConversationTurnState, ConversationPresenceSnapshot, StreamConversationOptions, AgentListRow,
+  CreateCloudSessionInput, CloudSessionCreated,
+  // Cloud-session developer surface (ADR-0052)
+  SessionPreview, PreviewOpened, OpenPreviewInput, SessionForked,
+  // Session branch proposals (ADR-0053)
+  SessionFileChange, SessionChangeSet,
+  SessionMergeReportDetail, SessionMergeReport, SessionDiscardReport,
+  // Channel-attached sessions (ADR-0057)
+  ChannelSessionStatus, ChannelSessionRow, ChannelSessionsResponse, SessionChannelMessagePosted,
+  FactoryFileSearchRow, FactoryFolderSearchRow, SearchFactoryFilesOptions, FactoryFileSearchResult, PublicFileLinkState,
+  // Membership-scoped authorization (ADR-0045)
+  ConversationMemberRole, ConversationMember,
+  DocumentCapability, TemplateCapability, ScopeGrant, ArtifactScope,
+  RunContext, SetScopeGrantsInput, SetTemplateScopeInput, TemplateDetail,
+  // Projects (ADR-0045 projects extension)
+  Project, ProjectsPage, ProjectRole, ProjectMember,
+  ProjectObject, ProjectObjectsPage, ProjectSkippedFile, ProjectPreviewFile,
+  ProjectAddPreview, AddProjectObjectInput, AddProjectObjectResult,
+  RefreshProjectObjectResult,
+  // Break-glass compliance sessions (ADR-0051)
+  ComplianceScopeKind, ComplianceStatus, ComplianceSession, ComplianceAccess,
+  RequestComplianceSessionInput, ListComplianceSessionsOptions, ComplianceSessionsPage,
+  ListComplianceAccessesOptions, ComplianceAccessesPage,
 } from "./client.js";
 
 // SSE parser — exposed so tests and downstream callers can reuse it.
 export { parseSseStream } from "./sse.js";
 
+// Cloud-session UI directives — the marker contract between the in-sandbox
+// `agentc` CLI and the server's cloud executor.
+export {
+  renderDirectiveMarker, parseDirectiveMarkers,
+  DIRECTIVE_MARKER_PREFIX, DIRECTIVE_MARKER_SUFFIX, MAX_DIRECTIVES_PER_OUTPUT,
+  REVISION_SELECTOR_RE,
+  ASK_DIRECTIVE_PROMPT_MAX, ASK_DIRECTIVE_MAX_OPTIONS,
+  ASK_DIRECTIVE_OPTION_ID_MAX, ASK_DIRECTIVE_OPTION_LABEL_MAX,
+  ASK_APPROVER_MIN, ASK_APPROVER_MAX,
+} from "./directives.js";
+export type { CloudDirective } from "./directives.js";
+
+// Conversation stream — typed wire events + the frame normalizer, shared by
+// `streamConversation` and clients that run their own SSE loop (the CLI's
+// `agentc session` terminal driver reuses its bridge parser + normalizes
+// through this, so every surface holds the same durable-vs-live invariant).
+export { normalizeConversationStreamEvent } from "./types/conversation-stream.js";
+export type {
+  ConversationStreamEvent, ConversationStreamAuthor,
+  ConversationPartEvent, ConversationPartPartialEvent, ConversationMessageDoneEvent,
+  ConversationErrorEvent, ConversationReactionEvent, ConversationMessageDeletedEvent,
+  ConversationReplayContinueEvent, ConversationTurnStateEvent, ConversationPresenceEvent,
+  ConversationSessionStatusEvent,
+  ConversationPresenceClient, ConversationAgentPresence,
+} from "./types/conversation-stream.js";
+
+// ACP client peer — the JSON-RPC client half of ADR-0020. Re-exported for the
+// CLI's local-agent bridge daemon (`agentc bridge`), which is an ACP client
+// over a locally spawned agent process and reuses the exact same peer +
+// session/update normaliser as the sandbox CLI-agent runtimes.
+export { AcpClientPeer, normalizeSessionUpdate, ACP_PROTOCOL_VERSION } from "./runtimes/_acp-client.js";
+export type { AcpAvailableCommand, AcpClientPeerDeps, AcpSessionCaps } from "./runtimes/_acp-client.js";
+
 // Errors and utilities
 export { AgentComposeError } from "./errors.js";
+export type { AuthzErrorCode } from "./errors.js";
 export { formatError } from "./utils/errors.js";
 
 // Bundling utilities
@@ -170,9 +231,11 @@ export type { GatewayModelId } from "ai";
 // CLI-agent runtimes — drive an external agentic CLI (codex / amp) inside the
 // sandbox and stream-parse its JSONL. No heavy npm deps (the CLI lives in the
 // sandbox image), so these are root-exported like claudeRuntime.
-export { createCodexRuntime } from "./runtimes/codex.js";
+export { createCodexRuntime, codexSpec } from "./runtimes/codex.js";
 export type { CodexRuntimeConfig } from "./runtimes/codex.js";
 export { default as codexRuntime } from "./runtimes/codex.js";
+// Reasoning-effort level a CLI runtime turn may carry (claude-code / codex).
+export type { CliReasoningEffort } from "./runtimes/_cli-agent.js";
 export { createAmpRuntime } from "./runtimes/amp.js";
 export type { AmpRuntimeConfig } from "./runtimes/amp.js";
 export { default as ampRuntime } from "./runtimes/amp.js";
@@ -188,6 +251,14 @@ export { createDroidRuntime, droidSpec } from "./runtimes/droid.js";
 export type { DroidRuntimeConfig } from "./runtimes/droid.js";
 export { default as droidRuntime } from "./runtimes/droid.js";
 
+// Claude Code as a CLI-agent runtime (in-sandbox `claude -p` / the Zed ACP
+// adapter) — the cloud-hostable counterpart of `claudeRuntime` (claude.ts,
+// which drives the Agent SDK in the calling process and so can never run a
+// server-driven cloud-session turn).
+export { createClaudeCodeRuntime, claudeCodeSpec, CLAUDE_CODE_ACP_ADAPTER, CLAUDE_CODE_THINKING_TOKENS } from "./runtimes/claude-code.js";
+export type { ClaudeCodeRuntimeConfig } from "./runtimes/claude-code.js";
+export { default as claudeCodeRuntime } from "./runtimes/claude-code.js";
+
 // Built-in coding tools for Vercel AI SDK runtime.
 export { bashTool, codingTools, editTool, readTool, writeTool } from "./tools/index.js";
 export type { CodingTool } from "./tools/index.js";
@@ -202,7 +273,10 @@ export { createSandbox, reconnectSandbox, killAllSandboxes, killSandboxById,
   parseSseExecStream, AGENT_COMPOSE_TAG,
   SANDBOX_VCPUS, DEFAULT_SANDBOX_SIZE, E2B_TEMPLATE_SIZES,
   isE2bSupportedSize, e2bMachineSpec, e2bBaseTemplate, e2bAgentEnvTemplate,
-  isPlatformE2bTemplateAlias } from "./sandbox.js";
+  isPlatformE2bTemplateAlias,
+  // ADR-0038 "Computer" — the per-member persistent desktop machine template.
+  E2B_DEVBOX_TEMPLATE, E2B_DEVBOX_SPEC, E2B_DEVBOX_RECIPE_VERSION,
+  e2bDevboxTemplateRef } from "./sandbox.js";
 export { SandboxUnavailableError, SANDBOX_UNAVAILABLE_PREFIX } from "./sandbox-errors.js";
 export type {
   SandboxCreateOpts, SandboxNetworkPolicy, SandboxNetworkHeaderTransform,
@@ -210,7 +284,7 @@ export type {
   SandboxQuotaResult, OwnedSandboxResult, OwnedSandbox, SandboxSize,
   ParseSseExecStreamOptions, SandboxCommandRunOptions, SandboxCommandResult,
 } from "./sandbox.js";
-export type { SandboxResources } from "./types/workflow-metadata.js";
+export type { SandboxResources, DriveMergePolicy } from "./types/workflow-metadata.js";
 
 // Workflow engine
 export { runWorkflow, WorkflowError, EngineError, classifyError, parseNameVersion } from "./workflows/engine.js";
@@ -231,6 +305,7 @@ export {
 export type {
   Step,
   StepContext,
+  StepDeliverable,
   StepRunResult,
   Workflow,
   DefineStepOpts,
@@ -274,7 +349,7 @@ export {
 } from "./pause/errors.js";
 export type { PauseErrorCode } from "./pause/errors.js";
 export type { PauseRequest } from "./pause/pause-core.js";
-export type { WaitForEventRequest } from "./pause/wrappers.js";
+export type { WaitForEventRequest, DecisionRequest } from "./pause/wrappers.js";
 // ADR-0028 — the in-sandbox pause client. `agentc pause` and the gate-pause
 // processor both pause their OWN run through the server pause API and block
 // until a human answers (create-then-poll; the VM suspends in place while
@@ -298,7 +373,26 @@ export { agentLoop, parseAgentStatus, DEFAULT_CLAUDE_MODEL } from "./agent/agent
 export type { AgentLifecycleEvent, AgentLoopOpts, AgentLoopResult } from "./agent/agent-loop.js";
 export { agent } from "./agent/run-agent.js";
 export type { AgentOpts } from "./agent/run-agent.js";
-export { AGENT_COMPOSE_MANUAL, buildAgentContextDoc, writeAgentContext } from "./agent/agent-context.js";
-export type { AgentConnectorInfo } from "./agent/agent-context.js";
+export { AGENT_COMPOSE_MANUAL, buildAgentContextDoc, writeAgentContext, buildAddedSessionBrief } from "./agent/agent-context.js";
+export type { AgentConnectorInfo, AddedSessionBriefParams } from "./agent/agent-context.js";
 export { AgentMessageSchema, parseAgentResponse } from "./agent/protocol.js";
 export { importSourceModule, TMP_DIR, LATEST_VERSION } from "./utils/source-loader.js";
+
+// The display palette (ADR-0040 §7) — the typed marker contract between
+// `agentc display` and the session executors, plus the promoter that maps
+// native-harness tool traffic onto the platform's rich-card part shapes.
+export {
+  DISPLAY_MARKER_KEY, DISPLAY_MARKER_VERSION, PLAN_MAX_ENTRIES, PLAN_ENTRY_MAX_CHARS,
+  TABLE_MAX_COLUMNS, TABLE_MAX_ROWS, TABLE_CELL_MAX_CHARS,
+  CHART_MAX_SERIES, CHART_MAX_POINTS_PER_SERIES, CHART_LABEL_MAX_CHARS,
+  ASK_PROMPT_MAX_CHARS, ASK_MAX_OPTIONS, ASK_OPTION_ID_MAX_CHARS, ASK_OPTION_LABEL_MAX_CHARS,
+  serializeDisplayMarker, parseDisplayMarker, findDisplayMarker, clampPlanEntries,
+  clampTableData, clampChartSeries, clampChartAxisLabel, clampAskOptions,
+  detectAgentcInvocation, shellWords, createDisplayPromoter,
+} from "./display.js";
+export type {
+  DisplayMarker, DisplayPlanEntry, DisplayPlanStatus,
+  DisplayTableCell, DisplayTableColumn, DisplayTableData,
+  DisplayChartKind, DisplayChartPoint, DisplayChartSeries, DisplayAskOption,
+  AgentcInvocation, PromotedPart, DisplayPromoter, DisplayPromoterContext,
+} from "./display.js";

package/src/pause/wrappers.ts

@@ -1,21 +1,24 @@
 /**
- * The two opinionated pause wrappers (ADR-0006 §"SDK surface"), each a thin
- * closure over `ctx.pause`:
+ * The three opinionated pause wrappers (ADR-0006 §"SDK surface", ADR-0042),
+ * each a thin closure over `ctx.pause`:
  *
  *   - `sleep`           — a lightweight timed pause; resolves on its own TTL,
  *                         skips the snapshot, returns void.
  *   - `waitForEvent`    — pause until an event resumes by correlation key.
- *
- * A typed human/agent decision is NOT a wrapper — it's a plain `ctx.pause`
- * with a `schema` (and `payload.options` for the dashboard's answer UI). The
- * pause primitive carries the reason (the ask) and the resume value (the
- * resolution); there is no separate `requestDecision`.
+ *   - `requestDecision` — a typed human/agent decision (wire `kind:
+ *                         "decision"`): the prompt/options/approvers ride
+ *                         `payload` for the dashboard's answer UI, and the
+ *                         resume value is the frozen `{ decision: string }`
+ *                         convention. `approvers` travel as RAW member refs
+ *                         (user ids or emails) — the SERVER resolves them
+ *                         against the team roster at pause-insert time and
+ *                         stamps the gate-bearing snapshots (ADR-0042 §2).
  *
  * Built from a `PauseFn` so the wrapper logic lives in one place and the step
  * runner just spreads them onto the context next to `pause`.
  */
 
-import type { z } from "zod";
+import { z } from "zod";
 import type { StepPauseRequest } from "../step-invocation/types.js";
 import type { PauseRequest } from "./pause-core.js";
 
@@ -23,7 +26,7 @@ import type { PauseRequest } from "./pause-core.js";
 export type PauseFn = <T = unknown>(req: PauseRequest<T>) => Promise<T>;
 
 /** Internal: pause with an explicit wire `kind`. The wrappers stamp
- *  `sleep`/`event` through this; the public `ctx.pause` is always
+ *  `decision`/`sleep`/`event` through this; the public `ctx.pause` is always
  *  `custom` and never exposes it. */
 export type KindedPauseFn = <T = unknown>(req: PauseRequest<T>, kind: StepPauseRequest["kind"]) => Promise<T>;
 
@@ -35,9 +38,26 @@ export interface WaitForEventRequest<T> {
   ttlMs?:         number;
 }
 
+export interface DecisionRequest {
+  prompt:          string;
+  /** Choices the decision UI offers as buttons; free text is always open. */
+  options?:        Array<string | { label: string; value: string }>;
+  /** Team member refs (user ids or emails, ≤ 10) — with any named, ONLY a
+   *  named approver may resolve the decision, and each gets an Activity
+   *  ping. Resolution is server-side at pause creation. */
+  approvers?:      string[];
+  /** DecisionDraft artifact rendered alongside the prompt. */
+  draft?:          Record<string, unknown>;
+  ttlMs?:          number;
+  correlationKey?: string;
+}
+
+const DecisionResultSchema = z.object({ decision: z.string() });
+
 export interface PauseWrappers {
   sleep(durationMs: number): Promise<void>;
   waitForEvent<T = unknown>(req: WaitForEventRequest<T>): Promise<T>;
+  requestDecision(req: DecisionRequest): Promise<{ decision: string }>;
 }
 
 export function buildPauseWrappers(pause: KindedPauseFn): PauseWrappers {
@@ -61,5 +81,20 @@ export function buildPauseWrappers(pause: KindedPauseFn): PauseWrappers {
         ...(req.ttlMs !== undefined ? { ttlMs: req.ttlMs } : {}),
       }, "event");
     },
+
+    requestDecision(req: DecisionRequest): Promise<{ decision: string }> {
+      return pause<{ decision: string }>({
+        reason: req.prompt,
+        payload: {
+          prompt: req.prompt,
+          ...(req.options !== undefined ? { options: req.options } : {}),
+          ...(req.approvers !== undefined ? { approvers: req.approvers } : {}),
+          ...(req.draft !== undefined ? { draft: req.draft } : {}),
+        },
+        schema: DecisionResultSchema,
+        ...(req.ttlMs !== undefined ? { ttlMs: req.ttlMs } : {}),
+        ...(req.correlationKey !== undefined ? { correlationKey: req.correlationKey } : {}),
+      }, "decision");
+    },
   };
 }

package/src/runtimes/_acp-client.ts

@@ -60,6 +60,28 @@ const OPTION_KIND_FOR_VERDICT = {
   deny: ["reject_once", "reject_always"],
 } as const;
 
+/** Session-lifecycle capabilities the agent advertised at `initialize`,
+ *  surfaced (not discarded) so callers can pick a resume strategy
+ *  (ADR-0037 §3). The in-sandbox CLI-agent runtimes ignore both — they
+ *  resume via the CLI's own on-disk rollout (ADR-0020 Q4); the bridge
+ *  daemon attempts `session/resume` only when `resume` is true. */
+export interface AcpSessionCaps {
+  /** Agent supports `session/load` — full-history replay as
+   *  `agent_message_chunk`s. Deliberately NOT used for resume: replaying
+   *  history would re-emit the transcript as new parts and duplicate the
+   *  conversation (ADR-0037 alternative D). */
+  loadSession: boolean;
+  /** Agent supports `session/resume` — context restore with NO replay. */
+  resume: boolean;
+}
+
+/** One entry of the agent's slash-command palette, as announced by the ACP
+ *  `available_commands_update` session notification. */
+export interface AcpAvailableCommand {
+  name: string;
+  description: string;
+}
+
 /** Collaborators `AcpClientPeer` needs from `CliAgentRunner`, kept as a small
  *  injected surface so the peer stays transport-agnostic and unit-testable. */
 export interface AcpClientPeerDeps {
@@ -80,6 +102,14 @@ export interface AcpClientPeerDeps {
   /** Turn-scoped abort signal from `sendMessage`. On abort the peer sends
    *  `session/cancel` for the live session. */
   signal?: AbortSignal;
+  /** The agent announced (or changed) its slash-command palette — an ACP
+   *  `available_commands_update` session NOTIFICATION, which can arrive at
+   *  any time (typically right after session/new, outside any prompt), so
+   *  it rides a callback rather than the per-turn message stream. Each call
+   *  carries the ENTIRE palette (replace semantics). Optional: the
+   *  in-sandbox runtimes ignore it; the bridge daemon reports it to the
+   *  server for composer autocomplete. */
+  onAvailableCommands?: (commands: AcpAvailableCommand[]) => void;
 }
 
 // ── The single session/update → AgentMessage normaliser ───────────────────────
@@ -270,6 +300,17 @@ export class AcpClientPeer {
     // answers method-not-found.
     const handler: Client = {
       sessionUpdate: (params: acp.SessionNotification): void => {
+        // The slash-command palette is session state, not turn content —
+        // it can land OUTSIDE any prompt (right after session/new), when
+        // no turn queue is being drained, so it goes to its own callback
+        // instead of the AgentMessage stream (which drops it).
+        if (params.update.sessionUpdate === "available_commands_update") {
+          this.deps.onAvailableCommands?.(params.update.availableCommands.map((c) => ({
+            name: c.name,
+            description: c.description,
+          })));
+          return;
+        }
         // Push mapped messages onto the queue. Tolerate updates that race in
         // after cancel (the agent may flush a few before unwinding) — the
         // normaliser handles them the same way.
@@ -290,9 +331,12 @@ export class AcpClientPeer {
    * Negotiate the wire protocol at `initialize`. Pins `protocolVersion` to
    * integer 1 and advertises NO fs / terminal capabilities. Returns the
    * version the agent negotiated — `CliAgentRunner` compares it to
-   * `ACP_PROTOCOL_VERSION` to decide ACP-path vs. legacy-JSONL fallback.
+   * `ACP_PROTOCOL_VERSION` to decide ACP-path vs. legacy-JSONL fallback —
+   * plus the agent's advertised session-lifecycle capabilities (`caps`),
+   * which the bridge daemon caches as `agent_sessions.resume_supported`
+   * (ADR-0037 §3). Absent capability blocks mean "not supported".
    */
-  async initialize(): Promise<{ protocolVersion: number }> {
+  async initialize(): Promise<{ protocolVersion: number; caps: AcpSessionCaps }> {
     const res = await this.conn.initialize({
       protocolVersion: ACP_PROTOCOL_VERSION,
       clientCapabilities: {
@@ -300,7 +344,15 @@ export class AcpClientPeer {
         terminal: false,
       },
     });
-    return { protocolVersion: res.protocolVersion };
+    return {
+      protocolVersion: res.protocolVersion,
+      caps: {
+        loadSession: res.agentCapabilities?.loadSession ?? false,
+        // Per the ACP schema, `resume` is a capability OBJECT (`{}` =
+        // supported), not a boolean — presence is the signal.
+        resume: res.agentCapabilities?.sessionCapabilities?.resume != null,
+      },
+    };
   }
 
   /**
@@ -316,6 +368,23 @@ export class AcpClientPeer {
     return res.sessionId;
   }
 
+  /**
+   * Resume an existing session by id — ACP `session/resume` (ADR-0037 §3).
+   * ADDITIVE and opt-in: the in-sandbox CLI-agent runtimes never call this
+   * (their resume path is the CLI's own persisted rollout, see
+   * `startSession`); the bridge daemon calls it only when `initialize`
+   * advertised `caps.resume`. Unlike `session/load` there is NO history
+   * replay — the agent restores its internal context and returns nothing,
+   * so nothing is re-emitted through the caller's part sink. Throws on an
+   * unknown/expired session id (JSON-RPC error from the agent) — the caller
+   * marks the durable row stale and falls back to `startSession` + full
+   * re-render. `this.sessionId` is only adopted on success.
+   */
+  async resumeSession(cwd: string, acpSessionId: string): Promise<void> {
+    await this.conn.resumeSession({ sessionId: acpSessionId, cwd, mcpServers: [] });
+    this.sessionId = acpSessionId;
+  }
+
   /**
    * Drive one `session/prompt` turn, yielding `AgentMessage`s as the agent
    * streams `session/update` notifications. Resolves the generator when the