@mono-agent/agent-runtime 0.15.3 → 0.16.0

package/src/ai/types.js

@@ -147,7 +147,8 @@
  * @property {boolean} [fastMode]
  * @property {string} [cwd]
  * @property {Object<string, Object>} [mcpServers]
- * @property {ReadonlyArray<Object>} [skills]             Runtime skill metadata for progressive disclosure.
+ * @property {ReadonlyArray<{name: string, description?: string}>} [skills] Skills disclosed to this run, as `{name, description}`. Non-empty makes `supports_skills` a routing requirement (see router.js), so a chain entry that lacks it is skipped.
+ * @property {string} [skillsRoot]                       Directory holding `<name>/SKILL.md`. Required alongside `skills` for `ReadSkill` to be built.
  * @property {ReadonlyArray<string>} [allowedTools]
  * @property {ReadonlyArray<string>} [disallowedTools]
  * @property {string} [permissionMode]
@@ -161,8 +162,13 @@
  * @property {RuntimeToolLimits} [toolLimits] Typed per-run tool-output limits (supported replacement for the deprecated `settings` tool keys).
  * @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"|"keyless", endpoint?: string}} [webSearchConfig] Run-scoped WebSearch backend configuration.
+ * @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 {Object} [nativeSubagents] Same-runtime teammate helpers exposed through native provider subagent surfaces.
+ * @property {RuntimeSubagentsOptions} [subagents] In-process `Agent` built-in: profiles, caps, and the nested-run callback.
  * @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
  *   bridge in this package today.
@@ -185,6 +191,52 @@
  * hub's emit). `systemPrompt` is passed positionally, not folded into this object.
  */
 
+/**
+ * @typedef {Object} RuntimeSubagentDefinition
+ * One named subagent profile the `Agent` built-in can deploy.
+ * @property {string} name Model-visible identifier and the tool's `name` enum value.
+ * @property {string} description Model-visible: when to pick this profile.
+ * @property {string} systemPrompt Full system prompt for the child run.
+ * @property {RuntimeModelRef} [model] Absent inherits the parent's configured route.
+ * @property {string} [effort]
+ * @property {ReadonlyArray<string>} [allowedTools] Absent uses the safe read-only default set.
+ * @property {ReadonlyArray<string>} [disallowedTools]
+ * @property {Object<string, Object>} [mcpServers]
+ * @property {number} [maxTurns]
+ * @property {number} [timeoutMs]
+ */
+
+/**
+ * @callback RuntimeSubagentRun
+ * Owning-layer callback that actually executes one child turn. The kernel
+ * supplies a self-run fallback so `createRuntime` works without host wiring;
+ * agent-app replaces it so subagent runs get the configured fallback chain,
+ * same-model retries, and run recording.
+ * @param {Object} request
+ * @returns {Promise<RuntimeResult>}
+ */
+
+/**
+ * @typedef {Object} RuntimeInlineSubagentsOptions
+ * Policy for subagents the model authors at call time rather than picking from
+ * `definitions`. Absent suppresses authoring entirely.
+ * @property {boolean} [enabled] Only `false` turns authoring off.
+ * @property {ReadonlyArray<string>} [allowedTools] Ceiling on what an authored subagent may
+ *   request. Absent means the safe read-only default set, never every built-in.
+ */
+
+/**
+ * @typedef {Object} RuntimeSubagentsOptions
+ * @property {ReadonlyArray<RuntimeSubagentDefinition>} [definitions] Named profiles.
+ * @property {RuntimeInlineSubagentsOptions} [inline] Call-time authoring policy.
+ * @property {number} [maxConcurrent] In-flight subagents per parent turn. Default 5.
+ * @property {number} [maxPerTurn] Total Agent calls per parent turn. Default 20.
+ * @property {number} [maxTurns] Default per-subagent turn cap. Default 100.
+ * @property {number} [timeoutMs] Default per-subagent wall clock.
+ * @property {RuntimeSubagentRun} [run] Nested-run callback; absent uses the kernel self-run.
+ * @property {number} [depth] Kernel-owned. Absent/0 is the parent; >=1 suppresses the `Agent` tool.
+ */
+
 /**
  * @typedef {Object} RuntimeResult
  * @property {string|null} [text]
@@ -206,7 +258,7 @@
  * @property {Array<Object>} [runtimeWarnings]
  * @property {Object} [diagnostics]
  * @property {Object} [capabilitiesUsed]
- * @property {Array<{model: RuntimeModelRef, failureKind: (string|null), requestId?: (string|null), retryableSubkind?: (string|null), requirements?: Object, routeSafety?: RuntimeRouteSafetyMode, safetyContract?: RuntimeRouteSafetyContract}>} [failoverHistory] Set by createRouterRuntime (ai/runtime/router.js) on every failed/skipped attempt.
+ * @property {Array<{model: RuntimeModelRef, failureKind: (string|null), requestId?: (string|null), retryableSubkind?: (string|null), retryIndex?: number, requirements?: Object, routeSafety?: RuntimeRouteSafetyMode, safetyContract?: RuntimeRouteSafetyContract}>} [failoverHistory] Set by createRouterRuntime (ai/runtime/router.js) on every failed/skipped attempt.
  * @property {Array<{attemptIndex: number, model: RuntimeModelRef, routeSafety: RuntimeRouteSafetyMode, safetyContract: RuntimeRouteSafetyContract, status: string}>} [routeSafetyHistory] Bounded route-safety audit emitted by createRouterRuntime.
  */
 

