better-dsh 0.2.5 → 0.3.0

package/lib/index.js

@@ -1,16 +1,17 @@
-import { a as RESERVED_ERROR_MEMBERS, i as RESERVED_BINDING_GLOBALS, n as DUNDER_MEMBER, o as ReplRuntime, r as PORTABLE_RESERVED_WORDS, t as isFlatBindableName } from "./py-sdk-Chvy92MB.js";
-import { s as resolveKernelEnv } from "./kernel-env-hxaihi9C.js";
-import { t as captureAllTools } from "./native-capture-x_Hos2e8.js";
+import { t as Schema } from "./lib-C8_jXvwA.js";
+import { a as RESERVED_ERROR_MEMBERS, i as RESERVED_BINDING_GLOBALS, n as DUNDER_MEMBER, o as ReplRuntime, r as PORTABLE_RESERVED_WORDS, t as isFlatBindableName } from "./py-sdk-D7klhpWb.js";
+import { s as resolveKernelEnv } from "./kernel-env-D8UOWeji.js";
+import { t as captureAllTools } from "./native-capture-BEByDXYM.js";
 import { createRequire } from "node:module";
+import { randomBytes, randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { Context } from "@deepseek-ai/cordis";
-import { createHmac, randomBytes, randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import z from "@deepseek-ai/schemastery";
-import { spawn } from "node:child_process";
 import { tmpdir } from "node:os";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
-import { Dealer, Subscriber } from "zeromq";
+import { createInterface } from "node:readline";
 import { TOOL_RUNTIME_SCHEDULER, defineTool } from "@deepseek-ai/dsh-tools";
 import * as dshLlm from "@deepseek-ai/dsh-llm";
 import { BlockAssembler, HarnessError, createUserMessage } from "@deepseek-ai/dsh-llm";
@@ -174,6 +175,240 @@ function snapshotJsonValue(value) {
 	return walkJsonValue(value, true);
 }
 
+//#endregion
+//#region src/kernel-transport.ts
+/** The bridge script shipped beside the built entry (`lib/kernel-bridge.py`). */
+const BRIDGE_SCRIPT = fileURLToPath(new URL("./kernel-bridge.py", import.meta.url));
+/**
+* One bridge subprocess speaking JSON lines. Lifecycle is owned by the caller
+* (the kernel bridge registers it as an `ctx.effect`); this type installs no
+* process-level signal handlers.
+*/
+var KernelTransport = class {
+	child;
+	reader;
+	startup = false;
+	closed = false;
+	readySettled = false;
+	readyResolve;
+	readyReject;
+	bridgeStderr = "";
+	handlers = /* @__PURE__ */ new Set();
+	waiters = /* @__PURE__ */ new Set();
+	constructor(options) {
+		this.options = options;
+	}
+	/** Spawn the bridge and resolve once it reports the channels are up. */
+	async start() {
+		if (this.reader !== void 0) return;
+		if (this.closed) throw new Error("kernel transport is closed");
+		const child = spawn(this.options.python, [BRIDGE_SCRIPT, this.options.connectionFile], {
+			...this.options.cwd === void 0 ? {} : { cwd: this.options.cwd },
+			env: {
+				PATH: process.env.PATH ?? "/usr/local/bin:/usr/bin:/bin",
+				LANG: "C.UTF-8",
+				HOME: process.env.HOME ?? tmpdir(),
+				PYTHONUNBUFFERED: "1"
+			},
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			]
+		});
+		this.child = child;
+		this.startup = true;
+		const ready = new Promise((resolve$1, reject) => {
+			this.readyResolve = resolve$1;
+			this.readyReject = reject;
+		});
+		const timer = setTimeout(() => {
+			this.failReady(/* @__PURE__ */ new Error(`kernel bridge did not report ready within ${this.options.readyTimeoutMs}ms; stderr tail:\n${this.stderrTail()}`));
+		}, this.options.readyTimeoutMs);
+		timer.unref?.();
+		child.stderr?.on("data", (buffer) => {
+			this.bridgeStderr += buffer.toString();
+		});
+		child.stdin?.on("error", (error) => {
+			this.bridgeStderr += `stdin error: ${error.code ?? error.message}\n`;
+			this.closed = true;
+			this.failWaiters();
+		});
+		child.stdout?.on("error", (error) => {
+			this.bridgeStderr += `stdout error: ${error.code ?? error.message}\n`;
+		});
+		child.on("error", (error) => {
+			this.bridgeStderr += `spawn error: ${error.message}\n`;
+			this.failReady(/* @__PURE__ */ new Error(`kernel bridge failed to spawn: ${error.message}`));
+			this.failWaiters();
+			this.failExit();
+		});
+		child.on("exit", (code, signal) => {
+			const detail = `kernel bridge exited (code=${String(code)} signal=${String(signal)})`;
+			this.bridgeStderr += `${detail}\n`;
+			this.closed = true;
+			this.failReady(/* @__PURE__ */ new Error(`${detail}; stderr tail:\n${this.stderrTail()}`));
+			this.failWaiters();
+			this.failExit();
+		});
+		if (child.stdout) {
+			this.reader = createInterface({ input: child.stdout });
+			this.reader.on("line", (line) => {
+				this.accept(line);
+			});
+		}
+		try {
+			await ready;
+		} finally {
+			clearTimeout(timer);
+			this.startup = false;
+		}
+	}
+	/** Whether the bridge process is still live. */
+	get alive() {
+		return this.child !== void 0 && this.child.exitCode === null && !this.closed;
+	}
+	/** The bridge's stderr tail, for startup and crash diagnostics. */
+	stderrTail() {
+		return this.bridgeStderr.slice(-1024) || "(empty)";
+	}
+	/** Register a message handler; the returned function removes it. */
+	onMessage(handler) {
+		this.handlers.add(handler);
+		return () => {
+			this.handlers.delete(handler);
+		};
+	}
+	/**
+	* Register a bridge-exit handler; the returned function removes it. A bridge
+	* that dies mid-cell must settle the active execution at once rather than at
+	* the cell budget.
+	*/
+	onExit(handler) {
+		this.exitHandlers.add(handler);
+		return () => {
+			this.exitHandlers.delete(handler);
+		};
+	}
+	exitHandlers = /* @__PURE__ */ new Set();
+	/** Notify exit handlers once per bridge process end. */
+	failExit() {
+		const handlers = [...this.exitHandlers];
+		this.exitHandlers.clear();
+		for (const handler of handlers) handler();
+	}
+	/** Send one message on the shell or control channel. */
+	send(channel, message) {
+		this.writeLine({
+			op: "send",
+			channel,
+			header: message.header,
+			content: message.content
+		});
+	}
+	/** Ask the kernel to interrupt the running cell (control channel). */
+	interrupt() {
+		this.writeLine({ op: "interrupt" });
+	}
+	/** Write one protocol line, refusing instead of throwing when the pipe is gone. */
+	writeLine(payload) {
+		const stdin = this.child?.stdin;
+		if (stdin === null || stdin === void 0 || this.closed || !stdin.writable) throw new Error("kernel bridge is not connected");
+		stdin.write(`${JSON.stringify(payload)}\n`);
+	}
+	/**
+	* Wait for the next message on `channel` matching `match`.
+	* @returns The message, or null when the budget expires or the bridge dies.
+	*/
+	waitFor(channel, match, timeoutMs) {
+		if (this.closed) return Promise.resolve(null);
+		return new Promise((resolve$1) => {
+			const waiter = {
+				channel,
+				match,
+				settle: (message) => {
+					clearTimeout(waiter.timer);
+					this.waiters.delete(waiter);
+					resolve$1(message);
+				},
+				timer: setTimeout(() => {
+					this.waiters.delete(waiter);
+					resolve$1(null);
+				}, timeoutMs)
+			};
+			waiter.timer.unref?.();
+			this.waiters.add(waiter);
+		});
+	}
+	/** Stop the bridge (graceful shutdown note, then kill). */
+	async dispose() {
+		const child = this.child;
+		this.closed = true;
+		this.failWaiters();
+		this.reader?.close();
+		this.reader = void 0;
+		if (child === void 0) return;
+		try {
+			if (child.stdin?.writable === true) child.stdin.write(`${JSON.stringify({ op: "shutdown" })}\n`);
+		} catch {}
+		try {
+			child.stdin?.end();
+		} catch {}
+		if (child.exitCode !== null) return;
+		await new Promise((resolve$1) => {
+			const timer = setTimeout(() => {
+				try {
+					child.kill("SIGKILL");
+				} catch {}
+				resolve$1();
+			}, 500);
+			timer.unref?.();
+			child.once("exit", () => {
+				clearTimeout(timer);
+				resolve$1();
+			});
+		});
+	}
+	failReady(error) {
+		if (this.readySettled) return;
+		this.readySettled = true;
+		this.readyReject?.(error);
+	}
+	failWaiters() {
+		for (const waiter of [...this.waiters]) waiter.settle(null);
+	}
+	/** Route one decoded line; unknown events are ignored. */
+	accept(line) {
+		let event;
+		try {
+			event = JSON.parse(line);
+		} catch {
+			return;
+		}
+		if (event.ev === "ready") {
+			if (!this.readySettled) {
+				this.readySettled = true;
+				this.readyResolve?.();
+			}
+			return;
+		}
+		if (event.ev === "msg") {
+			const channel = event.channel;
+			const raw = event.msg;
+			if (typeof channel !== "string" || raw === void 0 || typeof raw.header !== "object" || raw.header === null) return;
+			const message = {
+				header: raw.header,
+				parent_header: raw.parent_header ?? {},
+				content: raw.content ?? {}
+			};
+			for (const waiter of [...this.waiters]) if (waiter.channel === channel && waiter.match(message)) waiter.settle(message);
+			for (const handler of this.handlers) handler(channel, message);
+			return;
+		}
+		if (event.ev === "fatal") this.bridgeStderr += `fatal: ${String(event.message ?? "unknown")}\n`;
+	}
+};
+
 //#endregion
 //#region src/bootstrap.ts
 /**
@@ -887,7 +1122,6 @@ function finalizeOutput(logs, value, error, maxBytes) {
 
 //#endregion
 //#region src/kernel.ts
-const DELIM = Buffer.from("<IDS|MSG>");
 const PROTOCOL_VERSION = "5.3";
 /** Loopback PUB/SUB subscription propagation guard before the first execute. */
 const IOPUB_SUBSCRIBE_DELAY_MS = 50;
@@ -910,35 +1144,6 @@ function buildMessage(msgType, content, session, username) {
 		content
 	};
 }
