@hydraharness/harness-code-runtime-python 0.1.1-rc.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,27 @@
+# @hydraharness/harness-code-runtime-python
+
+CPython-subprocess implementation of the [`@hydraharness/harness-code-runtime`](../code-runtime/README.md) seam. Companion to [`@hydraharness/harness-code-runtime-worker-thread`](../code-runtime-worker-thread/README.md); trades the Node worker thread for a fresh `python3` subprocess so model code is Python instead of TypeScript.
+
+The package owns the wire protocol for that seam: the host-side frame codec and the Python-side mirror of the same message vocabulary.
+
+## Wire protocol
+
+The host and the CPython subprocess exchange a versionless, JSON-lines protocol on the child's fd 3 — one JSON object per line, leaving stdout/stderr free for the program's own output. `src/protocol.ts` is the host side; `py/protocol.py` mirrors its message shapes and the shared truncation-marker text on the Python side.
+
+- **fd 3, not stdout** — Node pins the channel positionally with `stdio: ['pipe','pipe','pipe','pipe']`; the Python bootstrap reads the same `PROTOCOL_FD` constant. JSON-lines framing.
+- **Host treats every inbound frame as hostile** — model code has full access to fd 3 and can post anything through it, so `validateChildFrame` shape-validates and REBUILDS each frame before the host reads it: forged extra fields never ride along, a non-number call id can never be echoed into a reply, and junk drops to `undefined` rather than throwing in the host's message handler. The Python side trusts host replies (the host is not model-controlled).
+- **Lossless-JSON crossing** — completion values and binding arguments cross as exact JSON. `encodeJsonPlain` serializes a `JSON.parse`-produced value without recursion, so a deep value below the byte budget crosses intact instead of dying on `JSON.stringify`'s stack limit; `checkDoneValue` meters a forged completion value's byte length AND number losslessness in one traversal that rejects an over-budget payload before the incremental work it would add (the enqueued children; strings and keys are metered by a non-allocating escaped-size scan, so the escaped copy is never materialized) — the frame's own width is already parsed and capped upstream by the host's fd-3 receive buffer, not re-bounded here; `hasUnsafeIntegerToken` reads the raw frame text to catch an integer token that `JSON.parse` would silently round; `hasNonLosslessNumber` rejects a non-finite or negative-zero number in unbounded `call.args`. Beyond-safe-range integral doubles serialize through `BigInt` digits so the exact integer crosses, not the rounded `String()` form.
+- **Shared truncation marker** — `logTruncationMarker(maxBytes)` produces byte-identical text on both sides, so a truncated log run reads the same however the cap was hit. The `log` frame's `truncated` flag distinguishes the child ledger's own marker from program output.
+
+## Model Experience
+
+Indirectly, through Code Mode in [`@hydraharness/harness-tools`](../../core/tools/README.md), which renders this backend's exact completion value when it fits (or an explicit `invalid-output` / `output-limit` failure), plus the exact `[@hydraharness/harness-code-runtime-python] log capture truncated at <maxLogBytes> bytes` log marker, into a retained `run_code` result.
+
+#### KV Cache effect
+
+No direct invalidation; the named consumer owns any request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+- **The cross-language guard covers the runtime-executed surfaces and the frame field shapes** — `tests/protocol-mirror.e2e.ts` spawns a real `python3` and asserts, against `src/protocol.ts`, both `PROTOCOL_FD` / the log truncation marker text AND each `TypedDict`'s required/optional wire field set in `py/protocol.py`. What it does not compare is the field *types* (e.g. that `cpuSeconds` is an `int` on both sides): comparing type declarations across TypeScript and Python has no mechanical equivalent here, so a type-level drift is still caught by review plus the backend's real-subprocess suite rather than this package's tests.
+- **`src/index.ts` exports the protocol vocabulary only** — the package carries no subprocess execution path and no Python-side JSON codec, so nothing here spawns `python3` outside the mirror test.

package/lib/index.js

