@agentproto/runtime 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -3,35 +3,178 @@ import { B as BuildHeartbeatAgent } from './heartbeat-COGpMrJS.js';
 export { H as HeartbeatAgent, a as HeartbeatRunner, R as RuntimeEvent, b as RuntimeEvents, p as parseDuration } from './heartbeat-COGpMrJS.js';
 import { AcpMcpServer } from '@agentproto/acp';
 import { ChildProcess } from 'node:child_process';
+import { D as DeclaredAdapterOption } from './spawn-defaults-d5gAhNkV.js';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { AdapterHandle, AdapterLister } from '@agentproto/adapter-kit';
+import { AdapterHandle, SetupField, AdapterResolver, AdapterLister, AdapterEntry } from '@agentproto/provider-kit';
+import { SandboxProvider } from '@agentproto/sandbox';
 import { WorkspaceFs } from './workspace-fs.js';
 export { createWorkspaceFs } from './workspace-fs.js';
 export { ConversationMeta, ConversationStore, ConversationTurn, fileConversationStore } from './conversations.js';
+import { ProviderPreset } from '@agentproto/provider-presets';
+import { StepCache } from '@agentproto/workflow-runtime';
 export { PROVIDER_ENV_VARS, ProviderEntry, ProvidersFile, injectProviderKeysIntoEnv, loadProviders, providerEnvVar, providersPath, removeProviderKey, setProviderKey } from './providers-store.js';
 
+/**
+ * Per-session JSONL record of a completed `command_execute` invocation
+ * (and cron's `kind: "command"` action jobs, which share the same
+ * allowlist + `runCommand` path — see cron-scheduler.ts's "one
+ * enforcement path, not two" comment).
+ *
+ * Each call gets its OWN `kind: "command"` session, minted via
+ * `SessionsRegistry.recordCommand` — same as an agent-cli or PTY session,
+ * so it shows up in `session_list` / `command_list` for free instead of
+ * needing a bespoke query surface. Its result is stored at the exact
+ * per-id path an agent-cli session's structured transcript already uses:
+ * `~/.agentproto/sessions/<id>/events.jsonl` (see transcript-writer.ts).
+ * A command session's file holds exactly one line — there's no seq/turn
+ * machinery to reconstruct because the call is already finished by the
+ * time this is written.
+ *
+ * This module only knows how to read/write that one line; minting the
+ * session itself (and deciding the file's base directory) is
+ * `sessions.ts`'s job via `recordCommand`.
+ */
+interface CommandLogEntry {
+    ts: string;
+    command: string;
+    args: string[];
+    cwd: string;
+    exitCode: number;
+    signal: string | null;
+    durationMs: number;
+    stdout: string;
+    stderr: string;
+    truncated?: boolean;
+}
+
+/**
+ * Per-session usage snapshot — the single place that decides a session's
+ * `costUsd` and where that number came from.
+ *
+ * Two cost sources feed a session:
+ *   - an adapter's own usage reader (`readUsage`, e.g. hermes reads its
+ *     state.db) or an ACP `usage_update` that carries a `cost` block — these
+ *     are authoritative, tagged `source: "adapter"`.
+ *   - raw input/output token counts with NO adapter cost (ACP adapters like
+ *     claude-code / mastracode that report tokens but not dollars) — here we
+ *     price them ourselves against agentproto's in-repo LLM pricing catalog,
+ *     tagged `source: "computed"`.
+ *
+ * When tokens exist but the model is absent from the catalog we NEVER
+ * fabricate a price: `costUsd` is left undefined and the snapshot is tagged
+ * `source: "no-pricing"`. A session with neither cost nor tokens is
+ * `source: "none"`.
+ *
+ * This module is pure (the catalog lookup is injected) so the decision tree is
+ * unit-testable without building the whole model catalog.
+ */
+/** Where a session's `costUsd` came from — see the module doc. */
+type UsageSource = "adapter" | "computed" | "no-pricing" | "none";
+/** Per-token USD prices for a model (per 1M tokens), the subset of the
+ *  catalog's `LLMPricing` this module needs. */
+interface TokenPricing {
+    inputPer1M: number;
+    outputPer1M: number;
+}
+/** Pluggable pricing accessor — defaults to the in-repo catalog's
+ *  `resolvePricing`, overridable in tests. Returns undefined for an
+ *  unknown model (the caller then tags `no-pricing`). */
+type PricingResolver = (model: string) => TokenPricing | undefined;
+/** Raw signals gathered over a turn, handed to `deriveSessionUsage`. */
+interface UsageComputeInput {
+    /** Requested model id — needed to look up per-token prices. */
+    model?: string;
+    /** Cost the adapter reported directly (readUsage or usage_update.cost).
+     *  Present → authoritative, wins over token-based computation. */
+    adapterCostUsd?: number;
+    tokensIn?: number;
+    tokensOut?: number;
+    contextSize?: number;
+    contextUsed?: number;
+}
+/** The resolved usage snapshot — the shape `session_usage` returns and the
+ *  durable `usage_snapshot` transcript record carries. Cost/token fields are
+ *  omitted when absent so a missing value never reads as a measured zero. */
+interface SessionUsage {
+    model?: string;
+    costUsd?: number;
+    tokensIn?: number;
+    tokensOut?: number;
+    contextSize?: number;
+    contextUsed?: number;
+    source: UsageSource;
+}
+/**
+ * Decide a session's usage snapshot + cost source from the raw signals.
+ *
+ * Priority: an adapter-reported cost wins; else price the tokens against the
+ * catalog; else `none`. Never fabricates a price for an unpriced model.
+ */
+declare function deriveSessionUsage(input: UsageComputeInput, resolve?: PricingResolver): SessionUsage;
+/** Descriptor-shaped fields `projectSessionUsage` reads. */
+interface UsageDescriptorFields {
+    model?: string;
+    costUsd?: number;
+    tokensIn?: number;
+    tokensOut?: number;
+    contextSize?: number;
+    contextUsed?: number;
+    usageSource?: UsageSource;
+}
+/**
+ * Project a session descriptor's persisted usage fields into the
+ * `session_usage` response shape. Omits absent fields; defaults an
+ * unstamped `usageSource` to `"none"`.
+ */
+declare function projectSessionUsage(desc: UsageDescriptorFields): SessionUsage;
+
 /**
  * In-process pub/sub bus for session lifecycle events. Separate from
  * RuntimeEvents (global daemon bus) — session events are scoped to
  * individual sessions and fire at turn-level granularity.
  *
- * Consumers: EventRing (poll_events cursor), WebhookNotifier
+ * Consumers: EventRing (session_events_poll cursor), WebhookNotifier
  * (fire-and-forget HTTP), RoutineRunner (state machine fan-in),
- * and wait_for_any MCP tool (long-poll multiplexed).
+ * and session_monitor MCP tool (long-poll multiplexed).
  */
