@celestea/tools 2.7.1

package/dist/plugin.js

@@ -0,0 +1,101 @@
+/**
+ * The tools plugin — `mount(ctx)` is the only installation path (nothing
+ * self-registers at runtime), and it publishes exactly three services:
+ *
+ * - `ToolRegistryService` → the assembled registry (schema → guard → execute);
+ * - `SandboxService`      → the execution boundary `run_shell` orchestrates;
+ * - `ProcessRegistryService` → the session-scoped background process registry.
+ *
+ * The guard chain is mounted here because **order is security semantics**: the
+ * path whitelist must run before any tool execution, and `CELESTEA_TOOL_GUARD=0`
+ * is the only (explicit, documented) way to skip it.
+ *
+ * `run_code` (W255) is mounted here too, not in `builtinTools`: it needs a
+ * late-bound handle on the very registry it will dispatch sub-calls through,
+ * which only the assembly can bind — exactly like the runtime compose
+ * (`crates/runtime/src/tools.rs`). Pass `runCode: false` to leave it out.
+ */
+import { definePlugin, SANDBOX_SERVICE, TOOL_REGISTRY_SERVICE, } from "@celestea/core";
+import { builtinTools } from "./builtin.js";
+import { mountProductionGuards } from "./guard/path-guard.js";
+import { HttpTargetPolicy } from "./http/ssrf.js";
+import { PROCESS_REGISTRY_SERVICE, ProcessRegistry } from "./process/registry.js";
+import { ToolRegistryImpl } from "./registry.js";
+import { sessionSandboxConfig } from "./sandbox/config.js";
+import { selectSandbox } from "./sandbox/provider.js";
+import { RegistryHandle, runCodeToolWithHandle } from "./tools/run-code.js";
+export const TOOLS_PLUGIN_NAME = "celestea.tools";
+/** Build the tool assembly without mounting it (compose roots / tests). */
+export function assembleTools(options = {}) {
+    const env = options.env ?? process.env;
+    const grants = options.grants ?? {};
+    const scope = options.scope ?? null;
+    const processes = options.processes ?? new ProcessRegistry();
+    // W768: ONE scope feeds both halves of the boundary — the sandbox's cwd/root
+    // and the guard's writable workspace — so "where the shell starts" and "what
+    // the path tools may touch" are the same directory by construction.
+    const sandbox = options.sandbox ?? selectSandbox({ env, grants, config: sessionSandboxConfig(scope, env) });
+    const registry = new ToolRegistryImpl();
+    // W783: the injected question service must reach the DEFAULT tool set too, not
+    // only an explicitly supplied one — otherwise a host that mounts the service
+    // through `assembleTools` would silently lose the tool.
+    const tools = options.tools
+        ?? builtinTools({
+            sandbox,
+            processes,
+            http: httpOptions(env, grants),
+            // W884: the skill layers hang off the SAME session scope the sandbox and
+            // the path guard use (W768) — never the process cwd.
+            workspace: scope?.workspace ?? null,
+            env,
+            ...(options.questions === undefined ? {} : { questions: options.questions }),
+            ...(options.attachments === undefined ? {} : { attachments: options.attachments }),
+            ...(options.imageInputAllowed === undefined ? {} : { imageInputAllowed: options.imageInputAllowed }),
+            ...(options.model === undefined ? {} : { model: options.model }),
+        });
+    for (const tool of tools)
+        registry.register(tool);
+    const runCode = mountRunCode(registry, sandbox, options);
+    let guardMounted = false;
+    if (options.guard === null)
+        guardMounted = false;
+    else if (options.guard !== undefined) {
+        registry.addGuard(options.guard);
+        guardMounted = true;
+    }
+    else
+        guardMounted = mountProductionGuards(registry, env, grants, scope);
+    return { registry, sandbox, processes, guardMounted, runCode };
+}
+/** The `http_request` options of this assembly (grants merged into allow). */
+export function httpOptions(env, grants) {
+    return { env, policy: HttpTargetPolicy.fromEnv(env, grants) };
+}
+/**
+ * Mount the W255 `run_code` tool: register it into [registry], then bind the
+ * handle to that same registry (the tool must live inside the registry it
+ * dispatches through). A caller-supplied `run_code` tool always wins.
+ */
+function mountRunCode(registry, sandbox, options) {
+    if (options.runCode === false)
+        return null;
+    if (registry.get("run_code") !== undefined)
+        return null;
+    const mount = options.runCode ?? {};
+    const { tool, handle } = runCodeToolWithHandle({
+        sandbox,
+        ...(mount.config === undefined ? {} : { config: mount.config }),
+        ...(mount.events === undefined ? {} : { events: mount.events }),
+    });
+    registry.register(tool);
+    handle.set(registry);
+    return handle;
+}
+export function toolsPlugin(options = {}) {
+    return definePlugin(TOOLS_PLUGIN_NAME, (ctx) => {
+        const assembly = assembleTools(options);
+        ctx.provide(TOOL_REGISTRY_SERVICE, assembly.registry);
+        ctx.provide(SANDBOX_SERVICE, assembly.sandbox);
+        ctx.provide(PROCESS_REGISTRY_SERVICE, assembly.processes);
+    });
+}

