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

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

@@ -0,0 +1,329 @@
+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 { 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, 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),
+        environments: deps.environments,
+    };
+}
+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);
+    }
+}
+/**
+ * `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);
+    }
+}
+/**
+ * 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);
+            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 { 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: "/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);
+            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);
+                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.js

@@ -45,9 +45,9 @@ export function sandboxWriteTool(deps) {
         async run(input, ctx) {
             const path = checkWritable(input.file_path);
             const data = new TextEncoder().encode(input.content);
-            const { value, notices } = await inSandbox(deps, ctx, ({ h, p, signal }) => 
+            const { value, notices } = await inSandbox(deps, ctx, ({ environmentId, h, p, signal }) => 
             // stat, read the previous content, write: one holder at a time per file
-            withPathLease(deps, ctx, path, signal, async (signal) => {
+            withPathLease(deps, { environmentId }, path, signal, async (signal) => {
                 const st = await p.stat(h, path, signal);
                 if (st?.isDir)
                     throw new ToolError(isDirectory(path));

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;

package/dist/tools/builtins/send-message.js

@@ -0,0 +1,100 @@
+import { z } from "zod";
+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 const SendMessageInput = z
+    .object({
+    to: z.string().min(1).max(64),
+    message: z.string().min(1).max(100_000),
+})
+    .strict();
+/** The target a sub-agent uses for the agent that dispatched it. */
+export const PARENT_TARGET = "parent";
+const SPEC = {
+    name: "SendMessage",
+    description: "Send a message to another agent of this conversation. To reach one of your sub-agents, pass " +
+        "its agentId (from the Agent result) as to: a sub-agent that is working reads the message at " +
+        "its next step, and one that already finished starts working again with its earlier context. " +
+        'A sub-agent can pass "parent" as to, to send a note to the agent that dispatched it. This ' +
+        "tool only delivers the message and returns at once; it never waits for a reply. Replies, " +
+        "reports and finishes arrive later in this conversation as notifications. A sub-agent hands " +
+        "back its final report with SubagentHandback, not with this tool.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            to: {
+                type: "string",
+                minLength: 1,
+                maxLength: 64,
+                description: 'The agentId of one of your sub-agents, or "parent" in a sub-agent.',
+            },
+            message: {
+                type: "string",
+                minLength: 1,
+                maxLength: 100000,
+                description: "The message. The receiving agent sees only this text, so include everything it needs.",
+            },
+        },
+        required: ["to", "message"],
+        additionalProperties: false,
+    },
+    // display only (UI refresh B): who the message goes to; never sent to the model
+    keyArgs: ["to"],
+};
+/** `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, ",");
+/** How a target is listed in a refusal. */
+const targetLine = (t) => `${t.id} (${JSON.stringify(t.description)})`;
+/** Refusals: `isError` results written without delivering anything (model-visible). */
+export 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.
+     */
+    unknownTarget: (to, targets, opts) => {
+        const lines = [
+            ...targets.map(targetLine),
+            ...(opts.hasParent ? [`"${PARENT_TARGET}" (the agent that dispatched you)`] : []),
+        ];
+        if (lines.length === 0) {
+            return `There is no agent "${to}" to send to: you have no sub-agents yet. Use Agent to dispatch one.`;
+        }
+        const more = opts.more > 0 ? `, and ${opts.more} older sub-agents` : "";
+        return `There is no agent "${to}" you can send to. Pass one of these as to: ${lines.join(", ")}${more}.`;
+    },
+    /** The sub-agent's type or org agent is no longer available to the caller (its gates). */
+    notAvailable: (id, type) => `Sub-agent ${id} can no longer receive messages: its agent type "${type}" is not available to you any more. Use Agent to dispatch another sub-agent instead.`,
+    /** The limits of a send that would start an idle sub-agent again (agent map spec §6). */
+    tooManyConcurrent: (n) => `At most ${n} of your sub-agents can run at once in this conversation, and this one has finished; send the message again after one of the running sub-agents finishes.`,
+    tooManyDispatches: (n) => `${n} sub-agents have been dispatched or restarted since the user's latest message, counted across all levels of sub-agents; that is the limit, so this finished sub-agent cannot start again. Do the remaining work yourself.`,
+    budget: (n) => `Sub-agents have used their token budget since the user's latest message (${count(n)} tokens, counted across all levels of sub-agents), so this finished sub-agent cannot start again. Do the remaining work yourself.`,
+    depthLimit: (maxDepth) => `Sub-agents can be nested at most ${maxDepth} levels deep and you are at the deepest level, so this finished sub-agent cannot start again. Do the remaining work yourself.`,
+    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 const SEND_TARGETS_LISTED = 20;
+/** The result of a message to a sub-agent whose run was active (agent map spec §5.1). */
+export const sentToRunningText = (t) => `Message delivered to sub-agent ${targetLine(t)}, which is working; it reads the message at its next step. Its reply or report arrives later as a notification; keep working or end your turn.`;
+/** The result of a message that started an idle sub-agent again (agent map spec §5.1, §6). */
+export const sentToIdleText = (t) => `Message delivered to sub-agent ${targetLine(t)}, which had finished; it is working again with its earlier context. Its reply or report arrives later as a notification; keep working or end your turn.`;
+/** The result of a sub-agent's note to its parent (agent map spec §5.2). */
+export 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 const sendMessageTool = {
+    spec: SPEC,
+    defaultPolicy: "allow",
+    run: async () => ({
+        content: [{ type: "text", text: SEND_MESSAGE_REFUSALS.notAvailableHere }],
+        isError: true,
+    }),
+};