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

package/dist/tools/builtins/builtin-tools.js

@@ -8,21 +8,39 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { Inject, Injectable } from "@nestjs/common";
+import { BackgroundTaskFinisher } from "../../background/finish.js";
+import { BackgroundTaskStopper } from "../../background/stop.js";
+import { BackgroundTaskStore } from "../../background/store.js";
 import { AttachmentsService } from "../../conversations/attachments.service.js";
 import { EventLog } from "../../conversations/event-log.js";
+import { ConversationEnvironments } from "../../environments/conversation-environments.js";
+import { ExtensionHost } from "../../extensions/host.js";
+import { ExtensionPointDefaults } from "../../extensions/point-defaults.js";
 import { KernelConfigService } from "../../infra/config/kernel-config.service.js";
 import { KernelDb } from "../../infra/database/kernel-db.js";
+import { KERNEL_LOGGER } from "../../infra/tokens.js";
+import { ModelPurposesService } from "../../models/purposes.js";
+import { readOrgSettings } from "../../orgs/settings.service.js";
+import { PlatformActor } from "../../platform/actor.js";
+import { AgentDocs } from "../../platform/agent-docs.js";
+import { PlatformOperations } from "../../platform/registry.js";
+import { StepLog } from "../../runtime/step-log.js";
+import { UsageReporter } from "../../runtime/usage-report.js";
 import { SandboxService } from "../../sandbox/sandbox.service.js";
 import { SkillChangesService } from "../../skills/changes.service.js";
 import { StorageService } from "../../storage/storage.service.js";
 import { ToolOutputs } from "../outputs.js";
 import { agentTool } from "./agent.js";
 import { askUserTool } from "./ask-user.js";
+import { handbackTool } from "./handback.js";
+import { platformTool } from "./platform.js";
 import { readToolOutputTool } from "./read-tool-output.js";
 import { sandboxTools } from "./sandbox/index.js";
+import { sendMessageTool } from "./send-message.js";
 import { skillLoadTool } from "./skill-load.js";
 import { skillWriteTool } from "./skill-write.js";
 import { toolSearchTool } from "./tool-search.js";