@@ -0,0 +1,413 @@
+Object.fromEntries(Object.entries({
+	BootMessage: {
+		type: "required",
+		cpuSeconds: "required",
+		addressSpaceBytes: "required",
+		maxLogBytes: "required",
+		maxValueBytes: "required",
+		namespaces: "required"
+	},
+	Namespace: {
+		global: "required",
+		names: "required",
+		errorClass: "optional"
+	},
+	RunMessage: {
+		type: "required",
+		program: "required"
+	},
+	BootAckMessage: { type: "required" },
+	CallMessage: {
+		type: "required",
+		id: "required",
+		global: "required",
+		name: "required",
+		args: "required"
+	},
+	LogMessage: {
+		type: "required",
+		text: "required",
+		truncated: "optional"
+	},
+	DoneErrorField: {
+		kind: "required",
+		message: "required"
+	},
+	DoneMessage: {
+		type: "required",
+		value: "optional",
+		error: "optional"
+	},
+	ErrorClass: {
+		name: "required",
+		memberNameProperty: "required"
+	},
+	ReplyOk: {
+		type: "required",
+		id: "required",
+		ok: "required",
+		value: "required"
+	},
+	ReplyErr: {
+		type: "required",
+		id: "required",
+		ok: "required",
+		message: "required"
+	}
+}).map(([frame, roles]) => {
+	return [frame, {
+		required: Object.keys(roles).filter((key) => roles[key] === "required").sort(),
+		optional: Object.keys(roles).filter((key) => roles[key] === "optional").sort()
+	}];
+}));
+/**
+* The in-band marker text announcing that log capture stopped at the byte
+* budget. Shared wire vocabulary: the Python-side LogBuffer emits it when ITS
+* ledger exhausts, and the host emits identical text when its own ledger drops
+* a frame first (forged fd-3 traffic, stray stdout bytes) — a truncated run
+* reads the same however the cap was hit.
+* @param maxBytes - the configured `maxLogBytes` the marker names.
+* @returns the marker line.
+*/
+function logTruncationMarker(maxBytes) {
+	return `[hydra-code-runtime-python] log capture truncated at ${maxBytes} bytes`;
+}
+/**
+* Serialize one JSON-parse-produced value without recursion. `JSON.stringify`
+* recurses per nesting level and throws `RangeError` a few thousand levels
+* deep, but the seam's `CodeJsonValue` has no depth limit — an honest deep
+* completion or binding resolution below the byte budget must cross intact
+* (the worker backend's wire is equally stack-safe). Callers must pass a value
+* produced by `JSON.parse` (or equally JSON-plain): only `null`, finite
+* numbers, booleans, strings, dense arrays, and plain objects — this encoder
+* validates nothing. Output matches compact `JSON.stringify` byte for byte
+* EXCEPT on an integral double beyond the safe range, where {@link scalarJson}
+* emits the exact integer's BigInt digits rather than `JSON.stringify`'s rounded
+* spelling (`1152921504606846976`, not `...847000`) so the seam's lossless-JSON
+* promise holds across the wire.
+* @param value - a JSON-plain value (e.g. straight from `JSON.parse`).
+* @returns the compact JSON encoding.
+*/
+function encodeJsonPlain(value) {
+	const chunks = [];
+	const tasks = [{ value }];
+	for (let task = tasks.pop(); task !== void 0; task = tasks.pop()) {
+		if ("text" in task) {
+			chunks.push(task.text);
+			continue;
+		}
+		const current = task.value;
+		if (typeof current === "string") chunks.push(JSON.stringify(current));
+		else if (Array.isArray(current)) {
+			chunks.push("[");
+			tasks.push({ text: "]" });
+			for (let index = current.length - 1; index >= 0; index--) {
+				if (index < current.length - 1) tasks.push({ text: "," });
+				tasks.push({ value: current[index] });
+			}
+		} else if (typeof current === "object" && current !== null) {
+			const record = current;
+			chunks.push("{");
+			tasks.push({ text: "}" });
+			const keys = Object.keys(record);
+			for (let index = keys.length - 1; index >= 0; index--) {
+				const key = keys[index];
+				if (index < keys.length - 1) tasks.push({ text: "," });
+				tasks.push({ value: record[key] });
+				tasks.push({ text: `${JSON.stringify(key)}:` });
+			}
+		} else chunks.push(scalarJson(current));
+	}
+	return chunks.join("");
+}
+/**
+* One scalar (null, boolean, finite number) as JSON text. A beyond-safe-range
+* integral double needs BigInt digits: `String(2 ** 60)` emits the ROUNDED
+* `...847000` form, and echoing that to the child would silently change the
+* integer the seam promised to carry losslessly — `BigInt(2 ** 60)` prints the
+* exact `...846976` the double actually holds.
+* @param current - a JSON-plain scalar (JSON.parse emits nothing else).
+* @returns its JSON encoding.
+*/
+function scalarJson(current) {
+	if (typeof current === "number" && Number.isInteger(current) && !Number.isSafeInteger(current)) return BigInt(current).toString();
+	return String(current);
+}
+/**
+* Exact UTF-8 byte length of one string's compact JSON form (quotes + escapes),
+* computed by a single non-allocating scan that stops the instant the running
+* total exceeds `maxBytes`. Used instead of `Buffer.byteLength(JSON.stringify(s))`
+* so a control-heavy forged string — whose escaped copy expands up to ~6x — is
+* rejected BEFORE that copy is materialized: `JSON.stringify` would allocate the
+* full escaped form first, the very hundreds-of-MB spike the metered traversal
+* exists to avoid. Mirrors `JSON.stringify`'s escaping byte-for-byte: `"` and
+* `\` and the five short C0 escapes cost 2, other C0 controls `\uXXXX` cost 6, a
+* valid surrogate pair is one astral code point emitted as raw 4-byte UTF-8, a
+* LONE surrogate becomes `\uXXXX` at 6, and any other code point costs its raw
+* UTF-8 width.
+* @param text - the string to meter.
+* @param maxBytes - largest serialized size the caller can still admit.
+* @returns the exact serialized byte length, or `undefined` once it exceeds `maxBytes`.
+*/
+function jsonStringBytesUpTo(text, maxBytes) {
+	let bytes = 2;
+	if (bytes > maxBytes) return void 0;
+	for (let index = 0; index < text.length; index++) {
+		const code = text.charCodeAt(index);
+		if (code === 34 || code === 92 || code === 8 || code === 9 || code === 10 || code === 12 || code === 13) bytes += 2;
+		else if (code < 32) bytes += 6;
+		else if (code < 128) bytes += 1;
+		else if (code < 2048) bytes += 2;
+		else if (code >= 55296 && code <= 56319 && index + 1 < text.length) {
+			const next = text.charCodeAt(index + 1);
+			if (next >= 56320 && next <= 57343) {
+				bytes += 4;
+				index++;
+			} else bytes += 6;
+		} else if (code >= 55296 && code <= 57343) bytes += 6;
+		else bytes += 3;
+		if (bytes > maxBytes) return void 0;
+	}
+	return bytes;
+}
+/**
+* Meter a `JSON.parse`-produced done value's compact-JSON byte length AND its
+* number losslessness in one traversal, stopping the instant `maxBytes` is
+* crossed. This bounds the INCREMENTAL allocation the check itself would add on
+* top of the already-parsed value — the enqueued children; strings and keys are
+* metered by {@link jsonStringBytesUpTo} without allocating an escaped copy —
+* not the parse that produced `value`.
+* That upstream width is bounded separately, by the host-side cap on inbound
+* fd-3 frame size before `JSON.parse` runs (owned by the runtime that reads the
+* channel), so `value` cannot be arbitrarily large when it reaches here. The
+* budget is the `maxValueBytes` the boot frame carries — a required wire field
+* with no default at this layer. The traversal rejects over-budget BEFORE
+* materializing a string's escaped form or enqueuing an array's/object's
+* children, so a forgery within that frame cap cannot force those secondary
+* allocations. Object key COUNTING is
+* unavoidably O(keys) — JS has no lazy own-key iterator, and the parse already
+* built the key set — but the check still refuses the per-entry work before the
+* enqueue loop. A non-lossless number (non-finite, negative zero) is caught only
+* when the value fits the budget — an over-budget value is rejected regardless,
+* so the distinction is moot. Same JSON-plain precondition and traversal shape
+* as {@link encodeJsonPlain}; a number's byte length is measured through
+* {@link scalarJson} (matching the encoder, so a beyond-safe-range integer
+* meters its exact BigInt digits, not `JSON.stringify`'s rounded spelling) and
+* a string's/key's through {@link jsonStringBytesUpTo} (the exact escaped size,
+* scanned without allocating the escaped copy).
+* @param value - a JSON-plain value (e.g. straight from `JSON.parse`).
+* @param maxBytes - the completion-value budget in bytes.
+* @returns `{ ok: true, bytes }` with the exact serialized size, or
+* `{ ok: false, reason }` — `over-budget` once the size exceeds `maxBytes`,
+* `non-lossless` on a non-finite or negative-zero number.
+*/
+function checkDoneValue(value, maxBytes) {
+	let bytes = 0;
+	let nonLossless = false;
+	const stack = [value];
+	while (stack.length > 0) {
+		const current = stack.pop();
+		if (typeof current === "number") {
+			if (!Number.isFinite(current) || Object.is(current, -0)) nonLossless = true;
+			bytes += Buffer.byteLength(scalarJson(current), "utf8");
+		} else if (typeof current === "string") {
+			const stringBytes = jsonStringBytesUpTo(current, maxBytes - bytes);
+			if (stringBytes === void 0) return {
+				ok: false,
+				reason: "over-budget"
+			};
+			bytes += stringBytes;
+		} else if (Array.isArray(current)) {
+			bytes += 2 + (current.length > 1 ? current.length - 1 : 0);
+			if (bytes + current.length > maxBytes) return {
+				ok: false,
+				reason: "over-budget"
+			};
+			for (const item of current) stack.push(item);
+		} else if (typeof current === "object" && current !== null) {
+			const record = current;
+			let count = 0;
+			for (const key in record) if (Object.hasOwn(record, key)) count += 1;
+			bytes += 2 + (count > 1 ? count - 1 : 0);
+			if (bytes + count * 4 > maxBytes) return {
+				ok: false,
+				reason: "over-budget"
+			};
+			for (const key in record) {
+				if (!Object.hasOwn(record, key)) continue;
+				const keyBytes = jsonStringBytesUpTo(key, maxBytes - bytes);
+				if (keyBytes === void 0) return {
+					ok: false,
+					reason: "over-budget"
+				};
+				bytes += keyBytes + 1;
+				stack.push(record[key]);
+			}
+		} else bytes += Buffer.byteLength(scalarJson(current), "utf8");
+		if (bytes > maxBytes) return {
+			ok: false,
+			reason: "over-budget"
+		};
+	}
+	if (nonLossless) return {
+		ok: false,
+		reason: "non-lossless"
+	};
+	return {
+		ok: true,
+		bytes
+	};
+}
+/**
+* Whether a raw JSON line contains an integer token that would lose precision
+* as a JavaScript number. `JSON.parse` silently rounds such a token
+* (`9007199254740993` becomes `...992`) BEFORE any validation can see it, so
+* the check must read the source text; a beyond-safe-range token whose double
+* parse round-trips exactly (`2**53`, `2**60`) is lossless and passes. The scan walks the line skipping string literals (a digit run
+* inside a string is data, not a number token) and tests every number token
+* in plain integer form — no fraction or exponent, which parse as doubles by
+* intent. A reviver cannot do this job: the reviver walk recurses per nesting
+* level and would reintroduce the depth limit `encodeJsonPlain` removes.
+* @param line - the raw UTF-8 text of one JSON-lines frame.
+* @returns true when an unsafe integer token is present outside strings.
+*/
+function hasUnsafeIntegerToken(line) {
+	for (let index = 0; index < line.length; index++) {
+		const char = line[index];
+		if (char === "\"") {
+			for (index++; index < line.length; index++) if (line[index] === "\\") index++;
+			else if (line[index] === "\"") break;
+			continue;
+		}
+		if (char === "-" || char !== void 0 && char >= "0" && char <= "9") {
+			let end = index + 1;
+			while (end < line.length) {
+				const c = line[end];
+				if (c >= "0" && c <= "9" || c === "." || c === "e" || c === "E" || c === "+" || c === "-") end++;
+				else break;
+			}
+			const token = line.slice(index, end);
+			if (/^-?\d+$/.test(token)) {
+				const parsed = Number(token);
+				if (!Number.isFinite(parsed)) return true;
+				if (!Number.isSafeInteger(parsed) && BigInt(token) !== BigInt(parsed)) return true;
+			}
+			index = end - 1;
+		}
+	}
+	return false;
+}
+/**
+* Lazily yield one plain object's own enumerable property values. A generator
+* (not `Object.values`/`Object.entries`) because {@link hasNonLosslessNumber}
+* walks breadth it cannot bound: those helpers copy the whole VALUE (or
+* key/value pair) list into a fresh array up front, so a wide object would cost
+* that second full-breadth allocation before a single value is examined. The
+* `for...in` here does not make the walk sublinear — V8 still materializes the
+* key-name enumeration when the loop starts — but it avoids the extra value
+* array, yielding each value straight off the already-parsed object.
+* @param record - a JSON-parse-produced object.
+* @yields each own enumerable property value, in key order.
+*/
+function* ownValues(record) {
+	for (const key in record) if (Object.hasOwn(record, key)) yield record[key];
+}
+/**
+* Whether a JSON.parse-produced value contains a number outside lossless
+* JSON: non-finite (`1e400` parses to `Infinity`) or negative zero (`-0.0`
+* parses to JS `-0`, whose sign bit a re-serialization drops). The honest
+* child's validator rejects these before sending, so a frame carrying one is
+* forged.
+*
+* Runs on `call.args`, which — unlike a completion value — has NO seam byte
+* cap, so there is no budget to reject a wide payload against the way
+* {@link checkDoneValue} does. The traversal therefore holds ONE cursor per
+* NESTING LEVEL (an array or {@link ownValues} iterator) instead of one entry
+* per member: a forged flat `args` at the top of the host's inbound frame-size
+* cap would
+* otherwise push tens of millions of stack entries — and `Object.values` would
+* copy each object's full breadth — allocating hundreds of megabytes beyond
+* what `JSON.parse` already holds. Iterative either way, so a deep frame
+* cannot overflow the host stack.
+* @param value - a JSON-parse-produced value from an fd-3 frame.
+* @returns true when any contained number is non-finite or negative zero.
+*/
+function hasNonLosslessNumber(value) {
+	const cursors = [[value].values()];
+	while (cursors.length > 0) {
+		const step = cursors.at(-1).next();
+		if (step.done === true) {
+			cursors.pop();
+			continue;
+		}
+		const current = step.value;
+		if (typeof current === "number") {
+			if (!Number.isFinite(current) || Object.is(current, -0)) return true;
+		} else if (Array.isArray(current)) cursors.push(current.values());
+		else if (typeof current === "object" && current !== null) cursors.push(ownValues(current));
+	}
+	return false;
+}
+/**
+* Runtime shape gate for inbound fd-3 traffic. Model code has full access to
+* fd 3 and can post anything — `null`, primitives, poisoned fields — so the
+* compile-time union means nothing here: every field is validated and REBUILT
+* before the host reads it (forged extras never ride along; a non-number id
+* can never be echoed into a reply). Junk returns `undefined` and is dropped
+* so a throw in the host's `message` handler cannot crash the host process.
+* @param raw - one JSON-parsed frame from fd 3.
+* @returns the rebuilt frame, or `undefined` to drop it silently.
+*/
+function validateChildFrame(raw) {
+	if (typeof raw !== "object" || raw === null) return void 0;
+	const m = raw;
+	switch (m.type) {
+		case "boot-ack": return { type: "boot-ack" };
+		case "log":
+			if (typeof m.text !== "string") return void 0;
+			return {
+				type: "log",
+				text: m.text,
+				...m.truncated === true ? { truncated: true } : {}
+			};
+		case "call":
+			if (typeof m.id !== "number" || !Number.isFinite(m.id) || Object.is(m.id, -0) || typeof m.global !== "string" || typeof m.name !== "string") return void 0;
+			if (!Object.hasOwn(m, "args")) return void 0;
+			if (hasNonLosslessNumber(m.args)) return void 0;
+			return {
+				type: "call",
+				id: m.id,
+				global: m.global,
+				name: m.name,
+				args: m.args
+			};
+		case "done": {
+			const err = m.error;
+			if (err === void 0) return m.value === void 0 ? { type: "done" } : {
+				type: "done",
+				value: m.value
+			};
+			if (typeof err !== "object" || err === null) return void 0;
+			const { kind, message } = err;
+			if (typeof message !== "string") return void 0;
+			if (kind !== "exception" && kind !== "invalid-output" && kind !== "output-limit") return void 0;
+			return m.value === void 0 ? {
+				type: "done",
+				error: {
+					kind,
+					message
+				}
+			} : {
+				type: "done",
+				value: m.value,
+				error: {
+					kind,
+					message
+				}
+			};
+		}
+		default: return;
+	}
+}
+//#endregion
+export { checkDoneValue, encodeJsonPlain, hasNonLosslessNumber, hasUnsafeIntegerToken, logTruncationMarker, validateChildFrame };

