@celestea/tools 2.7.1

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

@@ -0,0 +1,69 @@
+/**
+ * Line framing and byte budgets for the `run_code` broker
+ * (`crates/tools/src/run_code.rs:488-560`).
+ *
+ * The child speaks a line protocol on stdout, so the parent needs three things
+ * the sandbox's capped whole-stream captures cannot give it:
+ * - **one `\n`-terminated line at a time, with a deadline** — the wall clock is
+ *   enforced while waiting, not after the stream ends;
+ * - **a per-line byte budget** — an over-long line is drained and dropped, never
+ *   buffered and never parsed as protocol (a truncated JSON line is not JSON);
+ * - **UTF-8 safe cuts** — a budget never splits a multi-byte character, so a
+ *   truncated value or log stays valid text.
+ */
+import type { Readable } from "node:stream";
+import { TIMED_OUT } from "../sandbox/async.js";
+/** One framed stdout line plus whether its byte budget cut it. */
+export interface BoundedLine {
+    text: string;
+    truncated: boolean;
+}
+/**
+ * `\n`-framed reader over a byte stream with a per-line cap and a deadline.
+ * Feed-driven (no async iterators): the broker asks for one line at a time and
+ * always re-arms the *remaining* wall clock, so a silent child cannot stall it.
+ */
+export declare class LineReader {
+    private readonly stream;
+    private readonly maxLineBytes;
+    private readonly queued;
+    private readonly parts;
+    private bytes;
+    private cut;
+    private done;
+    private wake;
+    constructor(stream: Readable | null, maxLineBytes: number);
+    /**
+     * The next complete line, `null` at EOF, or [`TIMED_OUT`] when `remainingMs`
+     * elapses first. A partial tail at EOF is dropped (parity: only
+     * `\n`-terminated lines are protocol candidates).
+     */
+    next(remainingMs: number): Promise<BoundedLine | null | typeof TIMED_OUT>;
+    /** Stop consuming: detach and pause so post-final output is not buffered. */
+    stop(): void;
+    private arrival;
+    private signal;
+    private feed;
+    private push;
+    private complete;
+}
+/**
+ * Decode UTF-8 bytes, dropping a trailing **incomplete** sequence (the budget
+ * cut may land inside a multi-byte character: `"hé"[:3]` must not become
+ * `"h\uFFFD"`).
+ */
+export declare function safeUtf8(buffer: Buffer): string;
+/** UTF-8 safe prefix of `text` at most `maxBytes` bytes long. */
+export declare function utf8Prefix(text: string, maxBytes: number): string;
+/** Serialized size of a value in bytes, or `null` when it is not JSON-able. */
+export declare function jsonByteLength(value: unknown): number | null;
+/** Append up to `maxBytes` of `chunk` to `current` (UTF-8 safe, parity). */
+export declare function appendBounded(current: string, chunk: string, maxBytes: number): BoundedLine;
+/**
+ * Truncate a sub-call result to `budget` serialized bytes: strings keep a
+ * UTF-8 safe prefix; non-strings collapse to a placeholder (there is no
+ * lossless way to cut an object/array). Legacy `truncate_value`.
+ */
+export declare function truncateValue(value: unknown, budget: number): unknown;
+/** The last `maxChars` characters of `text` (failure-message log tail). */
+export declare function tail(text: string, maxChars: number): string;

package/dist/run-code/lines.js