package/dist/process/buffers.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Capped stream buffers for background processes (`crates/tools/src/process.rs`).
+ *
+ * A background process outlives the turn, so its output must not grow without
+ * bound: each stream keeps the LAST N bytes (older bytes are dropped and the
+ * truncation flag latched), `poll` returns a short tail, and the completion
+ * record keeps an even shorter tail with newline runs folded so the mailbox
+ * message stays compact.
+ */
+/** Bytes kept per stream in the registry ring buffer (last N bytes win). */
+export declare const MAX_STREAM_BUFFER: number;
+/** Bytes returned by `poll` as `stdout_tail` / `stderr_tail`. */
+export declare const TAIL_BYTES: number;
+/** Bytes kept per stream in a completion record. */
+export declare const COMPLETION_TAIL_BYTES = 1024;
+/** Append-only ring buffer over bytes: keeps the newest `cap` bytes. */
+export declare class RingBuffer {
+    private chunks;
+    private size;
+    private overflow;
+    private readonly cap;
+    constructor(cap?: number);
+    append(data: Buffer): void;
+    private dropOldest;
+    get truncated(): boolean;
+    get length(): number;
+    toBuffer(): Buffer;
+    /** The last `bytes` bytes, decoded as UTF-8 (partial sequences are lossy). */
+    tail(bytes: number): string;
+}
+/** Last [COMPLETION_TAIL_BYTES] of a stream with newline runs folded. */
+export declare function completionTail(buffer: RingBuffer, bytes?: number): string;
+export declare function foldNewlines(text: string): string;

package/dist/process/buffers.js

@@ -0,0 +1,86 @@
+/**
+ * Capped stream buffers for background processes (`crates/tools/src/process.rs`).
+ *
+ * A background process outlives the turn, so its output must not grow without
+ * bound: each stream keeps the LAST N bytes (older bytes are dropped and the
+ * truncation flag latched), `poll` returns a short tail, and the completion
+ * record keeps an even shorter tail with newline runs folded so the mailbox
+ * message stays compact.
+ */
+/** Bytes kept per stream in the registry ring buffer (last N bytes win). */
+export const MAX_STREAM_BUFFER = 512 * 1024;
+/** Bytes returned by `poll` as `stdout_tail` / `stderr_tail`. */
+export const TAIL_BYTES = 4 * 1024;
+/** Bytes kept per stream in a completion record. */
+export const COMPLETION_TAIL_BYTES = 1024;
+/** Append-only ring buffer over bytes: keeps the newest `cap` bytes. */
+export class RingBuffer {
+    chunks = [];
+    size = 0;
+    overflow = false;
+    cap;
+    constructor(cap = MAX_STREAM_BUFFER) {
+        this.cap = cap;
+    }
+    append(data) {
+        if (data.length >= this.cap) {
+            this.chunks = [data.subarray(data.length - this.cap)];
+            this.size = this.cap;
+            this.overflow = true;
+            return;
+        }
+        this.chunks.push(data);
+        this.size += data.length;
+        this.dropOldest();
+    }
+    dropOldest() {
+        while (this.size > this.cap) {
+            const head = this.chunks[0];
+            if (head === undefined)
+                return;
+            const excess = this.size - this.cap;
+            if (head.length <= excess) {
+                this.chunks.shift();
+                this.size -= head.length;
+            }
+            else {
+                this.chunks[0] = head.subarray(excess);
+                this.size -= excess;
+            }
+            this.overflow = true;
+        }
+    }
+    get truncated() {
+        return this.overflow;
+    }
+    get length() {
+        return this.size;
+    }
+    toBuffer() {
+        return Buffer.concat(this.chunks);
+    }
+    /** The last `bytes` bytes, decoded as UTF-8 (partial sequences are lossy). */
+    tail(bytes) {
+        const all = this.toBuffer();
+        return all.subarray(Math.max(all.length - bytes, 0)).toString("utf8");
+    }
+}
+/** Last [COMPLETION_TAIL_BYTES] of a stream with newline runs folded. */
+export function completionTail(buffer, bytes = COMPLETION_TAIL_BYTES) {
+    return foldNewlines(buffer.tail(bytes));
+}
+export function foldNewlines(text) {
+    let out = "";
+    let previousWasNewline = false;
+    for (const ch of text) {
+        if (ch !== "\n") {
+            out += ch;
+            previousWasNewline = false;
+            continue;
+        }
+        if (!previousWasNewline)
+            out += ch;
+        previousWasNewline = true;
+    }
+    return out;
+}

