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

package/dist/tools/builtins/skill-load.d.ts

@@ -5,26 +5,29 @@ import { type CatalogSkill } from "../../runtime/context/skills.js";
 import type { BuiltinCallContext, BuiltinTool } from "../registry.js";
 import { type SandboxToolDeps } from "./sandbox/common.js";
 /**
- * 内置工具 `Skill`（M5 T14，Ruling M17）：按日志里最新一份技能目录快照把名字解析为 id 与版本，返回该版本
- * SKILL.md 的正文与文件清单（结果里写明版本）。技能带其他文件时把整个技能复制进本对话沙箱的 `/skills/<name>/`
- * （提供方以 root 写，命令用户只读）；没有沙箱提供方时只给正文，并说明脚本不可用。
+ * Builtin tool `Skill` (M5 T14, ruling M17): resolves the name against the latest skills catalog
+ * snapshot in the log to an id and version, and returns that version's SKILL.md body and file list
+ * (the result names the version). A skill with other files is copied whole into the conversation's
+ * environment at `/skills/<name>@<digest>/` (the provider writes as root, commands read only; the
+ * digest is {@link skillDigest} of the version's file manifest, so versions of one skill coexist in
+ * the shared file system). Without a sandbox provider only the body is given, with a note that
+ * scripts are unavailable.
  *
- * - 存储里读出的每个文件都按清单的 sha256 核对，不符即拒绝（不把被替换的内容给模型或放进沙箱）。
- * - 复制记录在内核控制的标记文件（每个技能一个，{@link skillMarkerPath}：`/skills/.capybara/<name>.json`，
- *   命令用户改不了）：`{ id, version, prefix, files, stale }`。新建 / 重建的沙箱、版本或来源前缀变化、同名换了技能时
- *   重新复制，否则跳过。
- * - agent 没有任何沙箱工具时不创建沙箱、不复制（模型也跑不了脚本），只给正文并说明。
- * - 可执行位：提供方写的文件一律不可执行（0644）。不扩展 `sandbox@1` 的 `writeFile`，而是在结果里告诉模型用解释器
- *   运行（`sh` / `python3` / `node`）：契约与两个提供方不变，技能包里的 shebang 脚本照样能跑，代价只是不能 `./x`。
- * - 旧版本多出的文件：`sandbox@1` 没有删除原语，命令用户也删不了 `/skills` 下的文件，所以新版本原地覆盖，
- *   旧版本独有的文件留在原处、记进标记的 `stale`，每次加载都在结果里列出「不属于当前版本、忽略它们」。
+ * - Every file read from storage is checked against the manifest's sha256; a mismatch is refused.
+ * - The copy is recorded in a kernel-controlled marker, one per skill version
+ *   ({@link skillMarkerPath}: `/skills/.capybara/<name>@<digest>.json`, commands cannot change it):
+ *   `{ digest, files }`. A present marker with the same digest skips the copy.
+ * - An agent without any sandbox tool creates no sandbox and copies nothing (the model could not
+ *   run the scripts), and is told so.
+ * - Executable bit: files the provider writes are never executable (0644). The result tells the model
+ *   to run scripts with an interpreter (`sh` / `python3` / `node`).
  */
 /**
  * 已复制进沙箱的技能的标记目录（内核控制：`/skills` 只有提供方以 root 能写；技能名不以 `.` 开头，不会撞名）。
  */
 export declare const SKILLS_MARKER_DIR = "/skills/.capybara";
