@mono-agent/agent-runtime 0.15.3 → 0.15.4

package/src/runtime.js

@@ -140,7 +140,48 @@ export function createRuntime(host = {}) {
   // THIS object so later runs of this instance observe the update.
   const toolContext = createToolContext({ ...toolRuntime, runtimeBrand });
 
-  return {
+  /** @type {*} */
+  let self;
+
+  /**
+   * Kernel fallback for `subagents.run`, so the `Agent` built-in works from a
+   * bare `createRuntime` with no host wiring. Hosts replace it to route child
+   * turns through their own runtime (fallback chain, retries, recording).
+   *
+   * Scope of the guarantee, precisely: this fallback rebuilds the child bag with
+   * stripped session/steering state, but a HOST-SUPPLIED `run` is installed
+   * verbatim and is a privileged seam — it is responsible for its own session
+   * isolation. Recursion is blocked independently of the callback: the `Agent`
+   * tool stamps `depth + 1` into every descriptor it hands out, and
+   * `getPiBuiltinTools` refuses to register the tool at depth >= 1, so a custom
+   * callback cannot produce a grandchild even if it ignores the rest.
+   * @param {*} request
+   */
+  const defaultSubagentRun = async (request) => self.run(request.systemPrompt, {
+    model: request.model,
+    // A child must never be less confined than its parent. The policy is a
+    // per-run option, not a host key, so without forwarding it the child would
+    // run with no sandbox at all — and its default tools include WebFetch and
+    // WebSearch, so even a read-only profile could bypass network policy.
+    ...(request.sandboxPolicy === undefined ? {} : { sandboxPolicy: request.sandboxPolicy }),
+    ...(request.sandboxEngine === undefined ? {} : { sandboxEngine: request.sandboxEngine }),
+    ...(request.executionMode === undefined ? {} : { executionMode: request.executionMode }),
+    ...(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
+    // parent's level while reporting the profile's.
+    ...(request.definition?.effort === undefined ? {} : { effort: request.definition.effort }),
+    messages: [{ role: "user", content: request.prompt }],
+    maxTurns: request.maxTurns,
+    allowedTools: request.definition?.allowedTools,
+    disallowedTools: request.definition?.disallowedTools,
+    mcpServers: request.definition?.mcpServers ?? {},
+    abortSignal: request.abortSignal,
+    onEvent: request.onEvent,
+    subagents: { depth: (request.depth ?? 1) },
+  });
+
+  self = {
     /**
      * @param {string} systemPrompt
      * @param {Partial<RuntimeRunOptions>} [options] Optional only so the
@@ -162,9 +203,16 @@ export function createRuntime(host = {}) {
       });
       const liveInput = instrumentLiveInputAppliedEvents(options.liveInput, hub.emit);
       const prompts = resolvePrompts(host.prompts, options.prompts);
+      // Default the nested-run callback so the Agent built-in is usable without
+      // host wiring; the depth field is left exactly as the caller set it, since
+      // defaultSubagentRun is what increments it for the child.
+      const subagents = options.subagents === undefined
+        ? undefined
+        : { ...options.subagents, run: options.subagents.run ?? defaultSubagentRun };
       const result = await bridge.execute(systemPrompt, {
         ...hostDefaults,
         ...options,
+        ...(subagents === undefined ? {} : { subagents }),
         // `...options` alone doesn't carry the `options.model` narrowing above
         // (spread reads the parameter's declared — Partial — type); re-assert
         // the already-validated model so the request satisfies RuntimeRequest.
@@ -204,4 +252,6 @@ export function createRuntime(host = {}) {
       return disposeAllProviderSessions();
     },
   };
+
+  return self;
 }

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

@@ -0,0 +1,60 @@
+/**
+ * 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?: *, onEvent?: (event: *) => void}} [context]
+ * @returns {*|null}
+ */
+export function createAgentTool(subagents: RuntimeSubagentsOptions | null | undefined, context?: {
+    model?: any;
+    executionMode?: string;
+    cwd?: string;
+    parentRunId?: string;
+    sandboxPolicy?: any;
+    sandboxEngine?: any;
+    onEvent?: (event: any) => void;
+}): any | null;
+/**
+ * A subagent that fails, times out, or says nothing still returns its activity
+ * log: that log is the most useful artifact of a failed delegation, and a
+ * thrown tool error would discard it.
+ *
+ * @param {{profileName: string, label?: string, outcome: {status: string, answer: string, reason?: string}, durationMs: number, activity: ReadonlyArray<{name: string, args: unknown, ms?: number, isError: boolean}>, maxBytes?: number, cwd?: string, notice?: string}} input
+ * @returns {string}
+ */
+export function formatSubagentResult({ profileName, label, outcome, durationMs, activity, maxBytes, cwd, notice }: {
+    profileName: string;
+    label?: string;
+    outcome: {
+        status: string;
+        answer: string;
+        reason?: string;
+    };
+    durationMs: number;
+    activity: ReadonlyArray<{
+        name: string;
+        args: unknown;
+        ms?: number;
+        isError: boolean;
+    }>;
+    maxBytes?: number;
+    cwd?: string;
+    notice?: string;
+}): string;
+/** @typedef {import('../../ai/types.js').RuntimeSubagentDefinition} RuntimeSubagentDefinition */
+/** @typedef {import('../../ai/types.js').RuntimeSubagentsOptions} RuntimeSubagentsOptions */
+export const GENERAL_PURPOSE_SUBAGENT: "general-purpose";
+/**
+ * Read-only by default. A profile that needs a shell or writes must say so in
+ * config: widening a subagent's reach is an operator decision, not one the
+ * model makes at call time.
+ */
+export const DEFAULT_SUBAGENT_TOOLS: readonly string[];
+/**
+ * Never available to a subagent, whatever a profile asks for. `Agent` is the
+ * third independent recursion lock; the rest would let a helper hijack the
+ * user's conversation or post to a channel on the main agent's behalf.
+ */
+export const SUBAGENT_HARD_DENY: readonly string[];
+export type RuntimeSubagentDefinition = import("../../ai/types.js").RuntimeSubagentDefinition;
+export type RuntimeSubagentsOptions = import("../../ai/types.js").RuntimeSubagentsOptions;

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

@@ -1,16 +1,64 @@
-export function normalizeBashTimeoutMs(value: any, fallback?: number): number;
 /**
- * @param {{command: string, timeout?: number, max_output_chars?: number, workdir?: string}} params
- * @param {{signal?: any, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any}} [options]
+ * Legacy Bash timeout normalization. Values up to 600 are seconds; larger
+ * values are milliseconds. New callers should use `timeout_ms`.
  */
-export function bashToolImpl({ command, timeout, max_output_chars, workdir }: {
+export function normalizeBashTimeoutMs(value: any, fallback?: number): any;
+/**
+ * Exact millisecond timeout used by Bash.timeout_ms and Exec.timeout_ms.
+ */
+export function normalizeProcessTimeoutMs(value: any, fallback?: number): any;
+/**
+ * Compatibility wrapper retained for direct callers and tests.
+ *
+ * @param {{command: string, timeout?: number, timeout_ms?: number, max_output_chars?: number, workdir?: string}} params
+ * @param {{signal?: AbortSignal, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any}} [options]
+ */
+export function bashToolImpl(params: {
+    command: string;
+    timeout?: number;
+    timeout_ms?: number;
+    max_output_chars?: number;
+    workdir?: string;
+}, options?: {
+    signal?: AbortSignal;
+    sandboxPolicy?: any;
+    sandboxEngine?: any;
+    ctx?: any;
+}): Promise<any>;
+/**
+ * Structured Bash execution used by the Pi bridge.
+ *
+ * @param {{command: string, timeout?: number, timeout_ms?: number, max_output_chars?: number, workdir?: string}} params
+ * @param {{signal?: AbortSignal, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any}} [options]
+ */
+export function bashToolRun({ command, timeout, timeout_ms, max_output_chars, workdir, }: {
     command: string;
     timeout?: number;
+    timeout_ms?: number;
     max_output_chars?: number;
     workdir?: string;
-}, { signal, sandboxPolicy, sandboxEngine, ctx }?: {
-    signal?: any;
+}, { signal, sandboxPolicy, sandboxEngine, ctx, }?: {
+    signal?: AbortSignal;
     sandboxPolicy?: any;
     sandboxEngine?: any;
     ctx?: any;
-}): Promise<string>;
+}): Promise<{
+    text: any;
+    outcome: {
+        status: string;
+        code: any;
+        retryable: boolean;
+        attempts: number;
+        durationMs: number;
+        bytes: number;
+        truncated: boolean;
+        exitCode: any;
+        signal: any;
+        timedOut: boolean;
+    };
+    error: boolean;
+} | {
+    text: string;
+    outcome: any;
+    error: boolean;
+}>;

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

@@ -0,0 +1,53 @@
+/**
+ * @param {{executable: string, args?: string[], workdir?: string, timeout_ms?: number, max_output_chars?: number}} params
+ * @param {{signal?: AbortSignal, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any}} [options]
+ */
+export function execToolImpl(params: {
+    executable: string;
+    args?: string[];
+    workdir?: string;
+    timeout_ms?: number;
+    max_output_chars?: number;
+}, options?: {
+    signal?: AbortSignal;
+    sandboxPolicy?: any;
+    sandboxEngine?: any;
+    ctx?: any;
+}): Promise<any>;
+/**
+ * Execute an argv vector directly, without shell parsing.
+ *
+ * @param {{executable: string, args?: string[], workdir?: string, timeout_ms?: number, max_output_chars?: number}} params
+ * @param {{signal?: AbortSignal, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any}} [options]
+ */
+export function execToolRun({ executable, args, workdir, timeout_ms, max_output_chars, }: {
+    executable: string;
+    args?: string[];
+    workdir?: string;
+    timeout_ms?: number;
+    max_output_chars?: number;
+}, { signal, sandboxPolicy, sandboxEngine, ctx, }?: {
+    signal?: AbortSignal;
+    sandboxPolicy?: any;
+    sandboxEngine?: any;
+    ctx?: any;
+}): Promise<{
+    text: any;
+    outcome: {
+        status: string;
+        code: any;
+        retryable: boolean;
+        attempts: number;
+        durationMs: number;
+        bytes: number;
+        truncated: boolean;
+        exitCode: any;
+        signal: any;
+        timedOut: boolean;
+    };
+    error: boolean;
+} | {
+    text: string;
+    outcome: any;
+    error: any;
+}>;

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

@@ -3,8 +3,10 @@ export { writeToolImpl } from "./write.js";
 export { editToolImpl } from "./edit.js";
 export { globToolImpl } from "./glob.js";
 export { grepToolImpl } from "./grep.js";
-export { webFetchToolImpl } from "./web-fetch.js";
-export { webSearchToolImpl } from "./web-search.js";
+export { createWebToolController } from "./web-controller.js";
 export { resolveRgPath } from "./shared/ripgrep.js";
-export { bashToolImpl, normalizeBashTimeoutMs } from "./bash.js";
+export { bashToolImpl, bashToolRun, normalizeBashTimeoutMs, normalizeProcessTimeoutMs } from "./bash.js";
+export { execToolImpl, execToolRun } from "./exec.js";
+export { webFetchToolImpl, performWebFetch } from "./web-fetch.js";
+export { webSearchToolImpl, performWebSearch } from "./web-search.js";
 export { isPathAllowed, isWorkdirAllowed } from "./shared/path-resolver.js";

package/types/agent/tools/node-repl.d.ts

@@ -9,11 +9,36 @@ export function createNodeReplController({ cwd, maxOutputChars, sandboxPolicy, s
     sandboxEngine?: any;
     ctx?: any;
 }): {
-    /** @param {{code: string}} params @param {{signal?: AbortSignal}} [execution] */
-    execute({ code }: {
+    execute: ({ code }: {
         code: string;
     }, { signal }?: {
         signal?: AbortSignal;
-    }): Promise<any>;
+    }) => Promise<any>;
+    /** Structured result used by the Pi bridge so telemetry does not depend on text prefixes. */
+    executeDetailed(params: any, execution?: {}): Promise<{
+        text: any;
+        outcome: {
+            status: string;
+            code: string;
+            retryable: boolean;
+            attempts: number;
+            durationMs: number;
+            bytes: number;
+            truncated: boolean;
+        };
+        error: boolean;
+    } | {
+        text: string;
+        outcome: {
+            status: string;
+            code: any;
+            retryable: boolean;
+            attempts: number;
+            durationMs: number;
+            bytes: number;
+            truncated: boolean;
+        };
+        error: boolean;
+    }>;
     close(): Promise<void>;
 };

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, 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, 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, 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, subagents, subagentContext, toolExecutionMode, ctx, }?: {
     disallowedTools?: any[];
     skillNames?: any[];
     skills?: any[];
@@ -56,6 +56,10 @@ export function getPiBuiltinTools(allowedTools: any, { disallowedTools, skillNam
     approvalManager?: any;
     approvalModel?: any;
     nodeReplController?: any;
+    webController?: any;
+    toolExecutionMode?: "sequential" | "safe-parallel";
+    subagents?: any;
+    subagentContext?: any;
     ctx?: any;
 }): any[];
 export function resolveMcpStdioCwd(cfg?: {}, cwd?: any): any;

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

@@ -0,0 +1,33 @@
+/**
+ * Run one already-prepared executable without adding a shell.
+ *
+ * The result is deliberately loss-aware: stdout/stderr are retained up to the
+ * shared byte cap even when the child times out, is aborted, exits by signal,
+ * or exceeds that cap.
+ *
+ * @param {{command: string, args?: string[], cwd?: string, env?: Record<string, string|undefined>}} commandSpec
+ * @param {{timeoutMs?: number, signal?: AbortSignal, maxBufferBytes?: number}} [options]
+ */
+export function runPreparedProcess(commandSpec: {
+    command: string;
+    args?: string[];
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+}, { timeoutMs, signal, maxBufferBytes, }?: {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    maxBufferBytes?: number;
+}): Promise<any>;
+/**
+ * @param {import("node:child_process").ChildProcess} child
+ * @param {NodeJS.Signals} signal
+ */
+export function killProcessGroup(child: import("node:child_process").ChildProcess, signal: NodeJS.Signals): void;
+/**
+ * @param {{stdout?: string, stderr?: string}} result
+ */
+export function combinedProcessOutput(result: {
+    stdout?: string;
+    stderr?: string;
+}): string;
+export const DEFAULT_PROCESS_BUFFER_BYTES: number;

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

@@ -0,0 +1,29 @@
+/**
+ * @typedef {Object} CountingSemaphore
+ * @property {(signal?: AbortSignal) => Promise<() => void>} acquire Resolves with
+ *   a single-use release function once a slot is free. Rejects if `signal`
+ *   aborts while queued; an already-acquired slot is never leaked.
+ * @property {() => number} inFlight Slots currently held.
+ * @property {() => number} queued Waiters not yet admitted.
+ */
+/**
+ * @param {number} limit Maximum simultaneous holders. Values below 1 are clamped.
+ * @returns {CountingSemaphore}
+ */
+export function createCountingSemaphore(limit: number): CountingSemaphore;
+export type CountingSemaphore = {
+    /**
+     * Resolves with
+     * a single-use release function once a slot is free. Rejects if `signal`
+     * aborts while queued; an already-acquired slot is never leaked.
+     */
+    acquire: (signal?: AbortSignal) => Promise<() => void>;
+    /**
+     * Slots currently held.
+     */
+    inFlight: () => number;
+    /**
+     * Waiters not yet admitted.
+     */
+    queued: () => number;
+};

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

@@ -0,0 +1,16 @@
+/**
+ * Render one public page in a fresh anonymous agent-browser session.
+ *
+ * @param {string} url
+ * @param {{browserCommand?: string, namespace?: string, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, signal?: AbortSignal, registerCleanup?: (cleanup: () => Promise<void>) => () => void}} [options]
+ */
+export function renderWithAgentBrowser(url: string, { browserCommand, namespace, sandboxPolicy, sandboxEngine, ctx, signal, registerCleanup, }?: {
+    browserCommand?: string;
+    namespace?: string;
+    sandboxPolicy?: any;
+    sandboxEngine?: any;
+    ctx?: any;
+    signal?: AbortSignal;
+    registerCleanup?: (cleanup: () => Promise<void>) => () => void;
+}): Promise<any>;
+export function extractBrowserText(output: any): any;

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

@@ -0,0 +1,20 @@
+/**
+ * One ephemeral web-tool controller for one model run. It owns in-memory
+ * deduplication, result caches, anonymous browser namespaces, and cleanup.
+ *
+ * @param {{searchConfig?: any, fetchConfig?: any, sandboxPolicy?: any, sandboxEngine?: any, ctx?: any, fetchImpl?: typeof fetch, browserRenderer?: any}} [options]
+ */
+export function createWebToolController({ searchConfig, fetchConfig, sandboxPolicy, sandboxEngine, ctx, fetchImpl, browserRenderer, }?: {
+    searchConfig?: any;
+    fetchConfig?: any;
+    sandboxPolicy?: any;
+    sandboxEngine?: any;
+    ctx?: any;
+    fetchImpl?: typeof fetch;
+    browserRenderer?: any;
+}): {
+    namespace: string;
+    search(params: any, execution?: {}): Promise<any>;
+    fetch(params: any, execution?: {}): Promise<any>;
+    close(): Promise<void>;
+};

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

@@ -1,13 +1,82 @@
 /**
- * @param {{url: string, headers?: Record<string, string>, max_output_chars?: number}} params
- * @param {{sandboxPolicy?: any, ctx?: any, retryDelaysMs?: number[]}} [options]
+ * 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]
  */
-export function webFetchToolImpl({ url, headers, max_output_chars }: {
+export function webFetchToolImpl(params: {
     url: string;
     headers?: Record<string, string>;
     max_output_chars?: number;
-}, { sandboxPolicy, ctx, retryDelaysMs }?: {
+    format?: string;
+    render?: string;
+}, options?: {
     sandboxPolicy?: any;
+    sandboxEngine?: any;
     ctx?: any;
+    signal?: AbortSignal;
     retryDelaysMs?: number[];
-}): Promise<string>;
+    fetchConfig?: any;
+    fetchImpl?: typeof fetch;
+    browserRenderer?: typeof renderWithAgentBrowser;
+    namespace?: string;
+    registerCleanup?: (cleanup: () => Promise<void>) => () => void;
+}): Promise<any>;
+/**
+ * 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]
+ */
+export function performWebFetch({ url, headers, max_output_chars, format, render, }: {
+    url: string;
+    headers?: Record<string, string>;
+    max_output_chars?: number;
+    format?: string;
+    render?: string;
+}, { sandboxPolicy, sandboxEngine, ctx, signal, retryDelaysMs, fetchConfig, fetchImpl, browserRenderer, namespace, registerCleanup, }?: {
+    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;
+}): Promise<{
+    text: any;
+    outcome: {
+        status: string;
+        code: any;
+        retryable: boolean;
+        attempts: number;
+        backend: string;
+        cacheHit: boolean;
+        durationMs: number;
+        bytes: number;
+        truncated: boolean;
+    };
+    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;
+    };
+    error: boolean;
+}>;
+import { renderWithAgentBrowser } from "./web-browser-render.js";

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

@@ -1,11 +1,87 @@
 /**
- * @param {{query: string, limit?: number}} params
- * @param {{sandboxPolicy?: any, ctx?: any}} [options]
+ * Compatibility wrapper for direct callers.
+ *
+ * @param {{query: string, limit?: number, alternate_queries?: string[], domains?: string[], exclude_domains?: string[], language?: string, time_range?: string}} params
+ * @param {{sandboxPolicy?: any, ctx?: any, signal?: AbortSignal, searchConfig?: any, fetchImpl?: typeof fetch}} [options]
  */
-export function webSearchToolImpl({ query, limit }: {
+export function webSearchToolImpl(params: {
     query: string;
     limit?: number;
-}, { sandboxPolicy, ctx }?: {
+    alternate_queries?: string[];
+    domains?: string[];
+    exclude_domains?: string[];
+    language?: string;
+    time_range?: string;
+}, options?: {
     sandboxPolicy?: any;
     ctx?: any;
-}): Promise<string>;
+    signal?: AbortSignal;
+    searchConfig?: any;
+    fetchImpl?: typeof fetch;
+}): Promise<any>;
+/**
+ * Search through an operator-owned SearXNG endpoint and/or the keyless HTML
+ * fallback chain. Returns a structured internal outcome for the Pi bridge.
+ *
+ * @param {{query: string, limit?: number, alternate_queries?: string[], domains?: string[], exclude_domains?: string[], language?: string, time_range?: string}} params
+ * @param {{sandboxPolicy?: any, ctx?: any, signal?: AbortSignal, searchConfig?: any, fetchImpl?: typeof fetch}} [options]
+ */
+export function performWebSearch({ query, limit, alternate_queries, domains, exclude_domains, language, time_range, }: {
+    query: string;
+    limit?: number;
+    alternate_queries?: string[];
+    domains?: string[];
+    exclude_domains?: string[];
+    language?: string;
+    time_range?: string;
+}, { sandboxPolicy, ctx, signal, searchConfig, fetchImpl, }?: {
+    sandboxPolicy?: any;
+    ctx?: any;
+    signal?: AbortSignal;
+    searchConfig?: any;
+    fetchImpl?: typeof fetch;
+}): Promise<{
+    text: any;
+    outcome: {
+        status: string;
+        code: any;
+        retryable: boolean;
+        attempts: number;
+        backend: string;
+        cacheHit: boolean;
+        durationMs: number;
+        bytes: number;
+        truncated: boolean;
+    };
+    error: boolean;
+} | {
+    text: string;
+    outcome: {
+        status: string;
+        code: string;
+        retryable: boolean;
+        attempts: number;
+        backend: any;
+        cacheHit: boolean;
+        durationMs: number;
+        bytes: number;
+        truncated: boolean;
+        resultCount: number;
+        providerFailureCount: number;
+    };
+    error: boolean;
+}>;
+export function parseDuckDuckGoResults(html: any): {
+    title: string;
+    url: string;
+    snippet: string;
+    backend: string;
+}[];
+export function parseStartpageResults(html: any): {
+    title: string;
+    url: string;
+    snippet: string;
+    backend: string;
+}[];
+export function canonicalizeSearchUrl(value: any, base: any): string;
+export function mergeRankedResults(rankedLists: any, limit?: number): any[];