@mono-agent/agent-runtime 0.20.11 → 0.21.0

package/types/ai/types.d.ts

@@ -1,48 +1,17 @@
 /**
- * @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.
  */
 /**
  * @typedef {Object} RuntimeSubagentIdentity
@@ -60,6 +29,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.
  */
 /**
  * @typedef {"agent_started"|"started"|"completed"|"message"|"agent_completed"} RuntimeSubagentActivityPhase
@@ -120,7 +91,7 @@
  * @typedef {Readonly<{
  *   recordId?: string,
  *   sequence?: number,
- *   persistence: "persisted"|"failed",
+ *   persistence: "persisted"|"deferred"|"failed",
  *   truncated?: boolean,
  *   originalBytes?: number,
  *   retainedBytes?: number,
@@ -134,32 +105,11 @@
  * @param {RuntimeToolLifecycleEvent} event
  * @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]
  */
@@ -214,19 +164,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.
@@ -235,46 +185,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.
@@ -284,7 +220,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
@@ -351,18 +287,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.
  */
 /**
  * @typedef {Object} RuntimeCapabilities
@@ -381,8 +318,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
@@ -447,6 +383,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]
@@ -455,11 +393,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]
@@ -474,6 +409,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]
@@ -485,77 +422,37 @@
  * 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
  */
 export const PROVIDER_KIND_VALUES: string[];
 /**
- * Canonical active runtime id. See ACTIVE_RUNTIME_KINDS (model-refs.js) for
- * the enforced-at-runtime vocabulary.
+ * Runtime-result and telemetry label. Model references no longer carry this
+ * field because Pi is the sole runtime bridge.
  */
-export type RuntimeSdkId = "claude" | "pi" | "codex" | "opencode" | "acp" | (string & {});
+export type RuntimeSdkId = "pi";
 /**
- * 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.
+ * Registry bridge id. See src/ai/runtime/registry.js's builtinBridgeSpecs.
  */
-export type RuntimeBridgeId = "claude" | "claude-code" | "codex-app" | "opencode-app" | "pi" | "acp-stdio" | (string & {});
+export type RuntimeBridgeId = "pi";
 export type RuntimeModelRef = {
     /**
-     * Canonical active runtime id.
+     * Pi provider id.
      */
-    sdk: RuntimeSdkId;
+    provider: string;
     /**
      * Provider model id.
      */
     model: string;
     /**
-     * Original canonical model reference; always set by
-     *           parseRuntimeModelReference, but router.js's chain
-     *           shorthand accepts bare {sdk, model} refs without one.
-     */
-    reference?: string;
-    /**
-     * Pi/OpenCode provider id when sdk === "pi" | "opencode".
-     */
-    provider?: string;
-};
-/**
- * One caller-defined Claude native `Task` profile. Codex collaboration-agent
- * definitions are owned by Codex and are not represented by this type.
- */
-export type RuntimeNativeSubagentDefinition = {
-    name: string;
-    displayName?: string;
-    description?: string;
-    helperSystemPrompt?: string;
-    instructions?: string;
-    allowedTools?: ReadonlyArray<string>;
-    disallowedTools?: ReadonlyArray<string>;
-    modelRef?: string | RuntimeModelRef;
-    model?: RuntimeModelRef;
-    effort?: string;
-    mcpServers?: {
-        [x: string]: any;
-    };
-    /**
-     * App-owned exact-connection MCP Apps registry (Pi-native only).
+     * Canonical `<provider>:<model>` reference.
      */
-    mcpApps?: any;
-};
-/**
- * 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.
- */
-export type RuntimeNativeSubagentsOptions = {
-    provider: "claude";
-    teammates: ReadonlyArray<RuntimeNativeSubagentDefinition>;
+    reference: string;
 };
 /**
  * Provider-neutral identity attached to every `subagent_activity` event.
@@ -595,6 +492,11 @@ export type RuntimeSubagentIdentity = {
      * attribute it to this subagent.
      */
     costUsd?: number;