@@ -0,0 +1,199 @@
+/**
+ * Line framing and byte budgets for the `run_code` broker
+ * (`crates/tools/src/run_code.rs:488-560`).
+ *
+ * The child speaks a line protocol on stdout, so the parent needs three things
+ * the sandbox's capped whole-stream captures cannot give it:
+ * - **one `\n`-terminated line at a time, with a deadline** — the wall clock is
+ *   enforced while waiting, not after the stream ends;
+ * - **a per-line byte budget** — an over-long line is drained and dropped, never
+ *   buffered and never parsed as protocol (a truncated JSON line is not JSON);
+ * - **UTF-8 safe cuts** — a budget never splits a multi-byte character, so a
+ *   truncated value or log stays valid text.
+ */
+import { TIMED_OUT } from "../sandbox/async.js";
+const NEWLINE = 0x0a;
+/** Longest UTF-8 sequence (a 4-byte code point) — the cut look-back window. */
+const MAX_UTF8_SEQUENCE = 4;
+/**
+ * `\n`-framed reader over a byte stream with a per-line cap and a deadline.
+ * Feed-driven (no async iterators): the broker asks for one line at a time and
+ * always re-arms the *remaining* wall clock, so a silent child cannot stall it.
+ */
+export class LineReader {
+    stream;
+    maxLineBytes;
+    queued = [];
+    parts = [];
+    bytes = 0;
+    cut = false;
+    done = false;
+    wake = null;
+    constructor(stream, maxLineBytes) {
+        this.stream = stream;
+        this.maxLineBytes = maxLineBytes;
+        if (stream === null) {
+            this.done = true;
+            return;
+        }
+        stream.on("data", (chunk) => {
+            this.feed(typeof chunk === "string" ? Buffer.from(chunk, "utf8") : chunk);
+            this.signal();
+        });
+        const end = () => {
+            this.done = true;
+            this.signal();
+        };
+        stream.on("end", end);
+        stream.on("close", end);
+        stream.on("error", end);
+    }
+    /**
+     * The next complete line, `null` at EOF, or [`TIMED_OUT`] when `remainingMs`
+     * elapses first. A partial tail at EOF is dropped (parity: only
+     * `\n`-terminated lines are protocol candidates).
+     */
+    async next(remainingMs) {
+        const deadline = Date.now() + remainingMs;
+        for (;;) {
+            const line = this.queued.shift();
+            if (line !== undefined)
+                return line;
+            if (this.done)
+                return null;
+            const left = deadline - Date.now();
+            if (left <= 0)
+                return TIMED_OUT;
+            if (!(await this.arrival(left)))
+                return TIMED_OUT;
+        }
+    }
+    /** Stop consuming: detach and pause so post-final output is not buffered. */
+    stop() {
+        this.done = true;
+        if (this.stream === null)
+            return;
+        this.stream.removeAllListeners("data");
+        this.stream.pause();
+    }
+    arrival(ms) {
+        return new Promise((resolve) => {
+            let settled = false;
+            const timer = setTimeout(() => {
+                if (settled)
+                    return;
+                settled = true;
+                this.wake = null;
+                resolve(false);
+            }, ms);
+            this.wake = () => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                this.wake = null;
+                resolve(true);
+            };
+        });
+    }
+    signal() {
+        this.wake?.();
+    }
+    feed(chunk) {
+        let start = 0;
+        for (;;) {
+            const end = chunk.indexOf(NEWLINE, start);
+            if (end === -1) {
+                this.push(chunk.subarray(start));
+                return;
+            }
+            this.push(chunk.subarray(start, end));
+            this.complete();
+            start = end + 1;
+        }
+    }
+    push(segment) {
+        if (this.cut || segment.length === 0)
+            return;
+        const room = this.maxLineBytes - this.bytes;
+        if (segment.length <= room) {
+            this.parts.push(segment);
+            this.bytes += segment.length;
+            return;
+        }
+        this.parts.push(segment.subarray(0, Math.max(room, 0)));
+        this.bytes = this.maxLineBytes;
+        this.cut = true;
+    }
+    complete() {
+        this.queued.push({ text: safeUtf8(Buffer.concat(this.parts)), truncated: this.cut });
+        this.parts.length = 0;
+        this.bytes = 0;
+        this.cut = false;
+    }
+}
+/**
+ * Decode UTF-8 bytes, dropping a trailing **incomplete** sequence (the budget
+ * cut may land inside a multi-byte character: `"hé"[:3]` must not become
+ * `"h\uFFFD"`).
+ */
+export function safeUtf8(buffer) {
+    for (let back = 0; back < MAX_UTF8_SEQUENCE && back < buffer.length; back += 1) {
+        const byte = buffer[buffer.length - 1 - back] ?? 0;
+        if ((byte & 0xc0) === 0x80)
+            continue; // continuation byte: keep looking back
+        if ((byte & 0x80) === 0)
+            return buffer.toString("utf8"); // ASCII tail: complete
+        const need = byte >= 0xf0 ? 4 : byte >= 0xe0 ? 3 : 2;
+        if (back + 1 === need)
+            return buffer.toString("utf8"); // complete code point
+        return buffer.subarray(0, buffer.length - 1 - back).toString("utf8"); // cut inside it
+    }
+    return buffer.toString("utf8");
+}
+/** UTF-8 safe prefix of `text` at most `maxBytes` bytes long. */
+export function utf8Prefix(text, maxBytes) {
+    if (maxBytes <= 0)
+        return "";
+    const bytes = Buffer.from(text, "utf8");
+    return bytes.length <= maxBytes ? text : safeUtf8(bytes.subarray(0, maxBytes));
+}
+/** Serialized size of a value in bytes, or `null` when it is not JSON-able. */
+export function jsonByteLength(value) {
+    let encoded;
+    try {
+        encoded = JSON.stringify(value);
+    }
+    catch {
+        return null;
+    }
+    return encoded === undefined ? null : Buffer.byteLength(encoded, "utf8");
+}
+/** Append up to `maxBytes` of `chunk` to `current` (UTF-8 safe, parity). */
+export function appendBounded(current, chunk, maxBytes) {
+    if (chunk === "")
+        return { text: current, truncated: false };
+    const room = maxBytes - Buffer.byteLength(current, "utf8");
+    const size = Buffer.byteLength(chunk, "utf8");
+    if (size <= room)
+        return { text: current + chunk, truncated: false };
+    return { text: current + utf8Prefix(chunk, Math.max(room, 0)), truncated: true };
+}
+/**
+ * Truncate a sub-call result to `budget` serialized bytes: strings keep a
+ * UTF-8 safe prefix; non-strings collapse to a placeholder (there is no
+ * lossless way to cut an object/array). Legacy `truncate_value`.
+ */
+export function truncateValue(value, budget) {
+    if (typeof value === "string")
+        return utf8Prefix(value, budget);
+    const size = jsonByteLength(value);
+    if (size !== null && size <= budget)
+        return value;
+    return "[run_code] sub-call output exceeded the budget; value dropped";
+}
+/** The last `maxChars` characters of `text` (failure-message log tail). */
+export function tail(text, maxChars) {
+    const chars = [...text];
+    return chars.length <= maxChars ? text : chars.slice(chars.length - maxChars).join("");
+}

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