-/** 一个技能的标记文件。 */
-export declare const skillMarkerPath: (name: string) => string;
+/** The marker file of one skill version. */
+export declare const skillMarkerPath: (name: string, digest: string) => string;
 /** 依赖：沙箱工具的依赖，加上读技能行用的库与读快照用的日志。 */
 export interface SkillLoadDeps extends SandboxToolDeps {
     db: KernelSchemaDb;
@@ -44,6 +47,11 @@ export declare function readSkillFile(store: ObjectStore, key: string, file: Ski
  * 批准时草稿前缀原样成为版本前缀，版本号变了也能找到），再找本对话发起、仍待批准、前缀相同的技能改动（试用草稿：
  * 没有 `skill_versions` 行，新技能连 `skills` 行都没有）。绝不按版本号解析——被拒绝的草稿与之后别人批准的同号版本
  * 内容不同。都没有 → undefined（已移除）。
+ *
+ * Phase 2 (ruling D2): a `platform:<prefix>` source is a platform skill version: found by its
+ * prefix for the platform skill with the entry's id, or the platform skill an org copy with that id
+ * links to (ruling B2), while neither is deleted. The returned `object_prefix` keeps the
+ * `platform:` form; `skillFileStore` picks the store for it.
  */
 export declare function findSkillVersion(db: KernelSchemaDb, ctx: Pick<BuiltinCallContext, "orgId" | "conversationId">, entry: Pick<CatalogSkill, "id" | "source">): Promise<{
     manifest: SkillManifest;

package/dist/tools/builtins/skill-load.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { parseSkillMd, renderSkillBody, SKILL_ENTRY_FILE, SKILL_INVOCATION_LIMITS, SKILLS_SANDBOX_ROOT, skillSandboxPath, ToolError, } from "@capybara-hq/plugin-sdk";
+import { parseSkillMd, renderSkillBody, SKILL_ENTRY_FILE, SKILL_INVOCATION_LIMITS, SKILLS_SANDBOX_ROOT, skillDigest, skillSandboxDir, skillSandboxPath, ToolError, } from "@capybara-hq/plugin-sdk";
 import { sql } from "kysely";
 import { normalizeStoredDefinition } from "../../agents/definition.js";
 import { ApiError } from "../../errors.js";
@@ -7,29 +7,33 @@ import { latestInvocation } from "../../runtime/context/skills.js";
 import { dispatchOfChildRun } from "../../runtime/subagents/child.js";
 import { resolveSkillForkType } from "../../runtime/subagents/roster.js";
 import { invocationOf, resolveSkills } from "../../skills/catalog.js";
+import { PLATFORM_SOURCE, skillFileStore } from "../../skills/usable.js";
 import { AGENT_TOOL, SANDBOX_TOOL_NAMES } from "../builtin-names.js";
 import { clip, display, inSandbox, sandboxBaseTimeoutMs, withNotices, withPathLease, } from "./sandbox/common.js";
 /**
- * 内置工具 `Skill`（M5 T14，Ruling M17）：按日志里最新一份技能目录快照把名字解析为 id 与版本，返回该版本
- * SKILL.md 的正文与文件清单（结果里写明版本）。技能带其他文件时把整个技能复制进本对话沙箱的 `/skills/<name>/`
- * （提供方以 root 写，命令用户只读）；没有沙箱提供方时只给正文，并说明脚本不可用。
+ * Builtin tool `Skill` (M5 T14, ruling M17): resolves the name against the latest skills catalog
+ * snapshot in the log to an id and version, and returns that version's SKILL.md body and file list
+ * (the result names the version). A skill with other files is copied whole into the conversation's
+ * environment at `/skills/<name>@<digest>/` (the provider writes as root, commands read only; the
+ * digest is {@link skillDigest} of the version's file manifest, so versions of one skill coexist in
+ * the shared file system). Without a sandbox provider only the body is given, with a note that
+ * scripts are unavailable.
  *
- * - 存储里读出的每个文件都按清单的 sha256 核对，不符即拒绝（不把被替换的内容给模型或放进沙箱）。
- * - 复制记录在内核控制的标记文件（每个技能一个，{@link skillMarkerPath}：`/skills/.capybara/<name>.json`，
- *   命令用户改不了）：`{ id, version, prefix, files, stale }`。新建 / 重建的沙箱、版本或来源前缀变化、同名换了技能时
- *   重新复制，否则跳过。
- * - agent 没有任何沙箱工具时不创建沙箱、不复制（模型也跑不了脚本），只给正文并说明。
- * - 可执行位：提供方写的文件一律不可执行（0644）。不扩展 `sandbox@1` 的 `writeFile`，而是在结果里告诉模型用解释器
- *   运行（`sh` / `python3` / `node`）：契约与两个提供方不变，技能包里的 shebang 脚本照样能跑，代价只是不能 `./x`。
- * - 旧版本多出的文件：`sandbox@1` 没有删除原语，命令用户也删不了 `/skills` 下的文件，所以新版本原地覆盖，
- *   旧版本独有的文件留在原处、记进标记的 `stale`，每次加载都在结果里列出「不属于当前版本、忽略它们」。
+ * - Every file read from storage is checked against the manifest's sha256; a mismatch is refused.
+ * - The copy is recorded in a kernel-controlled marker, one per skill version
+ *   ({@link skillMarkerPath}: `/skills/.capybara/<name>@<digest>.json`, commands cannot change it):
+ *   `{ digest, files }`. A present marker with the same digest skips the copy.
+ * - An agent without any sandbox tool creates no sandbox and copies nothing (the model could not
+ *   run the scripts), and is told so.
+ * - Executable bit: files the provider writes are never executable (0644). The result tells the model
+ *   to run scripts with an interpreter (`sh` / `python3` / `node`).
  */
 /**
  * 已复制进沙箱的技能的标记目录（内核控制：`/skills` 只有提供方以 root 能写；技能名不以 `.` 开头，不会撞名）。
  */
 export const SKILLS_MARKER_DIR = `${SKILLS_SANDBOX_ROOT}/.capybara`;
-/** 一个技能的标记文件。 */
-export const skillMarkerPath = (name) => `${SKILLS_MARKER_DIR}/${name}.json`;
+/** The marker file of one skill version. */
+export const skillMarkerPath = (name, digest) => `${SKILLS_MARKER_DIR}/${name}@${digest}.json`;
 const MARKER_MAX_BYTES = 256 * 1024;
 /** 结果里最多列出的文件数（其余只给数量）。 */
 const MAX_LISTED_FILES = 200;
@@ -42,9 +46,8 @@ const SPEC = {
     description: "Load a skill from the skills list: returns the skill's instructions " +
         "(its SKILL.md) and the list of its files. Call it before starting a task that matches a " +
         "skill's description, then follow the returned instructions. If the skill has scripts or other " +
-        "files, they are copied read-only to /skills/<name>/ in this conversation's sandbox; run scripts " +
-        "there with an interpreter (sh, python3, node). Call it again when the skills list changes or " +
-        "the sandbox was recreated. Pass args when the task gives the skill arguments (they replace " +
+        "files, they are copied read-only to /skills/<name>@<version-id>/ in this environment; run scripts " +
+        "there with an interpreter (sh, python3, node). Call it again when the skills list changes. Pass args when the task gives the skill arguments (they replace " +
         "$ARGUMENTS and $1, $2… in the instructions). Do not use it for skills that are not in the list.",
     inputSchema: {
         type: "object",
@@ -79,22 +82,20 @@ const removedText = (name) => `Skill "${name}" was removed after the skills list
 const forkAvailableText = (type) => `This skill is written to run in a sub-agent: call Agent with subagent_type "${type}" and a prompt containing these instructions and the details of the task, then use its report; do not follow the instructions yourself.`;
 const FORK_UNAVAILABLE_TEXT = "This skill is written to run in a sub-agent, which is not available here; follow the instructions yourself.";
 const integrityText = (name) => `Skill "${name}" failed an integrity check (its stored files do not match the uploaded package); ask an administrator to upload the skill again.`;
-const strings = (v) => Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
-/** 解析一个技能的标记文件；坏的按没有处理（重新复制）。 */
+/** Parses a version's marker; a broken one counts as missing (the version is copied again). */
 function parseMarker(data) {
     try {
         const r = JSON.parse(new TextDecoder().decode(data));
         if (r === null || typeof r !== "object" || Array.isArray(r))
             return undefined;
         const e = r;
-        if (typeof e.id !== "string" || typeof e.version !== "number")
+        if (typeof e.digest !== "string")
             return undefined;
         return {
-            id: e.id,
-            version: e.version,
-            ...(typeof e.prefix === "string" && { prefix: e.prefix }),
-            files: strings(e.files),
-            stale: strings(e.stale),
+            digest: e.digest,
+            files: Array.isArray(e.files)
+                ? e.files.filter((x) => typeof x === "string")
+                : [],
         };
     }
     catch {
@@ -156,34 +157,25 @@ async function readVerified(store, key, file, skill, signal) {
     }
 }
 /**
- * 把技能整个复制到 `/skills/<name>/`（标记命中则跳过）。每个文件按清单核对后写入，全部写完才更新标记：
- * 中途失败下次整体重来。返回旧版本留下的文件。
+ * Copies the skill version whole to `/skills/<name>@<digest>/` (skipped when its marker matches).
+ * Every file is checked against the manifest before it is written; the marker is written last, so
+ * a failure midway means the next call starts over.
  */
 async function copySkill(s, v) {
-    const { name, id, version } = v.entry;
-    const markerPath = skillMarkerPath(name);
-    let cur;
-    if (!s.reset) {
-        const m = await s.p.readFile(s.h, markerPath, { maxBytes: MARKER_MAX_BYTES, signal: s.signal });
-        if (m && !m.truncated)
-            cur = parseMarker(m.data);
-    }
-    if (cur && cur.id === id && cur.version === version && cur.prefix === v.prefix) {
-        return { stale: cur.stale };
-    }
+    const { name } = v.entry;
+    const markerPath = skillMarkerPath(name, v.digest);
+    const m = await s.p.readFile(s.h, markerPath, { maxBytes: MARKER_MAX_BYTES, signal: s.signal });
+    const cur = m && !m.truncated ? parseMarker(m.data) : undefined;
+    if (cur?.digest === v.digest)
+        return;
     for (const f of v.manifest.files) {
         const data = f.path === SKILL_ENTRY_FILE
             ? v.entryBytes
-            : await readVerified(v.store, `${v.prefix}${f.path}`, f, name, s.signal);
-        await s.p.writeFile(s.h, skillSandboxPath(name, f.path), data, s.signal);
+            : await readVerified(v.store, `${v.keyPrefix}${f.path}`, f, name, s.signal);
+        await s.p.writeFile(s.h, skillSandboxPath(name, v.digest, f.path), data, s.signal);
     }
-    const files = v.manifest.files.map((f) => f.path);
-    const now = new Set(files);
-    const stale = cur ? [...new Set([...cur.stale, ...cur.files])].filter((p) => !now.has(p)) : [];
-    stale.sort();
-    const entry = { id, version, prefix: v.prefix, files, stale };
+    const entry = { digest: v.digest, files: v.manifest.files.map((f) => f.path) };
     await s.p.writeFile(s.h, markerPath, new TextEncoder().encode(JSON.stringify(entry)), s.signal);
-    return { stale };
 }
 /** 本步可用的工具里是否有沙箱工具（没有时模型用不了复制进去的文件）。 */
 const hasSandboxTools = (ctx) => (ctx.tools ?? []).some((t) => t.source.kind === "builtin" &&
@@ -200,8 +192,15 @@ function fileList(files) {
  * 批准时草稿前缀原样成为版本前缀，版本号变了也能找到），再找本对话发起、仍待批准、前缀相同的技能改动（试用草稿：
  * 没有 `skill_versions` 行，新技能连 `skills` 行都没有）。绝不按版本号解析——被拒绝的草稿与之后别人批准的同号版本
  * 内容不同。都没有 → undefined（已移除）。
+ *
+ * Phase 2 (ruling D2): a `platform:<prefix>` source is a platform skill version: found by its
+ * prefix for the platform skill with the entry's id, or the platform skill an org copy with that id
+ * links to (ruling B2), while neither is deleted. The returned `object_prefix` keeps the
+ * `platform:` form; `skillFileStore` picks the store for it.
  */
 export async function findSkillVersion(db, ctx, entry) {
+    if (entry.source.startsWith(PLATFORM_SOURCE))
+        return findPlatformVersion(db, ctx.orgId, entry);
     const row = await db
         .selectFrom("skills")
         .innerJoin("skill_versions", "skill_versions.skill_id", "skills.id")
@@ -225,6 +224,29 @@ export async function findSkillVersion(db, ctx, entry) {
         return undefined;
     return { manifest: draft.proposed_version.manifest, object_prefix: draft.object_prefix };
 }
+/** {@link findSkillVersion} for a `platform:<prefix>` source. */
+async function findPlatformVersion(db, orgId, entry) {
+    const row = await db
+        .selectFrom("platform_skill_versions as v")
+        .innerJoin("platform_skills as p", "p.id", "v.skill_id")
+        .select(["v.manifest"])
+        .where("v.object_prefix", "=", entry.source.slice(PLATFORM_SOURCE.length))
+        .where("p.deleted_at", "is", null)
+        // a platform skill disabled on the deployment is not loaded, even from an older snapshot
+        .where("p.disabled", "=", false)
+        .where((eb) => eb.or([
+        eb("p.id", "=", entry.id),
+        eb("p.id", "in", eb
+            .selectFrom("skills")
+            .select("platform_skill_id")
+            .where("id", "=", entry.id)
+            .where("org_id", "=", orgId)
+            .where("deleted_at", "is", null)
+            .where("platform_skill_id", "is not", null)),
+    ]))
+        .executeTakeFirst();
+    return row && { manifest: row.manifest, object_prefix: entry.source };
+}
 /** A Claude Code style qualified name `<plugin>:<skill>` (phase B, spec §9.3). */
 const QUALIFIED_NAME_RE = /^([a-z0-9][a-z0-9-]{0,63}):(.+)$/;
 /**
@@ -385,13 +407,23 @@ export function skillLoadTool(deps) {
             if (!row)
                 throw new ToolError(removedText(name));
             const manifest = row.manifest;
-            const store = deps.storage.kernel(ctx.orgId);
+            // the marker records the source (`platform:` included); keys use the store's own prefix
             const prefix = row.object_prefix;
+            const { store, prefix: keyPrefix } = skillFileStore(deps.storage, ctx.orgId, prefix);
             const md = manifest.files.find((f) => f.path === SKILL_ENTRY_FILE);
             if (!md)
                 throw new ToolError(integrityText(name));
-            const mdBytes = await readVerified(store, `${prefix}${md.path}`, md, name, ctx.signal);
-            const v = { entry, manifest, prefix, store, entryBytes: mdBytes };
+            const mdBytes = await readVerified(store, `${keyPrefix}${md.path}`, md, name, ctx.signal);
+            const digest = skillDigest(manifest.files);
+            const v = {
+                entry,
+                manifest,
+                digest,
+                prefix,
+                keyPrefix,
+                store,
+                entryBytes: mdBytes,
+            };
             let parsed;
             try {
                 parsed = parseSkillMd(new TextDecoder("utf-8", { fatal: true }).decode(mdBytes), {
@@ -403,7 +435,7 @@ export function skillLoadTool(deps) {
             }
             if ("errors" in parsed)
                 throw new ToolError(integrityText(name));
-            const dir = `${SKILLS_SANDBOX_ROOT}/${name}/`;
+            const dir = `${skillSandboxDir(name, digest)}/`;
             const others = manifest.files.filter((f) => f.path !== SKILL_ENTRY_FILE);
             let notices = [];
             let filesText;
@@ -425,22 +457,19 @@ export function skillLoadTool(deps) {
             }
             else {
                 // the skill's marker is read, compared and written: one holder at a time per skill
-                const r = await inSandbox(deps, ctx, (s) => withPathLease(deps, ctx, skillMarkerPath(v.entry.name), s.signal, (signal) => copySkill({ ...s, signal }, v)));
+                const r = await inSandbox(deps, ctx, (s) => withPathLease(deps, s, skillMarkerPath(name, digest), s.signal, (signal) => copySkill({ ...s, signal }, v)));
                 notices = r.notices;
-                const stale = r.value.stale.length > 0
-                    ? `\nFiles left over from an earlier version (not part of this version; ignore them): ${r.value.stale.join(", ")}`
-                    : "";
                 filesText =
                     `Skill files (copied to ${dir} in the sandbox, read-only):\n${fileList(manifest.files)}\n` +
                         `Run scripts with an interpreter, e.g. \`sh ${dir}<script>.sh\`, \`python3 ${dir}<script>.py\` ` +
                         "or `node`; the files are not executable, so `./script` does not work. Write outputs under " +
-                        `/workspace, not ${SKILLS_SANDBOX_ROOT}.${stale}`;
+                        `/workspace, not ${SKILLS_SANDBOX_ROOT}.`;
             }
             const invocation = invocationOf(manifest);
             const fork = invocation.fork;
             let instructions;
             try {
-                instructions = renderSkillBody(parsed.body.trim(), invocation, args ?? "", name);
+                instructions = renderSkillBody(parsed.body.trim(), invocation, args ?? "", name, digest);
             }
             catch (e) {
                 if (!(e instanceof RangeError))

package/dist/tools/builtins/skill-write.js

@@ -29,7 +29,7 @@ const SPEC = {
         "user-invocable, context, agent, argument-hint and arguments, which are kept; with " +
         "disable-model-invocation: true only a person can invoke the skill and you cannot load it). " +
         "Every other entry in `files` is stored at " +
-        "/skills/<name>/<path>. Files of the previous version that you leave out are not part of the new " +
+        "/skills/<name>@<version-id>/<path> once loaded. Files of the previous version that you leave out are not part of the new " +
         "version. Text files only, at most 1 MB per skill in total. Use an existing skill's name to update " +
         "it; an organization skill with the same name is shadowed by this agent's own skill. On a private " +
         "agent the new version takes effect immediately. On a shared agent the change is sent to the " +

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>;