@capybara-hq/kernel 0.1.0-rc.3 → 0.1.0-rc.4

package/dist/tools/builtins/sandbox/task-output.js

@@ -0,0 +1,304 @@
+import { setTimeout as sleep } from "node:timers/promises";
+import { isSandboxGoneError, ToolError, } from "@capybara-hq/plugin-sdk";
+import { TASK_ID_RE, TASKS_DIR } from "../../../background/launch.js";
+import { formatElapsed, lostReasonText } from "../../../background/render.js";
+import { SID_RE } from "../../../background/session.js";
+import { parsePollOutput, polledAs, pollScript, } from "../../../background/status.js";
+import { notRunningAs, RECREATED } from "../../../background/stop.js";
+import { clip, display, mapSandboxError, noSandboxError, runTimeLeftMs, sandboxBaseTimeoutMs, unavailableWhenNoSandbox, } from "./common.js";
+/** How long `TaskOutput` waits with `block` when `timeout` is not given (ms). */
+export const TASK_OUTPUT_DEFAULT_TIMEOUT_MS = 30_000;
+/** The longest `TaskOutput` wait (ms). */
+export const TASK_OUTPUT_MAX_TIMEOUT_MS = 600_000;
+/** How often a blocking `TaskOutput` checks the task (each check a short exec of its own). */
+export const TASK_CHECK_INTERVAL_MS = 2000;
+/** The time limit of one check or read exec. */
+const READ_EXEC_TIMEOUT_MS = 30_000;
+const SPEC = {
+    name: "TaskOutput",
+    // Display only (the tool row; not in the fingerprint, never sent to the model).
+    keyArgs: ["task_id"],
+    description: "Read the status and output of a background task started with Bash and run_in_background. " +
+        "The result has the status (running, completed, failed, stopped, timed out or lost), the " +
+        "exit code and the elapsed time, then the output the task wrote since the last TaskOutput " +
+        "call for it. With block (the default) it waits until the task finishes or timeout " +
+        "milliseconds pass, checking every 2 seconds; prefer this over sleeping in Bash. Each call " +
+        "returns a bounded slice of new output; the task's whole output file (its path is in the Bash " +
+        "result) can also be read with Read. You are told when a task finishes, so there is no need " +
+        "to poll for that.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            task_id: {
+                type: "string",
+                minLength: 1,
+                description: "The id of the background task (bt_...) that Bash returned.",
+            },
+            block: {
+                type: "boolean",
+                description: "Whether to wait for the task to finish. Default true.",
+            },
+            timeout: {
+                type: "number",
+                minimum: 0,
+                maximum: TASK_OUTPUT_MAX_TIMEOUT_MS,
+                description: `Milliseconds to wait at most when block is true. Default ${TASK_OUTPUT_DEFAULT_TIMEOUT_MS}, at most ${TASK_OUTPUT_MAX_TIMEOUT_MS}; never past the run's own time limit.`,
+            },
+        },
+        required: ["task_id"],
+        additionalProperties: false,
+    },
+};
+/** The task tools' dependencies; throws the tool's error when they are missing. */
+export function taskEnv(deps) {
+    if (!deps.sandbox.available)
+        throw noSandboxError();
+    const { background, tasks } = deps;
+    if (!background || !tasks || !deps.sandbox.ifRunning) {
+        throw new ToolError("Background tasks are not available here; use Bash without run_in_background instead.");
+    }
+    return { store: background, tasks, ifRunning: deps.sandbox.ifRunning.bind(deps.sandbox) };
+}
+const notFound = (id) => new ToolError(`No background task ${clip(id, 40)} in this conversation. Pass a task id that Bash with run_in_background returned in this conversation.`);
+/**
+ * The task `id` when it belongs to the calling conversation; a task of another conversation (a
+ * sub-agent's, when called from its parent) is not found, the same as an unknown id.
+ */
+export async function ownedTask(env, ctx, id) {
+    if (!TASK_ID_RE.test(id))
+        throw notFound(id);
+    const task = await env.store.get(id);
+    if (!task || task.conversationId !== ctx.conversationId)
+        throw notFound(id);
+    return task;
+}
+/** `ifRunning` on the task's own sandbox instance; sandbox errors become the tools' errors. */
+export async function onTaskInstance(env, task, fn, signal) {
+    try {
+        return await env.ifRunning(task.sandboxConversationId, { createdAt: task.sandboxCreatedAt }, fn, signal);
+    }
+    catch (e) {
+        throw mapSandboxError(e);
+    }
+}
+/**
+ * The task's status line: `Status: running (2m05s)`, `Status: failed, exit code 3, after 4m12s`,
+ * `Status: stopped after 1m00s`, `Status: lost (the sandbox was suspended) after 3s`.
+ */
+export function statusLine(task, now = new Date()) {
+    const end = task.status === "running" ? now : (task.finishedAt ?? now);
+    const elapsed = formatElapsed(end.getTime() - task.startedAt.getTime());
+    if (task.status === "running")
+        return `Status: running (${elapsed})`;
+    let s = `Status: ${task.status === "timed_out" ? "timed out" : task.status}`;
+    if (task.lostReason !== null)
+        s += ` (${lostReasonText(task.lostReason)})`;
+    if (task.exitCode !== null)
+        return `${s}, exit code ${task.exitCode}, after ${elapsed}`;
+    return `${s} after ${elapsed}`;
+}
+/** The absolute path of the task's output file, as the model sees it. */
+export const outputFile = (task) => `/workspace/${task.outputPath}`;
+/** Why the output cannot be read: the task's sandbox instance is not running. */
+export function unavailableText(task, r) {
+    if (r.kind === "not_running" && r.status === "suspended") {
+        return `[Output unavailable: the sandbox is suspended. Read ${outputFile(task)} resumes it and reads what the task wrote.]`;
+    }
+    return "[Output unavailable: the sandbox that ran this task is gone, and its output with it.]";
+}
+// ---- reading a task ----
+/**
+ * The exec that checks and reads task `t` (relative to `/workspace`): for a running task first
+ * its status line (the poller's, {@link pollScript}: liveness, then the exit file), then
+ * `size <bytes>` and `out <base64>`, at most `cap` bytes of the output from byte `offset` on.
+ * The file is never read whole: `tail -c +<offset+1> | head -c <cap>`. Without `read` only the
+ * status line.
+ */
+export function taskReadScript(t, offset, cap, read = true) {
+    if (!TASK_ID_RE.test(t.id))
+        throw new Error(`invalid background task id: ${t.id}`);
+    const lines = [];
+    if (t.running && t.sid !== null)
+        lines.push(pollScript([{ id: t.id, sid: t.sid }]));
+    if (read) {
+        const f = `${TASKS_DIR}/${t.id}.out`;
+        const from = Math.max(0, Math.floor(offset)) + 1;
+        const n = Math.max(1, Math.floor(cap));
+        lines.push(`s=$({ wc -c < ${f}; } 2>/dev/null | tr -d ' '); echo "size \${s:-0}"`);
+        lines.push(`printf 'out '; { tail -c +${from} ${f} 2>/dev/null | head -c ${n} | base64 | tr -d '\\n'; }; echo`);
+    }
+    return lines.join("\n");
+}
+function parseRead(id, stdout) {
+    const size = /^size ([0-9]+)$/m.exec(stdout);
+    const out = /^out ?([A-Za-z0-9+/=]*)$/m.exec(stdout);
+    return {
+        report: parsePollOutput(stdout).get(id),
+        size: size ? Number(size[1]) : 0,
+        data: Buffer.from(out?.[1] ?? "", "base64"),
+    };
+}
+/**
+ * The bytes of `buf` up to its last whole UTF-8 character: a character cut by the read's cap is
+ * left for the next read.
+ */
+export function wholeUtf8Length(buf) {
+    let i = buf.length - 1;
+    let back = 0;
+    while (i >= 0 && back < 3 && (buf[i] & 0xc0) === 0x80) {
+        i--;
+        back++;
+    }
+    if (i < 0)
+        return buf.length;
+    const b = buf[i];
+    const need = b >= 0xf0 ? 4 : b >= 0xe0 ? 3 : b >= 0xc0 ? 2 : 1;
+    return i + need > buf.length ? i : buf.length;
+}
+/** Checks (and with `read`, reads) the task in its sandbox instance; never creates or resumes one. */
+async function look(env, task, read, signal) {
+    if (task.sid !== null && !SID_RE.test(task.sid)) {
+        throw new Error(`invalid background task session: ${task.sid}`);
+    }
+    const script = taskReadScript({ id: task.id, sid: task.sid, running: task.status === "running" }, read?.offset ?? 0, read?.cap ?? 1, read !== null);
+    const maxBytes = Math.ceil((read?.cap ?? 0) / 3) * 4 + 64 * 1024;
+    return onTaskInstance(env, task, async (p, h, sig) => {
+        const r = await p.exec(h, {
+            command: script,
+            cwd: "/workspace",
+            timeoutMs: READ_EXEC_TIMEOUT_MS,
+            maxOutputBytes: maxBytes,
+            signal: sig,
+        });
+        if (r.exitCode !== 0 || r.truncated) {
+            throw new ToolError(`Background task ${task.id} could not be read (exit ${r.exitCode}${r.truncated ? ", output truncated" : ""}); retry TaskOutput, or Read ${outputFile(task)}.`);
+        }
+        return parseRead(task.id, r.stdout);
+    }, signal);
+}
+/**
+ * How `seen` shows the running `task` ended (an exit file, no process left, its sandbox instance
+ * not running), or null while it runs (or when the row is no longer running).
+ */
+function endOf(task, seen) {
+    if (task.status !== "running")
+        return null;
+    if (seen.kind === "not_running") {
+        return { to: notRunningAs(seen.status, seen.status === "suspended"), lastLines: "" };
+    }
+    if (seen.kind === "other_instance")
+        return { to: RECREATED, lastLines: "" };
+    const r = seen.value.report;
+    const to = r ? polledAs(task, r, new Date()) : null;
+    return to === null ? null : { to, lastLines: r?.lastLines ?? "" };
+}
+/**
+ * Finishes the task as `end` says, marked reported: called only once nothing can fail before the
+ * result reaches the model, so a reported finish is one the model saw. A task a stop claimed is
+ * left to the stop. Returns the task's row afterwards.
+ */
+async function settle(env, task, end) {
+    if (end === null)
+        return task;
+    await env.tasks.finisher.finish(task, end.to, end.lastLines, true, { unclaimed: true });
+    return (await env.store.get(task.id)) ?? task;
+}
+/** {@link look}, with a `SandboxGoneError` from the exec as null (the instance is gone). */
+async function lookOrGone(env, task, read, signal) {
+    try {
+        return await look(env, task, read, signal);
+    }
+    catch (e) {
+        if (isSandboxGoneError(e))
+            return null;
+        throw e;
+    }
+}
+/**
+ * Built-in `TaskOutput` (spec 2026-11-05-background-bash-design §2.2): a task's status and the
+ * output since this conversation's last read of it. Every check is a short exec through
+ * `SandboxService.ifRunning` on the task's own sandbox instance: it never creates or resumes a
+ * sandbox, so a suspended or rebuilt one means the task is lost (its output unavailable). With
+ * `block`, checks every {@link TASK_CHECK_INTERVAL_MS}, each under a lease of its own, until the
+ * task ends or the wait (at most `timeout` and the run's time left) is over; the checks only
+ * detect the end, and the one read that makes the result finishes the task (reported). The output
+ * read is capped at `tools.outputSpillChars` bytes; the pipeline spills the result beyond that.
+ */
+export function taskOutputTool(deps) {
+    return {
+        spec: SPEC,
+        defaultPolicy: "allow",
+        unavailable: unavailableWhenNoSandbox(deps),
+        timeoutMs: (input) => {
+            const { block, timeout } = input;
+            const wait = block === false
+                ? 0
+                : Math.min(timeout ?? TASK_OUTPUT_DEFAULT_TIMEOUT_MS, TASK_OUTPUT_MAX_TIMEOUT_MS);
+            return wait + sandboxBaseTimeoutMs(deps.config.get());
+        },
+        async run(input, ctx) {
+            const { task_id, block = true, timeout } = input;
+            const env = taskEnv(deps);
+            let task = await ownedTask(env, ctx, task_id);
+            if (block && task.status === "running") {
+                const wait = Math.max(0, Math.min(timeout ?? TASK_OUTPUT_DEFAULT_TIMEOUT_MS, TASK_OUTPUT_MAX_TIMEOUT_MS, runTimeLeftMs(ctx.runDeadline)));
+                const until = Date.now() + wait;
+                // no check right before the final read: the loop ends when the wait does
+                while (task.status === "running" && Date.now() < until) {
+                    if (task.sandboxCreatedAt !== null) {
+                        const seen = await lookOrGone(env, task, null, ctx.signal);
+                        if (seen === null || endOf(task, seen) !== null)
+                            break;
+                    }
+                    const left = until - Date.now();
+                    if (left <= 0)
+                        break;
+                    await sleep(Math.min(TASK_CHECK_INTERVAL_MS, left), undefined, { signal: ctx.signal });
+                    task = (await env.store.get(task.id)) ?? task;
+                }
+            }
+            if (task.sandboxCreatedAt === null) {
+                // a reservation still launching, or a launch that failed: nothing ran
+                return result(task, [
+                    statusLine(task),
+                    task.status === "running"
+                        ? "[The task is still starting; no output yet.]"
+                        : "[No output: the command never started.]",
+                ]);
+            }
+            const offset = task.readOffset;
+            const cap = deps.config.get().tools.outputSpillChars;
+            const seen = await lookOrGone(env, task, { offset, cap }, ctx.signal);
+            if (seen === null) {
+                return result(task, [statusLine(task), unavailableText(task, { kind: "other_instance" })]);
+            }
+            const end = endOf(task, seen);
+            if (seen.kind !== "ran") {
+                task = await settle(env, task, end);
+                return result(task, [statusLine(task), unavailableText(task, seen)]);
+            }
+            const { data, size } = seen.value;
+            // an ended task's output is complete: only a read cut by the cap can end inside a character
+            const ended = task.status !== "running" || end !== null;
+            const used = ended && data.length < cap ? data.length : wholeUtf8Length(data);
+            if (used > 0)
+                await env.store.advanceOffset(task.id, offset + used);
+            task = await settle(env, task, end);
+            const parts = [];
+            const more = size - (offset + used);
+            if (more > 0) {
+                parts.push(`[${more} more bytes of output after this; call TaskOutput again to read them, or Read ${outputFile(task)}.]`);
+            }
+            parts.push(used === 0 ? "[No new output.]" : data.subarray(0, used).toString("utf8"));
+            return result(task, [statusLine(task), ...parts]);
+        },
+    };
+}
+function result(task, lines) {
+    const d = clip(task.description, 120);
+    return {
+        content: [{ type: "text", text: lines.join("\n") }],
+        isError: false,
+        display: display(`读取后台任务输出：${d}`, `Read background task output: ${d}`),
+    };
+}

