@agentproto/runtime 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -1,15 +1,136 @@
 import { DoctypeSpec } from '@agentproto/manifest';
 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 { AcpPermissionResolution, AcpMcpServer } from '@agentproto/acp';
 import { ChildProcess } from 'node:child_process';
+import { R as ResolvedAuthSpec, D as DeclaredAdapterOption, A as AdapterAuthDescriptor } from './spawn-defaults-DAbADRd4.js';
+export { a as AuthEcho, b as AuthResolutionError, C as CredentialSource, c as DefaultsAdapterAuthConfig, d as DefaultsAdapterConfig, e as ResolvedSpawnAuthMaterial, f as ResolvedSpawnDefaults, S as SpawnDefaultsConfig, g as credentialFingerprint, n as normalizeSkillsOption, r as resolveAuthSpec, h as resolveSpawnDefaults } from './spawn-defaults-DAbADRd4.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 { FrameSink, E2eFrameSink } from '@agentproto/acp/tunnel';
+import { DaemonIdentity } from '@agentproto/secrets/identity';
 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';
+export { PROVIDER_ENV_VARS, ProviderEntry, ProvidersFile, getProviderKey, injectProviderKeysIntoEnv, loadProviders, providerEnvVar, providersPath, removeProviderKey, setProviderKey } from '@agentproto/providers-store';
+import '@agentproto/model-catalog';
+
+/**
+ * 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
@@ -20,7 +141,7 @@ export { PROVIDER_ENV_VARS, ProviderEntry, ProvidersFile, injectProviderKeysInto
  * (fire-and-forget HTTP), RoutineRunner (state machine fan-in),
  * 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" | "cron:fired" | "cron:succeeded" | "cron:failed";
+type SessionEventType = "session:turn-end" | "session:awaiting-input" | "session:permission-request" | "session:permission-resolved" | "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
@@ -51,6 +172,16 @@ interface SessionTurnEndEvent {
      * Absent for drivers that don't report a reason.
      */
     reason?: string;
