@mono-agent/agent-runtime 0.20.14 → 0.21.0

package/types/ai/runtime/live-input-events.d.ts

@@ -1,22 +1,46 @@
 /**
- * @typedef {{body: string, id?: string, receivedAt?: string, acknowledge?: () => void, reject?: (reason?: unknown) => void}} RuntimeLiveInputMessage
- * @typedef {{type: "live_input_applied", inputId: string, receivedAt?: string}} LiveInputAppliedEvent
+ * @typedef {{providerEntryId?: string, providerRunId?: string}} RuntimeLiveInputEvidence
+ * @typedef {{reason: "delivery_uncertain", providerEntryId?: string, providerRunId?: string}} RuntimeLiveInputUncertainty
+ * @typedef {{body: string, id?: string, receivedAt?: string, logicalOwner?: object, accepted?: (evidence?: RuntimeLiveInputEvidence) => unknown, acknowledge?: (evidence?: RuntimeLiveInputEvidence) => unknown, uncertain?: (details: RuntimeLiveInputUncertainty) => unknown, reject?: (reason?: unknown) => unknown}} RuntimeLiveInputMessage
+ * @typedef {{message: RuntimeLiveInputMessage, callbackMessage: RuntimeLiveInputMessage, logicalOwner?: object, inputId: string, receivedAt?: string, phase: "available"|"leased"|"native_accepted"|"consumed"|"uncertain", attempt: number, generation: number}} LiveInputOwner
+ * @typedef {{type: string, [key: string]: unknown}} LiveInputEvent
  */
 /**
  * @param {AsyncIterable<RuntimeLiveInputMessage>|undefined} liveInput
- * @param {(event: LiveInputAppliedEvent) => void} onApplied
+ * @param {(event: LiveInputEvent) => void} onEvent
  * @returns {AsyncIterable<RuntimeLiveInputMessage>|undefined}
  */
-export function instrumentLiveInputAppliedEvents(liveInput: AsyncIterable<RuntimeLiveInputMessage> | undefined, onApplied: (event: LiveInputAppliedEvent) => void): AsyncIterable<RuntimeLiveInputMessage> | undefined;
+export function instrumentLiveInputAppliedEvents(liveInput: AsyncIterable<RuntimeLiveInputMessage> | undefined, onEvent: (event: LiveInputEvent) => void): AsyncIterable<RuntimeLiveInputMessage> | undefined;
+export type RuntimeLiveInputEvidence = {
+    providerEntryId?: string;
+    providerRunId?: string;
+};
+export type RuntimeLiveInputUncertainty = {
+    reason: "delivery_uncertain";
+    providerEntryId?: string;
+    providerRunId?: string;
+};
 export type RuntimeLiveInputMessage = {
     body: string;
     id?: string;
     receivedAt?: string;
-    acknowledge?: () => void;
-    reject?: (reason?: unknown) => void;
+    logicalOwner?: object;
+    accepted?: (evidence?: RuntimeLiveInputEvidence) => unknown;
+    acknowledge?: (evidence?: RuntimeLiveInputEvidence) => unknown;
+    uncertain?: (details: RuntimeLiveInputUncertainty) => unknown;
+    reject?: (reason?: unknown) => unknown;
 };
-export type LiveInputAppliedEvent = {
-    type: "live_input_applied";
+export type LiveInputOwner = {
+    message: RuntimeLiveInputMessage;
+    callbackMessage: RuntimeLiveInputMessage;
+    logicalOwner?: object;
     inputId: string;
     receivedAt?: string;
+    phase: "available" | "leased" | "native_accepted" | "consumed" | "uncertain";
+    attempt: number;
+    generation: number;
+};
+export type LiveInputEvent = {
+    type: string;
+    [key: string]: unknown;
 };

package/types/ai/tool-lifecycle.d.ts

@@ -1,9 +1,10 @@
 /**
- * @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 }: {
     sink?: (event: any) => Promise<any>;
     onObserve?: (event: any) => void;
+    onLifecycleAdmitted?: (event: any) => void;
     onEvent?: (event: any) => void;
     abortSignal?: AbortSignal;
 }): {
@@ -35,7 +36,7 @@ export function historyMetadata(persisted: any, terminalStateValue: string | und
     originalBytes?: number;
     truncated?: any;
     terminalState?: string;
-    persistence: string;
+    persistence: any;
     sequence?: number;
     recordId?: any;
 };

package/types/ai/types.d.ts

@@ -29,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
@@ -89,7 +91,7 @@
  * @typedef {Readonly<{
  *   recordId?: string,
  *   sequence?: number,
- *   persistence: "persisted"|"failed",
+ *   persistence: "persisted"|"deferred"|"failed",
  *   truncated?: boolean,
  *   originalBytes?: number,
  *   retainedBytes?: number,
@@ -107,6 +109,7 @@
  * @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]
  */
@@ -163,11 +166,14 @@
  * @property {RuntimeModelRef} model                     Resolved model reference; see parseRuntimeModelReference.
  * @property {string} [sessionId]                         Host conversation/session key for resumable bridges.
  * @property {string} [providerSessionId]                 Provider-owned resume id for resumable bridges.
+ * @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]
@@ -179,23 +185,31 @@
  * @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 {{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 {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
@@ -206,7 +220,7 @@
  */
 /**
  * @typedef {RuntimeRunOptions
- *   & Pick<AgentRuntimeHostOptions, "resolveCustomPricing" | "resolvePiApiKey" | "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
@@ -273,11 +287,13 @@
  * @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]
@@ -367,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]
@@ -391,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]
@@ -402,9 +422,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
@@ -471,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`
@@ -549,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;
@@ -565,6 +591,10 @@ export type RuntimeToolLifecycleSink = (event: RuntimeToolLifecycleEvent) => Pro
  * 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>);
 };
@@ -688,6 +718,17 @@ export type RuntimeRunOptions = {
      * Provider-owned resume id for resumable bridges.
      */
     providerSessionId?: string;
+    /**
+     * Host-owned provider attribution continuity key; does not authorize transcript resume.
+     */
+    providerAttributionSessionId?: string;
+    /**
+     * Host-owned durable recovery opt-in.
+     */
+    sessionRecovery?: {
+        runId: string;
+        revision: number;
+    };
     /**
      * Keep resumable provider state alive after the turn.
      */
@@ -697,20 +738,37 @@ 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.
      */
@@ -736,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.
      */
@@ -763,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).
      */
@@ -771,16 +854,34 @@ export type RuntimeRunOptions = {
      * Per-run prompt-fragment overrides (run wins over the host default).
      */
     prompts?: RuntimePromptOverrides;
+    /**
+     * Host-owned shared web admission and quota state.
+     */
+    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.
      */
@@ -808,6 +909,15 @@ 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.
      */
@@ -834,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" | "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: {
@@ -943,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).
@@ -1066,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;
@@ -1119,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;
@@ -1131,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>;