package/lib/invariant.js

@@ -0,0 +1,24 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hydraharness/harness-code-runtime-python`.
+* @module @hydraharness/harness-code-runtime-python/invariant
+*/
+const PACKAGE_NAME = "@hydraharness/harness-code-runtime-python";
+/** Cordis companion plugin name. */
+const name = "code-runtime-python-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this package ships only the fd-3 wire-protocol codec and its Python mirror,
+* exposing no runtime event sequence or mutable data relation; `protocol.spec.ts` and
+* `protocol-mirror.e2e.ts` cover the protocol's behavior.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * CPython subprocess code runtime for the Hydra harness code-execution seam.
+ *
+ * The package owns the versionless fd-3 wire protocol between the Node host and
+ * the CPython subprocess. The protocol's host-side codec and hostile-frame
+ * validators are re-exported so every consumer of the wire shares one
+ * vocabulary.
+ * @module @hydraharness/harness-code-runtime-python
+ */
+export type { BootMessage, ChildToHost, ReplyMessage } from './protocol.ts';
+export { checkDoneValue, encodeJsonPlain, hasNonLosslessNumber, hasUnsafeIntegerToken, logTruncationMarker, validateChildFrame, } from './protocol.ts';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hydraharness/harness-code-runtime-python`.
+ * @module @hydraharness/harness-code-runtime-python/invariant
+ */
+import type { Context } from '@hydraharness/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "code-runtime-python-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/protocol.d.ts

