@celestea/tools 2.7.1

package/dist/registry.js

@@ -0,0 +1,161 @@
+/**
+ * `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 { GUARD_ERROR_PREFIX, TOOLARG_ERROR_PREFIX, contractError, errorText, quoteMessage } from "./errors.js";
+import { validateArgs } from "./schema.js";
+const ALLOW = { kind: "allow" };
+export class ToolRegistryImpl {
+    tools = new Map();
+    guards = [];
+    register(tool) {
+        this.tools.set(tool.spec().name, tool);
+    }
+    addGuard(guard) {
+        this.guards.push(guard);
+    }
+    get(name) {
+        return this.tools.get(name);
+    }
+    /** Registered tool names, in registration order (`schemas()` sorts instead). */
+    names() {
+        return [...this.tools.keys()];
+    }
+    /** The guard chain, in evaluation order (diagnostics / compose assertions). */
+    guardChain() {
+        return this.guards;
+    }
+    schemas() {
+        return [...this.tools.values()].map((t) => t.spec()).sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    }
+    async dispatch(input) {
+        const tool = this.tools.get(input.name);
+        if (tool === undefined)
+            return refused(input.call_id, `unknown tool: ${input.name}`);
+        const invalid = validateArgs(tool.spec().parameters, input.args);
+        if (invalid !== null) {
+            return refused(input.call_id, contractError(TOOLARG_ERROR_PREFIX, "schema", invalid.message));
+        }
+        const decision = await this.runGuards(input);
+        if (decision.kind === "deny")
+            return decisionFailure(input.call_id, "deny", decision.reason);
+        if (decision.kind === "ask")
+            return decisionFailure(input.call_id, "ask", decision.reason);
+        return this.runTool(tool, input);
+    }
+    async runTool(tool, input) {
+        try {
+            const outcome = tool.executeWith === undefined
+                ? { value: await tool.execute(input.args), render: null }
+                : await tool.executeWith(input);
+            return {
+                call_id: input.call_id,
+                value: outcome.value,
+                render: outcome.render ?? humanRender(outcome.value),
+                error: null,
+                decision: ALLOW,
+                // W855 (B6): a tool-authored model face (e.g. read_file truncation).
+                ...(outcome.surface === undefined ? {} : { surface: outcome.surface }),
+            };
+        }
+        catch (e) {
+            return failure(input.call_id, errorText(e));
+        }
+    }
+    async runGuards(input) {
+        for (const guard of this.guards) {
+            let decision;
+            try {
+                decision = await guard.check(input);
+            }
+            catch (e) {
+                decision = { kind: "deny", reason: contractError(GUARD_ERROR_PREFIX, "guard_error", errorText(e)) };
+            }
+            if (decision.kind !== "allow")
+                return decision;
+        }
+        return ALLOW;
+    }
+}
+/**
+ * A call that ran and then failed: the guards allowed it, so the verdict is
+ * `allow` — `error` carries the failure (`decision` is not a success flag).
+ */
+function failure(callId, error) {
+    return { call_id: callId, value: null, render: null, error, decision: ALLOW };
+}
+/**
+ * A call the seam REFUSED before execution (unknown tool / invalid args): the
+ * verdict is a `deny` whose reason is the very error the caller sees, so
+ * "refused" can never be reported as "allowed" (W738 P1).
+ */
+function refused(callId, error) {
+    return { call_id: callId, value: null, render: null, error, decision: { kind: "deny", reason: error } };
+}
+function decisionFailure(callId, kind, reason) {
+    // parity: a Deny surfaces as `denied: <reason>`, an Ask as `ask: <reason>`.
+    return {
+        call_id: callId,
+        value: null,
+        render: null,
+        error: `${kind === "deny" ? "denied" : "ask"}: ${reason}`,
+        decision: kind === "deny" ? { kind: "deny", reason } : { kind: "ask", reason },
+    };
+}
+/** Registry seeded with tools + guards (guards run in the given order). */
+export function createToolRegistry(tools = [], guards = []) {
+    const registry = new ToolRegistryImpl();
+    for (const tool of tools)
+        registry.register(tool);
+    for (const guard of guards)
+        registry.addGuard(guard);
+    return registry;
+}
+/**
+ * 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 function humanRender(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return null;
+    const obj = value;
+    const isStreamShape = "stdout" in obj || "stderr" in obj || "exit_code" in obj;
+    if (!isStreamShape)
+        return null;
+    const lines = [];
+    if (obj["exit_code"] !== undefined && obj["exit_code"] !== null)
+        lines.push(`exit_code: ${String(obj["exit_code"])}`);
+    if (typeof obj["stdout"] === "string" && obj["stdout"] !== "")
+        lines.push(`stdout: ${obj["stdout"]}`);
+    if (typeof obj["stderr"] === "string" && obj["stderr"] !== "")
+        lines.push(`stderr: ${obj["stderr"]}`);
+    const rendered = lines.join("\n").trimEnd();
+    return rendered === "" ? null : rendered;
+}
+/** Stamp a guard denial reason with the contract prefix (compose-time helper). */
+export function guardDenyReason(code, message) {
+    return contractError(GUARD_ERROR_PREFIX, code, quoteMessage(message));
+}

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

