@oh-my-pi/pi-coding-agent 17.2.3 → 17.2.5

package/dist/types/tools/computer/supervisor.d.ts

@@ -1,32 +1,45 @@
-import type { DesktopAction, DesktopCapabilities, DesktopCapture, DesktopSessionOptions } from "@oh-my-pi/pi-natives";
-import { type ComputerWorkerInbound, type ComputerWorkerOutbound } from "./protocol.js";
+import type { DesktopCapabilities } from "@oh-my-pi/pi-natives";
+import type { ToolSession } from "../index.js";
+import { type ComputerRunOk, type ComputerSessionSnapshot, type ComputerWorkerInbound, type ComputerWorkerOutbound } from "./protocol.js";
+/** Runs desktop scripts and owns their persistent worker session. */
 export interface ComputerController {
-    readonly capabilities: DesktopCapabilities | undefined;
-    execute(actions: DesktopAction[], signal?: AbortSignal): Promise<DesktopCapture>;
+    run(code: string, timeoutMs: number, snapshot: ComputerSessionSnapshot, signal?: AbortSignal): Promise<ComputerRunOk>;
+    capabilities(): Promise<DesktopCapabilities | undefined>;
     close(): Promise<void>;
 }
+/** Minimal Bun worker lifecycle surface used by the supervisor. */
 export interface ComputerWorkerHandle {
     send(message: ComputerWorkerInbound): void;
     onMessage(handler: (message: ComputerWorkerOutbound) => void): () => void;
     onError(handler: (error: Error) => void): () => void;
     terminate(): Promise<void>;
 }
+/** Startup and shutdown deadlines for a computer worker. */
 export interface ComputerSupervisorTimeouts {
     startMs: number;
     closeMs: number;
 }
+/** Dispatches a tool call requested from desktop JavaScript. */
+export type ComputerSessionToolCaller = (name: string, args: unknown, options: {
+    session: ToolSession;
+    signal?: AbortSignal;
+    emitStatus?: () => void;
+}) => Promise<unknown>;
+/** Creates an isolated computer worker handle. */
 export type ComputerWorkerFactory = () => ComputerWorkerHandle;
+/** Spawns the computer worker through the active CLI host when available. */
 export declare function spawnComputerWorker(): ComputerWorkerHandle;
+/** Supervises one lazy, crash-isolated computer worker per agent session. */
 export declare class ComputerSupervisor implements ComputerController {
     #private;
-    private readonly options;
-    private readonly createWorker;
-    private readonly timeouts;
-    constructor(options: DesktopSessionOptions, createWorker?: ComputerWorkerFactory, timeouts?: ComputerSupervisorTimeouts);
-    get capabilities(): DesktopCapabilities | undefined;
-    execute(actions: DesktopAction[], signal?: AbortSignal): Promise<DesktopCapture>;
+    constructor(session: ToolSession, createWorker?: ComputerWorkerFactory, timeouts?: ComputerSupervisorTimeouts, callSessionTool?: ComputerSessionToolCaller);
+    capabilities(): Promise<DesktopCapabilities | undefined>;
+    run(code: string, timeoutMs: number, snapshot: ComputerSessionSnapshot, signal?: AbortSignal): Promise<ComputerRunOk>;
     close(): Promise<void>;
 }
+/** Registers a controller for owner-scoped session cleanup. */
 export declare function registerComputerController(ownerId: string | undefined, controller: ComputerController): () => void;
+/** Closes every computer session owned by an agent session. */
 export declare function releaseComputerSessionsForOwner(ownerId: string | undefined): Promise<void>;
+/** Verifies computer worker startup, messaging, and bounded shutdown. */
 export declare function smokeTestComputerWorker(timeoutMs?: number, createWorker?: ComputerWorkerFactory): Promise<void>;

package/dist/types/tools/computer/worker-entry.d.ts

@@ -1 +1,2 @@
+/** Starts the computer worker once when running inside a Bun worker thread. */
 export declare function startComputerWorker(): void;

package/dist/types/tools/computer/worker.d.ts

