@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.10

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

@@ -0,0 +1,55 @@
+import { type ToolSpec, type WebFetchPage } from "@capybara-hq/plugin-sdk";
+import type { ExtensionPointDefaults } from "../../../extensions/point-defaults.js";
+import type { KernelConfigService } from "../../../infra/config/kernel-config.service.js";
+import type { BuiltinCallContext, BuiltinTool } from "../../registry.js";
+import type { WebPages } from "./page-cache.js";
+/**
+ * Appended to a page cut at `web.fetch.maxPageChars` or to fit the extraction model's context
+ * (seen by the extraction model only).
+ */
+export declare const TRUNCATED_MARKER = "\n[truncated]";
+/**
+ * The fixed spec (web tools spec §3.2). Nothing per org or provider: `specHash` stays the same
+ * across providers, so remembered grants survive a change of the org's default provider.
+ */
+export declare const WEB_FETCH_SPEC: ToolSpec;
+/** What {@link fetchPage} needs. */
+export interface WebFetchPageDeps {
+    points: Pick<ExtensionPointDefaults, "resolve">;
+    config: Pick<KernelConfigService, "get">;
+    cache: Pick<WebPages, "get" | "set">;
+}
+/** The outcome of {@link fetchPage}: the page to extract from, or a redirect to another host. */
+export type FetchedPage = {
+    kind: "page";
+    page: WebFetchPage;
+} | {
+    kind: "redirect";
+    finalUrl: string;
+};
+/**
+ * Fetches `url` (already checked by {@link normalizeFetchUrl}) with the org's `web-fetch@1`
+ * provider (resolved per call, never cached in process), through the page cache. The provider's
+ * `finalUrl` is checked like any URL before the model can see it: a final URL on another host
+ * (apex ↔ www is the same host) is returned as a `redirect` (no extraction; web tools spec §3.2),
+ * one WebFetch may not fetch is an error. An empty page is an error; a long one is cut to `web.fetch.maxPageChars`.
+ */
+export declare function fetchPage(deps: WebFetchPageDeps, ctx: Pick<BuiltinCallContext, "orgId" | "signal">, url: string): Promise<FetchedPage>;
+/**
+ * The extraction call (web tools spec §5): the page and the prompt in, a short answer out
+ * (`extractAnswer` in `extract.ts` in production). It throws a `ToolError` instead of ever
+ * returning the page.
+ */
+export type WebFetchExtract = (ctx: BuiltinCallContext, page: WebFetchPage, prompt: string) => Promise<string>;
+/** What {@link webFetchTool} needs. */
+export interface WebFetchDeps extends WebFetchPageDeps {
+    extract: WebFetchExtract;
+}
+/**
+ * The builtin `WebFetch` (web tools spec §3.2): checks and upgrades the URL, fetches the page with
+ * the org's `web-fetch@1` provider ({@link fetchPage}) and answers `prompt` from it with one
+ * extraction call; the result is the answer headed by the URL, never the raw page. A redirect to
+ * another host returns the new URL instead. Default `ask`; time limit `web.fetch.timeoutMs`;
+ * unavailable when the org has no provider or several without a default.
+ */
+export declare function webFetchTool(deps: WebFetchDeps): BuiltinTool;

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

