init pinned pi sandbox runtime

Dockerfile

@@ -0,0 +1,21 @@
+FROM node:22-bookworm-slim
+
+ARG PI_VERSION=0.84.2
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends ca-certificates curl git openssh-client ripgrep \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /opt/chat-ui-agent
+RUN npm init -y \
+    && npm install --omit=dev --no-audit --no-fund \
+      "@earendil-works/pi-coding-agent@${PI_VERSION}" \
+      "ws@8.18.3" \
+    && ln -s /opt/chat-ui-agent/node_modules/.bin/pi /usr/local/bin/pi
+
+COPY bridge.mjs runtime-health.mjs /opt/chat-ui-agent/
+
+ENV PI_TELEMETRY=0
+EXPOSE 7860
+CMD ["node", "/opt/chat-ui-agent/runtime-health.mjs"]
+

README.md

@@ -1,10 +1,16 @@
 ---
-title: Chat Ui Agent Runtime
-emoji: ⚡
+title: Chat UI Agent Runtime
+emoji: 🧰
 colorFrom: yellow
-colorTo: pink
+colorTo: indigo
 sdk: docker
-pinned: false
+short_description: Pinned pi runtime image for chat-ui sandboxes
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Chat UI Agent Runtime
+
+Prebuilt Node, git, ripgrep, pi, and reconnect-safe RPC bridge image used by chat-ui Agent
+workspaces. The Space itself exposes a small health endpoint; Hugging Face Jobs overrides the
+command to start `sbx-server`, then chat-ui spawns `bridge.mjs` inside the dedicated sandbox.
+
+No Hugging Face or provider credential is baked into this image.

bridge.mjs