+import { extractAnswer, WebPages, webTools } from "./web/index.js";
 /**
  * The kernel's builtin tools, built once from the injected services (their specs: names,
  * descriptions and schemas, are the factories' own and unchanged). `ToolSearch` and `Skill`
@@ -31,9 +49,14 @@ import { toolSearchTool } from "./tool-search.js";
  */
 let BuiltinTools = class BuiltinTools {
     tools;
-    constructor(db, config, outputs, storage, skillChanges, attachments, eventLog, sandbox) {
+    constructor(db, config, outputs, storage, skillChanges, attachments, eventLog, sandbox, environments, points, webPages, 
+    /** The WebFetch extraction call: the `web_fetch` purpose, its hooks, usage and denials. */
+    purposes, host, usageReport, stepLog, log, background, finisher, stopper, platformOps, platformActor, agentDocs) {
         const sandboxDeps = {
             sandbox,
+            environments,
+            background,
+            tasks: { finisher, stopper },
             attachments,
             storage,
             eventLog,
@@ -45,12 +68,17 @@ let BuiltinTools = class BuiltinTools {
             toolSearchTool(),
             // dispatches sub-agents; the tool pipeline handles its calls (sub-agents spec §4, §7.1)
             agentTool,
+            // messages between the agents of one tree; the registry offers them and the tool pipeline
+            // handles their calls (agent map spec §4.2, §4.3)
+            sendMessageTool,
+            handbackTool,
             ...sandboxTools(sandboxDeps),
             // 技能加载：对话日志里有技能目录快照时由注册表自动加入（Ruling M17）
             skillLoadTool({
                 storage,
                 config,
                 sandbox,
+                environments,
                 attachments,
                 eventLog,
                 get db() {
@@ -59,6 +87,21 @@ let BuiltinTools = class BuiltinTools {
             }),
             // 自写技能：agent 定义显式引用才可用
             skillWriteTool({ changes: skillChanges }),
+            // web search / fetch through the org's default provider (web tools spec §3); WebFetch answers
+            // from the page with one call on the `web_fetch` purpose (§5), never returning the page
+            ...webTools({
+                points,
+                config,
+                cache: webPages,
+                extract: (ctx, page, prompt) => extractAnswer({ purposes, eventLog, stepLog, config, log, hooks: host?.hooks, usageReport }, ctx, page, prompt),
+            }),
+            // the platform's own operations and docs, as the run's person (Platform tool spec)
+            platformTool({
+                ops: platformOps,
+                actor: platformActor,
+                docs: agentDocs,
+                setting: async (orgId) => (await readOrgSettings(db.db, orgId)).platformTool,
+            }),
         ];
     }
     /** The builtin tools, in a fixed order. */
@@ -75,6 +118,20 @@ BuiltinTools = __decorate([
     __param(4, Inject(SkillChangesService)),
     __param(5, Inject(AttachmentsService)),
     __param(6, Inject(EventLog)),
-    __param(7, Inject(SandboxService))
+    __param(7, Inject(SandboxService)),
+    __param(8, Inject(ConversationEnvironments)),
+    __param(9, Inject(ExtensionPointDefaults)),
+    __param(10, Inject(WebPages)),
+    __param(11, Inject(ModelPurposesService)),
+    __param(12, Inject(ExtensionHost)),
+    __param(13, Inject(UsageReporter)),
+    __param(14, Inject(StepLog)),
+    __param(15, Inject(KERNEL_LOGGER)),
+    __param(16, Inject(BackgroundTaskStore)),
+    __param(17, Inject(BackgroundTaskFinisher)),
+    __param(18, Inject(BackgroundTaskStopper)),
+    __param(19, Inject(PlatformOperations)),
+    __param(20, Inject(PlatformActor)),
+    __param(21, Inject(AgentDocs))
 ], BuiltinTools);
 export { BuiltinTools };

package/dist/tools/builtins/handback.d.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import type { BuiltinTool } from "../registry.js";
+export { SUBAGENT_HANDBACK } from "../builtin-names.js";
+/**
+ * The `SubagentHandback` builtin tool (agent map spec §4.3, children only): delivers a report to
+ * the agent that dispatched the sub-agent, as a `report` `subagent_delivery` in the parent's log.
+ * The sub-agent keeps its turn and may go on working; several handbacks are allowed. A run that
+ * handed back and then completes delivers nothing more (it only logs `subagent_finished`); one that
+ * ends otherwise (failed, stopped, a limit) is delivered as a one-line status. The tool pipeline handles the call itself
+ * (`SubagentMessages`), so {@link handbackTool}'s `run` is only a guard.
+ */
+/** The input of a `SubagentHandback` call. */
+export declare const HandbackInput: z.ZodObject<{
+    message: z.ZodString;
+}, z.core.$strict>;
+export type HandbackInputT = z.infer<typeof HandbackInput>;
+/** The result of a handback (agent map spec §4.3). */
+export declare const HANDBACK_RESULT_TEXT = "Report delivered to your caller.";
+/** A call outside a sub-agent (the tool is never offered there). */
+export declare const HANDBACK_NOT_A_CHILD_TEXT = "Only sub-agents can hand back a report; reply in this conversation instead.";
+/** A fork invocation's child (phase D): its parent reads its final reply as the report. */
+export declare const HANDBACK_FORK_TEXT = "You run a skill for the agent that dispatched you, which reads your final reply as the report; end your turn with the report instead.";
+/**
+ * The builtin. `defaultPolicy: "allow"`: it only moves text inside one tree the person already
+ * started. The tool pipeline handles `SubagentHandback` calls itself; `run` answers only when a
+ * call reaches it anyway.
+ */
+export declare const handbackTool: BuiltinTool;

package/dist/tools/builtins/handback.js

@@ -0,0 +1,53 @@
+import { z } from "zod";
+export { SUBAGENT_HANDBACK } from "../builtin-names.js";
+/**
+ * The `SubagentHandback` builtin tool (agent map spec §4.3, children only): delivers a report to
+ * the agent that dispatched the sub-agent, as a `report` `subagent_delivery` in the parent's log.
+ * The sub-agent keeps its turn and may go on working; several handbacks are allowed. A run that
+ * handed back and then completes delivers nothing more (it only logs `subagent_finished`); one that
+ * ends otherwise (failed, stopped, a limit) is delivered as a one-line status. The tool pipeline handles the call itself
+ * (`SubagentMessages`), so {@link handbackTool}'s `run` is only a guard.
+ */
+/** The input of a `SubagentHandback` call. */
+export const HandbackInput = z.object({ message: z.string().min(1).max(200_000) }).strict();
+const SPEC = {
+    name: "SubagentHandback",
+    description: "Hand your report back to the agent that dispatched you. It receives the message as your " +
+        "report, so include everything it needs: what you did, what you found, and anything left " +
+        "open. You keep your turn after this call: go on working if something remains, then end your " +
+        "turn. You can hand back more than once, for example a partial report and then the final " +
+        "one. Once you handed back, your final reply is not delivered again. For a short note while " +
+        'you work, use SendMessage with to "parent" instead.',
+    inputSchema: {
+        type: "object",
+        properties: {
+            message: {
+                type: "string",
+                minLength: 1,
+                maxLength: 200000,
+                description: "Your report for the agent that dispatched you.",
+            },
+        },
+        required: ["message"],
+        additionalProperties: false,
+    },
+};
+/** The result of a handback (agent map spec §4.3). */
+export const HANDBACK_RESULT_TEXT = "Report delivered to your caller.";
+/** A call outside a sub-agent (the tool is never offered there). */
+export const HANDBACK_NOT_A_CHILD_TEXT = "Only sub-agents can hand back a report; reply in this conversation instead.";
+/** A fork invocation's child (phase D): its parent reads its final reply as the report. */
+export const HANDBACK_FORK_TEXT = "You run a skill for the agent that dispatched you, which reads your final reply as the report; end your turn with the report instead.";
+/**
+ * The builtin. `defaultPolicy: "allow"`: it only moves text inside one tree the person already
+ * started. The tool pipeline handles `SubagentHandback` calls itself; `run` answers only when a
+ * call reaches it anyway.
+ */
+export const handbackTool = {
+    spec: SPEC,
+    defaultPolicy: "allow",
+    run: async () => ({
+        content: [{ type: "text", text: HANDBACK_NOT_A_CHILD_TEXT }],
+        isError: true,
+    }),
+};

package/dist/tools/builtins/platform.d.ts

@@ -0,0 +1,34 @@
+import type { OrgSettings } from "../../orgs/settings.service.js";
+import type { ActorFacts } from "../../platform/actor.js";
+import type { AgentDocTopic } from "../../platform/agent-docs.js";
+import type { PlatformOperations } from "../../platform/registry.js";
+import type { BuiltinTool, CallPolicyContext } from "../registry.js";
+/**
+ * The `Platform` builtin (Platform tool spec §3–§6): one tool through which an agent discovers and
+ * calls the platform's own operations as the run's trigger account, and reads the agent docs.
+ * - `browse` / `search` / `describe` / `read` only read; their policy is the tool's `allow`.
+ * - `call` gets a per-call policy key `Platform:<operation>` ({@link BuiltinTool.callPolicy}): a
+ *   read runs, a write asks (remembered only for `personal`), an operation that cannot run now is
+ *   denied with its reason. Right before `op.run` the availability is checked again on fresh facts
+ *   (the actor may have lost the role while the confirmation waited).
+ * - The actor, the agent and the conversation come from the runtime context, never from input.
+ * - Results are JSON text; a list an operation returns is capped at {@link LIST_MAX} entries.
+ */
+/** The most entries of a list in one result (operations that page return `next`). */
+export declare const LIST_MAX = 50;
+/** The tool's `unavailable` reason when the org setting `platformTool` is `off` (spec §3). */
+export declare const PLATFORM_UNAVAILABLE_OFF = "The org turned the Platform tool off; ask an org admin to turn it on.";
+/** What the tool needs; `BuiltinTools` passes the Nest providers. */
+export interface PlatformToolDeps {
+    ops: Pick<PlatformOperations, "domains" | "inDomain" | "get" | "search">;
+    actor: {
+        facts(ctx: CallPolicyContext): Promise<ActorFacts>;
+    };
+    docs: {
+        topics(): AgentDocTopic[];
+        read(id: string): string | null;
+    };
+    /** The org setting `platformTool`. */
+    setting(orgId: string): Promise<OrgSettings["platformTool"]>;
+}
+export declare function platformTool(deps: PlatformToolDeps): BuiltinTool;

package/dist/tools/builtins/platform.js

@@ -0,0 +1,362 @@
+import { ToolError } from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+import { availability } from "../../platform/availability.js";
+import { toToolError } from "../../platform/errors.js";
+import { PLATFORM_METHOD } from "../../platform/method.js";
+import { OPERATION_ID, operationDomain, } from "../../platform/operation.js";
+import { BUILTIN } from "../builtin-names.js";
+/**
+ * The `Platform` builtin (Platform tool spec §3–§6): one tool through which an agent discovers and
+ * calls the platform's own operations as the run's trigger account, and reads the agent docs.
+ * - `browse` / `search` / `describe` / `read` only read; their policy is the tool's `allow`.
+ * - `call` gets a per-call policy key `Platform:<operation>` ({@link BuiltinTool.callPolicy}): a
+ *   read runs, a write asks (remembered only for `personal`), an operation that cannot run now is
+ *   denied with its reason. Right before `op.run` the availability is checked again on fresh facts
+ *   (the actor may have lost the role while the confirmation waited).
+ * - The actor, the agent and the conversation come from the runtime context, never from input.
+ * - Results are JSON text; a list an operation returns is capped at {@link LIST_MAX} entries.
+ */
+/** The most entries of a list in one result (operations that page return `next`). */
+export const LIST_MAX = 50;
+/** The most operations `search` returns. */
+const SEARCH_MAX = 20;
+/** The tool's `unavailable` reason when the org setting `platformTool` is `off` (spec §3). */
+export const PLATFORM_UNAVAILABLE_OFF = "The org turned the Platform tool off; ask an org admin to turn it on.";
+const ACTIONS = ["browse", "search", "describe", "call", "read"];
+const SPEC = {
+    name: BUILTIN.Platform,
+    description: "Discover and use the platform's own operations (skills, agents, templates, plugins, " +
+        "marketplaces, requests, connectors, extensions) and its documentation, as the person you are " +
+        'working for. Start with action "browse", then "describe" an operation before you "call" it; ' +
+        'never guess parameters. Writes ask the person to confirm. Use "read" for how-to documentation ' +
+        "(plugin format, skills, extension points).",
+    inputSchema: {
+        type: "object",
+        properties: {
+            action: {
+                type: "string",
+                enum: [...ACTIONS],
+                description: 'browse: the domains and the method, or one domain\'s operations with "domain"; search: ' +
+                    'operations matching "query"; describe: one operation\'s full definition; call: run ' +
+                    '"operation" with "params"; read: a documentation topic, or the list of topics without ' +
+                    '"topic".',
+            },
+            domain: {
+                type: "string",
+                maxLength: 100,
+                description: 'For browse: a domain id from the browse result, e.g. "skills".',
+            },
+            query: {
+                type: "string",
+                maxLength: 200,
+                description: "For search: words to look for in operation ids and descriptions.",
+            },
+            operation: {
+                type: "string",
+                maxLength: 100,
+                description: 'For describe and call: an operation id, e.g. "skills.list".',
+            },
+            params: {
+                type: "object",
+                description: "For call: the operation's input, matching the inputSchema describe returned. Pass " +
+                    '"cursor" from a previous result\'s "next" to get the next page.',
+            },
+            topic: {
+                type: "string",
+                maxLength: 100,
+                description: "For read: a topic id from the topic list.",
+            },
+        },
+        required: ["action"],
+        additionalProperties: false,
+    },
+    keyArgs: ["action", "operation", "domain"],
+};
+const json = (value, summary) => ({
+    content: [{ type: "text", text: JSON.stringify(value) }],
+    display: { summary },
+});
+/** Longest model-written text quoted in a display summary (summaries are at most 200). */
+const SUMMARY_QUOTE_MAX = 80;
+const clip = (s) => s.length > SUMMARY_QUOTE_MAX ? `${s.slice(0, SUMMARY_QUOTE_MAX)}…` : s;
+/** The first sentence of a description: the line `browse` and `search` show. */
+const firstSentence = (text) => {
+    const m = /^(.+?[.!?])(\s|$)/s.exec(text.trim());
+    return (m?.[1] ?? text).trim();
+};
+const kindOf = (op) => op.confirm === "read" ? "read" : "write";
+const availabilityFields = (a) => a.ok ? { available: true } : { available: false, reason: a.reason };
+/** One operation as `browse` and `search` list it. */
+const line = (op, facts) => ({
+    id: op.id,
+    description: firstSentence(op.description),
+    kind: kindOf(op),
+    ...availabilityFields(availability(op, facts)),
+});
+const capped = (items) => ({
+    items: items.slice(0, LIST_MAX),
+    ...(items.length > LIST_MAX && {
+        total: items.length,
+        truncated: true,
+        hint: "Narrow the query or pass params.cursor where the operation pages.",
+    }),
+});
+/** An operation's result as a JSON object: a bare list is capped, nothing becomes `{ ok: true }`. */
+function asResult(value) {
+    if (Array.isArray(value))
+        return capped(value);
+    if (value === undefined || value === null)
+        return { ok: true };
+    if (typeof value !== "object")
+        return { result: value };
+    return value;
+}
+const unknownOperationText = (id) => `Unknown operation "${id}". Use browse or search to find an operation id, then describe it.`;
+const missingText = (action, field, what) => `Action ${action} needs "${field}": pass ${what}.`;
+const invalidParamsText = (id, problems) => `Invalid params for ${id}: ${problems}. Call describe with operation "${id}" for its input schema and an example, then call again.`;
+const unavailableOpText = (id, reason) => `Operation ${id} is unavailable, so do not call it again as is: ${reason}`;
+const outputRefText = (id) => `Operation ${id} writes, and its params hold a {"$output": ...} reference, which the person confirming would see instead of the content. Pass the content inline in params and call again.`;
+/** Whether a value holds a `{"$output": …}` reference anywhere (the pipeline's form). */
+function hasOutputRef(v) {
+    if (Array.isArray(v))
+        return v.some(hasOutputRef);
+    if (typeof v !== "object" || v === null)
+        return false;
+    const keys = Object.keys(v);
+    if (keys.length === 1 && keys[0] === "$output")
+        return true;
+    return Object.values(v).some(hasOutputRef);
+}
+/** Zod issues as one line: `path: message; …` (at most five). */
+function issuesText(error) {
+    const parts = error.issues
+        .slice(0, 5)
+        .map((i) => `${i.path.length === 0 ? "params" : i.path.join(".")}: ${i.message}`);
+    if (error.issues.length > 5)
+        parts.push(`and ${error.issues.length - 5} more`);
+    return parts.join("; ");
+}
+/** The operation of a `call` / `describe`; a `ToolError` when there is none (model-visible). */
+function operationOf(deps, action, id) {
+    if (id === undefined || id === "") {
+        throw new ToolError(missingText(action, "operation", "an operation id from browse or search"));
+    }
+    const op = deps.ops.get(id);
+    if (op === null)
+        throw new ToolError(unknownOperationText(id));
+    return op;
+}
+/** `params` checked against the operation's schema; a `ToolError` naming `describe` otherwise. */
+function paramsOf(op, params) {
+    const parsed = op.input.safeParse(params ?? {});
+    if (!parsed.success)
+        throw new ToolError(invalidParamsText(op.id, issuesText(parsed.error)));
+    return parsed.data;
+}
+/**
+ * The operation context of a confirmation (`confirmFor`, `summary`): the runtime's ids, never
+ * input. Nothing aborts it; it only reads.
+ */
+const confirmCtx = (ctx) => ({
+    orgId: ctx.orgId,
+    actorAccountId: ctx.accountId,
+    agentId: ctx.agentId,
+    conversationId: ctx.conversationId,
+    runId: ctx.runId,
+    signal: new AbortController().signal,
+});
+const factsCtx = (ctx) => ({
+    orgId: ctx.orgId,
+    accountId: ctx.accountId,
+    agentId: ctx.agentId,
+    conversationId: ctx.conversationId,
+    runId: ctx.runId ?? null,
+});
+export function platformTool(deps) {
+    const facts = (ctx) => deps.actor.facts(ctx);
+    async function callPolicy(raw, ctx) {
+        const input = raw;
+        if (input.action !== "call")
+            return null;
+        const id = input.operation;
+        const key = `${BUILTIN.Platform}:${id !== undefined && OPERATION_ID.test(id) ? id : "unknown"}`;
+        const deny = (denyReason) => ({
+            key,
+            policy: "deny",
+            remember: false,
+            denyReason,
+        });
+        let op;
+        let params;
+        try {
+            op = operationOf(deps, "call", id);
+            // params that cannot run are refused here, so the person is never asked to confirm them
+            params = paramsOf(op, input.params);
+        }
+        catch (e) {
+            if (e instanceof ToolError)
+                return deny(e.message);
+            throw e;
+        }
+        const verdict = availability(op, await facts(ctx));
+        if (!verdict.ok)
+            return deny(unavailableOpText(op.id, verdict.reason));
+        if (op.confirm === "read")
+            return { key, policy: "allow", remember: false };
+        // the card shows the raw input: a write must carry what it writes, not a reference to it
+        if (hasOutputRef(ctx.rawInput?.params)) {
+            return deny(outputRefText(op.id));
+        }
+        const octx = confirmCtx(ctx);
+        const [cls, summary] = await Promise.all([
+            classOf(op, params, octx),
+            summaryOf(op, params, octx),
+        ]);
+        return {
+            key,
+            policy: "ask",
+            // org / platform writes are confirmed every time (spec §6.2)
+            remember: cls === "personal",
+            summary,
+        };
+    }
+    async function run(raw, ctx) {
+        const input = raw;
+        switch (input.action) {
+            case "browse":
+                return input.domain === undefined ? browseRoot() : browseDomain(input.domain, ctx);
+            case "search":
+                return search(input.query, ctx);
+            case "describe":
+                return describe(input.operation, ctx);
+            case "call":
+                return call(input, ctx);
+            case "read":
+                return read(input.topic);
+        }
+    }
+    function browseRoot() {
+        const domains = deps.ops.domains().map((d) => ({
+            id: d.id,
+            description: d.description,
+            operations: deps.ops.inDomain(d.id).length,
+        }));
+        return json({ domains, method: PLATFORM_METHOD }, { zh: "浏览平台操作", en: "Browsed platform operations" });
+    }
+    async function browseDomain(domain, ctx) {
+        const ids = deps.ops.domains().map((d) => d.id);
+        if (!ids.includes(domain)) {
+            throw new ToolError(`Unknown domain "${domain}". Use one of: ${ids.join(", ")}; or call browse without a domain.`);
+        }
+        const f = await facts(factsCtx(ctx));
+        const ops = deps.ops.inDomain(domain);
+        return json({
+            domain,
+            operations: ops.slice(0, LIST_MAX).map((op) => line(op, f)),
+            ...(ops.length > LIST_MAX && { truncated: true, hint: "Use search to narrow the list." }),
+        }, { zh: `浏览平台操作：${domain}`, en: `Browsed platform operations: ${domain}` });
+    }
+    async function search(query, ctx) {
+        if (query === undefined || query.trim() === "") {
+            throw new ToolError(missingText("search", "query", "words to look for"));
+        }
+        const f = await facts(factsCtx(ctx));
+        const found = deps.ops.search(query, SEARCH_MAX);
+        return json({
+            query,
+            operations: found.map((op) => line(op, f)),
+            ...(found.length === 0 && {
+                hint: "Nothing matched; use other words, or browse a domain.",
+            }),
+        }, { zh: `搜索平台操作：${clip(query)}`, en: `Searched platform operations: ${clip(query)}` });
+    }
+    async function describe(id, ctx) {
+        const op = operationOf(deps, "describe", id);
+        const f = await facts(factsCtx(ctx));
+        return json({
+            id: op.id,
+            description: op.description,
+            kind: kindOf(op),
+            confirm: op.confirm,
+            inputSchema: z.toJSONSchema(op.input, { io: "input", unrepresentable: "any" }),
+            example: op.example,
+            ...(op.errors !== undefined && op.errors.length > 0 && { errors: op.errors }),
+            ...availabilityFields(availability(op, f)),
+            related: deps.ops
+                .inDomain(operationDomain(op.id))
+                .filter((o) => o.id !== op.id)
+                .map((o) => o.id),
+        }, { zh: `查看平台操作 ${op.id}`, en: `Described platform operation ${op.id}` });
+    }
+    async function call(input, ctx) {
+        const op = operationOf(deps, "call", input.operation);
+        const params = paramsOf(op, input.params);
+        // fresh facts right before running: the role may be gone since the confirmation (Review Focus 3)
+        const verdict = availability(op, await facts(factsCtx(ctx)));
+        if (!verdict.ok)
+            throw new ToolError(unavailableOpText(op.id, verdict.reason));
+        let result;
+        try {
+            result = await op.run(params, {
+                orgId: ctx.orgId,
+                actorAccountId: ctx.accountId,
+                agentId: ctx.agentId,
+                conversationId: ctx.conversationId,
+                runId: ctx.runId ?? null,
+                signal: ctx.signal,
+            });
+        }
+        catch (e) {
+            throw toToolError(e);
+        }
+        return json(asResult(result), { zh: `调用平台操作 ${op.id}`, en: `Called ${op.id}` });
+    }
+    function read(topic) {
+        if (topic === undefined || topic === "") {
+            return json({ topics: deps.docs.topics(), hint: 'Read one with action "read" and its "topic".' }, { zh: "查看平台文档目录", en: "Listed platform docs" });
+        }
+        const text = deps.docs.read(topic);
+        if (text === null) {
+            throw new ToolError(`Unknown topic "${topic}". Call read without a topic to list the topics.`);
+        }
+        return {
+            content: [{ type: "text", text }],
+            display: { summary: { zh: `阅读平台文档 ${topic}`, en: `Read platform doc ${topic}` } },
+        };
+    }
+    return {
+        spec: SPEC,
+        defaultPolicy: "allow",
+        run,
+        callPolicy,
+        async unavailable({ orgId }) {
+            return (await deps.setting(orgId)) === "off" ? PLATFORM_UNAVAILABLE_OFF : null;
+        },
+    };
+}
+/**
+ * The class of one write: `confirmFor` when the operation has one (the target decides), else
+ * `confirm`. A `confirmFor` that throws counts as `org`: never remembered.
+ */
+async function classOf(op, params, ctx) {
+    if (op.confirmFor === undefined)
+        return op.confirm;
+    try {
+        return await op.confirmFor(params, ctx);
+    }
+    catch {
+        return "org";
+    }
+}
+/** The card summary of a write, rendered from the validated params and kernel reads. */
+async function summaryOf(op, params, ctx) {
+    try {
+        const s = await op.summary?.(params, ctx);
+        if (s !== undefined)
+            return s;
+    }
+    catch {
+        // a summary that cannot render falls back to the operation id (the card shows every param)
+    }
+    return { zh: `平台操作 ${op.id}`, en: `Platform operation ${op.id}` };
+}

package/dist/tools/builtins/sandbox/bash.d.ts

@@ -1,4 +1,4 @@
-import type { ExecResult } from "@capybara-hq/plugin-sdk";
+import { type ExecResult } from "@capybara-hq/plugin-sdk";
 import type { BuiltinTool } from "../../registry.js";
 import { type SandboxToolDeps } from "./common.js";
 /** The command timeout in seconds when `timeout` is not given, at most `sandbox.limits.maxCommandSeconds`. */