@celestea/tools 2.7.1

package/dist/tools/process-control.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `process_control` — poll / stdin / kill a background process
+ * (`crates/tools/src/process.rs`).
+ *
+ * Handles live in the session-scoped registry and survive across turns; a
+ * process that exits stays pollable from a bounded tombstone (most recent 32, or
+ * 10 minutes), then the handle is unknown. Failures are results
+ * (`{ok:false, error}`), not rejections: "unknown handle" is a normal answer to
+ * a stale handle, and callers branch on `ok`.
+ */
+import type { ProcessRegistry } from "../process/registry.js";
+import type { Tool, ToolSpec } from "@celestea/core";
+export declare function processControlSpec(): ToolSpec;
+export declare function processControlTool(processes: ProcessRegistry): Tool;

package/dist/tools/process-control.js

@@ -0,0 +1,49 @@
+/**
+ * `process_control` — poll / stdin / kill a background process
+ * (`crates/tools/src/process.rs`).
+ *
+ * Handles live in the session-scoped registry and survive across turns; a
+ * process that exits stays pollable from a bounded tombstone (most recent 32, or
+ * 10 minutes), then the handle is unknown. Failures are results
+ * (`{ok:false, error}`), not rejections: "unknown handle" is a normal answer to
+ * a stale handle, and callers branch on `ok`.
+ */
+import { optionalStringArg, stringArg } from "../args.js";
+import { descParam } from "../desc.js";
+import { fnTool } from "../fn-tool.js";
+export function processControlSpec() {
+    return {
+        name: "process_control",
+        description: "Control a background process started by run_shell(background=true). Handles live in the session-scoped process registry and survive across turns; a process that exits stays pollable from a bounded tombstone (most recent 32, or 10 minutes), so poll AFTER exit returns {running:false, exit_code, signal, stdout_tail(<=4KB), stderr_tail, cpu_exceeded?} instead of an unknown handle. action=poll reads the current or terminal state; action=kill sends SIGTERM, waits a grace period, then SIGKILL and returns {killed:true}; action=stdin writes one line (content + newline) to the process stdin.",
+        parameters: {
+            type: "object",
+            properties: {
+                handle: { type: "string", description: "Process handle returned by run_shell(background=true)." },
+                action: { type: "string", enum: ["poll", "kill", "stdin"], description: "poll | kill | stdin (see tool description)." },
+                content: { type: "string", description: "Line to write to the process stdin (action=stdin only)." },
+                desc: descParam(),
+            },
+            required: ["handle", "action"],
+            additionalProperties: false,
+        },
+    };
+}
+export function processControlTool(processes) {
+    return fnTool(processControlSpec(), async (args) => {
+        const handle = stringArg(args, "handle").trim();
+        if (handle === "")
+            return { ok: false, error: "handle required" };
+        const action = optionalStringArg(args, "action") ?? "";
+        if (action === "poll")
+            return processes.poll(handle);
+        if (action === "kill")
+            return processes.kill(handle);
+        if (action === "stdin") {
+            const content = optionalStringArg(args, "content");
+            if (content === undefined)
+                return { ok: false, error: "content required for action=stdin" };
+            return processes.stdinLine(handle, content);
+        }
+        return { ok: false, error: `unknown action: ${action}` };
+    });
+}

package/dist/tools/read-file.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `read_file` — read a UTF-8 text file and return its contents as a string
+ * (legacy `builtin.rs::read_file_spec`). A default (no `offset`/`limit`) read
+ * keeps the canonical value shape: the value stays the text, the truncation
+ * travels in the authored `render`. Passing `offset`/`limit` (W846) returns a
+ * line window whose pagination metadata lives on `value` — `render` is not
+ * projected to the model, so metadata there would be invisible.
+ */
+import type { Tool, ToolSpec } from "@celestea/core";
+export declare function readFileSpec(): ToolSpec;
+export declare function readFileTool(): Tool;

package/dist/tools/read-file.js

