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

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,51 @@
+import type { KernelLogger } from "../../log.js";
+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 PlatformOperation } from "../../platform/operation.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, and so is a write whose `precheck` knows it would fail (spec §14.2
+ *   item 2: no card). The policy is derived again when an approved call resumes, so a precheck
+ *   that fails by then returns its error and nothing runs. Right before `op.run` the availability
+ *   is checked again on fresh facts (the actor may have lost the role while the confirmation
+ *   waited).
+ * - An `ApiError` gets the next step the operation declares for its code and the actor's role.
+ * - 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"]>;
+    /** How long a precheck may take; default {@link PRECHECK_TIMEOUT_MS} (a test seam). */
+    precheckTimeoutMs?: number;
+    /** A precheck that throws is logged (warn) and one that times out (debug), with the op id. */
+    log?: Pick<KernelLogger, "warn"> & Partial<Pick<KernelLogger, "debug">>;
+}
+/**
+ * An operation's input keys as `browse` and `search` show them, so a call needs no guess:
+ * `"itemId"`, `"agentId, updatedAt, avatar?, quickActions?"` (`?` = optional), `""` when it takes
+ * none. A union input lists the keys of every branch; a key is required when every branch requires
+ * it. Types, bounds and an example stay in `describe`.
+ */
+export declare function paramsLine(op: PlatformOperation): string;
+export declare function platformTool(deps: PlatformToolDeps): BuiltinTool;

package/dist/tools/builtins/platform.js