@@ -0,0 +1,232 @@
+import http from "node:http";
+import { spawn } from "node:child_process";
+import process from "node:process";
+import { WebSocketServer, WebSocket } from "ws";
+
+const PORT = parsePositiveInt(process.env.BRIDGE_PORT, 4777);
+const HOST = process.env.BRIDGE_HOST || "127.0.0.1";
+const WORKSPACE = process.env.WORKSPACE_DIR || "/workspace";
+const PI_BIN = process.env.PI_BIN || "pi";
+const MAX_EVENTS = parsePositiveInt(process.env.BRIDGE_MAX_EVENTS, 5_000);
+const MAX_BUFFER_BYTES = parsePositiveInt(process.env.BRIDGE_MAX_BUFFER_BYTES, 8 * 1024 * 1024);
+const MAX_LINE_BYTES = parsePositiveInt(process.env.BRIDGE_MAX_LINE_BYTES, 1024 * 1024);
+const WS_HIGH_WATER_BYTES = parsePositiveInt(process.env.BRIDGE_WS_HIGH_WATER_BYTES, 4 * 1024 * 1024);
+
+const piPrefixArgs = parseStringArray(process.env.PI_BIN_PREFIX_ARGS_JSON);
+const piArgs = [...piPrefixArgs, "--mode", "rpc", "--approve"];
+if (process.env.PI_PROVIDER) piArgs.push("--provider", process.env.PI_PROVIDER);
+if (process.env.PI_MODEL) piArgs.push("--model", process.env.PI_MODEL);
+if (process.env.PI_SESSION_DIR) piArgs.push("--session-dir", process.env.PI_SESSION_DIR);
+if (process.env.PI_SESSION_NAME) piArgs.push("--name", process.env.PI_SESSION_NAME);
+if (process.env.PI_CONTINUE === "1") piArgs.push("--continue");
+
+let nextSequence = 1;
+let bufferedBytes = 0;
+let stdoutBuffer = "";
+const replayBuffer = [];
+const sockets = new Set();
+
+const pi = spawn(PI_BIN, piArgs, {
+	cwd: WORKSPACE,
+	env: {
+		...process.env,
+		PI_TELEMETRY: process.env.PI_TELEMETRY ?? "0",
+	},
+	stdio: ["pipe", "pipe", "pipe"],
+});
+
+const server = http.createServer((request, response) => {
+	if (request.url === "/health") {
+		response.writeHead(pi.exitCode === null ? 200 : 503, { "Content-Type": "application/json" });
+		response.end(
+			JSON.stringify({
+				status: pi.exitCode === null ? "ready" : "stopped",
+				pid: pi.pid,
+				sequence: nextSequence - 1,
+			})
+		);
+		return;
+	}
+	response.writeHead(404).end();
+});
+
+const webSockets = new WebSocketServer({ server, path: "/ws", maxPayload: MAX_LINE_BYTES });
+
+webSockets.on("connection", (socket, request) => {
+	sockets.add(socket);
+	const requestUrl = new URL(request.url ?? "/ws", "http://bridge.local");
+	const fromSequence = parseNonNegativeInt(requestUrl.searchParams.get("fromSeq"), 0);
+
+	send(socket, {
+		type: "bridge_ready",
+		pid: pi.pid,
+		fromSeq: replayBuffer.at(0)?.seq ?? nextSequence,
+		toSeq: nextSequence - 1,
+		piExited: pi.exitCode !== null,
+	});
+	for (const record of replayBuffer) {
+		if (record.seq > fromSequence) sendRecord(socket, record);
+	}
+
+	socket.on("message", (raw, isBinary) => {
+		if (isBinary) {
+			send(socket, { type: "bridge_error", message: "Binary RPC commands are not supported" });
+			return;
+		}
+		const text = raw.toString("utf8");
+		if (Buffer.byteLength(text) > MAX_LINE_BYTES) {
+			send(socket, { type: "bridge_error", message: "RPC command exceeds bridge limit" });
+			return;
+		}
+		let command;
+		try {
+			command = JSON.parse(text);
+		} catch {
+			send(socket, { type: "bridge_error", message: "RPC command must be valid JSON" });
+			return;
+		}
+		if (!command || typeof command !== "object" || Array.isArray(command)) {
+			send(socket, { type: "bridge_error", message: "RPC command must be an object" });
+			return;
+		}
+		if (command.type === "bridge_ping") {
+			send(socket, { type: "bridge_pong", sequence: nextSequence - 1 });
+			return;
+		}
+		if (command.type === "bridge_state") {
+			send(socket, {
+				type: "bridge_state",
+				pid: pi.pid,
+				fromSeq: replayBuffer.at(0)?.seq ?? nextSequence,
+				toSeq: nextSequence - 1,
+				piExited: pi.exitCode !== null,
+			});
+			return;
+		}
+		if (!pi.stdin.writable || pi.exitCode !== null) {
+			send(socket, { type: "bridge_error", message: "pi is not running" });
+			return;
+		}
+		pi.stdin.write(`${JSON.stringify(command)}\n`);
+	});
+
+	socket.on("close", () => {
+		sockets.delete(socket);
+	});
+});
+
+pi.stdout.on("data", (chunk) => {
+	stdoutBuffer += chunk.toString("utf8");
+	let newline = stdoutBuffer.indexOf("\n");
+	while (newline !== -1) {
+		const line = stdoutBuffer.slice(0, newline).replace(/\r$/, "");
+		stdoutBuffer = stdoutBuffer.slice(newline + 1);
+		handlePiLine(line);
+		newline = stdoutBuffer.indexOf("\n");
+	}
+	if (Buffer.byteLength(stdoutBuffer) > MAX_LINE_BYTES) {
+		record({ type: "bridge_error", message: "pi emitted an oversized JSONL record" });
+		stdoutBuffer = "";
+	}
+});
+
+pi.stderr.on("data", (chunk) => {
+	const data = chunk.toString("utf8");
+	record({
+		type: "bridge_stderr",
+		data: truncateUtf8(data, Math.min(MAX_LINE_BYTES, 64 * 1024)),
+	});
+});
+
+pi.on("error", (error) => {
+	record({ type: "bridge_error", message: `Unable to start pi: ${error.message}` });
+});
+
+pi.on("exit", (code, signal) => {
+	record({ type: "bridge_exit", exitCode: code, signal });
+});
+
+server.listen(PORT, HOST);
+
+function handlePiLine(line) {
+	if (!line) return;
+	if (Buffer.byteLength(line) > MAX_LINE_BYTES) {
+		record({ type: "bridge_error", message: "pi emitted an oversized JSONL record" });
+		return;
+	}
+	try {
+		record(JSON.parse(line));
+	} catch {
+		record({
+			type: "bridge_error",
+			message: "pi emitted invalid JSONL",
+			preview: truncateUtf8(line, 2_000),
+		});
+	}
+}
+
+function record(payload) {
+	const record = { seq: nextSequence++, payload };
+	const bytes = Buffer.byteLength(JSON.stringify(record));
+	replayBuffer.push({ ...record, bytes });
+	bufferedBytes += bytes;
+	while (replayBuffer.length > MAX_EVENTS || bufferedBytes > MAX_BUFFER_BYTES) {
+		const removed = replayBuffer.shift();
+		bufferedBytes -= removed?.bytes ?? 0;
+	}
+	for (const socket of sockets) {
+		if (socket.readyState === WebSocket.OPEN) sendRecord(socket, record);
+	}
+}
+
+function sendRecord(socket, record) {
+	if (socket.bufferedAmount > WS_HIGH_WATER_BYTES) {
+		// The replay buffer remains authoritative. Closing forces a reconnect with
+		// fromSeq instead of letting unbounded WebSocket backpressure consume RAM.
+		socket.close(1013, "Controller is too slow; reconnect to replay");
+		return;
+	}
+	send(socket, { type: "bridge_event", seq: record.seq, payload: record.payload });
+}
+
+function send(socket, value) {
+	if (socket.readyState === WebSocket.OPEN) socket.send(JSON.stringify(value));
+}
+
+function truncateUtf8(value, maxBytes) {
+	const bytes = Buffer.from(value);
+	if (bytes.length <= maxBytes) return value;
+	return `${bytes.subarray(0, maxBytes).toString("utf8")}\n… output truncated by bridge`;
+}
+
+function parsePositiveInt(value, fallback) {
+	const parsed = Number.parseInt(value ?? "", 10);
+	return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+
+function parseNonNegativeInt(value, fallback) {
+	const parsed = Number.parseInt(value ?? "", 10);
+	return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback;
+}
+
+function parseStringArray(value) {
+	if (!value) return [];
+	try {
+		const parsed = JSON.parse(value);
+		return Array.isArray(parsed) && parsed.every((entry) => typeof entry === "string") ? parsed : [];
+	} catch {
+		return [];
+	}
+}
+
+function shutdown() {
+	webSockets.close();
+	server.close();
+	if (pi.exitCode === null) pi.kill("SIGTERM");
+	setTimeout(() => {
+		if (pi.exitCode === null) pi.kill("SIGKILL");
+	}, 5_000).unref();
+}
+
+process.once("SIGTERM", shutdown);
+process.once("SIGINT", shutdown);

fake-pi.mjs

@@ -0,0 +1,40 @@
+let buffer = "";
+
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+	buffer += chunk;
+	let newline = buffer.indexOf("\n");
+	while (newline !== -1) {
+		const line = buffer.slice(0, newline).replace(/\r$/, "");
+		buffer = buffer.slice(newline + 1);
+		if (line) handle(line);
+		newline = buffer.indexOf("\n");
+	}
+});
+
+function handle(line) {
+	const command = JSON.parse(line);
+	if (command.type === "emit_later") {
+		write({
+			id: command.id,
+			type: "response",
+			command: command.type,
+			success: true,
+		});
+		setTimeout(() => {
+			write({ type: "queue_update", steering: [command.message], followUp: [] });
+		}, 75);
+		return;
+	}
+	write({
+		id: command.id,
+		type: "response",
+		command: command.type,
+		success: true,
+		data: { echo: command.message },
+	});
+}
+
+function write(value) {
+	process.stdout.write(`${JSON.stringify(value)}\n`);
+}

runtime-health.mjs

@@ -0,0 +1,9 @@
+import http from "node:http";
+
+const server = http.createServer((_request, response) => {
+	response.writeHead(200, { "Content-Type": "text/plain; charset=utf-8" });
+	response.end("chat-ui agent runtime image is ready\n");
+});
+
+server.listen(7860, "0.0.0.0");
+