A desktop coding agent with free access to frontier models.
TypeScript
// Ported from the CLI (omnirush-cli src/box/client.js, feat/local-box);
// keep the two in step. Only types were added here.
//
// The host side of boxd's wire format (box/go/proto): one TCP connection per
// operation, a JSON request line, then type+length frames. The engine's
// shell calls go through the native client (boxsh); this one is for the
// launcher: readiness, the snapshot's stat/walk/tar, and toolchain probes.
import { createHash } from "node:crypto";
import { once } from "node:events";
import { createWriteStream } from "node:fs";
import net from "node:net";
export const PROTO_VERSION = 1;
const T = { stdout: 0x6f, stderr: 0x65, exit: 0x78, data: 0x64, fail: 0x45, stdinEof: 0x63, signal: 0x73 };
export type BoxEndpoint = { host?: string; port: number; token: string };
export type BoxRequest = { op: string; argv?: string[]; cwd?: string; env?: Record<string, string>; paths?: string[]; wait?: number; root?: boolean };
export type BoxExit = { code: number; ms?: number };
export type BoxReply = { exit: BoxExit; stdout: string; stderr: string; data: Buffer };
export type BoxStat = { path: string; type: string; mode?: number; size?: number; uid?: number; gid?: number; link?: string; mtime_ns?: number | string; ctime_ns?: number | string };
export type BoxChange = BoxStat & { kind: "A" | "C" | "D" };
function frame(kind: number, payload = Buffer.alloc(0)): Buffer {
const head = Buffer.alloc(5);
head[0] = kind;
head.writeUInt32BE(payload.length, 1);
return Buffer.concat([head, payload]);
}
/**
* One operation: resolves { exit, stdout, stderr, data } where data is the
* concatenated Data frames (unless onData takes them). Rejects when the box
* cannot be reached or closes early. An onData that returns a promise holds
* the connection (backpressure) until it settles; a rejection fails the call.
*/
export function request(
box: BoxEndpoint,
req: BoxRequest,
{ onData, onStdout, onStderr, timeoutMs = 30_000, signal }: { onData?: (chunk: Buffer) => Promise<unknown> | null | void; onStdout?: (chunk: Buffer) => void; onStderr?: (chunk: Buffer) => void; timeoutMs?: number; signal?: AbortSignal } = {},
): Promise<BoxReply> {
return new Promise((resolve, reject) => {
const socket = net.connect({ host: box.host || "127.0.0.1", port: box.port });
socket.setNoDelay(true);
let buffered: Buffer = Buffer.alloc(0);
const out: Buffer[] = [];
const err: Buffer[] = [];
const data: Buffer[] = [];
let settled = false;
const finish = <V>(fn: (value: V) => void, value: V) => {
if (settled) return;
settled = true;
clearTimeout(timer);
signal?.removeEventListener?.("abort", onAbort);
socket.destroy();
fn(value);
};
const onAbort = () => finish(reject, new Error("aborted"));
signal?.addEventListener?.("abort", onAbort, { once: true });
const timer = setTimeout(() => finish(reject, new Error(`box ${req.op} timed out after ${timeoutMs} ms`)), timeoutMs);
socket.once("connect", () => {
socket.write(`${JSON.stringify({ v: PROTO_VERSION, token: box.token, ...req })}\n`);
if (req.op === "exec") socket.write(frame(T.stdinEof));
});
socket.on("error", (error) => finish(reject, error));
socket.on("close", () => finish(reject, new Error(`box closed the ${req.op} connection early`)));
socket.on("data", (chunk: Buffer) => {
buffered = buffered.length ? Buffer.concat([buffered, chunk]) : chunk;
while (buffered.length >= 5) {
const size = buffered.readUInt32BE(1);
if (buffered.length < 5 + size) break;
const kind = buffered[0];
const payload = buffered.subarray(5, 5 + size);
buffered = buffered.subarray(5 + size);
if (kind === T.stdout) (onStdout ? onStdout(payload) : out.push(Buffer.from(payload)));
else if (kind === T.stderr || kind === T.fail) (onStderr ? onStderr(payload) : err.push(Buffer.from(payload)));
else if (kind === T.data) {
if (onData) {
let wait: Promise<unknown> | null | void;
try { wait = onData(payload); } catch (error) { finish(reject, error); return; }
if (wait && typeof wait.then === "function" && !socket.isPaused()) {
socket.pause();
wait.then(() => { if (!settled) socket.resume(); }, (error: unknown) => finish(reject, error));
}
} else data.push(Buffer.from(payload));
} else if (kind === T.exit) {
let exit: BoxExit = { code: 0 };
try { exit = JSON.parse(payload.toString("utf8")); } catch { /* keep */ }
finish(resolve, { exit, stdout: Buffer.concat(out).toString("utf8"), stderr: Buffer.concat(err).toString("utf8"), data: Buffer.concat(data) });
return;
}
}
});
});
}
/** boxd's identity, or null when it does not answer. */
export async function ping(box: BoxEndpoint, { timeoutMs = 2_000 }: { timeoutMs?: number } = {}): Promise<Record<string, unknown> | null> {
try {
const result = await request(box, { op: "ping" }, { timeoutMs });
return JSON.parse(result.data.toString("utf8"));
} catch {
return null;
}
}
export type ExecResult = { code: number; stdout: string; stderr: string; ms?: number };
/** Run a command in the box: { code, stdout, stderr, ms }. */
export async function exec(box: BoxEndpoint, argv: string[], { cwd, env, root = false, timeoutMs = 60_000 }: { cwd?: string; env?: Record<string, string>; root?: boolean; timeoutMs?: number } = {}): Promise<ExecResult> {
const result = await request(box, { op: "exec", argv, ...(cwd ? { cwd } : {}), ...(env ? { env } : {}), ...(root ? { root: true } : {}) }, { timeoutMs });
return { code: result.exit.code, stdout: result.stdout, stderr: result.stderr, ms: result.exit.ms };
}
/** A listening TCP socket inside the box (op "ports"). */
export type BoxListener = { port: number; addr: string };
/**
* The box's listening TCP ports (boxd's own left out), or null when this
* box's boxd predates the request (a box made by an older version: Reset
* sandbox gives it the new helper). Rejects when the box cannot be reached.
*/
export async function listPorts(box: BoxEndpoint, { timeoutMs = 5_000 }: { timeoutMs?: number } = {}): Promise<BoxListener[] | null> {
const result = await request(box, { op: "ports" }, { timeoutMs });
if (result.exit.code !== 0) {
if (/unknown op/.test(result.stderr)) return null;
throw new Error(`box ports failed: ${result.stderr.trim() || result.exit.code}`);
}
const parsed: unknown = JSON.parse(result.data.toString("utf8") || "[]");
return Array.isArray(parsed) ? parsed.filter((item): item is BoxListener => Number.isInteger(item?.port)) : [];
}
/**
* A TCP stream to `port` inside the box, through boxd: resolves { socket,
* head } once boxd connected (socket paused; `head` is what already arrived
* after boxd's answer and goes first), rejects with boxd's reason otherwise.
*/
export function connectPort(box: BoxEndpoint, port: number, { timeoutMs = 5_000 }: { timeoutMs?: number } = {}): Promise<{ socket: net.Socket; head: Buffer }> {
return new Promise((resolve, reject) => {
const socket = net.connect({ host: box.host || "127.0.0.1", port: box.port, allowHalfOpen: true });
socket.setNoDelay(true);
let buffered: Buffer = Buffer.alloc(0);
let settled = false;
const failText: string[] = [];
const done = (error: Error | null, value?: { socket: net.Socket; head: Buffer }) => {
if (settled) return;
settled = true;
clearTimeout(timer);
socket.removeListener("data", onData);
socket.removeListener("error", onError);
socket.removeListener("close", onClose);
if (error || !value) { socket.destroy(); reject(error ?? new Error("box connect failed")); } else resolve(value);
};
const timer = setTimeout(() => done(new Error(`box connect to port ${port} timed out after ${timeoutMs} ms`)), timeoutMs);
const onError = (error: Error) => done(error);
const onClose = () => done(new Error(`box closed the connect to port ${port} early`));
const onData = (chunk: Buffer) => {
buffered = buffered.length ? Buffer.concat([buffered, chunk]) : chunk;
while (buffered.length >= 5) {
const size = buffered.readUInt32BE(1);
if (buffered.length < 5 + size) return;
const kind = buffered[0];
const payload = buffered.subarray(5, 5 + size);
buffered = buffered.subarray(5 + size);
if (kind === T.data) {
socket.pause();
done(null, { socket, head: Buffer.from(buffered) });
return;
}
if (kind === T.fail || kind === T.stderr) failText.push(payload.toString("utf8"));
else if (kind === T.exit) { done(new Error(failText.join("").trim() || `box could not connect to port ${port}`)); return; }
}
};
socket.once("connect", () => socket.write(`${JSON.stringify({ v: PROTO_VERSION, token: box.token, op: "connect", port })}\n`));
socket.on("data", onData);
socket.on("error", onError);
socket.on("close", onClose);
});
}
/** lstat of each path, in order (type "missing" for a path that is gone). */
export async function stat(box: BoxEndpoint, paths: string[], { timeoutMs = 60_000, budget = REQUEST_LINE_BUDGET }: { timeoutMs?: number; budget?: number } = {}): Promise<BoxStat[]> {
const out: BoxStat[] = [];
const { batches, skipped } = batchPaths(paths, { budget, overhead: lineOverhead(box, { op: "stat" }) });
// A path no request can carry (never in practice: a path is at most 4 KiB) is "other": not looked at.
const tooLong = new Set(skipped.map((item) => item.path));
const answers = new Map<string, BoxStat>();
for (const part of batches) {
const result = await request(box, { op: "stat", paths: part }, { timeoutMs });
const entries: BoxStat[] = JSON.parse(result.data.toString("utf8"));
if (!tooLong.size) out.push(...entries);
else for (const entry of entries) answers.set(entry.path, entry);
}
if (!tooLong.size) return out;
return paths.map((p) => answers.get(p) ?? { path: p, type: "other", uid: 0, gid: 0 });
}
/**
* What differs from the image ({ kind: A|C|D, path, ...stat }), walked by
* boxd against the index it took at the box's first start; `skip` folders
* are not walked (their `keep` subfolders are). Null when boxd cannot (an
* older box with no index): the caller uses the runtime's `diff`.
*/
export async function changes(box: BoxEndpoint, skip: string[], keep: string[], { timeoutMs = 120_000 }: { timeoutMs?: number } = {}): Promise<BoxChange[] | null> {
try {
const result = await request(box, { op: "changes", paths: skip, env: { keep: keep.join(",") } }, { timeoutMs });
if (result.exit.code !== 0) return null;
return JSON.parse(result.data.toString("utf8"));
} catch {
return null;
}
}
/** Every entry below the folders, stat fields included. */
export async function walk(box: BoxEndpoint, roots: string[], { max = 400_000, timeoutMs = 120_000, budget = REQUEST_LINE_BUDGET }: { max?: number; timeoutMs?: number; budget?: number } = {}): Promise<{ entries?: BoxStat[]; truncated?: boolean }> {
const { batches } = batchPaths(roots, { budget, overhead: lineOverhead(box, { op: "walk", wait: max }) });
if (batches.length <= 1) {
const result = await request(box, { op: "walk", paths: batches[0] ?? [], wait: max }, { timeoutMs });
return JSON.parse(result.data.toString("utf8"));
}
const entries: BoxStat[] = [];
let truncated = false;
for (const part of batches) {
const left = max - entries.length;
if (left <= 0) { truncated = true; break; }
const result = await request(box, { op: "walk", paths: part, wait: left }, { timeoutMs });
const parsed: { entries?: BoxStat[]; truncated?: boolean } = JSON.parse(result.data.toString("utf8"));
entries.push(...(parsed.entries ?? []));
if (parsed.truncated) { truncated = true; break; }
}
return { entries, truncated };
}
export type TarResult = { bytes: number; sha256: string; ms?: number; warning: string | null; skipped?: SkippedPath[] };
/**
* Tar exactly these paths into `file`: { bytes, sha256, ms, warning } (and
* `skipped`, the paths no request could carry). The tar streams to disk: the
* box's connection waits while the file catches up. Many paths go in several
* requests (each line within the budget), written one after the other as a
* single archive: each part but the last loses its end-of-archive marker.
* The paths go in byte order (boxd's), so a folder comes before what is in it.
*/
export async function tarTo(box: BoxEndpoint, paths: string[], file: string, { timeoutMs = 15 * 60_000, budget = REQUEST_LINE_BUDGET }: { timeoutMs?: number; budget?: number } = {}): Promise<TarResult> {
const { batches, skipped } = batchPaths(byteSorted(paths), { budget, overhead: lineOverhead(box, { op: "tar" }) });
const stream = createWriteStream(file, { mode: 0o600 });
const hash = createHash("sha256");
const controller = new AbortController();
let bytes = 0;
let draining: Promise<unknown> | null = null;
let failed: Error | null = null;
stream.on("error", (error) => {
failed ??= error;
controller.abort();
});
await once(stream, "open");
const write = (pieces: Buffer[]): Promise<unknown> | null => {
if (!pieces.length) return draining;
const copy = Buffer.concat(pieces);
hash.update(copy);
bytes += copy.length;
// One drain wait at a time, however many frames arrive before it.
if (!stream.write(copy) && !draining) {
draining = once(stream, "drain").finally(() => { draining = null; });
draining.catch(() => undefined); // a write error is `failed`
}
return draining;
};
let ms: number | undefined;
const warnings: string[] = [];
try {
// Nothing any request could carry: still a valid (empty) archive.
if (!batches.length) await write([Buffer.alloc(1024)]);
for (let index = 0; index < batches.length; index += 1) {
const body = index < batches.length - 1 ? archiveBody() : null;
let result: BoxReply;
try {
result = await request(box, { op: "tar", paths: batches[index] }, {
timeoutMs,
signal: controller.signal,
onData: (chunk) => write(body ? body.push(chunk) : [chunk]),
});
} catch (error) {
throw failed ?? error;
}
if (failed) throw failed;
if (result.exit.code !== 0) throw new Error(`box tar failed: ${result.stderr.trim() || result.exit.code}${batches.length > 1 ? ` (part ${index + 1} of ${batches.length})` : ""}`);
body?.end();
if (typeof result.exit.ms === "number") ms = (ms ?? 0) + result.exit.ms;
const warning = result.stderr.trim();
if (warning && !warnings.includes(warning)) warnings.push(warning);
}
} finally {
await new Promise<void>((resolve) => stream.end(() => resolve()));
}
if (failed) throw failed;
return { bytes, sha256: hash.digest("hex"), ms, warning: warnings.join("\n") || null, ...(skipped.length ? { skipped } : {}) };
}
// --- path lists in requests -------------------------------------------------------
/**
* boxd reads a request line of at most 4 MiB (box/go/proto ReadRequest; 16
* MiB from this version on, but a box may run an older boxd): a list of
* paths goes in requests whose line stays well under it.
*/
export const REQUEST_LINE_MAX = 4 << 20;
export const REQUEST_LINE_BUDGET = 3 << 20;
export type SkippedPath = { path: string; reason: string };
/** The bytes of a request's line (newline included) with no paths. */
export function lineOverhead(box: BoxEndpoint, req: BoxRequest): number {
return Buffer.byteLength(JSON.stringify({ v: PROTO_VERSION, token: box.token, ...req, paths: [] })) + 1;
}
/**
* `paths` in order, cut into batches whose request line (`overhead` plus the
* JSON of the list, newline included) stays within `budget` bytes. A path
* that alone does not fit is left out: { batches, skipped }.
*/
export function batchPaths(paths: string[], { budget = REQUEST_LINE_BUDGET, overhead = 0 }: { budget?: number; overhead?: number } = {}): { batches: string[][]; skipped: SkippedPath[] } {
const batches: string[][] = [];
const skipped: SkippedPath[] = [];
let current: string[] = [];
let size = overhead;
for (const p of paths) {
// Its JSON string, and the comma before it unless it starts a batch.
const bytes = Buffer.byteLength(JSON.stringify(p));
if (overhead + bytes > budget) { skipped.push({ path: p, reason: "path_too_long" }); continue; }
if (current.length && size + bytes + 1 > budget) {
batches.push(current);
current = [];
size = overhead;
}
size += bytes + (current.length ? 1 : 0);
current.push(p);
}
if (current.length) batches.push(current);
return { batches, skipped };
}
/** Sorted by their UTF-8 bytes (Go's sort.Strings, what boxd's tar uses). */
export function byteSorted(paths: string[]): string[] {
return paths.map((p) => [Buffer.from(p, "utf8"), p] as const).sort((a, b) => Buffer.compare(a[0], b[0])).map((item) => item[1]);
}
// Entry types with no data, whatever their size field says (Go's archive/tar reader).
const HEADER_ONLY = new Set([0x31, 0x32, 0x33, 0x34, 0x35, 0x36]);
/** A tar header's numeric field: octal text, or base-256 (high bit set). */
function tarNumber(field: Buffer): number {
if ((field[0] ?? 0) & 0x80) {
let value = BigInt((field[0] ?? 0) & 0x7f);
for (let i = 1; i < field.length; i += 1) value = (value << 8n) | BigInt(field[i] ?? 0);
return Number(value);
}
const text = field.toString("latin1").replace(/[\0 ]+$/g, "").replace(/^[\0 ]+/, "");
if (!/^[0-7]*$/.test(text)) throw new Error("box tar: a header has a bad number");
return text ? parseInt(text, 8) : 0;
}
/** The `size` record of a PAX extended header's data, or null. */
function paxSize(data: Buffer): number | null {
let at = 0;
while (at < data.length) {
const space = data.indexOf(0x20, at);
if (space < 0) break;
const length = Number(data.subarray(at, space).toString("latin1"));
if (!Number.isInteger(length) || length <= 0 || at + length > data.length) break;
const record = data.subarray(space + 1, at + length - 1).toString("utf8");
const eq = record.indexOf("=");
if (eq > 0 && record.slice(0, eq) === "size") {
const value = Number(record.slice(eq + 1));
if (Number.isSafeInteger(value) && value >= 0) return value;
}
at += length;
}
return null;
}
/**
* One part of a tar written in several: passes the archive through up to its
* end-of-archive marker (the first all-zero header block) and drops the
* marker and the zero padding after it, so the next part follows on as the
* same archive. push(chunk) -> the pieces to write; end() throws when the
* part did not end as an archive does.
*/
export function archiveBody(): { push: (chunk: Buffer) => Buffer[]; end: () => void } {
const block = Buffer.alloc(512);
let filled = 0;
let left = 0;
let pax: Buffer[] | null = null;
let paxLength = 0;
let nextSize: number | null = null;
let ended = false;
return {
push(chunk) {
const out: Buffer[] = [];
let i = 0;
while (i < chunk.length) {
if (ended) {
for (; i < chunk.length; i += 1) if (chunk[i] !== 0) throw new Error("box tar: data after the end of the archive");
break;
}
if (left > 0) {
const n = Math.min(left, chunk.length - i);
const piece = chunk.subarray(i, i + n);
out.push(piece);
if (pax) pax.push(Buffer.from(piece));
left -= n;
i += n;
if (left === 0 && pax) {
nextSize = paxSize(Buffer.concat(pax).subarray(0, paxLength));
pax = null;
}
continue;
}
const n = Math.min(512 - filled, chunk.length - i);
chunk.copy(block, filled, i, i + n);
filled += n;
i += n;
if (filled < 512) break;
filled = 0;
if (!block.some((byte) => byte !== 0)) { ended = true; continue; }
let sum = 0;
for (let k = 0; k < 512; k += 1) sum += k >= 148 && k < 156 ? 0x20 : block[k] ?? 0;
if (tarNumber(block.subarray(148, 156)) !== sum) throw new Error("box tar: a header's checksum does not match");
const type = block[156] ?? 0;
let size = tarNumber(block.subarray(124, 136));
const extended = type === 0x78 || type === 0x67; // x, g
if (!extended && nextSize !== null) { size = nextSize; nextSize = null; }
if (HEADER_ONLY.has(type)) size = 0;
out.push(Buffer.from(block));
left = Math.ceil(size / 512) * 512;
if (type === 0x78 && size > 0) {
if (size > 8 << 20) throw new Error("box tar: an extended header is too large");
pax = [];
paxLength = size;
}
}
return out;
},
end() {
if (!ended) throw new Error("box tar: a part ended before its end-of-archive marker");
},
};
}