@@ -0,0 +1,175 @@
+import { ToolError, } from "@capybara-hq/plugin-sdk";
+import { BUILTIN } from "../../builtin-names.js";
+import { webToolError } from "./errors.js";
+import { MAX_FETCH_URL_CHARS, normalizeFetchUrl } from "./url.js";
+/** The extension point name (without the major) the provider is resolved from. */
+const POINT = "web-fetch";
+/**
+ * Appended to a page cut at `web.fetch.maxPageChars` or to fit the extraction model's context
+ * (seen by the extraction model only).
+ */
+export const TRUNCATED_MARKER = "\n[truncated]";
+/**
+ * The fixed spec (web tools spec §3.2). Nothing per org or provider: `specHash` stays the same
+ * across providers, so remembered grants survive a change of the org's default provider.
+ */
+export const WEB_FETCH_SPEC = {
+    name: BUILTIN.WebFetch,
+    // Display only (the tool row; not in the fingerprint, never sent to the model).
+    keyArgs: ["url", "prompt"],
+    description: "Fetch a web page and answer a question about it. Pass the full URL and a prompt saying what " +
+        "to extract; the page is read and a smaller model answers the prompt from it, so the result " +
+        "is the answer, not the raw page. Use it after WebSearch, or when the user gives you a URL. " +
+        "It is read-only. HTTP URLs are upgraded to HTTPS. If the URL redirects to another host, " +
+        "the result tells you the new URL to fetch.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            // No `format: "uri"` and no maxLength: the kernel checks the URL itself (normalizeFetchUrl)
+            // and its errors tell the model what to pass.
+            url: { type: "string", description: "The full URL of the page to fetch." },
+            prompt: {
+                type: "string",
+                minLength: 1,
+                description: "What to extract from the page, or the question to answer from it.",
+            },
+        },
+        required: ["url", "prompt"],
+        additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+};
+/** Why the tool is unavailable in an org (web tools spec §3.4; English, actionable). */
+function unavailableText(reason) {
+    if (reason === "none") {
+        return "No web fetch provider is enabled in this organization; ask an org admin to enable one.";
+    }
+    return "Several web fetch providers are enabled and none is the default; ask an org admin to choose one in the organization settings.";
+}
+/** The page's markdown cut to `max` characters with {@link TRUNCATED_MARKER}; idempotent. */
+function capMarkdown(page, max) {
+    if (page.markdown.length <= max)
+        return page;
+    return { ...page, markdown: `${page.markdown.slice(0, max)}${TRUNCATED_MARKER}` };
+}
+/** A provider's page with only the fields of the contract, of the right types. */
+function cleanPage(p, url) {
+    const o = (p ?? {});
+    return {
+        finalUrl: typeof o.finalUrl === "string" && o.finalUrl.trim() !== "" ? o.finalUrl : url,
+        markdown: typeof o.markdown === "string" ? o.markdown : "",
+        ...(typeof o.title === "string" && { title: o.title }),
+        ...(typeof o.contentType === "string" && { contentType: o.contentType }),
+    };
+}
+/**
+ * The error for a final URL WebFetch may not fetch. The provider's URL is echoed only when it is
+ * a URL of a reasonable length, never arbitrary provider text.
+ */
+function refusedRedirectText(finalUrl) {
+    let parses = true;
+    try {
+        new URL(finalUrl);
+    }
+    catch {
+        parses = false;
+    }
+    if (parses && finalUrl.length <= MAX_FETCH_URL_CHARS) {
+        return `The URL redirected to ${finalUrl}, which WebFetch cannot fetch; use another URL.`;
+    }
+    return "The URL redirected to an address WebFetch cannot fetch; use another URL.";
+}
+/** A hostname without one leading `www.`. */
+const withoutWww = (host) => (host.startsWith("www.") ? host.slice(4) : host);
+/**
+ * Whether a redirect from host `b` to host `a` stays on the same site: equal hosts after one
+ * leading `www.` is stripped on both sides (apex ↔ www, as Claude Code allows).
+ */
+const sameSite = (a, b) => withoutWww(a) === withoutWww(b);
+/**
+ * Fetches `url` (already checked by {@link normalizeFetchUrl}) with the org's `web-fetch@1`
+ * provider (resolved per call, never cached in process), through the page cache. The provider's
+ * `finalUrl` is checked like any URL before the model can see it: a final URL on another host
+ * (apex ↔ www is the same host) is returned as a `redirect` (no extraction; web tools spec §3.2),
+ * one WebFetch may not fetch is an error. An empty page is an error; a long one is cut to `web.fetch.maxPageChars`.
+ */
+export async function fetchPage(deps, ctx, url) {
+    const resolved = await deps.points.resolve(ctx.orgId, POINT);
+    if (!resolved.ok)
+        throw new ToolError(unavailableText(resolved.reason));
+    const max = deps.config.get().web.fetch.maxPageChars;
+    let page = await deps.cache.get(ctx.orgId, resolved.extension, url);
+    if (page === null) {
+        let fetched;
+        try {
+            fetched = await resolved.impl.fetch({
+                url,
+                orgConfig: resolved.orgConfig,
+                config: resolved.config,
+                signal: ctx.signal,
+            });
+        }
+        catch (e) {
+            webToolError(e, "fetch");
+        }
+        // cached already cut, so a large page costs Redis no more than the model may read
+        page = capMarkdown(cleanPage(fetched, url), max);
+        await deps.cache.set(ctx.orgId, resolved.extension, url, page);
+    }
+    const final = normalizeFetchUrl(page.finalUrl);
+    if (!final.ok)
+        throw new ToolError(refusedRedirectText(page.finalUrl));
+    if (!sameSite(new URL(final.url).hostname, new URL(url).hostname)) {
+        return { kind: "redirect", finalUrl: final.url };
+    }
+    if (page.markdown.trim() === "") {
+        throw new ToolError("The page has no readable text; use another URL.");
+    }
+    return { kind: "page", page: capMarkdown({ ...page, finalUrl: final.url }, max) };
+}
+/**
+ * The builtin `WebFetch` (web tools spec §3.2): checks and upgrades the URL, fetches the page with
+ * the org's `web-fetch@1` provider ({@link fetchPage}) and answers `prompt` from it with one
+ * extraction call; the result is the answer headed by the URL, never the raw page. A redirect to
+ * another host returns the new URL instead. Default `ask`; time limit `web.fetch.timeoutMs`;
+ * unavailable when the org has no provider or several without a default.
+ */
+export function webFetchTool(deps) {
+    return {
+        spec: WEB_FETCH_SPEC,
+        defaultPolicy: "ask",
+        // the provider's fetch and a large extraction call need more than `tools.timeoutMs`; read per
+        // call (hot config)
+        timeoutMs: () => deps.config.get().web.fetch.timeoutMs,
+        async unavailable({ orgId }) {
+            const r = await deps.points.resolve(orgId, POINT);
+            return r.ok ? null : unavailableText(r.reason);
+        },
+        async run(input, ctx) {
+            const { url: rawUrl, prompt } = input;
+            const checked = normalizeFetchUrl(rawUrl);
+            if (!checked.ok)
+                throw new ToolError(`${checked.error} Then call WebFetch again.`);
+            const url = checked.url;
+            const host = new URL(url).hostname;
+            const display = { summary: { zh: `读取网页：${host}`, en: `Read ${host}` } };
+            const fetched = await fetchPage(deps, ctx, url);
+            if (fetched.kind === "redirect") {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `The URL redirected to ${fetched.finalUrl}. Call WebFetch again with that URL if you want its content.`,
+                        },
+                    ],
+                    display,
+                };
+            }
+            const answer = await deps.extract(ctx, fetched.page, prompt);
+            const head = fetched.page.finalUrl === url
+                ? `URL: ${url}`
+                : `URL: ${url}\nFinal URL: ${fetched.page.finalUrl}`;
+            return { content: [{ type: "text", text: `${head}\n\n${answer}` }], display };
+        },
+    };
+}

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