@@ -0,0 +1,34 @@
+/**
+ * The TypeScript SDK preamble + runner (W774) — split out of `sdk.ts` (which is
+ * the Python parity file and stays at its own size budget).
+ *
+ * Same protocol, same four bridges, but executed by Node's NATIVE type stripping
+ * (`node .celestea/<file>.ts`): no build step, no `node_modules`, no dependency.
+ *
+ * Deliberate differences from the Python preamble (both are pinned by tests):
+ *   - attribute access is native (`r.stdout` and `r["stdout"]` both just work),
+ *     so the Python `_AttrDict` / `_Value` dual-interface wrappers have no
+ *     counterpart;
+ *   - `await tools.read_file(...)` works because awaiting a non-promise value
+ *     returns it unchanged — no awaitable wrapper needed;
+ *   - the reply channel is read SYNCHRONOUSLY with `fs.readSync(0, …)` plus a
+ *     half-line buffer (the equivalent of Python's `sys.stdin.readline()`);
+ *     after EOF a further bridge call THROWS instead of hanging.
+ *
+ * Only ERASABLE TypeScript is allowed in the assembled file (Node strips types,
+ * it never compiles them): no `enum`, no `namespace`, no parameter properties.
+ */
+export declare const RUN_CODE_SDK_TS = "// =============================================================================\n// celestea run_code SDK (W774) - engine-injected preamble (TypeScript).\n// Node standard library only. Runs under `node .celestea/<file>.ts` inside the\n// Celestea execution sandbox; the parent engine (the \"broker\") reads our\n// protocol lines from stdout and writes replies to stdin.\n//\n// Protocol (one JSON object per line, no other framing) - identical to the\n// Python SDK on purpose: the broker is language-neutral.\n//   child -> parent   {\"id\": <int>, \"tool\": \"<name>\", \"args\": {...}}\n//   parent -> child   {\"id\": <int>, \"ok\": true, \"value\": <json>, \"truncated\": <bool>}\n//                     {\"id\": <int>, \"ok\": false, \"error\": \"<message>\"}\n//   child -> parent   {\"__final__\": <json>}      (normal end: main()'s return)\n//                     {\"__error__\": \"<message>\"} (uncaught exception)\n//\n// Contract:\n//   - Write the program as a `function main()` BODY (an indented body is wrapped\n//     for you), or as a complete script that defines main. main() MAY be async:\n//     the harness awaits it. Its resolved value (lossless JSON) is the result.\n//   - `tools.<name>({...})` is a SYNCHRONOUS bridge: every sub-call is dispatched\n//     by the parent through its normal tool pipeline (guards, schema checks,\n//     limits). A failure throws ToolCallError - catch it and continue.\n//     `await tools.<name>({...})` is the same thing (awaiting a value is free).\n//   - Only console.log what the model needs: a line that is not protocol JSON is\n//     a LOG line (budgeted at 64KiB); intermediate results never enter the chat.\n//   - Sub-calls run SERIALLY, one at a time, in request order.\n//   - Exposed tools: read_file / write_file / list_dir / run_shell. Any other\n//     name (including run_code itself) is rejected by the parent.\n//   - TYPE STRIPPING ONLY: this file is executed by Node's native type stripping,\n//     so only ERASABLE TypeScript is allowed - no `enum`, no `namespace`, no\n//     parameter properties, no `declare`. Plain JavaScript always works.\n//   - Do not read process.stdin and do not call process.exit(): stdin is the\n//     protocol reply channel and this harness is the entry point.\n// =============================================================================\nimport { readSync as _readSync } from \"node:fs\";\nimport { StringDecoder as _StringDecoder } from \"node:string_decoder\";\nimport { createRequire as _createRequire } from \"node:module\";\n\n// Models sometimes reach for CommonJS: in an ES module `require` is undefined,\n// so expose the real one (the same resolution rules as this file).\n(globalThis as { require?: unknown }).require ??= _createRequire(import.meta.url);\n\nclass ToolCallError extends Error {\n  readonly toolName: string;\n\n  constructor(toolName: string, message: string) {\n    super(\"tool '\" + toolName + \"' failed: \" + message);\n    this.name = \"ToolCallError\";\n    this.toolName = toolName;\n  }\n}\n\nlet _subCallId = 0;\nlet _pending = \"\";\nlet _eof = false;\nconst _decoder = new _StringDecoder(\"utf8\");\n\n/** Synchronous sleep (only needed if the reply channel is non-blocking). */\nfunction _sleepMs(ms: number): void {\n  try {\n    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);\n  } catch {\n    const until = Date.now() + ms;\n    while (Date.now() < until) {\n      /* last-resort spin: the bridge must never hang */\n    }\n  }\n}\n\n/**\n * Read ONE line from the protocol channel, blocking until it arrives (the\n * equivalent of Python's `sys.stdin.readline()`). Returns null at EOF.\n *\n * The buffer may already hold several lines (the parent writes replies back to\n * back) and one read may split a UTF-8 sequence, which is why bytes go through\n * a StringDecoder rather than `chunk.toString()`. CRLF is accepted.\n */\nfunction _readProtocolLine(): string | null {\n  for (;;) {\n    const nl = _pending.indexOf(\"\\n\");\n    if (nl >= 0) {\n      const line = _pending.slice(0, nl);\n      _pending = _pending.slice(nl + 1);\n      return line.endsWith(\"\\r\") ? line.slice(0, -1) : line;\n    }\n    if (_eof) {\n      // A trailing fragment without a newline is still a line (readline does the\n      // same); only a fully drained buffer means EOF.\n      if (_pending === \"\") return null;\n      const rest = _pending;\n      _pending = \"\";\n      return rest;\n    }\n    const chunk = Buffer.allocUnsafe(65536);\n    let read = 0;\n    try {\n      read = _readSync(0, chunk, 0, chunk.length, null);\n    } catch (error) {\n      if ((error as NodeJS.ErrnoException).code === \"EAGAIN\") {\n        _sleepMs(5); // non-blocking stdin: wait, then retry (never fail the call)\n        continue;\n      }\n      throw new ToolCallError(\"protocol\", \"cannot read the reply channel: \" + String((error as Error).message));\n    }\n    if (read === 0) {\n      _eof = true;\n      _pending += _decoder.end();\n      continue;\n    }\n    _pending += _decoder.write(chunk.subarray(0, read));\n  }\n}\n\n/** One bridge call: request line out, reply line in, value or ToolCallError. */\nfunction _bridgeCall(tool: string, args: unknown): unknown {\n  const requestId = ++_subCallId;\n  let payload: string;\n  try {\n    payload = JSON.stringify({ id: requestId, tool: tool, args: args === undefined ? {} : args });\n  } catch (error) {\n    throw new ToolCallError(tool, \"arguments are not JSON-serializable: \" + String((error as Error).message));\n  }\n  process.stdout.write(payload + \"\\n\");\n  const line = _readProtocolLine();\n  if (line === null) {\n    throw new ToolCallError(tool, \"the parent broker closed the reply channel (run aborted)\");\n  }\n  let reply: Record<string, unknown>;\n  try {\n    const decoded: unknown = JSON.parse(line);\n    if (typeof decoded !== \"object\" || decoded === null || Array.isArray(decoded)) {\n      throw new Error(\"reply is not a JSON object\");\n    }\n    reply = decoded as Record<string, unknown>;\n  } catch (error) {\n    throw new ToolCallError(tool, \"malformed reply from the parent broker: \" + String((error as Error).message));\n  }\n  if (reply[\"id\"] !== requestId) {\n    throw new ToolCallError(tool, \"reply id mismatch (expected \" + requestId + \", got \" + String(reply[\"id\"]) + \")\");\n  }\n  if (reply[\"ok\"] !== true) {\n    const message = typeof reply[\"error\"] === \"string\" ? (reply[\"error\"] as string) : \"unknown error\";\n    throw new ToolCallError(tool, message);\n  }\n  return reply[\"value\"] === undefined ? null : reply[\"value\"];\n}\n\n/** Canonical single-argument name per bridged tool (for the positional shortcut). */\nconst _primaryArg: Record<string, string> = {\n  read_file: \"path\",\n  write_file: \"path\",\n  list_dir: \"path\",\n  run_shell: \"command\",\n};\n\n/**\n * Both call styles work: the documented object form\n * (`tools.read_file({ path: ... })`) and the positional shorthand models write\n * anyway (`tools.read_file(\"x\")`, `tools.write_file(\"x\", \"content\")`).\n */\nfunction _mergeArgs(tool: string, received: readonly unknown[]): Record<string, unknown> {\n  const first = received[0];\n  const second = received[1];\n  if (typeof first === \"string\") {\n    const args: Record<string, unknown> = {};\n    args[_primaryArg[tool] as string] = first;\n    if (tool === \"write_file\" && typeof second === \"string\") args[\"content\"] = second;\n    return args;\n  }\n  if (first === undefined) return {};\n  if (typeof first !== \"object\" || first === null || Array.isArray(first)) {\n    throw new ToolCallError(\n      tool,\n      \"expected an arguments object, e.g. tools.\" + tool + \"({ \" + (_primaryArg[tool] as string) + \": ... })\",\n    );\n  }\n  const args: Record<string, unknown> = { ...(first as Record<string, unknown>) };\n  if (tool === \"write_file\" && typeof second === \"string\") args[\"content\"] = second;\n  return args;\n}\n\nclass _Tools {\n  read_file(...args: unknown[]): unknown {\n    return _bridgeCall(\"read_file\", _mergeArgs(\"read_file\", args));\n  }\n\n  write_file(...args: unknown[]): unknown {\n    return _bridgeCall(\"write_file\", _mergeArgs(\"write_file\", args));\n  }\n\n  list_dir(...args: unknown[]): unknown {\n    return _bridgeCall(\"list_dir\", _mergeArgs(\"list_dir\", args));\n  }\n\n  run_shell(...args: unknown[]): unknown {\n    // The full result object: {\"exit_code\", \"stdout\", \"stderr\", ...}.\n    return _bridgeCall(\"run_shell\", _mergeArgs(\"run_shell\", args));\n  }\n}\n\nconst tools = new _Tools();\n";
+/**
+ * The TypeScript runner appended after the user program (W774).
+ *
+ * Python parity, line for line: run `main()`, await it, emit `{__final__: …}`;
+ * on any failure print the stack (the traceback equivalent) and then
+ * `{__error__: "<Name>: <message>"}`, and exit 1. `undefined` becomes `null`
+ * because `JSON.stringify` drops `undefined`, while Python's `main()` returning
+ * None reports `{"__final__": null}` — the broker must see the same shape.
+ *
+ * `process.exitCode` is set instead of calling `process.exit()`: the protocol
+ * line is written to a PIPE, and an immediate exit can truncate it.
+ */
+export declare const RUN_CODE_RUNNER_TS = "\n// ======================= harness entry point (injected) =======================\nfunction _celesteaErrorLine(error: unknown): string {\n  const named = error as { name?: unknown; message?: unknown };\n  const name = typeof named?.name === \"string\" ? named.name : \"Error\";\n  const message = named?.message === undefined ? String(error) : String(named.message);\n  return name + \": \" + message;\n}\n\nfunction _celesteaFail(error: unknown): void {\n  const stacked = error as { stack?: unknown };\n  const text = typeof stacked?.stack === \"string\" ? stacked.stack : _celesteaErrorLine(error);\n  for (const line of text.split(\"\\n\")) process.stdout.write(line + \"\\n\");\n  process.stdout.write(JSON.stringify({ __error__: _celesteaErrorLine(error) }) + \"\\n\");\n  process.exitCode = 1;\n}\n\nasync function _celesteaRunMain(): Promise<unknown> {\n  // `typeof` on an undeclared identifier is safe, so a program without main()\n  // gets a clear message instead of a ReferenceError.\n  const entry: unknown = typeof main === \"function\" ? main : undefined;\n  if (entry === undefined) {\n    throw new Error(\n      \"run_code: no 'main' defined - write the program as a function body, or as a \" +\n        \"complete script defining function main() (it may be async)\",\n    );\n  }\n  return await (entry as () => unknown)();\n}\n\n_celesteaRunMain().then(\n  function (value: unknown): void {\n    try {\n      process.stdout.write(JSON.stringify({ __final__: value === undefined ? null : value }) + \"\\n\");\n    } catch (error) {\n      _celesteaFail(error);\n    }\n  },\n  function (error: unknown): void {\n    _celesteaFail(error);\n  },\n);\n";

