@mono-agent/agent-runtime 0.20.14 → 0.21.0

package/src/ai/types.js

@@ -42,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.
  */
 
 /**
@@ -110,7 +112,7 @@
  * @typedef {Readonly<{
  *   recordId?: string,
  *   sequence?: number,
- *   persistence: "persisted"|"failed",
+ *   persistence: "persisted"|"deferred"|"failed",
  *   truncated?: boolean,
  *   originalBytes?: number,
  *   retainedBytes?: number,
@@ -130,6 +132,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]
  */
@@ -190,11 +193,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]
@@ -206,23 +212,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
@@ -234,7 +248,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
@@ -306,11 +320,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]
@@ -407,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]
@@ -432,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]
@@ -444,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/runtime.js

@@ -36,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
@@ -49,9 +50,8 @@ import { createToolLifecycleEventGate } from "./ai/tool-lifecycle.js";
  */
 
 // Host-integration callbacks bound onto every request. This list is the runtime
-// half of the `Pick<AgentRuntimeHostOptions, ...>` clause in the `RuntimeRequest`
-// typedef (ai/types.js) -- the two must stay identical, or hosts get keys the
-// declared request shape does not admit.
+// 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",
@@ -67,6 +67,8 @@ const HOST_KEYS = [
 const TOOL_RUNTIME_KEYS = [
   "workspace",
   "repoRoot",
+  "additionalReadRoots",
+  "additionalWriteRoots",
   "ripgrepPath",
   "qaOutputDir",
   "sandboxPolicy",
@@ -175,6 +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.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
@@ -200,6 +205,7 @@ export function createRuntime(host = {}) {
      */
     async run(systemPrompt, options = {}) {
       if (!options.model) throw new Error("createRuntime.run requires options.model");
+      const webSearchState = createWebSearchRunState(options.webSearchConfig, options.webSearchState);
       const bridge = await resolveRuntimeBridge(options.model, {
         liveInput: !!options.liveInput,
       });
@@ -212,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,
       });
@@ -228,11 +235,20 @@ 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
@@ -258,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;

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

@@ -38,7 +38,7 @@ export function subagentUsageForRun(subagents: any, parentRunId: string | undefi
  * Build the `Agent` tool, or null when subagents are unavailable for this run.
  *
  * @param {RuntimeSubagentsOptions|null|undefined} subagents
- * @param {{model?: *, cwd?: string, parentRunId?: string, sandboxPolicy?: *, sandboxEngine?: *, skills?: {name: string, description?: string}[], skillsRoot?: string, toolEnvironment?: *, onEvent?: (event: *) => void}} [context]
+ * @param {{model?: *, cwd?: string, parentRunId?: string, sandboxPolicy?: *, sandboxEngine?: *, skills?: {name: string, description?: string}[], skillsRoot?: string, toolEnvironment?: *, webSearchConfig?: *, webRequestCoordinator?: *, webFetchConfig?: *, onEvent?: (event: *) => void}} [context]
  * @returns {*|null}
  */
 export function createAgentTool(subagents: RuntimeSubagentsOptions | null | undefined, context?: {
@@ -53,6 +53,9 @@ export function createAgentTool(subagents: RuntimeSubagentsOptions | null | unde
     }[];
     skillsRoot?: string;
     toolEnvironment?: any;
+    webSearchConfig?: any;
+    webRequestCoordinator?: any;
+    webFetchConfig?: any;
     onEvent?: (event: any) => void;
 }): any | null;
 /**

package/types/agent/tools/bash.d.ts

@@ -24,7 +24,7 @@ export function normalizeBackgroundBashTimeoutMs(value: any): number;
 /**
  * Compatibility wrapper retained for direct callers and tests.
  *
- * @param {{command: string, description?: string, timeout?: number, timeout_ms?: number, max_output_chars?: number, workdir?: string, background?: boolean}} params
+ * @param {{command: string, description?: string, timeout?: number, timeout_ms?: number, max_output_chars?: number, workdir?: string, background?: boolean, wake_on_completion?: boolean}} params
  * @param {{signal?: AbortSignal, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, processJobsController?: import("./shared/process-jobs.js").ProcessJobsController}} [options]
  */
 export function bashToolImpl(params: {
@@ -35,6 +35,7 @@ export function bashToolImpl(params: {
     max_output_chars?: number;
     workdir?: string;
     background?: boolean;
+    wake_on_completion?: boolean;
 }, options?: {
     signal?: AbortSignal;
     sandboxPolicy?: any;
@@ -45,10 +46,10 @@ export function bashToolImpl(params: {
 /**
  * Structured Bash execution used by the Pi bridge.
  *
- * @param {{command: string, description?: string, timeout?: number, timeout_ms?: number, max_output_chars?: number, workdir?: string, background?: boolean}} params
+ * @param {{command: string, description?: string, timeout?: number, timeout_ms?: number, max_output_chars?: number, workdir?: string, background?: boolean, wake_on_completion?: boolean}} params
  * @param {{signal?: AbortSignal, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, processJobsController?: import("./shared/process-jobs.js").ProcessJobsController}} [options]
  */
-export function bashToolRun({ command, description, timeout, timeout_ms, max_output_chars, workdir, background, }: {
+export function bashToolRun({ command, description, timeout, timeout_ms, max_output_chars, workdir, background, wake_on_completion, }: {
     command: string;
     description?: string;
     timeout?: number;
@@ -56,6 +57,7 @@ export function bashToolRun({ command, description, timeout, timeout_ms, max_out
     max_output_chars?: number;
     workdir?: string;
     background?: boolean;
+    wake_on_completion?: boolean;
 }, { signal, sandboxPolicy, sandboxEngine, ctx, processJobsController, }?: {
     signal?: AbortSignal;
     sandboxPolicy?: any;

package/types/agent/tools/codex-subscription-search.d.ts

@@ -18,13 +18,17 @@ export function inspectCodexSubscriptionSearch(options?: {
  * turns or cross-wire app-server notifications between requests.
  *
  * @param {string} query
- * @param {{model?: string, signal?: AbortSignal, clientFactory?: typeof createCodexAppServerClient}} [options]
+ * @param {{model?: string, signal?: AbortSignal, clientFactory?: typeof createCodexAppServerClient, coordinator?: any, language?: string, timeRange?: string, claimRequest?: () => void}} [options]
  */
 export function searchCodexSubscription(query: string, options?: {
     model?: string;
     signal?: AbortSignal;
     clientFactory?: typeof createCodexAppServerClient;
-}): Promise<void>;
+    coordinator?: any;
+    language?: string;
+    timeRange?: string;
+    claimRequest?: () => void;
+}): any;
 /** Test hook for process-shared broker state. */
 export function __resetCodexSubscriptionSearchForTests(): Promise<void>;
 export const DEFAULT_CODEX_SEARCH_MODEL: "gpt-5.6-luna";

package/types/agent/tools/exec.d.ts

@@ -1,6 +1,6 @@
 /** @typedef {import("./shared/process-jobs.js").ProcessJobsController} ProcessJobsController */
 /**
- * @param {{executable: string, args?: string[], workdir?: string, description?: string, timeout_ms?: number, max_output_chars?: number, background?: boolean}} params
+ * @param {{executable: string, args?: string[], workdir?: string, description?: string, timeout_ms?: number, max_output_chars?: number, background?: boolean, wake_on_completion?: boolean}} params
  * @param {{signal?: AbortSignal, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, processJobsController?: ProcessJobsController}} [options]
  */
 export function execToolImpl(params: {
@@ -11,6 +11,7 @@ export function execToolImpl(params: {
     timeout_ms?: number;
     max_output_chars?: number;
     background?: boolean;
+    wake_on_completion?: boolean;
 }, options?: {
     signal?: AbortSignal;
     sandboxPolicy?: any;
@@ -21,10 +22,10 @@ export function execToolImpl(params: {
 /**
  * Execute an argv vector directly, without shell parsing.
  *
- * @param {{executable: string, args?: string[], workdir?: string, description?: string, timeout_ms?: number, max_output_chars?: number, background?: boolean}} params
+ * @param {{executable: string, args?: string[], workdir?: string, description?: string, timeout_ms?: number, max_output_chars?: number, background?: boolean, wake_on_completion?: boolean}} params
  * @param {{signal?: AbortSignal, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, processJobsController?: ProcessJobsController}} [options]
  */
-export function execToolRun({ executable, args, workdir, description, timeout_ms, max_output_chars, background, }: {
+export function execToolRun({ executable, args, workdir, description, timeout_ms, max_output_chars, background, wake_on_completion, }: {
     executable: string;
     args?: string[];
     workdir?: string;
@@ -32,6 +33,7 @@ export function execToolRun({ executable, args, workdir, description, timeout_ms
     timeout_ms?: number;
     max_output_chars?: number;
     background?: boolean;
+    wake_on_completion?: boolean;
 }, { signal, sandboxPolicy, sandboxEngine, ctx, processJobsController, }?: {
     signal?: AbortSignal;
     sandboxPolicy?: any;

package/types/agent/tools/monitor.d.ts

@@ -14,15 +14,18 @@ export function normalizeMonitorTimeoutMs(value: any, fallback?: number): number
  * cleaned startup environment, and the same sandbox `prepareCommand` seam. A
  * monitor must never be a way to run a command Bash could not.
  *
- * @param {{command?: string, description?: string, timeout_ms?: number, persistent?: boolean, workdir?: string}} params
+ * @param {{command?: string, description?: string, timeout_ms?: number, persistent?: boolean, workdir?: string, wake_on?: "batch"|"exit", dedupe?: "none"|"batch", min_wake_interval_ms?: number}} params
  * @param {{signal?: AbortSignal, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, monitorsController?: import("./shared/monitors.js").MonitorsController}} [options]
  */
-export function monitorToolRun({ command, description, timeout_ms, persistent, workdir }: {
+export function monitorToolRun({ command, description, timeout_ms, persistent, workdir, wake_on, dedupe, min_wake_interval_ms }: {
     command?: string;
     description?: string;
     timeout_ms?: number;
     persistent?: boolean;
     workdir?: string;
+    wake_on?: "batch" | "exit";
+    dedupe?: "none" | "batch";
+    min_wake_interval_ms?: number;
 }, { sandboxPolicy, sandboxEngine, ctx, monitorsController }?: {
     signal?: AbortSignal;
     sandboxPolicy?: any;

package/types/agent/tools/pi-bridge.d.ts

@@ -35,9 +35,9 @@ export function createStructuredOutputTool(outputSchema: any, onStructuredOutput
 };
 /**
  * @param {any} allowedTools
- * @param {{disallowedTools?: any[], skillNames?: any[], skills?: any[], skillsRoot?: any, dataDir?: any, cwd?: any, onEvent?: (event: any) => void, toolLimits?: any, persistArtifact?: any, onTruncate?: any, toolPayloadMaxBytes?: number, imageInlineMaxBytes?: any, toolPolicy?: any, sandboxPolicy?: any, sandboxEngine?: any, approvalManager?: any, approvalModel?: any, nodeReplController?: any, webController?: any, processJobsController?: any, monitorsController?: any, toolExecutionMode?: "sequential"|"safe-parallel", subagents?: any, subagentContext?: any, ctx?: any}} [options]
+ * @param {{disallowedTools?: any[], skillNames?: any[], skills?: any[], skillsRoot?: any, dataDir?: any, cwd?: any, onEvent?: (event: any) => void, toolLimits?: any, persistArtifact?: any, onTruncate?: any, toolPayloadMaxBytes?: number, imageInlineMaxBytes?: any, toolPolicy?: any, sandboxPolicy?: any, sandboxEngine?: any, approvalManager?: any, approvalModel?: any, nodeReplController?: any, webController?: any, processJobsController?: any, processJobsAvailability?: any, monitorsController?: any, toolExecutionMode?: "sequential"|"safe-parallel", subagents?: any, subagentContext?: any, ctx?: any}} [options]
  */
-export function getPiBuiltinTools(allowedTools: any, { disallowedTools, skillNames, skills, skillsRoot, dataDir, cwd, onEvent, toolLimits, persistArtifact, onTruncate, toolPayloadMaxBytes, imageInlineMaxBytes, toolPolicy, sandboxPolicy, sandboxEngine, approvalManager, approvalModel, nodeReplController, webController, processJobsController, monitorsController, subagents, subagentContext, toolExecutionMode, ctx, }?: {
+export function getPiBuiltinTools(allowedTools: any, { disallowedTools, skillNames, skills, skillsRoot, dataDir, cwd, onEvent, toolLimits, persistArtifact, onTruncate, toolPayloadMaxBytes, imageInlineMaxBytes, toolPolicy, sandboxPolicy, sandboxEngine, approvalManager, approvalModel, nodeReplController, webController, processJobsController, processJobsAvailability, monitorsController, subagents, subagentContext, toolExecutionMode, ctx, }?: {
     disallowedTools?: any[];
     skillNames?: any[];
     skills?: any[];
@@ -58,6 +58,7 @@ export function getPiBuiltinTools(allowedTools: any, { disallowedTools, skillNam
     nodeReplController?: any;
     webController?: any;
     processJobsController?: any;
+    processJobsAvailability?: any;
     monitorsController?: any;
     toolExecutionMode?: "sequential" | "safe-parallel";
     subagents?: any;
@@ -82,10 +83,11 @@ export function coerceMcpContent(out: any, { textLimit, imageInlineMaxBytes, per
 /**
  * @param {any} mcpConfig
  * @param {Set<any>} [reservedNames]
- * @param {{limits?: any, cwd?: any, persistArtifact?: any, qaOutputDir?: any, onTruncate?: any, toolPayloadMaxBytes?: number, sandboxPolicy?: any, sandboxEngine?: any, onToolProgress?: any, ctx?: any, mcpApps?: any, runId?: string}} [options]
+ * @param {{limits?: any, mcpCallNoTotalTimeoutTools?: readonly string[], cwd?: any, persistArtifact?: any, qaOutputDir?: any, onTruncate?: any, toolPayloadMaxBytes?: number, sandboxPolicy?: any, sandboxEngine?: any, onToolProgress?: any, ctx?: any, mcpApps?: any, runId?: string}} [options]
  */
-export function initPiMcpTools(mcpConfig: any, reservedNames?: Set<any>, { limits, cwd, persistArtifact, qaOutputDir, onTruncate, toolPayloadMaxBytes, sandboxPolicy, sandboxEngine, onToolProgress, ctx, mcpApps, runId, }?: {
+export function initPiMcpTools(mcpConfig: any, reservedNames?: Set<any>, { limits, mcpCallNoTotalTimeoutTools, cwd, persistArtifact, qaOutputDir, onTruncate, toolPayloadMaxBytes, sandboxPolicy, sandboxEngine, onToolProgress, ctx, mcpApps, runId, }?: {
     limits?: any;
+    mcpCallNoTotalTimeoutTools?: readonly string[];
     cwd?: any;
     persistArtifact?: any;
     qaOutputDir?: any;

package/types/agent/tools/shared/monitors.d.ts

@@ -9,8 +9,11 @@
  *   description: string,
  *   timeoutMs?: number,
  *   persistent?: boolean,
+ *   wakeOn?: "batch"|"exit",
+ *   dedupe?: "none"|"batch",
+ *   minWakeIntervalMs?: number,
  *   launch: (options?: {timeoutMs?: number, onStdout?: (chunk: Buffer) => void, onStderr?: (chunk: Buffer) => void}) => ReturnType<typeof startPreparedProcess>,
- * }) => Promise<{monitorId: string, state: "starting"|"running", startedAt: string, maxRuntimeMs: number, persistent: boolean}>} start
+ * }) => Promise<{monitorId: string, state: "starting"|"running", startedAt: string, maxRuntimeMs: number, persistent: boolean, wakeOn: "batch"|"exit", dedupe: "none"|"batch", minWakeIntervalMs: number}>} start
  * @property {(monitorId: string) => Promise<{monitorId: string, state: string, stopped: boolean}>} stop
  */
 /**
@@ -24,17 +27,23 @@
  *   description: string,
  *   timeoutMs?: number,
  *   persistent?: boolean,
+ *   wakeOn?: "batch"|"exit",
+ *   dedupe?: "none"|"batch",
+ *   minWakeIntervalMs?: number,
  *   startedAt: number,
  *   failed: (text: string, code: string, startedAt: number) => any,
  * }} input
  */
-export function handOffMonitor({ controller, prepared, summary, description, timeoutMs, persistent, startedAt, failed, }: {
+export function handOffMonitor({ controller, prepared, summary, description, timeoutMs, persistent, wakeOn, dedupe, minWakeIntervalMs, startedAt, failed, }: {
     controller: MonitorsController;
     prepared: import("../../sandbox-seam.js").PreparedSandboxCommand;
     summary: string;
     description: string;
     timeoutMs?: number;
     persistent?: boolean;
+    wakeOn?: "batch" | "exit";
+    dedupe?: "none" | "batch";
+    minWakeIntervalMs?: number;
     startedAt: number;
     failed: (text: string, code: string, startedAt: number) => any;
 }): Promise<any>;
@@ -62,6 +71,9 @@ export type MonitorsController = {
         description: string;
         timeoutMs?: number;
         persistent?: boolean;
+        wakeOn?: "batch" | "exit";
+        dedupe?: "none" | "batch";
+        minWakeIntervalMs?: number;
         launch: (options?: {
             timeoutMs?: number;
             onStdout?: (chunk: Buffer) => void;
@@ -73,6 +85,9 @@ export type MonitorsController = {
         startedAt: string;
         maxRuntimeMs: number;
         persistent: boolean;
+        wakeOn: "batch" | "exit";
+        dedupe: "none" | "batch";
+        minWakeIntervalMs: number;
     }>;
     stop: (monitorId: string) => Promise<{
         monitorId: string;

package/types/agent/tools/shared/process-jobs.d.ts

@@ -8,6 +8,7 @@
  *   prepared: import("../../sandbox-seam.js").PreparedSandboxCommand,
  *   summary: string,
  *   description?: string,
+ *   wakeOnCompletion?: boolean,
  *   timeoutMs?: number,
  *   maxOutputChars?: number,
  *   launch: (options?: {timeoutMs?: number, signal?: AbortSignal, maxBufferBytes?: number, onStdout?: (chunk: Buffer) => void, onStderr?: (chunk: Buffer) => void}) => ReturnType<typeof startPreparedProcess>,
@@ -23,18 +24,20 @@
  *   prepared: import("../../sandbox-seam.js").PreparedSandboxCommand,
  *   summary: string,
  *   description?: string,
+ *   wakeOnCompletion?: boolean,
  *   timeoutMs?: number,
  *   maxOutputChars?: number,
  *   startedAt: number,
  *   failed: (text: string, code: string, startedAt: number) => any,
  * }} input
  */
-export function handOffProcessJob({ controller, tool, prepared, summary, description, timeoutMs, maxOutputChars, startedAt, failed, }: {
+export function handOffProcessJob({ controller, tool, prepared, summary, description, wakeOnCompletion, timeoutMs, maxOutputChars, startedAt, failed, }: {
     controller: ProcessJobsController;
     tool: "Exec" | "Bash";
     prepared: import("../../sandbox-seam.js").PreparedSandboxCommand;
     summary: string;
     description?: string;
+    wakeOnCompletion?: boolean;
     timeoutMs?: number;
     maxOutputChars?: number;
     startedAt: number;
@@ -50,6 +53,7 @@ export type ProcessJobsController = {
         prepared: import("../../sandbox-seam.js").PreparedSandboxCommand;
         summary: string;
         description?: string;
+        wakeOnCompletion?: boolean;
         timeoutMs?: number;
         maxOutputChars?: number;
         launch: (options?: {

package/types/agent/tools/shared/process-runner.d.ts

@@ -6,18 +6,19 @@
  * or exceeds that cap.
  *
  * @param {{command: string, args?: string[], cwd?: string, env?: Record<string, string|undefined>}} commandSpec
- * @param {{timeoutMs?: number, signal?: AbortSignal, maxBufferBytes?: number, input?: string|Buffer}} [options]
+ * @param {{timeoutMs?: number, signal?: AbortSignal, maxBufferBytes?: number, input?: string|Buffer, exactEnvironment?: boolean}} [options]
  */
 export function runPreparedProcess(commandSpec: {
     command: string;
     args?: string[];
     cwd?: string;
     env?: Record<string, string | undefined>;
-}, { timeoutMs, signal, maxBufferBytes, input, }?: {
+}, { timeoutMs, signal, maxBufferBytes, input, exactEnvironment, }?: {
     timeoutMs?: number;
     signal?: AbortSignal;
     maxBufferBytes?: number;
     input?: string | Buffer;
+    exactEnvironment?: boolean;
 }): Promise<any>;
 /**
  * Start one already-prepared executable and expose its process-group handle.

package/types/agent/tools/shared/tool-context.d.ts

@@ -47,6 +47,8 @@ export type RuntimeSandbox = import("../../sandbox-seam.js").RuntimeSandbox;
 export type ToolContext = {
     workspace?: string;
     repoRoot?: string;
+    additionalReadRoots?: ReadonlyArray<string>;
+    additionalWriteRoots?: ReadonlyArray<string>;
     runId?: string;
     toolArtifactDir?: string;
     ripgrepPath?: string;

package/types/agent/tools/web-access-interstitial.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Classify access and authentication interstitials without treating incidental
+ * words such as "captcha" or "access denied" as conclusive evidence.
+ *
+ * @param {{url?: string, text?: string, statusCode?: number}} input
+ * @returns {{code: "access_challenge"|"authentication_required", message: string}|undefined}
+ */
+export function classifyWebAccessInterstitial({ url, text, statusCode }?: {
+    url?: string;
+    text?: string;
+    statusCode?: number;
+}): {
+    code: "access_challenge" | "authentication_required";
+    message: string;
+} | undefined;
+/**
+ * @param {{url?: string, text?: string, statusCode?: number}} input
+ */
+export function assertNoWebAccessInterstitial(input: {
+    url?: string;
+    text?: string;
+    statusCode?: number;
+}): void;

package/types/agent/tools/web-browser-render.d.ts

@@ -12,5 +12,8 @@ export function renderWithAgentBrowser(url: string, { browserCommand, namespace,
     ctx?: any;
     signal?: AbortSignal;
     registerCleanup?: (cleanup: () => Promise<void>) => () => void;
-}): Promise<any>;
+}): Promise<{
+    text: any;
+    finalUrl: string;
+}>;
 export function extractBrowserText(output: any): any;

package/types/agent/tools/web-controller.d.ts

@@ -4,10 +4,12 @@
  * cleanup. Search results are the exception: they live in the process-wide
  * cache above so sibling subagents and later turns can reuse them.
  *
- * @param {{searchConfig?: any, fetchConfig?: any, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, fetchImpl?: typeof fetch, browserRenderer?: any, codexSearch?: any}} [options]
+ * @param {{coordinator?: any, searchConfig?: any, searchState?: any, fetchConfig?: any, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, fetchImpl?: typeof fetch, browserRenderer?: any, codexSearch?: any}} [options]
  */
-export function createWebToolController({ searchConfig, fetchConfig, sandboxPolicy, sandboxEngine, ctx, fetchImpl, browserRenderer, codexSearch, }?: {
+export function createWebToolController({ coordinator, searchConfig, searchState: suppliedSearchState, fetchConfig, sandboxPolicy, sandboxEngine, ctx, fetchImpl, browserRenderer, codexSearch, }?: {
+    coordinator?: any;
     searchConfig?: any;
+    searchState?: any;
     fetchConfig?: any;
     sandboxPolicy?: any;
     sandboxEngine?: any;

package/types/agent/tools/web-document-extractor.d.ts

@@ -0,0 +1,27 @@
+export function contentKind(contentType: any, bytes: any): "binary" | "text" | "markdown" | "pdf" | "json" | "xml" | "html";
+export function decodeWebBytes(bytes: any, contentType: any, kind?: string): {
+    text: string;
+    charset: string;
+    charsetSource: string;
+    hadDecodingReplacement: boolean;
+};
+export function extractWebDocument(bytes: any, { contentType, format, url }: {
+    contentType: any;
+    format: any;
+    url: any;
+}): Promise<{
+    text: string;
+    charset: string;
+    charsetSource: string;
+    hadDecodingReplacement: boolean;
+    kind: string;
+    body: any;
+    readableText: string;
+    title: any;
+    extractionStage: any;
+    parserFailureCount: any;
+    parserFailures: any;
+}>;
+export function shouldAutoRender(readableText: any, html: any): boolean;
+export function markdownToText(value: any): string;
+export const MAX_STRUCTURED_DOCUMENT_BYTES: number;