@@ -0,0 +1,13 @@
+import type { BuiltinTool } from "../../registry.js";
+import { type WebFetchDeps } from "./fetch.js";
+import { type WebSearchDeps } from "./search.js";
+export { webToolError } from "./errors.js";
+export { extractAnswer, WEB_FETCH_DENIED_TEXT, WEB_FETCH_EXTRACT_FAILED_TEXT, WEB_FETCH_SYSTEM_PROMPT, type WebFetchExtractDeps, webFetchSystemPrompt, } from "./extract.js";
+export { fetchPage, WEB_FETCH_SPEC, type WebFetchDeps, type WebFetchExtract, webFetchTool, } from "./fetch.js";
+export { WebPages } from "./page-cache.js";
+export { WEB_SEARCH_SPEC, webSearchTool } from "./search.js";
+export { normalizeFetchUrl } from "./url.js";
+/** What the web builtins need. */
+export type WebToolDeps = WebSearchDeps & WebFetchDeps;
+/** The web builtins (web tools spec §3), in a fixed order. */
+export declare function webTools(deps: WebToolDeps): BuiltinTool[];

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

@@ -0,0 +1,12 @@
+import { webFetchTool } from "./fetch.js";
+import { webSearchTool } from "./search.js";
+export { webToolError } from "./errors.js";
+export { extractAnswer, WEB_FETCH_DENIED_TEXT, WEB_FETCH_EXTRACT_FAILED_TEXT, WEB_FETCH_SYSTEM_PROMPT, webFetchSystemPrompt, } from "./extract.js";
+export { fetchPage, WEB_FETCH_SPEC, webFetchTool, } from "./fetch.js";
+export { WebPages } from "./page-cache.js";
+export { WEB_SEARCH_SPEC, webSearchTool } from "./search.js";
+export { normalizeFetchUrl } from "./url.js";
+/** The web builtins (web tools spec §3), in a fixed order. */
+export function webTools(deps) {
+    return [webSearchTool(deps), webFetchTool(deps)];
+}