package/src/pi-auth.js

@@ -4,7 +4,7 @@ import { realpathSync } from "node:fs";
 import { chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
 import { basename, dirname, join, resolve } from "node:path";
 
-import { getOAuthApiKey } from "@earendil-works/pi-ai/oauth";
+import { resolveOAuthApiKey } from "./ai/pi-oauth-compat.js";
 
 /**
  * @typedef {{type: "api_key", key?: string, env?: Object<string, *>}} PiApiKeyCredential
@@ -41,7 +41,7 @@ export function createPiOAuthApiKeyResolver(options = {}) {
         return undefined;
       }
 
-      const result = await getOAuthApiKey(provider, cloneAuth(auth));
+      const result = await resolveOAuthApiKey(provider, cloneAuth(auth));
       if (result === null || result === undefined || typeof result.apiKey !== "string" || result.apiKey.length === 0) {
         return undefined;
       }

package/src/runtime.js

@@ -140,7 +140,55 @@ 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 }),
+    // The parent's disclosed skills, for the same reason: they are a per-run
+    // option, so a child that does not receive them has no ReadSkill tool and no
+    // index, and must rediscover by trial and error what its parent could look
+    // up. A host-supplied `run` may gate this; the default has no route or deny
+    // list of its own to consult, so it forwards what it was given.
+    ...(request.skills === undefined ? {} : { skills: request.skills }),
+    ...(request.skillsRoot === undefined ? {} : { skillsRoot: request.skillsRoot }),
+    ...(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 +210,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 +259,6 @@ export function createRuntime(host = {}) {
       return disposeAllProviderSessions();
     },
   };
+
+  return self;
 }

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

@@ -0,0 +1,80 @@
+/**
+ * How many subagents this logical run actually spawned.
+ *
+ * A read-only accessor so a provider can report `subagent_invoked` truthfully
+ * without reaching into `__budgets`, which is a deliberately private,
+ * non-enumerable implementation detail. Returns 0 when nothing was ever
+ * registered — a run with no `Agent` tool never creates a budget entry, and that
+ * is indistinguishable from one that had the tool and never used it, which is
+ * exactly what "no subagent was invoked" means for this signal.
+ *
+ * @param {*} subagents The run-scoped options object, or undefined.
+ * @param {string|undefined} parentRunId
+ * @returns {number}
+ */
+export function subagentInvocationCount(subagents: any, parentRunId: string | undefined): number;
+/**
+ * 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, 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;
+    skills?: {
+        name: string;
+        description?: string;
+    }[];
+    skillsRoot?: string;
+    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";