@@ -0,0 +1,68 @@
+/**
+ * The `run_code` parent broker (`crates/tools/src/run_code.rs:562-978`).
+ *
+ * One `run_code` call = one round trip. The assembled program — TypeScript by
+ * default since W774, Python on request — runs in the sandbox; its sub-calls
+ * arrive as one-line JSON on stdout and the parent answers on stdin after
+ * dispatching each one through the **same** registry pipeline (schema → guards →
+ * execute) the model itself would use. Only `main()`'s return value travels back
+ * as the tool result.
+ *
+ * The protocol is language-neutral (it is byte-identical for both SDKs), so the
+ * language only decides two things: the script file's extension and the
+ * interpreter that runs it.
+ *
+ * Invariants:
+ * - every limit is enforced here, never in the child: the 21st sub-call is
+ *   refused before dispatch, the wall clock is enforced while waiting for a
+ *   line, the sub-call output ledger is charged per reply;
+ * - every infrastructure failure is a structured `run_code: code=… msg="…"`
+ *   (invalid_arg | registry | config | spawn | protocol | timeout | aborted);
+ *   a program exception is that exception's text plus a bounded log tail;
+ * - the child is killed on timeout, on cancel and on protocol failure — never
+ *   left behind — and its script file is removed on every exit path.
+ */
+import type { Sandbox, SessionEvent, ToolExecOutcome, ToolRegistry } from "@celestea/core";
+import { type RunCodeConfig } from "./limits.js";
+import { type RunCodeLanguage } from "./sdk.js";
+/** Session-log sink for sub-call rows (legacy `Fn(SessionEvent)` sink). */
+export type RunCodeEventSink = (event: SessionEvent) => void;
+/** Everything one broker run needs (the tool binds the registry + call id). */
+export interface BrokerContext {
+    sandbox: Sandbox;
+    registry: ToolRegistry;
+    events?: RunCodeEventSink;
+    config: RunCodeConfig;
+    /** The `run_code` call id: sub-call ids are `<parentId>:c<n>`. */
+    parentId: string;
+}
+/**
+ * Absolute interpreter path of a TypeScript program (W774): the Node that runs
+ * THIS process, which is the same binary the sandbox can see (`--ro-bind / /`
+ * mounts the host root read-only) and never depends on the child's PATH.
+ * `/usr/bin/node` is preferred because it is the host's system-wide install;
+ * `process.execPath` is the honest fallback (nvm/volta hosts).
+ *
+ * W885: the constant is kept for compatibility, but the interpreter actually
+ * used is resolved per run (`resolveInterpreter`), which checks the platform
+ * PATH first — `/usr/bin/node` is a POSIX convention that simply does not
+ * exist on Windows (W883 B9/B15).
+ */
+export declare const TS_PROGRAM_RUNTIME: string;
+/** One full run_code round trip: the program's final value + its render. */
+export declare function brokerRun(ctx: BrokerContext, args: unknown): Promise<ToolExecOutcome>;
+/**
+ * The interpreter of one `run_code` program (W885).
+ *
+ * TypeScript runs under the Node that runs THIS process — the one binary the
+ * sandbox is guaranteed to see through `--ro-bind / /` — with the host's PATH
+ * consulted first ONLY when that yields a Node (`node` is `node.exe` on
+ * Windows, and `process.execPath` there is routinely `C:\\Program Files\\…`
+ * with a space in it). Python keeps the historical `python3` on POSIX and
+ * falls back to the names Windows actually ships (`python`, `py`).
+ *
+ * Anything `whichSync` cannot find becomes the bare name, so a missing
+ * interpreter still surfaces as the interpreter's own "not found" instead of a
+ * silent wrong one.
+ */
+export declare function resolveInterpreter(language: RunCodeLanguage, platform?: string, env?: NodeJS.ProcessEnv): string;