@capybara-hq/kernel 0.1.0-rc.1 → 0.1.0-rc.11

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

@@ -0,0 +1,334 @@
+import { setTimeout as sleep } from "node:timers/promises";
+import { isSandboxGoneError, rootsOf, ToolError, } from "@capybara-hq/plugin-sdk";
+import { TASK_ID_RE, TASKS_DIR, taskOutputFile } from "../../../background/launch.js";
+import { formatElapsed, lostReasonText } from "../../../background/render.js";
+import { actingAs, SID_RE, taskActor } 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, sandboxConversationOf, sandboxUsable, 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, or when the
+ * conversation's environment cannot run (no cloud provider, and not a registered `@device` one:
+ * ruling R8).
+ */
+export async function taskEnv(deps, ctx) {
+    if (!(await sandboxUsable(deps, ctx.orgId, sandboxConversationOf(ctx))))
+        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),
+        environments: deps.environments,
+        log: deps.log,
+    };
+}
+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;
+}
+/**
+ * The per-call access re-check of every sandbox tool (`inSandbox`): the conversation's environment
+ * may still be used by its owner. The task tools read a task's own instance without `inSandbox`,
+ * so they check here first; errors become the tools' errors.
+ */
+export async function recheckEnvironment(env, ctx) {
+    try {
+        await env.environments.forTool(ctx.orgId, sandboxConversationOf(ctx));
+    }
+    catch (e) {
+        throw mapSandboxError(e, env.log);
+    }
+}
+/**
+ * `ifRunning` on the task's own environment instance (its execs act for the task's trigger in its
+ * conversation); sandbox errors become the tools' errors. A task from before environments has no
+ * instance (`not_running`).
+ */
+export async function onTaskInstance(env, task, fn, signal) {
+    if (task.environmentId === null)
+        return { kind: "not_running", status: "gone" };
+    try {
+        return await env.ifRunning(task.environmentId, { createdAt: task.sandboxCreatedAt }, (p, h, sig) => fn(actingAs(p, taskActor(task)), h, sig), signal);
+    }
+    catch (e) {
+        throw mapSandboxError(e, env.log);
+    }
+}
+/**
+ * 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) => taskOutputFile(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 the workspace root): 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: rootsOf(h).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 = await taskEnv(deps, ctx);
+            let task = await ownedTask(env, ctx, task_id);
+            await recheckEnvironment(env, ctx);
+            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,113 @@
+import { rootsOf, 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, recheckEnvironment, 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: rootsOf(h).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 = await taskEnv(deps, ctx);
+            const task = await ownedTask(env, ctx, task_id);
+            await recheckEnvironment(env, ctx);
+            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, env.log);
+                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;

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

@@ -1,26 +1,29 @@
-import { isSandboxGoneError, ToolError } from "@capybara-hq/plugin-sdk";
+import { ToolError } from "@capybara-hq/plugin-sdk";
 import { lineDiff, TOOL_VIEW_DIFF_MAX_BYTES, viewPath } from "../../view.js";
-import { checkWritable, clip, display, inSandbox, looksBinary, sandboxBaseTimeoutMs, unavailableWhenNoSandbox, withNotices, withPathLease, } from "./common.js";
+import { checkPathShape, checkWritable, clip, display, inSandbox, looksBinary, sandboxBaseTimeoutMs, unavailableWhenNoSandbox, withNotices, withPathLease, } from "./common.js";
+import { assertReadAndUnchanged, fileStateOf, normalizeSandboxPath, recordedFile, } from "./file-state.js";
+import { READ_MAX_BYTES } from "./read.js";
 const SPEC = {
-    name: "sandbox_write",
+    name: "Write",
     // Display only (the tool row; not in the fingerprint, never sent to the model).
-    keyArgs: ["path"],
+    keyArgs: ["file_path"],
     description: "Write a text file in this conversation's sandbox, creating parent directories as needed. " +
         "Each call replaces the whole file (it is created if missing). Use it to create scripts, " +
-        "source files and data files. The path is absolute, under /workspace or /tmp (/skills is " +
-        "read-only). To change part of an existing file, use sandbox_edit instead; to give a file to " +
-        "the user, use sandbox_deliver.",
+        "source files and data files. The path is absolute, under the workspace directory or the " +
+        "temporary files directory (the skills directory is read-only). Read an existing file first; overwriting a file you have not read, or one changed " +
+        "since you read it, fails. To change part of an existing file, use Edit instead; to give a file to " +
+        "the user, use Deliver.",
     inputSchema: {
         type: "object",
         properties: {
-            path: {
+            file_path: {
                 type: "string",
                 minLength: 1,
-                description: 'Absolute path of the file, e.g. "/workspace/report.md".',
+                description: "Absolute path of the file, e.g. report.md in the workspace directory.",
             },
             content: { type: "string", description: "The complete new content of the file." },
         },
-        required: ["path", "content"],
+        required: ["file_path", "content"],
         additionalProperties: false,
     },
 };
@@ -30,58 +33,62 @@ const SPEC = {
  * result carries no view.
  */
 const PREVIOUS_MAX_BYTES = TOOL_VIEW_DIFF_MAX_BYTES;