-type SessionEventType = "session:turn-end" | "session:awaiting-input" | "session:exited" | "session:command-done" | "policy:passed" | "policy:failed" | "policy:commit-ready" | "policy:committed";
+type SessionEventType = "session:turn-end" | "session:awaiting-input" | "session:exited" | "session:command-done" | "policy:passed" | "policy:failed" | "policy:commit-ready" | "policy:committed" | "cron:fired" | "cron:succeeded" | "cron:failed";
+/**
+ * Structured detail on why a session is awaiting input, when derivable.
+ * `source: "structured"` — a driver-reported ACP-style prompt (e.g. a tool
+ * permission request with real options). `source: "heuristic"` — a
+ * best-effort guess from the tail of the transcript (trailing "?" plus
+ * an optional enumerated option list) for drivers that don't report
+ * structured prompts. Absent entirely when neither could be determined —
+ * callers still have the plain `awaitingInput` boolean in that case.
+ */
+interface SessionAwaitingQuestion {
+    text: string;
+    options?: string[];
+    source: "structured" | "heuristic";
+}
 interface SessionTurnEndEvent {
     type: "session:turn-end";
     sessionId: string;
     awaitingInput: boolean;
     label?: string;
     ts: string;
+    question?: SessionAwaitingQuestion;
+    /**
+     * The adapter's stream `turn-end` reason, when the driver reports one
+     * (e.g. `"completed"`, `"cancelled"`, `"max_turns"`, or
+     * `"watchdog-timeout"` when the ACP client's turn-idle watchdog fired
+     * because the adapter went silent — see
+     * `@agentproto/acp/client`'s `AcpClientOptions.turnIdleTimeoutMs`).
+     * Absent for drivers that don't report a reason.
+     */
+    reason?: string;
 }
 interface SessionAwaitingInputEvent {
     type: "session:awaiting-input";
     sessionId: string;
     label?: string;
     ts: string;
+    question?: SessionAwaitingQuestion;
 }
 interface SessionExitedEvent {
     type: "session:exited";
@@ -41,8 +184,8 @@ interface SessionExitedEvent {
     label?: string;
     ts: string;
 }
-/** Emitted when execute_command finishes. commandId matches the id
- *  returned by the execute_command MCP tool. */
+/** Emitted when command_execute finishes. commandId matches the id
+ *  returned by the command_execute MCP tool. */
 interface SessionCommandDoneEvent {
     type: "session:command-done";
     sessionId: string;
@@ -68,7 +211,7 @@ interface PolicyFailedEvent {
 /**
  * Emitted by the supervisor (WP5) when a `then:"commit"` policy's gate passes
  * but `requireHumanAck` is set: the commit is staged-and-ready but NOT yet
- * executed. Carries the exact paths + message that `ack_policy(approve:true)`
+ * executed. Carries the exact paths + message that `policy_ack(approve:true)`
  * will commit. The policy sits in `awaiting-ack` until acked.
  */
 interface PolicyCommitReadyEvent {
@@ -81,7 +224,7 @@ interface PolicyCommitReadyEvent {
 }
 /** Emitted by the supervisor (WP5) when a `then:"commit"` policy has actually
  *  committed — either directly (requireHumanAck:false) or after an approving
- *  `ack_policy`. Carries the resulting commit sha. */
+ *  `policy_ack`. Carries the resulting commit sha. */
 interface PolicyCommittedEvent {
     type: "policy:committed";
     policyId: string;
@@ -91,7 +234,30 @@ interface PolicyCommittedEvent {
     message: string;
     ts: string;
 }
-type SessionEvent = SessionTurnEndEvent | SessionAwaitingInputEvent | SessionExitedEvent | SessionCommandDoneEvent | PolicyPassedEvent | PolicyFailedEvent | PolicyCommitReadyEvent | PolicyCommittedEvent;
+/** Emitted by CronScheduler when a job fires (before the action runs). */
+interface CronFiredEvent {
+    type: "cron:fired";
+    jobId: string;
+    label?: string;
+    ts: string;
+}
+/** Emitted by CronScheduler when a job action completes successfully. */
+interface CronSucceededEvent {
+    type: "cron:succeeded";
+    jobId: string;
+    label?: string;
+    summary: string;
+    ts: string;
+}
+/** Emitted by CronScheduler when a job action fails. */
+interface CronFailedEvent {
+    type: "cron:failed";
+    jobId: string;
+    label?: string;
+    error: string;
+    ts: string;
+}
+type SessionEvent = SessionTurnEndEvent | SessionAwaitingInputEvent | SessionExitedEvent | SessionCommandDoneEvent | PolicyPassedEvent | PolicyFailedEvent | PolicyCommitReadyEvent | PolicyCommittedEvent | CronFiredEvent | CronSucceededEvent | CronFailedEvent;
 interface SessionEventBus {
     emit(ev: SessionEvent): void;
     /** Subscribe to a specific event type. Returns an unsubscribe fn. */
@@ -103,26 +269,40 @@ interface SessionEventBus {
 }
 
 /**
- * Sessions registry — tracks long-lived child processes spawned by
- * the agentproto daemon (terminals, agent CLIs, custom commands).
+ * A per-session observer — the pluggable seam behind the runtime's transcript
+ * tap. `sessions.ts` drives one observer per turn (prompt in, each stream event,
+ * the turn-boundary usage snapshot, close). The transcript writer is the first
+ * and, today, only member; additional observers (e.g. a Langfuse session tracer)
+ * attach without touching the turn loop.
  *
- * The registry lives in-memory for the daemon's lifetime; a recent
- * snapshot also persists to `~/.agentproto/sessions.json` so a fresh
- * daemon restart can show "you had these running before" instead of
- * losing all visibility on a crash.
- *
- * Each session owns:
- *   - identity: id, kind, workspace slug, command + args, started time
- *   - lifecycle: status (starting/running/exited/killed/error)
- *   - output:    last N lines (ring buffer) for instant attach + a
- *                Node EventEmitter for live streaming consumers
+ * The method set is exactly the subset of `TranscriptWriter` the session loop
+ * calls, so `TranscriptWriter` IS a `SessionObserver` (see transcript-writer.ts).
+ */
+
+interface SessionObserver {
+    /** Record the outgoing message that opens a new turn. */
+    recordPrompt(sessionId: string, message: unknown): void;
+    /** Record one structured stream event (text-delta, tool-call, usage_update, …). */
+    recordEvent(sessionId: string, evt: AgentStreamEvent): void;
+    /** Record the durable turn-boundary / exit usage snapshot. */
+    recordUsageSnapshot(sessionId: string, usage: SessionUsage): void;
+    /** Flush and close this session's stream. Idempotent, fire-and-forget. */
+    close(sessionId: string): Promise<void>;
+    /** Close every open session stream (synchronous shutdown path). */
+    closeAll(): Promise<void>;
+}
+/**
+ * Fan a `SessionObserver` out over many. Each `record*` call is forwarded to
+ * every member in order; `close`/`closeAll` await all members.
  *
- * Consumers:
- *   - HTTP routes (GET /sessions, /sessions/:id, /sessions/:id/stream,
- *     POST /sessions/:id/kill)
- *   - CLI `agentproto sessions` (TUI navigation + attach)
- *   - guilde-web Active tab (session cards + terminal viewer)
+ * Every individual member call is isolated in try/catch so one throwing observer
+ * can neither break its siblings nor propagate into the turn loop — the
+ * transcript writer is effectively infallible today, but a future network-backed
+ * observer (a Langfuse sink) must never be able to throw a turn. Failures are
+ * swallowed here (no logging dependency at this layer); observers that need
+ * visibility into their own failures own that internally.
  */
+declare function composeSessionObservers(observers: readonly SessionObserver[]): SessionObserver;
 
 /**
  * Minimal shape we need from a driver-agent-cli session — kept as a
@@ -132,6 +312,12 @@ interface SessionEventBus {
  */
 interface AgentSessionLike {
     sessionId: string;
+    /** OS-level process id of the spawned child, when the driver owns a
+     *  real subprocess. Mirrored onto `SessionDescriptor.pid` at
+     *  `spawnAgent` time so `processAlive` can be computed without
+     *  adapter-specific forensics. Undefined for drivers that don't
+     *  expose a process (e.g. a future non-subprocess transport). */
+    pid?: number;
     send(message: unknown): AsyncIterable<AgentStreamEvent>;
     cancel(): Promise<void>;
     close(): Promise<void>;
@@ -165,7 +351,15 @@ type PtyFactory = (opts: PtyFactoryOptions) => PtyProcess;
 interface AgentStreamEvent {
     kind: string;
     text?: string;
+    /** Correlates a "tool-call" with its later "tool-result" (and an
+     *  "agent-prompt" with the permission it's asking about) — see
+     *  @agentproto/acp's `StreamEvent`. */
+    toolCallId?: string;
     toolName?: string;
+    /** Tool-call input, e.g. an ACP `tool_call`'s `arguments` — see @agentproto/acp's `StreamEvent`. */
+    arguments?: unknown;
+    /** Tool-call output, e.g. an ACP `tool_call_update`'s `result` — see @agentproto/acp's `StreamEvent`. */
+    result?: unknown;
     isError?: boolean;
     reason?: string;
     error?: {
@@ -173,6 +367,35 @@ interface AgentStreamEvent {
         code?: number;
         data?: unknown;
     };
+    /** Structured options offered by an "agent-prompt" event (e.g. an ACP
+     *  `requestPermission` callback surfaced as a clarifying question rather
+     *  than auto-answered). Typed `unknown` — like `@agentproto/acp`'s own
+     *  `StreamEvent["options"]` — so this structural type stays assignable
+     *  from any driver's runtime session without a hard dependency on its
+     *  exact option shape (`{optionId,name,kind}` for ACP, or whatever a
+     *  future driver reports); `normalizeAgentPromptOptions` narrows it
+     *  defensively at the one place it's consumed. */
+    options?: unknown;
+    /** "plan" event entries — see @agentproto/acp's `StreamEvent`'s `plan` kind. */
+    entries?: Array<{
+        content: string;
+        priority: string;
+        status: string;
+    }>;
+    /** "usage_update" context-window size (tokens). */
+    size?: number;
+    /** "usage_update" tokens currently in context. */
+    used?: number;
+    /** "usage_update" cumulative session cost, when the adapter reports one. */
+    cost?: {
+        amount: number;
+        currency: string;
+    };
+    /** "usage_update" cumulative input/output token counts, when the adapter
+     *  reports them (lets the daemon price a session whose adapter gives tokens
+     *  but no `cost`). */
+    tokensIn?: number;
+    tokensOut?: number;
 }
 type SessionKind = "terminal" | "agent-cli" | "command" | "browser";
 type SessionStatus = "starting" | "running" | "exited" | "killed" | "error";
@@ -191,6 +414,19 @@ interface SessionDescriptor {
     /** Last time anything was written to stdout/stderr. Lets the UI
      *  spot stuck sessions ("running for 2h, last output 12min ago"). */
     lastOutputAt?: string;
+    /** Last time ANY adapter-process activity was observed — ACP
+     *  JSON-RPC traffic, protocol-level events, not just ring-buffer
+     *  output lines. Stays current during long tool-call chains where
+     *  `lastOutputAt` goes stale. Updated on incoming session/update
+     *  notifications AND on outbound RPC calls. ISO 8601. */
+    lastActivityAt?: string;
+    /** Whether the underlying OS process is still alive. Computed via
+     *  `process.kill(pid, 0)` at read time (list()/get()) — cheap,
+     *  zero-overhead, standard POSIX check. Absent when `pid` is null
+     *  (no process to check). Never persisted — recomputed fresh on
+     *  every read since it's a live OS query, stale the instant it's
+     *  written to disk. */
+    processAlive?: boolean;
     /** Free-text label the spawner can attach (e.g. conversation id,
      *  operator name) so the UI can group/filter. */
     label?: string;
@@ -222,6 +458,16 @@ interface SessionDescriptor {
     /** Cumulative input / output token counts (same source + cadence as costUsd). */
     tokensIn?: number;
     tokensOut?: number;
+    /** Context-window size + tokens-in-context from the latest `usage_update`
+     *  event (ACP adapters that report a context window). Refreshed live as
+     *  usage_update events arrive, not just at turn-end. */
+    contextSize?: number;
+    contextUsed?: number;
+    /** Where `costUsd` came from — `"adapter"` (adapter's own reader or a
+     *  usage_update cost block), `"computed"` (tokens × in-repo catalog price),
+     *  `"no-pricing"` (tokens present but the model isn't in the catalog — cost
+     *  deliberately left undefined), or `"none"`. Stamped at each turn-end. */
+    usageSource?: UsageSource;
     /** ACP-level session id (the adapter's own handle — claude-code's
      *  conversation id, hermes' chat id, …). Set at spawnAgent time
      *  from `agentSession.sessionId`. Survives across daemon restarts
@@ -249,20 +495,42 @@ interface SessionDescriptor {
     resumeMetadata?: Record<string, string>;
     /** Set by the orchestration layer when the agent emits an
      *  "awaiting-input" turn-end. Cleared on the next turn start.
-     *  Used by `wait_for_any` to fast-return without subscribing. */
+     *  Used by `session_monitor` to fast-return without subscribing. */
     awaitingInput?: boolean;
+    /**
+     * Structured detail on WHY the session is awaiting input, when it can be
+     * determined — lets an orchestrator distinguish "blocked on a real
+     * question" from "just finished a turn" without re-reading raw output.
+     * `source: "structured"` comes from a driver-reported ACP-style prompt
+     * (`AgentStreamEvent.options`, e.g. a tool permission request);
+     * `source: "heuristic"` is a best-effort guess from the tail of the
+     * transcript (trailing "?" + an optional enumerated option list) for
+     * drivers that don't report structured prompts. Cleared alongside
+     * `awaitingInput` on the next turn start. */
+    awaitingQuestion?: SessionAwaitingQuestion;
     /** Count of turns that have fully completed (turn-end emitted) on this
-     *  session. Lets `wait_for_any` fast-return for a session that already
+     *  session. Lets `session_monitor` fast-return for a session that already
      *  finished its turn before the wait subscribed — a fast turn that ends
      *  in "completed" (not "awaiting-input") leaves no other persisted
      *  signal (status stays "running", busy clears). 0 = never ran a turn,
      *  so a freshly-spawned idle session is NOT mistaken for done. */
     turnsCompleted?: number;
     /** True while a turn is actively running (mirror of the internal
-     *  runtime `busy` flag). Lets `wait_for_any` distinguish "idle after a
+     *  runtime `busy` flag). Lets `session_monitor` distinguish "idle after a
      *  finished turn" from "mid-turn" so it doesn't fast-return a stale
      *  turn-end while the NEXT turn is still generating. */
     busy?: boolean;
+    /** What the in-flight turn is currently blocked on, when classifiable
+     *  from the pending tool call: a spawned sub-agent (`agent_start`) or a
+     *  shell/terminal command. Deliberately NO "user" variant — waiting on
+     *  the user is already covered by `awaitingInput`/`awaitingQuestion`.
+     *  Set on tool-call, cleared on the MATCHING tool-result (guarded by
+     *  `pendingToolCallId`), at turn start, and in the turn's finally. */
+    blockedOn?: "subagent" | "command";
+    /** toolCallId of the tool-call that set `blockedOn`. A tool-result only
+     *  clears `blockedOn` when its toolCallId matches — so a nested or
+     *  interleaved tool finishing first can't clear the flag early. */
+    pendingToolCallId?: string;
     /** Session id of the orchestrator that spawned this session, set when
      *  the spawn arrived via the scoped orchestrator sub-gateway (the
      *  token carried the spawner's identity). Absent for direct `/mcp`
@@ -276,6 +544,17 @@ interface SessionDescriptor {
      *  Treated as 0 when absent (legacy rows / direct spawns that predate
      *  WP4). */
     depth?: number;
+    /** Id of the most recently-completed `kind: "command"` session spawned
+     *  with the same `cwd`, found at spawn time — see `recordCommand` and
+     *  `findPriorCommandSessionId`. Deliberately a REFERENCE, not copied
+     *  content: a new session's own ring buffer / structured transcript
+     *  never gets a prior command_execute's stdout/stderr spliced in, it
+     *  just gets told where to look (`command_log_tail({sessionId})` or
+     *  `agent_export`/`command_list` resolve the id into the full record).
+     *  Set on `spawnAgent`/`spawnPty` when the registry already has a
+     *  matching command session; absent otherwise (including for legacy
+     *  rows persisted before this field existed). */
+    priorCommandSessionId?: string;
     /** Adapter id that drives this session (e.g. "camofox", "bureau"). */
     browserAdapterId?: string;
     /** Port the browser service listens on. */
@@ -284,6 +563,16 @@ interface SessionDescriptor {
     browserBaseUrl?: string;
     /** Execution location — "local" (default) or "cloud". */
     browserLocation?: "local" | "cloud";
+    /** True when this agent-cli session is running inside a sandbox (`agent_start.sandbox`)
+     *  rather than as a local subprocess — there's no local PID to check, so
+     *  `processAlive` never applies (it's already absent whenever `pid` is null). */
+    remote?: boolean;
+    /** Provider-assigned sandbox id (`BootedSandbox.sandboxId`), when `remote` is true. */
+    sandboxId?: string;
+    /** What session close does to the box (PR3 lifecycle) — `"kill"` (the
+     *  default, ephemeral) or `"pause"` (keeps `sandboxId` reconnectable via
+     *  `agent_start.sandbox.reuse`). Only set when `remote` is true. */
+    sandboxTeardown?: "kill" | "pause";
 }
 interface SessionsRegistry {
     spawn(input: SpawnSessionInput): SessionDescriptor;
@@ -306,25 +595,66 @@ interface SessionsRegistry {
      *  `attachPty(id, ...)`. Throws when the registry was constructed
      *  without a `spawnPty` factory (node-pty optional dep missing). */
     spawnPty(input: SpawnPtyInput): SessionDescriptor;
+    /** Register a COMPLETED `command_execute` (or cron `kind:"command"`
+     *  action) invocation as its own `kind: "command"` session. Unlike
+     *  `spawn`/`spawnAgent`/`spawnPty`, there's no live process to track —
+     *  the command already ran to completion via `runCommand` before this
+     *  is called — so the descriptor is minted already "finished"
+     *  (status exited/error, startedAt backdated by `durationMs`,
+     *  endedAt now) and its full result is written to that session's own
+     *  `events.jsonl` (see command-log.ts), the same per-id path an
+     *  agent-cli session's structured transcript uses. Synchronous: the
+     *  descriptor (and its id) is available immediately, the JSONL write
+     *  itself is fire-and-forget internally. */
+    recordCommand(input: RecordCommandInput): SessionDescriptor;
+    /** Read back a `kind:"command"` session's full logged result (the
+     *  `CommandLogEntry` `recordCommand` wrote). Resolves to null when the
+     *  session isn't a command session or has no recorded entry. Routed
+     *  through the registry (rather than callers importing
+     *  `readCommandLogEntry` directly) so the read always targets the same
+     *  base directory `recordCommand` wrote to — that dir is test-overridable
+     *  (`transcriptDir`) and callers outside sessions.ts have no other way
+     *  to know it. */
+    readCommandLog(sessionId: string): Promise<CommandLogEntry | null>;
     /** Register an already-running browser service adapter as a tracked
      *  session (kind="browser"). Idempotent by identity — each call
      *  mints a fresh session id. The `stop` callback is invoked by
      *  `kill()` best-effort. */
     registerBrowser(input: RegisterBrowserInput): SessionDescriptor;
     /** Send a follow-up turn to a live agent session. Throws when the
-     *  session is missing, not an agent-cli kind, or busy. The events
-     *  stream into the existing ring buffer + line emitter so /stream
-     *  consumers see them as they arrive. */
+     *  session is missing, not an agent-cli kind, dead (exited/killed/
+     *  error and unresumable — `SessionNotAliveError`), or busy
+     *  (mid-turn). The events stream into the existing ring buffer +
+     *  line emitter so /stream consumers see them as they arrive. */
     sendPrompt(id: string, message: unknown): Promise<void>;
-    /** Fire-and-forget variant of `sendPrompt`. Validates the same
-     *  preconditions synchronously — throws on missing session / wrong
-     *  kind / busy — but returns immediately after the turn is started,
-     *  letting the caller stream output via the SSE endpoint instead of
-     *  blocking on the full turn. Async errors during the turn are
-     *  pushed into the ring buffer as `[error]` lines so `/stream`
-     *  subscribers see them. Used by the web UI's chat input where a
-     *  long turn would otherwise freeze the textbox. */
-    enqueuePrompt(id: string, message: unknown): void;
+    /** Fire-and-forget variant of `sendPrompt` for the TURN ITSELF only.
+     *  Admission (resume attempt + the missing/wrong-kind/dead/busy
+     *  checks `sendPrompt` throws) is AWAITED before this resolves, so a
+     *  dead or busy session rejects instead of silently reporting
+     *  success — only resolves once the turn has actually started.
+     *  Errors during the turn's own execution (network drop, child died
+     *  mid-turn) are pushed into the ring buffer as `[error]` lines so
+     *  `/stream` subscribers see them. Used by the web UI's chat input
+     *  and MCP `agent_prompt`, where a long turn would otherwise freeze
+     *  the caller.
+     *
+     *  `opts.interrupt` lets a caller redirect a mid-turn session instead
+     *  of hitting the busy rejection: the in-flight turn is cancelled
+     *  (`agentSession.cancel()`), admission waits for that turn to
+     *  actually settle (busy flips false — no fixed sleep), then the new
+     *  prompt is admitted + fired on the SAME live session. Ignored
+     *  (identical to the default) when the session is idle. Omitted or
+     *  `false` reproduces today's mid-turn rejection byte-for-byte. */
+    enqueuePrompt(id: string, message: unknown, opts?: {
+        interrupt?: boolean;
+    }): Promise<void>;
+    /** Stamp `lastActivityAt` on a live agent-cli session's descriptor
+     *  and schedule a debounced persist. Called from the `onActivity`
+     *  callback threaded down through the driver → ACP client, which
+     *  fires on ANY adapter-process traffic (not just ring-buffer
+     *  output) — see `SessionDescriptor.lastActivityAt`. No-op when the
+     *  id is unknown (session already forgotten). */
+    pulseActivity(id: string): void;
     list(): SessionDescriptor[];
     get(id: string): SessionDescriptor | undefined;
     /** Subscribe to a session's output. Returns an unsubscribe fn.
@@ -448,6 +778,18 @@ interface SpawnAgentInput {
         tokensIn?: number;
         tokensOut?: number;
     } | null>;
+    /** Opt this session into Langfuse tracing (prompt/completion + tool spans +
+     *  tokens/cost). Effective opt-in is `trace ?? opts.langfuseTracingDefault ?? false`. */
+    trace?: boolean;
+    /** True when `agentSession` is a `SandboxAgentSessionProxy` (`agent_start.sandbox`)
+     *  rather than a local subprocess-backed session — stamped onto the descriptor
+     *  as `remote` since there's no local PID to report. */
+    remote?: boolean;
+    /** Provider-assigned sandbox id, when `remote` is true. */
+    sandboxId?: string;
+    /** What session close does to the box, when `remote` is true — see
+     *  `SessionDescriptor.sandboxTeardown`. */
+    sandboxTeardown?: "kill" | "pause";
 }
 interface SpawnSessionInput {
     kind: SessionKind;
@@ -491,6 +833,24 @@ interface SpawnPtyInput {
     name?: string;
     label?: string;
 }
+interface RecordCommandInput {
+    workspaceSlug: string;
+    /** Working directory the command actually ran in (post cwd-anchoring).
+     *  Matched against a fresh session's cwd by `findPriorCommandSessionId`. */
+    cwd: string;
+    command: string;
+    args: string[];
+    /** Fields mirror `command-tools.ts`'s `ExecuteResult` — kept inline here
+     *  (rather than importing that type) so sessions.ts has no dependency
+     *  on command-tools.ts. */
+    exitCode: number;
+    signal: string | null;
+    durationMs: number;
+    stdout: string;
+    stderr: string;
+    truncated?: boolean;
+    label?: string;
+}
 
 /**
  * MCP tools that expose browser service adapters (Camofox, Bureau, …) to
@@ -499,7 +859,7 @@ interface SpawnPtyInput {
  * for fs/exec/agent-cli.
  *
  * Five tools:
- *   list_adapter_browsers   discover available browser adapter ids + metadata
+ *   browser_adapter_list   discover available browser adapter ids + metadata
  *   start_browser           ensure a browser adapter is up, register as a session
  *   stop_browser            kill a running browser session
  *   list_browsers           browse alive/recent browser sessions
@@ -575,7 +935,7 @@ type BrowserAdapterLister = () => {
     config?: unknown[];
 }[];
 /**
- * Family-specific descriptor surfaced in the kit-path `list_adapter_browsers`
+ * Family-specific descriptor surfaced in the kit-path `browser_adapter_list`
  * response. Fields match the legacy lister shape so the tool output is
  * unchanged regardless of which path is active.
  */
@@ -593,7 +953,7 @@ interface BrowserAdapterInfo {
  * `TunnelRegistry` (multi-tunnel general surface) can share the same
  * provider contract without creating a circular dep.
  *
- * The tunnel family is the FIRST consumer of `@agentproto/adapter-kit`:
+ * The tunnel family is the FIRST consumer of `@agentproto/provider-kit`:
  * {@link TunnelProviderHandle} extends the kit's generic `AdapterHandle`
  * (slug/name/version/description/requiresSetup/check) with the
  * tunnel-specific `capabilities` + the existing `start`/`stop` lifecycle.
@@ -775,16 +1135,37 @@ declare class TunnelRegistry {
      * third-party secrets) merged with descriptor-carried config (named's
      * hostname/tunnelId/credentialsFile), descriptor taking precedence.
      */
-    private credsForDescriptor;
+    protected credsForDescriptor(desc: TunnelDescriptor): Promise<TunnelCreds>;
     private findEntryByIdOrName;
     private schedulePersist;
     private persistNow;
     private loadFromDisk;
 }
 
+/**
+ * Fire-and-forget webhook notifier for session lifecycle events.
+ *
+ * Each session can register its own `notifyUrl` (via `agent_start`).
+ * A global URL can be set via `AGENTPROTO_NOTIFY_URL` env var or
+ * `~/.agentproto/notify.json` (env wins). Both are POSTed when an event
+ * fires — the union of per-session + global URLs, deduplicated.
+ *
+ * Retry policy: one retry after 2 s on network error. No retry on 4xx/5xx.
+ * Timeout: 10 s per attempt. All errors are swallowed — the notifier never
+ * throws into the session's hot path.
+ */
+
+interface WebhookNotifier {
+    /** Register a per-session URL (called from agent_start). */
+    register(sessionId: string, url: string): void;
+    unregister(sessionId: string): void;
+    /** Handler to wire into SessionEventBus.onAny. Fire-and-forget. */
+    onSessionEvent(ev: SessionEvent): void;
+}
+
 /**
  * Cursor-based ring buffer for session events. Bridges the in-process
- * SessionEventBus (push) to the poll_events MCP tool (pull).
+ * SessionEventBus (push) to the session_events_poll MCP tool (pull).
  *
  * Capacity default: 1 000 events. Oldest entry dropped on overflow —
  * callers that lag beyond the cap see a gap in their cursor but never
@@ -845,9 +1226,9 @@ interface EventRing {
  *
  * Trigger: session:turn-end on the watched session(s).
  * Gate: optional shell command via the same allowlist + cwd-anchor as
- *       execute_command. exit 0 = pass.
+ *       command_execute. exit 0 = pass.
  * Action (then:"emit"): emits policy:passed / policy:failed on the bus
- *       (readable via poll_events).
+ *       (readable via session_events_poll).
  *
  * WP5 (then:"commit"): on a GREEN gate, prepare a host-side git commit in the
  * watched session's cwd — `git add -- <explicit paths>` then `git commit -m
@@ -859,7 +1240,7 @@ interface EventRing {
  * "nothing to commit" is treated as SUCCESS (idempotent re-commit after a
  * restart). `requireHumanAck` defaults to TRUE: the gate-green transition goes
  * to `awaiting-ack` and emits `policy:commit-ready` (paths + message) instead of
- * committing; the commit runs only on `ack_policy(approve:true)` →
+ * committing; the commit runs only on `policy_ack(approve:true)` →
  * `policy:committed` (+ sha) → done; `approve:false` → cancelled. With
  * `requireHumanAck:false` the commit runs directly at the green gate.
  * onFail (WP2): when gate fails, re-prompts the session(s) (sendPrompt) up to
@@ -913,7 +1294,10 @@ interface ShellGateSpec {
     command: string;
     args?: string[];
     /** Working directory for the gate command. Defaults to the watched
-     *  session's cwd, anchored to the workspace. */
+     *  session's own cwd (trusted as-is — it was already an explicit,
+     *  vetted choice made at `agent_start` time). When given explicitly,
+     *  anchored to that session's cwd (not the daemon's boot workspace)
+     *  so a stray/injected value can't escape it. */
     cwd?: string;
     timeoutMs?: number;
 }
@@ -970,7 +1354,7 @@ interface CommitSpec {
     /**
      * Human-in-the-loop gate before the commit actually runs. Default TRUE:
      * the green gate transitions to `awaiting-ack` + emits `policy:commit-ready`
-     * and waits for `ack_policy`. Set false to commit directly at the green gate.
+     * and waits for `policy_ack`. Set false to commit directly at the green gate.
      */
     requireHumanAck?: boolean;
 }
@@ -1073,6 +1457,15 @@ interface CompletionPolicySupervisor {
      */
     ack(policyId: string, approve: boolean): Promise<PolicyRunState | undefined>;
     list(): PolicyRunState[];
+    /**
+     * Subscribe to policy settlements — fired whenever a policy transitions
+     * into a terminal state (done / blocked / cancelled) OR into awaiting-ack.
+     * Used by the `/policies/:id/wait` long-poll to block until a policy
+     * resolves without reimplementing the state machine's event surface.
+     * Returns an unsubscribe fn. The callback receives the policyId; read
+     * the full state via `getStatus(policyId)`.
+     */
+    onSettle(cb: (policyId: string) => void): () => void;
     /**
      * Sync flush of the policy snapshot to disk. Call from the daemon
      * stop() path — mirrors sessions.shutdown().
@@ -1080,34 +1473,13 @@ interface CompletionPolicySupervisor {
     shutdown(): void;
 }
 
-/**
- * Fire-and-forget webhook notifier for session lifecycle events.
- *
- * Each session can register its own `notifyUrl` (via `start_agent_session`).
- * A global URL can be set via `AGENTPROTO_NOTIFY_URL` env var or
- * `~/.agentproto/notify.json` (env wins). Both are POSTed when an event
- * fires — the union of per-session + global URLs, deduplicated.
- *
- * Retry policy: one retry after 2 s on network error. No retry on 4xx/5xx.
- * Timeout: 10 s per attempt. All errors are swallowed — the notifier never
- * throws into the session's hot path.
- */
-
-interface WebhookNotifier {
-    /** Register a per-session URL (called from start_agent_session). */
-    register(sessionId: string, url: string): void;
-    unregister(sessionId: string): void;
-    /** Handler to wire into SessionEventBus.onAny. Fire-and-forget. */
-    onSessionEvent(ev: SessionEvent): void;
-}
-
 /**
  * Orchestrator sub-gateway (ADR §4.2 / WP2) — the security primitive
  * that lets a spawned agent become a *scoped* orchestrator without
  * handing it the daemon's full toolset.
  *
- * The plain `/mcp` endpoint registers EVERY tool (execute_command,
- * fs_*, remote_*, import_mcp, terminals, driver CRUD) and bypasses auth
+ * The plain `/mcp` endpoint registers EVERY tool (command_execute,
+ * fs_*, remote_*, mcp_import, terminals, driver CRUD) and bypasses auth
  * on loopback — pointing a child at it would be a privilege handout.
  * This module builds a second, scoped MCP server that registers ONLY a
  * curated orchestration allowlist, gated by an unguessable per-child
@@ -1126,21 +1498,20 @@ interface WebhookNotifier {
  * The curated set of tools a scoped child orchestrator may call.
  *
  * INCLUDED — the orchestration primitives:
- *   start_agent_session, prompt_agent_session, get_agent_session_output,
- *   wait_for_any, poll_events  (spawn + drive + fan-in)
- *   list_sessions, list_agent_sessions, kill_agent_session  (observe +
- *     halt). NB: list/kill are NOT yet scoped to the child's own
- *     subtree — that subtree filter is WP4 (parentSessionId/depth). For
- *     WP2 they are exposed daemon-wide; documented debt.
+ *   agent_start, agent_prompt, agent_output, agent_kill,
+ *   session_monitor, session_events_poll  (spawn + drive + fan-in)
+ *   session_list, session_tree  (observe). NB: list is NOT yet scoped
+ *     to the child's own subtree — that subtree filter is WP4
+ *     (parentSessionId/depth). For WP2 it is exposed daemon-wide;
+ *     documented debt.
  *
  * EXCLUDED — the danger surface (each a separate trust boundary):
- *   execute_command, terminal/PTY tools (raw shell), fs tools
- *   (read/write/delete file, create_directory, …), remote_* (publish
- *   the daemon to the internet), import_mcp / mcp_imported_* /
- *   list_discovered_mcps / remove_imported_mcp (widen the daemon's own
- *   MCP surface), and driver CRUD (create_/delete_/update_driver — these
- *   never register here because the scoped server is built with no
- *   doctype specs).
+ *   command_execute, terminal/PTY tools (raw shell), file_* /
+ *   directory_* tools, remote_* (publish the daemon to the internet),
+ *   mcp_import / mcp_discovered_* / mcp_imported_* (widen the daemon's
+ *   own MCP surface), and driver CRUD (create_/delete_/update_driver —
+ *   these never register here because the scoped server is built with
+ *   no doctype specs).
  */
 declare const DEFAULT_ORCHESTRATOR_TOOLS: readonly string[];
 interface OrchestratorScope {
@@ -1169,6 +1540,18 @@ interface OrchestratorScope {
     /** Max concurrently-alive children the owning orchestrator may spawn
      *  before further spawns are rejected. */
     maxChildren: number;
+    /**
+     * Name of the resolved role that owns this scope (spawn-role-
+     * profiles / privilege lattice). This is the "parent role" the
+     * `canSpawn` gate checks against when this scope is used to spawn a
+     * further child (`session-spawn.ts`). Defaults to `"supervisor"` at
+     * mint time when the caller doesn't say — every role that can reach
+     * `orchestrator: true` today resolves to supervisor (executor's
+     * `toolPolicy.delegation: "deny"` already excludes it from ever
+     * minting a scope), so this preserves #214 behaviour exactly until a
+     * custom role is actually granted delegation.
+     */
+    role: string;
 }
 /**
  * Narrow a caller-requested tool list to ⊆ a ceiling subset.
@@ -1197,6 +1580,9 @@ interface MintScopeOptions {
     maxDepth?: number;
     /** Per-orchestrator alive-child quota (default DEFAULT_MAX_CHILDREN). */
     maxChildren?: number;
+    /** Name of the resolved role that owns this scope. Default
+     *  `"supervisor"` — see `OrchestratorScope.role`. */
+    role?: string;
 }
 interface ScopeTokenRegistry {
     /** Mint a fresh scope-token. See `MintScopeOptions`. */
@@ -1228,16 +1614,21 @@ interface OrchestratorGatewayDeps {
     listAgentAdapters?: AgentAdapterLister;
     /** Orchestrator injector (WP3/WP4). When wired, a child orchestrator
      *  driving the scoped server can itself spawn sub-orchestrators
-     *  (`orchestrator: true` on its `start_agent_session`) — the new
+     *  (`orchestrator: true` on its `agent_start`) — the new
      *  token inherits depth+1 and is bounded by the caller's tools
      *  (non-re-grant). Omitted → recursion injection is unavailable on
      *  the scoped surface (a child can still spawn plain sub-agents). */
     orchestratorInjector?: OrchestratorInjector;
     /** Optional webhook notifier — same singleton as the root /mcp server.
-     *  When provided, per-session notifyUrl values from start_agent_session
+     *  When provided, per-session notifyUrl values from agent_start
      *  are registered on spawn and unregistered on exit, so child
      *  orchestrators spawning through this scoped gateway also fire webhooks. */
     webhookNotifier?: WebhookNotifier;
+    /** Forwarded to `registerSessionTools` — the daemon's own plain `/mcp`
+     *  gateway URL, defaulted onto `hermes` `agent_start` spawns issued
+     *  through this scoped sub-gateway that pass no `mcpServers`. See
+     *  `RegisterAgentToolsOptions.daemonMcpUrl`. */
+    daemonMcpUrl?: string;
 }
 type OrchestratorMcpServerFactory = (scope: OrchestratorScope) => Promise<McpServer>;
 /**
@@ -1310,37 +1701,109 @@ type OrchestratorInjector = (opts?: {
     /** Override the per-orchestrator child quota for the minted scope
      *  (clamped to the caller's). Root-only knob. */
     maxChildren?: number;
+    /** Name of the resolved role for the session THIS scope is being
+     *  minted for (i.e. the session becoming an orchestrator) — becomes
+     *  `OrchestratorScope.role`, the "parent role" a future spawn
+     *  through this scope is gated against. Default `"supervisor"`. */
+    role?: string;
 }) => OrchestratorInjection;
 /**
  * Build the orchestrator injector. Closed over the gateway's
  * scope-token registry + session-event bus + HTTP port. Returns a
- * function that the `start_agent_session` handler calls when its
+ * function that the `agent_start` handler calls when its
  * `orchestrator` field is set.
  */
 declare function createOrchestratorInjector(deps: OrchestratorInjectorDeps): OrchestratorInjector;
 
 /**
- * Tiny node:http server that fronts the runtime gateway.
+ * Shared types for pluggable sandbox providers.
+ *
+ * The sandbox family is a `@agentproto/provider-kit` consumer, same shape as
+ * the tunnel family (`remote-providers/types.ts`): {@link SandboxProviderHandle}
+ * extends the kit's generic `AdapterHandle` (slug/name/version/description/
+ * requiresSetup/check) with the AIP-36 capability namespace and the concrete
+ * `@agentproto/sandbox` `SandboxProvider` (`boot()`) the handle wraps.
+ */
+
+/**
+ * Declared capabilities of a sandbox provider — pure metadata, surfaced in
+ * `list_sandbox_providers`. Never carries secrets. Namespace mirrors AIP-36
+ * SANDBOX.md (`network.egress`, `mounts`, `lifecycle.pause_after_idle`,
+ * `read_only`, `limits.timeout_ms`).
+ */
+interface SandboxProviderCapabilities {
+    /** Sandbox can be given a network egress allowlist (AIP-36 `network.egress`). */
+    networkEgress: boolean;
+    /** Sandbox supports mounting external filesystems (AIP-36 `mounts`). */
+    mounts: boolean;
+    /** Sandbox can be paused (not just killed) between turns (AIP-36 `lifecycle.pause_after_idle`). */
+    lifecyclePause: boolean;
+    /** Sandbox can be started read-only (AIP-36 `read_only`). */
+    readOnly: boolean;
+    /** Hard cap on `limits.timeout_ms`, when the provider enforces one. */
+    maxTimeoutMs?: number;
+}
+/**
+ * A sandbox provider as an adapter-kit handle. Rides on the kit's generic
+ * {@link AdapterHandle} and adds the sandbox-specific `capabilities` plus
+ * the `@agentproto/sandbox` `SandboxProvider` the handle wraps — the thing
+ * `createSandboxAgentSessionHost` actually boots.
+ */
+interface SandboxProviderHandle extends AdapterHandle {
+    readonly provider: SandboxProvider;
+    readonly capabilities: SandboxProviderCapabilities;
+    /**
+     * Credential fields this provider accepts via `setup_sandbox_provider`
+     * (e.g. e2b's `apiKey`). Omit (or empty) when the provider needs no
+     * credentials (e.g. `local`).
+     */
+    readonly setupFields?: readonly SetupField[];
+}
+
+/**
+ * Sandbox family on top of `@agentproto/provider-kit` — mirrors
+ * `tunnel-adapters.ts`. This module is the entire bridge between the
+ * generic kit and `@agentproto/sandbox`'s `SandboxProvider` concept: it
+ * contributes nothing the kit already owns (catalog/status/creds/ledger/
+ * list/MCP-tool plumbing); it only supplies the sandbox-family `TInfo`
+ * (`SandboxAdapterInfo`), the static `SANDBOX_CATALOG`, and the resolver
+ * that maps a catalog slug to a concrete {@link SandboxProviderHandle}
+ * (`./sandbox-providers/registry.js`).
  *
- * Routes:
- *   GET  /health              — { status, workspace, registered, uptime }
- *   GET  /events              — SSE stream of RuntimeEvent
- *   POST /mcp                 — MCP Streamable HTTP transport (POST)
- *   GET  /mcp                 — MCP SSE response stream (GET)
- *   DELETE /mcp               — close MCP session
- *   GET  /conversations       — JSON list of conversation summaries
- *   GET  /conversations/<id>  — markdown body of one conversation
- *   POST /heartbeat/tick      — force-fire one heartbeat tick
+ * Kit primitives used:
+ *   - `makeCredsStore`      → per-slug 0600 creds under `~/.agentproto/sandbox-creds/`
+ *   - `makeSetupLedger`     → `~/.agentproto/setup/<slug>.json`
+ *   - `makeAdapterResolver` → wraps the throwing `load` into null-on-miss
+ *   - `makeAdapterLister`   → catalog → status-classified `AdapterEntry[]`
+ *   - `makeListTool`        → registers `list_sandbox_providers`
+ *   - `makeSetupTool`       → registers `setup_sandbox_provider` (multi-field
+ *                             form: e2b's `apiKey`, sensitive)
  *
- * No auth in `mode: "none"` (loopback default). `mode: "bearer"`
- * checks `Authorization: Bearer <token>` against the configured
- * token. Health is always public so external monitors can probe.
+ * This is pure additive plumbing (introspection + setup) — it does NOT wire
+ * a `sandbox` field into `agent_start`. That lands in a follow-up PR; the
+ * `resolveSandboxProvider`/`listSandboxProviders` overrides below exist now
+ * so that later wiring can inject the same resolver/lister this module
+ * builds by default, mirroring `resolveAgentAdapter`/`listAgentAdapters`.
  *
- * MCP transport: stateless mode for v1 — each request is independent.
- * Stateful session pinning can come later when long-running streaming
- * tool calls become a real use case.
+ * Security: `toSandboxInfo` exposes only `capabilities` — never a cred
+ * value (Appendix B). The setup tool's fields are marked SENSITIVE and the
+ * result NEVER echoes any field value back.
  */
 
+/**
+ * Family descriptor (`TInfo`). Pure metadata surfaced in
+ * `list_sandbox_providers`. The kit's `AdapterEntry` already carries
+ * slug/name/description/status/version, so the only sandbox-specific field
+ * is the declared capability set. NEVER carries a cred value.
+ */
+interface SandboxAdapterInfo {
+    capabilities: SandboxProviderCapabilities;
+}
+/** Resolve a sandbox provider slug to a handle, or null when unavailable. */
+type SandboxProviderResolver = AdapterResolver<SandboxProviderHandle>;
+/** List every sandbox provider with its live status + capabilities. */
+type SandboxProviderLister = AdapterLister<SandboxAdapterInfo>;
+
 /**
  * Pluggable adapter resolver — keeps the runtime package free of any
  * @agentproto/cli dep. The host (cli `serve`, playground, embedding
@@ -1361,12 +1824,36 @@ type AgentAdapterResolver = (slug: string) => Promise<{
     startSession(opts: {
         cwd: string;
         resumeSessionId?: string;
-        /** Model identifier forwarded from `start_agent_session`. For ACP
+        /**
+         * Manifest-declared mode id forwarded from `agent_start` (AIP-45
+         * `AgentCliHandle.modes` — e.g. claude-code's `plan` /
+         * `accept-edits` / `bypass-permissions`, codex's `read-only`,
+         * mastracode/opencode's `plan`). Applied at spawn time via
+         * `composeSpawn`'s mode patch (`bin_args_append` / `env`) — BEFORE
+         * the child process is exec'd, unlike `model`/`effort` below.
+         * Adapters with no declared `modes` (e.g. hermes) ignore it; an
+         * unknown id for an adapter that DOES declare modes throws
+         * `RuntimeConfigError` (composeSpawn validates against the
+         * manifest, so a typo fails the spawn rather than silently no-op).
+         */
+        mode?: string;
+        /**
+         * Manifest-declared option id → value map forwarded from
+         * `agent_start` (AIP-45 `AgentCliHandle.options` — e.g. hermes'
+         * `skills`). Applied at spawn time via `composeSpawn`'s option
+         * patches (`bin_args_prepend` / `bin_args_template` /
+         * `bin_args_append_when_true` / `env`), validated against each
+         * option's declared `type`/`enum`/`min`/`max`. An id the adapter
+         * doesn't declare throws `RuntimeConfigError` (composeSpawn
+         * validates against the manifest, same as an unknown `mode`).
+         */
+        options?: Record<string, boolean | number | string>;
+        /** Model identifier forwarded from `agent_start`. For ACP
          *  adapters this is applied via session/set_config_option after
          *  newSession (the ACP wrapper does not forward CLI args to claude).
          *  Adapters that don't support model selection ignore it. */
         model?: string;
-        /** Effort level forwarded from `start_agent_session`. Effort is
+        /** Effort level forwarded from `agent_start`. Effort is
          *  model-dependent — same label ≠ same budget across models; defaults
          *  differ by model. Omit to keep the model's own default. Applied
          *  via session/set_config_option on ACP adapters; others ignore it. */
@@ -1377,6 +1864,12 @@ type AgentAdapterResolver = (slug: string) => Promise<{
          *  a host-chosen scoped toolset (e.g. the daemon's own orchestration
          *  gateway). Adapters that don't model MCP mounting ignore it. */
         mcpServers?: AcpMcpServer[];
+        /** Called on any adapter-process activity (ACP JSON-RPC traffic in
+         *  either direction) — forwarded to the driver's
+         *  `runtime.start({ onActivity })`. The caller (agent_start's MCP
+         *  handler, POST /sessions/agent) wires this to pulse
+         *  `SessionDescriptor.lastActivityAt` via `registry.pulseActivity(id)`. */
+        onActivity?: () => void;
     }): Promise<AgentSessionLike>;
     /** Display label for the descriptor's `command` field. */
     commandPreview?: string;
@@ -1386,7 +1879,30 @@ type AgentAdapterResolver = (slug: string) => Promise<{
         tokensIn?: number;
         tokensOut?: number;
     } | null>;
+    /** AIP-45 `options[]` this adapter's manifest declares (id + type only —
+     *  no spawn internals). Lets `session-spawn.ts` fold a config-level
+     *  `defaults.skills` list into `options.skills` using the shape the
+     *  manifest actually declared (e.g. hermes' comma-joined string),
+     *  instead of guessing. Omitted/empty ⇒ the skills normalization is a
+     *  documented no-op for that adapter (e.g. claude-code, which
+     *  auto-discovers skills and declares no such option). */
+    declaredOptions?: readonly DeclaredAdapterOption[];
 } | null>;
+/**
+ * UI-safe projection of an AIP-45 `modes[]` entry as surfaced by
+ * `adapter_list`. Mirrors `@agentproto/cli`'s `AdapterMode` without
+ * importing it (the runtime deliberately carries no cli dep — see the
+ * `AgentAdapterLister` note above). Spawn internals (`bin_args_*`, `env`)
+ * are intentionally omitted; `status` is normalised to `"active"` by the
+ * lister when the manifest omits it, so a declared mode is never
+ * silently statusless.
+ */
+interface AdapterListMode {
+    id: string;
+    description?: string;
+    status: "active" | "noop" | "planned";
+    status_note?: string;
+}
 /**
  * Compact adapter metadata for the discovery endpoints. Independent
  * of the resolver function above — hosts that can list installed
@@ -1401,6 +1917,10 @@ interface AdapterListEntry {
     protocol: string;
     streaming: boolean;
     packageName: string;
+    /** Declared operation modes with their honest support status, so a
+     *  client can see e.g. hermes' `lean` mode is a measured no-op instead
+     *  of being silently accepted. Empty when the adapter declares none. */
+    modes: AdapterListMode[];
 }
 type AgentAdapterLister = () => Promise<AdapterListEntry[]>;
 interface AuthOptions {
@@ -1487,7 +2007,7 @@ interface InboundWatcher {
 }
 
 /**
- * Browser family on top of `@agentproto/adapter-kit` — Phase 3 (lightest
+ * Browser family on top of `@agentproto/provider-kit` — Phase 3 (lightest
  * adoption: no creds, no wizard, no catalog file).
  *
  * Provides the kit-compatible types (`BrowserAdapterHandle`) and the
@@ -1530,6 +2050,138 @@ declare function makeBrowserAdapterLister(opts: {
     resolveBrowserAdapter?: BrowserAdapterResolver;
 }): AdapterLister<BrowserAdapterInfo>;
 
+/**
+ * Turns a raw tool-call name + args (and its eventual result) into a short,
+ * human-readable line for ring-buffer / CLI / transcript rendering. Without
+ * this, every tool call renders as a bare `[tool] view` with no args and no
+ * outcome — this module is the one place that knows how to summarize both.
+ */
+/** A one-line human summary of a tool call, e.g. `read src/foo.ts` or `⏰ wake in 30s — checking CI`. */
+declare function formatToolCall(toolName: string, args: unknown): string;
+/**
+ * A short outcome line for a completed tool call, or `null` when there's
+ * nothing useful to show (e.g. an empty/void result). `toolName` is
+ * accepted for parity with `formatToolCall` and future bespoke result
+ * formatting, but generic text extraction covers today's cases.
+ */
+declare function formatToolResult(toolName: string | undefined, result: unknown, isError: boolean): string | null;
+
+/**
+ * Dependency-injection surface for MCP credential resolution.
+ *
+ * `packages/runtime` intentionally does NOT depend on `@agentproto/auth`;
+ * the daemon bootstrap (e.g. `packages/cli`) can set a broker-backed
+ * resolver here, and `session-spawn.ts` will call it when an `mcpServers`
+ * entry carries `credentialRef`. Errors from the hook are treated as
+ * non-fatal by the caller.
+ */
+interface McpCredentialDeps {
+    /** Resolve brokered headers for an `mcpServers` entry that names a
+     *  `credentialRef`. The returned headers are merged ON TOP of the
+     *  entry's static `headers` so brokered auth wins on collision. */
+    resolveMcpCredentialHeaders?: (o: {
+        credentialRef: string;
+        signal?: AbortSignal;
+    }) => Promise<Record<string, string> | undefined>;
+    /** Resolve a single named secret (an env-var-shaped slug — e.g. a sandbox
+     *  spec's `env.passthrough` / `env.auth.state.env` entries) to its raw
+     *  value. Distinct from `resolveMcpCredentialHeaders` above (which
+     *  resolves an MCP `credentialRef` PATH into Authorization-style
+     *  headers): this is the `SecretResolver` shape `agent_start`'s sandbox
+     *  branch (`session-spawn.ts`) passes to `@agentproto/sandbox`'s
+     *  `SandboxSecretsConfig.resolver` — so a booted sandbox's env is filled
+     *  from the same host-injected broker as every other secret, never a
+     *  bare `process.env` read at the call site. Returns null when the slug
+     *  can't be resolved (missing/unconfigured). */
+    resolveSandboxSecret?: (slug: string) => Promise<string | null>;
+}
+declare function setMcpCredentialDeps(d: McpCredentialDeps): void;
+declare function getMcpCredentialDeps(): McpCredentialDeps;
+
+/**
+ * Provider-preset family on top of `@agentproto/provider-kit` — the *thin,
+ * honest* lister (Option B). Unlike tunnels/sandboxes/eval-reporters, presets
+ * are bundled static data with no binary to install, no package to resolve, and
+ * no setup ledger: their only "setup" is an ambient API-key env var. So this
+ * module does NOT use `makeAdapterResolver` / `makeAdapterLister` / the wizard
+ * (all install-oriented, a forced fit). It reuses only `makeListTool` — the one
+ * kit primitive that's genuinely about "JSON a lister's output as an MCP tool."
+ *
+ * Status is derived honestly from the daemon's own environment (the env agents
+ * spawn into), not the CLI caller's:
+ *   "ready"     — `process.env[preset.keyEnv]` is set (key available to spawn)
+ *   "available" — key absent (preset known, usable once the env var is provided)
+ *
+ * There is no "supported" state: presets ship in-repo, so they're always at
+ * least "available." `version` is the literal "built-in".
+ *
+ * Security (Appendix B): `PresetInfo` carries only `keyEnv` (the env-var NAME),
+ * never a key value. The list tool never returns creds — there are none to
+ * return; keys live in the operator's environment, not a creds store.
+ */
+
+/**
+ * Manifest-declared AIP-45 preset, the minimum the catalog needs to merge
+ * an adapter-contributed preset into the listing. Mirrors
+ * `AgentCliPresetDeclaration`'s fields without importing
+ * `@agentproto/driver-agent-cli` into the runtime package (same structural-
+ * type pattern as `DeclaredAdapterOption` in spawn-defaults.ts).
+ */
+interface DeclaredAdapterPreset {
+    id: string;
+    label: string;
+    description?: string;
+    schemaFlavor: ProviderPreset["schemaFlavor"];
+    baseUrl: string;
+    keyEnv: string;
+    scrubEnv?: string[];
+    defaultModel?: string;
+    homepage?: string;
+}
+/**
+ * Family descriptor surfaced as `AdapterEntry.info`. User-facing preset facts
+ * only — no cred values (there are none in the registry), no adapter projection
+ * detail (`scrubEnv` stays internal to adapter manifests).
+ */
+interface PresetInfo {
+    /** API schema flavor — which adapter family can consume this preset. */
+    schemaFlavor: ProviderPreset["schemaFlavor"];
+    /** Base URL the client hits. */
+    baseUrl: string;
+    /** Env-var NAME holding the API key (never the value). */
+    keyEnv: string;
+    /** Conventional default model id, if any. */
+    defaultModel?: string;
+    /** Homepage/docs URL. */
+    homepage?: string;
+}
+/**
+ * Normalize a manifest-declared preset into the canonical `ProviderPreset`
+ * shape the catalog lists. `scrubEnv` defaults to empty (an adapter that
+ * scrubs in code may omit it); `description` defaults to empty. Pure.
+ */
+declare function declaredPresetToProviderPreset(decl: DeclaredAdapterPreset): ProviderPreset;
+/**
+ * Map the static preset registry → status-classified catalog entries, reading
+ * the daemon's environment for key presence. Pure (no I/O) save the `process`
+ * .env read; safe to call on every list invocation.
+ *
+ * `adapterPresets` — manifest-declared presets contributed by loaded adapters
+ * (Stage 3 AIP-45 `presets` field). Merged AFTER the built-in registry and
+ * deduped by id: an adapter-declared id that collides with a built-in is
+ * ignored (the registry is the source of truth for canonical providers), so
+ * an adapter can't silently override moonshot/openrouter facts. The live
+ * wiring that reads each adapter's `.presets` and passes them here is Stage 4;
+ * today this is the tested seam.
+ */
+declare function listPresets(env?: Record<string, string | undefined>, adapterPresets?: readonly DeclaredAdapterPreset[]): AdapterEntry<PresetInfo>[];
+
+/** A journal-file StepCache scoped to one cacheKey. Best-effort: read/parse
+ *  failures degrade to "no cache" (a miss), never throw into the run. */
+declare function createFileStepCache(cacheKey: string, opts?: {
+    dir?: string;
+}): StepCache;
+
 /**
  * `.agentproto/` config dir — runtime-managed state at the root of
  * every workspace. Mirrors the `.git/` model: user-content stays at
@@ -1648,6 +2300,90 @@ declare function readRuntimeMeta(workspace: string): Promise<{
  */
 declare function sweepStaleRuntimeMetas(workspaces: readonly string[], currentWorkspace: string): Promise<string[]>;
 
+/**
+ * MCP tools for event-driven orchestration:
+ *   - session_events_poll — cheap cursor-based snapshot of session events
+ *   - session_monitor     — multiplexed long-poll (1 call for N sessions)
+ *
+ * These complement the existing per-session waitForTurnEnd inside
+ * agent_output. The new tools handle multi-session fan-in
+ * and external-client retrigger without burning polling tokens.
+ */
+
+/**
+ * Event kind a session wait can target. Mirrors the `session_monitor`
+ * `event` parameter. `turn-end` also matches `awaiting-input` (both
+ * signal end-of-turn), matching the MCP tool's semantics.
+ */
+type SessionWaitEvent = "turn-end" | "awaiting-input" | "exited" | "any";
+/**
+ * Result of a single-session wait. On a hit, carries the session id, the
+ * matched event (ring-bus form, without the `session:` prefix), the
+ * session's current status, and whether it's awaiting input. On a
+ * timeout, `timedOut: true` and the watched id list.
+ */
+interface SessionWaitResult {
+    timedOut?: boolean;
+    sessionId?: string;
+    event?: string;
+    source?: "ring" | "state" | "bus";
+    awaitingInput?: boolean;
+    status?: string;
+    turnsCompleted?: number;
+    sessionIds?: string[];
+    since?: number;
+    /** Structured awaiting-input question (harness-parity). Surface on
+     *  turn-end / awaiting-input matches so callers (MCP session_monitor +
+     *  REST /sessions/:id/wait) can read the question without a separate
+     *  transcript fetch. Mirrors desc.awaitingQuestion / ev.question. */
+    question?: SessionAwaitingQuestion;
+}
+/**
+ * Block until one of the listed sessions fires a matching lifecycle event
+ * (turn-end / awaiting-input / exited / any), or until `timeoutMs` elapses.
+ *
+ * This is the single-session-capable core that the MCP `session_monitor`
+ * tool and the REST `GET /sessions/:id/wait` route both call. The MCP tool
+ * passes N ids (multiplexed fan-in); the REST route passes exactly one.
+ * The semantics are identical: race-free cursor replay → synchronous
+ * already-in-target-state check → bus long-poll → timeout.
+ *
+ * `since` is an EventRing cursor: when provided, already-emitted matching
+ * events for the watched sessions that occurred after that cursor are
+ * returned immediately (race-free replay) before subscribing to the bus.
+ */
+declare function monitorSessionWait(opts: {
+    registry: SessionsRegistry;
+    sessionEvents: SessionEventBus;
+    eventRing: EventRing;
+    sessionIds: string[];
+    event?: SessionWaitEvent;
+    timeoutMs?: number;
+    since?: number;
+}): Promise<SessionWaitResult>;
+/**
+ * Block until the named policy's status transitions out of the active
+ * `watching` / `queued` / `gating` / `nudging` states — i.e. reaches
+ * `done`, `blocked`, `awaiting-ack`, or `cancelled` — then return the
+ * full PolicyRunState. Returns `{ timedOut: true }` on timeout.
+ *
+ * Hooks into the supervisor's `onSettle` callback (the single reliable
+ * signal — some terminal transitions like `cancel()` / `ack(false)` /
+ * single-session-exit emit no SessionEventBus event). The MCP
+ * `policy_status` tool and the REST `GET /policies/:id/wait` route both
+ * delegate here, so the wait semantics are shared across transports.
+ */
+declare function monitorPolicyWait(opts: {
+    supervisor: CompletionPolicySupervisor;
+    policyId: string;
+    timeoutMs?: number;
+}): Promise<{
+    timedOut: true;
+} | {
+    timedOut: false;
+    state: PolicyRunState;
+}>;
+
 /**
  * @agentproto/runtime — long-running gateway around an agentproto
  * workspace dir.
@@ -1703,18 +2439,18 @@ interface CreateGatewayOptions {
      *  Without this, /sessions still works for raw `argv` spawns. */
     resolveAgentAdapter?: AgentAdapterResolver;
     /** Optional adapter lister — when provided, enables
-     *  `GET /adapters` HTTP route + `list_adapters` MCP tool so UIs
+     *  `GET /adapters` HTTP route + `adapter_list` MCP tool so UIs
      *  can discover what's installed on the host. */
     listAgentAdapters?: AgentAdapterLister;
     /** Optional browser adapter resolver — when provided, enables the
      *  `start_browser` MCP tool (launches Camofox / Bureau / Chromium). */
     resolveBrowserAdapter?: BrowserAdapterResolver;
     /** Optional browser adapter lister — when provided, enables the
-     *  `list_adapter_browsers` MCP tool. */
+     *  `browser_adapter_list` MCP tool. */
     listBrowserAdapters?: BrowserAdapterLister;
     /** Optional PTY factory (node-pty wrapper, typically from the cli
      *  layer's `loadNodePtyFactory()`). When provided, enables
-     *  `POST /sessions/terminal`, the `start_terminal_session` MCP
+     *  `POST /sessions/terminal`, the `terminal_start` MCP
      *  tool family, and the `/sessions/:id/pty` WebSocket. Without it,
      *  those routes return 501 / the MCP tools aren't registered. */
     spawnPty?: PtyFactory;
@@ -1731,6 +2467,30 @@ interface CreateGatewayOptions {
     /** When true, drop the localhost-wildcard defaults — only the
      *  explicit `allowedOrigins` list is honoured. */
     strictOrigins?: boolean;
+    /**
+     * Opt-in deferred/lazy MCP tool loading (harness-parity item 3, see
+     * `deferred-tools.ts`). When set, every root-gateway tool outside
+     * `alwaysOn` registers but starts disabled — excluded from the first
+     * `tools/list` — until the always-on `tool_search` meta-tool pulls it
+     * in by keyword. Omitted (default) → every tool is eagerly enabled,
+     * identical to pre-existing behaviour. Does not affect the scoped
+     * `/mcp/orchestrator` sub-gateway, which already exposes a small
+     * curated allowlist (`DEFAULT_ORCHESTRATOR_TOOLS`).
+     */
+    deferredTools?: {
+        alwaysOn?: readonly string[];
+    };
+    /**
+     * Optional sandbox provider resolver — overrides the sandbox family's
+     * default resolver (built-ins + `@agentproto/sandbox-<slug>` dynamic
+     * import) used by `list_sandbox_providers` / `setup_sandbox_provider`
+     * AND `agent_start.sandbox`. Mirrors `resolveAgentAdapter`'s injection
+     * shape.
+     */
+    resolveSandboxProvider?: SandboxProviderResolver;
+    /** Optional sandbox provider lister — mirrors `listAgentAdapters`.
+     *  Overrides the default catalog-driven lister behind `list_sandbox_providers`. */
+    listSandboxProviders?: SandboxProviderLister;
 }
 interface GatewayHandle {
     url: string;
@@ -1774,4 +2534,4 @@ interface GatewayHandle {
  */
 declare function createGateway(opts: CreateGatewayOptions): Promise<GatewayHandle>;
 
-export { type AdapterListEntry, type AgentAdapterLister, type AgentAdapterResolver, type AgentSessionLike, type AgentStreamEvent, type BrowserAdapterHandle, type BrowserAdapterInfo, type BrowserAdapterLister, type BrowserAdapterResolver, BuildHeartbeatAgent, type CreateGatewayOptions, DEFAULT_ORCHESTRATOR_TOOLS, type GatewayHandle, type InboundWatcher, type OrchestratorGatewayDeps, type OrchestratorInjection, type OrchestratorInjector, type OrchestratorInjectorDeps, type OrchestratorMcpServerFactory, type OrchestratorScope, type RegisterBrowserInput, type RegisterSessionInput, type RuntimeMeta, type ScopeTokenRegistry, type SessionDescriptor, type SessionKind, type SessionStatus, type SessionsRegistry, type SpawnAgentInput, type SpawnSessionInput, type TunnelDescriptor, type TunnelProvider, type TunnelStatus, type WatcherDescriptor, type WatcherStartInput, WorkspaceFs, createGateway, createOrchestratorInjector, createOrchestratorMcpServerFactory, createScopeTokenRegistry, daemonRegistryDir, makeBrowserAdapterLister, narrowOrchestratorTools, readDaemonRegistry, readRuntimeMeta, sweepStaleDaemonRegistry, sweepStaleRuntimeMetas, unlinkDaemonRegistryEntry, unlinkRuntimeMeta, writeDaemonRegistryEntry };
+export { type AdapterListEntry, type AgentAdapterLister, type AgentAdapterResolver, type AgentSessionLike, type AgentStreamEvent, type AttachPolicyInput, type BrowserAdapterHandle, type BrowserAdapterInfo, type BrowserAdapterLister, type BrowserAdapterResolver, BuildHeartbeatAgent, type CommitSpec, type CompletionPolicySupervisor, type CreateGatewayOptions, DEFAULT_ORCHESTRATOR_TOOLS, type DeclaredAdapterPreset, type GateSpec, type GatewayHandle, type InboundWatcher, type JudgeGateSpec, type McpCredentialDeps, type OnFailSpec, type OrchestratorGatewayDeps, type OrchestratorInjection, type OrchestratorInjector, type OrchestratorInjectorDeps, type OrchestratorMcpServerFactory, type OrchestratorScope, type PolicyRunState, type PolicyRunStatus, type PresetInfo, type PricingResolver, type RegisterBrowserInput, type RegisterSessionInput, type RuntimeMeta, type SandboxAdapterInfo, type SandboxProviderCapabilities, type SandboxProviderHandle, type SandboxProviderLister, type SandboxProviderResolver, type ScopeTokenRegistry, type SessionDescriptor, type SessionKind, type SessionObserver, type SessionStatus, type SessionUsage, type SessionWaitEvent, type SessionWaitResult, type SessionsRegistry, type ShellGateSpec, type SpawnAgentInput, type SpawnSessionInput, type TokenPricing, type TunnelDescriptor, type TunnelProvider, type TunnelStatus, type UsageComputeInput, type UsageSource, type WatcherDescriptor, type WatcherStartInput, WorkspaceFs, composeSessionObservers, createFileStepCache, createGateway, createOrchestratorInjector, createOrchestratorMcpServerFactory, createScopeTokenRegistry, daemonRegistryDir, declaredPresetToProviderPreset, deriveSessionUsage, formatToolCall, formatToolResult, getMcpCredentialDeps, listPresets, makeBrowserAdapterLister, monitorPolicyWait, monitorSessionWait, narrowOrchestratorTools, projectSessionUsage, readDaemonRegistry, readRuntimeMeta, setMcpCredentialDeps, sweepStaleDaemonRegistry, sweepStaleRuntimeMetas, unlinkDaemonRegistryEntry, unlinkRuntimeMeta, writeDaemonRegistryEntry };