@@ -0,0 +1,451 @@
+import { ToolError } from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+import { availability } from "../../platform/availability.js";
+import { errorRoleOf, errorsFor, nextStepFor, OPERATION_ERROR_NEXT, resolveNext, sentence, toToolError, } from "../../platform/errors.js";
+import { PLATFORM_METHOD } from "../../platform/method.js";
+import { OPERATION_ID, operationDomain, PRECHECK_TIMEOUT_MS, } 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, and so is a write whose `precheck` knows it would fail (spec §14.2
+ *   item 2: no card). The policy is derived again when an approved call resumes, so a precheck
+ *   that fails by then returns its error and nothing runs. Right before `op.run` the availability
+ *   is checked again on fresh facts (the actor may have lost the role while the confirmation
+ *   waited).
+ * - An `ApiError` gets the next step the operation declares for its code and the actor's role.
+ * - 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 (agents, skills, templates, plugins, " +
+        "connectors, extensions, conversations, environments, models, evals, channels, requests, " +
+        "approvals and the inbox, org settings, and for admins accounts, orgs and the admin console) " +
+        'and its documentation, as the person you are working for. Start with action "browse", which ' +
+        'lists every domain, 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 };
+/** The most input keys a `params` line names before it ends in `…`. */
+const PARAMS_MAX = 8;
+const paramsCache = new WeakMap();
+/**
+ * An operation's input keys as `browse` and `search` show them, so a call needs no guess:
+ * `"itemId"`, `"agentId, updatedAt, avatar?, quickActions?"` (`?` = optional), `""` when it takes
+ * none. A union input lists the keys of every branch; a key is required when every branch requires
+ * it. Types, bounds and an example stay in `describe`.
+ */
+export function paramsLine(op) {
+    const cached = paramsCache.get(op);
+    if (cached !== undefined)
+        return cached;
+    const schema = z.toJSONSchema(op.input, {
+        io: "input",
+        unrepresentable: "any",
+    });
+    const branches = schema.anyOf ?? schema.oneOf ?? [schema];
+    const keys = [];
+    for (const b of branches) {
+        for (const k of Object.keys(b.properties ?? {}))
+            if (!keys.includes(k))
+                keys.push(k);
+    }
+    const required = (k) => branches.every((b) => b.required?.includes(k) ?? false);
+    const ordered = [...keys.filter(required), ...keys.filter((k) => !required(k))];
+    const names = ordered.map((k) => (required(k) ? k : `${k}?`));
+    const text = names.length > PARAMS_MAX ? `${names.slice(0, PARAMS_MAX).join(", ")}, …` : names.join(", ");
+    paramsCache.set(op, text);
+    return text;
+}
+/** One operation as `browse` and `search` list it. */
+const line = (op, facts) => ({
+    id: op.id,
+    description: firstSentence(op.description),
+    kind: kindOf(op),
+    params: paramsLine(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 precheckText = (id, code, message, next) => `Operation ${id} cannot run now: ${code}: ${sentence(message)} ${next ?? OPERATION_ERROR_NEXT}`;
+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, errorRole) => ({
+    orgId: ctx.orgId,
+    actorAccountId: ctx.accountId,
+    agentId: ctx.agentId,
+    conversationId: ctx.conversationId,
+    runId: ctx.runId,
+    signal: new AbortController().signal,
+    errorRole,
+});
+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 f = await facts(ctx);
+        const verdict = availability(op, f);
+        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 role = errorRoleOf(f);
+        const failed = await precheckOf(op, params, ctx, role, deps.precheckTimeoutMs ?? PRECHECK_TIMEOUT_MS, deps.log);
+        if (failed !== null) {
+            const next = resolveNext(failed.next, role) ?? nextStepFor(op.errors, failed.code, role);
+            return deny(precheckText(op.id, failed.code, failed.message, next));
+        }
+        const octx = confirmCtx(ctx, role);
+        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" && op.rememberable !== false,
+            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: errorsFor(op.errors, errorRoleOf(f)) }),
+            ...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 f = await facts(factsCtx(ctx));
+        const verdict = availability(op, f);
+        if (!verdict.ok)
+            throw new ToolError(unavailableOpText(op.id, verdict.reason));
+        const role = errorRoleOf(f);
+        let result;
+        try {
+            result = await op.run(params, {
+                orgId: ctx.orgId,
+                actorAccountId: ctx.accountId,
+                agentId: ctx.agentId,
+                conversationId: ctx.conversationId,
+                runId: ctx.runId ?? null,
+                callId: ctx.callId,
+                signal: ctx.signal,
+                errorRole: role,
+            });
+        }
+        catch (e) {
+            // a service refusal after the approval (a race the precheck could not see) still names the
+            // next step for this actor (Review Focus 2)
+            throw toToolError(e, (code) => nextStepFor(op.errors, code, role));
+        }
+        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 operation's precheck, bounded by `ms`: the failure it found, or null (none, passed, timed
+ * out, or threw: the write's own errors speak then; a throw is logged as a warning, a timeout at
+ * debug). Its signal aborts at the timeout or when the run's signal aborts.
+ */
+async function precheckOf(op, params, ctx, role, ms, log) {
+    if (op.precheck === undefined)
+        return null;
+    const ac = new AbortController();
+    const signal = ctx.signal === undefined ? ac.signal : AbortSignal.any([ac.signal, ctx.signal]);
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => {
+            ac.abort();
+            log?.debug?.("platform precheck timed out; the card is shown", { operation: op.id, ms });
+            resolve(null);
+        }, ms);
+    });
+    try {
+        const r = await Promise.race([
+            op.precheck(params, { ...confirmCtx(ctx, role), signal }),
+            timeout,
+        ]);
+        if (r === null || r.ok)
+            return null;
+        return { code: r.code, message: r.message, ...(r.next !== undefined && { next: r.next }) };
+    }
+    catch (err) {
+        log?.warn("platform precheck failed; the card is shown", { operation: op.id, err });
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** 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/read-tool-output.d.ts

@@ -1,4 +1,4 @@
-import type { KernelConfig } from "../../config/schema.js";
+import type { KernelConfigService } from "../../infra/config/kernel-config.service.js";
 import { type ToolOutputs } from "../outputs.js";
 import type { BuiltinTool } from "../registry.js";
 /**
@@ -11,8 +11,8 @@ export declare function readPage(id: string, content: string, opts: {
     charOffset: number;
     budget: number;
 }): string;
-/** 内置工具 `read_tool_output`：读本会话未过期的输出存档（只读、默认 allow）。 */
+/** 内置工具 `ReadToolOutput`：读本会话未过期的输出存档（只读、默认 allow）。 */
 export declare function readToolOutputTool(deps: {
     outputs: Pick<ToolOutputs, "load">;
-    config: () => KernelConfig;
+    config: Pick<KernelConfigService, "get">;
 }): BuiltinTool;

package/dist/tools/builtins/read-tool-output.js

@@ -8,7 +8,7 @@ const DEFAULT_LIMIT = 200;
  */
 const FOOTER_RESERVE = 200;
 const SPEC = {
-    name: "read_tool_output",
+    name: "ReadToolOutput",
     description: "Read a saved tool output by its id, page by page. Large tool results are truncated in the " +
         "conversation and saved in full; the truncation notice gives the output id. Lines are numbered " +
         "from 0. Each call returns up to `limit` lines starting at line `offset`, capped at a maximum " +
@@ -85,7 +85,7 @@ export function readPage(id, content, opts) {
     const footer = `[Lines ${offset}–${last} of ${total}]`;
     return [parts.join("\n"), ...(cut === null ? [] : [cut]), footer].join("\n");
 }
-/** 内置工具 `read_tool_output`：读本会话未过期的输出存档（只读、默认 allow）。 */
+/** 内置工具 `ReadToolOutput`：读本会话未过期的输出存档（只读、默认 allow）。 */
 export function readToolOutputTool(deps) {
     return {
         spec: SPEC,
@@ -95,7 +95,7 @@ export function readToolOutputTool(deps) {
             const content = await deps.outputs.load({ orgId: ctx.orgId, conversationId: ctx.conversationId }, id);
             if (content === null)
                 throw new ToolError(outputNotFoundText(id));
-            const cfg = deps.config().tools;
+            const cfg = deps.config.get().tools;
             const budget = Math.max(1, Math.min(cfg.maxResultReadChars, cfg.outputSpillChars - FOOTER_RESERVE));
             return {
                 content: [

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

@@ -1,16 +1,16 @@
 import { type ExecResult } from "@capybara-hq/plugin-sdk";
 import type { BuiltinTool } from "../../registry.js";
 import { type SandboxToolDeps } from "./common.js";
-/** 不给 `timeoutSeconds` 时的命令超时（秒），不超过 `sandbox.limits.maxCommandSeconds`。 */
+/** The command timeout in seconds when `timeout` is not given, at most `sandbox.limits.maxCommandSeconds`. */
 export declare const BASH_DEFAULT_TIMEOUT_SECONDS = 120;
 /** The longest `description` (the shell row shows it instead of the command). */
 export declare const BASH_DESCRIPTION_MAX_CHARS = 120;
-/** bash 结果超过这么多字符即转存（走现有输出存档，模型用 read_tool_output 分页读）。 */
+/** bash 结果超过这么多字符即转存（走现有输出存档，模型用 ReadToolOutput 分页读）。 */
 export declare const BASH_SPILL_CHARS = 30000;
 /**
  * 命令结果 → 给模型的文本。`budgetClamped`：运行的时限把超时收紧到了 `seconds`（Ruling M20），超时说明改为
- * 指向 `runtime.maxRunSeconds`，而不是让模型加大 timeoutSeconds。
+ * 指向 `runtime.maxRunSeconds`，而不是让模型加大 timeout。`workspace`: the instance's workspace root.
  */
-export declare function formatExec(r: ExecResult, seconds: number, budgetClamped?: boolean): string;
-/** 内置工具 `sandbox_bash`：在本对话的沙箱里执行命令。 */
+export declare function formatExec(r: ExecResult, seconds: number, budgetClamped?: boolean, workspace?: string): string;
+/** 内置工具 `Bash`：在本对话的沙箱里执行命令。 */
 export declare function sandboxBashTool(deps: SandboxToolDeps): BuiltinTool;