@@ -0,0 +1,329 @@
+/**
+ * Versionless, JSON-lines wire protocol between the Node host and the CPython subprocess. Frames
+ * travel on the child's fd 3 (one JSON object per line), leaving stdout/stderr free for the
+ * program's own output. Host treats every inbound frame as hostile because model code can post
+ * anything through the same fd; the Python bootstrap trusts host replies.
+ * @module @hydraharness/harness-code-runtime-python/src/protocol
+ */
+/**
+ * The framed-JSON channel's file descriptor from the child's perspective. The
+ * host pins it positionally when it spawns the child (`stdio` index 3, i.e.
+ * `['pipe','pipe','pipe','pipe']`), and the Python bootstrap reads the same
+ * number from its own `protocol.py`. Exported as the single TS-side source of
+ * truth: the host wiring uses it, and the cross-language mirror test asserts the
+ * Python constant equals it, so a drift on either side breaks the boot channel
+ * loudly rather than silently.
+ */
+export declare const PROTOCOL_FD = 3;
+/**
+ * One binding namespace declaration inside a {@link BootMessage}. `global` is
+ * the program-visible name the namespace is materialized under; `errorClass`,
+ * when present, asks the bootstrap to mint a program-visible exception class.
+ */
+interface Namespace {
+    global: string;
+    names: string[];
+    errorClass?: ErrorClass;
+}
+/**
+ * A namespace's program-visible exception class: rejected calls raise its
+ * instances carrying the failed member name on `memberNameProperty`.
+ */
+interface ErrorClass {
+    name: string;
+    memberNameProperty: string;
+}
+/**
+ * What the host sends immediately after spawn, as the first line on fd 3. The
+ * Python bootstrap reads this, applies resource limits, then waits for the
+ * subsequent run frame. Separated from the run so the run message stays
+ * pure model input.
+ */
+export interface BootMessage {
+    type: 'boot';
+    /** RLIMIT_CPU seconds; the Python bootstrap sets this on itself before executing model code. */
+    cpuSeconds: number;
+    /** RLIMIT_AS bytes; caps address space so a runaway allocation fails cleanly. */
+    addressSpaceBytes: number;
+    /** Shared byte budget for captured log text (Python-side ledger). */
+    maxLogBytes: number;
+    /** Byte cap for the rendered completion value. */
+    maxValueBytes: number;
+    /**
+     * The namespaces to materialize inside the program (globals + names;
+     * functions stay host-side). See {@link Namespace}.
+     */
+    namespaces: Namespace[];
+}
+/** Python → host: acknowledges boot completed and resource limits are in place. */
+interface BootAckMessage {
+    type: 'boot-ack';
+}
+/** Python → host: one bridged binding call (`await tools.name(args)` inside the program). */
+interface CallMessage {
+    type: 'call';
+    /** Python-issued correlation id; the host answers each id at most once and ignores duplicates. */
+    id: number;
+    /** The namespace global the call targets. */
+    global: string;
+    /** The function name within the namespace. */
+    name: string;
+    /** The JSON-safe argument the model program passed. */
+    args: unknown;
+}
+/**
+ * Python → host: captured text, streamed eagerly so output survives a
+ * mid-run termination (RLIMIT_CPU, SIGTERM/SIGKILL, host wall-timeout).
+ */
+interface LogMessage {
+    type: 'log';
+    text: string;
+    /**
+     * Set when this frame IS the child ledger's truncation marker rather than
+     * program output. The two ledgers can exhaust at different points — one
+     * child entry larger than `maxLogBytes` sends only the marker while the host
+     * ledger is still nearly empty — so the host cannot infer the child's state
+     * from its own budget, and comparing the text against the marker string
+     * would also honour a program that printed that string itself. Carrying it
+     * as a field lets the host stop capturing at the same point the child did
+     * and keeps exactly one marker in `logs`.
+     */
+    truncated?: boolean;
+}
+/** The failure carried on a {@link DoneMessage}: one of three kinds plus text. */
+interface DoneErrorField {
+    kind: 'exception' | 'invalid-output' | 'output-limit';
+    message: string;
+}
+/**
+ * Python → host: the program settled. `error` carries a program exception
+ * (traceback text), an `invalid-output` (completion value was not lossless
+ * JSON), or an `output-limit` (serialized completion exceeded the configured
+ * cap); wall/CPU budgets, aborts, and substrate death are observed host-side.
+ * From the honest child `value` is present only on a clean completion that
+ * produced one, and crosses as exact lossless JSON — never substituted or
+ * truncated. A forged frame CAN carry both `value` and `error`;
+ * {@link validateChildFrame} preserves both rather than guessing which to drop,
+ * so a consumer MUST check `error` first and ignore `value` when it is set.
+ */
+interface DoneMessage {
+    type: 'done';
+    value?: unknown;
+    error?: DoneErrorField;
+}
+/**
+ * Every message the Python side sends. The member interfaces stay module-
+ * private: consumers match on the union's discriminant; the host sends the
+ * boot and run frames as inline literals.
+ */
+export type ChildToHost = BootAckMessage | CallMessage | LogMessage | DoneMessage;
+/** Host → Python: successful answer to one {@link CallMessage}. */
+interface ReplyOk {
+    type: 'reply';
+    id: number;
+    ok: true;
+    value: unknown;
+}
+/** Host → Python: failed answer to one {@link CallMessage}. */
+interface ReplyErr {
+    type: 'reply';
+    id: number;
+    ok: false;
+    message: string;
+}
+/** Host → Python: the answer to one {@link CallMessage}. */
+export type ReplyMessage = ReplyOk | ReplyErr;
+/**
+ * Each frame's wire fields tagged by required/optional, keyed by field name so
+ * the mapping is exhaustive over the frame interface (see {@link FrameFieldRoles})
+ * across the whole {@link WireFrameShapes} roster. Bound to the interfaces by
+ * `satisfies` below; {@link WIRE_FRAME_FIELDS} projects it to sorted
+ * required/optional arrays for the cross-language mirror comparison. `global` is
+ * the JSON key {@link CallMessage} and {@link Namespace} send (a reserved word
+ * the Python side carries via a functional `TypedDict`).
+ */
+declare const WIRE_FRAME_FIELD_ROLES: {
+    readonly BootMessage: {
+        readonly type: "required";
+        readonly cpuSeconds: "required";
+        readonly addressSpaceBytes: "required";
+        readonly maxLogBytes: "required";
+        readonly maxValueBytes: "required";
+        readonly namespaces: "required";
+    };
+    readonly Namespace: {
+        readonly global: "required";
+        readonly names: "required";
+        readonly errorClass: "optional";
+    };
+    readonly RunMessage: {
+        readonly type: "required";
+        readonly program: "required";
+    };
+    readonly BootAckMessage: {
+        readonly type: "required";
+    };
+    readonly CallMessage: {
+        readonly type: "required";
+        readonly id: "required";
+        readonly global: "required";
+        readonly name: "required";
+        readonly args: "required";
+    };
+    readonly LogMessage: {
+        readonly type: "required";
+        readonly text: "required";
+        readonly truncated: "optional";
+    };
+    readonly DoneErrorField: {
+        readonly kind: "required";
+        readonly message: "required";
+    };
+    readonly DoneMessage: {
+        readonly type: "required";
+        readonly value: "optional";
+        readonly error: "optional";
+    };
+    readonly ErrorClass: {
+        readonly name: "required";
+        readonly memberNameProperty: "required";
+    };
+    readonly ReplyOk: {
+        readonly type: "required";
+        readonly id: "required";
+        readonly ok: "required";
+        readonly value: "required";
+    };
+    readonly ReplyErr: {
+        readonly type: "required";
+        readonly id: "required";
+        readonly ok: "required";
+        readonly message: "required";
+    };
+};
+/**
+ * The wire field names of each frame, split into sorted required and optional
+ * key arrays — the shape the cross-language mirror test compares against
+ * `py/protocol.py`'s `TypedDict` `__required_keys__`/`__optional_keys__`.
+ * Projected from {@link WIRE_FRAME_FIELD_ROLES}, so it inherits that mapping's
+ * exhaustive, optionality-checked binding to the frame interfaces: a TS-side
+ * field add, remove, rename, or optionality flip fails typecheck at the roles
+ * map, and a Python-side divergence fails the mirror test at runtime.
+ */
+export declare const WIRE_FRAME_FIELDS: Record<keyof typeof WIRE_FRAME_FIELD_ROLES, {
+    required: string[];
+    optional: string[];
+}>;
+/**
+ * The in-band marker text announcing that log capture stopped at the byte
+ * budget. Shared wire vocabulary: the Python-side LogBuffer emits it when ITS
+ * ledger exhausts, and the host emits identical text when its own ledger drops
+ * a frame first (forged fd-3 traffic, stray stdout bytes) — a truncated run
+ * reads the same however the cap was hit.
+ * @param maxBytes - the configured `maxLogBytes` the marker names.
+ * @returns the marker line.
+ */
+export declare function logTruncationMarker(maxBytes: number): string;
+/**
+ * Serialize one JSON-parse-produced value without recursion. `JSON.stringify`
+ * recurses per nesting level and throws `RangeError` a few thousand levels
+ * deep, but the seam's `CodeJsonValue` has no depth limit — an honest deep
+ * completion or binding resolution below the byte budget must cross intact
+ * (the worker backend's wire is equally stack-safe). Callers must pass a value
+ * produced by `JSON.parse` (or equally JSON-plain): only `null`, finite
+ * numbers, booleans, strings, dense arrays, and plain objects — this encoder
+ * validates nothing. Output matches compact `JSON.stringify` byte for byte
+ * EXCEPT on an integral double beyond the safe range, where {@link scalarJson}
+ * emits the exact integer's BigInt digits rather than `JSON.stringify`'s rounded
+ * spelling (`1152921504606846976`, not `...847000`) so the seam's lossless-JSON
+ * promise holds across the wire.
+ * @param value - a JSON-plain value (e.g. straight from `JSON.parse`).
+ * @returns the compact JSON encoding.
+ */
+export declare function encodeJsonPlain(value: unknown): string;
+/**
+ * Meter a `JSON.parse`-produced done value's compact-JSON byte length AND its
+ * number losslessness in one traversal, stopping the instant `maxBytes` is
+ * crossed. This bounds the INCREMENTAL allocation the check itself would add on
+ * top of the already-parsed value — the enqueued children; strings and keys are
+ * metered by {@link jsonStringBytesUpTo} without allocating an escaped copy —
+ * not the parse that produced `value`.
+ * That upstream width is bounded separately, by the host-side cap on inbound
+ * fd-3 frame size before `JSON.parse` runs (owned by the runtime that reads the
+ * channel), so `value` cannot be arbitrarily large when it reaches here. The
+ * budget is the `maxValueBytes` the boot frame carries — a required wire field
+ * with no default at this layer. The traversal rejects over-budget BEFORE
+ * materializing a string's escaped form or enqueuing an array's/object's
+ * children, so a forgery within that frame cap cannot force those secondary
+ * allocations. Object key COUNTING is
+ * unavoidably O(keys) — JS has no lazy own-key iterator, and the parse already
+ * built the key set — but the check still refuses the per-entry work before the
+ * enqueue loop. A non-lossless number (non-finite, negative zero) is caught only
+ * when the value fits the budget — an over-budget value is rejected regardless,
+ * so the distinction is moot. Same JSON-plain precondition and traversal shape
+ * as {@link encodeJsonPlain}; a number's byte length is measured through
+ * {@link scalarJson} (matching the encoder, so a beyond-safe-range integer
+ * meters its exact BigInt digits, not `JSON.stringify`'s rounded spelling) and
+ * a string's/key's through {@link jsonStringBytesUpTo} (the exact escaped size,
+ * scanned without allocating the escaped copy).
+ * @param value - a JSON-plain value (e.g. straight from `JSON.parse`).
+ * @param maxBytes - the completion-value budget in bytes.
+ * @returns `{ ok: true, bytes }` with the exact serialized size, or
+ * `{ ok: false, reason }` — `over-budget` once the size exceeds `maxBytes`,
+ * `non-lossless` on a non-finite or negative-zero number.
+ */
+export declare function checkDoneValue(value: unknown, maxBytes: number): {
+    ok: true;
+    bytes: number;
+} | {
+    ok: false;
+    reason: 'over-budget' | 'non-lossless';
+};
+/**
+ * Whether a raw JSON line contains an integer token that would lose precision
+ * as a JavaScript number. `JSON.parse` silently rounds such a token
+ * (`9007199254740993` becomes `...992`) BEFORE any validation can see it, so
+ * the check must read the source text; a beyond-safe-range token whose double
+ * parse round-trips exactly (`2**53`, `2**60`) is lossless and passes. The scan walks the line skipping string literals (a digit run
+ * inside a string is data, not a number token) and tests every number token
+ * in plain integer form — no fraction or exponent, which parse as doubles by
+ * intent. A reviver cannot do this job: the reviver walk recurses per nesting
+ * level and would reintroduce the depth limit `encodeJsonPlain` removes.
+ * @param line - the raw UTF-8 text of one JSON-lines frame.
+ * @returns true when an unsafe integer token is present outside strings.
+ */
+export declare function hasUnsafeIntegerToken(line: string): boolean;
+/**
+ * Whether a JSON.parse-produced value contains a number outside lossless
+ * JSON: non-finite (`1e400` parses to `Infinity`) or negative zero (`-0.0`
+ * parses to JS `-0`, whose sign bit a re-serialization drops). The honest
+ * child's validator rejects these before sending, so a frame carrying one is
+ * forged.
+ *
+ * Runs on `call.args`, which — unlike a completion value — has NO seam byte
+ * cap, so there is no budget to reject a wide payload against the way
+ * {@link checkDoneValue} does. The traversal therefore holds ONE cursor per
+ * NESTING LEVEL (an array or {@link ownValues} iterator) instead of one entry
+ * per member: a forged flat `args` at the top of the host's inbound frame-size
+ * cap would
+ * otherwise push tens of millions of stack entries — and `Object.values` would
+ * copy each object's full breadth — allocating hundreds of megabytes beyond
+ * what `JSON.parse` already holds. Iterative either way, so a deep frame
+ * cannot overflow the host stack.
+ * @param value - a JSON-parse-produced value from an fd-3 frame.
+ * @returns true when any contained number is non-finite or negative zero.
+ */
+export declare function hasNonLosslessNumber(value: unknown): boolean;
+/**
+ * Runtime shape gate for inbound fd-3 traffic. Model code has full access to
+ * fd 3 and can post anything — `null`, primitives, poisoned fields — so the
+ * compile-time union means nothing here: every field is validated and REBUILT
+ * before the host reads it (forged extras never ride along; a non-number id
+ * can never be echoed into a reply). Junk returns `undefined` and is dropped
+ * so a throw in the host's `message` handler cannot crash the host process.
+ * @param raw - one JSON-parsed frame from fd 3.
+ * @returns the rebuilt frame, or `undefined` to drop it silently.
+ */
+export declare function validateChildFrame(raw: unknown): ChildToHost | undefined;
+export {};
+//# sourceMappingURL=protocol.d.ts.map

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@hydraharness/harness-code-runtime-python",
+  "description": "CPython subprocess implementation of the Hydra harness code-execution seam",
+  "version": "0.1.1-rc.10",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong2010/Hydra-Harness.git",
+    "directory": "packages/code-runtime/code-runtime-python"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "py/**/*.py",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@hydraharness/harness-invariants": "^0.1.1-rc.10",
+    "@hydraharness/cordis": "^4.0.2"
+  },
+  "devDependencies": {
+    "@hydraharness/harness-invariants": "^0.1.1-rc.10",
+    "@hydraharness/cordis": "^4.0.2"
+  }
+}