+    /**
+     * True when the turn completed normally but produced ZERO assistant
+     * output AND zero tool calls (and wasn't awaiting input) — a silent
+     * no-op. Grok via hermes/OpenRouter, and any invalid/rejected model id,
+     * complete a turn this way: `turnsCompleted` bumps, `$0` cost, empty
+     * transcript. Surfaced so an orchestrator can flag it instead of
+     * treating a green turn-end as real progress. Absent (not `false`) on
+     * a normal, productive turn.
+     */
+    empty?: boolean;
 }
 interface SessionAwaitingInputEvent {
     type: "session:awaiting-input";
@@ -59,6 +190,34 @@ interface SessionAwaitingInputEvent {
     ts: string;
     question?: SessionAwaitingQuestion;
 }
+/**
+ * Emitted when a permission-hold session parks a `session/request_permission`
+ * (see the pending-permissions inbox in sessions.ts). `permissionId` is the
+ * stable id `permissions_respond` / `POST /permissions/:id` resolve it with.
+ */
+interface SessionPermissionRequestEvent {
+    type: "session:permission-request";
+    sessionId: string;
+    permissionId: string;
+    toolName?: string;
+    text: string;
+    label?: string;
+    ts: string;
+}
+/**
+ * Emitted when a parked permission is resolved — by an inbox
+ * approve/deny, or auto-`cancelled` when the session is torn down while the
+ * request is still pending.
+ */
+interface SessionPermissionResolvedEvent {
+    type: "session:permission-resolved";
+    sessionId: string;
+    permissionId: string;
+    decision: "approve" | "deny" | "cancelled";
+    optionId?: string;
+    label?: string;
+    ts: string;
+}
 interface SessionExitedEvent {
     type: "session:exited";
     sessionId: string;
@@ -66,6 +225,12 @@ interface SessionExitedEvent {
     status: "exited" | "killed" | "error";
     label?: string;
     ts: string;
+    /** Mirrors `SessionDescriptor.endedReason` — set when this exit was the
+     *  daemon dying underneath the session (crash-discovered-at-boot or a
+     *  forced shutdown kill), not an operator targeting it. Lets a watcher
+     *  (completion-policy supervisor, `session_monitor`) tell "my agent died
+     *  because the daemon did" apart from a deliberate kill. Absent otherwise. */
+    reason?: "daemon-restart";
 }
 /** Emitted when command_execute finishes. commandId matches the id
  *  returned by the command_execute MCP tool. */
@@ -140,7 +305,7 @@ interface CronFailedEvent {
     error: string;
     ts: string;
 }
-type SessionEvent = SessionTurnEndEvent | SessionAwaitingInputEvent | SessionExitedEvent | SessionCommandDoneEvent | PolicyPassedEvent | PolicyFailedEvent | PolicyCommitReadyEvent | PolicyCommittedEvent | CronFiredEvent | CronSucceededEvent | CronFailedEvent;
+type SessionEvent = SessionTurnEndEvent | SessionAwaitingInputEvent | SessionPermissionRequestEvent | SessionPermissionResolvedEvent | 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. */
@@ -152,26 +317,40 @@ interface SessionEventBus {
 }
 
 /**
- * Sessions registry — tracks long-lived child processes spawned by
- * the agentproto daemon (terminals, agent CLIs, custom commands).
- *
- * 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.
+ * 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.
  *
- * 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
@@ -189,6 +368,13 @@ interface AgentSessionLike {
     pid?: number;
     send(message: unknown): AsyncIterable<AgentStreamEvent>;
     cancel(): Promise<void>;
+    /** Resolve a permission request the driver parked in permission-hold mode
+     *  (see the pending-permissions inbox below). `requestId` is the driver's
+     *  own stable id, surfaced on the `agent-prompt` event's `toolCallId`.
+     *  Returns true when a matching parked request was resolved. Absent for
+     *  drivers that don't model held permissions (sandbox proxy, future
+     *  transports). */
+    respondPermission?(requestId: string, resolution: AcpPermissionResolution): boolean | Promise<boolean>;
     close(): Promise<void>;
 }
 /**
@@ -227,6 +413,11 @@ interface AgentStreamEvent {
     toolName?: string;
     /** Tool-call input, e.g. an ACP `tool_call`'s `arguments` — see @agentproto/acp's `StreamEvent`. */
     arguments?: unknown;
+    /** True when a "tool-call" event ENRICHES one already announced under the
+     *  same `toolCallId` (the agent knew the input only after announcing the
+     *  call) rather than announcing a new one — see @agentproto/acp's
+     *  `StreamEvent`. Consumers merge by toolCallId; it is not a second call. */
+    isUpdate?: boolean;
     /** Tool-call output, e.g. an ACP `tool_call_update`'s `result` — see @agentproto/acp's `StreamEvent`. */
     result?: unknown;
     isError?: boolean;
@@ -260,9 +451,28 @@ interface AgentStreamEvent {
         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";
+/**
+ * The billing-auth resolver's OBSERVABLE echo, recorded on a session
+ * descriptor. `mode` + `fingerprint` are always present when recorded (a
+ * credential resolved); `provider` / `credentialSource` / `setEnv` are the
+ * multi-provider resolver's additions (DECISION 9③/10②) — optional for
+ * back-compat with descriptors from before that resolver shipped.
+ */
+interface SessionAuthEcho {
+    mode: "subscription" | "api-key";
+    fingerprint: string;
+    provider?: string;
+    credentialSource?: "explicit-config" | "providers-store" | "none";
+    setEnv?: string;
+}
 interface SessionDescriptor {
     id: string;
     kind: SessionKind;
@@ -275,6 +485,16 @@ interface SessionDescriptor {
     startedAt: string;
     endedAt?: string;
     exitCode?: number;
+    /** Set alongside `status: "killed"` when the session ended NOT because an
+     *  operator targeted it (`kill()`) but because the daemon process it lived
+     *  in went away out from under it — a hard crash discovered at next boot
+     *  (`loadHistorySnapshot`'s wasAlive reclassification), or a graceful
+     *  shutdown/restart that force-kills whatever's still busy
+     *  (`shutdownImpl`). Absent for every other terminal path (operator kill,
+     *  natural exit, turn error) — the session's own fault, or at least not
+     *  the daemon's. Lets the UI show "crashed with the daemon" instead of a
+     *  bare "killed" that reads as deliberate. */
+    endedReason?: "daemon-restart";
     /** Last time anything was written to stdout/stderr. Lets the UI
      *  spot stuck sessions ("running for 2h, last output 12min ago"). */
     lastOutputAt?: string;
@@ -315,6 +535,25 @@ interface SessionDescriptor {
     adapterSlug?: string;
     /** The model the session was requested to run (echoed back at spawn). */
     model?: string;
+    /**
+     * Deterministic billing-auth mode + a non-secret credential fingerprint,
+     * recorded at spawn time for adapters that resolved an explicit
+     * credential (today: claude-code — see `AgentCliAuth.modes` in
+     * `@agentproto/driver-agent-cli`). The "verifiability" answer to "what
+     * was used": `mode` is the resolved `"subscription" | "api-key"`;
+     * `fingerprint` is `credentialFingerprint(mode, credential)` — e.g.
+     * `"subscription · sk-ant-oat…3f9c"` — NEVER the raw credential. Absent
+     * when no credential resolved (every adapter besides claude-code, in
+     * practice) or for a sandboxed spawn (the box's own daemon resolves its
+     * own credential independently). Surfaced in `agentproto sessions
+     * --watch`'s DETAIL pane and `agent_sessions_list`.
+     *
+     * Carries the resolver's OBSERVABLE echo (DECISION 9③/10②): `provider`,
+     * `credentialSource`, and the `setEnv` actually set — so a verifier checks
+     * the RESOLUTION, not the model's self-report. These are optional for
+     * back-compat with descriptors persisted before the multi-provider resolver.
+     */
+    auth?: SessionAuthEcho;
     /** Cumulative estimated USD cost of the session — best-effort, refreshed
      *  on each turn-end from the adapter's usage reader (e.g. hermes reads its
      *  state.db). Absent for adapters with no usage source. */
@@ -322,6 +561,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
@@ -362,6 +611,14 @@ interface SessionDescriptor {
      * drivers that don't report structured prompts. Cleared alongside
      * `awaitingInput` on the next turn start. */
     awaitingQuestion?: SessionAwaitingQuestion;
+    /** True while this session (spawned in permission-hold mode) has at least
+     *  one permission request parked in the inbox awaiting a human/orchestrator
+     *  decision. Distinct from `awaitingInput` (a conversational question) — a
+     *  held permission is resolved via `permissions_respond` / `agentproto
+     *  permissions approve|deny`, not a normal prompt. Set when a request is
+     *  registered, cleared when the last pending one for this session resolves.
+     *  Absent (never `false`) for sessions with no held permissions. */
+    awaitingPermission?: boolean;
     /** Count of turns that have fully completed (turn-end emitted) on this
      *  session. Lets `session_monitor` fast-return for a session that already
      *  finished its turn before the wait subscribed — a fast turn that ends
@@ -374,6 +631,21 @@ interface SessionDescriptor {
      *  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; released (see `releaseBlockedOn`) on the MATCHING
+     *  tool-result, on `error` (a failing tool never emits a result), on the
+     *  next assistant `text-delta` (the model has the floor, so nothing is
+     *  pending), at turn start, and in the turn's finally. A claim about the
+     *  present tense — anything that disproves it must clear it. */
+    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`
@@ -387,6 +659,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. */
@@ -395,7 +678,63 @@ 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";
 }
+/**
+ * A `session/request_permission` request parked by a permission-hold session,
+ * awaiting a human/orchestrator decision through the cross-session inbox
+ * (`permissions_list` / `permissions_respond`, `GET /permissions` /
+ * `POST /permissions/:id`, `agentproto permissions ls|approve|deny`).
+ */
+interface PendingPermission {
+    /** Stable id — the driver's own request id, unique across sessions. Pass to
+     *  `respondPermission`. */
+    id: string;
+    sessionId: string;
+    /** ACP tool-call id the request was raised for (== `id` today; kept distinct
+     *  so a future driver can surface a separate correlation id). */
+    toolCallId: string;
+    /** Tool title/kind the agent is asking permission for, when known. */
+    toolName?: string;
+    /** Human-readable "Allow X?" line. */
+    text: string;
+    /** Options the agent offered (ACP `requestPermission` shape). */
+    options: Array<{
+        optionId: string;
+        name?: string;
+        kind?: string;
+    }>;
+    /** ISO timestamp the request was parked. */
+    requestedAt: string;
+}
+/** How a caller resolves a pending permission — an explicit `optionId` wins
+ *  over the `decision`→option mapping (approve → an allow-flavored option,
+ *  deny → a reject-flavored option). `scope: "always"` prefers an
+ *  allow-always option when the request offers one. */
+interface PermissionRespondInput {
+    decision: "approve" | "deny";
+    optionId?: string;
+    scope?: "once" | "always";
+}
+type PermissionRespondResult = {
+    ok: true;
+    permission: PendingPermission;
+    decision: "approve" | "deny";
+    optionId?: string;
+} | {
+    ok: false;
+    error: "not_found" | "session_gone" | "no_matching_option" | "unsupported";
+    message: string;
+};
 interface SessionsRegistry {
     spawn(input: SpawnSessionInput): SessionDescriptor;
     /** Adopt a ChildProcess that was spawned outside the registry —
@@ -417,17 +756,47 @@ 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, dead (exited/killed/
-     *  error and unresumable — `SessionNotAliveError`), or busy
+    /** Send a follow-up turn to a live agent session and AWAIT it. Throws
+     *  when the 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>;
+     *  line emitter so /stream consumers see them as they arrive.
+     *
+     *  `opts.interrupt` behaves exactly as it does on `enqueuePrompt`:
+     *  a mid-turn session has its in-flight turn cancelled and settled
+     *  before admission, so this prompt redirects the SAME live session
+     *  instead of hitting the busy rejection. Ignored (identical to the
+     *  default) when the session is idle. Omitted or `false` reproduces
+     *  the previous mid-turn rejection byte-for-byte. */
+    sendPrompt(id: string, message: unknown, opts?: {
+        interrupt?: boolean;
+    }): Promise<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
@@ -437,8 +806,18 @@ interface SessionsRegistry {
      *  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. */
-    enqueuePrompt(id: string, message: unknown): Promise<void>;
+     *  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
@@ -452,6 +831,14 @@ interface SessionsRegistry {
      *  Initial backfill: synchronously invokes `onLine` once for each
      *  line currently in the ring buffer so attaches show context. */
     attach(id: string, onLine: (line: string, stream: "stdout" | "stderr") => void): (() => void) | null;
+    /** Subscribe to a session's structured events.jsonl records as they're
+     *  written — the live-push half of `GET /sessions/:id/events/stream`'s
+     *  replay-then-subscribe handoff. Thin passthrough to the transcript
+     *  writer's own `subscribe` (see transcript-writer.ts for the exactly-
+     *  once contract this enables); no backfill, no existence check — a
+     *  session id with no writer state simply never calls back. Returns an
+     *  unsubscribe fn. */
+    subscribeToRecords(id: string, onRecord: (record: Record<string, unknown>) => void): () => void;
     /** Subscribe to a PTY session's byte stream. Returns a control
      *  handle (write/resize/detach) and null when the session is
      *  missing or not a PTY kind. Replays the ring buffer
@@ -483,6 +870,17 @@ interface SessionsRegistry {
      *  tail. Returns null when the session is missing or not a PTY. */
     readTerminalOutput(id: string, lastBytes?: number): Buffer | null;
     kill(id: string, signal?: NodeJS.Signals): boolean;
+    /** List permission requests currently parked in the pending-permissions
+     *  inbox across all permission-hold sessions, newest last. Optionally
+     *  filtered to one session. */
+    listPendingPermissions(filter?: {
+        sessionId?: string;
+    }): PendingPermission[];
+    /** Resolve a parked permission by id — maps the decision (or explicit
+     *  optionId) to one of the offered options, resolves the held driver RPC,
+     *  clears the session's awaiting-permission state, and emits
+     *  `session:permission-resolved`. */
+    respondPermission(id: string, input: PermissionRespondInput): Promise<PermissionRespondResult>;
     /** Stop tracking a session (after it exited and the user clicked
      *  "clear"). Doesn't kill — use `kill` first. */
     forget(id: string): boolean;
@@ -555,6 +953,11 @@ interface SpawnAgentInput {
     depth?: number;
     /** Requested model id — recorded on the descriptor for display + echo. */
     model?: string;
+    /** Resolved auth echo (mode + fingerprint + provider/source/setEnv) —
+     *  recorded verbatim onto {@link SessionDescriptor.auth}. See that field's
+     *  doc for the full contract; the caller (`session-spawn.ts`) computes this
+     *  via the billing-auth resolver, never passing the raw credential here. */
+    auth?: SessionAuthEcho;
     /** Hard ceiling on cumulative session cost (USD). When set and the
      *  adapter's usage reader reports a higher cost at a turn-end, the session
      *  is stopped (best-effort, turn-granular — caps continuation, can't abort
@@ -569,6 +972,23 @@ 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";
+    /** True when the driver session was started in permission-hold mode
+     *  (`AgentCliStartOptions.permissionHold`) — its `agent-prompt` events carry
+     *  respondable permission requests. Gates whether the registry registers
+     *  them in the pending-permissions inbox. Default false. */
+    permissionHold?: boolean;
 }
 interface SpawnSessionInput {
     kind: SessionKind;
@@ -612,6 +1032,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
@@ -714,7 +1152,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.
@@ -896,13 +1334,163 @@ 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;
 }
 
+/**
+ * Daemon-side pairing registry (design: DESIGN §3/§4, PLAN deliverable 2).
+ *
+ * Owns everything the daemon needs to be *paired with* over an untrusted
+ * rendezvous:
+ *
+ *   - **Offer store** — in-memory, single-use, expiry-checked one-time tokens
+ *     minted by `pair offer`. A daemon restart voids outstanding offers
+ *     (acceptable + documented). The P1 `verifyOfferToken` predicate plugs in
+ *     here and SPENDS the token on the first successful handshake.
+ *   - **Pairings store** — `~/.agentproto/pairings.json` (0600, atomic write),
+ *     one record per paired client: `{clientPub, name, fingerprint, createdAt,
+ *     lastSeen, pairRoot, rendezvousUrl}`. `pairRoot` is the long-term shared
+ *     secret (`derivePairRoot`) from which reconnect routing tokens derive.
+ *   - **Rendezvous connections** — for a fresh offer, and for every persisted
+ *     pairing on boot (autoconnect), the daemon dials the rendezvous *outbound*
+ *     (`side=daemon&t=<token>`), runs `daemonHandshakeOverSink` with the P1
+ *     crypto, and — on success — serves the spliced, E2E-wrapped channel exactly
+ *     like `serve --connect` serves a tunnel host. The serving path itself is
+ *     injected (`serve`) so this module stays free of pty/adapter concerns and
+ *     the CLI can reuse its `createTunnelServer` config verbatim.
+ *   - **Reconnect epochs** — a persisted pairing's standing connection uses the
+ *     pairing-derived routing token `t' = HKDF(pairRoot, "rv-route"‖epoch)`,
+ *     rotated per UTC day. The daemon parks on BOTH the current and previous
+ *     epoch tokens so a client whose clock straddles midnight still finds it;
+ *     reconnect-with-backoff keeps the standing connection alive.
+ *   - **Revocation** — removing a pairing drops its rendezvous connections and
+ *     stops the daemon parking on its tokens, so it can no longer be reached.
+ *
+ * ## Reconnect authentication (why no stable client key)
+ *
+ * P1's handshake carries only a client *ephemeral* key (regenerated per
+ * handshake) — there is no persistent client identity key, and the PLAN forbids
+ * changing the handshake. So a reconnect authenticates the client by
+ * **possession of the epoch routing token**, which derives from `pairRoot` — a
+ * secret only the paired client and daemon share (it fell out of the original
+ * ECDH). The daemon dials a pairing's epoch token, and on that connection the
+ * `verifyOfferToken` predicate accepts a hello whose offer-token field equals
+ * that same epoch token (constant-time). Token possession ⇒ paired party. The
+ * stored `fingerprint` (of the first handshake's ephemeral key) is a stable
+ * display/revocation handle, not an authentication input.
+ */
+
+declare const PAIRINGS_VERSION: 1;
+/** One persisted pairing. Written verbatim to `pairings.json`. */
+interface PairingRecord {
+    /** The client ephemeral public key from the FIRST handshake (a snapshot —
+     *  reconnects use fresh ephemerals; this is not an auth input). */
+    clientPub: string;
+    /** Human-facing label the client chose on `pair accept`. */
+    name: string;
+    /** `identityFingerprint(clientPub)` from the first handshake — the stable
+     *  display + revocation handle. */
+    fingerprint: string;
+    /** ISO-8601 first-pair timestamp. */
+    createdAt: string;
+    /** ISO-8601 of the most recent successful (re)connect. */
+    lastSeen: string;
+    /** Long-term shared secret (base64), from which epoch routing tokens derive. */
+    pairRoot: string;
+    /** Rendezvous endpoint to reconnect through. */
+    rendezvousUrl: string;
+}
+/** Mode of a served channel — first-contact offer vs. an established reconnect. */
+type PairingChannelMode = "offer" | "reconnect";
+/** Context handed to the injected `serve` when a channel comes up. */
+interface PairingChannelContext {
+    mode: PairingChannelMode;
+    /** Stable pairing fingerprint (present for reconnect; for an offer it's the
+     *  freshly-derived one). */
+    fingerprint: string;
+    /** Client label. */
+    name: string;
+}
+/** Handle to a live served channel — the registry closes it on teardown. */
+interface PairingChannelHandle {
+    close(): Promise<void>;
+}
+interface CreatedOffer {
+    /** The one-time offer token (base64url). */
+    token: string;
+    /** Offer expiry, unix seconds. */
+    exp: number;
+    /** The full `agentproto://pair?…` offer URL. */
+    url: string;
+    /** The daemon's identity fingerprint (shown to the human at accept time). */
+    fingerprint: string;
+    /** The rendezvous the offer routes through. */
+    rendezvousUrl: string;
+    /** True when `rendezvousUrl` is the hosted default — i.e. neither an explicit
+     *  `--rendezvous` nor a configured `pairing.rendezvous` applied, so the offer
+     *  falls back to `HOSTED_RENDEZVOUS_URL`. Surfaced so `pair offer` can flag,
+     *  never silently, that the daemon is relaying through our infrastructure. */
+    rendezvousIsHostedDefault: boolean;
+}
+interface CreateOfferInput {
+    /** Time-to-live in ms. Default 10 minutes. */
+    ttlMs?: number;
+    /** Rendezvous URL override; falls back to the configured default. */
+    rendezvousUrl?: string;
+}
+interface PairingRegistryDeps {
+    /** Lazily load (create on first use) the daemon identity. Kept lazy so a
+     *  daemon that never pairs never writes an identity file. */
+    loadIdentity: () => Promise<DaemonIdentity>;
+    /** Path to `pairings.json`. Defaults to `~/.agentproto/pairings.json`. */
+    pairingsPath?: string;
+    /** Configured rendezvous URL (from `config.pairing.rendezvous`). Three states:
+     *  - `undefined` (key absent) → `createOffer` falls back to the hosted default
+     *    (`HOSTED_RENDEZVOUS_URL`).
+     *  - a non-empty URL → that endpoint is the default for offers.
+     *  - `""` (explicitly empty) → an explicit opt-out: no default applies, so an
+     *    offer without `--rendezvous` fails closed. Wire it through verbatim (do
+     *    not coerce `""` to `undefined`) or the opt-out silently reverts to the
+     *    hosted default. */
+    defaultRendezvousUrl?: string;
+    /** Dial a rendezvous WS and adapt it to a FrameSink. Injected by the CLI
+     *  (uses `ws` + `wrapWebSocket`). Rejects if the dial fails. The `signal`
+     *  aborts on registry shutdown. */
+    dial: (wsUrl: string, signal: AbortSignal) => Promise<FrameSink>;
+    /** Serve the E2E-wrapped channel (the CLI builds `createTunnelServer` over
+     *  it with the same config `serve --connect` uses). */
+    serve: (sink: E2eFrameSink, ctx: PairingChannelContext) => PairingChannelHandle;
+    /** Injectable clock (ms). Defaults to Date.now. */
+    now?: () => number;
+    /** Diagnostic log sink. */
+    log?: (line: string) => void;
+    /** Reconnect backoff floor / ceiling (ms). Defaults 1s / 30s. */
+    reconnectMinMs?: number;
+    reconnectMaxMs?: number;
+    /** How long a parked daemon socket waits for a client hello before recycling
+     *  the connection. Kept just under the broker's park timeout. Default 110s. */
+    handshakeTimeoutMs?: number;
+}
+interface PairingRegistry {
+    /** Mint a one-time offer + start dialing the rendezvous for it. */
+    createOffer(input?: CreateOfferInput): Promise<CreatedOffer>;
+    /** All persisted pairings (copies). Loads `pairings.json` on first call. */
+    list(): Promise<PairingRecord[]>;
+    /** Drop a pairing by fingerprint or name; stops its rendezvous connections.
+     *  Returns false when nothing matched. */
+    revoke(idOrName: string): Promise<boolean>;
+    /** Start standing reconnect connections for every persisted pairing. Call
+     *  after the gateway is up (so the injected `serve` can reach it). */
+    startAutoconnect(): Promise<void>;
+    /** Tear down every offer + reconnect connection and served channel. */
+    shutdown(): Promise<void>;
+}
+declare function createPairingRegistry(deps: PairingRegistryDeps): PairingRegistry;
+
 /**
  * Fire-and-forget webhook notifier for session lifecycle events.
  *
@@ -1301,6 +1889,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.
@@ -1329,6 +1929,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`. */
@@ -1447,6 +2050,11 @@ 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
@@ -1456,6 +2064,95 @@ type OrchestratorInjector = (opts?: {
  */
 declare function createOrchestratorInjector(deps: OrchestratorInjectorDeps): OrchestratorInjector;
 
+/**
+ * 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`).
+ *
+ * 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)
+ *
+ * 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`.
+ *
+ * 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
@@ -1489,6 +2186,17 @@ type AgentAdapterResolver = (slug: string) => Promise<{
          * 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).
@@ -1511,6 +2219,17 @@ type AgentAdapterResolver = (slug: string) => Promise<{
          *  handler, POST /sessions/agent) wires this to pulse
          *  `SessionDescriptor.lastActivityAt` via `registry.pulseActivity(id)`. */
         onActivity?: () => void;
+        /** Start the session in permission-hold mode — forwarded to the driver's
+         *  `runtime.start({ permissionHold })` so each ACP permission request is
+         *  surfaced + parked in the daemon's inbox instead of auto-answered.
+         *  Adapters/arms with no permission surface ignore it. Default false. */
+        permissionHold?: boolean;
+        /** FULLY-RESOLVED billing-auth spec forwarded from `agent_start` to the
+         *  driver's `runtime.start({ auth })`, computed by the runtime's
+         *  `resolveAuthSpec` (provider, ordered mode, setEnv/scrub, credential
+         *  source all pre-decided). The driver applies it mechanically. Absent
+         *  when the resolver produced no spec (ambient). */
+        auth?: ResolvedAuthSpec;
     }): Promise<AgentSessionLike>;
     /** Display label for the descriptor's `command` field. */
     commandPreview?: string;
@@ -1520,7 +2239,39 @@ 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[];
+    /** Billing-auth descriptor projected from the adapter manifest
+     *  (`provider` / `authEnforce` / `authSubscription`) — the sole input the
+     *  runtime's `resolveAuthSpec` reads about the adapter's auth capability
+     *  (keeping the catalog coupling in the runtime, the driver mechanical).
+     *  Omitted ⇒ ambient (no credential injection). */
+    authDescriptor?: AdapterAuthDescriptor;
+    /** Adapter's default model id (`models.default`) — lets the resolver derive
+     *  a provider for a by-model spawn that omitted `model`. */
+    defaultModel?: string;
 } | 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
@@ -1535,6 +2286,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 {
@@ -1621,7 +2376,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
@@ -1680,6 +2435,137 @@ declare function formatToolCall(toolName: string, args: unknown): string;
  */
 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;
+
+/**
+ * MCP tools that drive the pairing registry — the daemon's "let a client pair
+ * with me over an untrusted rendezvous" surface (design: DESIGN §6).
+ *
+ * Three tools, mirroring the CLI verbs:
+ *
+ *   pair_offer   — mint a one-time offer + start dialing the rendezvous; returns
+ *                  the `agentproto://pair?…` URL, fingerprint, and expiry.
+ *   pair_list    — list persisted pairings (name, fingerprint, lastSeen).
+ *   pair_revoke  — drop a pairing by fingerprint or name; stops its rendezvous
+ *                  connections so it can no longer reconnect.
+ *
+ * Registered beside `remote_*` (remote-tools.ts) — same closure-rebind pattern;
+ * the registry singleton lives on the gateway.
+ */
+
+interface RegisterPairingToolsOptions {
+    registry: PairingRegistry;
+}
+declare function registerPairingTools(server: McpServer, opts: RegisterPairingToolsOptions): void;
+
+/**
+ * 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?: {
@@ -1984,6 +2870,27 @@ interface CreateGatewayOptions {
     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;
+    /**
+     * Optional E2E pairing registry (see `createPairingRegistry`). When wired,
+     * the gateway mounts the `/pairings/*` REST routes and the `pair_*` MCP
+     * tools, and exposes the registry on the handle. The CLI builds it (injecting
+     * the ws `dial` + a `createTunnelServer`-backed `serve`) and passes it here so
+     * the runtime stays free of pty/adapter concerns while the pairing surface is
+     * reachable over MCP + HTTP. Autoconnect is the caller's to start (after this
+     * returns) so the injected `serve` can capture the finished gateway.
+     */
+    pairingRegistry?: PairingRegistry;
 }
 interface GatewayHandle {
     url: string;
@@ -1998,6 +2905,10 @@ interface GatewayHandle {
      *  local port. Exposed so embedding hosts can open tunnels
      *  programmatically without going through the HTTP/MCP surface. */
     tunnels: TunnelRegistry;
+    /** E2E pairing registry, when one was wired via
+     *  `CreateGatewayOptions.pairingRegistry`. Undefined otherwise. Exposed so
+     *  the CLI can `startAutoconnect()` after boot and `shutdown()` it. */
+    pairing?: PairingRegistry;
     /** Per-boot bearer token required on mutating /sessions/* routes
      *  + WS PTY upgrades. Exposed so an embedding host (e.g. the CLI
      *  shell that hosts the gateway in-process) can pass it to child
@@ -2027,4 +2938,4 @@ interface GatewayHandle {
  */
 declare function createGateway(opts: CreateGatewayOptions): Promise<GatewayHandle>;
 
-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 GateSpec, type GatewayHandle, type InboundWatcher, type JudgeGateSpec, type OnFailSpec, type OrchestratorGatewayDeps, type OrchestratorInjection, type OrchestratorInjector, type OrchestratorInjectorDeps, type OrchestratorMcpServerFactory, type OrchestratorScope, type PolicyRunState, type PolicyRunStatus, type RegisterBrowserInput, type RegisterSessionInput, type RuntimeMeta, type ScopeTokenRegistry, type SessionDescriptor, type SessionKind, type SessionStatus, type SessionWaitEvent, type SessionWaitResult, type SessionsRegistry, type ShellGateSpec, type SpawnAgentInput, type SpawnSessionInput, type TunnelDescriptor, type TunnelProvider, type TunnelStatus, type WatcherDescriptor, type WatcherStartInput, WorkspaceFs, createFileStepCache, createGateway, createOrchestratorInjector, createOrchestratorMcpServerFactory, createScopeTokenRegistry, daemonRegistryDir, formatToolCall, formatToolResult, makeBrowserAdapterLister, monitorPolicyWait, monitorSessionWait, narrowOrchestratorTools, readDaemonRegistry, readRuntimeMeta, sweepStaleDaemonRegistry, sweepStaleRuntimeMetas, unlinkDaemonRegistryEntry, unlinkRuntimeMeta, writeDaemonRegistryEntry };
+export { AdapterAuthDescriptor, 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, type CreateOfferInput, type CreatedOffer, DEFAULT_ORCHESTRATOR_TOOLS, DeclaredAdapterOption, 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, PAIRINGS_VERSION, type PairingChannelContext, type PairingChannelHandle, type PairingChannelMode, type PairingRecord, type PairingRegistry, type PairingRegistryDeps, type PendingPermission, type PermissionRespondInput, type PermissionRespondResult, type PolicyRunState, type PolicyRunStatus, type PresetInfo, type PricingResolver, type RegisterBrowserInput, type RegisterPairingToolsOptions, type RegisterSessionInput, ResolvedAuthSpec, 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, createPairingRegistry, createScopeTokenRegistry, daemonRegistryDir, declaredPresetToProviderPreset, deriveSessionUsage, formatToolCall, formatToolResult, getMcpCredentialDeps, listPresets, makeBrowserAdapterLister, monitorPolicyWait, monitorSessionWait, narrowOrchestratorTools, projectSessionUsage, readDaemonRegistry, readRuntimeMeta, registerPairingTools, setMcpCredentialDeps, sweepStaleDaemonRegistry, sweepStaleRuntimeMetas, unlinkDaemonRegistryEntry, unlinkRuntimeMeta, writeDaemonRegistryEntry };