package/dist/process/registry.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Session-scoped registry of background processes (`crates/tools/src/process.rs`).
+ *
+ * A `run_shell(background: true)` spawn registers its detached child here.
+ * Entries survive across turns — that is the point: a server started in one
+ * turn stays controllable from later turns. Each child gets a reaper that
+ * drains stdout/stderr into capped ring buffers and records the exit exactly
+ * once. W6: a finished process is retained as a BOUNDED tombstone (most recent
+ * `MAX_TOMBSTONES`, at most `TOMBSTONE_TTL_MS`), so a `poll` AFTER exit still
+ * returns `{running:false, exit_code, signal, stdout_tail, stderr_tail}` instead
+ * of `unknown handle`; a CPU-cap kill is marked `cpu_exceeded`. For a **natural**
+ * exit the completion sink may fire once (a host CAN push a `[process] … exited
+ * …` message into a session mailbox, though this studio host does not wire one —
+ * `process_control(action=poll)` is the durable read). `kill`/`killAll` paths
+ * are deliberately silent: the caller already got `{killed: true}` back.
+ */
+import type { SandboxChild } from "@celestea/core";
+/** Well-known token for the process registry service in a Context. */
+export declare const PROCESS_REGISTRY_SERVICE = "celestea.tools.ProcessRegistry";
+/** Grace between SIGTERM and SIGKILL in `kill`. */
+export declare const KILL_GRACE_MS = 1000;
+/** Upper bound for the SIGKILL reap wait. */
+export declare const KILL_WAIT_MS = 2000;
+/** Upper bound for one stdin line write. */
+export declare const STDIN_WRITE_TIMEOUT_MS = 5000;
+/** W6: how many terminal records stay pollable (most recent wins). */
+export declare const MAX_TOMBSTONES = 32;
+/** W6: how long a terminal record stays pollable. */
+export declare const TOMBSTONE_TTL_MS: number;
+/** One natural-exit completion handed to the sink (W251 parity). */
+export interface ProcessCompletion {
+    handle: string;
+    pid: number | null;
+    exit_code: number | null;
+    stdout_tail: string;
+    stderr_tail: string;
+    elapsed_ms: number;
+}
+export type CompletionSink = (completion: ProcessCompletion) => void;
+export interface ProcessRegistryOptions {
+    killGraceMs?: number;
+    killWaitMs?: number;
+    maxStreamBuffer?: number;
+    tailBytes?: number;
+    /** W6: cap on retained terminal records (default [MAX_TOMBSTONES]). */
+    maxTombstones?: number;
+    /** W6: TTL of a terminal record (default [TOMBSTONE_TTL_MS]). */
+    tombstoneTtlMs?: number;
+    /** Clock (tests pin it). */
+    now?: () => number;
+}
+/** W6: per-insert facts the terminal record needs (the effective CPU cap). */
+export interface ProcessInsertOptions {
+    /** Effective `RLIMIT_CPU` of this process; enables the `cpu_exceeded` marker. */
+    cpuSec?: number | null;
+}
+export interface ProcessHandle {
+    handle: string;
+    pid: number | null;
+}
+export declare class ProcessRegistry {
+    private readonly map;
+    /** W6: finished processes (bounded in count and age), still pollable. */
+    private readonly tombstones;
+    private readonly options;
+    private readonly now;
+    private nextHandle;
+    private completionSink;
+    constructor(options?: ProcessRegistryOptions);
+    /** Install (or clear) the natural-exit sink: one per registry, last wins. */
+    setCompletionSink(sink: CompletionSink | null): void;
+    /** Register a spawned child: takes over its pipes and starts the reaper. */
+    insert(child: SandboxChild, notify?: boolean, opts?: ProcessInsertOptions): ProcessHandle;
+    get size(): number;
+    get isEmpty(): boolean;
+    /** `process_control(action=poll)`: running flag, capped tails, exit code. */
+    poll(handle: string): Record<string, unknown>;
+    /** `process_control(action=kill)`: SIGTERM, grace, then SIGKILL. Silent. */
+    kill(handle: string): Promise<Record<string, unknown>>;
+    /** `process_control(action=stdin)`: write one line (content + newline). */
+    stdinLine(handle: string, line: string): Promise<Record<string, unknown>>;
+    private write;
+    /** Kill every still-registered child (shutdown path); idempotent. */
+    killAll(): void;
+    /** Alias of [killAll] for `Runtime.shutdown` call sites. */
+    dispose(): void;
+    private waitExited;
+    /** Reaper tail: record the exit once, tombstone it, then maybe notify. */
+    private finish;
+    /** A live tombstone, or undefined (evicting it once its TTL has passed). */
+    private tombstone;
+    /** W6: the terminal answer `poll` gives after a process has exited. */
+    private tombstonePoll;
+    /** W6: RLIMIT_CPU termination (SIGXCPU, or the SIGKILL that follows it). */
+    private cpuExceeded;
+    /** Evict terminal records past the TTL, then oldest-first past the count cap. */
+    private evictTombstones;
+}

