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

package/dist/tools/builtins/sandbox/read.js

@@ -1,25 +1,27 @@
 import { ToolError } from "@capybara-hq/plugin-sdk";
 import { viewPath } from "../../view.js";
 import { checkPath, clip, display, inSandbox, looksBinary, sandboxBaseTimeoutMs, unavailableWhenNoSandbox, withNotices, } from "./common.js";
+import { normalizeSandboxPath, recordedFile } from "./file-state.js";
 /** 不给 `limit` 时一次读的行数。 */
 const DEFAULT_LIMIT = 2000;
 /** 单行最多显示的字符数（更长的截断并注明）。 */
 const MAX_LINE_CHARS = 2000;
-/** 最多读出的字节数（更大的文件只读开头，并说明用 sandbox_bash 读其余部分）。 */
+/** 最多读出的字节数（更大的文件只读开头，并说明用 Bash 读其余部分）。 */
 export const READ_MAX_BYTES = 10 * 1024 * 1024;
 const SPEC = {
-    name: "sandbox_read",
+    name: "Read",
     // Display only (the tool row; not in the fingerprint, never sent to the model).
-    keyArgs: ["path"],
+    keyArgs: ["file_path"],
     description: "Read a text file from this conversation's sandbox, with line numbers. Use it to look at " +
         "source code, data files, logs and files the user attached (under /workspace/attachments). " +
         "Paths are absolute, under /workspace, /skills or /tmp. Lines are numbered from 1; pass " +
-        "offset and limit to read part of a long file. Binary files are not shown; use sandbox_bash " +
-        "to inspect them. Do not use it to list directories; use sandbox_glob instead.",
+        "offset and limit to read part of a long file. Binary files are not shown; use Bash " +
+        "to inspect them. Do not use it to list directories; use Glob instead. Read a file before you " +
+        "write it: Write and Edit fail on a file you have not read, or one changed since you read it.",
     inputSchema: {
         type: "object",
         properties: {
-            path: {
+            file_path: {
                 type: "string",
                 minLength: 1,
                 description: 'Absolute path of the file, e.g. "/workspace/src/main.py".',
@@ -35,13 +37,13 @@ const SPEC = {
                 description: `Maximum number of lines to read. Default ${DEFAULT_LIMIT}.`,
             },
         },
-        required: ["path"],
+        required: ["file_path"],
         additionalProperties: false,
     },
     annotations: { readOnlyHint: true },
 };
-const notFound = (path) => `File not found: ${clip(path, 200)}. Check the path with sandbox_glob.`;
-const isDirectory = (path) => `${clip(path, 200)} is a directory; use sandbox_glob to list its files.`;
+const notFound = (path) => `File not found: ${clip(path, 200)}. Check the path with Glob.`;
+const isDirectory = (path) => `${clip(path, 200)} is a directory; use Glob to list its files.`;
 const pastEnd = (offset, total) => `offset ${offset} is past the end of the file (${total} lines); pass an offset of at most ${total}.`;
 /** The file's lines (a final newline does not start another line). */
 function fileLines(text) {
@@ -70,7 +72,7 @@ export function numberLines(text, offset, limit) {
     }
     return out.join("\n");
 }
-/** 内置工具 `sandbox_read`：读沙箱里的文本文件（只读，组织策略为 ask 时也不审批）。 */
+/** 内置工具 `Read`：读沙箱里的文本文件（只读，组织策略为 ask 时也不审批）。 */
 export function sandboxReadTool(deps) {
     return {
         spec: SPEC,
@@ -79,7 +81,7 @@ export function sandboxReadTool(deps) {
         timeoutMs: () => sandboxBaseTimeoutMs(deps.config.get()),
         async run(input, ctx) {
             const { offset = 1, limit = DEFAULT_LIMIT } = input;
-            const path = checkPath(input.path);
+            const path = checkPath(input.file_path, "file_path");
             const { value, notices } = await inSandbox(deps, ctx, async ({ h, p, signal }) => {
                 const st = await p.stat(h, path, signal);
                 if (st === null)
@@ -95,7 +97,7 @@ export function sandboxReadTool(deps) {
             // display only: the line range shown on the row
             let range = {};
             if (looksBinary(value.data)) {
-                text = `Binary file (${value.size} bytes); use sandbox_bash to inspect it (for example file or xxd).`;
+                text = `Binary file (${value.size} bytes); use Bash to inspect it (for example file or xxd).`;
             }
             else if (value.data.byteLength === 0) {
                 text = "(empty file)";
@@ -108,13 +110,18 @@ export function sandboxReadTool(deps) {
                     toLine: Math.min(fileLines(decoded).length, offset - 1 + limit),
                 };
                 if (value.truncated) {
-                    text += `\n[Only the first ${READ_MAX_BYTES} bytes of this ${value.size}-byte file were read; use sandbox_bash (e.g. sed -n or tail) for the rest.]`;
+                    text += `\n[Only the first ${READ_MAX_BYTES} bytes of this ${value.size}-byte file were read; use Bash (e.g. sed -n or tail) for the rest.]`;
                 }
             }
             return {
                 content: [{ type: "text", text: withNotices(notices, text) }],
                 display: display(`读取 ${clip(path, 180)}`, `Read ${clip(path, 180)}`),
-                view: { kind: "read", path: viewPath(path), ...range },
+                view: {
+                    kind: "read",
+                    path: viewPath(path),
+                    ...range,
+                    file: recordedFile(normalizeSandboxPath(path), value.data, value.size),
+                },
             };
         },
     };

package/dist/tools/builtins/sandbox/task-output.d.ts

@@ -0,0 +1,63 @@
+import { type SandboxHandle } from "@capybara-hq/plugin-sdk";
+import type { BackgroundTaskRow } from "../../../background/store.js";
+import type { IfRunningResult, SandboxService, TaggedProvider } from "../../../sandbox/sandbox.service.js";
+import type { BuiltinCallContext, BuiltinTool } from "../../registry.js";
+import { type SandboxToolDeps } from "./common.js";
+/** How long `TaskOutput` waits with `block` when `timeout` is not given (ms). */
+export declare const TASK_OUTPUT_DEFAULT_TIMEOUT_MS = 30000;
+/** The longest `TaskOutput` wait (ms). */
+export declare const TASK_OUTPUT_MAX_TIMEOUT_MS = 600000;
+/** How often a blocking `TaskOutput` checks the task (each check a short exec of its own). */
+export declare const TASK_CHECK_INTERVAL_MS = 2000;
+/** What `TaskOutput` and `TaskStop` work with. */
+export interface TaskEnv {
+    store: NonNullable<SandboxToolDeps["background"]>;
+    tasks: NonNullable<SandboxToolDeps["tasks"]>;
+    ifRunning: SandboxService["ifRunning"];
+}
+/** The task tools' dependencies; throws the tool's error when they are missing. */
+export declare function taskEnv(deps: SandboxToolDeps): TaskEnv;
+/**
+ * The task `id` when it belongs to the calling conversation; a task of another conversation (a
+ * sub-agent's, when called from its parent) is not found, the same as an unknown id.
+ */
+export declare function ownedTask(env: TaskEnv, ctx: BuiltinCallContext, id: string): Promise<BackgroundTaskRow>;
+/** `ifRunning` on the task's own sandbox instance; sandbox errors become the tools' errors. */
+export declare function onTaskInstance<T>(env: TaskEnv, task: BackgroundTaskRow, fn: (p: TaggedProvider, h: SandboxHandle, signal: AbortSignal) => Promise<T>, signal: AbortSignal): Promise<IfRunningResult<T>>;
+/**
+ * The task's status line: `Status: running (2m05s)`, `Status: failed, exit code 3, after 4m12s`,
+ * `Status: stopped after 1m00s`, `Status: lost (the sandbox was suspended) after 3s`.
+ */
+export declare function statusLine(task: BackgroundTaskRow, now?: Date): string;
+/** The absolute path of the task's output file, as the model sees it. */
+export declare const outputFile: (task: BackgroundTaskRow) => string;
+/** Why the output cannot be read: the task's sandbox instance is not running. */
+export declare function unavailableText(task: BackgroundTaskRow, r: IfRunningResult<unknown>): string;
+/**
+ * The exec that checks and reads task `t` (relative to `/workspace`): for a running task first
+ * its status line (the poller's, {@link pollScript}: liveness, then the exit file), then
+ * `size <bytes>` and `out <base64>`, at most `cap` bytes of the output from byte `offset` on.
+ * The file is never read whole: `tail -c +<offset+1> | head -c <cap>`. Without `read` only the
+ * status line.
+ */
+export declare function taskReadScript(t: {
+    id: string;
+    sid: string | null;
+    running: boolean;
+}, offset: number, cap: number, read?: boolean): string;
+/**
+ * The bytes of `buf` up to its last whole UTF-8 character: a character cut by the read's cap is
+ * left for the next read.
+ */
+export declare function wholeUtf8Length(buf: Uint8Array): number;
+/**
+ * Built-in `TaskOutput` (spec 2026-11-05-background-bash-design §2.2): a task's status and the
+ * output since this conversation's last read of it. Every check is a short exec through
+ * `SandboxService.ifRunning` on the task's own sandbox instance: it never creates or resumes a
+ * sandbox, so a suspended or rebuilt one means the task is lost (its output unavailable). With
+ * `block`, checks every {@link TASK_CHECK_INTERVAL_MS}, each under a lease of its own, until the
+ * task ends or the wait (at most `timeout` and the run's time left) is over; the checks only
+ * detect the end, and the one read that makes the result finishes the task (reported). The output
+ * read is capped at `tools.outputSpillChars` bytes; the pipeline spills the result beyond that.
+ */
+export declare function taskOutputTool(deps: SandboxToolDeps): BuiltinTool;

package/dist/tools/builtins/sandbox/task-output.js

@@ -0,0 +1,304 @@
+import { setTimeout as sleep } from "node:timers/promises";
+import { isSandboxGoneError, ToolError, } from "@capybara-hq/plugin-sdk";
+import { TASK_ID_RE, TASKS_DIR } from "../../../background/launch.js";
+import { formatElapsed, lostReasonText } from "../../../background/render.js";
+import { SID_RE } from "../../../background/session.js";
+import { parsePollOutput, polledAs, pollScript, } from "../../../background/status.js";
+import { notRunningAs, RECREATED } from "../../../background/stop.js";
+import { clip, display, mapSandboxError, noSandboxError, runTimeLeftMs, sandboxBaseTimeoutMs, unavailableWhenNoSandbox, } from "./common.js";
+/** How long `TaskOutput` waits with `block` when `timeout` is not given (ms). */
+export const TASK_OUTPUT_DEFAULT_TIMEOUT_MS = 30_000;
+/** The longest `TaskOutput` wait (ms). */
+export const TASK_OUTPUT_MAX_TIMEOUT_MS = 600_000;
+/** How often a blocking `TaskOutput` checks the task (each check a short exec of its own). */
+export const TASK_CHECK_INTERVAL_MS = 2000;
+/** The time limit of one check or read exec. */
+const READ_EXEC_TIMEOUT_MS = 30_000;
+const SPEC = {
+    name: "TaskOutput",
+    // Display only (the tool row; not in the fingerprint, never sent to the model).
+    keyArgs: ["task_id"],
+    description: "Read the status and output of a background task started with Bash and run_in_background. " +
+        "The result has the status (running, completed, failed, stopped, timed out or lost), the " +
+        "exit code and the elapsed time, then the output the task wrote since the last TaskOutput " +
+        "call for it. With block (the default) it waits until the task finishes or timeout " +
+        "milliseconds pass, checking every 2 seconds; prefer this over sleeping in Bash. Each call " +
+        "returns a bounded slice of new output; the task's whole output file (its path is in the Bash " +
+        "result) can also be read with Read. You are told when a task finishes, so there is no need " +
+        "to poll for that.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            task_id: {
+                type: "string",
+                minLength: 1,
+                description: "The id of the background task (bt_...) that Bash returned.",
+            },
+            block: {
+                type: "boolean",
+                description: "Whether to wait for the task to finish. Default true.",
+            },
+            timeout: {
+                type: "number",
+                minimum: 0,
+                maximum: TASK_OUTPUT_MAX_TIMEOUT_MS,
+                description: `Milliseconds to wait at most when block is true. Default ${TASK_OUTPUT_DEFAULT_TIMEOUT_MS}, at most ${TASK_OUTPUT_MAX_TIMEOUT_MS}; never past the run's own time limit.`,
+            },
+        },
+        required: ["task_id"],
+        additionalProperties: false,
+    },
+};
+/** The task tools' dependencies; throws the tool's error when they are missing. */
+export function taskEnv(deps) {
+    if (!deps.sandbox.available)
+        throw noSandboxError();
+    const { background, tasks } = deps;
+    if (!background || !tasks || !deps.sandbox.ifRunning) {
+        throw new ToolError("Background tasks are not available here; use Bash without run_in_background instead.");
+    }
+    return { store: background, tasks, ifRunning: deps.sandbox.ifRunning.bind(deps.sandbox) };
+}
+const notFound = (id) => new ToolError(`No background task ${clip(id, 40)} in this conversation. Pass a task id that Bash with run_in_background returned in this conversation.`);
+/**
+ * The task `id` when it belongs to the calling conversation; a task of another conversation (a
+ * sub-agent's, when called from its parent) is not found, the same as an unknown id.
+ */
+export async function ownedTask(env, ctx, id) {
+    if (!TASK_ID_RE.test(id))
+        throw notFound(id);
+    const task = await env.store.get(id);
+    if (!task || task.conversationId !== ctx.conversationId)
+        throw notFound(id);
+    return task;
+}
+/** `ifRunning` on the task's own sandbox instance; sandbox errors become the tools' errors. */
+export async function onTaskInstance(env, task, fn, signal) {
+    try {
+        return await env.ifRunning(task.sandboxConversationId, { createdAt: task.sandboxCreatedAt }, fn, signal);
+    }
+    catch (e) {
+        throw mapSandboxError(e);
+    }
+}
+/**
+ * The task's status line: `Status: running (2m05s)`, `Status: failed, exit code 3, after 4m12s`,
+ * `Status: stopped after 1m00s`, `Status: lost (the sandbox was suspended) after 3s`.
+ */
+export function statusLine(task, now = new Date()) {
+    const end = task.status === "running" ? now : (task.finishedAt ?? now);
+    const elapsed = formatElapsed(end.getTime() - task.startedAt.getTime());
+    if (task.status === "running")
+        return `Status: running (${elapsed})`;
+    let s = `Status: ${task.status === "timed_out" ? "timed out" : task.status}`;
+    if (task.lostReason !== null)
+        s += ` (${lostReasonText(task.lostReason)})`;
+    if (task.exitCode !== null)
+        return `${s}, exit code ${task.exitCode}, after ${elapsed}`;
+    return `${s} after ${elapsed}`;
+}
+/** The absolute path of the task's output file, as the model sees it. */
+export const outputFile = (task) => `/workspace/${task.outputPath}`;
+/** Why the output cannot be read: the task's sandbox instance is not running. */
+export function unavailableText(task, r) {
+    if (r.kind === "not_running" && r.status === "suspended") {
+        return `[Output unavailable: the sandbox is suspended. Read ${outputFile(task)} resumes it and reads what the task wrote.]`;
+    }
+    return "[Output unavailable: the sandbox that ran this task is gone, and its output with it.]";
+}
+// ---- reading a task ----
+/**
+ * The exec that checks and reads task `t` (relative to `/workspace`): for a running task first
+ * its status line (the poller's, {@link pollScript}: liveness, then the exit file), then
+ * `size <bytes>` and `out <base64>`, at most `cap` bytes of the output from byte `offset` on.
+ * The file is never read whole: `tail -c +<offset+1> | head -c <cap>`. Without `read` only the
+ * status line.
+ */
+export function taskReadScript(t, offset, cap, read = true) {
+    if (!TASK_ID_RE.test(t.id))
+        throw new Error(`invalid background task id: ${t.id}`);
+    const lines = [];
+    if (t.running && t.sid !== null)
+        lines.push(pollScript([{ id: t.id, sid: t.sid }]));
+    if (read) {
+        const f = `${TASKS_DIR}/${t.id}.out`;
+        const from = Math.max(0, Math.floor(offset)) + 1;
+        const n = Math.max(1, Math.floor(cap));
+        lines.push(`s=$({ wc -c < ${f}; } 2>/dev/null | tr -d ' '); echo "size \${s:-0}"`);
+        lines.push(`printf 'out '; { tail -c +${from} ${f} 2>/dev/null | head -c ${n} | base64 | tr -d '\\n'; }; echo`);
+    }
+    return lines.join("\n");
+}
+function parseRead(id, stdout) {
+    const size = /^size ([0-9]+)$/m.exec(stdout);
+    const out = /^out ?([A-Za-z0-9+/=]*)$/m.exec(stdout);
+    return {
+        report: parsePollOutput(stdout).get(id),
+        size: size ? Number(size[1]) : 0,
+        data: Buffer.from(out?.[1] ?? "", "base64"),
+    };
+}
+/**
+ * The bytes of `buf` up to its last whole UTF-8 character: a character cut by the read's cap is
+ * left for the next read.
+ */
+export function wholeUtf8Length(buf) {
+    let i = buf.length - 1;
+    let back = 0;
+    while (i >= 0 && back < 3 && (buf[i] & 0xc0) === 0x80) {
+        i--;
+        back++;
+    }
+    if (i < 0)
+        return buf.length;
+    const b = buf[i];
+    const need = b >= 0xf0 ? 4 : b >= 0xe0 ? 3 : b >= 0xc0 ? 2 : 1;
+    return i + need > buf.length ? i : buf.length;
+}
+/** Checks (and with `read`, reads) the task in its sandbox instance; never creates or resumes one. */
+async function look(env, task, read, signal) {
+    if (task.sid !== null && !SID_RE.test(task.sid)) {
+        throw new Error(`invalid background task session: ${task.sid}`);
+    }
+    const script = taskReadScript({ id: task.id, sid: task.sid, running: task.status === "running" }, read?.offset ?? 0, read?.cap ?? 1, read !== null);
+    const maxBytes = Math.ceil((read?.cap ?? 0) / 3) * 4 + 64 * 1024;
+    return onTaskInstance(env, task, async (p, h, sig) => {
+        const r = await p.exec(h, {
+            command: script,
+            cwd: "/workspace",
+            timeoutMs: READ_EXEC_TIMEOUT_MS,
+            maxOutputBytes: maxBytes,
+            signal: sig,
+        });
+        if (r.exitCode !== 0 || r.truncated) {
+            throw new ToolError(`Background task ${task.id} could not be read (exit ${r.exitCode}${r.truncated ? ", output truncated" : ""}); retry TaskOutput, or Read ${outputFile(task)}.`);
+        }
+        return parseRead(task.id, r.stdout);
+    }, signal);
+}
+/**
+ * How `seen` shows the running `task` ended (an exit file, no process left, its sandbox instance
+ * not running), or null while it runs (or when the row is no longer running).
+ */
+function endOf(task, seen) {
+    if (task.status !== "running")
+        return null;
+    if (seen.kind === "not_running") {
+        return { to: notRunningAs(seen.status, seen.status === "suspended"), lastLines: "" };
+    }
+    if (seen.kind === "other_instance")
+        return { to: RECREATED, lastLines: "" };
+    const r = seen.value.report;
+    const to = r ? polledAs(task, r, new Date()) : null;
+    return to === null ? null : { to, lastLines: r?.lastLines ?? "" };
+}
+/**
+ * Finishes the task as `end` says, marked reported: called only once nothing can fail before the
+ * result reaches the model, so a reported finish is one the model saw. A task a stop claimed is
+ * left to the stop. Returns the task's row afterwards.
+ */
+async function settle(env, task, end) {
+    if (end === null)
+        return task;
+    await env.tasks.finisher.finish(task, end.to, end.lastLines, true, { unclaimed: true });
+    return (await env.store.get(task.id)) ?? task;
+}
+/** {@link look}, with a `SandboxGoneError` from the exec as null (the instance is gone). */
+async function lookOrGone(env, task, read, signal) {
+    try {
+        return await look(env, task, read, signal);
+    }
+    catch (e) {
+        if (isSandboxGoneError(e))
+            return null;
+        throw e;
+    }
+}
+/**
+ * Built-in `TaskOutput` (spec 2026-11-05-background-bash-design §2.2): a task's status and the
+ * output since this conversation's last read of it. Every check is a short exec through
+ * `SandboxService.ifRunning` on the task's own sandbox instance: it never creates or resumes a
+ * sandbox, so a suspended or rebuilt one means the task is lost (its output unavailable). With
+ * `block`, checks every {@link TASK_CHECK_INTERVAL_MS}, each under a lease of its own, until the
+ * task ends or the wait (at most `timeout` and the run's time left) is over; the checks only
+ * detect the end, and the one read that makes the result finishes the task (reported). The output
+ * read is capped at `tools.outputSpillChars` bytes; the pipeline spills the result beyond that.
+ */
+export function taskOutputTool(deps) {
+    return {
+        spec: SPEC,
+        defaultPolicy: "allow",
+        unavailable: unavailableWhenNoSandbox(deps),
+        timeoutMs: (input) => {
+            const { block, timeout } = input;
+            const wait = block === false
+                ? 0
+                : Math.min(timeout ?? TASK_OUTPUT_DEFAULT_TIMEOUT_MS, TASK_OUTPUT_MAX_TIMEOUT_MS);
+            return wait + sandboxBaseTimeoutMs(deps.config.get());
+        },
+        async run(input, ctx) {
+            const { task_id, block = true, timeout } = input;
+            const env = taskEnv(deps);
+            let task = await ownedTask(env, ctx, task_id);
+            if (block && task.status === "running") {
+                const wait = Math.max(0, Math.min(timeout ?? TASK_OUTPUT_DEFAULT_TIMEOUT_MS, TASK_OUTPUT_MAX_TIMEOUT_MS, runTimeLeftMs(ctx.runDeadline)));
+                const until = Date.now() + wait;
+                // no check right before the final read: the loop ends when the wait does
+                while (task.status === "running" && Date.now() < until) {
+                    if (task.sandboxCreatedAt !== null) {
+                        const seen = await lookOrGone(env, task, null, ctx.signal);
+                        if (seen === null || endOf(task, seen) !== null)
+                            break;
+                    }
+                    const left = until - Date.now();
+                    if (left <= 0)
+                        break;
+                    await sleep(Math.min(TASK_CHECK_INTERVAL_MS, left), undefined, { signal: ctx.signal });
+                    task = (await env.store.get(task.id)) ?? task;
+                }
+            }
+            if (task.sandboxCreatedAt === null) {
+                // a reservation still launching, or a launch that failed: nothing ran
+                return result(task, [
+                    statusLine(task),
+                    task.status === "running"
+                        ? "[The task is still starting; no output yet.]"
+                        : "[No output: the command never started.]",
+                ]);
+            }
+            const offset = task.readOffset;
+            const cap = deps.config.get().tools.outputSpillChars;
+            const seen = await lookOrGone(env, task, { offset, cap }, ctx.signal);
+            if (seen === null) {
+                return result(task, [statusLine(task), unavailableText(task, { kind: "other_instance" })]);
+            }
+            const end = endOf(task, seen);
+            if (seen.kind !== "ran") {
+                task = await settle(env, task, end);
+                return result(task, [statusLine(task), unavailableText(task, seen)]);
+            }
+            const { data, size } = seen.value;
+            // an ended task's output is complete: only a read cut by the cap can end inside a character
+            const ended = task.status !== "running" || end !== null;
+            const used = ended && data.length < cap ? data.length : wholeUtf8Length(data);
+            if (used > 0)
+                await env.store.advanceOffset(task.id, offset + used);
+            task = await settle(env, task, end);
+            const parts = [];
+            const more = size - (offset + used);
+            if (more > 0) {
+                parts.push(`[${more} more bytes of output after this; call TaskOutput again to read them, or Read ${outputFile(task)}.]`);
+            }
+            parts.push(used === 0 ? "[No new output.]" : data.subarray(0, used).toString("utf8"));
+            return result(task, [statusLine(task), ...parts]);
+        },
+    };
+}
+function result(task, lines) {
+    const d = clip(task.description, 120);
+    return {
+        content: [{ type: "text", text: lines.join("\n") }],
+        isError: false,
+        display: display(`读取后台任务输出：${d}`, `Read background task output: ${d}`),
+    };
+}

package/dist/tools/builtins/sandbox/task-stop.d.ts

@@ -0,0 +1,10 @@
+import type { BuiltinTool } from "../../registry.js";
+import { type SandboxToolDeps } from "./common.js";
+/**
+ * Built-in `TaskStop` (spec 2026-11-05-background-bash-design §2.3): stops one of this
+ * conversation's background tasks through `BackgroundTaskStopper` (SIGTERM to its session, SIGKILL
+ * after 5 s, never creating or resuming a sandbox). A task that had already finished is not an
+ * error; a reservation still launching, or a task another stop already claimed, is reported as
+ * stopping. A stop that failed leaves the task running and is an error the model can retry.
+ */
+export declare function taskStopTool(deps: SandboxToolDeps): BuiltinTool;

package/dist/tools/builtins/sandbox/task-stop.js

@@ -0,0 +1,112 @@
+import { ToolError } from "@capybara-hq/plugin-sdk";
+import { decodeTail, tailCommand } from "../../../background/session.js";
+import { clip, display, mapSandboxError, sandboxBaseTimeoutMs, unavailableWhenNoSandbox, } from "./common.js";
+import { onTaskInstance, ownedTask, statusLine, taskEnv } from "./task-output.js";
+/** The time limit of reading a stopped task's last lines. */
+const TAIL_EXEC_TIMEOUT_MS = 10_000;
+const SPEC = {
+    name: "TaskStop",
+    // Display only (the tool row; not in the fingerprint, never sent to the model).
+    keyArgs: ["task_id"],
+    description: "Stop a background task started with Bash and run_in_background: every process of the task " +
+        "gets SIGTERM, then SIGKILL after 5 seconds. The result has the final status and the last " +
+        "lines of output. Stopping a task that has already finished is not an error; the result says " +
+        "so. A conversation can stop only its own tasks.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            task_id: {
+                type: "string",
+                minLength: 1,
+                description: "The id of the background task (bt_...) that Bash returned.",
+            },
+        },
+        required: ["task_id"],
+        additionalProperties: false,
+    },
+};
+/** The task's last 20 lines, read from its own sandbox instance; null when that is not running. */
+async function lastLinesOf(env, task, signal) {
+    if (task.sandboxCreatedAt === null)
+        return null;
+    try {
+        const r = await onTaskInstance(env, task, async (p, h, sig) => {
+            const res = await p.exec(h, {
+                command: tailCommand(task.id),
+                cwd: "/workspace",
+                timeoutMs: TAIL_EXEC_TIMEOUT_MS,
+                maxOutputBytes: 64 * 1024,
+                signal: sig,
+            });
+            return res.exitCode === 0 ? decodeTail(res.stdout) : null;
+        }, signal);
+        return r.kind === "ran" ? r.value : null;
+    }
+    catch {
+        // the task is stopped either way; only its last lines are missing
+        return null;
+    }
+}
+/** The result text: what happened, the status line and the last lines. */
+async function ended(env, task, what, signal) {
+    const lines = await lastLinesOf(env, task, signal);
+    const tail = task.sandboxCreatedAt === null
+        ? "[No output: the command never started.]"
+        : lines === null
+            ? "[Last lines unavailable: the sandbox that ran this task is not running.]"
+            : lines === ""
+                ? "[No output.]"
+                : `Last lines:\n${lines.replace(/\n$/, "")}`;
+    return text(task, `Background task ${task.id} ("${task.description}") ${what}.\n${statusLine(task)}\n${tail}`);
+}
+function text(task, body) {
+    const d = clip(task.description, 120);
+    return {
+        content: [{ type: "text", text: body }],
+        isError: false,
+        display: display(`停止后台任务：${d}`, `Stop background task: ${d}`),
+    };
+}
+/**
+ * Built-in `TaskStop` (spec 2026-11-05-background-bash-design §2.3): stops one of this
+ * conversation's background tasks through `BackgroundTaskStopper` (SIGTERM to its session, SIGKILL
+ * after 5 s, never creating or resuming a sandbox). A task that had already finished is not an
+ * error; a reservation still launching, or a task another stop already claimed, is reported as
+ * stopping. A stop that failed leaves the task running and is an error the model can retry.
+ */
+export function taskStopTool(deps) {
+    return {
+        spec: SPEC,
+        defaultPolicy: "allow",
+        unavailable: unavailableWhenNoSandbox(deps),
+        timeoutMs: () => sandboxBaseTimeoutMs(deps.config.get()),
+        async run(input, ctx) {
+            const { task_id } = input;
+            const env = taskEnv(deps);
+            const task = await ownedTask(env, ctx, task_id);
+            if (task.status !== "running") {
+                return ended(env, task, "had already finished", ctx.signal);
+            }
+            let after;
+            try {
+                after = await env.tasks.stopper.stop(task, "tool", ctx.signal);
+            }
+            catch (e) {
+                const mapped = mapSandboxError(e);
+                if (mapped instanceof ToolError)
+                    throw mapped;
+                const why = e instanceof Error ? e.message : String(e);
+                throw new ToolError(`Background task ${task.id} could not be stopped (${clip(why, 300)}); it keeps running. Retry TaskStop, or check the sandbox with Bash.`);
+            }
+            if (after.status === "running") {
+                return text(after, `Background task ${after.id} ("${after.description}") is stopping: it is still starting, or another stop is in progress. Call TaskOutput to see when it has ended.`);
+            }
+            const what = after.status === "stopped"
+                ? "was stopped"
+                : after.status === "lost"
+                    ? "is lost"
+                    : "had already finished";
+            return ended(env, after, what, ctx.signal);
+        },
+    };
+}

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

@@ -1,4 +1,4 @@
 import type { BuiltinTool } from "../../registry.js";
 import { type SandboxToolDeps } from "./common.js";
-/** 内置工具 `sandbox_write`：整文件写入。 */
+/** 内置工具 `Write`：整文件写入。 */
 export declare function sandboxWriteTool(deps: SandboxToolDeps): BuiltinTool;