@capybara-hq/kernel 0.0.0-stage → 0.1.0-rc.0

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

@@ -0,0 +1,81 @@
+import type { ToolSpec } from "@capybara-hq/plugin-sdk";
+import { z } from "zod";
+import type { EventPayload } from "../../conversations/events.js";
+import { type RosterEntry } from "../../runtime/subagents/roster.js";
+import type { BuiltinTool } from "../registry.js";
+/**
+ * The `agent` builtin tool (sub-agents spec §4): dispatches a sub-agent. Its description is built
+ * per parent agent version from the roster ({@link agentToolSpec}); the tool pipeline handles the
+ * call itself (dispatch, suspend, resume), so {@link agentTool}'s `run` is only a guard.
+ */
+export declare const AGENT_TOOL = "agent";
+/** How a sub-agent's run ended (`subagent_finished.status`). */
+export type SubagentStatus = EventPayload<"subagent_finished">["status"];
+/** The input of an `agent` call (§4.2). */
+export declare const AgentToolInput: z.ZodObject<{
+    description: z.ZodString;
+    prompt: z.ZodString;
+    subagent_type: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodEnum<{
+        capable: "capable";
+        fast: "fast";
+        inherit: "inherit";
+        standard: "standard";
+    }>>;
+    resume: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type AgentToolInputT = z.infer<typeof AgentToolInput>;
+/**
+ * The `agent` tool definition of a parent agent version (§4.3): the fixed text with
+ * `maxConcurrent`, then one line per roster entry in roster order. Built at tool resolution, so the
+ * spec hash changes with the roster or the limit (logged per request in `tool_specs`).
+ */
+export declare function agentToolSpec(roster: readonly RosterEntry[], maxConcurrent: number): ToolSpec;
+/** Refusals (§4.5): `isError` results written without starting anything (model-visible). */
+export declare const AGENT_REFUSALS: {
+    readonly unknownType: (x: string, roster: readonly string[]) => string;
+    readonly tooManyConcurrent: (n: number) => string;
+    readonly tooManyDispatches: (n: number) => string;
+    readonly budget: (n: number) => string;
+    readonly noSuchAgent: (id: string) => string;
+    readonly stillRunning: (id: string) => string;
+    readonly resumeWithType: "resume cannot be combined with subagent_type or model.";
+    readonly notAvailableHere: "Sub-agents are not available in this conversation.";
+    readonly agentNotAvailable: (name: string) => string;
+};
+/**
+ * The parent run was stopped while this sub-agent worked (§4.4, §12): the result of a stopped
+ * parent's open `agent` call, and the text of a child stopped with its parent.
+ */
+export declare const AGENT_STOPPED_WITH_RUN_TEXT = "The run was stopped while this sub-agent was working; it was stopped too.";
+/**
+ * The tool result of a finished sub-agent (§4.4): the text for how its run ended, a blank line, and
+ * the status line with its `agentId`. `ownModel`: an org agent dispatched with a `model` that was
+ * ignored. `abortedBy: "parent"`: stopped together with the parent run (seen only in logs).
+ */
+export declare function agentResultText(r: {
+    reply: string;
+    agentId: string;
+    status: SubagentStatus;
+    errorCode?: string;
+    errorMessage?: string;
+    toolCalls: number;
+    durationMs: number;
+    tokens: number;
+    ownModel?: boolean;
+    abortedBy?: "user" | "parent";
+    /**
+     * Phase D: the report of a person's fork invocation, whose parent need not have the `agent`
+     * tool: the status line leaves out the resume hint (batch 3 review m2).
+     */
+    noResumeHint?: boolean;
+}): {
+    content: string;
+    isError: boolean;
+};
+/**
+ * The builtin. `defaultPolicy: "allow"` (§4.6): a sub-agent runs only tools its parent may run,
+ * each under its own policy. The tool pipeline dispatches `agent` calls itself; `run` answers only
+ * when a call reaches it anyway.
+ */
+export declare const agentTool: BuiltinTool;

package/dist/tools/builtins/agent.js

@@ -0,0 +1,223 @@
+import { z } from "zod";
+import { ROSTER_DESCRIPTION_MAX } from "../../runtime/subagents/roster.js";
+/**
+ * The `agent` builtin tool (sub-agents spec §4): dispatches a sub-agent. Its description is built
+ * per parent agent version from the roster ({@link agentToolSpec}); the tool pipeline handles the
+ * call itself (dispatch, suspend, resume), so {@link agentTool}'s `run` is only a guard.
+ */
+export const AGENT_TOOL = "agent";
+/** The input of an `agent` call (§4.2). */
+export const AgentToolInput = z
+    .object({
+    description: z.string().min(1).max(80),
+    prompt: z.string().min(1).max(100_000),
+    subagent_type: z.string().min(1).max(130).optional(),
+    model: z.enum(["inherit", "fast", "standard", "capable"]).optional(),
+    resume: z.string().max(64).optional(),
+})
+    .strict();
+/** Display only (UI refresh B): the task name, then the type; never sent to the model. */
+const KEY_ARGS = ["description", "subagent_type"];
+const INPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        description: {
+            type: "string",
+            minLength: 1,
+            maxLength: 80,
+            description: "A short label for the task (3 to 6 words), shown to the user.",
+        },
+        prompt: {
+            type: "string",
+            minLength: 1,
+            maxLength: 100000,
+            description: "The complete task for the sub-agent. It sees nothing else of this conversation: include " +
+                "every fact, file path and constraint it needs, and say what its final reply must contain.",
+        },
+        subagent_type: {
+            type: "string",
+            minLength: 1,
+            maxLength: 130,
+            description: "Which agent type to run, from the list in this tool's description. Defaults to " +
+                "general-purpose.",
+        },
+        model: {
+            type: "string",
+            enum: ["inherit", "fast", "standard", "capable"],
+            description: "Model tier for this sub-agent: fast and cheap for mechanical work, standard for " +
+                "integration and judgment, capable for design and final reviews. Defaults to the agent " +
+                "type's own setting, else your model.",
+        },
+        resume: {
+            type: "string",
+            maxLength: 64,
+            description: "The agentId from an earlier result of this tool: sends prompt to that sub-agent as a " +
+                "follow-up, with its earlier context intact. Leave subagent_type and model unset.",
+        },
+    },
+    required: ["description", "prompt"],
+    additionalProperties: false,
+};
+/** The text before the roster (§4.3), with the concurrency limit. */
+const head = (maxConcurrent) => "Dispatch a sub-agent: a fresh agent with its own context that works on one task and returns its " +
+    "final reply as this tool's result. The sub-agent sees only your prompt, not this conversation, so " +
+    "include everything it needs and say what its final reply must contain. It shares your sandbox " +
+    "files. You wait until it finishes. To run several at once, call this tool several times in the " +
+    `same response (at most ${maxConcurrent} at a time); their commands run in the sandbox at the ` +
+    "same time, so give parallel sub-agents separate files or directories. Sub-agents cannot " +
+    "dispatch sub-agents or ask the user questions. To send a finished sub-agent a follow-up while " +
+    "keeping its context, pass the agentId from its result as resume.\n" +
+    "\n" +
+    "Agent types (subagent_type):\n";
+/**
+ * Roster text from owners and plugins, made inert (batch 1 review M1): whitespace runs (newlines
+ * included) become one space, so an entry stays one line and cannot add entries or sections, and
+ * `<` / `>` become `‹` / `›`, so no tag can be opened or closed (Claude agent descriptions carry
+ * `<example>` blocks; they stay readable). Length-preserving apart from the whitespace.
+ */
+const inert = (s) => s.replace(/\s+/g, " ").trim().replaceAll("<", "‹").replaceAll(">", "›");
+function rosterLine(e) {
+    const description = inert(e.description).slice(0, ROSTER_DESCRIPTION_MAX);
+    const line = `- ${inert(e.type)}: ${description}`;
+    if (e.source !== "agent")
+        return line;
+    return e.agentName === undefined
+        ? `${line} (another agent, with its own tools and model)`
+        : `${line} (the agent "${inert(e.agentName).replaceAll('"', "'")}", with its own tools and model)`;
+}
+/**
+ * The `agent` tool definition of a parent agent version (§4.3): the fixed text with
+ * `maxConcurrent`, then one line per roster entry in roster order. Built at tool resolution, so the
+ * spec hash changes with the roster or the limit (logged per request in `tool_specs`).
+ */
+export function agentToolSpec(roster, maxConcurrent) {
+    return {
+        name: AGENT_TOOL,
+        description: head(maxConcurrent) + roster.map(rosterLine).join("\n"),
+        inputSchema: INPUT_SCHEMA,
+        keyArgs: KEY_ARGS,
+    };
+}
+/**
+ * The static definition: the rendering for a roster of only general-purpose at the default
+ * `subagents.maxConcurrentPerRun` (what an agent without `subagents` gets under the defaults).
+ * Written out as a literal for the tool design check; a test pins it equal to
+ * `agentToolSpec([general-purpose], 4)`.
+ */
+const SPEC = {
+    name: "agent",
+    description: "Dispatch a sub-agent: a fresh agent with its own context that works on one task and returns its " +
+        "final reply as this tool's result. The sub-agent sees only your prompt, not this conversation, so " +
+        "include everything it needs and say what its final reply must contain. It shares your sandbox " +
+        "files. You wait until it finishes. To run several at once, call this tool several times in the " +
+        "same response (at most 4 at a time); their commands run in the sandbox at the same time, so give " +
+        "parallel sub-agents separate files or directories. Sub-agents cannot dispatch sub-agents or ask " +
+        "the user questions. To send a finished sub-agent a follow-up while keeping its context, pass the " +
+        "agentId from its result as resume.\n" +
+        "\n" +
+        "Agent types (subagent_type):\n" +
+        "- general-purpose: a copy of you with your tools and skills, for multi-step work.",
+    inputSchema: INPUT_SCHEMA,
+    keyArgs: KEY_ARGS,
+};
+/** Refusals (§4.5): `isError` results written without starting anything (model-visible). */
+export const AGENT_REFUSALS = {
+    unknownType: (x, roster) => `Unknown subagent_type "${x}". Available: ${roster.join(", ")}.`,
+    tooManyConcurrent: (n) => `At most ${n} sub-agents can run at once in this run; dispatch the remaining tasks after these finish.`,
+    tooManyDispatches: (n) => `This run has dispatched ${n} sub-agents, the limit; do the remaining work yourself.`,
+    budget: (n) => `Sub-agents of this run have used their token budget (${count(n)} tokens); do the remaining work yourself.`,
+    noSuchAgent: (id) => `No sub-agent with agentId "${id}" in this conversation.`,
+    stillRunning: (id) => `Sub-agent "${id}" is still running; wait for its result before sending a follow-up.`,
+    resumeWithType: "resume cannot be combined with subagent_type or model.",
+    notAvailableHere: "Sub-agents are not available in this conversation.",
+    agentNotAvailable: (name) => `The agent "${name}" is not available to the person who started this conversation; do this task yourself or use another agent type.`,
+};
+/**
+ * The parent run was stopped while this sub-agent worked (§4.4, §12): the result of a stopped
+ * parent's open `agent` call, and the text of a child stopped with its parent.
+ */
+export const AGENT_STOPPED_WITH_RUN_TEXT = "The run was stopped while this sub-agent was working; it was stopped too.";
+/** `12345` → `12,345` (no locale data involved, so the text is the same on every replica). */
+const count = (n) => String(Math.round(n)).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+/** `4s`, `1m 05s`, `1h 02m`. */
+function duration(ms) {
+    const s = Math.round(ms / 1000);
+    if (s < 60)
+        return `${s}s`;
+    if (s < 3600)
+        return `${Math.floor(s / 60)}m ${String(s % 60).padStart(2, "0")}s`;
+    return `${Math.floor(s / 3600)}h ${String(Math.floor((s % 3600) / 60)).padStart(2, "0")}m`;
+}
+/**
+ * The tool result of a finished sub-agent (§4.4): the text for how its run ended, a blank line, and
+ * the status line with its `agentId`. `ownModel`: an org agent dispatched with a `model` that was
+ * ignored. `abortedBy: "parent"`: stopped together with the parent run (seen only in logs).
+ */
+export function agentResultText(r) {
+    const reply = r.reply.trim();
+    let status;
+    let text;
+    let isError = true;
+    switch (r.status) {
+        case "completed":
+            [status, text, isError] = ["completed", reply, false];
+            break;
+        case "max_steps":
+            [status, text, isError] = [
+                "stopped at the step limit; the reply may be partial",
+                reply,
+                false,
+            ];
+            break;
+        case "max_duration":
+            status = "stopped at the time limit; the reply may be partial";
+            text = reply === "" ? "The sub-agent produced no reply before the time limit." : reply;
+            isError = false;
+            break;
+        case "budget":
+            [status, text] = ["stopped: token budget used up", reply];
+            break;
+        case "aborted":
+            [status, text] =
+                r.abortedBy === "parent"
+                    ? ["stopped with this run", AGENT_STOPPED_WITH_RUN_TEXT]
+                    : ["stopped by the user", "The user stopped this sub-agent."];
+            break;
+        case "timed_out":
+            // the parent's sub-agents wait timed out (§7.2) and stopped it; the parent goes on
+            [status, text] = ["timed out", "stopped: the sub-agent wait timed out"];
+            break;
+        case "failed":
+            status = r.errorCode === undefined ? "failed" : `failed (${r.errorCode})`;
+            text =
+                r.errorMessage === undefined
+                    ? "The sub-agent failed."
+                    : `The sub-agent failed: ${r.errorMessage}`;
+            break;
+    }
+    const parts = [
+        `agentId: ${r.agentId}`,
+        status,
+        ...(r.ownModel === true ? ["model: the agent's own"] : []),
+        `${r.toolCalls} tool ${r.toolCalls === 1 ? "call" : "calls"}`,
+        duration(r.durationMs),
+        r.noResumeHint === true
+            ? `${count(r.tokens)} tokens.`
+            : `${count(r.tokens)} tokens. Pass the agentId as resume to send this sub-agent a follow-up.`,
+    ];
+    const line = `[${parts.join(" · ")}]`;
+    return { content: text === "" ? line : `${text}\n\n${line}`, isError };
+}
+/**
+ * The builtin. `defaultPolicy: "allow"` (§4.6): a sub-agent runs only tools its parent may run,
+ * each under its own policy. The tool pipeline dispatches `agent` calls itself; `run` answers only
+ * when a call reaches it anyway.
+ */
+export const agentTool = {
+    spec: SPEC,
+    defaultPolicy: "allow",
+    run: async () => ({
+        content: [{ type: "text", text: AGENT_REFUSALS.notAvailableHere }],
+        isError: true,
+    }),
+};

