@mono-agent/agent-runtime 0.20.11 → 0.21.0

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

@@ -38,12 +38,11 @@ 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?: *, executionMode?: string, 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?: {
     model?: any;
-    executionMode?: string;
     cwd?: string;
     parentRunId?: string;
     sandboxPolicy?: any;
@@ -54,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,14 +18,18 @@ 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";
-import { createCodexAppServerClient } from "../../ai/providers/codex-app.js";
+import { createCodexAppServerClient } from "../../ai/providers/codex/app-server-client.js";

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/index.d.ts

@@ -7,6 +7,7 @@ export { createWebToolController } from "./web-controller.js";
 export { resolveRgPath } from "./shared/ripgrep.js";
 export { bashToolImpl, bashToolRun, normalizeBackgroundBashTimeoutMs, normalizeBackgroundTimeoutMs, normalizeBashTimeoutMs, normalizeProcessTimeoutMs } from "./bash.js";
 export { execToolImpl, execToolRun } from "./exec.js";
+export { DEFAULT_MONITOR_TIMEOUT_MS, MIN_MONITOR_TIMEOUT_MS, monitorStopToolRun, monitorToolRun, normalizeMonitorTimeoutMs } from "./monitor.js";
 export { webFetchToolImpl, performWebFetch } from "./web-fetch.js";
 export { webSearchToolImpl, performWebSearch } from "./web-search.js";
 export { DEFAULT_CODEX_SEARCH_MODEL, inspectCodexSubscriptionSearch, searchCodexSubscription } from "./codex-subscription-search.js";

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

@@ -0,0 +1,47 @@
+/**
+ * Normalize `timeout_ms` for a monitor. Unlike Bash there is no
+ * seconds-vs-milliseconds heuristic — this field is new, so it is exact
+ * milliseconds only. `undefined`/invalid falls back to the documented default;
+ * the host's own ceiling clamps the result on its side and reports what it
+ * actually granted.
+ */
+export function normalizeMonitorTimeoutMs(value: any, fallback?: number): number;
+/**
+ * Structured Monitor execution used by the Pi bridge.
+ *
+ * Command preparation is deliberately byte-identical to Bash: the same
+ * `/bin/bash --noprofile --norc -c` shape, the same workdir rules, the same
+ * 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, 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, 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;
+    sandboxEngine?: any;
+    ctx?: any;
+    monitorsController?: import("./shared/monitors.js").MonitorsController;
+}): Promise<any>;
+/**
+ * @param {{monitor_id?: string}} params
+ * @param {{monitorsController?: import("./shared/monitors.js").MonitorsController}} [options]
+ */
+export function monitorStopToolRun({ monitor_id }: {
+    monitor_id?: string;
+}, { monitorsController }?: {
+    monitorsController?: import("./shared/monitors.js").MonitorsController;
+}): Promise<any>;
+/** Claude-Code-compatible defaults: 5 minutes, never below one second. */
+export const DEFAULT_MONITOR_TIMEOUT_MS: 300000;
+export const MIN_MONITOR_TIMEOUT_MS: 1000;

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, 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, 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,8 @@ export function getPiBuiltinTools(allowedTools: any, { disallowedTools, skillNam
     nodeReplController?: any;
     webController?: any;
     processJobsController?: any;
+    processJobsAvailability?: any;
+    monitorsController?: any;
     toolExecutionMode?: "sequential" | "safe-parallel";
     subagents?: any;
     subagentContext?: any;
@@ -81,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/bash-environment.d.ts

@@ -0,0 +1,4 @@
+export function cleanBashEnvironment(sourceEnv?: NodeJS.ProcessEnv): {
+    BASH_ENV: string;
+    ENV: string;
+};

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

@@ -0,0 +1,98 @@
+/**
+ * Kernel-local structural controller seam. The typed public interface lives in
+ * runtime-adapter; this package deliberately has no workspace dependencies.
+ *
+ * @typedef {Object} MonitorsController
+ * @property {(request: {
+ *   prepared: import("../../sandbox-seam.js").PreparedSandboxCommand,
+ *   summary: string,
+ *   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, wakeOn: "batch"|"exit", dedupe: "none"|"batch", minWakeIntervalMs: number}>} start
+ * @property {(monitorId: string) => Promise<{monitorId: string, state: string, stopped: boolean}>} stop
+ */
+/**
+ * Transfer one prepared watch command to the injected host controller. From the
+ * instant `start()` is invoked, the controller owns cleanup on every path.
+ *
+ * @param {{
+ *   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,
+ * }} input
+ */
+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>;
+/**
+ * Stop one monitor by id. Idempotent: stopping an already-terminal monitor is a
+ * success that reports the state it settled in, never an error, so a model that
+ * re-issues a stop after a terminal wake is not pushed into a retry loop.
+ *
+ * @param {{controller: MonitorsController, monitorId: unknown, startedAt: number, failed: (text: string, code: string, startedAt: number) => any}} input
+ */
+export function handOffMonitorStop({ controller, monitorId, startedAt, failed }: {
+    controller: MonitorsController;
+    monitorId: unknown;
+    startedAt: number;
+    failed: (text: string, code: string, startedAt: number) => any;
+}): Promise<any>;
+/**
+ * Kernel-local structural controller seam. The typed public interface lives in
+ * runtime-adapter; this package deliberately has no workspace dependencies.
+ */
+export type MonitorsController = {
+    start: (request: {
+        prepared: import("../../sandbox-seam.js").PreparedSandboxCommand;
+        summary: string;
+        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;
+        wakeOn: "batch" | "exit";
+        dedupe: "none" | "batch";
+        minWakeIntervalMs: number;
+    }>;
+    stop: (monitorId: string) => Promise<{
+        monitorId: string;
+        state: string;
+        stopped: boolean;
+    }>;
+};
+import { startPreparedProcess } from "./process-runner.js";

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.
@@ -28,7 +29,15 @@ export function runPreparedProcess(commandSpec: {
  * descendant in the owned group is still alive.
  *
  * @param {{command: string, args?: string[], cwd?: string, env?: Record<string, string|undefined>}} commandSpec
- * @param {{timeoutMs?: number, signal?: AbortSignal, maxBufferBytes?: number, input?: string|Buffer, waitForProcessGroup?: boolean, exactEnvironment?: boolean, onStdout?: (chunk: Buffer) => void, onStderr?: (chunk: Buffer) => void}} [options]
+ * `outputMode` selects how output is handled. "buffer" (default) accumulates it
+ * under `maxBufferBytes` and terminates the process when that bound is crossed —
+ * the right contract for a job whose whole output is the result. "stream" hands
+ * every chunk to `onStdout`/`onStderr` and stores NEITHER, so an indefinitely
+ * long watch is never killed for producing output and the caller owns the only
+ * copy. Buffering stderr as well would hand a streaming caller two overlapping
+ * views of it: the runner's bounded PREFIX plus the caller's own tail.
+ *
+ * @param {{timeoutMs?: number, signal?: AbortSignal, maxBufferBytes?: number, input?: string|Buffer, waitForProcessGroup?: boolean, exactEnvironment?: boolean, outputMode?: "buffer"|"stream", onStdout?: (chunk: Buffer) => void, onStderr?: (chunk: Buffer) => void}} [options]
  * For process jobs, `release()` is the persistence fence: the target cannot
  * spawn until the host has durably recorded the returned ownership metadata.
  * Foreground handles expose a harmless no-op release for one structural shape.
@@ -40,13 +49,14 @@ export function startPreparedProcess(commandSpec: {
     args?: string[];
     cwd?: string;
     env?: Record<string, string | undefined>;
-}, { timeoutMs, signal, maxBufferBytes, input, waitForProcessGroup, exactEnvironment, onStdout, onStderr, }?: {
+}, { timeoutMs, signal, maxBufferBytes, input, waitForProcessGroup, exactEnvironment, outputMode, onStdout, onStderr, }?: {
     timeoutMs?: number;
     signal?: AbortSignal;
     maxBufferBytes?: number;
     input?: string | Buffer;
     waitForProcessGroup?: boolean;
     exactEnvironment?: boolean;
+    outputMode?: "buffer" | "stream";
     onStdout?: (chunk: Buffer) => void;
     onStderr?: (chunk: Buffer) => void;
 }): {

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;

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

@@ -1,8 +1,8 @@
 /**
  * Compatibility wrapper for direct callers.
  *
- * @param {{url: string, headers?: Record<string, string>, max_output_chars?: number, format?: string, render?: string}} params
- * @param {{sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, signal?: AbortSignal, retryDelaysMs?: number[], fetchConfig?: any, fetchImpl?: typeof fetch, browserRenderer?: typeof renderWithAgentBrowser, namespace?: string, registerCleanup?: (cleanup: () => Promise<void>) => () => void}} [options]
+ * @param {{url: string, headers?: Record<string, string>, max_output_chars?: number, format?: string, render?: string, start_line?: number, max_lines?: number}} params
+ * @param {{documentOnly?: boolean, coordinator?: any, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, signal?: AbortSignal, retryDelaysMs?: number[], fetchConfig?: any, fetchImpl?: typeof fetch, browserRenderer?: typeof renderWithAgentBrowser, namespace?: string, registerCleanup?: (cleanup: () => Promise<void>) => () => void}} [options]
  */
 export function webFetchToolImpl(params: {
     url: string;
@@ -10,7 +10,11 @@ export function webFetchToolImpl(params: {
     max_output_chars?: number;
     format?: string;
     render?: string;
+    start_line?: number;
+    max_lines?: number;
 }, options?: {
+    documentOnly?: boolean;
+    coordinator?: any;
     sandboxPolicy?: any;
     sandboxEngine?: any;
     ctx?: any;
@@ -25,16 +29,20 @@ export function webFetchToolImpl(params: {
 /**
  * Fetch and locally extract one public URL.
  *
- * @param {{url: string, headers?: Record<string, string>, max_output_chars?: number, format?: string, render?: string}} params
- * @param {{sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, signal?: AbortSignal, retryDelaysMs?: number[], fetchConfig?: any, fetchImpl?: typeof fetch, browserRenderer?: typeof renderWithAgentBrowser, namespace?: string, registerCleanup?: (cleanup: () => Promise<void>) => () => void}} [options]
+ * @param {{url: string, headers?: Record<string, string>, max_output_chars?: number, format?: string, render?: string, start_line?: number, max_lines?: number}} params
+ * @param {{documentOnly?: boolean, coordinator?: any, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, signal?: AbortSignal, retryDelaysMs?: number[], fetchConfig?: any, fetchImpl?: typeof fetch, browserRenderer?: typeof renderWithAgentBrowser, namespace?: string, registerCleanup?: (cleanup: () => Promise<void>) => () => void}} [options]
  */
-export function performWebFetch({ url, headers, max_output_chars, format, render, }: {
+export function performWebFetch(params: {
     url: string;
     headers?: Record<string, string>;
     max_output_chars?: number;
     format?: string;
     render?: string;
-}, { sandboxPolicy, sandboxEngine, ctx, signal, retryDelaysMs, fetchConfig, fetchImpl, browserRenderer, namespace, registerCleanup, }?: {
+    start_line?: number;
+    max_lines?: number;
+}, options?: {
+    documentOnly?: boolean;
+    coordinator?: any;
     sandboxPolicy?: any;
     sandboxEngine?: any;
     ctx?: any;
@@ -45,7 +53,8 @@ export function performWebFetch({ url, headers, max_output_chars, format, render
     browserRenderer?: typeof renderWithAgentBrowser;
     namespace?: string;
     registerCleanup?: (cleanup: () => Promise<void>) => () => void;
-}): Promise<{
+}): Promise<any>;
+export function formatWebFetchDocument(document: any, params: any, ctx: any): {
     text: any;
     outcome: {
         status: string;
@@ -61,22 +70,8 @@ export function performWebFetch({ url, headers, max_output_chars, format, render
     error: boolean;
 } | {
     text: string;
-    outcome: {
-        status: string;
-        code: string;
-        retryable: boolean;
-        attempts: number;
-        backend: string;
-        cacheHit: boolean;
-        durationMs: number;
-        bytes: number;
-        truncated: boolean;
-        statusCode: any;
-        redirectCount: number;
-        rendered: boolean;
-        renderFailed: boolean;
-        contentKind: string;
-    };
+    outcome: any;
     error: boolean;
-}>;
+    document: any;
+};
 import { renderWithAgentBrowser } from "./web-browser-render.js";

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

@@ -0,0 +1,20 @@
+/** One deadline covers admission, backend startup, I/O, and retries. */
+export function withWebDeadline(signal: any, milliseconds: any, execute: any): Promise<any>;
+export function coordinatedWebRequest(coordinator: any, kind: any, key: any, signal: any, execute: any, classify?: typeof classifySearch): Promise<any>;
+export function webRequestFailure(error: any, backend: any, signal: any): {
+    ok: boolean;
+    backend: any;
+    code: any;
+    message: string;
+    retryable: boolean;
+    cooldown: boolean;
+    rateLimited: boolean;
+    retryAfterMs: any;
+    retryAtMs: any;
+};
+declare function classifySearch(result: any): {
+    retryAtMs?: any;
+    retryAfterMs?: any;
+    status: string;
+};
+export {};

package/types/agent/tools/web-search-output.d.ts

@@ -0,0 +1,31 @@
+/** Replace isolated UTF-16 surrogates while preserving valid astral pairs. @param {unknown} value */
+export function toWellFormedText(value: unknown): string;
+/** @param {unknown} value @param {number} maxChars */
+export function sliceWellFormedCodePoints(value: unknown, maxChars: number): string;
+/** @param {string} value @param {number} maxBytes */
+export function sliceUtf8(value: string, maxBytes: number): string;
+/** @param {unknown} value @param {number} [maxChars] */
+export function boundWebSearchSnippet(value: unknown, maxChars?: number): {
+    text: string;
+    truncated: boolean;
+};
+/**
+ * @param {Array<{title?: unknown, url?: unknown, snippet?: unknown, snippetTruncated?: boolean}>} results
+ * @param {{maxBytes?: number}} [options]
+ */
+export function renderBoundedWebSearchBody(results: Array<{
+    title?: unknown;
+    url?: unknown;
+    snippet?: unknown;
+    snippetTruncated?: boolean;
+}>, { maxBytes }?: {
+    maxBytes?: number;
+}): {
+    body: string;
+    renderedResultCount: number;
+    truncated: boolean;
+};
+export const WEB_SEARCH_TITLE_MAX_CHARS: 500;
+export const WEB_SEARCH_SNIPPET_MAX_CHARS: 4000;
+export const WEB_SEARCH_BODY_MAX_BYTES: number;
+export const WEB_SEARCH_SNIPPET_TRUNCATION_MARKER: "[snippet truncated; use WebFetch for full source]";