package/py/protocol.py

@@ -0,0 +1,138 @@
+"""Wire protocol vocabulary for the Python side of hydra-code-runtime-python.
+
+Mirrors ``src/protocol.ts``. Frames travel on fd 3 as JSON-lines (one JSON
+object per line). The host validates every inbound frame; this side trusts
+host replies.
+
+The wire uses the JSON key ``global`` (a Python keyword), so the frame
+``TypedDict``s that carry it are declared with the functional syntax rather than
+class bodies: a class attribute cannot be named ``global``, and a ``global_``
+attribute would describe a key the wire never sends. Optional-field messages
+pair a required base with a ``total=False`` subclass so a required field such as
+``type`` cannot be dropped while ``value``/``error``/``truncated`` stay optional.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, TypedDict, Union
+
+# The protocol fd from the child's perspective. Node passes
+# ``stdio: [pipe, pipe, pipe, pipe]`` so the fourth entry (fd 3) is the
+# framed-JSON channel; stdout/stderr stay clear for the program's own output.
+PROTOCOL_FD = 3
+
+
+class ErrorClass(TypedDict):
+    """A namespace's program-visible exception class: rejected calls raise its
+    instances carrying the failed member name on ``memberNameProperty``."""
+
+    name: str
+    memberNameProperty: str
+
+
+# ``global`` is a Python keyword, so the required part is declared functionally
+# to hold the real wire key; ``errorClass`` is optional per the TS `errorClass?`.
+_NamespaceRequired = TypedDict("_NamespaceRequired", {"global": str, "names": "list[str]"})
+
+
+class Namespace(_NamespaceRequired, total=False):
+    """One binding namespace declaration: the ``global`` name, its function
+    ``names``, and an optional program-visible ``errorClass`` for rejected calls."""
+
+    errorClass: ErrorClass
+
+
+class BootMessage(TypedDict):
+    """Host → child, first frame on fd 3. Carries every cap and the namespaces."""
+
+    type: Literal["boot"]
+    cpuSeconds: int
+    addressSpaceBytes: int
+    maxLogBytes: int
+    maxValueBytes: int
+    namespaces: "list[Namespace]"
+
+
+class RunMessage(TypedDict):
+    """Host → child, sent after ``boot-ack``. Carries only the program body."""
+
+    type: Literal["run"]
+    program: str
+
+
+class BootAckMessage(TypedDict):
+    """Child → host: resource limits applied, ready for the run message."""
+
+    type: Literal["boot-ack"]
+
+
+# ``global`` wire key: whole message declared functionally, all fields required.
+CallMessage = TypedDict(
+    "CallMessage",
+    {"type": Literal["call"], "id": int, "global": str, "name": str, "args": Any},
+)
+
+
+_LogMessageRequired = TypedDict("_LogMessageRequired", {"type": Literal["log"], "text": str})
+
+
+class LogMessage(_LogMessageRequired, total=False):
+    """Child → host: one captured text chunk, streamed eagerly.
+
+    ``truncated`` is set only on the frame that IS the child ledger's truncation
+    marker (not program output), so the host stops capturing at the same point
+    the child did — mirrors the TS `truncated?`.
+    """
+
+    truncated: bool
+
+
+class DoneErrorField(TypedDict):
+    """Child → host: the failure carried on a ``done`` frame. ``kind`` is one of
+    the three the host validates; ``message`` is the traceback or diagnostic."""
+
+    kind: Literal["exception", "invalid-output", "output-limit"]
+    message: str
+
+
+_DoneMessageRequired = TypedDict("_DoneMessageRequired", {"type": Literal["done"]})
+
+
+class DoneMessage(_DoneMessageRequired, total=False):
+    """Child → host: the program settled. ``value`` and ``error`` are optional per the TS mirror."""
+
+    value: Any
+    error: DoneErrorField
+
+
+ChildToHost = Union[BootAckMessage, CallMessage, LogMessage, DoneMessage]
+
+
+class ReplyOk(TypedDict):
+    type: Literal["reply"]
+    id: int
+    ok: Literal[True]
+    value: Any
+
+
+class ReplyErr(TypedDict):
+    type: Literal["reply"]
+    id: int
+    ok: Literal[False]
+    message: str
+
+
+ReplyMessage = Union[ReplyOk, ReplyErr]
+# The host sends ``boot`` and ``run`` before any ``reply``, so the child-facing
+# inbound union covers all three, not replies alone.
+HostToChild = Union[BootMessage, RunMessage, ReplyMessage]
+
+
+def log_truncation_marker(max_bytes: int) -> str:
+    """Return the in-band marker for a log ledger that exhausted its budget.
+
+    Byte-identical text on both sides of the wire so a truncated run reads the
+    same however the cap was hit.
+    """
+
+    return f"[hydra-code-runtime-python] log capture truncated at {max_bytes} bytes"