package/dist/tools/builtins/ask-user.d.ts

@@ -0,0 +1,28 @@
+import { type FormAnswer, type InputForm } from "@capybara-hq/plugin-sdk";
+import type { KernelConfig } from "../../config/schema.js";
+import type { BuiltinTool } from "../registry.js";
+interface Question {
+    question: string;
+    header: string;
+    multiSelect: boolean;
+    options: {
+        label: string;
+        description: string;
+    }[];
+}
+/**
+ * 问题 → 表单（每个问题一个枚举字段）。InputForm 没有「选项说明」：header 与各选项说明写进字段说明，
+ * 每个选项一行 `- <label>: <description>`。
+ */
+export declare function questionsForm(questions: Question[]): InputForm;
+/** 答案 → 给模型的结果文本：`User answered: "<question>" = "<answer>"; …`。 */
+export declare function answerText(questions: Question[], answer: FormAnswer): string;
+/**
+ * 内置工具 `ask_user`：用通用的输入请求机制实现——首次调用返回 `input_required`，
+ * 内核暂停运行并展示表单；用户回答（或超时）后用同一 input 再次调用，按 `ctx.resume` 生成结果。
+ * 默认 allow（提问本身就是让用户参与，不再审批）。
+ */
+export declare function askUserTool(deps: {
+    config: () => KernelConfig;
+}): BuiltinTool;
+export {};