package/dist/process/registry.js

@@ -0,0 +1,282 @@
+/**
+ * Session-scoped registry of background processes (`crates/tools/src/process.rs`).
+ *
+ * A `run_shell(background: true)` spawn registers its detached child here.
+ * Entries survive across turns — that is the point: a server started in one
+ * turn stays controllable from later turns. Each child gets a reaper that
+ * drains stdout/stderr into capped ring buffers and records the exit exactly
+ * once. W6: a finished process is retained as a BOUNDED tombstone (most recent
+ * `MAX_TOMBSTONES`, at most `TOMBSTONE_TTL_MS`), so a `poll` AFTER exit still
+ * returns `{running:false, exit_code, signal, stdout_tail, stderr_tail}` instead
+ * of `unknown handle`; a CPU-cap kill is marked `cpu_exceeded`. For a **natural**
+ * exit the completion sink may fire once (a host CAN push a `[process] … exited
+ * …` message into a session mailbox, though this studio host does not wire one —
+ * `process_control(action=poll)` is the durable read). `kill`/`killAll` paths
+ * are deliberately silent: the caller already got `{killed: true}` back.
+ */
+import { delay, TIMED_OUT, withTimeout } from "../sandbox/async.js";
+import { completionTail, MAX_STREAM_BUFFER, RingBuffer, TAIL_BYTES, } from "./buffers.js";
+/** Well-known token for the process registry service in a Context. */
+export const PROCESS_REGISTRY_SERVICE = "celestea.tools.ProcessRegistry";
+/** Grace between SIGTERM and SIGKILL in `kill`. */
+export const KILL_GRACE_MS = 1_000;
+/** Upper bound for the SIGKILL reap wait. */
+export const KILL_WAIT_MS = 2_000;
+/** Upper bound for one stdin line write. */
+export const STDIN_WRITE_TIMEOUT_MS = 5_000;
+/** Exit-poll interval while waiting for a kill to land. */
+const POLL_INTERVAL_MS = 20;
+/** W6: how many terminal records stay pollable (most recent wins). */
+export const MAX_TOMBSTONES = 32;
+/** W6: how long a terminal record stays pollable. */
+export const TOMBSTONE_TTL_MS = 10 * 60 * 1_000;
+class ProcState {
+    exited = false;
+    exitCode = null;
+    /** W6: terminating signal (SIGXCPU/SIGKILL on a CPU cap, …). */
+    signal = null;
+    /** kill/shutdown path: record the exit, never fire the completion sink. */
+    killPath = false;
+    writeChain = Promise.resolve();
+    stdout;
+    stderr;
+    spawnedAt = Date.now();
+    constructor(maxStreamBuffer) {
+        this.stdout = new RingBuffer(maxStreamBuffer);
+        this.stderr = new RingBuffer(maxStreamBuffer);
+    }
+}
+export class ProcessRegistry {
+    map = new Map();
+    /** W6: finished processes (bounded in count and age), still pollable. */
+    tombstones = new Map();
+    options;
+    now;
+    nextHandle = 0;
+    completionSink = null;
+    constructor(options = {}) {
+        this.options = {
+            killGraceMs: options.killGraceMs ?? KILL_GRACE_MS,
+            killWaitMs: options.killWaitMs ?? KILL_WAIT_MS,
+            maxStreamBuffer: options.maxStreamBuffer ?? MAX_STREAM_BUFFER,
+            tailBytes: options.tailBytes ?? TAIL_BYTES,
+            maxTombstones: options.maxTombstones ?? MAX_TOMBSTONES,
+            tombstoneTtlMs: options.tombstoneTtlMs ?? TOMBSTONE_TTL_MS,
+        };
+        this.now = options.now ?? Date.now;
+    }
+    /** Install (or clear) the natural-exit sink: one per registry, last wins. */
+    setCompletionSink(sink) {
+        this.completionSink = sink;
+    }
+    /** Register a spawned child: takes over its pipes and starts the reaper. */
+    insert(child, notify = true, opts = {}) {
+        const handle = `proc-${this.nextHandle}`;
+        this.nextHandle += 1;
+        const state = new ProcState(this.options.maxStreamBuffer);
+        const entry = { handle, pid: child.pid, child, state, notify, cpuSec: opts.cpuSec ?? null };
+        this.map.set(handle, entry);
+        child.stdout?.on("data", (chunk) => state.stdout.append(chunk));
+        child.stderr?.on("data", (chunk) => state.stderr.append(chunk));
+        void child.wait().then((exit) => this.finish(entry, exit));
+        return { handle, pid: child.pid };
+    }
+    get size() {
+        return this.map.size;
+    }
+    get isEmpty() {
+        return this.map.size === 0;
+    }
+    /** `process_control(action=poll)`: running flag, capped tails, exit code. */
+    poll(handle) {
+        const entry = this.map.get(handle);
+        if (entry !== undefined) {
+            const state = entry.state;
+            return {
+                ok: true,
+                handle: entry.handle,
+                pid: entry.pid,
+                running: !state.exited,
+                stdout_tail: state.stdout.tail(this.options.tailBytes),
+                stderr_tail: state.stderr.tail(this.options.tailBytes),
+                stdout_truncated: state.stdout.truncated,
+                stderr_truncated: state.stderr.truncated,
+                exit_code: state.exited ? state.exitCode : null,
+            };
+        }
+        // W6: a finished process stays pollable from its bounded tombstone.
+        const done = this.tombstone(handle);
+        return done === undefined ? unknownHandle(handle) : this.tombstonePoll(done);
+    }
+    /** `process_control(action=kill)`: SIGTERM, grace, then SIGKILL. Silent. */
+    async kill(handle) {
+        const entry = this.map.get(handle);
+        if (entry === undefined) {
+            const done = this.tombstone(handle);
+            return done === undefined ? unknownHandle(handle) : { ok: false, error: exitedMessage(done) };
+        }
+        entry.state.killPath = true;
+        entry.child.terminate();
+        if (!(await this.waitExited(entry, this.options.killGraceMs))) {
+            entry.child.kill();
+            await this.waitExited(entry, this.options.killWaitMs);
+        }
+        return { ok: true, killed: true, handle: entry.handle };
+    }
+    /** `process_control(action=stdin)`: write one line (content + newline). */
+    async stdinLine(handle, line) {
+        const entry = this.map.get(handle);
+        if (entry === undefined) {
+            const done = this.tombstone(handle);
+            return done === undefined ? unknownHandle(handle) : { ok: false, error: `process ${handle} already exited` };
+        }
+        if (entry.state.exited)
+            return { ok: false, error: `process ${handle} already exited` };
+        if (entry.child.stdin === null)
+            return { ok: false, error: `process ${handle} stdin unavailable` };
+        const payload = `${line}\n`;
+        // Serialize writes per process: two concurrent stdin actions must not
+        // interleave and corrupt a line-oriented child.
+        const chained = entry.state.writeChain.then(() => this.write(entry, payload));
+        entry.state.writeChain = chained.catch(() => undefined);
+        const settled = await withTimeout(chained.then(() => ({ ok: true }), (e) => ({ ok: false, error: `stdin write failed: ${e instanceof Error ? e.message : String(e)}` })), STDIN_WRITE_TIMEOUT_MS);
+        if (settled === TIMED_OUT)
+            return { ok: false, error: "stdin write timed out (5s)" };
+        if (!settled.ok)
+            return { ok: false, error: settled.error };
+        return { ok: true, handle: entry.handle, written: Buffer.byteLength(payload) };
+    }
+    write(entry, payload) {
+        const stdin = entry.child.stdin;
+        if (stdin === null)
+            return Promise.resolve();
+        return new Promise((resolve, reject) => {
+            stdin.write(payload, (error) => (error === null || error === undefined ? resolve() : reject(error)));
+        });
+    }
+    /** Kill every still-registered child (shutdown path); idempotent. */
+    killAll() {
+        for (const entry of [...this.map.values()]) {
+            entry.state.killPath = true;
+            entry.child.kill();
+        }
+        this.map.clear();
+        this.tombstones.clear();
+    }
+    /** Alias of [killAll] for `Runtime.shutdown` call sites. */
+    dispose() {
+        this.killAll();
+    }
+    async waitExited(entry, windowMs) {
+        const deadline = Date.now() + windowMs;
+        while (Date.now() < deadline) {
+            if (entry.state.exited)
+                return true;
+            await delay(POLL_INTERVAL_MS);
+        }
+        return entry.state.exited;
+    }
+    /** Reaper tail: record the exit once, tombstone it, then maybe notify. */
+    finish(entry, exit) {
+        const state = entry.state;
+        if (state.exited)
+            return;
+        state.exited = true;
+        state.exitCode = exit.code;
+        state.signal = exit.signal ?? null;
+        this.map.delete(entry.handle);
+        // W6: keep a bounded terminal record so poll-after-exit still answers.
+        this.tombstones.set(entry.handle, {
+            handle: entry.handle,
+            pid: entry.pid,
+            exitCode: state.exitCode,
+            signal: state.signal,
+            cpuSec: entry.cpuSec,
+            stdoutTail: state.stdout.tail(this.options.tailBytes),
+            stderrTail: state.stderr.tail(this.options.tailBytes),
+            stdoutTruncated: state.stdout.truncated,
+            stderrTruncated: state.stderr.truncated,
+            spawnedAt: state.spawnedAt,
+            finishedAt: this.now(),
+            killPath: state.killPath,
+        });
+        this.evictTombstones();
+        if (!entry.notify || state.killPath)
+            return;
+        this.completionSink?.({
+            handle: entry.handle,
+            pid: entry.pid,
+            exit_code: exit.code,
+            stdout_tail: completionTail(state.stdout),
+            stderr_tail: completionTail(state.stderr),
+            elapsed_ms: this.now() - state.spawnedAt,
+        });
+    }
+    /** A live tombstone, or undefined (evicting it once its TTL has passed). */
+    tombstone(handle) {
+        const done = this.tombstones.get(handle);
+        if (done === undefined)
+            return undefined;
+        if (this.now() - done.finishedAt > this.options.tombstoneTtlMs) {
+            this.tombstones.delete(handle);
+            return undefined;
+        }
+        return done;
+    }
+    /** W6: the terminal answer `poll` gives after a process has exited. */
+    tombstonePoll(done) {
+        const cpuExceeded = this.cpuExceeded(done);
+        return {
+            ok: true,
+            handle: done.handle,
+            pid: done.pid,
+            running: false,
+            stdout_tail: done.stdoutTail,
+            stderr_tail: done.stderrTail,
+            stdout_truncated: done.stdoutTruncated,
+            stderr_truncated: done.stderrTruncated,
+            exit_code: done.exitCode,
+            signal: done.signal,
+            ...(cpuExceeded ? { cpu_exceeded: true, message: `CPU time limit ${done.cpuSec}s exceeded` } : {}),
+        };
+    }
+    /** W6: RLIMIT_CPU termination (SIGXCPU, or the SIGKILL that follows it). */
+    cpuExceeded(done) {
+        if (done.killPath || done.cpuSec === null)
+            return false;
+        return done.signal === "SIGXCPU" || done.signal === "SIGKILL";
+    }
+    /** Evict terminal records past the TTL, then oldest-first past the count cap. */
+    evictTombstones() {
+        const now = this.now();
+        for (const [handle, done] of [...this.tombstones]) {
+            if (now - done.finishedAt > this.options.tombstoneTtlMs)
+                this.tombstones.delete(handle);
+        }
+        while (this.tombstones.size > this.options.maxTombstones) {
+            let oldest = null;
+            let oldestAt = Infinity;
+            for (const [handle, done] of this.tombstones) {
+                if (done.finishedAt < oldestAt) {
+                    oldestAt = done.finishedAt;
+                    oldest = handle;
+                }
+            }
+            if (oldest === null)
+                break;
+            this.tombstones.delete(oldest);
+        }
+    }
+}
+function unknownHandle(handle) {
+    return { ok: false, error: `unknown handle: ${handle}` };
+}
+/** W6: a clear terminal error for a handle whose process has already exited. */
+function exitedMessage(done) {
+    const tail = done.exitCode === null
+        ? done.signal === null
+            ? "no exit status"
+            : `signal=${done.signal}`
+        : `exit_code=${done.exitCode}`;
+    return `process ${done.handle} already exited (${tail})`;
+}