package/dist/run-code/sdk-ts.js

@@ -0,0 +1,276 @@
+/**
+ * The TypeScript SDK preamble + runner (W774) — split out of `sdk.ts` (which is
+ * the Python parity file and stays at its own size budget).
+ *
+ * Same protocol, same four bridges, but executed by Node's NATIVE type stripping
+ * (`node .celestea/<file>.ts`): no build step, no `node_modules`, no dependency.
+ *
+ * Deliberate differences from the Python preamble (both are pinned by tests):
+ *   - attribute access is native (`r.stdout` and `r["stdout"]` both just work),
+ *     so the Python `_AttrDict` / `_Value` dual-interface wrappers have no
+ *     counterpart;
+ *   - `await tools.read_file(...)` works because awaiting a non-promise value
+ *     returns it unchanged — no awaitable wrapper needed;
+ *   - the reply channel is read SYNCHRONOUSLY with `fs.readSync(0, …)` plus a
+ *     half-line buffer (the equivalent of Python's `sys.stdin.readline()`);
+ *     after EOF a further bridge call THROWS instead of hanging.
+ *
+ * Only ERASABLE TypeScript is allowed in the assembled file (Node strips types,
+ * it never compiles them): no `enum`, no `namespace`, no parameter properties.
+ */
+export const RUN_CODE_SDK_TS = `// =============================================================================
+// celestea run_code SDK (W774) - engine-injected preamble (TypeScript).
+// Node standard library only. Runs under \`node .celestea/<file>.ts\` inside the
+// Celestea execution sandbox; the parent engine (the "broker") reads our
+// protocol lines from stdout and writes replies to stdin.
+//
+// Protocol (one JSON object per line, no other framing) - identical to the
+// Python SDK on purpose: the broker is language-neutral.
+//   child -> parent   {"id": <int>, "tool": "<name>", "args": {...}}
+//   parent -> child   {"id": <int>, "ok": true, "value": <json>, "truncated": <bool>}
+//                     {"id": <int>, "ok": false, "error": "<message>"}
+//   child -> parent   {"__final__": <json>}      (normal end: main()'s return)
+//                     {"__error__": "<message>"} (uncaught exception)
+//
+// Contract:
+//   - 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:
+//     the harness awaits it. Its resolved value (lossless JSON) is the result.
+//   - \`tools.<name>({...})\` is a SYNCHRONOUS bridge: every sub-call is dispatched
+//     by the parent through its normal tool pipeline (guards, schema checks,
+//     limits). A failure throws ToolCallError - catch it and continue.
+//     \`await tools.<name>({...})\` is the same thing (awaiting a value is free).
+//   - Only console.log what the model needs: a line that is not protocol JSON is
+//     a LOG line (budgeted at 64KiB); intermediate results never enter the chat.
+//   - Sub-calls run SERIALLY, one at a time, in request order.
+//   - Exposed tools: read_file / write_file / list_dir / run_shell. Any other
+//     name (including run_code itself) is rejected by the parent.
+//   - TYPE STRIPPING ONLY: this file is executed by Node's native type stripping,
+//     so only ERASABLE TypeScript is allowed - no \`enum\`, no \`namespace\`, no
+//     parameter properties, no \`declare\`. Plain JavaScript always works.
+//   - Do not read process.stdin and do not call process.exit(): stdin is the
+//     protocol reply channel and this harness is the entry point.
+// =============================================================================
+import { readSync as _readSync } from "node:fs";
+import { StringDecoder as _StringDecoder } from "node:string_decoder";
+import { createRequire as _createRequire } from "node:module";
+
+// Models sometimes reach for CommonJS: in an ES module \`require\` is undefined,
+// so expose the real one (the same resolution rules as this file).
+(globalThis as { require?: unknown }).require ??= _createRequire(import.meta.url);
+
+class ToolCallError extends Error {
+  readonly toolName: string;
+
+  constructor(toolName: string, message: string) {
+    super("tool '" + toolName + "' failed: " + message);
+    this.name = "ToolCallError";
+    this.toolName = toolName;
+  }
+}
+
+let _subCallId = 0;
+let _pending = "";
+let _eof = false;
+const _decoder = new _StringDecoder("utf8");
+
+/** Synchronous sleep (only needed if the reply channel is non-blocking). */
+function _sleepMs(ms: number): void {
+  try {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+  } catch {
+    const until = Date.now() + ms;
+    while (Date.now() < until) {
+      /* last-resort spin: the bridge must never hang */
+    }
+  }
+}
+
+/**
+ * Read ONE line from the protocol channel, blocking until it arrives (the
+ * equivalent of Python's \`sys.stdin.readline()\`). Returns null at EOF.
+ *
+ * The buffer may already hold several lines (the parent writes replies back to
+ * back) and one read may split a UTF-8 sequence, which is why bytes go through
+ * a StringDecoder rather than \`chunk.toString()\`. CRLF is accepted.
+ */
+function _readProtocolLine(): string | null {
+  for (;;) {
+    const nl = _pending.indexOf("\\n");
+    if (nl >= 0) {
+      const line = _pending.slice(0, nl);
+      _pending = _pending.slice(nl + 1);
+      return line.endsWith("\\r") ? line.slice(0, -1) : line;
+    }
+    if (_eof) {
+      // A trailing fragment without a newline is still a line (readline does the
+      // same); only a fully drained buffer means EOF.
+      if (_pending === "") return null;
+      const rest = _pending;
+      _pending = "";
+      return rest;
+    }
+    const chunk = Buffer.allocUnsafe(65536);
+    let read = 0;
+    try {
+      read = _readSync(0, chunk, 0, chunk.length, null);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "EAGAIN") {
+        _sleepMs(5); // non-blocking stdin: wait, then retry (never fail the call)
+        continue;
+      }
+      throw new ToolCallError("protocol", "cannot read the reply channel: " + String((error as Error).message));
+    }
+    if (read === 0) {
+      _eof = true;
+      _pending += _decoder.end();
+      continue;
+    }
+    _pending += _decoder.write(chunk.subarray(0, read));
+  }
+}
+
+/** One bridge call: request line out, reply line in, value or ToolCallError. */
+function _bridgeCall(tool: string, args: unknown): unknown {
+  const requestId = ++_subCallId;
+  let payload: string;
+  try {
+    payload = JSON.stringify({ id: requestId, tool: tool, args: args === undefined ? {} : args });
+  } catch (error) {
+    throw new ToolCallError(tool, "arguments are not JSON-serializable: " + String((error as Error).message));
+  }
+  process.stdout.write(payload + "\\n");
+  const line = _readProtocolLine();
+  if (line === null) {
+    throw new ToolCallError(tool, "the parent broker closed the reply channel (run aborted)");
+  }
+  let reply: Record<string, unknown>;
+  try {
+    const decoded: unknown = JSON.parse(line);
+    if (typeof decoded !== "object" || decoded === null || Array.isArray(decoded)) {
+      throw new Error("reply is not a JSON object");
+    }
+    reply = decoded as Record<string, unknown>;
+  } catch (error) {
+    throw new ToolCallError(tool, "malformed reply from the parent broker: " + String((error as Error).message));
+  }
+  if (reply["id"] !== requestId) {
+    throw new ToolCallError(tool, "reply id mismatch (expected " + requestId + ", got " + String(reply["id"]) + ")");
+  }
+  if (reply["ok"] !== true) {
+    const message = typeof reply["error"] === "string" ? (reply["error"] as string) : "unknown error";
+    throw new ToolCallError(tool, message);
+  }
+  return reply["value"] === undefined ? null : reply["value"];
+}
+
+/** Canonical single-argument name per bridged tool (for the positional shortcut). */
+const _primaryArg: Record<string, string> = {
+  read_file: "path",
+  write_file: "path",
+  list_dir: "path",
+  run_shell: "command",
+};
+
+/**
+ * Both call styles work: the documented object form
+ * (\`tools.read_file({ path: ... })\`) and the positional shorthand models write
+ * anyway (\`tools.read_file("x")\`, \`tools.write_file("x", "content")\`).
+ */
+function _mergeArgs(tool: string, received: readonly unknown[]): Record<string, unknown> {
+  const first = received[0];
+  const second = received[1];
+  if (typeof first === "string") {
+    const args: Record<string, unknown> = {};
+    args[_primaryArg[tool] as string] = first;
+    if (tool === "write_file" && typeof second === "string") args["content"] = second;
+    return args;
+  }
+  if (first === undefined) return {};
+  if (typeof first !== "object" || first === null || Array.isArray(first)) {
+    throw new ToolCallError(
+      tool,
+      "expected an arguments object, e.g. tools." + tool + "({ " + (_primaryArg[tool] as string) + ": ... })",
+    );
+  }
+  const args: Record<string, unknown> = { ...(first as Record<string, unknown>) };
+  if (tool === "write_file" && typeof second === "string") args["content"] = second;
+  return args;
+}
+
+class _Tools {
+  read_file(...args: unknown[]): unknown {
+    return _bridgeCall("read_file", _mergeArgs("read_file", args));
+  }
+
+  write_file(...args: unknown[]): unknown {
+    return _bridgeCall("write_file", _mergeArgs("write_file", args));
+  }
+
+  list_dir(...args: unknown[]): unknown {
+    return _bridgeCall("list_dir", _mergeArgs("list_dir", args));
+  }
+
+  run_shell(...args: unknown[]): unknown {
+    // The full result object: {"exit_code", "stdout", "stderr", ...}.
+    return _bridgeCall("run_shell", _mergeArgs("run_shell", args));
+  }
+}
+
+const tools = new _Tools();
+`;
+/**
+ * The TypeScript runner appended after the user program (W774).
+ *
+ * Python parity, line for line: run `main()`, await it, emit `{__final__: …}`;
+ * on any failure print the stack (the traceback equivalent) and then
+ * `{__error__: "<Name>: <message>"}`, and exit 1. `undefined` becomes `null`
+ * because `JSON.stringify` drops `undefined`, while Python's `main()` returning
+ * None reports `{"__final__": null}` — the broker must see the same shape.
+ *
+ * `process.exitCode` is set instead of calling `process.exit()`: the protocol
+ * line is written to a PIPE, and an immediate exit can truncate it.
+ */
+export const RUN_CODE_RUNNER_TS = `
+// ======================= harness entry point (injected) =======================
+function _celesteaErrorLine(error: unknown): string {
+  const named = error as { name?: unknown; message?: unknown };
+  const name = typeof named?.name === "string" ? named.name : "Error";
+  const message = named?.message === undefined ? String(error) : String(named.message);
+  return name + ": " + message;
+}
+
+function _celesteaFail(error: unknown): void {
+  const stacked = error as { stack?: unknown };
+  const text = typeof stacked?.stack === "string" ? stacked.stack : _celesteaErrorLine(error);
+  for (const line of text.split("\\n")) process.stdout.write(line + "\\n");
+  process.stdout.write(JSON.stringify({ __error__: _celesteaErrorLine(error) }) + "\\n");
+  process.exitCode = 1;
+}
+
+async function _celesteaRunMain(): Promise<unknown> {
+  // \`typeof\` on an undeclared identifier is safe, so a program without main()
+  // gets a clear message instead of a ReferenceError.
+  const entry: unknown = typeof main === "function" ? main : undefined;
+  if (entry === undefined) {
+    throw new Error(
+      "run_code: no 'main' defined - write the program as a function body, or as a " +
+        "complete script defining function main() (it may be async)",
+    );
+  }
+  return await (entry as () => unknown)();
+}
+
+_celesteaRunMain().then(
+  function (value: unknown): void {
+    try {
+      process.stdout.write(JSON.stringify({ __final__: value === undefined ? null : value }) + "\\n");
+    } catch (error) {
+      _celesteaFail(error);
+    }
+  },
+  function (error: unknown): void {
+    _celesteaFail(error);
+  },
+);
+`;

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