+    /**
+     * Bounded provider-route attribution for the
+     * completed child run. Consumers must treat it as operator telemetry.
+     */
+    attribution?: any;
 };
 /**
  * `agent_started`/`agent_completed` bracket the delegation; `started`/`completed`
@@ -673,7 +575,7 @@ export type RuntimeToolLifecycleEvent = RuntimeToolLifecycleInvocationEvent | Ru
 export type RuntimeToolLifecyclePersistence = Readonly<{
     recordId?: string;
     sequence?: number;
-    persistence: "persisted" | "failed";
+    persistence: "persisted" | "deferred" | "failed";
     truncated?: boolean;
     originalBytes?: number;
     retainedBytes?: number;
@@ -684,34 +586,15 @@ export type RuntimeToolLifecyclePersistence = Readonly<{
     errorCode?: string;
 }>;
 export type RuntimeToolLifecycleSink = (event: RuntimeToolLifecycleEvent) => Promise<RuntimeToolLifecyclePersistence | undefined>;
-export type RuntimeRouteSafetyMode = "uniform" | "per-route-native";
-/**
- * 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.
- */
-export type RuntimeRouteSandboxContract = "mono-agent-monotonic" | "disabled" | "mono-agent-srt" | "mono-agent-srt-unsafe-host-fallback" | "provider-native" | "codex-native" | "unsupported";
-/**
- * `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 `["*"]`.
- */
-export type RuntimeRouteToolsContract = "mono-agent-monotonic" | "mono-agent-policy" | "provider-representable" | "exact-allow-all" | "unsupported";
-/**
- * Bounded, credential-free description of the sandbox/tool contract applied
- * to one fallback route.
- */
-export type RuntimeRouteSafetyContract = {
-    mode: RuntimeRouteSafetyMode;
-    sandbox: RuntimeRouteSandboxContract;
-    tools: RuntimeRouteToolsContract;
-};
 /**
  * Per-call or host-level observer merged by createObserverHub (ai/observer.js).
  * Loose on purpose: observer.js is not a kernel seam file.
  */
 export type RuntimeObserver = {
+    /**
+     * Synchronous admission before queued lifecycle persistence.
+     */
+    recordToolLifecycle?: (event: RuntimeToolLifecycleEvent) => void;
     onEvent?: (event: RuntimeEvent) => (void | Promise<void>);
     flush?: () => (void | Promise<void>);
 };