package/dist/tools/builtins/ask-user.js

@@ -0,0 +1,139 @@
+import { ToolError } from "@capybara-hq/plugin-sdk";
+const SPEC = {
+    name: "ask_user",
+    description: "Ask the user one or more multiple-choice questions and wait for the answers. Use it when you " +
+        "need the user's preference or decision to continue, or when a request is ambiguous; do not use " +
+        "it for questions you can answer yourself. Each question has a short header, 2-4 options with a " +
+        "label and a description, and can allow selecting several options (multiSelect). The user can " +
+        "always choose Other and type their own answer instead. The run pauses until the user answers; " +
+        "if they do not answer in time, the result says so.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            questions: {
+                type: "array",
+                minItems: 1,
+                maxItems: 4,
+                description: "Questions to ask (1-4).",
+                items: {
+                    type: "object",
+                    properties: {
+                        question: {
+                            type: "string",
+                            minLength: 1,
+                            description: "The complete question, ending with a question mark.",
+                        },
+                        header: {
+                            type: "string",
+                            minLength: 1,
+                            maxLength: 12,
+                            description: 'A very short label for the question (max 12 chars), e.g. "Database".',
+                        },
+                        multiSelect: {
+                            type: "boolean",
+                            description: "Allow the user to select more than one option.",
+                        },
+                        options: {
+                            type: "array",
+                            minItems: 2,
+                            maxItems: 4,
+                            description: "The choices (2-4). Do not add an Other option; it is always offered.",
+                            items: {
+                                type: "object",
+                                properties: {
+                                    label: {
+                                        type: "string",
+                                        minLength: 1,
+                                        description: "Short text of the choice (1-5 words).",
+                                    },
+                                    description: {
+                                        type: "string",
+                                        description: "What this choice means or implies.",
+                                    },
+                                },
+                                required: ["label", "description"],
+                                additionalProperties: false,
+                            },
+                        },
+                    },
+                    required: ["question", "header", "multiSelect", "options"],
+                    additionalProperties: false,
+                },
+            },
+        },
+        required: ["questions"],
+        additionalProperties: false,
+    },
+};
+/** 第 i 个问题的字段 key。 */
+const fieldKey = (i) => `q${i}`;
+/**
+ * 问题 → 表单（每个问题一个枚举字段）。InputForm 没有「选项说明」：header 与各选项说明写进字段说明，
+ * 每个选项一行 `- <label>: <description>`。
+ */
+export function questionsForm(questions) {
+    return {
+        title: questions.map((q) => q.header).join(" · "),
+        fields: questions.map((q, i) => ({
+            key: fieldKey(i),
+            label: q.question,
+            description: [
+                q.header,
+                ...q.options.map((o) => o.description === "" ? `- ${o.label}` : `- ${o.label}: ${o.description}`),
+            ].join("\n"),
+            schema: { type: "string", enum: q.options.map((o) => o.label) },
+            multiSelect: q.multiSelect,
+            allowOther: true,
+            required: true,
+        })),
+    };
+}
+/** 答案 → 给模型的结果文本：`User answered: "<question>" = "<answer>"; …`。 */
+export function answerText(questions, answer) {
+    const parts = questions.map((q, i) => {
+        const v = answer[fieldKey(i)];
+        const text = v === undefined ? "(no answer)" : Array.isArray(v) ? v.join(", ") : String(v);
+        return `"${q.question}" = "${text}"`;
+    });
+    return `User answered: ${parts.join("; ")}`;
+}
+/** 给模型的结果文本 + 给界面的一句话说明（中英文，不进模型上下文）。 */
+const text = (t, zh, en) => ({
+    content: [{ type: "text", text: t }],
+    display: { summary: { zh, en } },
+});
+/**
+ * 内置工具 `ask_user`：用通用的输入请求机制实现——首次调用返回 `input_required`，
+ * 内核暂停运行并展示表单；用户回答（或超时）后用同一 input 再次调用，按 `ctx.resume` 生成结果。
+ * 默认 allow（提问本身就是让用户参与，不再审批）。
+ */
+export function askUserTool(deps) {
+    return {
+        spec: SPEC,
+        defaultPolicy: "allow",
+        async run(input, ctx) {
+            const { questions } = input;
+            if (ctx.resume) {
+                const { answer, state } = ctx.resume;
+                if (answer !== null) {
+                    const n = questions.length;
+                    return text(answerText(questions, answer), `用户回答了 ${n} 个问题`, `User answered ${n} question${n === 1 ? "" : "s"}`);
+                }
+                const hours = state?.hours;
+                // 运行在等待中被中止时内核直接写取消说明，不会再调用工具；能走到这里的 null 只有超时
+                // （以及未来的「用户关闭提问」，那时 state 不带小时数）。
+                return typeof hours === "number"
+                    ? text(`The user did not answer within ${hours}h.`, `用户未在 ${hours} 小时内回答`, `No answer within ${hours}h`)
+                    : text("The user dismissed the question.", "用户关闭了提问", "User dismissed the question");
+            }
+            for (const q of questions) {
+                const labels = q.options.map((o) => o.label);
+                if (new Set(labels).size !== labels.length) {
+                    throw new ToolError(`Option labels must be unique within a question; "${q.question}" has duplicates. Provide distinct labels.`);
+                }
+            }
+            const state = { hours: deps.config().tools.approvalTimeoutHours };
+            return { kind: "input_required", form: questionsForm(questions), state };
+        },
+    };
+}