@@ -1,15 +1,50 @@
-import type { DesktopAction, DesktopCapture, DesktopSession, DesktopSessionOptions } from "@oh-my-pi/pi-natives";
-import type { ComputerWorkerTransport } from "./protocol.js";
+import type { AxNode, AxQuery, AxSnapshotOptions, DesktopCapabilities, DesktopDisplay, DesktopPoint, DesktopSessionOptions, DesktopWindow, PointerOptions } from "@oh-my-pi/pi-natives";
+import type { ComputerWorkerInbound, ComputerWorkerTransport } from "./protocol.js";
+/** Native desktop operations consumed by the script runtime. */
 export interface NativeDesktopSession {
-    readonly capabilities: DesktopSession["capabilities"];
-    capture(): Promise<DesktopCapture>;
-    execute(actions: DesktopAction[]): Promise<DesktopCapture>;
+    readonly capabilities: DesktopCapabilities;
+    listDisplays(): Promise<DesktopDisplay[]>;
+    listWindows(): Promise<DesktopWindow[]>;
+    capture(target: string, caps?: {
+        maxWidth?: number;
+        maxHeight?: number;
+    } | null): Promise<{
+        data: Uint8Array;
+        width: number;
+        height: number;
+        sourceWidth: number;
+        sourceHeight: number;
+        target: string;
+    }>;
+    click(target: string, x: number, y: number, opts?: PointerOptions | null): Promise<void>;
+    moveMouse(target: string, x: number, y: number, opts?: PointerOptions | null): Promise<void>;
+    drag(target: string, points: DesktopPoint[], opts?: PointerOptions | null): Promise<void>;
+    scroll(target: string, x: number, y: number, dx: number, dy: number, opts?: PointerOptions | null): Promise<void>;
+    typeText(target: string, text: string, opts?: PointerOptions | null): Promise<void>;
+    keyChord(target: string, keys: string[], opts?: PointerOptions | null): Promise<void>;
+    raiseWindow(windowId: string): Promise<void>;
+    axSnapshot(target: string, opts?: AxSnapshotOptions | null): Promise<{
+        text: string;
+    }>;
+    axQuery(target: string, query: AxQuery): Promise<AxNode[]>;
+    axElementAt(target: string, x: number, y: number): Promise<AxNode | null | undefined>;
+    axFocused(): Promise<AxNode | null | undefined>;
+    axNode(ref: string): Promise<AxNode>;
+    axAttributes(ref: string): Promise<Array<[string, string]>>;
+    axChildren(ref: string): Promise<AxNode[]>;
+    axParent(ref: string): Promise<AxNode | null | undefined>;
+    axPerform(ref: string, action: string): Promise<void>;
+    axSetValue(ref: string, value: string): Promise<void>;
+    axFocus(ref: string): Promise<void>;
+    axClick(ref: string, opts?: PointerOptions | null): Promise<void>;
     close(): Promise<void>;
 }
+/** Creates the native session co-located with the computer worker runtime. */
 export type NativeDesktopSessionFactory = (options: DesktopSessionOptions) => NativeDesktopSession;
+/** Hosts the persistent JavaScript runtime and native desktop session. */
 export declare class ComputerWorkerCore {
     #private;
-    private readonly transport;
-    private readonly createSession;
     constructor(transport: ComputerWorkerTransport, createSession?: NativeDesktopSessionFactory);
+    /** Routes one supervisor command into the persistent worker state. */
+    handle(message: ComputerWorkerInbound): void;
 }

package/dist/types/tools/computer-renderer.d.ts