+const vanished = (path) => `${clip(path, 200)} disappeared while it was being written; retry the call.`;
 const isDirectory = (path) => `${clip(path, 200)} is a directory; pass the path of a file inside it.`;
-/** 内置工具 `sandbox_write`：整文件写入。 */
+/** 内置工具 `Write`：整文件写入。 */
 export function sandboxWriteTool(deps) {
     return {
         spec: SPEC,
         defaultPolicy: "allow",
         unavailable: unavailableWhenNoSandbox(deps),
-        timeoutMs: () => sandboxBaseTimeoutMs(deps.config()),
+        timeoutMs: () => sandboxBaseTimeoutMs(deps.config.get()),
         async run(input, ctx) {
-            const path = checkWritable(input.path);
             const data = new TextEncoder().encode(input.content);
-            const { value, notices } = await inSandbox(deps, ctx, ({ h, p, signal }) => 
-            // stat, read the previous content, write: one holder at a time per file
-            withPathLease(deps, ctx, path, signal, async (signal) => {
-                const st = await p.stat(h, path, signal);
-                if (st?.isDir)
-                    throw new ToolError(isDirectory(path));
-                // the previous content, for the diff on the row (display only: a failure here never
-                // fails the write, the result just carries no view)
-                let previous = "";
-                if (st !== null) {
-                    try {
-                        const got = st.size <= PREVIOUS_MAX_BYTES
-                            ? await p.readFile(h, path, { maxBytes: PREVIOUS_MAX_BYTES, signal })
-                            : null;
+            checkPathShape(input.file_path, "file_path");
+            let path = "";
+            const { value, notices } = await inSandbox(deps, ctx, ({ environmentId, h, roots, p, signal }) => {
+                path = checkWritable(input.file_path, roots);
+                // stat, read the previous content, write: one holder at a time per file
+                return withPathLease(deps, { environmentId }, path, signal, async (signal) => {
+                    const st = await p.stat(h, path, signal);
+                    if (st?.isDir)
+                        throw new ToolError(isDirectory(path));
+                    // the previous content: for the read-before-write check, and the diff on the row (display
+                    // only: a file too large or binary to diff just leaves the view without hunks)
+                    let previous = "";
+                    if (st !== null) {
+                        const got = await p.readFile(h, path, { maxBytes: READ_MAX_BYTES, signal });
+                        if (got === null)
+                            throw new ToolError(vanished(path));
+                        await assertReadAndUnchanged(deps, ctx.conversationId, path, fileStateOf(got.data, st.size));
                         previous =
-                            got === null || got.truncated || looksBinary(got.data) || got.data.includes(0)
+                            st.size > PREVIOUS_MAX_BYTES ||
+                                got.truncated ||
+                                looksBinary(got.data) ||
+                                got.data.includes(0)
                                 ? null
                                 : new TextDecoder().decode(got.data);
                     }
-                    catch (e) {
-                        if (signal.aborted || isSandboxGoneError(e))
-                            throw e;
-                        previous = null;
-                    }
-                }
-                await p.writeFile(h, path, data, signal);
-                return { existed: st !== null, previous };
-            }));
+                    await p.writeFile(h, path, data, signal);
+                    return { existed: st !== null, previous };
+                });
+            });
             const { existed, previous } = value;
             const text = `${existed ? "Overwrote" : "Created"} ${path} (${data.byteLength} bytes).`;
             return {
                 content: [{ type: "text", text: withNotices(notices, text) }],
                 display: display(`写入 ${clip(path, 180)}`, `Wrote ${clip(path, 180)}`),
-                ...(previous !== null && {
-                    view: {
-                        kind: "edit",
-                        path: viewPath(path),
-                        created: !existed,
-                        ...lineDiff(previous, input.content),
-                    },
-                }),
+                // the view always carries the file state: the next Write / Edit of the path needs it
+                view: {
+                    kind: "edit",
+                    path: viewPath(path),
+                    created: !existed,
+                    ...(previous !== null
+                        ? lineDiff(previous, input.content)
+                        : { added: 0, removed: 0, truncated: true, hunks: [] }),
+                    // over the bytes the next Write / Edit reads back (Read's limit), as Read records it
+                    file: recordedFile(normalizeSandboxPath(path), data.subarray(0, READ_MAX_BYTES), data.byteLength),
+                },
             };
         },
     };

package/dist/tools/builtins/send-message.d.ts

@@ -0,0 +1,56 @@
+import { z } from "zod";
+import type { BuiltinTool } from "../registry.js";
+export { SEND_MESSAGE } from "../builtin-names.js";
+/**
+ * The `SendMessage` builtin tool (agent map spec §4.2, §5.1, §5.2): moves text between the agents
+ * of one tree. An agent sends to one of its own sub-agents by agentId (a running one reads it at its
+ * next step, an idle one starts again with its earlier context), and a sub-agent to `"parent"`.
+ * The result says the message was delivered, never the target's reply. The tool pipeline handles
+ * the call itself (`SubagentMessages`), so {@link sendMessageTool}'s `run` is only a guard.
+ */
+/** The input of a `SendMessage` call. */
+export declare const SendMessageInput: z.ZodObject<{
+    to: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strict>;
+export type SendMessageInputT = z.infer<typeof SendMessageInput>;
+/** The target a sub-agent uses for the agent that dispatched it. */
+export declare const PARENT_TARGET = "parent";
+/** One valid target of a caller: a sub-agent of its own, by agentId and task label. */
+export interface SendTarget {
+    id: string;
+    description: string;
+}
+/** Refusals: `isError` results written without delivering anything (model-visible). */
+export declare const SEND_MESSAGE_REFUSALS: {
+    /**
+     * `to` is none of the caller's own sub-agents (nor `"parent"` in a sub-agent): lists the valid
+     * targets, at most the newest {@link SEND_TARGETS_LISTED} sub-agents.
+     */
+    readonly unknownTarget: (to: string, targets: readonly SendTarget[], opts: {
+        hasParent: boolean;
+        more: number;
+    }) => string;
+    /** The sub-agent's type or org agent is no longer available to the caller (its gates). */
+    readonly notAvailable: (id: string, type: string) => string;
+    /** The limits of a send that would start an idle sub-agent again (agent map spec §6). */
+    readonly tooManyConcurrent: (n: number) => string;
+    readonly tooManyDispatches: (n: number) => string;
+    readonly budget: (n: number) => string;
+    readonly depthLimit: (maxDepth: number) => string;
+    readonly notAvailableHere: "Messages between agents are not available in this conversation.";
+};
+/** How many of the caller's sub-agents an unknown-target refusal lists (the newest). */
+export declare const SEND_TARGETS_LISTED = 20;
+/** The result of a message to a sub-agent whose run was active (agent map spec §5.1). */
+export declare const sentToRunningText: (t: SendTarget) => string;
+/** The result of a message that started an idle sub-agent again (agent map spec §5.1, §6). */
+export declare const sentToIdleText: (t: SendTarget) => string;
+/** The result of a sub-agent's note to its parent (agent map spec §5.2). */
+export declare const SENT_TO_PARENT_TEXT = "Message delivered to the agent that dispatched you. Keep working; its reply, if any, arrives as a message in this conversation.";
+/**
+ * The builtin. `defaultPolicy: "allow"` (agent map spec §4.2): it only moves text inside one tree
+ * the person already started. The tool pipeline handles `SendMessage` calls itself; `run` answers
+ * only when a call reaches it anyway.
+ */
+export declare const sendMessageTool: BuiltinTool;