@@ -0,0 +1,81 @@
+/**
+ * `read_file` — read a UTF-8 text file and return its contents as a string
+ * (legacy `builtin.rs::read_file_spec`). A default (no `offset`/`limit`) read
+ * keeps the canonical value shape: the value stays the text, the truncation
+ * travels in the authored `render`. Passing `offset`/`limit` (W846) returns a
+ * line window whose pagination metadata lives on `value` — `render` is not
+ * projected to the model, so metadata there would be invisible.
+ */
+import { optionalIntArg, stringArg } from "../args.js";
+import { descParam } from "../desc.js";
+import { DEFAULT_READ_LIMIT, MAX_READ_BYTES, readTextFile, readTextLines, truncationNote } from "../fs/file-io.js";
+export function readFileSpec() {
+    return {
+        name: "read_file",
+        description: "Read a UTF-8 text file and return its contents as a string. A whole read is capped at 256 KiB; pass offset (0-based line) and/or limit (line count) to page through a larger file — a paged result is an object {text, offset, limit, lineCount, totalLines, hasMore, nextOffset, truncated, totalBytes}.",
+        parameters: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "Filesystem path of the file to read." },
+                offset: {
+                    type: "integer",
+                    minimum: 0,
+                    description: "Optional 0-based line index to start from (pagination). Omit to read from the top.",
+                },
+                limit: {
+                    type: "integer",
+                    minimum: 1,
+                    description: "Optional maximum number of lines to return (pagination). Omit to use the default window.",
+                },
+                desc: descParam(),
+            },
+            required: ["path"],
+            additionalProperties: false,
+        },
+    };
+}
+async function read(args) {
+    const path = stringArg(args, "path");
+    const offset = optionalIntArg(args, "offset");
+    const limit = optionalIntArg(args, "limit");
+    // No pagination params: the legacy byte read, value byte-for-byte unchanged.
+    if (offset === undefined && limit === undefined) {
+        const result = await readTextFile(path);
+        if (!result.truncated)
+            return { value: result.text, render: null };
+        const note = truncationNote(`'${path}'`, MAX_READ_BYTES, result.totalBytes, "bytes", 'read the rest with offset/limit, or run_shell on the same path (head -c / tail -c / sed -n)');
+        // W855 (B6): the note must reach the MODEL too — `render` is display-only
+        // (never projected), so it rides as a surface descriptor on the log row.
+        return { value: result.text, render: note, surface: { kind: "truncation", note } };
+    }
+    // W846 pagination: line window; metadata on `value` (render is not projected).
+    const window = await readTextLines(path, offset ?? 0, limit ?? DEFAULT_READ_LIMIT);
+    const lastLine = window.offset + window.lineCount - 1;
+    const more = window.hasMore
+        ? `; ${window.totalLines - window.offset - window.lineCount} more at offset=${window.nextOffset}`
+        : "";
+    return {
+        value: {
+            text: window.text,
+            offset: window.offset,
+            limit: window.limit,
+            lineCount: window.lineCount,
+            totalLines: window.totalLines,
+            hasMore: window.hasMore,
+            nextOffset: window.nextOffset,
+            truncated: window.truncated,
+            totalBytes: window.totalBytes,
+        },
+        render: window.hasMore || window.truncated
+            ? `read_file: lines ${window.offset}-${lastLine} of ${window.totalLines}${more}${window.truncated ? " (window clipped at 256 KiB)" : ""}`
+            : null,
+    };
+}
+export function readFileTool() {
+    const spec = readFileSpec();
+    return {
+        spec: () => spec,
+        execute: async (args) => (await read(args)).value,
+        executeWith: async (input) => read(input.args),
+    };
+}

package/dist/tools/read-image.d.ts