@@ -0,0 +1,39 @@
+/**
+ * The engine-injected Python SDK preamble + runner (W255).
+ *
+ * Byte-for-byte port of `RUN_CODE_SDK` / `RUN_CODE_RUNNER` in
+ * `crates/tools/src/run_code.rs` (the raw strings are re-encoded here as
+ * escape-safe template literals; `run-code/sdk.test.ts` re-extracts the
+ * blocks and diffs them, so drift cannot hide).
+ *
+ * The program the broker actually runs is `SDK + user code + RUNNER`:
+ *   - the SDK exposes exactly one object `tools` (four synchronous bridges) and
+ *     the catchable `ToolCallError`; every bridge call is a one-line JSON
+ *     request on stdout, answered by the parent on stdin;
+ *   - the runner calls `main()` (awaiting it when it is a coroutine) and emits
+ *     `{"__final__": <json>}` — or `{"__error__": "<Type>: <msg>"}` after
+ *     printing the traceback, exiting 1.
+ */
+/** The runner appended after the user program. */
+export declare const RUN_CODE_RUNNER = "\n# ======================= harness entry point (injected) =======================\ndef _plain(v):\n    \"\"\"Unwrap dual-interface results before JSON serialization (dict/list deep).\"\"\"\n    if isinstance(v, _Value):\n        v = v._v\n    if isinstance(v, dict):\n        return {k: _plain(x) for k, x in v.items()}\n    if isinstance(v, (list, tuple)):\n        return [_plain(x) for x in v]\n    return v\n\n\nimport asyncio as _asyncio\n\n\ndef _celestea_run_main():\n    main = globals().get(\"main\")\n    if main is None:\n        raise RuntimeError(\n            \"run_code: no 'main' defined - write the program as an async \"\n            \"function body, or as a complete script defining async def main()\"\n        )\n    result = main()\n    if _asyncio.iscoroutine(result):\n        result = _asyncio.run(result)\n    return result\n\n\ntry:\n    _final_value = _celestea_run_main()\n    print(_json.dumps({\"__final__\": _plain(_final_value)}, ensure_ascii=False), flush=True)\nexcept BaseException as _exc:  # report ANY failure as __error__\n    _tb = _traceback.format_exc()\n    for _line in _tb.rstrip(\"\\n\").split(\"\\n\"):\n        print(_line, flush=True)\n    print(\n        _json.dumps({\"__error__\": f\"{type(_exc).__name__}: {_exc}\"}, ensure_ascii=False),\n        flush=True,\n    )\n    _sys.exit(1)\n";
+export { RUN_CODE_RUNNER_TS, RUN_CODE_SDK_TS } from "./sdk-ts.js";
+/** The SDK preamble (standard library only; zero pip). */
+export declare const RUN_CODE_SDK = "# =============================================================================\n# celestea run_code SDK (W255 P0) - engine-injected preamble. Standard library\n# only (zero pip). Runs under `python3 -uB <file>` inside the Celestea\n# execution sandbox; the parent engine (the \"broker\") reads our protocol lines\n# from stdout and writes replies to stdin.\n#\n# Protocol (one JSON object per line, no other framing):\n#   child -> parent   {\"id\": <int>, \"tool\": \"<name>\", \"args\": {...}}\n#   parent -> child   {\"id\": <int>, \"ok\": true, \"value\": <json>, \"truncated\": <bool>}\n#                     {\"id\": <int>, \"ok\": false, \"error\": \"<message>\"}\n#   child -> parent   {\"__final__\": <json>}      (normal end: main()'s return)\n#                     {\"__error__\": \"<message>\"} (uncaught exception)\n#\n# Contract:\n#   - Write the program as an `async def main():` FUNCTION BODY, or as a\n#     complete script that defines main. main()'s return value (lossless JSON)\n#     is the final result of the run.\n#   - `tools.<name>(**args)` (also `tools.<name>({\"path\": ...})`) is a\n#     SYNCHRONOUS bridge: every sub-call is dispatched by the parent through\n#     its normal tool pipeline (guards, schema checks, limits). A failure\n#     raises ToolCallError - catch it and continue.\n#   - Only print what the model needs (stdout logs are budgeted at 64KiB);\n#     intermediate tool results never enter the conversation automatically.\n#   - Sub-calls run SERIALLY in P0: Python-side concurrency (the Promise.all\n#     equivalent for independent read-only calls) is a documented follow-up.\n#   - Exposed tools: read_file / write_file / list_dir / run_shell. Any other\n#     name (including run_code itself) is rejected by the parent.\n#   - Do not read sys.stdin and do not add an `if __name__ == \"__main__\"`\n#     block: stdin is the protocol reply channel and this harness is the\n#     entry point.\n# =============================================================================\nimport sys as _sys\nimport json as _json\nimport traceback as _traceback\n\n\nclass ToolCallError(Exception):\n    \"\"\"A bridged tool call failed (guard denial, unknown tool, dispatch\n    error, limit exceeded). Catchable: the program may recover and continue.\"\"\"\n\n    def __init__(self, tool_name, message):\n        super().__init__(f\"tool '{tool_name}' failed: {message}\")\n        self.tool_name = tool_name\n\n\n_sub_call_id = 0\n\n\ndef _bridge_call(tool, args):\n    global _sub_call_id\n    _sub_call_id += 1\n    request_id = _sub_call_id\n    try:\n        payload = _json.dumps(\n            {\"id\": request_id, \"tool\": tool, \"args\": args}, ensure_ascii=False\n        )\n    except (TypeError, ValueError) as exc:\n        raise ToolCallError(tool, f\"arguments are not JSON-serializable: {exc}\")\n    print(payload, flush=True)\n    line = _sys.stdin.readline()\n    if not line:\n        raise ToolCallError(tool, \"the parent broker closed the reply channel (run aborted)\")\n    try:\n        reply = _json.loads(line)\n    except ValueError as exc:\n        raise ToolCallError(tool, f\"malformed reply from the parent broker: {exc}\")\n    if reply.get(\"id\") != request_id:\n        raise ToolCallError(\n            tool, f\"reply id mismatch (expected {request_id}, got {reply.get('id')})\"\n        )\n    if not reply.get(\"ok\", False):\n        raise ToolCallError(tool, reply.get(\"error\", \"unknown error\"))\n    return _Value(_attr(reply.get(\"value\")))\n\n\nclass _AttrDict(dict):\n    \"\"\"dict whose keys are also attributes: s.stdout == s['stdout'].\n    Models write both styles; both must work, including AFTER `await`.\"\"\"\n\n    def __getattr__(self, name):\n        try:\n            return self[name]\n        except KeyError:\n            raise AttributeError(name)\n\n\ndef _attr(v):\n    \"\"\"Recursively convert decoded JSON dicts/lists so every dict in a tool\n    result is an _AttrDict (attribute access everywhere, at any depth).\"\"\"\n    if isinstance(v, dict):\n        return _AttrDict({k: _attr(x) for k, x in v.items()})\n    if isinstance(v, list):\n        return [_attr(x) for x in v]\n    return v\n\n\nclass _Value:\n    \"\"\"Dual-interface tool result: usable directly (indexing/iteration/str)\n    AND awaitable. Models write both styles \u2014 `await tools.list_dir(...)`\n    and `tools.list_dir(...)` must behave identically.\"\"\"\n\n    def __init__(self, v):\n        self._v = v\n\n    def __await__(self):\n        # Correct awaitable protocol: yield NOTHING and RETURN the value.\n        # (Yielding the value itself makes asyncio treat it as an awaitable\n        #  and dict/list results blow up with \"Task got bad yield\".)\n        if False:\n            yield\n        return self._v\n\n    def __iter__(self):\n        return iter(self._v)\n\n    def __getitem__(self, k):\n        return self._v[k]\n\n    def __len__(self):\n        return len(self._v)\n\n    def __bool__(self):\n        return bool(self._v)\n\n    def __str__(self):\n        return str(self._v)\n\n    def __repr__(self):\n        return repr(self._v)\n\n    def __eq__(self, other):\n        if isinstance(other, _Value):\n            other = other._v\n        return self._v == other\n\n    def get(self, *a, **k):\n        return self._v.get(*a, **k) if hasattr(self._v, \"get\") else None\n\n    def __getattr__(self, name):\n        # Method passthrough (splitlines, keys, ...) so the wrapper behaves\n        # exactly like the wrapped value in normal code paths.\n        return getattr(self._v, name)\n\n\ndef _merge_args(positional, kwargs, tool):\n    if positional:\n        if len(positional) == 1 and isinstance(positional[0], dict):\n            merged = dict(positional[0])\n            merged.update(kwargs)\n            return merged\n        raise ToolCallError(tool, \"expected a single dict argument and/or keyword arguments\")\n    return dict(kwargs)\n\n\nclass _Tools:\n    \"\"\"The SDK tool surface: only these four tools are bridged to the parent\n    (read_file / write_file / list_dir / run_shell).\"\"\"\n\n    def read_file(self, *args, **kwargs):\n        return _bridge_call(\"read_file\", _merge_args(args, kwargs, \"read_file\"))\n\n    def write_file(self, *args, **kwargs):\n        return _bridge_call(\"write_file\", _merge_args(args, kwargs, \"write_file\"))\n\n    def list_dir(self, *args, **kwargs):\n        return _bridge_call(\"list_dir\", _merge_args(args, kwargs, \"list_dir\"))\n\n    def run_shell(self, *args, **kwargs):\n        # Returns the full result dict: {\"exit_code\", \"stdout\", \"stderr\", ...}.\n        # Fields are readable both ways: s['stdout'] AND s.stdout, before or\n        # after `await` (results are _AttrDict at any depth).\n        return _bridge_call(\"run_shell\", _merge_args(args, kwargs, \"run_shell\"))\n\n\ntools = _Tools()\n";
+/** The two languages `run_code` can run (W774: TypeScript is the default). */
+export type RunCodeLanguage = "typescript" | "python";
+/** What `run_code` runs when the call omits `language`. */
+export declare const DEFAULT_RUN_CODE_LANGUAGE: RunCodeLanguage;
+/**
+ * Assemble the program file for one language: SDK preamble + user code + runner.
+ *
+ * When the first non-blank line of the user code is indented it is treated as a
+ * **function body** and wrapped (`async def main():` / `async function main()`);
+ * otherwise it must be a complete script defining `main` itself (legacy
+ * `assemble_program`). The Python path is byte-for-byte what it always was; the
+ * TypeScript path lays the file out the same way and deliberately does NOT
+ * re-indent a wrapped body — JavaScript does not need it, and re-indenting would
+ * rewrite the contents of a template literal.
+ */
+export declare function assembleProgram(userCode: string, language: RunCodeLanguage): string;
+/** True when the first non-blank line starts with whitespace (body form). */
+export declare function firstNonblankLineIndented(code: string): boolean;