-function encode(msg, key) {
-	const parts = [
-		Buffer.from(JSON.stringify(msg.header)),
-		Buffer.from(JSON.stringify(msg.parent_header)),
-		Buffer.from("{}"),
-		Buffer.from(JSON.stringify(msg.content))
-	];
-	const hmac = createHmac("sha256", key);
-	for (const part of parts) hmac.update(part);
-	return [
-		DELIM,
-		Buffer.from(hmac.digest("hex")),
-		...parts
-	];
-}
-function decode(frames) {
-	let i = 0;
-	while (i < frames.length && !frames[i].equals(DELIM)) i++;
-	if (i + 5 >= frames.length) return null;
-	try {
-		return {
-			header: JSON.parse(frames[i + 2].toString()),
-			parent_header: JSON.parse(frames[i + 3].toString()),
-			content: JSON.parse(frames[i + 5].toString())
-		};
-	} catch {
-		return null;
-	}
-}
 function makeConnection() {
 	const info = {
 		ip: "127.0.0.1",
@@ -953,16 +1158,16 @@ function makeConnection() {
 		kernel_name: "python3"
 	};
 	const tempDir = mkdtempSync(join(tmpdir(), "dashr-kernel-"));
-	const path = join(tempDir, "connection.json");
-	writeFileSync(path, JSON.stringify(info, null, 2), { mode: 384 });
+	const path$1 = join(tempDir, "connection.json");
+	writeFileSync(path$1, JSON.stringify(info, null, 2), { mode: 384 });
 	return {
-		path,
+		path: path$1,
 		tempDir
 	};
 }
-function readResolvedConnection(path) {
+function readResolvedConnection(path$1) {
 	try {
-		const parsed = JSON.parse(readFileSync(path, "utf8"));
+		const parsed = JSON.parse(readFileSync(path$1, "utf8"));
 		if (!isRecord(parsed) || parsed.ip !== "127.0.0.1" || parsed.transport !== "tcp" || parsed.signature_scheme !== "hmac-sha256" || typeof parsed.key !== "string") return null;
 		for (const port of [
 			"shell_port",
@@ -989,9 +1194,7 @@ var IpyKernelBridge = class {
 	state = "idle";
 	startPromise;
 	kernel;
-	shell;
-	iopub;
-	control;
+	transport;
 	connection;
 	tempDir;
 	kernelStderr = "";
@@ -999,7 +1202,6 @@ var IpyKernelBridge = class {
 	activeExec;
 	commTargets = /* @__PURE__ */ new Map();
 	servedComms = /* @__PURE__ */ new Set();
-	iopubPump;
 	constructor(options) {
 		this.options = options;
 	}
@@ -1036,13 +1238,13 @@ var IpyKernelBridge = class {
 	async doStart() {
 		if (this.state !== "idle") return;
 		this.state = "starting";
-		const { path, tempDir } = makeConnection();
+		const { path: path$1, tempDir } = makeConnection();
 		this.tempDir = tempDir;
 		const kernel = spawn(this.options.python, [
 			"-m",
 			"ipykernel_launcher",
 			"-f",
-			path
+			path$1
 		], {
 			cwd: this.options.cwd,
 			env: {
@@ -1070,22 +1272,37 @@ var IpyKernelBridge = class {
 		});
 		let conn;
 		try {
-			conn = await this.waitForConnection(path);
+			conn = await this.waitForConnection(path$1);
 			this.connection = conn;
 		} catch (error) {
 			this.cleanupResources();
 			this.state = "idle";
 			throw error;
 		}
-		this.shell = new Dealer();
-		this.iopub = new Subscriber();
-		this.control = new Dealer();
-		this.shell.connect(`${conn.transport}://${conn.ip}:${conn.shell_port}`);
-		this.iopub.connect(`${conn.transport}://${conn.ip}:${conn.iopub_port}`);
-		this.control.connect(`${conn.transport}://${conn.ip}:${conn.control_port}`);
-		this.iopub.subscribe("");
+		const transport = new KernelTransport({
+			python: this.options.python,
+			connectionFile: path$1,
+			...this.options.cwd === void 0 ? {} : { cwd: this.options.cwd },
+			readyTimeoutMs: this.options.startupTimeoutMs
+		});
+		this.transport = transport;
+		transport.onMessage((channel, message) => {
+			this.handleTransportMessage(channel, message);
+		});
+		transport.onExit(() => {
+			if (this.state !== "shutdown") this.forceSettleActive({
+				kind: "worker-exit",
+				message: `kernel bridge died. stderr tail:\n${transport.stderrTail()}`
+			});
+		});
+		try {
+			await transport.start();
+		} catch (error) {
+			this.cleanupResources();
+			this.state = "idle";
+			throw error;
+		}
 		await setTimeout$1(IOPUB_SUBSCRIBE_DELAY_MS);
-		this.startIopubPump();
 		try {
 			await this.probeReady();
 		} catch (error) {
@@ -1106,35 +1323,26 @@ var IpyKernelBridge = class {
 		}
 		this.state = "running";
 	}
-	async waitForConnection(path) {
+	async waitForConnection(path$1) {
 		const deadline = Date.now() + this.options.startupTimeoutMs;
 		while (Date.now() < deadline) {
 			if (this.state === "shutdown") throw new Error(`kernel exited before resolving ports. stderr:\n${this.stderrTail()}`);
-			const info = readResolvedConnection(path);
+			const info = readResolvedConnection(path$1);
 			if (info) return info;
 			await setTimeout$1(CONNECT_POLL_MS);
 		}
 		throw new Error(`kernel did not resolve connection ports within ${this.options.startupTimeoutMs}ms. stderr tail:\n${this.stderrTail()}`);
 	}
 	async probeReady() {
-		const conn = this.connection;
-		const shell = this.shell;
-		if (!conn || !shell) throw new Error("kernel channels are not connected");
+		const transport = this.transport;
+		if (!transport) throw new Error("kernel channels are not connected");
 		const msg = buildMessage("kernel_info_request", {}, this.session, this.options.username);
 		const requestMsgId = msg.header.msg_id;
-		await shell.send(encode(msg, conn.key));
-		const deadline = Date.now() + this.options.startupTimeoutMs;
-		while (Date.now() < deadline) {
-			if (this.state === "shutdown") throw new Error(`kernel exited during startup. stderr:\n${this.stderrTail()}`);
-			const winner = await Promise.race([shell.receive().then((frames) => ({
-				kind: "frames",
-				frames
-			})), setTimeout$1(Math.max(1, deadline - Date.now())).then(() => ({ kind: "timeout" }))]);
-			if (winner.kind === "timeout") break;
-			const incoming = decode(winner.frames);
-			if (incoming?.header.msg_type === "kernel_info_reply" && incoming.parent_header.msg_id === requestMsgId) return;
-		}
-		throw new Error(`kernel did not answer kernel_info_request within ${this.options.startupTimeoutMs}ms. stderr tail:\n${this.stderrTail()}`);
+		transport.send("shell", msg);
+		if (await transport.waitFor("shell", (incoming) => incoming.header.msg_type === "kernel_info_reply" && incoming.parent_header.msg_id === requestMsgId, this.options.startupTimeoutMs)) return;
+		const bridgeTail = transport.stderrTail();
+		if (this.state === "shutdown") throw new Error(`kernel exited during startup. kernel stderr:\n${this.stderrTail()}\nbridge stderr:\n${bridgeTail}`);
+		throw new Error(`kernel did not answer kernel_info_request within ${this.options.startupTimeoutMs}ms. kernel stderr:\n${this.stderrTail()}\nbridge stderr:\n${bridgeTail}`);
 	}
 	/**
 	* Execute one cell on the persistent kernel, serialized against all other
@@ -1165,9 +1373,8 @@ var IpyKernelBridge = class {
 		}
 	}
 	executeInner(code, opts) {
-		const conn = this.connection;
-		const shell = this.shell;
-		if (!conn || !shell) return Promise.resolve({
+		const transport = this.transport;
+		if (!transport) return Promise.resolve({
 			outcome: "forced",
 			failure: {
 				kind: "worker-exit",
@@ -1232,7 +1439,9 @@ var IpyKernelBridge = class {
 			opts.signal?.addEventListener("abort", onAbort, { once: true });
 			execution.detachSignal = () => opts.signal?.removeEventListener("abort", onAbort);
 			if (opts.signal?.aborted) onAbort();
-			shell.send(encode(msg, conn.key)).catch(() => {
+			try {
+				transport.send("shell", msg);
+			} catch {
 				settle({
 					outcome: "forced",
 					failure: {
@@ -1241,35 +1450,22 @@ var IpyKernelBridge = class {
 					},
 					streamText: execution.streamText
 				});
-			});
+			}
 		});
 	}
-	startIopubPump() {
-		if (this.iopubPump) return;
-		this.iopubPump = this.runIopubPump();
-	}
-	async runIopubPump() {
-		const iopub = this.iopub;
-		if (!iopub) return;
-		try {
-			for await (const frames of iopub) {
-				const incoming = decode(frames);
-				if (!incoming) continue;
-				const msgType = incoming.header.msg_type;
-				if (msgType === "comm_open" || msgType === "comm_msg" || msgType === "comm_close") {
-					this.handleCommMessage(incoming);
-					continue;
-				}
-				this.handleExecutionMessage(incoming);
-			}
-		} catch {
-			if (this.state !== "shutdown") this.forceSettleActive({
-				kind: "worker-exit",
-				message: "kernel iopub channel failed"
-			});
-		} finally {
-			if (this.iopub === iopub) this.iopubPump = void 0;
+	/**
+	* Route one relayed message. Only iopub drives executions and comms; shell
+	* replies serve the startup probe (via `waitFor`), and control is inbound
+	* for host replies.
+	*/
+	handleTransportMessage(channel, incoming) {
+		if (channel !== "iopub") return;
+		const msgType = incoming.header.msg_type;
+		if (msgType === "comm_open" || msgType === "comm_msg" || msgType === "comm_close") {
+			this.handleCommMessage(incoming);
+			return;
 		}
+		this.handleExecutionMessage(incoming);
 	}
 	forceSettleActive(failure) {
 		const execution = this.activeExec;
@@ -1385,12 +1581,12 @@ var IpyKernelBridge = class {
 		})().catch(() => void 0);
 	}
 	async replyComm(commId, data) {
-		const channel = this.control ?? this.shell;
-		if (!channel || !this.connection) throw new Error("kernel channels are not connected");
-		await channel.send(encode(buildMessage("comm_msg", {
+		const transport = this.transport;
+		if (!transport) throw new Error("kernel channels are not connected");
+		transport.send("control", buildMessage("comm_msg", {
 			comm_id: commId,
 			data
-		}, this.session, this.options.username), this.connection.key));
+		}, this.session, this.options.username));
 	}
 	/**
 	* Phase one NOW, phase two on a timer: send the control-channel interrupt,
@@ -1407,9 +1603,10 @@ var IpyKernelBridge = class {
 	* contract: a busy loop still breaks, one confirm window later.
 	*/
 	async sendInterrupt(execution) {
-		if (!this.control || !this.connection) return;
+		const transport = this.transport;
+		if (!transport) return;
 		try {
-			await this.control.send(encode(buildMessage("interrupt_request", {}, this.session, this.options.username), this.connection.key));
+			transport.interrupt();
 		} catch {}
 		execution.alarmTimer = setTimeout(() => {
 			if (execution.settled) return;
@@ -1650,13 +1847,8 @@ var IpyKernelBridge = class {
 		this.cleanupResources();
 	}
 	cleanupResources() {
-		this.shell?.close();
-		this.iopub?.close();
-		this.control?.close();
-		this.shell = void 0;
-		this.iopub = void 0;
-		this.control = void 0;
-		this.iopubPump = void 0;
+		this.transport?.dispose();
+		this.transport = void 0;
 		this.connection = void 0;
 		try {
 			this.kernel?.kill("SIGKILL");
@@ -1678,8 +1870,8 @@ var IpyKernelBridge = class {
 		}
 		this.state = "shutdown";
 		try {
-			if (this.control && this.connection) {
-				await this.control.send(encode(buildMessage("shutdown_request", { restart: false }, this.session, this.options.username), this.connection.key));
+			if (this.transport) {
+				this.transport.send("control", buildMessage("shutdown_request", { restart: false }, this.session, this.options.username));
 				await setTimeout$1(SHUTDOWN_DRAIN_MS);
 			}
 		} catch {}
@@ -1738,21 +1930,21 @@ function keyDirectoryName(principal) {
 * and shutdown of every key on plugin disposal — is effect-owned.
 */
 var DashrRuntime = class extends ReplRuntime {
-	static Config = z.object({
-		python: z.string().default("python3"),
-		startupTimeoutMs: z.number().default(3e4),
-		runTimeoutMs: z.number().default(12e4),
-		interruptGraceMs: z.number().default(2e3),
-		interruptConfirmMs: z.number().default(250),
-		disposeTimeoutMs: z.number().default(5e3),
-		snapshotTimeoutMs: z.number().default(3e4),
-		maxOutputBytes: z.number().default(67108864),
-		snapshotDir: z.string(),
-		snapshotSizeCapBytes: z.number().default(268435456),
-		kernelEnvDir: z.string(),
-		kernelPythonVersion: z.string(),
-		kernelAutoInstall: z.boolean().default(true),
-		username: z.string().default("dashr")
+	static Config = Schema.object({
+		python: Schema.string().default("python3"),
+		startupTimeoutMs: Schema.number().default(3e4),
+		runTimeoutMs: Schema.number().default(12e4),
+		interruptGraceMs: Schema.number().default(2e3),
+		interruptConfirmMs: Schema.number().default(250),
+		disposeTimeoutMs: Schema.number().default(5e3),
+		snapshotTimeoutMs: Schema.number().default(3e4),
+		maxOutputBytes: Schema.number().default(67108864),
+		snapshotDir: Schema.string(),
+		snapshotSizeCapBytes: Schema.number().default(268435456),
+		kernelEnvDir: Schema.string(),
+		kernelPythonVersion: Schema.string(),
+		kernelAutoInstall: Schema.boolean().default(true),
+		username: Schema.string().default("dashr")
 	});
 	language = "python";
 	isolation = "process";
@@ -2809,10 +3001,14 @@ function finishError(finish) {
 * output: the model's text (a bare string root), or a structured `{ error }`
 * object — never a thrown exception for bad input or a degraded finish.
 */
+/** Narrow a tool result to the success variant (for the model-facing render). */
+function isTextResult(value) {
+	return typeof value === "object" && value !== null && value.ok === true && typeof value.text === "string";
+}
 function createLlmCompletionTool(deps) {
 	return defineTool({
 		name: "llm_completion",
-		description: "One-shot stateless LLM call — no tools, no history, no agent. Give {prompt} (and optional {system}, {maxTokens}); get the model's text back. For judge steps, extraction, and handoff compression inside one cell, without spawning a subagent.",
+		description: "One-shot stateless LLM call — no tools, no history, no agent. Give {prompt} (and optional {system}, {maxTokens}); get a discriminated result back: {ok:true,text} on success or {ok:false,error} on failure, so a programmatic caller can branch without shape guessing (a direct tool call renders just the text on success). For judge steps, extraction, and handoff compression inside one cell, without spawning a subagent.",
 		parameters: {
 			prompt: {
 				type: "string",
@@ -2828,31 +3024,68 @@ function createLlmCompletionTool(deps) {
 			}
 		},
 		output: {
-			schema: { oneOf: [{ type: "string" }, {
+			schema: { oneOf: [{
+				type: "object",
+				properties: {
+					ok: {
+						type: "boolean",
+						required: true
+					},
+					text: {
+						type: "string",
+						required: true
+					}
+				},
+				additionalProperties: false
+			}, {
 				type: "object",
-				properties: { error: { type: "string" } },
+				properties: {
+					ok: {
+						type: "boolean",
+						required: true
+					},
+					error: {
+						type: "string",
+						required: true
+					}
+				},
 				additionalProperties: false
 			}] },
 			render: (_args, value) => [{
 				type: "text",
-				text: typeof value === "string" ? value : JSON.stringify(value, null, 2)
+				text: isTextResult(value) ? value.text : JSON.stringify(value, null, 2)
 			}]
 		},
 		execute: async (args, exec) => {
 			const a = args;
 			const prompt = a["prompt"];
-			if (typeof prompt !== "string" || prompt.length === 0) return { error: "llm_completion() requires {\"prompt\": \"...\"} — the one-shot prompt" };
+			if (typeof prompt !== "string" || prompt.length === 0) return {
+				ok: false,
+				error: "llm_completion() requires {\"prompt\": \"...\"} — the one-shot prompt"
+			};
 			const system = a["system"];
-			if (system !== void 0 && typeof system !== "string") return { error: "llm_completion() system must be a string" };
+			if (system !== void 0 && typeof system !== "string") return {
+				ok: false,
+				error: "llm_completion() system must be a string"
+			};
 			const maxTokens = a["maxTokens"] === void 0 ? MAX_COMPLETION_TOKENS : a["maxTokens"];
-			if (typeof maxTokens !== "number" || !Number.isSafeInteger(maxTokens) || maxTokens < 1 || maxTokens > MAX_COMPLETION_TOKENS) return { error: `llm_completion() maxTokens must be a positive safe integer no greater than ${MAX_COMPLETION_TOKENS}` };
+			if (typeof maxTokens !== "number" || !Number.isSafeInteger(maxTokens) || maxTokens < 1 || maxTokens > MAX_COMPLETION_TOKENS) return {
+				ok: false,
+				error: `llm_completion() maxTokens must be a positive safe integer no greater than ${MAX_COMPLETION_TOKENS}`
+			};
 			const llm = deps.requireLlm();
-			if (llm === void 0) return { error: "llm_completion() is unavailable: no ctx.llm service is mounted in this composition" };
+			if (llm === void 0) return {
+				ok: false,
+				error: "llm_completion() is unavailable: no ctx.llm service is mounted in this composition"
+			};
 			const agent = exec.agent;
 			const route = agent?.options;
 			const provider = route?.provider;
 			const model = route?.model;
-			if (typeof provider !== "string" || provider.length === 0 || typeof model !== "string" || model.length === 0) return { error: "llm_completion() requires a model route: the calling agent has no provider/model selected (a judge call runs on its caller's tier)" };
+			if (typeof provider !== "string" || provider.length === 0 || typeof model !== "string" || model.length === 0) return {
+				ok: false,
+				error: "llm_completion() requires a model route: the calling agent has no provider/model selected (a judge call runs on its caller's tier)"
+			};
 			const options = {
 				provider,
 				model,
@@ -2875,15 +3108,30 @@ function createLlmCompletionTool(deps) {
 					assembler.push(chunk);
 				}
 			} catch (error) {
-				return { error: `llm_completion() failed: ${error instanceof Error ? error.message : String(error)}` };
+				return {
+					ok: false,
+					error: `llm_completion() failed: ${error instanceof Error ? error.message : String(error)}`
+				};
 			}
 			const failure = finishError(assembler.finish);
-			if (failure !== "") return { error: failure };
+			if (failure !== "") return {
+				ok: false,
+				error: failure
+			};
 			const blocks = assembler.blocks();
-			if (blocks.some((block) => block.type === "tool-call")) return { error: "llm_completion() output must contain text only" };
+			if (blocks.some((block) => block.type === "tool-call")) return {
+				ok: false,
+				error: "llm_completion() output must contain text only"
+			};
 			const text = blocks.filter((block) => block.type === "text").map((block) => block.text).join(" ");
-			if (text.trim().length === 0) return { error: "llm_completion() produced no text" };
-			return text;
+			if (text.trim().length === 0) return {
+				ok: false,
+				error: "llm_completion() produced no text"
+			};
+			return {
+				ok: true,
+				text
+			};
 		}
 	});
 }
@@ -2899,7 +3147,7 @@ const name = "dashr-repl";
 */
 const inject = ["tools"];
 /** Runtime schema. */
-const Config = z.intersect([DashrRuntime.Config, z.object({ maxParallelSubCalls: z.natural().min(1).default(10) })]);
+const Config = Schema.intersect([DashrRuntime.Config, Schema.object({ maxParallelSubCalls: Schema.natural().min(1).default(10) })]);
 /** The model-facing name of the DASHR cell transport. */
 const EVAL_NAME = "eval";
 /**