@@ -0,0 +1,33 @@
+/**
+ * read_image (W804, multimodal P0 section 6) — read an image from the session's
+ * attachments or from the sandbox roots and hand it to a vision-capable model.
+ *
+ * Two channels (section 6.3):
+ *   1. the tool VALUE (persisted, logged): metadata plus value.attachments — a
+ *      list of [ImageRef]s. It NEVER contains bytes.
+ *   2. the model-visible image block: deriveMessagesFrom reads value.attachments
+ *      and projects an ImageContent onto the same tool message; the wire layer
+ *      then delivers it in a following user message (shape B, section 3.3).
+ *
+ * The capability gate (section 6.6) is OPTIMISTIC: the host passes
+ * imageInputAllowed = false only when the target model was EXPLICITLY configured
+ * with input_modalities excluding "image". An optimistic default that the
+ * upstream rejects is handled by the section 7.6 downgrade, not here.
+ */
+import type { Tool, ToolSpec } from "@celestea/core";
+import { type AttachmentStore } from "../attachments/store.js";
+/** The frozen contract description; mirrored by contracts/tools.json. */
+export declare const READ_IMAGE_DESCRIPTION = "Read an image (PNG/JPEG/WebP/GIF) and attach it to the conversation so a vision-capable model can see it. Returns metadata; the image content block is delivered with the tool result. Fails on models without image input.";
+export interface ReadImageToolOptions {
+    /** The session's content-addressed store; the tool cannot exist without it. */
+    attachments: AttachmentStore;
+    /**
+     * false = the target model's input_modalities was EXPLICITLY configured without
+     * "image"; the tool then refuses before touching any file (section 6.6).
+     */
+    imageInputAllowed?: boolean;
+    /** The model id, for the refusal text (the user must be able to switch). */
+    model?: string;
+}
+export declare function readImageSpec(): ToolSpec;
+export declare function readImageTool(options: ReadImageToolOptions): Tool;

package/dist/tools/read-image.js