package/dist/tools/builtins/read-tool-output.d.ts

@@ -0,0 +1,18 @@
+import type { KernelConfig } from "../../config/schema.js";
+import { type ToolOutputs } from "../outputs.js";
+import type { BuiltinTool } from "../registry.js";
+/**
+ * 按行分页读取：从 `offset` 行（第一行从 `charOffset` 字符起）读最多 `limit` 行，正文不超过 `budget` 个字符。
+ * 正文按整行截止；只有第一行本身就超过上限时按字符切，并写明续读位置。结尾写 `[Lines a–b of total]`（0 起）。
+ */
+export declare function readPage(id: string, content: string, opts: {
+    offset: number;
+    limit: number;
+    charOffset: number;
+    budget: number;
+}): string;
+/** 内置工具 `read_tool_output`：读本会话未过期的输出存档（只读、默认 allow）。 */
+export declare function readToolOutputTool(deps: {
+    outputs: Pick<ToolOutputs, "load">;
+    config: () => KernelConfig;
+}): BuiltinTool;

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

@@ -0,0 +1,108 @@
+import { ToolError } from "@capybara-hq/plugin-sdk";
+import { outputNotFoundText } from "../outputs.js";
+/** 默认一次读的行数。 */
+const DEFAULT_LIMIT = 200;
+/**
+ * 给尾部说明留的字符数：正文上限同时不超过 `outputSpillChars - FOOTER_RESERVE`，
+ * 读取结果本身不会因超过转存阈值被再次转存。
+ */
+const FOOTER_RESERVE = 200;
+const SPEC = {
+    name: "read_tool_output",
+    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 " +
+        "number of characters, and ends with `[Lines <a>–<b> of <total>]`; continue with offset=<b+1>. " +
+        "If a single line is too long, it is cut and the result says which offset and charOffset to " +
+        "call again with. Outputs expire after a retention period.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            id: {
+                type: "string",
+                minLength: 1,
+                description: "The output id from the truncation notice.",
+            },
+            offset: {
+                type: "integer",
+                minimum: 0,
+                description: "First line to read (0-based). Default 0.",
+            },
+            limit: {
+                type: "integer",
+                minimum: 1,
+                description: `Maximum number of lines to read. Default ${DEFAULT_LIMIT}.`,
+            },
+            charOffset: {
+                type: "integer",
+                minimum: 0,
+                description: "Character position to start from within the first line (only to continue a cut line). Default 0.",
+            },
+        },
+        required: ["id"],
+        additionalProperties: false,
+    },
+    annotations: { readOnlyHint: true },
+};
+/**
+ * 按行分页读取：从 `offset` 行（第一行从 `charOffset` 字符起）读最多 `limit` 行，正文不超过 `budget` 个字符。
+ * 正文按整行截止；只有第一行本身就超过上限时按字符切，并写明续读位置。结尾写 `[Lines a–b of total]`（0 起）。
+ */
+export function readPage(id, content, opts) {
+    const lines = content.split("\n");
+    const total = lines.length;
+    const { offset, limit, charOffset, budget } = opts;
+    if (offset >= total) {
+        throw new ToolError(`Offset ${offset} is past the end of output ${id} (${total} lines). Use an offset below ${total}.`);
+    }
+    const first = lines[offset];
+    if (charOffset > 0 && charOffset >= first.length) {
+        throw new ToolError(`charOffset ${charOffset} is past the end of line ${offset} (${first.length} characters). Use a charOffset below ${first.length}.`);
+    }
+    const end = Math.min(total, offset + limit);
+    const parts = [];
+    let used = 0;
+    let last = offset;
+    let cut = null;
+    for (let i = offset; i < end; i++) {
+        const text = i === offset ? first.slice(charOffset) : lines[i];
+        const cost = (parts.length > 0 ? 1 : 0) + text.length;
+        if (used + cost <= budget) {
+            parts.push(text);
+            used += cost;
+            last = i;
+            continue;
+        }
+        if (parts.length === 0) {
+            // 这一行本身就超过上限：按字符切
+            parts.push(text.slice(0, budget));
+            last = i;
+            const next = charOffset + budget;
+            cut = `[Line ${i} continues; call again with offset=${i} charOffset=${next}]`;
+        }
+        break;
+    }
+    const footer = `[Lines ${offset}–${last} of ${total}]`;
+    return [parts.join("\n"), ...(cut === null ? [] : [cut]), footer].join("\n");
+}
+/** 内置工具 `read_tool_output`：读本会话未过期的输出存档（只读、默认 allow）。 */
+export function readToolOutputTool(deps) {
+    return {
+        spec: SPEC,
+        defaultPolicy: "allow",
+        async run(input, ctx) {
+            const { id, offset = 0, limit = DEFAULT_LIMIT, charOffset = 0 } = input;
+            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 budget = Math.max(1, Math.min(cfg.maxResultReadChars, cfg.outputSpillChars - FOOTER_RESERVE));
+            return {
+                content: [
+                    { type: "text", text: readPage(id, content, { offset, limit, charOffset, budget }) },
+                ],
+                display: { summary: { zh: `已读取输出 ${id}`, en: `Read output ${id}` } },
+            };
+        },
+    };
+}

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

@@ -0,0 +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`。 */
+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 分页读）。 */
+export declare const BASH_SPILL_CHARS = 30000;
+/**
+ * 命令结果 → 给模型的文本。`budgetClamped`：运行的时限把超时收紧到了 `seconds`（Ruling M20），超时说明改为
+ * 指向 `runtime.maxRunSeconds`，而不是让模型加大 timeoutSeconds。
+ */
+export declare function formatExec(r: ExecResult, seconds: number, budgetClamped?: boolean): string;
+/** 内置工具 `sandbox_bash`：在本对话的沙箱里执行命令。 */
+export declare function sandboxBashTool(deps: SandboxToolDeps): BuiltinTool;