@@ -827,10 +710,6 @@ export type RuntimeRunOptions = {
      * Resolved model reference; see parseRuntimeModelReference.
      */
     model: RuntimeModelRef;
-    /**
-     * "sdk" (default), "cli", or "acp"; selects which bridge variant handles the model.
-     */
-    executionMode?: "sdk" | "cli" | "acp";
     /**
      * Host conversation/session key for resumable bridges.
      */
@@ -840,9 +719,16 @@ export type RuntimeRunOptions = {
      */
     providerSessionId?: string;
     /**
-     * Advanced programmatic/test seam for the Claude SDK route; omitted runs use the runtime's pinned SDK query implementation.
+     * Host-owned provider attribution continuity key; does not authorize transcript resume.
+     */
+    providerAttributionSessionId?: string;
+    /**
+     * Host-owned durable recovery opt-in.
      */
-    claudeAgentQuery?: typeof import("@anthropic-ai/claude-agent-sdk").query;
+    sessionRecovery?: {
+        runId: string;
+        revision: number;
+    };
     /**
      * Keep resumable provider state alive after the turn.
      */
@@ -852,27 +738,43 @@ export type RuntimeRunOptions = {
      */
     sessionIdleTimeoutMs?: number;
     /**
-     * Stream of in-flight user messages for steering an active run. Providers acknowledge only after accepting a message into the active turn.
+     * 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.
      */
     liveInput?: AsyncIterable<{
         body: string;
         id?: string;
         receivedAt?: string;
-        acknowledge?: () => void;
-        reject?: (error?: unknown) => void;
+        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;
     }>;
     /**
      * Per-call observers (see RuntimeObserver) merged with host-level (createRuntime) observers.
      */
     observers?: ReadonlyArray<any>;
     onEvent?: (event: RuntimeEvent) => void;
+    /**
+     * Emit metadata-only prompt-cache request fingerprints.
+     */
+    promptCacheDiagnostics?: boolean;
     /**
      * Awaited host-owned incremental lifecycle persistence boundary.
      */
     toolLifecycleSink?: RuntimeToolLifecycleSink;
     messages?: ReadonlyArray<any>;
     effort?: string;
-    fastMode?: boolean;
     cwd?: string;
     mcpServers?: {
         [x: string]: any;
@@ -892,9 +794,29 @@ export type RuntimeRunOptions = {
     disallowedTools?: ReadonlyArray<string>;
     permissionMode?: string;
     maxTurns?: number;
+    /**
+     * Internal provider-check output cap; ordinary callers must omit it.
+     */
+    providerCheckMaxTokens?: number;
+    /**
+     * Internal provider-check effective auth context; ordinary callers must omit it.
+     */
+    providerCheckAuthContext?: {
+        env(name: string): Promise<string | undefined>;
+        fileExists(path: string): Promise<boolean>;
+    };
     outputSchema?: any;
     runArtifactDir?: string;
     abortSignal?: AbortSignal;
+    /**
+     * Host-owned synchronous artifact writer bound to this run.
+     */
+    persistArtifact?: (artifact: {
+        filename: string;
+        buffer: Buffer;
+        toolName: string;
+        toolUseId: (string | null);
+    }) => (string | null);
     /**
      * Host-only environment for Bash, Exec, and nested subagents in this run.
      */
@@ -919,6 +841,11 @@ export type RuntimeRunOptions = {
      * Typed per-run tool-output limits (supported replacement for the deprecated `settings` tool keys).
      */
     toolLimits?: RuntimeToolLimits;
+    /**
+     * Exact `server:tool`
+     * names whose host-owned lifecycle has no total deadline. Inactivity and abort still apply.
+     */
+    mcpCallNoTotalTimeoutTools?: readonly string[];
     /**
      * Typed per-run compaction policy (supported replacement for the deprecated `settings` compaction keys).
      */
@@ -928,27 +855,33 @@ export type RuntimeRunOptions = {
      */
     prompts?: RuntimePromptOverrides;
     /**
-     * Per-run ACP profile resolver; wins over the host default.
-     */
-    resolveAcpProfile?: import("./providers/acp-client.js").AcpClientHostOptions["resolveAcpProfile"];
-    /**
-     * Per-run ACP permission/elicitation callback; wins over the host default.
-     */
-    onAcpInteractionRequest?: import("./providers/acp-client.js").AcpClientHostOptions["onAcpInteractionRequest"];
-    /**
-     * Host-owned 32-byte key for confidential authenticated ACP session handles. Required for every ACP task run.
+     * Host-owned shared web admission and quota state.
      */
-    acpSessionTokenKey?: Uint8Array;
+    webRequestCoordinator?: any;
     /**
      * Run-scoped WebSearch backend configuration.
      */
     webSearchConfig?: {
-        backend?: "auto" | "searxng" | "codex" | "keyless";
+        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;
         };
     };
+    /**
+     * Private request budget and provider deferral state for one logical run.
+     */
+    webSearchState?: any;
     /**
      * Run-scoped WebFetch extraction/render configuration.
      */
@@ -968,38 +901,6 @@ export type RuntimeRunOptions = {
      * 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).
      */
     settings?: any;
-    /**
-     * 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.
-     */
-    settingSources?: ReadonlyArray<"user" | "project" | "local">;
-    /**
-     * 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.
-     */
-    codexLoadProjectDocs?: boolean;
-    /**
-     * 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.
-     */
-    codexSandboxNetworkAccess?: boolean;
-    /**
-     * 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.
-     */
-    nativeSubagents?: RuntimeNativeSubagentsOptions;
     /**
      * In-process `Agent` built-in: profiles, caps, and the nested-run callback.
      */
@@ -1008,6 +909,19 @@ export type RuntimeRunOptions = {
      * Pi-native-only structural process-job controller. When absent, Exec/Bash schemas and foreground behavior are unchanged.
      */
     processJobs?: import("../agent/tools/shared/process-jobs.js").ProcessJobsController;
+    /**
+     * Host-owned request lineage diagnostics, including when the controller is unavailable.
+     */
+    processJobsAvailability?: {
+        chainDepth: number;
+        maxChainDepth: number;
+        remainingStarts: number;
+        unavailableReason?: string;
+    };
+    /**
+     * Pi-native-only structural monitor controller. When absent, the Monitor and MonitorStop tools are not registered at all.
+     */
+    monitors?: import("../agent/tools/shared/monitors.js").MonitorsController;
     /**
      * 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
@@ -1030,7 +944,7 @@ export type RuntimeRunOptions = {
  * createRuntime), and the per-run observerHub (onEvent is overridden to the
  * hub's emit). `systemPrompt` is passed positionally, not folded into this object.
  */
-export type RuntimeRequest = RuntimeRunOptions & Pick<AgentRuntimeHostOptions, "resolveCustomPricing" | "resolvePiApiKey" | "resolveAcpProfile" | "onAcpInteractionRequest" | "acpSessionTokenKey" | "persistArtifact" | "onCompactionRecorded" | "onToolApprovalRequest" | "toolRiskTiers" | "approvalDefaultRiskTier" | "approvalTimeoutMs" | "approvalAlwaysAllowTools"> & {
+export type RuntimeRequest = RuntimeRunOptions & 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: {
@@ -1139,11 +1053,22 @@ export type RuntimeResult = {
     numTurns?: number;
     model?: string;
     effort?: string;
+    /**
+     * Provider-effective reasoning/thinking level when reported.
+     */
+    effectiveEffort?: string;
     sdk?: RuntimeSdkId;
     cancelled?: boolean;
     error?: string | null;
     errorDetails?: any | null;
     failureKind?: string | null;
+    providerSessionRecovery?: {
+        runId: string;
+        revision: number;
+        providerSessionId: string;
+        modelKey: string;
+        tipId: string;
+    };
     providerSessionId?: string | null;
     /**
      * Bounded stderr tail from a CLI-backed bridge; see createStderrTail (ai/failure.js).
@@ -1162,18 +1087,6 @@ export type RuntimeResult = {
         retryableSubkind?: (string | null);
         retryIndex?: number;
         requirements?: any;
-        routeSafety?: RuntimeRouteSafetyMode;
-        safetyContract?: RuntimeRouteSafetyContract;
-    }>;
-    /**
-     * Bounded route-safety audit emitted by createRouterRuntime.
-     */
-    routeSafetyHistory?: Array<{
-        attemptIndex: number;
-        model: RuntimeModelRef;
-        routeSafety: RuntimeRouteSafetyMode;
-        safetyContract: RuntimeRouteSafetyContract;
-        status: string;
     }>;
 };
 /**
@@ -1195,8 +1108,7 @@ export type RuntimeCapabilities = {
     supports_live_input?: boolean;
     /**
      * 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.
      */
     supports_native_subagents?: boolean;
     supports_request_tool_environment?: boolean;
@@ -1275,6 +1187,8 @@ export type CompactionRecordedPayload = {
 export type AgentRuntimeHostOptions = {
     workspace?: string;
     repoRoot?: string;
+    additionalReadRoots?: ReadonlyArray<string>;
+    additionalWriteRoots?: ReadonlyArray<string>;
     ripgrepPath?: string;
     qaOutputDir?: string;
     sandboxPolicy?: import("../agent/sandbox-seam.js").SandboxPolicy;
@@ -1299,26 +1213,13 @@ export type AgentRuntimeHostOptions = {
      * See resolvePricing (ai/cost.js).
      */
     resolveCustomPricing?: (parsed: {
-        sdk: (string | null);
-        provider?: string;
+        provider: string;
         model: string;
     }) => (import("./cost.js").NormalizedPricing | null);
     /**
      * See createPiOAuthApiKeyResolver (pi-auth.js) for a ready-made implementation.
      */
     resolvePiApiKey?: import("../pi-auth.js").PiApiKeyResolver;
-    /**
-     * Default ACP profile resolver; a per-run callback wins.
-     */
-    resolveAcpProfile?: import("./providers/acp-client.js").AcpClientHostOptions["resolveAcpProfile"];
-    /**
-     * Default ACP interaction callback; a per-run callback wins.
-     */
-    onAcpInteractionRequest?: import("./providers/acp-client.js").AcpClientHostOptions["onAcpInteractionRequest"];
-    /**
-     * Default host-owned 32-byte key for confidential authenticated ACP session handles.
-     */
-    acpSessionTokenKey?: Uint8Array;
     persistArtifact?: (artifact: {
         filename: string;
         buffer: Buffer;
@@ -1341,6 +1242,8 @@ export type AgentRuntimeHostOptions = {
 export type AgentRuntimeToolOptions = {
     workspace?: string;
     repoRoot?: string;
+    additionalReadRoots?: ReadonlyArray<string>;
+    additionalWriteRoots?: ReadonlyArray<string>;
     ripgrepPath?: string;
     qaOutputDir?: string;
     sandboxPolicy?: import("../agent/sandbox-seam.js").SandboxPolicy;
@@ -1353,13 +1256,16 @@ export type AgentRuntimeToolOptions = {
 export type AgentRuntimeInstance = {
     run: (systemPrompt: string, options: RuntimeRunOptions) => Promise<RuntimeResult>;
     configureTools: (next?: AgentRuntimeToolOptions) => void;
+    recoverSession: (receipt: NonNullable<RuntimeResult["providerSessionRecovery"]>, context: {
+        appliedInputIds: readonly string[];
+    }) => Promise<boolean>;
     syncSession: (providerSessionId: string) => Promise<boolean>;
     /**
      * Guarantees the id has no reusable process-local handle; rejects on failure.
      */
     refreshSession: (providerSessionId: string) => Promise<void>;
     /**
-     * Permanently deletes every durable transcript with the exact id; absence is success.
+     * 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.
      */
     retireDurableSession: (providerSessionId: string, sessionsRoot: string) => Promise<void>;
     disposeSession: (providerSessionId: string) => Promise<boolean>;