package/dist/tools/builtins/web/page-cache.d.ts

@@ -0,0 +1,25 @@
+import type { WebFetchPage } from "@capybara-hq/plugin-sdk";
+import { CacheService } from "../../../infra/cache/cache.service.js";
+import { KernelConfigService } from "../../../infra/config/kernel-config.service.js";
+/**
+ * The cache key of a fetched page: per org, provider and URL (the URL hashed, it may be long).
+ * `CacheService` stores it under `cache:<key>`.
+ */
+export declare const webPageKey: (orgId: string, provider: string, url: string) => string;
+/**
+ * The `WebFetch` page cache (web tools spec §10): the provider's page (never the extraction,
+ * which depends on the prompt) in Redis under {@link webPageKey}, for `web.fetch.cacheSeconds`
+ * (read at every call; 0 turns the cache off). It saves the org's provider quota when an agent
+ * reads the same page twice. Through `CacheService`, so it fails open: a Redis error is logged and
+ * behaves like a miss or a skipped write. (Not named `*Cache`: that name is `infra/cache`'s.)
+ */
+export declare class WebPages {
+    private readonly cache;
+    private readonly config;
+    constructor(cache: CacheService, config: KernelConfigService);
+    private ttl;
+    /** The cached page of `url`, or null on a miss, when the cache is off or on a Redis error. */
+    get(orgId: string, provider: string, url: string): Promise<WebFetchPage | null>;
+    /** Caches `page` for `url`; nothing when the cache is off. */
+    set(orgId: string, provider: string, url: string, page: WebFetchPage): Promise<void>;
+}

package/dist/tools/builtins/web/page-cache.js