package/dist/tools/builtins/sandbox/task-stop.d.ts

@@ -0,0 +1,10 @@
+import type { BuiltinTool } from "../../registry.js";
+import { type SandboxToolDeps } from "./common.js";
+/**
+ * Built-in `TaskStop` (spec 2026-11-05-background-bash-design §2.3): stops one of this
+ * conversation's background tasks through `BackgroundTaskStopper` (SIGTERM to its session, SIGKILL
+ * after 5 s, never creating or resuming a sandbox). A task that had already finished is not an
+ * error; a reservation still launching, or a task another stop already claimed, is reported as
+ * stopping. A stop that failed leaves the task running and is an error the model can retry.
+ */
+export declare function taskStopTool(deps: SandboxToolDeps): BuiltinTool;

package/dist/tools/builtins/sandbox/task-stop.js

@@ -0,0 +1,112 @@
+import { ToolError } from "@capybara-hq/plugin-sdk";
+import { decodeTail, tailCommand } from "../../../background/session.js";
+import { clip, display, mapSandboxError, sandboxBaseTimeoutMs, unavailableWhenNoSandbox, } from "./common.js";
+import { onTaskInstance, ownedTask, statusLine, taskEnv } from "./task-output.js";
+/** The time limit of reading a stopped task's last lines. */
+const TAIL_EXEC_TIMEOUT_MS = 10_000;
+const SPEC = {
+    name: "TaskStop",
+    // Display only (the tool row; not in the fingerprint, never sent to the model).
+    keyArgs: ["task_id"],
+    description: "Stop a background task started with Bash and run_in_background: every process of the task " +
+        "gets SIGTERM, then SIGKILL after 5 seconds. The result has the final status and the last " +
+        "lines of output. Stopping a task that has already finished is not an error; the result says " +
+        "so. A conversation can stop only its own tasks.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            task_id: {
+                type: "string",
+                minLength: 1,
+                description: "The id of the background task (bt_...) that Bash returned.",
+            },
+        },
+        required: ["task_id"],
+        additionalProperties: false,
+    },
+};
+/** The task's last 20 lines, read from its own sandbox instance; null when that is not running. */
+async function lastLinesOf(env, task, signal) {
+    if (task.sandboxCreatedAt === null)
+        return null;
+    try {
+        const r = await onTaskInstance(env, task, async (p, h, sig) => {
+            const res = await p.exec(h, {
+                command: tailCommand(task.id),
+                cwd: "/workspace",
+                timeoutMs: TAIL_EXEC_TIMEOUT_MS,
+                maxOutputBytes: 64 * 1024,
+                signal: sig,
+            });
+            return res.exitCode === 0 ? decodeTail(res.stdout) : null;
+        }, signal);
+        return r.kind === "ran" ? r.value : null;
+    }
+    catch {
+        // the task is stopped either way; only its last lines are missing
+        return null;
+    }
+}
+/** The result text: what happened, the status line and the last lines. */
+async function ended(env, task, what, signal) {
+    const lines = await lastLinesOf(env, task, signal);
+    const tail = task.sandboxCreatedAt === null
+        ? "[No output: the command never started.]"
+        : lines === null
+            ? "[Last lines unavailable: the sandbox that ran this task is not running.]"
+            : lines === ""
+                ? "[No output.]"
+                : `Last lines:\n${lines.replace(/\n$/, "")}`;
+    return text(task, `Background task ${task.id} ("${task.description}") ${what}.\n${statusLine(task)}\n${tail}`);
+}
+function text(task, body) {
+    const d = clip(task.description, 120);
+    return {
+        content: [{ type: "text", text: body }],
+        isError: false,
+        display: display(`停止后台任务：${d}`, `Stop background task: ${d}`),
+    };
+}
+/**
+ * Built-in `TaskStop` (spec 2026-11-05-background-bash-design §2.3): stops one of this
+ * conversation's background tasks through `BackgroundTaskStopper` (SIGTERM to its session, SIGKILL
+ * after 5 s, never creating or resuming a sandbox). A task that had already finished is not an
+ * error; a reservation still launching, or a task another stop already claimed, is reported as
+ * stopping. A stop that failed leaves the task running and is an error the model can retry.
+ */
+export function taskStopTool(deps) {
+    return {
+        spec: SPEC,
+        defaultPolicy: "allow",
+        unavailable: unavailableWhenNoSandbox(deps),
+        timeoutMs: () => sandboxBaseTimeoutMs(deps.config.get()),
+        async run(input, ctx) {
+            const { task_id } = input;
+            const env = taskEnv(deps);
+            const task = await ownedTask(env, ctx, task_id);
+            if (task.status !== "running") {
+                return ended(env, task, "had already finished", ctx.signal);
+            }
+            let after;
+            try {
+                after = await env.tasks.stopper.stop(task, "tool", ctx.signal);
+            }
+            catch (e) {
+                const mapped = mapSandboxError(e);
+                if (mapped instanceof ToolError)
+                    throw mapped;
+                const why = e instanceof Error ? e.message : String(e);
+                throw new ToolError(`Background task ${task.id} could not be stopped (${clip(why, 300)}); it keeps running. Retry TaskStop, or check the sandbox with Bash.`);
+            }
+            if (after.status === "running") {
+                return text(after, `Background task ${after.id} ("${after.description}") is stopping: it is still starting, or another stop is in progress. Call TaskOutput to see when it has ended.`);
+            }
+            const what = after.status === "stopped"
+                ? "was stopped"
+                : after.status === "lost"
+                    ? "is lost"
+                    : "had already finished";
+            return ended(env, after, what, ctx.signal);
+        },
+    };
+}

