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

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,209 @@
+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,
+                    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 };
+}

package/dist/tools/connectors.service.js

@@ -8,7 +8,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { randomUUID } from "node:crypto";
-import { ToolError, } from "@capybara-hq/plugin-sdk";
+import { connectorToolKey, ToolError, } from "@capybara-hq/plugin-sdk";
 import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
 import { z } from "zod";
@@ -25,7 +25,7 @@ import { OrgLock } from "../orgs/org-lock.js";
 import { CredentialMissing, Credentials, isOAuth, } from "./credentials.js";
 import { snapshot, ToolDrift, toolIssue, } from "./drift.js";
 import { endpointCredentialIssues, endpointView } from "./endpoint.js";
-import { deriveSlug, isValidSlug, SLUG_RULE, toolKey } from "./naming.js";
+import { deriveSlug, isValidSlug, SLUG_RULE } from "./naming.js";
 import { checkOAuthUrl, discoverMcp, OAuthSetupError, oauthHttpOptions, pickAuthMethod, registerClient, } from "./oauth/discovery.js";
 import { callbackUrl, publicUrlRequired } from "./oauth/flow-paths.js";
 import { OAuthGrantError, OAuthUnavailable, tokenRequest, } from "./oauth/tokens.js";
@@ -619,7 +619,7 @@ let ConnectorsService = class ConnectorsService {
             issues = snap.issues;
             tools = snap.rows.map((r) => ({
                 name: r.name,
-                key: toolKey(slug, r.name),
+                key: connectorToolKey(slug, r.name),
                 description: r.spec.description,
                 inputSchema: r.spec.inputSchema,
                 annotations: r.spec.annotations ?? null,
@@ -720,7 +720,7 @@ let ConnectorsService = class ConnectorsService {
                 const next = t.pending_spec;
                 return {
                     name: t.name,
-                    key: toolKey(r.slug, t.name),
+                    key: connectorToolKey(r.slug, t.name),
                     description: spec.description,
                     inputSchema: spec.inputSchema,
                     annotations: spec.annotations ?? null,

package/dist/tools/display-names.d.ts

@@ -0,0 +1,9 @@
+import type { LocalizedName } from "@capybara-hq/plugin-sdk";
+import type { KernelSchemaDb } from "../db/kernel-schema.js";
+/**
+ * The display names of plugins, for naming their extensions' tools (`<display name> [<tool>]`,
+ * tool naming spec §7): the live catalog item's `displayName`, else the plugin name in both
+ * languages (a bootstrap or uploaded plugin without a catalog item, or one without a display name).
+ * Display only.
+ */
+export declare function pluginDisplayNames(db: KernelSchemaDb, names: readonly string[]): Promise<Map<string, LocalizedName>>;

package/dist/tools/display-names.js

@@ -0,0 +1,24 @@
+/**
+ * The display names of plugins, for naming their extensions' tools (`<display name> [<tool>]`,
+ * tool naming spec §7): the live catalog item's `displayName`, else the plugin name in both
+ * languages (a bootstrap or uploaded plugin without a catalog item, or one without a display name).
+ * Display only.
+ */
+export async function pluginDisplayNames(db, names) {
+    const unique = [...new Set(names)];
+    const out = new Map(unique.map((n) => [n, { zh: n, en: n }]));
+    if (unique.length === 0)
+        return out;
+    const rows = await db
+        .selectFrom("catalog_items")
+        .select(["name", "display_name"])
+        .where("name", "in", unique)
+        .where("deleted_at", "is", null)
+        .execute();
+    for (const r of rows) {
+        const d = r.display_name;
+        if (d && typeof d.zh === "string" && typeof d.en === "string" && d.zh !== "" && d.en !== "")
+            out.set(r.name, { zh: d.zh, en: d.en });
+    }
+    return out;
+}

package/dist/tools/drift.js

@@ -7,7 +7,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
-import { TOOL_TITLE_MAX, ToolError, validateToolPresentation, } from "@capybara-hq/plugin-sdk";
+import { connectorToolKey, TOOL_TITLE_MAX, ToolError, validateToolPresentation, } from "@capybara-hq/plugin-sdk";
 import { getQueueToken } from "@nestjs/bullmq";
 import { Inject, Injectable } from "@nestjs/common";
 import { sql } from "kysely";
@@ -21,7 +21,7 @@ import { KERNEL_LOGGER } from "../infra/tokens.js";
 import { MAINTENANCE_QUEUE_NAME } from "../runtime/maintenance-queue.js";
 import { HIDDEN_FORMAT_RE } from "../text.js";
 import { CredentialMissing, Credentials, isOAuth } from "./credentials.js";
-import { toolKey, toolKeyIssue } from "./naming.js";
+import { toolKeyIssue } from "./naming.js";
 import { redactDeep, redactorFor } from "./redact.js";
 import { canonicalJson, policyFromAnnotations, specHash, ToolRegistry } from "./registry.js";
 import { resourceToolSpecs } from "./resources.js";
@@ -105,7 +105,7 @@ export function snapshot(slug, specs, resources) {
             ...(isObj(s.connectorData) && { connectorData: s.connectorData }),
             ...displayFields(s),
         };
-        let issue = toolKeyIssue(toolKey(slug, name));
+        let issue = toolKeyIssue(connectorToolKey(slug, name));
         if (!issue && !isObj(s.inputSchema))
             issue = "Tool inputSchema must be an object";
         if (issue)
@@ -122,7 +122,7 @@ export function snapshot(slug, specs, resources) {
                 });
                 continue;
             }
-            const issue = toolKeyIssue(toolKey(slug, spec.name));
+            const issue = toolKeyIssue(connectorToolKey(slug, spec.name));
             if (issue)
                 issues.push({ name: spec.name, reason: issue });
             rows.push({ name: spec.name, spec, specHash: specHash(spec), issue, source: "resources" });
@@ -172,7 +172,7 @@ const displayOf = (spec) => {
 };
 /** 工具当前不能启用的原因（视图、启用与复核校验共用）。 */
 export function toolIssue(slug, spec) {
-    const keyIssue = toolKeyIssue(toolKey(slug, spec.name));
+    const keyIssue = toolKeyIssue(connectorToolKey(slug, spec.name));
     if (keyIssue)
         return keyIssue;
     if (!isObj(spec.inputSchema))

package/dist/tools/elicitation.js

@@ -33,7 +33,7 @@ export class ElicitationSuspended extends Error {
 }
 /** 不能展示的 elicitation 被拒绝时附在工具结果后的说明（模型可见，英文）。 */
 export const UNSUPPORTED_ELICITATION_NOTE = "The app asked the user for input that cannot be shown in this client, so the request was declined";
-const unsupportedNote = (why) => `[${UNSUPPORTED_ELICITATION_NOTE} (${why}). If the call needs that input, ask the user for it with ask_user and pass it as tool arguments, or try another approach.]`;
+const unsupportedNote = (why) => `[${UNSUPPORTED_ELICITATION_NOTE} (${why}). If the call needs that input, ask the user for it with AskUserQuestion and pass it as tool arguments, or try another approach.]`;
 /** URL 模式表单里「已完成」开关的字段名。 */
 export const URL_COMPLETED_FIELD = "completed";
 /** 表单标题（远端给的 message）最多字符数。 */

package/dist/tools/info.d.ts

@@ -1,3 +1,4 @@
+import { type LocalizedName } from "@capybara-hq/plugin-sdk";
 import { ConversationAccess } from "../conversations/access.js";
 import type { KernelSchemaDb } from "../db/kernel-schema.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
@@ -11,16 +12,32 @@ export type ToolKind = "command" | "read" | "edit" | "search" | "connector" | "m
 export interface ToolInfo {
     /** The model-visible tool key, as asked for. */
     key: string;
+    /**
+     * Set only for a release-candidate builtin key (old history, tool naming spec §9): the current
+     * tool it stands for. Everything else describes that tool, with `keyArgs` in the old parameter
+     * names the logged input carries. Pages map a call's name through it (the `Agent` row, labels).
+     */
+    aliasOf?: string;
     /** The declared display title (`ToolSpec.title`), or null. */
     title: string | null;
     kind: ToolKind;
+    /** True exactly for the builtin tools that run in the conversation's sandbox. */
+    sandbox: boolean;
     /** The declared key arguments (`ToolSpec.keyArgs`), or []. */
     keyArgs: string[];
+    /**
+     * The local tool name parsed from a connector or extension key (`mcp__crm__delete` -> `delete`),
+     * shown in brackets after the source's display name; null for builtins and unparsable keys.
+     */
+    tool: string | null;
     source: {
         kind: "builtin";
-    } | {
+    }
+    /** `displayName`: the plugin's catalog display name, else its name. */
+     | {
         kind: "extension";
         name: string;
+        displayName: LocalizedName;
     } | {
         kind: "connector";
         id: string;
@@ -31,8 +48,7 @@ export interface ToolInfo {
         kind: "unknown";
     };
 }
-/** Kinds of the kernel builtin tools; a builtin missing here is a plain `tool`. */
-export declare const BUILTIN_TOOL_KINDS: Readonly<Record<string, ToolKind>>;
+export { BUILTIN_TOOL_KINDS } from "./builtin-names.js";
 /** At most this many keys per request, each at most {@link TOOL_INFO_KEY_MAX} characters. */
 export declare const TOOL_INFO_MAX_KEYS = 100;
 export declare const TOOL_INFO_KEY_MAX = 200;
@@ -42,7 +58,7 @@ export interface ToolInfoDeps {
 }
 /**
  * Presentation metadata for `keys` in this org, in request order with repeats dropped. Builtins
- * by name; `<prefix>__<tool>` keys first as a loaded extension's registration, then as a live
+ * by name (a release-candidate builtin key as its current tool, with `aliasOf`); `plugin__<plugin>__<tool>` keys as a loaded extension's registration, and `mcp__<slug>__<tool>` keys as a live
  * connector's current stored tool (its reviewed definition, never a pending one). Anything else
  * comes back as an unknown plain tool.
  *