@mono-agent/agent-runtime 0.20.11 → 0.21.0

package/src/ai/runtime/session-liveness.js

@@ -1,8 +1,8 @@
 // @ts-check
 // Synchronous session-liveness primitives over a createSessionRegistry.
 //
-// A provider bridge owns session DURABILITY (pi keeps a Session transcript,
-// codex keeps an app-server thread); this kernel layer owns session LIVENESS —
+// The Pi bridge owns session DURABILITY by keeping a Session transcript; this
+// kernel layer owns session LIVENESS —
 // the concurrency claim that keeps two turns from driving one session at once.
 // The primitives here are deliberately SYNCHRONOUS: each does its registry
 // get -> check -> set in a single await-free span, so the "busy claim must be
@@ -11,8 +11,7 @@
 //
 // The registry stays the storage + idle-TTL + dispose fan-out layer (its
 // exports are unchanged, worklab-compatible); liveness only adds the claim /
-// reserve / release / adoptIfPresent seam that pi-native's session-lifecycle and
-// codex-app both consume.
+// reserve / release / adoptIfPresent seam that Pi's session lifecycle consumes.
 
 /**
  * @typedef {object} SessionRegistryLike

package/src/ai/runtime/sessions.js

@@ -1,8 +1,7 @@
 // Provider session registries.
 //
-// Bridges that support continuous provider sessions (codex-app keeps the
-// app-server subprocess + thread alive, pi-native keeps a pi Session
-// transcript) register their live sessions here, keyed by provider session id.
+// Pi keeps each continuous provider session as a live Session transcript and
+// registers it here under the provider session id.
 // The host
 // owns session lifetime policy (which conversation maps to which session,
 // when to resume, when to retire); these registries only make sure nothing
@@ -13,8 +12,8 @@
 // `createSessionRegistry` instances self-register in a module-level set so
 // the runtime surface can expose `syncSession(id)` / `refreshSession(id)` /
 // `disposeSession(id)` / `disposeAllSessions()`
-// without knowing which bridge owns the id. Provider session ids are unique
-// across bridges (codex thread ids, pi uuids), so fan-out dispose is safe.
+// without coupling the host-facing lifecycle surface to Pi's transcript
+// implementation. Pi session UUIDs are unique, so fan-out dispose is safe.
 
 const DEFAULT_IDLE_TIMEOUT_MS = 30 * 60 * 1000;
 

package/src/ai/runtime/tool-policy.js

@@ -2,8 +2,6 @@
 
 /** @type {"projected"} */
 export const TOOL_POLICY_PROJECTED = "projected";
-/** @type {"allow_all_only"} */
-export const TOOL_POLICY_ALLOW_ALL_ONLY = "allow_all_only";
 
 /**
  * True when a tool policy is semantically unrestricted.

package/src/ai/tool-lifecycle.js

@@ -15,9 +15,9 @@ const HOST_HISTORY_METADATA = Symbol("mono-agent.host-tool-history");
 const HOST_TOOL_LIFECYCLE_METADATA = Symbol("mono-agent.host-tool-lifecycle");
 
 /**
- * @param {{sink?: (event: any) => Promise<any>, onObserve?: (event: any) => void, onEvent?: (event: any) => void, abortSignal?: AbortSignal}} options
+ * @param {{sink?: (event: any) => Promise<any>, onObserve?: (event: any) => void, onLifecycleAdmitted?: (event: any) => void, onEvent?: (event: any) => void, abortSignal?: AbortSignal}} options
  */