@@ -2,21 +2,23 @@ import type { Component } from "@oh-my-pi/pi-tui";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types.js";
 import type { Theme } from "../modes/theme/theme.js";
 interface ComputerRenderArgs {
-    actions?: Array<{
-        type?: unknown;
-    }>;
+    code?: unknown;
+    read_only?: unknown;
+    window?: unknown;
+    actions?: unknown;
 }
 interface ComputerRenderResult {
-    content: Array<{
+    content?: Array<{
         type: string;
         text?: string;
     }>;
     details?: unknown;
     isError?: boolean;
 }
+/** Renders computer scripts, run state, screenshots, and failures in the TUI. */
 export declare const computerToolRenderer: {
     mergeCallAndResult: boolean;
-    renderCall(args: ComputerRenderArgs, _options: RenderResultOptions, theme: Theme): Component;
+    renderCall(args: ComputerRenderArgs, options: RenderResultOptions, theme: Theme): Component;
     renderResult(result: ComputerRenderResult, options: RenderResultOptions, theme: Theme, args?: ComputerRenderArgs): Component;
 };
 export {};

package/dist/types/tools/computer.d.ts

@@ -1,66 +1,47 @@
 import type { AgentTool, AgentToolContext, AgentToolResult, AgentToolUpdateCallback, ToolApprovalDecision } from "@oh-my-pi/pi-agent-core";
-import type { ComputerAction } from "@oh-my-pi/pi-ai";
-import type { DesktopCapabilities, DesktopCapture, DesktopDisplay, DesktopSessionOptions } from "@oh-my-pi/pi-natives";
+import type { DesktopCapabilities } from "@oh-my-pi/pi-natives";
 import { type Type } from "arktype";
+import type { ComputerScreenshot } from "./computer/protocol.js";
 import { type ComputerController } from "./computer/supervisor.js";
 import type { ToolSession } from "./index.js";
-type ComputerSchemaPoint = {
-    x: number;
-    y: number;
-};
-type ComputerSchemaAction = {
-    type: ComputerAction["type"];
-    x?: number;
-    y?: number;
-    button?: "left" | "right" | "wheel" | "back" | "forward";
-    path?: ComputerSchemaPoint[];
-    keys?: string[] | null;
-    scroll_x?: number;
-    scroll_y?: number;
-    text?: string;
-};
-export type ComputerParams = {
-    actions?: ComputerSchemaAction[];
-};
-type IsSameType<Left, Right> = [Left] extends [Right] ? ([Right] extends [Left] ? true : false) : false;
-type ComputerSchema<Schema extends Type = Type<ComputerParams>> = IsSameType<ComputerParams, Schema["infer"]> extends true ? Schema : never;
+interface ComputerToolInput {
+    code: string;
+    read_only?: boolean;
+    timeout?: number;
+}
+type ComputerSchema = Type<ComputerToolInput>;
+/** Renderer and artifact metadata produced by a computer tool run. */
 export interface ComputerToolDetails {
-    width: number;
-    height: number;
-    backend: DesktopCapture["backend"];
-    displayServer?: string;
-    capturePermission: string;
-    inputPermission: string;
-    displays: DesktopDisplay[];
-    capabilities?: DesktopCapabilities;
-    actions: ComputerAction["type"][];
+    code?: string;
+    readOnly?: boolean;
+    screenshots: ComputerScreenshot[];
+    returnValue?: string;
+    backend?: string;
+    capturePermission?: string;
+    inputPermission?: string;
+    axPermission?: string;
 }
-export type ComputerControllerFactory = (options: DesktopSessionOptions) => ComputerController;
+/** Creates the session-scoped controller used by the computer tool. */
+export type ComputerControllerFactory = (session: ToolSession) => ComputerController;
+/** Maps inspection-only runs to read approval and all other runs to execution approval. */
 export declare function computerApproval(args: unknown): ToolApprovalDecision;
+/** Executes persistent desktop JavaScript through one lazy worker session. */
 export declare class ComputerTool implements AgentTool<ComputerSchema, ComputerToolDetails> {
     #private;
     readonly session: ToolSession;
     readonly name = "computer";
-    readonly native: {
-        readonly type: "computer";
-    };
     readonly label = "Computer";
     readonly loadMode: "essential";
     readonly concurrency: "exclusive";
-    readonly summary = "Capture and control the host desktop through native OS APIs";
-    get parameters(): ComputerSchema;
+    readonly summary = "Control the host desktop with persistent JavaScript and OS accessibility APIs";
     readonly strict = false;
     readonly approval: typeof computerApproval;
     readonly formatApprovalDetails: (args: unknown) => string[];
-    /**
-     * Settings snapshot used to create the tool's current controller; refreshed
-     * when a model switch crosses the coordinate-safe sizing boundary. Surfaced
-     * by `/computer status`.
-     */
-    effectiveConfiguration: Readonly<DesktopSessionOptions>;
     constructor(session: ToolSession, createController?: ComputerControllerFactory);
+    get parameters(): ComputerSchema;
     get description(): string;
-    execute(_toolCallId: string, params: ComputerParams, signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<ComputerToolDetails>, context?: AgentToolContext): Promise<AgentToolResult<ComputerToolDetails>>;
+    execute(_toolCallId: string, params: ComputerToolInput, signal?: AbortSignal, _onUpdate?: AgentToolUpdateCallback<ComputerToolDetails>, _context?: AgentToolContext): Promise<AgentToolResult<ComputerToolDetails>>;
+    capabilities(): Promise<DesktopCapabilities | undefined>;
     close(): Promise<void>;
 }
 export {};

package/dist/types/tools/context.d.ts

@@ -12,6 +12,9 @@ declare module "@oh-my-pi/pi-agent-core" {
          *  wrapper must not re-prompt for the same action (explicit per-tool
          *  policies and overrides still apply). */
         xdevApproved?: boolean;
+        /** Reports the approval tier resolved after an extension rewrites an
+         *  xd:// device call, so dispatch metadata describes the input that ran. */
+        xdevTierResolved?(tier: "read" | "write" | "exec"): void;
         /** Set only after an interactive prompt approves provider computer safety checks. */
         providerSafetyApproved?: boolean;
     }

package/dist/types/tools/default-renderer.d.ts

@@ -11,6 +11,9 @@ export interface DefaultToolRenderInput {
     result?: {
         output: string;
         isError?: boolean;
+        /** Synthetic placeholder for a call skipped mid-batch to service steering/peer
+         * input — the tool never ran, so it renders neutral (info) rather than as an error. */
+        skipped?: boolean;
     };
     /** Current expansion and lifecycle state. */
     options: RenderResultOptions;

package/dist/types/tools/glob.d.ts

@@ -64,7 +64,7 @@ export declare class GlobTool implements AgentTool<typeof findSchema, GlobToolDe
     readonly approval: "read";
     readonly loadMode = "essential";
     readonly label = "Glob";
-    readonly description: string;
+    get description(): string;
     readonly parameters: import("arktype/internal/variants/object.ts").ObjectType<{
         path?: string | undefined;
         hidden?: boolean | undefined;

package/dist/types/tools/grep.d.ts

@@ -78,7 +78,7 @@ export declare class GrepTool implements AgentTool<typeof searchSchema, GrepTool
     readonly label = "Grep";
     readonly loadMode = "discoverable";
     readonly summary = "Grep file contents using ripgrep (fast regex search)";
-    readonly description: string;
+    get description(): string;
     readonly parameters: import("arktype/internal/variants/object.ts").ObjectType<{
         pattern: string;
         path?: string | undefined;

package/dist/types/tools/render-utils.d.ts

@@ -28,6 +28,8 @@ export declare const PREVIEW_LIMITS: {
     readonly OUTPUT_COLLAPSED: 3;
     /** Output preview lines in expanded view */
     readonly OUTPUT_EXPANDED: 10;
+    /** Computer script lines shown in collapsed view */
+    readonly COMPUTER_CODE_COLLAPSED: 10;
     /** Max hunks shown when collapsed (edit tool) */
     readonly DIFF_COLLAPSED_HUNKS: 8;
     /** Max diff lines shown when collapsed (edit tool) */

package/dist/types/tools/{browser/run-cancellation.d.ts → run-scope.d.ts}

@@ -1,7 +1,7 @@
 /**
  * Marks a run-scoped promise as observed without changing its behavior for awaited callers.
  *
- * Browser run teardown aborts can reject promises created for evaluated code after user code
+ * Run teardown aborts can reject promises created for evaluated code after user code
  * has stopped observing them (for example fire-and-forget `wait()`/facade calls). In 16.3.0
  * those zero-consumer rejections reached the process-level `unhandledRejection` handler and
  * killed every subagent sharing the process (issues #4499/#4672). Attaching a no-op rejection
@@ -23,19 +23,19 @@ export interface WaitPredicateOptions {
 /**
  * Effective `wait(predicate)` deadline for a given cell budget. Always strictly below
  * the cell budget so the named `wait(predicate) timed out` error wins the race against
- * the opaque whole-cell "Browser code execution timed out". `0`/`Infinity` ("disable")
- * map to the largest bounded deadline; negative/NaN garbage falls back to the default.
+ * the opaque whole-cell execution timeout. `0`/`Infinity` ("disable") map to the largest
+ * bounded deadline; negative/NaN garbage falls back to the default.
  */
 export declare function resolvePredicateTimeout(cellTimeoutMs: number, explicit?: number): number;
 /**
- * Run-scoped `wait()` helper for evaluated browser code, honoring the owning run's
- * cancellation signal.
+ * Run-scoped `wait()` helper for evaluated code (browser and computer workers), honoring
+ * the owning run's cancellation signal.
  *
  * - `wait(ms)` sleeps for `ms` milliseconds.
  * - `wait(fn, { timeout?, interval? })` polls `fn` (sync or async) until it returns a
  *   truthy value and resolves with that value; throws a named `ToolError` on timeout
  *   instead of stalling into the whole-cell deadline. Predicate errors propagate.
  */
-export declare function waitForBrowserRun(msOrPredicate: number | (() => unknown), signal: AbortSignal, opts?: WaitPredicateOptions): Promise<unknown>;
-/** Binds a long-lived browser facade to one evaluated run's abort signal. */
-export declare function bindBrowserRunFacade<T extends object>(target: T, signal: AbortSignal): T;
+export declare function waitForRun(msOrPredicate: number | (() => unknown), signal: AbortSignal, opts?: WaitPredicateOptions): Promise<unknown>;
+/** Binds a long-lived scope facade (page/tab/desktop objects) to one evaluated run's abort signal. */
+export declare function bindRunFacade<T extends object>(target: T, signal: AbortSignal): T;

package/dist/types/tools/tool-timeouts.d.ts

@@ -22,6 +22,11 @@ export declare const TOOL_TIMEOUTS: {
         readonly min: 1;
         readonly max: 300;
     };
+    readonly computer: {
+        readonly default: 120;
+        readonly min: 1;
+        readonly max: 300;
+    };
     readonly ssh: {
         readonly default: 60;
         readonly min: 1;

package/dist/types/tools/xdev.d.ts

@@ -32,6 +32,7 @@ import type { AgentToolContext, AgentToolResult, AgentToolUpdateCallback, ToolLo
 import { type Component } from "@oh-my-pi/pi-tui";
 import type { RenderResultOptions } from "../extensibility/custom-tools/types.js";
 import type { Theme } from "../modes/theme/theme.js";
+import { type ToolTier } from "./approval.js";
 import type { Tool } from "./index.js";
 import type { ToolRenderer } from "./renderers.js";
 /**
@@ -71,6 +72,13 @@ export interface XdevDispatch {
     mode: "help" | "execute";
     /** Validated inner args, kept for renderer delegation on result rebuilds. */
     args?: Record<string, unknown>;
+    /**
+     * Approval tier of the wrapped tool for {@link args} (`read` = no workspace
+     * mutation). Absent for `help` dispatches and calls whose tier could not be
+     * resolved. Consumed by the prewalk coordinator to skip read-only device
+     * calls when deciding the model hand-off (issue #7312).
+     */
+    tier?: ToolTier;
     /** Details object returned by the wrapped tool, when executed. */
     inner?: unknown;
 }

package/dist/types/utils/clipboard.d.ts

@@ -1,4 +1,4 @@
-import type { ClipboardImage } from "@oh-my-pi/pi-natives";
+import { type ClipboardImage } from "@oh-my-pi/pi-natives/clipboard";
 /**
  * Read file paths from the macOS pasteboard's `public.file-url` representation.
  *
@@ -28,7 +28,7 @@ export declare function copyToClipboard(text: string): Promise<void>;
  * because terminal clipboard paths can leave image payloads invisible to the
  * native bridge.
  *
- * @returns PNG payload or null when no image is available.
+ * @returns A supported image payload or null when no image is available.
  */
 export declare function readImageFromClipboard(): Promise<ClipboardImage | null>;
 /**

package/dist/types/web/kagi.d.ts

@@ -82,6 +82,7 @@ export interface KagiSearchOptions {
     recency?: "day" | "week" | "month" | "year";
     sessionId?: string;
     signal?: AbortSignal;
+    timeoutMs?: number;
     fetch?: FetchImpl;
 }
 export interface KagiSearchSource {

package/dist/types/web/search/index.d.ts

@@ -10,7 +10,7 @@ import { ModelRegistry } from "../../config/model-registry.js";
 import type { CustomTool } from "../../extensibility/custom-tools/types.js";
 import type { ToolSession } from "../../tools/index.js";
 import { type SearchRenderDetails } from "./render.js";
-import type { SearchProviderId } from "./types.js";
+import { type SearchProviderId } from "./types.js";
 /** Web search tool parameters schema */
 export declare const webSearchSchema: import("arktype/internal/variants/object.ts").ObjectType<{
     query: string;

package/dist/types/web/search/providers/anthropic.d.ts

@@ -15,6 +15,7 @@ export interface AnthropicSearchParams {
     max_tokens?: number;
     temperature?: number;
     signal?: AbortSignal;
+    timeoutMs?: number;
     fetch?: FetchImpl;
 }
 /**

package/dist/types/web/search/providers/base.d.ts

@@ -46,6 +46,8 @@ export interface SearchParams {
     recency?: "day" | "week" | "month" | "year";
     systemPrompt: string;
     signal?: AbortSignal;
+    /** Hard timeout for this provider's search transport, in milliseconds. */
+    timeoutMs?: number;
     fetch?: FetchImpl;
     maxOutputTokens?: number;
     numSearchResults?: number;

package/dist/types/web/search/providers/brave.d.ts

@@ -15,6 +15,7 @@ export interface BraveSearchParams {
     recency?: "day" | "week" | "month" | "year";
     parsedQuery?: StructuredQuery;
     signal?: AbortSignal;
+    timeoutMs?: number;
     fetch?: FetchImpl;
 }
 /** Find BRAVE_API_KEY from environment or .env files. */

package/dist/types/web/search/providers/browser-page.d.ts

@@ -21,6 +21,7 @@ interface BrowserFallbackOptions {
 export interface BrowserFetchOptions {
     fetch?: FetchImpl;
     signal: AbortSignal;
+    timeoutMs?: number;
     randomizeHeaders?: boolean;
     referer?: string;
     init?: Omit<RequestInit, "headers" | "signal">;

package/dist/types/web/search/providers/codex.d.ts

@@ -4,6 +4,7 @@ import type { SearchParams } from "./base.js";
 import { SearchProvider } from "./base.js";
 export interface CodexSearchParams {
     signal?: AbortSignal;
+    timeoutMs?: number;
     fetch?: FetchImpl;
     query: string;
     system_prompt?: string;

package/dist/types/web/search/providers/exa.d.ts

@@ -23,6 +23,7 @@ export interface ExaSearchParams {
     start_published_date?: string;
     end_published_date?: string;
     signal?: AbortSignal;
+    timeoutMs?: number;
     fetch?: FetchImpl;
     /**
      * Credential source. Resolved before falling back to `EXA_API_KEY` so

package/dist/types/web/search/providers/firecrawl.d.ts

@@ -15,6 +15,7 @@ export interface FirecrawlSearchParams {
     /** Explicit `tbs` (custom date range); takes precedence over `recency`. */
     tbs?: string;
     signal?: AbortSignal;
+    timeoutMs?: number;
     fetch?: FetchImpl;
 }
 /** Resolve Firecrawl API key through the shared auth storage pipeline. */

package/dist/types/web/search/providers/gemini.d.ts

@@ -31,6 +31,7 @@ export interface GeminiSearchParams extends GeminiToolParams {
     /** Sampling temperature (0–1). Lower = more focused/factual. */
     temperature?: number;
     signal?: AbortSignal;
+    timeoutMs?: number;
     authStorage: AuthStorage;
     sessionId?: string;
     fetch?: FetchImpl;

package/dist/types/web/search/providers/jina.d.ts

@@ -17,6 +17,7 @@ export interface JinaSearchParams {
     /** Single bare host for Jina's `X-Site` in-site search header. */
     site?: string;
     signal?: AbortSignal;
+    timeoutMs?: number;
     fetch?: FetchImpl;
 }
 /** Find JINA_API_KEY from environment or .env files. */

package/dist/types/web/search/providers/kagi.d.ts

@@ -18,6 +18,7 @@ export declare function searchKagi(params: {
     recency?: SearchParams["recency"];
     parsedQuery?: StructuredQuery;
     signal?: AbortSignal;
+    timeoutMs?: number;
     authStorage: AuthStorage;
     sessionId?: string;
     fetch?: FetchImpl;

package/dist/types/web/search/providers/kimi.d.ts

@@ -21,6 +21,7 @@ export interface KimiSearchParams {
     num_results?: number;
     include_content?: boolean;
     signal?: AbortSignal;
+    timeoutMs?: number;
     authStorage: AuthStorage;
     sessionId?: string;
     fetch?: FetchImpl;

package/dist/types/web/search/providers/parallel.d.ts

@@ -7,6 +7,7 @@ export declare function searchParallel(params: {
     query: string;
     num_results?: number;
     signal?: AbortSignal;
+    timeoutMs?: number;
     fetch?: FetchImpl;
     parsedQuery?: StructuredQuery;
 }, authStorage: AuthStorage, sessionId?: string): Promise<SearchResponse>;

package/dist/types/web/search/providers/perplexity.d.ts

@@ -14,6 +14,7 @@ import type { SearchParams } from "./base.js";
 import { SearchProvider } from "./base.js";
 export interface PerplexitySearchParams {
     signal?: AbortSignal;
+    timeoutMs?: number;
     query: string;
     system_prompt?: string;
     /** Pre-parsed view of `query` from the search pipeline; parsed locally when absent. */

package/dist/types/web/search/providers/searxng.d.ts

@@ -44,6 +44,7 @@ export declare function searchSearXNG(params: {
     num_results?: number;
     recency?: "day" | "week" | "month" | "year";
     signal?: AbortSignal;
+    timeoutMs?: number;
     fetch?: FetchImpl;
 }): Promise<SearchResponse>;
 /** Search provider for SearXNG web search. */

package/dist/types/web/search/providers/tavily.d.ts

@@ -21,6 +21,7 @@ export interface TavilySearchParams {
     /** `before:` upper bound, ISO `YYYY-MM-DD`, mapped to `end_date`. */
     end_date?: string;
     signal?: AbortSignal;
+    timeoutMs?: number;
     fetch?: FetchImpl;
 }
 /** Find Tavily API key through AuthStorage's unified refresh pipeline. */

package/dist/types/web/search/providers/tinyfish.d.ts

@@ -14,6 +14,7 @@ export interface TinyFishSearchParams {
     recency?: SearchParams["recency"];
     page?: number;
     signal?: AbortSignal;
+    timeoutMs?: number;
     fetch?: FetchImpl;
 }
 /** Resolve TinyFish API key through the shared auth storage pipeline. */

package/dist/types/web/search/providers/utils.d.ts

@@ -15,16 +15,13 @@ import { SearchProviderError, type SearchProviderId, type SearchSource } from ".
  */
 export declare function findCredential(storage: AgentStorage | null | undefined, envKey: string | null | undefined, ...storageProviders: string[]): string | null;
 /**
- * Default hard ceiling for a single web-search round-trip. 60s tolerates
- * legitimate slow LLM-mediated responses (anthropic web_search_20250305,
- * perplexity, gemini, codex) while still guaranteeing the session unfreezes
- * within a minute if Bun's `AbortSignal` fails to propagate on Windows.
- *
- * Pure search APIs (brave, exa, jina, tavily, searxng, synthetic, zai)
- * settle far faster in practice; reusing the same ceiling keeps the wiring
- * uniform without compromising correctness.
+ * The 60-second default tolerates legitimate slow LLM-mediated responses
+ * (Anthropic web_search_20250305, Perplexity, Gemini, Codex) while bounding
+ * Windows stalls when Bun's `AbortSignal` fails to propagate. Callers may
+ * configure a longer provider deadline, capped at five minutes by the
+ * dispatcher; pure search APIs typically settle far faster.
  */
-export declare const SEARCH_HARD_TIMEOUT_MS = 60000;
+export declare const SEARCH_HARD_TIMEOUT_MS: number;
 /**
  * Compose a caller-supplied {@link AbortSignal} with a hard timeout so an
  * outbound `fetch()` is guaranteed to settle within `ms` even when the

package/dist/types/web/search/providers/zai.d.ts

@@ -12,6 +12,7 @@ export interface ZaiSearchParams {
     query: string;
     num_results?: number;
     signal?: AbortSignal;
+    timeoutMs?: number;
     fetch?: FetchImpl;
     authStorage: AuthStorage;
     sessionId?: string;

package/dist/types/web/search/types.d.ts

@@ -100,6 +100,10 @@ export declare const SEARCH_PROVIDER_OPTIONS: readonly [{
     readonly label: "Public Web";
     readonly description: "Queries every credential-free engine in parallel and consolidates deduplicated results";
 }];
+/** Default hard timeout for each web-search provider transport. */
+export declare const DEFAULT_WEB_SEARCH_TIMEOUT_SECONDS = 60;
+/** Maximum configurable hard timeout for each web-search provider transport. */
+export declare const MAX_WEB_SEARCH_TIMEOUT_SECONDS = 300;
 /** Supported web search providers (every option except `auto`). */
 export type SearchProviderId = Exclude<(typeof SEARCH_PROVIDER_OPTIONS)[number]["value"], "auto">;
 /**