package/dist/tools/builtins/web/errors.d.ts

@@ -0,0 +1,8 @@
+/** Which web tool is calling its provider (it names the provider in some texts). */
+export type WebToolKind = "search" | "fetch";
+/**
+ * Rethrows a web provider's failure for the tool pipeline: a `WebProviderError` becomes a
+ * `ToolError` with its kind's fixed text; anything else is rethrown unchanged (the pipeline's
+ * generic failure, which names only the error class, never the provider's message).
+ */
+export declare function webToolError(e: unknown, tool: WebToolKind): never;

package/dist/tools/builtins/web/errors.js

@@ -0,0 +1,53 @@
+import { ToolError, WebProviderError } from "@capybara-hq/plugin-sdk";
+const KINDS = new Set([
+    "not_found",
+    "blocked",
+    "auth",
+    "rate_limited",
+    "unavailable",
+    "invalid",
+]);
+/**
+ * The kind of a provider's `WebProviderError`, or undefined for any other error. Matched by name
+ * as well as by class, so an extension bundled with its own copy of the class still maps.
+ */
+function providerErrorKind(e) {
+    if (!(e instanceof Error))
+        return undefined;
+    if (!(e instanceof WebProviderError) && e.name !== "WebProviderError")
+        return undefined;
+    const kind = e.kind;
+    return typeof kind === "string" && KINDS.has(kind) ? kind : undefined;
+}
+/**
+ * The fixed model-visible text of a provider error kind (web tools spec §4.2): providers never
+ * write model-visible text.
+ */
+function providerErrorText(kind, tool) {
+    const provider = tool === "search" ? "web search" : "web fetch";
+    switch (kind) {
+        case "auth":
+            return `The ${provider} provider rejected its credentials; ask an org admin to check the provider's configuration.`;
+        case "rate_limited":
+            return `The ${provider} provider is rate limiting this org; retry in a minute or continue without it.`;
+        case "not_found":
+            return "No results or page found; check the query or URL and retry.";
+        case "blocked":
+            return "The site refused the provider; use another source.";
+        case "unavailable":
+            return "The web provider is unavailable right now; retry later or continue without it.";
+        case "invalid":
+            return "The provider rejected the request; check the query or URL and retry.";
+    }
+}
+/**
+ * Rethrows a web provider's failure for the tool pipeline: a `WebProviderError` becomes a
+ * `ToolError` with its kind's fixed text; anything else is rethrown unchanged (the pipeline's
+ * generic failure, which names only the error class, never the provider's message).
+ */
+export function webToolError(e, tool) {
+    const kind = providerErrorKind(e);
+    if (kind === undefined)
+        throw e;
+    throw new ToolError(providerErrorText(kind, tool));
+}