@@ -0,0 +1,77 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { createHash } from "node:crypto";
+import { Inject, Injectable } from "@nestjs/common";
+import { CacheService } from "../../../infra/cache/cache.service.js";
+import { KernelConfigService } from "../../../infra/config/kernel-config.service.js";
+/**
+ * The cache key of a fetched page: per org, provider and URL (the URL hashed, it may be long).
+ * `CacheService` stores it under `cache:<key>`.
+ */
+export const webPageKey = (orgId, provider, url) => `web_page:${orgId}:${provider}:${createHash("sha256").update(url).digest("hex")}`;
+/** A stored value read back as a page, or null when it is not one. */
+function asPage(raw) {
+    let v;
+    try {
+        v = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (v === null || typeof v !== "object")
+        return null;
+    const p = v;
+    if (typeof p.finalUrl !== "string" || typeof p.markdown !== "string")
+        return null;
+    return {
+        finalUrl: p.finalUrl,
+        markdown: p.markdown,
+        ...(typeof p.title === "string" && { title: p.title }),
+        ...(typeof p.contentType === "string" && { contentType: p.contentType }),
+    };
+}
+/**
+ * The `WebFetch` page cache (web tools spec §10): the provider's page (never the extraction,
+ * which depends on the prompt) in Redis under {@link webPageKey}, for `web.fetch.cacheSeconds`
+ * (read at every call; 0 turns the cache off). It saves the org's provider quota when an agent
+ * reads the same page twice. Through `CacheService`, so it fails open: a Redis error is logged and
+ * behaves like a miss or a skipped write. (Not named `*Cache`: that name is `infra/cache`'s.)
+ */
+let WebPages = class WebPages {
+    cache;
+    config;
+    constructor(cache, config) {
+        this.cache = cache;
+        this.config = config;
+    }
+    ttl() {
+        return this.config.get().web.fetch.cacheSeconds;
+    }
+    /** The cached page of `url`, or null on a miss, when the cache is off or on a Redis error. */
+    async get(orgId, provider, url) {
+        if (this.ttl() <= 0)
+            return null;
+        const raw = await this.cache.get(webPageKey(orgId, provider, url));
+        return raw === undefined ? null : asPage(raw);
+    }
+    /** Caches `page` for `url`; nothing when the cache is off. */
+    async set(orgId, provider, url, page) {
+        const ttl = this.ttl();
+        if (ttl <= 0)
+            return;
+        await this.cache.setJson(webPageKey(orgId, provider, url), page, ttl);
+    }
+};
+WebPages = __decorate([
+    Injectable(),
+    __param(0, Inject(CacheService)),
+    __param(1, Inject(KernelConfigService))
+], WebPages);
+export { WebPages };

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

@@ -0,0 +1,25 @@
+import { type ToolSpec } from "@capybara-hq/plugin-sdk";
+import type { ExtensionPointDefaults } from "../../../extensions/point-defaults.js";
+import type { KernelConfigService } from "../../../infra/config/kernel-config.service.js";
+import type { BuiltinTool } from "../../registry.js";
+/**
+ * The fixed spec (web tools spec §3.1). No date and nothing per org or provider: `specHash` stays
+ * the same across days and providers, so remembered grants survive both and replays match the log.
+ * The date is the first line of every result instead.
+ */
+export declare const WEB_SEARCH_SPEC: ToolSpec;
+/** What {@link webSearchTool} needs. */
+export interface WebSearchDeps {
+    points: Pick<ExtensionPointDefaults, "resolve">;
+    config: Pick<KernelConfigService, "get">;
+    /** The clock of the result's date line (tests fix it). */
+    now?: () => Date;
+}
+/**
+ * The builtin `WebSearch` (web tools spec §3.1): searches with the org's `web-search@1` provider
+ * (`ExtensionPointDefaults`, resolved per call and per step, never cached), asking it for
+ * `web.search.maxResults` results with the domain lists as hints and the org's config, then
+ * filters the results again. Default `ask`; unavailable when the org has no provider or several
+ * without a default.
+ */
+export declare function webSearchTool(deps: WebSearchDeps): BuiltinTool;

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

@@ -0,0 +1,210 @@
+import { domainToASCII } from "node:url";
+import { ToolError, } from "@capybara-hq/plugin-sdk";
+import { BUILTIN } from "../../builtin-names.js";
+import { webToolError } from "./errors.js";
+/** The extension point name (without the major) the provider is resolved from. */
+const POINT = "web-search";
+/**
+ * The fixed spec (web tools spec §3.1). No date and nothing per org or provider: `specHash` stays
+ * the same across days and providers, so remembered grants survive both and replays match the log.
+ * The date is the first line of every result instead.
+ */
+export const WEB_SEARCH_SPEC = {
+    name: BUILTIN.WebSearch,
+    // Display only (the tool row; not in the fingerprint, never sent to the model).
+    keyArgs: ["query"],
+    description: "Search the web and get a list of results with title, URL and a short snippet. Use it for " +
+        "information newer than your training data, or to check whether something you know is still " +
+        "current. Then use WebFetch to read the pages you need. Do not use it for questions you can " +
+        "answer reliably without the web. Cite the sources you use.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            query: {
+                type: "string",
+                minLength: 2,
+                maxLength: 500,
+                description: "The search query.",
+            },
+            allowed_domains: {
+                type: "array",
+                items: { type: "string", minLength: 1, maxLength: 253 },
+                maxItems: 50,
+                description: "Only return results from these domains (hostnames such as example.com; subdomains " +
+                    "are included). Do not combine with blocked_domains.",
+            },
+            blocked_domains: {
+                type: "array",
+                items: { type: "string", minLength: 1, maxLength: 253 },
+                maxItems: 50,
+                description: "Never return results from these domains (hostnames such as example.com; subdomains " +
+                    "are included). Do not combine with allowed_domains.",
+            },
+        },
+        required: ["query"],
+        additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+};
+/** The last line of a result with entries (Claude Code tells the model to list its sources). */
+const CITE_LINE = "Cite the sources you use as markdown links in your answer.";
+/** Why the tool is unavailable in an org (web tools spec §3.4; English, actionable). */
+function unavailableText(reason) {
+    if (reason === "none") {
+        return "No web search provider is enabled in this organization; ask an org admin to enable one.";
+    }
+    return "Several web search providers are enabled and none is the default; ask an org admin to choose one in the organization settings.";
+}
+/**
+ * A domain entry as a bare lowercase ASCII hostname: tolerates a scheme, a path, a port, a leading
+ * `*.` / `.` and a trailing dot; a Unicode (IDN) name becomes its punycode form, as result hosts
+ * are (WHATWG URL parsing). Empty when nothing is left.
+ */
+function normalizeDomain(entry) {
+    let d = entry.trim().toLowerCase();
+    d = d.replace(/^[a-z][a-z0-9+.-]*:\/\//, "");
+    d = d.replace(/[/?#].*$/, "").replace(/:\d+$/, "");
+    d = d.replace(/^\*\./, "").replace(/^\.+/, "").replace(/\.+$/, "");
+    if (d === "")
+        return d;
+    // domainToASCII is "" for a name IDNA rejects: keep the entry as given (it matches no host)
+    return domainToASCII(d) || d;
+}
+/**
+ * A domain list normalized; undefined when absent or empty (no filter). A list whose entries all
+ * normalize to nothing stays an empty list, which no host matches.
+ */
+const normalizeDomains = (list) => list === undefined || list.length === 0
+    ? undefined
+    : [...new Set(list.map(normalizeDomain).filter((d) => d !== ""))];
+/** Whether `host` is `domain` or one of its subdomains. */
+const covers = (domain, host) => host === domain || host.endsWith(`.${domain}`);
+const oneLine = (s) => s.replace(/\s+/g, " ").trim();
+/**
+ * The provider's results the model may see (web tools spec §7.2): an absolute http(s) URL, a
+ * non-empty title, each URL once, within the domain lists, at most `max`. The kernel filters even
+ * when the provider honored the domain hints.
+ */
+function usable(results, allowed, blocked, max) {
+    const seen = new Set();
+    const out = [];
+    for (const r of results) {
+        if (out.length >= max)
+            break;
+        if (typeof r?.url !== "string" || typeof r.title !== "string")
+            continue;
+        const title = oneLine(r.title);
+        if (title === "")
+            continue;
+        let u;
+        try {
+            // no base: a relative URL throws
+            u = new URL(r.url.trim());
+        }
+        catch {
+            continue;
+        }
+        if (u.protocol !== "https:" && u.protocol !== "http:")
+            continue;
+        const host = u.hostname.toLowerCase().replace(/\.$/, "");
+        if (host === "")
+            continue;
+        if (allowed !== undefined && !allowed.some((d) => covers(d, host)))
+            continue;
+        if (blocked?.some((d) => covers(d, host)))
+            continue;
+        if (seen.has(u.href))
+            continue;
+        seen.add(u.href);
+        const date = typeof r.publishedAt === "string" ? /^\d{4}-\d{2}-\d{2}/.exec(r.publishedAt.trim()) : null;
+        const snippet = typeof r.snippet === "string" ? oneLine(r.snippet) : "";
+        out.push({
+            title,
+            url: u.href,
+            ...(date !== null && { date: date[0] }),
+            ...(snippet !== "" && { snippet }),
+        });
+    }
+    return out;
+}
+/** The model-visible result (web tools spec §3.1): the date line first, then the entries. */
+function resultText(day, entries) {
+    const head = `Search date: ${day} (UTC).`;
+    if (entries.length === 0)
+        return `${head}\n\nNo results.`;
+    const blocks = entries.map((e, i) => [
+        `${i + 1}. ${e.title}`,
+        `   URL: ${e.url}`,
+        ...(e.date !== undefined ? [`   Published: ${e.date}`] : []),
+        ...(e.snippet !== undefined ? [`   ${e.snippet}`] : []),
+    ].join("\n"));
+    return [head, ...blocks, CITE_LINE].join("\n\n");
+}
+/** The query in the display summary: one line, at most this many code points. */
+const DISPLAY_QUERY_MAX = 120;
+function displayQuery(query) {
+    const cps = [...oneLine(query)];
+    return cps.length > DISPLAY_QUERY_MAX
+        ? `${cps.slice(0, DISPLAY_QUERY_MAX - 1).join("")}…`
+        : cps.join("");
+}
+/**
+ * The builtin `WebSearch` (web tools spec §3.1): searches with the org's `web-search@1` provider
+ * (`ExtensionPointDefaults`, resolved per call and per step, never cached), asking it for
+ * `web.search.maxResults` results with the domain lists as hints and the org's config, then
+ * filters the results again. Default `ask`; unavailable when the org has no provider or several
+ * without a default.
+ */
+export function webSearchTool(deps) {
+    const now = deps.now ?? (() => new Date());
+    return {
+        spec: WEB_SEARCH_SPEC,
+        defaultPolicy: "ask",
+        async unavailable({ orgId }) {
+            const r = await deps.points.resolve(orgId, POINT);
+            return r.ok ? null : unavailableText(r.reason);
+        },
+        async run(input, ctx) {
+            const { query, allowed_domains, blocked_domains } = input;
+            if (allowed_domains !== undefined && blocked_domains !== undefined) {
+                throw new ToolError("Pass either allowed_domains or blocked_domains, not both; call WebSearch again with one of them.");
+            }
+            const allowed = normalizeDomains(allowed_domains);
+            const blocked = normalizeDomains(blocked_domains);
+            // the provider may have changed since the step resolved the tool: resolve again
+            const resolved = await deps.points.resolve(ctx.orgId, POINT);
+            if (!resolved.ok)
+                throw new ToolError(unavailableText(resolved.reason));
+            const max = deps.config.get().web.search.maxResults;
+            const day = now().toISOString().slice(0, 10);
+            let results;
+            try {
+                const out = await resolved.impl.search({
+                    query,
+                    ...(allowed !== undefined && allowed.length > 0 && { allowedDomains: allowed }),
+                    ...(blocked !== undefined && blocked.length > 0 && { blockedDomains: blocked }),
+                    maxResults: max,
+                    orgConfig: resolved.orgConfig,
+                    config: resolved.config,
+                    signal: ctx.signal,
+                });
+                results = Array.isArray(out?.results) ? out.results : [];
+            }
+            catch (e) {
+                webToolError(e, "search");
+            }
+            const entries = usable(results, allowed, blocked, max);
+            const q = displayQuery(query);
+            const n = entries.length;
+            return {
+                content: [{ type: "text", text: resultText(day, entries) }],
+                display: {
+                    summary: {
+                        zh: `搜索网页：${q}（${n} 条结果）`,
+                        en: `Searched the web: ${q} (${n} result${n === 1 ? "" : "s"})`,
+                    },
+                },
+            };
+        },
+    };
+}

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

@@ -0,0 +1,17 @@
+/** The longest URL `WebFetch` accepts, in characters (Claude Code's limit; web tools spec §7.1). */
+export declare const MAX_FETCH_URL_CHARS = 2000;
+/** The outcome of {@link normalizeFetchUrl}: the URL to fetch, or a model-visible error. */
+export type FetchUrlCheck = {
+    ok: true;
+    url: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * A `WebFetch` URL checked and normalized (web tools spec §7.1): absolute http(s), `http:`
+ * upgraded to `https:`, no user name or password, at most {@link MAX_FETCH_URL_CHARS} characters
+ * (before and after normalization), and a host that can name a public internet host. Pure, no DNS: a public name that resolves to a
+ * private address is the provider's to refuse. Errors are English and tell the model what to pass.
+ */
+export declare function normalizeFetchUrl(raw: string): FetchUrlCheck;

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

@@ -0,0 +1,43 @@
+import { isPublicHostname } from "@capybara-hq/plugin-sdk";
+/** The longest URL `WebFetch` accepts, in characters (Claude Code's limit; web tools spec §7.1). */
+export const MAX_FETCH_URL_CHARS = 2000;
+const fail = (error) => ({ ok: false, error });
+/**
+ * A `WebFetch` URL checked and normalized (web tools spec §7.1): absolute http(s), `http:`
+ * upgraded to `https:`, no user name or password, at most {@link MAX_FETCH_URL_CHARS} characters
+ * (before and after normalization), and a host that can name a public internet host. Pure, no DNS: a public name that resolves to a
+ * private address is the provider's to refuse. Errors are English and tell the model what to pass.
+ */
+export function normalizeFetchUrl(raw) {
+    const input = raw.trim();
+    // a cheap guard before parsing; the normalized URL is checked again below
+    if (input.length > MAX_FETCH_URL_CHARS) {
+        return fail(`Pass a URL of at most ${MAX_FETCH_URL_CHARS} characters.`);
+    }
+    let u;
+    try {
+        // no base: a relative URL throws
+        u = new URL(input);
+    }
+    catch {
+        return fail("Pass a full absolute URL, such as https://example.com/page.");
+    }
+    if (u.protocol !== "https:" && u.protocol !== "http:") {
+        return fail("Pass an https URL; only http and https URLs can be fetched.");
+    }
+    if (u.username !== "" || u.password !== "") {
+        return fail("Pass the URL without a user name or password.");
+    }
+    u.protocol = "https:";
+    // `u.hostname` is WHATWG-normalized (lowercased, IDNA, numeric IPv4 forms such as `0x7f.0.0.1`
+    // rewritten to dotted decimal, IPv6 in brackets), which is what isPublicHostname expects: never
+    // pass it a hand-parsed host.
+    if (!isPublicHostname(u.hostname)) {
+        return fail("Pass a full public https URL; this host is private or local.");
+    }
+    // the limit is on the URL as fetched: the upgrade, IDNA and percent-encoding can lengthen it
+    if (u.href.length > MAX_FETCH_URL_CHARS) {
+        return fail(`Pass a URL of at most ${MAX_FETCH_URL_CHARS} characters.`);
+    }
+    return { ok: true, url: u.href };
+}