@agent-compose/sdk 0.6.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).
@@ -77,6 +74,8 @@ export {
   requireScope,
   redactPattern,
   createGatePauseProcessor,
+  createAskHumanProcessor,
+  ASK_USER_QUESTION_TOOL,
 } from "./processors/index.js";
 export type {
   Processor,
@@ -106,6 +105,8 @@ export type {
 export type {
   SandboxProvider,
   DesktopSandboxProvider,
+  SandboxPtyOpts,
+  SandboxPtyHandle,
 } from "./types/sandbox.js";
 
 // HTTP client
@@ -120,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,
@@ -128,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
@@ -168,12 +231,33 @@ 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";
+export { createOpencodeRuntime, opencodeSpec } from "./runtimes/opencode.js";
+export type { OpencodeRuntimeConfig } from "./runtimes/opencode.js";
+export { default as opencodeRuntime } from "./runtimes/opencode.js";
+
+export { createCursorRuntime, cursorSpec } from "./runtimes/cursor.js";
+export type { CursorRuntimeConfig } from "./runtimes/cursor.js";
+export { default as cursorRuntime } from "./runtimes/cursor.js";
+
+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";
@@ -189,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,
@@ -197,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";
@@ -218,6 +305,7 @@ export {
 export type {
   Step,
   StepContext,
+  StepDeliverable,
   StepRunResult,
   Workflow,
   DefineStepOpts,
@@ -261,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
@@ -285,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/processors/ask-human.ts

@@ -0,0 +1,136 @@
+/**
+ * Ask-human processor (ADR-0028).
+ *
+ * Makes "ask a human" a FIRST-CLASS agent affordance: when the agent calls the
+ * built-in `AskUserQuestion` tool, this short-circuits it into a SERVER pause
+ * (`requestPauseAndAwait`) — the run freezes (compute stops), the question +
+ * options land on the human's pause feed, and the human's answer comes back as
+ * the tool result. No `agentc pause` CLI for the model to remember, and no
+ * dependency on prompt discipline: the moment the agent asks, the run pauses.
+ *
+ * Loud by construction — the danger this fixes is a pause that SILENTLY doesn't
+ * happen (a stale in-sandbox CLI, a non-E2B substrate, an auth error) letting
+ * the agent proceed as if it had an answer:
+ *   - pause cannot be created (server reject) → `Verdict.abort` ENDS the agent
+ *     loop with a WorkflowError. The run fails loud; it never guesses an answer.
+ *   - pause expires / is cancelled → the tool result says NO answer came and to
+ *     not assume one.
+ *
+ * Lives in the shared `gateToolCall` chain, so one implementation covers every
+ * runtime (the Claude Agent SDK `PreToolUse` hook and the ACP permission path).
+ * No run credential in the env (local / non-sandbox) → no-op: `AskUserQuestion`
+ * passes through untouched so a dev invocation isn't hard-failed.
+ */
+
+import type { Processor, ProcessorContext, ToolCall } from "./processor.js";
+import { Verdict } from "./processor.js";
+import { requestPauseAndAwait } from "../agent/pause-client.js";
+import type { GatePauseConnection } from "./gate-pause.js";
+
+/** The Claude built-in tool an agent uses to ask the user a question. */
+export const ASK_USER_QUESTION_TOOL = "AskUserQuestion";
+
+/** One question in an `AskUserQuestion` call (only the fields we read). */
+interface AskQuestion { question?: unknown; header?: unknown; options?: unknown }
+
+/** Pull the human-facing question + its option labels out of an
+ *  `AskUserQuestion` tool input. We pause on the FIRST question (the common
+ *  case); any others are folded into the reason so nothing is lost. */
+function parseAsk(input: Record<string, unknown>): { reason: string; options: Array<{ id: string; label: string }> } {
+  const questions = Array.isArray(input.questions) ? (input.questions as AskQuestion[]) : [];
+  const first = questions[0] ?? {};
+  const head = typeof first.question === "string" && first.question.trim()
+    ? first.question.trim()
+    : "The agent needs your input to continue.";
+  const extra = questions.length > 1
+    ? ` (+${questions.length - 1} more question${questions.length > 2 ? "s" : ""})`
+    : "";
+  const options = Array.isArray(first.options)
+    ? (first.options as Array<{ label?: unknown }>)
+        .map((o) => String(o?.label ?? "").trim())
+        .filter(Boolean)
+        .map((label) => ({ id: label, label }))
+    : [];
+  return { reason: head + extra, options };
+}
+
+/** Unwrap the dashboard's `{ decision }` resume payload to the raw answer text. */
+function answerText(decision: unknown): string {
+  const raw = decision !== null && typeof decision === "object" && "decision" in decision
+    ? (decision as { decision: unknown }).decision
+    : decision;
+  return typeof raw === "string" ? raw.trim() : raw == null ? "" : JSON.stringify(raw);
+}
+
+/** Recognise the agent shelling out to `agentc pause` and extract the same
+ *  {reason, options} we'd get from AskUserQuestion. We INTERCEPT it here — in the
+ *  tool gate, BEFORE the command runs — so the pause takes the DESIGNED path (the
+ *  answer returns as the tool result and the agent loop continues) instead of the
+ *  command actually blocking inside the sandbox shell, which froze the runner
+ *  mid-tool-exec and never resumed the loop. */
+function parseAgentcPause(command: string): { reason: string; options: Array<{ id: string; label: string }> } | null {
+  if (!/(^|\s|&&|;|\|)\s*agentc\s+pause(\s|$)/.test(command)) return null;
+  const r = command.match(/--reason(?:=|\s+)(?:"([^"]*)"|'([^']*)'|(\S+))/);
+  const reason = (r?.[1] ?? r?.[2] ?? r?.[3] ?? "The agent needs your input to continue.").trim();
+  const options = [...command.matchAll(/--option(?:=|\s+)(?:"([^"]*)"|'([^']*)'|(\S+))/g)]
+    .map((m) => (m[1] ?? m[2] ?? m[3] ?? "").trim())
+    .filter(Boolean)
+    .map((label) => ({ id: label, label }));
+  return { reason, options };
+}
+
+/** Pull the ask (reason + options) from either the `AskUserQuestion` tool OR a
+ *  `Bash` call running `agentc pause`. Null for anything else. */
+function extractAsk(call: ToolCall): { reason: string; options: Array<{ id: string; label: string }> } | null {
+  if (call.toolName === ASK_USER_QUESTION_TOOL) return parseAsk(call.toolInput);
+  if (call.toolName === "Bash") {
+    const cmd = (call.toolInput as { command?: unknown })?.command;
+    return typeof cmd === "string" ? parseAgentcPause(cmd) : null;
+  }
+  return null;
+}
+
+export function createAskHumanProcessor(opts: { connection?: GatePauseConnection } = {}): Processor {
+  return {
+    name: "ask-human",
+    async processToolCall(call: ToolCall, ctx: ProcessorContext) {
+      // Fires for AskUserQuestion OR a `Bash` call running `agentc pause` — both
+      // ask a human and must take the SAME processor path so the answer returns
+      // as the tool result and the agent loop continues.
+      const ask = extractAsk(call);
+      if (!ask) return Verdict.continue(call);
+
+      const conn = opts.connection ?? {
+        baseUrl: process.env.AGENT_COMPOSE_URL ?? "",
+        token:   process.env.AGENT_COMPOSE_RUN_TOKEN ?? "",
+        runId:   process.env.RUN_ID ?? "",
+      };
+      // No run credential (local / non-sandbox) — can't pause; let the tool
+      // through rather than hard-failing a dev invocation.
+      if (!conn.baseUrl || !conn.token || !conn.runId) return Verdict.continue(call);
+
+      let decision;
+      try {
+        decision = await requestPauseAndAwait({
+          baseUrl: conn.baseUrl, token: conn.token, runId: conn.runId,
+          reason: ask.reason,
+          ...(ask.options.length ? { options: ask.options } : {}),
+          action: { tool: call.toolName, input: call.toolInput },
+          signal: ctx.abortSignal,
+        });
+      } catch (err) {
+        // The pause could NOT be honored (server reject, non-E2B substrate, auth).
+        // Abort the loop — never let the agent proceed as if it had an answer.
+        const msg = err instanceof Error ? err.message : String(err);
+        return Verdict.abort(`Could not ask the human — the run could not be paused (${msg}). Stopping rather than guessing an answer.`);
+      }
+
+      if (decision.status === "resolved") {
+        const answer = answerText(decision.decision);
+        return Verdict.deny(`The human answered: ${answer || "(no text returned)"}. Continue using this answer.`);
+      }
+      // Expired / cancelled — no answer. Do NOT let the agent assume one.
+      return Verdict.deny(`No answer came back (${decision.status}). Do NOT assume an answer — ask again, or stop and report exactly what you need from a human.`);
+    },
+  };
+}

package/src/processors/index.ts

@@ -20,3 +20,8 @@ export {
 // through the shared gateToolCall chain.
 export { createGatePauseProcessor } from "./gate-pause.js";
 export type { GatePausePolicy, GatePauseApproval, GatePauseConnection } from "./gate-pause.js";
+
+// ADR-0028 — first-class "ask a human": maps the agent's `AskUserQuestion` tool
+// to a server pause and returns the human's answer as the tool result. Added by
+// default to every agent (no-op unless the tool is granted + called).
+export { createAskHumanProcessor, ASK_USER_QUESTION_TOOL } from "./ask-human.js";

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