package/dist/tools/builtins/web/extract.d.ts

@@ -0,0 +1,62 @@
+import { type Logger, type WebFetchPage } from "@capybara-hq/plugin-sdk";
+import type { EventLog } from "../../../conversations/event-log.js";
+import type { KernelConfigService } from "../../../infra/config/kernel-config.service.js";
+import { type ModelPurposesService } from "../../../models/purposes.js";
+import { type HookRunner } from "../../../runtime/hook-calls.js";
+import type { StepLog } from "../../../runtime/step-log.js";
+import type { UsageReporter } from "../../../runtime/usage-report.js";
+import type { BuiltinCallContext } from "../../registry.js";
+/**
+ * The `WebFetch` extraction call (web tools spec §5): the fetched page and the model's prompt go to
+ * the `web_fetch` model purpose (unmapped → the calling conversation's current chat model, a
+ * sub-agent's call: the sub-agent's), and only its answer comes back. One call, no tools, output
+ * capped at `web.fetch.maxAnswerTokens`. The page sits between a random per-call tag the system
+ * prompt names, so page text cannot close it or fake the prompt; it is cut to fit the purpose
+ * model's context window ({@link fitPage}). It fires `model.request` (a policy denial is the tool error
+ * {@link WEB_FETCH_DENIED_TEXT}, logged as any hook denial) and `model.response` like the title
+ * call; its tokens are a `usage` event with `purpose: "web_fetch"` and the call id, reported, and
+ * counted on the parent run of a sub-agent. The page itself is never stored and never returned:
+ * a failure is the tool error {@link WEB_FETCH_EXTRACT_FAILED_TEXT}. The call is not model-visible
+ * to the agent (its result is the recorded `tool_result`), so replays never make it.
+ */
+/**
+ * The fixed start of the extraction call's system prompt (model-facing, English; a core constant).
+ * The prompt sent is {@link webFetchSystemPrompt}, which adds the call's page tag.
+ */
+export declare const WEB_FETCH_SYSTEM_PROMPT: string;
+/** The system prompt of one extraction call: {@link WEB_FETCH_SYSTEM_PROMPT} naming its page tag. */
+export declare function webFetchSystemPrompt(tag: string): string;
+/** The tool error when the extraction call fails (the page is never returned instead). */
+export declare const WEB_FETCH_EXTRACT_FAILED_TEXT = "Could not extract an answer from the page; retry, or try another URL.";
+/** The tool error when a `model.request` policy hook denies the extraction call. */
+export declare const WEB_FETCH_DENIED_TEXT = "An org policy blocked reading this page; continue without it or ask the user.";
+/** What {@link extractAnswer} needs. */
+export interface WebFetchExtractDeps {
+    purposes: Pick<ModelPurposesService, "chat" | "chatLimits">;
+    eventLog: Pick<EventLog, "append" | "notify" | "latestOfType">;
+    stepLog: Pick<StepLog, "appendCounted" | "appendAudited">;
+    config: Pick<KernelConfigService, "get">;
+    log: Pick<Logger, "warn">;
+    /** Extension hooks (absent: none fire). */
+    hooks?: HookRunner | undefined;
+    usageReport?: Pick<UsageReporter, "enqueue"> | undefined;
+}
+/**
+ * The user message of the extraction call: the URL, then the page (title, markdown) between
+ * `<tag>` and `</tag>`, then the prompt.
+ */
+export declare function extractionMessage(page: WebFetchPage, prompt: string, tag: string): string;
+/**
+ * The page cut so the extraction request fits the purpose model's context (web tools spec §4.2):
+ * system prompt + message + answer cap + headroom within `contextWindow`, by the kernel's
+ * `estimateTokens`. A cut page ends with {@link TRUNCATED_MARKER}; one that fits is unchanged.
+ */
+export declare function fitPage(page: WebFetchPage, prompt: string, tag: string, system: string, limits: {
+    contextWindow: number;
+    answerTokens: number;
+}): WebFetchPage;
+/**
+ * Answers `prompt` from `page` with one call on the `web_fetch` purpose (see the module comment).
+ * Returns the answer text; throws a {@link ToolError} on a denial or a failure.
+ */
+export declare function extractAnswer(deps: WebFetchExtractDeps, ctx: BuiltinCallContext, page: WebFetchPage, prompt: string): Promise<string>;