package/dist/registry.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `ToolRegistryImpl` — the dispatch pipeline of the tool seam.
+ *
+ * One dispatch runs four stages, in this order (a hard pipeline, not a
+ * convention):
+ *   1. **schema** — `args` are validated against `tool.spec().parameters`
+ *      (`toolargs: code=schema …`, the tool never runs);
+ *   2. **guard** — the guard chain runs in registration order and the FIRST
+ *      non-`Allow` decision short-circuits (`denied: toolguard: …`) — a later
+ *      `Allow` never un-denies an earlier `Deny`;
+ *   3. **execute** — through `executeWith` when the tool overrides it, else
+ *      `execute(args)`;
+ *   4. **structure** — the result is a `ToolOutput`: canonical `value`, an
+ *      optional authored `render`, captured `error`, and the guard `decision`
+ *      as a first-class field.
+ *
+ * Errors are captured, never thrown across the seam (parity:
+ * `crates/tools/src/registry.rs`).
+ *
+ * **The verdict never lies (W738 P1)**: `decision` describes what the seam did
+ * with the call, so a call the seam REFUSED to run (unknown tool, schema
+ * rejection) is a `deny`, never an `allow` — an `allow` there would tell the
+ * caller (and the audit log) that a rejected call passed every check. A tool that
+ * did run and then failed keeps `allow`: the guards really did allow it and the
+ * verdict is not a success flag.
+ */
+import type { Tool, ToolGuard, ToolInput, ToolOutput, ToolRegistry, ToolSpec } from "@celestea/core";
+export declare class ToolRegistryImpl implements ToolRegistry {
+    private readonly tools;
+    private readonly guards;
+    register(tool: Tool): void;
+    addGuard(guard: ToolGuard): void;
+    get(name: string): Tool | undefined;
+    /** Registered tool names, in registration order (`schemas()` sorts instead). */
+    names(): string[];
+    /** The guard chain, in evaluation order (diagnostics / compose assertions). */
+    guardChain(): readonly ToolGuard[];
+    schemas(): ToolSpec[];
+    dispatch(input: ToolInput): Promise<ToolOutput>;
+    private runTool;
+    private runGuards;
+}
+/** Registry seeded with tools + guards (guards run in the given order). */
+export declare function createToolRegistry(tools?: readonly Tool[], guards?: readonly ToolGuard[]): ToolRegistryImpl;
+/**
+ * Best-effort human-readable rendering of a successful result (legacy
+ * `human_render`): a `{stdout, stderr, exit_code}` object condenses to a stream
+ * summary; plain text and everything else keep the generic value view (`null`).
+ */
+export declare function humanRender(value: unknown): string | null;
+/** Stamp a guard denial reason with the contract prefix (compose-time helper). */
+export declare function guardDenyReason(code: string, message: string): string;