-export function createToolLifecycleEventGate({ sink, onObserve, onEvent, abortSignal }) {
+export function createToolLifecycleEventGate({ sink, onObserve, onLifecycleAdmitted, onEvent, abortSignal }) {
   /** @type {Promise<void>} */
   let tail = Promise.resolve();
   let pendingDeliveries = 0;
@@ -25,22 +25,30 @@ export function createToolLifecycleEventGate({ sink, onObserve, onEvent, abortSi
   const timing = new Map();
   /** @type {Map<string, any>} */
   const approvals = new Map();
+  const preparedBlocks = new WeakSet();
 
   const emit = (event) => {
     stripProviderLifecycleMetadata(event);
     try { onObserve?.(event); } catch { /* observer callback semantics remain best-effort */ }
+    observeClassification(event, timing, approvals);
     const requiresPersistence = typeof sink === "function" && eventNeedsPersistence(event);
+    // Admission/classification follows native emission, not delayed storage.
+    const writes = requiresPersistence ? prepareEvent(event, { timing, approvals, abortSignal }, preparedBlocks) : [];
+    for (const write of writes) {
+      try { onLifecycleAdmitted?.(write.lifecycle); } catch { /* observers remain best-effort */ }
+    }
     if (!requiresPersistence && pendingDeliveries === 0) {
-      observeClassification(event, timing, approvals);
       try { onEvent?.(event); } catch { /* host callback semantics remain best-effort */ }
       return;
     }
 
     pendingDeliveries += 1;
     const delivery = tail.then(async () => {
-      observeClassification(event, timing, approvals);
       if (requiresPersistence) {
-        await persistEvent(event, sink, { timing, approvals, abortSignal });
+        for (const write of writes) {
+          const persisted = await safePersist(sink, write.lifecycle);
+          try { write.block.history = historyMetadata(persisted, write.state); } catch { /* still settle every admitted write */ }
+        }
       }
       try { onEvent?.(event); } catch { /* host callback semantics remain best-effort */ }
     }).catch((error) => {
@@ -118,32 +126,34 @@ function observeClassification(event, timing, approvals) {
   }
 }
 
-/** @param {any} event @param {(event:any)=>Promise<any>} sink @param {{timing:Map<string,any>,approvals:Map<string,any>,abortSignal?:AbortSignal}} context */
-async function persistEvent(event, sink, context) {
-  if (!record(event) || (event.type !== "assistant" && event.type !== "user")) return;
+/** @param {any} event @param {{timing:Map<string,any>,approvals:Map<string,any>,abortSignal?:AbortSignal}} context @param {WeakSet<object>} preparedBlocks */
+function prepareEvent(event, context, preparedBlocks) {
+  const writes = [];
+  if (!record(event) || (event.type !== "assistant" && event.type !== "user")) return writes;
   const message = event.message;
-  if (!record(message) || !Array.isArray(message.content)) return;
+  if (!record(message) || !Array.isArray(message.content)) return writes;
   for (const block of message.content) {
     if (!record(block)) continue;
     if (event.type === "assistant" && block.type === "tool_use") {
-      if (hostHistoryMetadata(block.history)) continue;
+      if (hostHistoryMetadata(block.history) || preparedBlocks.has(block)) continue;
       if (typeof block.id !== "string" || typeof block.name !== "string") continue;
-      const persisted = await safePersist(sink, {
+      const lifecycle = {
         phase: "invocation",
         toolCallId: block.id,
         toolName: block.name,
         ...(Object.hasOwn(block, "input") ? { arguments: block.input } : {}),
-      });
-      block.history = historyMetadata(persisted, undefined);
+      };
+      preparedBlocks.add(block);
+      writes.push({ block, lifecycle, state: undefined });
       continue;
     }
     if (event.type === "user" && block.type === "tool_result") {
-      if (hostHistoryMetadata(block.history)) continue;
+      if (hostHistoryMetadata(block.history) || preparedBlocks.has(block)) continue;
       const id = typeof block.tool_use_id === "string" ? block.tool_use_id
         : typeof block.tool_call_id === "string" ? block.tool_call_id : undefined;
       if (id === undefined) continue;
       const classified = classifyGenericResult(block, context.timing.get(id), context.approvals.get(id), context.abortSignal);
-      const persisted = await safePersist(sink, {
+      const lifecycle = {
         phase: "result",
         toolCallId: id,
         ...(typeof block.name === "string" ? { toolName: block.name } : {}),
@@ -153,12 +163,14 @@ async function persistEvent(event, sink, context) {
           ? { executionMs: context.timing.get(id).execution_ms }
           : {}),
         artifacts: artifactPaths(block),
-      });
-      block.history = historyMetadata(persisted, classified.state);
+      };
+      preparedBlocks.add(block);
+      writes.push({ block, lifecycle, state: classified.state });
       context.timing.delete(id);
       context.approvals.delete(id);
     }
   }
+  return writes;
 }
 
 /** @param {any} block @param {any} timing @param {any} approval @param {AbortSignal|undefined} abortSignal */
@@ -219,7 +231,9 @@ export function historyMetadata(persisted, terminalStateValue) {
   const metadata = {
     ...(typeof persisted?.recordId === "string" ? { recordId: persisted.recordId } : {}),
     ...(Number.isFinite(Number(persisted?.sequence)) ? { sequence: Number(persisted.sequence) } : {}),
-    persistence: persisted?.persistence === "persisted" ? "persisted" : "failed",
+    persistence: persisted?.persistence === "persisted" || persisted?.persistence === "deferred"
+      ? persisted.persistence
+      : "failed",
     ...(terminalStateValue === undefined ? {} : { terminalState: terminalStateValue }),
     ...(typeof persisted?.truncated === "boolean" ? { truncated: persisted.truncated } : {}),
     ...(Number.isFinite(Number(persisted?.originalBytes)) ? { originalBytes: Number(persisted.originalBytes) } : {}),

package/src/ai/types.js

@@ -8,62 +8,22 @@
 // via `import('./types.js').X` JSDoc syntax from the other seam files, or
 // transitively through the package root's generated declarations.
 //
-// A few fields below use the `"literal" | (string & {})` shape (a "branded
-// string union"). This keeps the known literal values available for
-// IDE/editor autocomplete while still accepting any plain `string`, since
-// hosts validate the real vocabulary at runtime (parseRuntimeModelReference,
-// resolveRuntimeBridge) rather than at the type level — the type only
-// documents the values active runtimes currently produce.
-
 /**
- * @typedef {"claude" | "pi" | "codex" | "opencode" | "acp" | (string & {})} RuntimeSdkId
- * Canonical active runtime id. See ACTIVE_RUNTIME_KINDS (model-refs.js) for
- * the enforced-at-runtime vocabulary.
+ * @typedef {"pi"} RuntimeSdkId
+ * Runtime-result and telemetry label. Model references no longer carry this
+ * field because Pi is the sole runtime bridge.
  */
 
 /**
- * @typedef {"claude" | "claude-code" | "codex-app" | "opencode-app" | "pi" | "acp-stdio" | (string & {})} RuntimeBridgeId
- * Registry bridge id (distinct from RuntimeSdkId: a single sdk can be served
- * by more than one bridge, e.g. sdk "claude" is served by both the "claude"
- * SDK bridge and the "claude-code" CLI bridge). See
- * src/ai/runtime/registry.js's builtinBridgeSpecs.
+ * @typedef {"pi"} RuntimeBridgeId
+ * Registry bridge id. See src/ai/runtime/registry.js's builtinBridgeSpecs.
  */
 
 /**
  * @typedef {Object} RuntimeModelRef
- * @property {RuntimeSdkId} sdk           Canonical active runtime id.
+ * @property {string} provider            Pi provider id.
  * @property {string} model               Provider model id.
- * @property {string} [reference]         Original canonical model reference; always set by
- *                                         parseRuntimeModelReference, but router.js's chain
- *                                         shorthand accepts bare {sdk, model} refs without one.
- * @property {string} [provider]          Pi/OpenCode provider id when sdk === "pi" | "opencode".
- */
-
-/**
- * @typedef {Object} RuntimeNativeSubagentDefinition
- * One caller-defined Claude native `Task` profile. Codex collaboration-agent
- * definitions are owned by Codex and are not represented by this type.
- * @property {string} name
- * @property {string} [displayName]
- * @property {string} [description]
- * @property {string} [helperSystemPrompt]
- * @property {string} [instructions]
- * @property {ReadonlyArray<string>} [allowedTools]
- * @property {ReadonlyArray<string>} [disallowedTools]
- * @property {string | RuntimeModelRef} [modelRef]
- * @property {RuntimeModelRef} [model]
- * @property {string} [effort]
- * @property {Object<string, Object>} [mcpServers]
- * @property {Object} [mcpApps] App-owned exact-connection MCP Apps registry (Pi-native only).
- */
-
-/**
- * @typedef {Object} RuntimeNativeSubagentsOptions
- * Caller-defined native profiles are supported only by the Claude bridges.
- * Codex owns its collaboration agents; use `codexLoadProjectDocs` when those
- * agents should receive repository instructions.
- * @property {"claude"} provider
- * @property {ReadonlyArray<RuntimeNativeSubagentDefinition>} teammates
+ * @property {string} reference           Canonical `<provider>:<model>` reference.
  */
 
 /**
@@ -82,6 +42,8 @@
  *   nested native agent. Informational only; `id` remains the attachment key.
  * @property {number} [costUsd] Priced delegation cost, when the runtime can
  *   attribute it to this subagent.
+ * @property {*} [attribution] Bounded provider-route attribution for the
+ *   completed child run. Consumers must treat it as operator telemetry.
  */
 
 /**
@@ -150,7 +112,7 @@
  * @typedef {Readonly<{
  *   recordId?: string,
  *   sequence?: number,
- *   persistence: "persisted"|"failed",
+ *   persistence: "persisted"|"deferred"|"failed",
  *   truncated?: boolean,
  *   originalBytes?: number,
  *   retainedBytes?: number,
@@ -166,36 +128,11 @@
  * @returns {Promise<RuntimeToolLifecyclePersistence|undefined>}
  */
 
-/** @typedef {"uniform"|"per-route-native"} RuntimeRouteSafetyMode */
-
-/**
- * @typedef {"mono-agent-monotonic"|"disabled"|"mono-agent-srt"|"mono-agent-srt-unsafe-host-fallback"|"provider-native"|"codex-native"|"unsupported"} RuntimeRouteSandboxContract
- * Fixed telemetry vocabulary for a route's sandbox posture. The
- * `mono-agent-srt-unsafe-host-fallback` describes a policy that prefers SRT but
- * explicitly permits host execution if unavailable; it does not claim which
- * branch ran for a particular command.
- */
-
-/**
- * @typedef {"mono-agent-monotonic"|"mono-agent-policy"|"provider-representable"|"exact-allow-all"|"unsupported"} RuntimeRouteToolsContract
- * `exact-allow-all` is a stable telemetry token. It describes an effective
- * unrestricted contract, including mixed allowlists that contain `"*"`;
- * it does not require the literal one-element array `["*"]`.
- */
-
-/**
- * @typedef {Object} RuntimeRouteSafetyContract
- * Bounded, credential-free description of the sandbox/tool contract applied
- * to one fallback route.
- * @property {RuntimeRouteSafetyMode} mode
- * @property {RuntimeRouteSandboxContract} sandbox
- * @property {RuntimeRouteToolsContract} tools
- */
-
 /**
  * @typedef {Object} RuntimeObserver
  * Per-call or host-level observer merged by createObserverHub (ai/observer.js).
  * Loose on purpose: observer.js is not a kernel seam file.
+ * @property {(event: RuntimeToolLifecycleEvent) => void} [recordToolLifecycle] Synchronous admission before queued lifecycle persistence.
  * @property {(event: RuntimeEvent) => (void|Promise<void>)} [onEvent]
  * @property {() => (void|Promise<void>)} [flush]
  */
@@ -254,19 +191,19 @@
  * @typedef {Object} RuntimeRunOptions
  * The options object a host passes to `createRuntime(host).run(systemPrompt, options)`.
  * @property {RuntimeModelRef} model                     Resolved model reference; see parseRuntimeModelReference.
- * @property {"sdk"|"cli"|"acp"} [executionMode]       "sdk" (default), "cli", or "acp"; selects which bridge variant handles the model.
  * @property {string} [sessionId]                         Host conversation/session key for resumable bridges.
  * @property {string} [providerSessionId]                 Provider-owned resume id for resumable bridges.
- * @property {typeof import("@anthropic-ai/claude-agent-sdk").query} [claudeAgentQuery] Advanced programmatic/test seam for the Claude SDK route; omitted runs use the runtime's pinned SDK query implementation.
+ * @property {string} [providerAttributionSessionId]      Host-owned provider attribution continuity key; does not authorize transcript resume.
+ * @property {{runId: string, revision: number}} [sessionRecovery] Host-owned durable recovery opt-in.
  * @property {boolean} [sessionKeepAlive]                 Keep resumable provider state alive after the turn.
  * @property {number} [sessionIdleTimeoutMs]              Idle TTL for resumable provider state.
- * @property {AsyncIterable<{body: string, id?: string, receivedAt?: string, acknowledge?: () => void, reject?: (error?: unknown) => void}>} [liveInput] Stream of in-flight user messages for steering an active run. Providers acknowledge only after accepting a message into the active turn.
+ * @property {AsyncIterable<{body: string, id?: string, receivedAt?: string, logicalOwner?: object, accepted?: (evidence?: {providerEntryId?: string, providerRunId?: string}) => unknown, acknowledge?: (evidence?: {providerEntryId?: string, providerRunId?: string}) => unknown, uncertain?: (details: {reason: "delivery_uncertain", providerEntryId?: string, providerRunId?: string}) => unknown, reject?: (error?: unknown) => unknown}>} [liveInput] Stream of in-flight user messages for steering an active run. Native acceptance, exact transcript consumption, and uncertain delivery are distinct synchronous callbacks; thenables are never awaited as settlement confirmation. An optional opaque logicalOwner object proves that a later same-id value is a fresh callback lease for the first logical owner, not an independent duplicate.
  * @property {ReadonlyArray<*>} [observers]               Per-call observers (see RuntimeObserver) merged with host-level (createRuntime) observers.
  * @property {(event: RuntimeEvent) => void} [onEvent]
+ * @property {boolean} [promptCacheDiagnostics] Emit metadata-only prompt-cache request fingerprints.
  * @property {RuntimeToolLifecycleSink} [toolLifecycleSink] Awaited host-owned incremental lifecycle persistence boundary.
  * @property {ReadonlyArray<Object>} [messages]
  * @property {string} [effort]
- * @property {boolean} [fastMode]
  * @property {string} [cwd]
  * @property {Object<string, Object>} [mcpServers]
  * @property {ReadonlyArray<{name: string, description?: string}>} [skills] Skills disclosed to this run, as `{name, description}`. Non-empty makes `supports_skills` a routing requirement (see router.js), so a chain entry that lacks it is skipped.
@@ -275,46 +212,32 @@
  * @property {ReadonlyArray<string>} [disallowedTools]
  * @property {string} [permissionMode]
  * @property {number} [maxTurns]
+ * @property {number} [providerCheckMaxTokens] Internal provider-check output cap; ordinary callers must omit it.
+ * @property {{env(name: string): Promise<string|undefined>, fileExists(path: string): Promise<boolean>}} [providerCheckAuthContext] Internal provider-check effective auth context; ordinary callers must omit it.
  * @property {Object} [outputSchema]
  * @property {string} [runArtifactDir]
  * @property {AbortSignal} [abortSignal]
+ * @property {(artifact: {filename: string, buffer: Buffer, toolName: string, toolUseId: (string|null)}) => (string|null)} [persistArtifact] Host-owned synchronous artifact writer bound to this run.
  * @property {{schema: 1, values: Readonly<Record<string, string>>, pathPrepend?: readonly string[]}} [toolEnvironment] Host-only environment for Bash, Exec, and nested subagents in this run.
  * @property {import('../agent/sandbox-seam.js').SandboxPolicy} [sandboxPolicy] Per-run sandbox policy; merged monotonically with the host policy (see resolveSandboxPolicy, agent/tools/shared/tool-context.js).
  * @property {import('../agent/sandbox-seam.js').RuntimeSandboxEngine} [sandboxEngine] Per-run concrete sandbox engine handed to the active sandbox implementation.
  * @property {import('../agent/sandbox-seam.js').RuntimeSandbox} [sandbox] Per-run sandbox IMPLEMENTATION override; when set it enforces this run's tools instead of the host/ToolContext impl (precedence run > host > passthrough). Policy DATA still merges monotonically (I13); this overrides only the enforcing code.
  * @property {RuntimeToolLimits} [toolLimits] Typed per-run tool-output limits (supported replacement for the deprecated `settings` tool keys).
+ * @property {readonly string[]} [mcpCallNoTotalTimeoutTools] Exact `server:tool`
+ *   names whose host-owned lifecycle has no total deadline. Inactivity and abort still apply.
  * @property {RuntimeCompactionPolicy} [compaction] Typed per-run compaction policy (supported replacement for the deprecated `settings` compaction keys).
  * @property {RuntimePromptOverrides} [prompts] Per-run prompt-fragment overrides (run wins over the host default).
- * @property {import('./providers/acp-client.js').AcpClientHostOptions["resolveAcpProfile"]} [resolveAcpProfile] Per-run ACP profile resolver; wins over the host default.
- * @property {import('./providers/acp-client.js').AcpClientHostOptions["onAcpInteractionRequest"]} [onAcpInteractionRequest] Per-run ACP permission/elicitation callback; wins over the host default.
- * @property {Uint8Array} [acpSessionTokenKey] Host-owned 32-byte key for confidential authenticated ACP session handles. Required for every ACP task run.
- * @property {{backend?: "auto"|"searxng"|"codex"|"keyless", endpoint?: string, codex?: {model?: string}}} [webSearchConfig] Run-scoped WebSearch backend configuration.
+ * @property {any} [webRequestCoordinator] Host-owned shared web admission and quota state.
+ * @property {{backend?: "auto"|"searxng"|"ollama"|"codex"|"keyless", maxRequestsPerRun?: number, endpoint?: string, searxng?: {endpoint?: string}, ollama?: {baseUrl?: string, apiKey?: string, apiKeyEnv?: string, trustPublicUrl?: boolean}, codex?: {model?: string}}} [webSearchConfig] Run-scoped WebSearch backend configuration.
+ * @property {any} [webSearchState] Private request budget and provider deferral state for one logical run.
  * @property {{render?: "never"|"auto", browserCommand?: string}} [webFetchConfig] Run-scoped WebFetch extraction/render configuration.
  * @property {"sequential"|"safe-parallel"} [piToolExecutionMode] Pi built-in tool scheduling mode. Safe parallelism is the default.
  * @property {"one-at-a-time"|"all"} [piToolParallelismMode] DEPRECATED. Compatibility alias mapped to piToolExecutionMode.
  * @property {Object} [settings] DEPRECATED. Legacy flat settings bag; consumed only as a per-group FALLBACK when the corresponding typed object (`toolLimits` / `compaction`) is absent. Consuming any key emits one `deprecated_settings_option` runtime_warning per run. Migrate via resolveRuntimePolicies (@mono-agent/runtime-adapter).
- * @property {ReadonlyArray<"user" | "project" | "local">} [settingSources] Claude Agent SDK only. Filesystem
- *   settings the SDK may load for this run. Omitted/empty disables user, project, and local sources, including their
- *   CLAUDE.md, hooks, plugins, and on-disk agent profiles. Anthropic managed settings remain in force and may still
- *   configure hooks or plugins; this option is not a managed-policy bypass. Each opted-in source may execute configured
- *   hooks and plugins, so enable only trusted settings and avoid these sources in an untrusted checkout. Include
- *   `"project"`/`"user"` to let the native `Task` tool discover `.claude/agents` definitions. Unrecognized entries are
- *   dropped. The Claude Code CLI bridge does not take this option: that binary performs its own settings discovery and
- *   mono-agent passes no `--setting-sources`, so a CLI run already reads the host config regardless of this value.
- * @property {boolean} [codexLoadProjectDocs] Codex app-server only. Omitted/false starts the managed app-server with
- *   `project_doc_max_bytes=0`, preventing automatic repository-instruction discovery. True restores Codex's native
- *   project-doc loading defaults. An explicit `codexAppServerArgs` array wins over this convenience option.
- * @property {boolean} [codexSandboxNetworkAccess] Codex app-server only, code-only. Strict `true` enables native
- *   network access for plan/read-only and default/acceptEdits/workspace-write turns; omitted or any other runtime
- *   value denies it. No-tool probes always deny network access, and bypass/danger-full-access remains unchanged. This
- *   is unrelated to `RuntimeRunOptions.sandboxPolicy`, which controls mono-agent's own sandbox and is not consumed by
- *   Codex's provider-owned tool loop. Default/acceptEdits workspace-write plus network true grants repository read and
- *   network egress in the same turn; prefer plan when only read-only browsing is needed.
- * @property {RuntimeNativeSubagentsOptions} [nativeSubagents] Caller-defined Claude native `Task` profiles. Direct
- *   Codex owns its collaboration agents and rejects configured teammate definitions; `codexLoadProjectDocs` controls
- *   whether Codex loads repository instructions for its own agents.
  * @property {RuntimeSubagentsOptions} [subagents] In-process `Agent` built-in: profiles, caps, and the nested-run callback.
  * @property {import('../agent/tools/shared/process-jobs.js').ProcessJobsController} [processJobs] Pi-native-only structural process-job controller. When absent, Exec/Bash schemas and foreground behavior are unchanged.
+ * @property {{chainDepth: number, maxChainDepth: number, remainingStarts: number, unavailableReason?: string}} [processJobsAvailability] Host-owned request lineage diagnostics, including when the controller is unavailable.
+ * @property {import('../agent/tools/shared/monitors.js').MonitorsController} [monitors] Pi-native-only structural monitor controller. When absent, the Monitor and MonitorStop tools are not registered at all.
  * @property {Object} [diagnosticsSeed] Set by createRouterRuntime (ai/runtime/router.js) with a `resume_snapshot` when
  *   failing over mid-chain; a host-level coordinator may relay it forward (see agent/transcript.js), not read by any
  *   bridge in this package today.
@@ -325,7 +248,7 @@
 
 /**
  * @typedef {RuntimeRunOptions
- *   & Pick<AgentRuntimeHostOptions, "resolveCustomPricing" | "resolvePiApiKey" | "resolveAcpProfile" | "onAcpInteractionRequest" | "acpSessionTokenKey" | "persistArtifact" | "onCompactionRecorded" | "onToolApprovalRequest" | "toolRiskTiers" | "approvalDefaultRiskTier" | "approvalTimeoutMs" | "approvalAlwaysAllowTools">
+ *   & Pick<AgentRuntimeHostOptions, "resolveCustomPricing" | "resolvePiApiKey" | "onCompactionRecorded" | "onToolApprovalRequest" | "toolRiskTiers" | "approvalDefaultRiskTier" | "approvalTimeoutMs" | "approvalAlwaysAllowTools">
  *   & {runtimeBrand: import('../runtime-brand.js').RuntimeBrand, toolContext?: import('../agent/tools/shared/tool-context.js').ToolContext, observerHub: {emit: (event: RuntimeEvent) => void, flush: () => Promise<void>}}
  * } RuntimeRequest
  * The request shape a bridge's `execute(systemPrompt, req)` receives as its
@@ -397,18 +320,19 @@
  * @property {number} [numTurns]
  * @property {string} [model]
  * @property {string} [effort]
+ * @property {string} [effectiveEffort] Provider-effective reasoning/thinking level when reported.
  * @property {RuntimeSdkId} [sdk]
  * @property {boolean} [cancelled]
  * @property {string|null} [error]
  * @property {Object|null} [errorDetails]
  * @property {string|null} [failureKind]
+ * @property {{runId: string, revision: number, providerSessionId: string, modelKey: string, tipId: string}} [providerSessionRecovery]
  * @property {string|null} [providerSessionId]
  * @property {string|null} [stderrTail] Bounded stderr tail from a CLI-backed bridge; see createStderrTail (ai/failure.js).
  * @property {Array<Object>} [runtimeWarnings]
  * @property {Object} [diagnostics]
  * @property {Object} [capabilitiesUsed]
- * @property {Array<{model: RuntimeModelRef, failureKind: (string|null), requestId?: (string|null), retryableSubkind?: (string|null), retryIndex?: number, requirements?: Object, routeSafety?: RuntimeRouteSafetyMode, safetyContract?: RuntimeRouteSafetyContract}>} [failoverHistory] Set by createRouterRuntime (ai/runtime/router.js) on every failed/skipped attempt.
- * @property {Array<{attemptIndex: number, model: RuntimeModelRef, routeSafety: RuntimeRouteSafetyMode, safetyContract: RuntimeRouteSafetyContract, status: string}>} [routeSafetyHistory] Bounded route-safety audit emitted by createRouterRuntime.
+ * @property {Array<{model: RuntimeModelRef, failureKind: (string|null), requestId?: (string|null), retryableSubkind?: (string|null), retryIndex?: number, requirements?: Object}>} [failoverHistory] Set by createRouterRuntime (ai/runtime/router.js) on every failed/skipped attempt.
  */
 
 /**
@@ -428,8 +352,7 @@
  * @property {boolean} [supports_builtin_tools]
  * @property {boolean} [supports_live_input]
  * @property {boolean} [supports_native_subagents] Whether the bridge exposes provider-native subagent surfaces and
- *   normalized activity. This does not imply it accepts caller-defined `nativeSubagents`: Codex owns its collaboration
- *   agents, while only the Claude bridges project caller-defined profiles.
+ *   normalized activity. In-process delegation is the `Agent` tool, configured by the host.
  * @property {boolean} [supports_request_tool_environment]
  * @property {boolean} [supports_fast_mode]
  * @property {"projected"|"allow_all_only"} [tool_policy] Whether the bridge can
@@ -500,6 +423,8 @@
  * host-integration callbacks (bound once, applied to every run via hostDefaults).
  * @property {string} [workspace]
  * @property {string} [repoRoot]
+ * @property {ReadonlyArray<string>} [additionalReadRoots]
+ * @property {ReadonlyArray<string>} [additionalWriteRoots]
  * @property {string} [ripgrepPath]
  * @property {string} [qaOutputDir]
  * @property {import('../agent/sandbox-seam.js').SandboxPolicy} [sandboxPolicy]
@@ -508,11 +433,8 @@
  * @property {RuntimePromptOverrides} [prompts] Host-level prompt-fragment override defaults; a per-run `options.prompts` field wins over these (see resolvePrompts, runtime.js).
  * @property {ReadonlyArray<*>} [observers] Observer instances (see RuntimeObserver); loose because observer.js is not a kernel seam file.
  * @property {*} [runtimeBrand] See resolveRuntimeBrand (runtime-brand.js); accepts a partial RuntimeBrand.
- * @property {(parsed: {sdk: (string|null), provider?: string, model: string}) => (import('./cost.js').NormalizedPricing|null)} [resolveCustomPricing] See resolvePricing (ai/cost.js).
+ * @property {(parsed: {provider: string, model: string}) => (import('./cost.js').NormalizedPricing|null)} [resolveCustomPricing] See resolvePricing (ai/cost.js).
  * @property {import('../pi-auth.js').PiApiKeyResolver} [resolvePiApiKey] See createPiOAuthApiKeyResolver (pi-auth.js) for a ready-made implementation.
- * @property {import('./providers/acp-client.js').AcpClientHostOptions["resolveAcpProfile"]} [resolveAcpProfile] Default ACP profile resolver; a per-run callback wins.
- * @property {import('./providers/acp-client.js').AcpClientHostOptions["onAcpInteractionRequest"]} [onAcpInteractionRequest] Default ACP interaction callback; a per-run callback wins.
- * @property {Uint8Array} [acpSessionTokenKey] Default host-owned 32-byte key for confidential authenticated ACP session handles.
  * @property {(artifact: {filename: string, buffer: Buffer, toolName: string, toolUseId: (string|null)}) => (string|null)} [persistArtifact]
  * @property {(record: CompactionRecordedPayload) => void} [onCompactionRecorded]
  * @property {(payload: ApprovalRequestPayload) => Promise<ApprovalDecision>} [onToolApprovalRequest]
@@ -528,6 +450,8 @@
  * (createRuntime's TOOL_RUNTIME_KEYS pick).
  * @property {string} [workspace]
  * @property {string} [repoRoot]
+ * @property {ReadonlyArray<string>} [additionalReadRoots]
+ * @property {ReadonlyArray<string>} [additionalWriteRoots]
  * @property {string} [ripgrepPath]
  * @property {string} [qaOutputDir]
  * @property {import('../agent/sandbox-seam.js').SandboxPolicy} [sandboxPolicy]
@@ -540,9 +464,10 @@
  * The object `createRuntime`/`createRouterRuntime` return.
  * @property {(systemPrompt: string, options: RuntimeRunOptions) => Promise<RuntimeResult>} run
  * @property {(next?: AgentRuntimeToolOptions) => void} configureTools
+ * @property {(receipt: NonNullable<RuntimeResult["providerSessionRecovery"]>, context: {appliedInputIds: readonly string[]}) => Promise<boolean>} recoverSession
  * @property {(providerSessionId: string) => Promise<boolean>} syncSession
  * @property {(providerSessionId: string) => Promise<void>} refreshSession Guarantees the id has no reusable process-local handle; rejects on failure.
- * @property {(providerSessionId: string, sessionsRoot: string) => Promise<void>} retireDurableSession Permanently deletes every durable transcript with the exact id; absence is success.
+ * @property {(providerSessionId: string, sessionsRoot: string) => Promise<void>} retireDurableSession Deletes every currently materialized durable transcript with the exact id; callers retry after an active retired run settles to reclaim any late same-name append. Absence is success.
  * @property {(providerSessionId: string) => Promise<boolean>} disposeSession
  * @property {(providerSessionId: string) => Promise<boolean>} invalidateSession
  * @property {() => Promise<void>} disposeAllSessions

package/src/index.js

@@ -18,12 +18,6 @@ export {
   DEFAULT_RUNTIME_BRAND,
   resolveRuntimeBrand,
 } from "./runtime-brand.js";
-export {
-  CLAUDE_SDK_CATALOG_VERSION,
-  discoverClaudeSdkModels,
-  normalizeClaudeSdkCatalog,
-  normalizeClaudeSdkModelId,
-} from "./ai/providers/claude-sdk-discovery.js";
 
 export * from "./ai/index.js";
 export * from "./agent/index.js";

package/src/runtime.js

@@ -5,14 +5,11 @@
 // per-instance `ToolContext` (agent/tools/shared/tool-context.js) that this
 // runtime instance threads to every bridge call via `options.toolContext`
 // instead of a process-global, and returns a `.run(systemPrompt, options)`
-// method that resolves the right provider bridge based on `options.model` +
-// `options.executionMode`.
+// method that resolves the Pi provider bridge based on `options.model`.
 //
-// The runtime registry contains a static table for the six built-in bridges
-// (ACP, Claude SDK/CLI, Pi-native, Codex app-server, OpenCode app-server) and lazily imports
-// the matching implementation only when a run selects it. Hosts that need finer
-// control can keep using the named exports (resolveRuntimeBridge,
-// generateClaudeResponse, etc.) directly.
+// The runtime registry lazily imports the Pi implementation only when a run
+// selects it. Hosts that need finer control can keep using the named exports
+// directly.
 //
 // Return shape from `.run()`:
 //   { text, structuredResult, structuredResultSource, events, usage,
@@ -39,9 +36,10 @@ import {
 } from "./ai/runtime/sessions.js";
 import { createToolContext, updateToolContext } from "./agent/tools/shared/tool-context.js";
 import { resolveRuntimeBrand } from "./runtime-brand.js";
-import { retireDurableNativeSession } from "./ai/providers/pi-native/session-lifecycle.js";
+import { recoverDurableNativeSession, retireDurableNativeSession } from "./ai/providers/pi-native/session-lifecycle.js";
 import { instrumentLiveInputAppliedEvents } from "./ai/runtime/live-input-events.js";
 import { createToolLifecycleEventGate } from "./ai/tool-lifecycle.js";
+import { createWebSearchRunState } from "./agent/tools/web-search-state.js";
 
 /**
  * @typedef {import('./ai/types.js').AgentRuntimeHostOptions} AgentRuntimeHostOptions
@@ -51,12 +49,12 @@ import { createToolLifecycleEventGate } from "./ai/tool-lifecycle.js";
  * @typedef {import('./ai/types.js').RuntimeResult} RuntimeResult
  */
 
+// Host-integration callbacks bound onto every request. This list is the runtime
+// host-default half of `RuntimeRequest` in ai/types.js. Every entry must be
+// admitted either by RuntimeRunOptions itself or by its host-option Pick.
 const HOST_KEYS = [
   "resolveCustomPricing",
   "resolvePiApiKey",
-  "resolveAcpProfile",
-  "onAcpInteractionRequest",
-  "acpSessionTokenKey",
   "persistArtifact",
   "onCompactionRecorded",
   "onToolApprovalRequest",
@@ -69,6 +67,8 @@ const HOST_KEYS = [
 const TOOL_RUNTIME_KEYS = [
   "workspace",
   "repoRoot",
+  "additionalReadRoots",
+  "additionalWriteRoots",
   "ripgrepPath",
   "qaOutputDir",
   "sandboxPolicy",
@@ -177,7 +177,9 @@ export function createRuntime(host = {}) {
     ...(request.skills === undefined ? {} : { skills: request.skills }),
     ...(request.skillsRoot === undefined ? {} : { skillsRoot: request.skillsRoot }),
     ...(request.toolEnvironment === undefined ? {} : { toolEnvironment: request.toolEnvironment }),
-    ...(request.executionMode === undefined ? {} : { executionMode: request.executionMode }),
+    ...(request.webSearchConfig === undefined ? {} : { webSearchConfig: request.webSearchConfig }),
+    ...(request.webRequestCoordinator === undefined ? {} : { webRequestCoordinator: request.webRequestCoordinator }),
+    ...(request.webFetchConfig === undefined ? {} : { webFetchConfig: request.webFetchConfig }),
     ...(request.cwd === undefined ? {} : { cwd: request.cwd }),
     // A profile that pins effort — declared or authored at call time — means it
     // on this path too; dropping it would silently run the child at the
@@ -203,10 +205,9 @@ export function createRuntime(host = {}) {
      */
     async run(systemPrompt, options = {}) {
       if (!options.model) throw new Error("createRuntime.run requires options.model");
-      const executionMode = typeof options.executionMode === "string" ? options.executionMode : "sdk";
+      const webSearchState = createWebSearchRunState(options.webSearchConfig, options.webSearchState);
       const bridge = await resolveRuntimeBridge(options.model, {
         liveInput: !!options.liveInput,
-        executionMode,
       });
       const callObservers = Array.isArray(options.observers) ? options.observers : [];
       const hub = createObserverHub({
@@ -217,6 +218,7 @@ export function createRuntime(host = {}) {
         // Observer delivery keeps the runtime's synchronous contract. Only the
         // client-facing lifecycle event waits for its serialized persistence.
         onObserve: (event) => hub.emit(event),
+        onLifecycleAdmitted: (event) => hub.recordToolLifecycle(event),
         onEvent: options.onEvent,
         abortSignal: options.abortSignal,
       });
@@ -233,17 +235,25 @@ export function createRuntime(host = {}) {
       // defaultSubagentRun is what increments it for the child.
       const subagents = options.subagents === undefined
         ? undefined
-        : { ...options.subagents, run: options.subagents.run ?? defaultSubagentRun };
+        : {
+            ...options.subagents,
+            run: options.subagents.run ?? ((request) => defaultSubagentRun({
+              ...request,
+              ...(options.webSearchConfig === undefined ? {} : { webSearchConfig: options.webSearchConfig }),
+              ...(options.webRequestCoordinator === undefined ? {} : { webRequestCoordinator: options.webRequestCoordinator }),
+              ...(options.webFetchConfig === undefined ? {} : { webFetchConfig: options.webFetchConfig }),
+            })),
+          };
       try {
         return await bridge.execute(systemPrompt, {
           ...hostDefaults,
           ...options,
+          webSearchState,
           ...(subagents === undefined ? {} : { subagents }),
           // `...options` alone doesn't carry the `options.model` narrowing above
           // (spread reads the parameter's declared — Partial — type); re-assert
           // the already-validated model so the request satisfies RuntimeRequest.
           model: options.model,
-          executionMode,
           runtimeBrand,
           toolContext: runToolContext,
           observerHub: hub,
@@ -264,6 +274,9 @@ export function createRuntime(host = {}) {
     configureTools(next = {}) {
       updateToolContext(toolContext, pickPresent(next, TOOL_RUNTIME_KEYS));
     },
+    async recoverSession(receipt, context) {
+      return recoverDurableNativeSession(receipt, context);
+    },
     async syncSession(providerSessionId) {
       return syncProviderSession(providerSessionId);
     },

package/types/agent/tool-bloat.d.ts

@@ -6,7 +6,7 @@ export function summarisePayload(toolName: any, contentBlocks: any, persistArtif
 } | {
     rewrittenBlocks: {
         type: string;
-        text: string;
+        text: any;
     }[];
     savedPaths: any[];
     originalBytes: any;