@@ -0,0 +1,144 @@
+/**
+ * read_image (W804, multimodal P0 section 6) — read an image from the session's
+ * attachments or from the sandbox roots and hand it to a vision-capable model.
+ *
+ * Two channels (section 6.3):
+ *   1. the tool VALUE (persisted, logged): metadata plus value.attachments — a
+ *      list of [ImageRef]s. It NEVER contains bytes.
+ *   2. the model-visible image block: deriveMessagesFrom reads value.attachments
+ *      and projects an ImageContent onto the same tool message; the wire layer
+ *      then delivers it in a following user message (shape B, section 3.3).
+ *
+ * The capability gate (section 6.6) is OPTIMISTIC: the host passes
+ * imageInputAllowed = false only when the target model was EXPLICITLY configured
+ * with input_modalities excluding "image". An optimistic default that the
+ * upstream rejects is handled by the section 7.6 downgrade, not here.
+ */
+import { open } from "node:fs/promises";
+import { basename } from "node:path";
+import { optionalStringArg } from "../args.js";
+import { descParam } from "../desc.js";
+import { contractFailure, isToolFailure } from "../errors.js";
+import { ATTACHMENT_MAX_BYTES, AttachmentError } from "../attachments/store.js";
+/** The frozen contract description; mirrored by contracts/tools.json. */
+export const READ_IMAGE_DESCRIPTION = "Read an image (PNG/JPEG/WebP/GIF) and attach it to the conversation so a vision-capable model can see it. Returns metadata; the image content block is delivered with the tool result. Fails on models without image input.";
+export function readImageSpec() {
+    return {
+        name: "read_image",
+        description: READ_IMAGE_DESCRIPTION,
+        parameters: {
+            type: "object",
+            properties: {
+                path: {
+                    type: "string",
+                    description: "Filesystem path of the image to read (PNG/JPEG/WebP/GIF; format detected by content, not extension).",
+                },
+                attachment_id: {
+                    type: "string",
+                    description: "Content-addressed id of an already-uploaded attachment (from a user message). Use instead of path.",
+                },
+                desc: descParam(),
+            },
+            required: [],
+            additionalProperties: false,
+        },
+    };
+}
+async function run(args, options) {
+    if (options.imageInputAllowed === false) {
+        const model = options.model !== undefined && options.model !== "" ? options.model : "unknown";
+        throw contractFailure("read_image", "unsupported_modality", `当前模型 "${model}" 的 input_modalities 未包含 image（按配置显式排除），read_image 未执行。\n请改用文本工具，或在该模型的 provider 设置里打开 input_modalities（加入 "image"）。`);
+    }
+    const path = optionalStringArg(args, "path");
+    const attachmentId = optionalStringArg(args, "attachment_id");
+    if ((path === undefined) === (attachmentId === undefined)) {
+        throw contractFailure("read_image", "invalid_arg", "exactly one of 'path' or 'attachment_id' is required");
+    }
+    let bytes;
+    let name;
+    let sourcePath = null;
+    if (path !== undefined) {
+        bytes = await readBoundedImage(path);
+        name = basename(path);
+        sourcePath = path;
+    }
+    else {
+        const found = await options.attachments.readById(attachmentId);
+        if (found === null) {
+            throw contractFailure("read_image", "not_found", `attachment '${attachmentId}' was not found in this session`);
+        }
+        bytes = found.bytes;
+        name = found.ref.name;
+    }
+    let ref;
+    try {
+        ref = await options.attachments.put({ bytes, ...(name === undefined || name === "" ? {} : { name }) });
+    }
+    catch (e) {
+        if (e instanceof AttachmentError)
+            throw contractFailure("read_image", e.code, e.message);
+        throw e;
+    }
+    const value = {
+        ok: true,
+        ...(sourcePath === null ? {} : { path: sourcePath }),
+        media_type: ref.media_type,
+        bytes: bytes.length,
+        width: ref.width,
+        height: ref.height,
+        sha256: ref.attachment_id,
+        attachment_id: ref.attachment_id,
+        attachments: [ref],
+    };
+    const render = `read image ${ref.media_type} ${ref.width}x${ref.height} (${bytes.length} bytes)`;
+    return { value, render };
+}
+/**
+ * B2 / W812 P1-3 (R3): read the image with a HARD byte ceiling. The attachment
+ * store already rejects >4 MiB, but only AFTER the whole file was buffered, so a
+ * huge path would spike RSS (or OOM) before that check ran. Open + stat + read
+ * at most the cap, so the oversize case never allocates the file at all.
+ */
+async function readBoundedImage(path) {
+    let handle;
+    try {
+        handle = await open(path, "r");
+    }
+    catch (e) {
+        throw contractFailure("read_image", "io", `cannot read '${path}': ${e instanceof Error ? e.message : String(e)}`);
+    }
+    try {
+        const info = await handle.stat();
+        if (info.isDirectory())
+            throw contractFailure("read_image", "io", `'${path}' is a directory, not a file`);
+        if (info.size > ATTACHMENT_MAX_BYTES) {
+            throw contractFailure("read_image", "too_large", `image is ${info.size} bytes, over the ${ATTACHMENT_MAX_BYTES}-byte limit`);
+        }
+        const size = Number(info.size);
+        const buffer = Buffer.allocUnsafe(size);
+        let offset = 0;
+        while (offset < size) {
+            const { bytesRead } = await handle.read(buffer, offset, size - offset, offset);
+            if (bytesRead === 0)
+                break;
+            offset += bytesRead;
+        }
+        return buffer.subarray(0, offset);
+    }
+    catch (e) {
+        if (isToolFailure(e))
+            throw e;
+        throw contractFailure("read_image", "io", `cannot read '${path}': ${e instanceof Error ? e.message : String(e)}`);
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+}
+export function readImageTool(options) {
+    const spec = readImageSpec();
+    return {
+        spec: () => spec,
+        execute: async (args) => (await run(args, options)).value,
+        executeWith: async (input) => run(input.args, options),
+    };
+}

package/dist/tools/run-code.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `run_code` — programmatic tool execution with a parent broker (W255;
+ * TypeScript since W774, `crates/tools/src/run_code.rs`).
+ *
+ * One call = one round trip: the program runs under the *same* sandbox as
+ * `run_shell`, its `tools.<name>(...)` bridge calls travel to this process as
+ * one-line JSON on stdout, and each one is dispatched through the identical
+ * `ToolRegistry` pipeline (schema → guards → execute) before the reply goes
+ * back on stdin. The model sees only `main()`'s return value; the intermediate
+ * rows stay in the session log as nested `ToolCall`/`ToolResult` events
+ * (`id = "<parent>:c<n>"`, `parent_id = <parent>`), which `deriveMessages`
+ * skips.
+ *
+ * Wiring is late-bound on purpose ([`RegistryHandle`]): the tool must be
+ * registered *into* the registry it will dispatch through, so the handle is
+ * bound right after registration (the `RegistryHandle` / `run_code_tool_with_handle`).
+ */
+import type { Sandbox, Tool, ToolRegistry, ToolSpec } from "@celestea/core";
+import { type RunCodeEventSink } from "../run-code/broker.js";
+import { type RunCodeConfig } from "../run-code/limits.js";
+/**
+ * Late-bound handle to the composed registry: `run_code` is registered before
+ * the registry can be handed to it, so the assembly binds this afterwards and
+ * dispatch resolves at execution time. The FIRST binding wins (legacy
+ * `OnceLock<Weak<dyn ToolRegistry>>`).
+ */
+export declare class RegistryHandle {
+    private registry;
+    set(registry: ToolRegistry): void;
+    resolve(): ToolRegistry | null;
+}
+export interface RunCodeToolOptions {
+    /** The execution boundary — the same provider `run_shell` runs under. */
+    sandbox: Sandbox;
+    /** Late-bound registry: sub-calls ride its guard + schema pipeline. */
+    handle: RegistryHandle;
+    /** Session-log sink for nested sub-call rows (optional). */
+    events?: RunCodeEventSink;
+    /** Tuning knobs; default = [`runCodeConfigFromEnv`]. */
+    config?: RunCodeConfig;
+}
+/** Build the tool plus the handle the assembly must bind after registration. */
+export declare function runCodeToolWithHandle(options: Omit<RunCodeToolOptions, "handle">): {
+    tool: Tool;
+    handle: RegistryHandle;
+};
+export declare function runCodeTool(options: RunCodeToolOptions): Tool;
+export declare function runCodeSpec(): ToolSpec;

package/dist/tools/run-code.js

@@ -0,0 +1,115 @@
+/**
+ * `run_code` — programmatic tool execution with a parent broker (W255;
+ * TypeScript since W774, `crates/tools/src/run_code.rs`).
+ *
+ * One call = one round trip: the program runs under the *same* sandbox as
+ * `run_shell`, its `tools.<name>(...)` bridge calls travel to this process as
+ * one-line JSON on stdout, and each one is dispatched through the identical
+ * `ToolRegistry` pipeline (schema → guards → execute) before the reply goes
+ * back on stdin. The model sees only `main()`'s return value; the intermediate
+ * rows stay in the session log as nested `ToolCall`/`ToolResult` events
+ * (`id = "<parent>:c<n>"`, `parent_id = <parent>`), which `deriveMessages`
+ * skips.
+ *
+ * Wiring is late-bound on purpose ([`RegistryHandle`]): the tool must be
+ * registered *into* the registry it will dispatch through, so the handle is
+ * bound right after registration (the `RegistryHandle` / `run_code_tool_with_handle`).
+ */
+import { descParam } from "../desc.js";
+import { ToolFailure } from "../tool-failure.js";
+import { brokerRun } from "../run-code/broker.js";
+import { DEFAULT_TIMEOUT_MS, MAX_LOG_BYTES, MAX_SUB_CALLS, MAX_SUB_OUTPUT_BYTES, MAX_TIMEOUT_MS, RUN_CODE_ERROR_PREFIX, runCodeConfigFromEnv, } from "../run-code/limits.js";
+/**
+ * Late-bound handle to the composed registry: `run_code` is registered before
+ * the registry can be handed to it, so the assembly binds this afterwards and
+ * dispatch resolves at execution time. The FIRST binding wins (legacy
+ * `OnceLock<Weak<dyn ToolRegistry>>`).
+ */
+export class RegistryHandle {
+    registry = null;
+    set(registry) {
+        if (this.registry === null)
+            this.registry = registry;
+    }
+    resolve() {
+        return this.registry;
+    }
+}
+/** Build the tool plus the handle the assembly must bind after registration. */
+export function runCodeToolWithHandle(options) {
+    const handle = new RegistryHandle();
+    return { tool: runCodeTool({ ...options, handle }), handle };
+}
+export function runCodeTool(options) {
+    const spec = runCodeSpec();
+    const config = options.config ?? runCodeConfigFromEnv();
+    return {
+        spec: () => spec,
+        execute: async () => {
+            // The broker needs the caller-assigned call id (sub-call ids embed it).
+            throw new ToolFailure(RUN_CODE_ERROR_PREFIX, `${RUN_CODE_ERROR_PREFIX}: dispatched without a call id`);
+        },
+        executeWith: async (input) => {
+            const registry = options.handle.resolve();
+            if (registry === null) {
+                throw new ToolFailure("registry", `${RUN_CODE_ERROR_PREFIX}: code=registry msg="the tool registry is not bound"`);
+            }
+            const ctx = {
+                sandbox: options.sandbox,
+                registry,
+                config,
+                parentId: input.call_id,
+                ...(options.events === undefined ? {} : { events: options.events }),
+            };
+            return brokerRun(ctx, input.args);
+        },
+    };
+}
+/**
+ * The human/model-facing contract text. Kept as one block because it is diffed
+ * byte-for-byte against `contracts/tools.json` (`sdk.test.ts`).
+ */
+const DESC = "Execute a program in the sandbox and get its final value in ONE round trip (parent-broker). " +
+    "DEFAULT LANGUAGE: TypeScript, run by Node with native type stripping (no build step) — only ERASABLE TypeScript is allowed: " +
+    "no `enum`, no `namespace`, no parameter properties, no `declare`; plain JavaScript always works. " +
+    'Pass language: "python" for Python instead. ' +
+    "Write the program as a `function main()` body (an indented body is wrapped for you), or as a complete script that defines main; " +
+    "main() MAY be async and its resolved value (lossless JSON) is the final result. " +
+    "Inside the program the SDK exposes four synchronous bridges dispatched through the normal guarded tool pipeline: " +
+    "tools.read_file({path}) / tools.write_file({path, content}) / tools.list_dir({path}) / tools.run_shell({command}) " +
+    "(Python: tools.read_file(path=...) etc.); a denied or failed sub-call raises ToolCallError (catch it and continue). " +
+    "Bridge tools resolve relative paths against the TOOL workdir, not the program's cwd — pass absolute paths from inside the program. " +
+    "Only log what the model needs: a non-protocol stdout line becomes a log line (≤" + MAX_LOG_BYTES + " bytes, UI render only); " +
+    "intermediate sub-call results are recorded in the session log but context-retained (the model sees only the final value). " +
+    "Hard limits: ≤" + MAX_SUB_CALLS + " sub-calls (the next one errors), wall clock ≤" + MAX_TIMEOUT_MS + "ms (timeout_ms, default " + DEFAULT_TIMEOUT_MS + "), " +
+    "sub-call output ledger ≤" + MAX_SUB_OUTPUT_BYTES + " bytes (truncated with a warning). " +
+    "No network; the same sandbox as run_shell (bwrap/raw/userspace + rlimits).";
+export function runCodeSpec() {
+    return {
+        name: "run_code",
+        description: DESC,
+        parameters: {
+            type: "object",
+            properties: {
+                language: {
+                    type: "string",
+                    enum: ["typescript", "python"],
+                    description: "Program language; default \"typescript\". TypeScript runs under Node's native type stripping (erasable syntax only: no enum/namespace/parameter properties) and needs no build; \"python\" runs under python3 -uB.",
+                },
+                code: {
+                    type: "string",
+                    description: "Program source in the chosen language: a \`function main()\` body (an indented body is wrapped for you) or a complete script that defines main. The engine injects the SDK preamble (tools bridge + protocol).",
+                },
+                timeout_ms: {
+                    type: "integer",
+                    minimum: 1,
+                    maximum: 120000,
+                    description: "Optional whole-run wall clock in ms. Default 120000; hard cap 120000 (CELAESTEA_RUN_CODE_TIMEOUT_MS tunes the default, never the cap).",
+                },
+                desc: descParam(),
+            },
+            required: ["code"],
+            additionalProperties: false,
+        },
+    };
+}

package/dist/tools/run-shell.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `run_shell` — **orchestration only** (`crates/tools/src/builtin.rs`).
+ *
+ * This tool never spawns anything itself: it validates arguments, delegates
+ * execution to the injected `Sandbox` seam, and — for `background: true` —
+ * hands the detached child to the session process registry so
+ * `process_control` can drive it across turns. Consequences:
+ * - swapping in the P2c OS-isolated sandbox changes no line here;
+ * - a timeout/kill/workdir failure arrives as a structured `SandboxError`
+ *   (`run_shell-sandbox: code=…`), never as prose;
+ * - the effective isolation mode is reported back inside `sandbox`.
+ */
+import type { Sandbox, Tool, ToolSpec } from "@celestea/core";
+import type { ProcessRegistry } from "../process/registry.js";
+export interface RunShellToolOptions {
+    /** The execution boundary (userspace-lite in P2b, OS-isolated in P2c). */
+    sandbox: Sandbox;
+    /** Session-scoped registry that owns background children. */
+    processes: ProcessRegistry;
+}
+export declare function runShellSpec(): ToolSpec;
+export declare function runShellTool(options: RunShellToolOptions): Tool;

package/dist/tools/run-shell.js

@@ -0,0 +1,81 @@
+/**
+ * `run_shell` — **orchestration only** (`crates/tools/src/builtin.rs`).
+ *
+ * This tool never spawns anything itself: it validates arguments, delegates
+ * execution to the injected `Sandbox` seam, and — for `background: true` —
+ * hands the detached child to the session process registry so
+ * `process_control` can drive it across turns. Consequences:
+ * - swapping in the P2c OS-isolated sandbox changes no line here;
+ * - a timeout/kill/workdir failure arrives as a structured `SandboxError`
+ *   (`run_shell-sandbox: code=…`), never as prose;
+ * - the effective isolation mode is reported back inside `sandbox`.
+ */
+import { boolArg, optionalIntArg, optionalStringArg, stringArg } from "../args.js";
+import { descParam } from "../desc.js";
+import { fnTool } from "../fn-tool.js";
+export function runShellSpec() {
+    return {
+        name: "run_shell",
+        description: "Run a shell command inside the sandbox (v2 OS isolation when available: namespaces + read-only root + resource limits, else the v1 userspace path; fixed workdir, sanitized env, bounded timeout and output) and return stdout, stderr, exit code, and a `sandbox` object {provider: bwrap|raw|userspace, net_isolated, tmp_private, seccomp} reporting the effective isolation (W249: network isolated and /tmp a private tmpfs by default; CELESTEA_SANDBOX_NET=1 / CELESTEA_SANDBOX_SHARE_TMP=1 restore the shared host net/tmp; CELESTEA_SANDBOX_SECCOMP=1 enables the seccomp whitelist). With background:true the command is spawned detached (no call-level timeout; resource limits still apply) and returns {background, handle, pid} immediately — control it with the process_control tool (poll / stdin / kill); background processes live in the session process registry and survive across turns. Default timeout is 30s; raise it with timeout_ms up to the cap configured by CELESTEA_SHELL_MAX_TIMEOUT_MS (default 300000ms). Optional cpu_sec overrides RLIMIT_CPU for THIS process (default 20s, foreground and background alike); values above the cap from CELESTEA_SHELL_MAX_CPU_SEC (default 600) are CLAMPED to it, and a CPU-cap kill is reported as cpu_exceeded.",
+        parameters: {
+            type: "object",
+            properties: {
+                command: { type: "string", description: "The command line to execute." },
+                workdir: {
+                    type: "string",
+                    description: "Optional working directory. Must already exist inside the sandbox root; relative paths resolve against the sandbox workdir.",
+                },
+                timeout_ms: {
+                    type: "integer",
+                    minimum: 1,
+                    description: "Optional per-call timeout in milliseconds. Default 30000; can be raised up to the cap from CELESTEA_SHELL_MAX_TIMEOUT_MS (default 300000). Ignored when background:true.",
+                },
+                cpu_sec: {
+                    type: "integer",
+                    minimum: 1,
+                    description: "Optional per-call CPU time limit in seconds (RLIMIT_CPU) for THIS process, foreground or background. Default 20; values above CELESTEA_SHELL_MAX_CPU_SEC (default 600) are clamped to that cap. A process killed by the CPU limit reports cpu_exceeded:true with a message naming the limit.",
+                },
+                background: {
+                    type: "boolean",
+                    description: "Optional, default false. When true, spawn the command detached (no call-level timeout; rlimits including cpu_sec still apply) and return {background:true, handle, pid} immediately; control the process with process_control (poll / stdin / kill). A process that exits stays pollable from a bounded tombstone (most recent 32, or 10 minutes), so poll after exit still returns exit_code/signal and the tails.",
+                },
+                notify: {
+                    type: "boolean",
+                    description: "Optional, default true. When background:true, whether a NATURAL exit may be offered to a host completion sink. No sink is wired in this deployment, so read the terminal state with process_control(action=poll); the flag is kept for hosts that install one.",
+                },
+                desc: descParam(),
+            },
+            required: ["command"],
+            additionalProperties: false,
+        },
+    };
+}
+export function runShellTool(options) {
+    return fnTool(runShellSpec(), async (args) => {
+        const command = stringArg(args, "command");
+        const workdir = optionalStringArg(args, "workdir");
+        const cpuSec = optionalIntArg(args, "cpu_sec");
+        const cpu = cpuSec === undefined ? {} : { cpuSec };
+        if (boolArg(args, "background", false)) {
+            const spawned = await options.sandbox.spawn({ command, workdir, ...cpu });
+            const handle = options.processes.insert(spawned.child, boolArg(args, "notify", true), {
+                cpuSec: spawned.sandbox.cpu_sec ?? cpuSec ?? null,
+            });
+            return { background: true, handle: handle.handle, pid: handle.pid, sandbox: spawned.sandbox };
+        }
+        const run = await options.sandbox.run({ command, workdir, timeoutMs: optionalIntArg(args, "timeout_ms"), ...cpu });
+        // W6: an RLIMIT_CPU kill (SIGXCPU, or the SIGKILL that follows) must not read
+        // as a bare death; mark it when the provider reported a CPU cap in force.
+        const cpuExceeded = run.exit_code === null && run.sandbox.cpu_sec !== undefined && (run.signal === "SIGXCPU" || run.signal === "SIGKILL");
+        return {
+            stdout: run.stdout,
+            stderr: run.stderr,
+            exit_code: run.exit_code,
+            ...(run.signal === null || run.signal === undefined ? {} : { signal: run.signal }),
+            ...(cpuExceeded ? { cpu_exceeded: true, message: `CPU time limit ${run.sandbox.cpu_sec}s exceeded` } : {}),
+            stdout_truncated: run.stdout_truncated,
+            stderr_truncated: run.stderr_truncated,
+            sandbox: run.sandbox,
+        };
+    });
+}

package/dist/tools/write-file.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `write_file` — create or overwrite a text file, answering `"ok"` like the
+ * legacy `builtin.rs::write_file`. The path policy (workspace-only writes) is
+ * enforced by the guard chain, not here.
+ */
+import type { Tool, ToolSpec } from "@celestea/core";
+export declare function writeFileSpec(): ToolSpec;
+export declare function writeFileTool(): Tool;

package/dist/tools/write-file.js

@@ -0,0 +1,31 @@
+/**
+ * `write_file` — create or overwrite a text file, answering `"ok"` like the
+ * legacy `builtin.rs::write_file`. The path policy (workspace-only writes) is
+ * enforced by the guard chain, not here.
+ */
+import { stringArg } from "../args.js";
+import { descParam } from "../desc.js";
+import { writeTextFile } from "../fs/file-io.js";
+import { fnTool } from "../fn-tool.js";
+export function writeFileSpec() {
+    return {
+        name: "write_file",
+        description: "Write text content to a file, creating or overwriting it.",
+        parameters: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "Filesystem path of the file to write." },
+                content: { type: "string", description: "Text content to write." },
+                desc: descParam(),
+            },
+            required: ["path", "content"],
+            additionalProperties: false,
+        },
+    };
+}
+export function writeFileTool() {
+    return fnTool(writeFileSpec(), async (args) => {
+        await writeTextFile(stringArg(args, "path"), stringArg(args, "content"));
+        return "ok";
+    });
+}