@wardby/cli 0.5.2 → 0.6.0

package/dist/native-worker/stdio.js

@@ -0,0 +1,188 @@
+/**
+ * The worker contract over a child process's stdin/stdout, as newline-delimited
+ * JSON. The control plane writes the WorkerInput as the first line, then
+ * answers the worker's requests; the worker writes requests and reads answers.
+ * Both directions are capped at MAX_MESSAGE_BYTES per line. stderr is the
+ * worker's diagnostics only.
+ *
+ * Frames, worker → control:  { id, request }
+ * Frames, control → worker:  { id, ok: true, result } | { id, ok: false, error: { code, message } }
+ *                            | { id, event }  (llm.stream events)  | { id, end: true }
+ */
+import { spawn } from "node:child_process";
+import { GatewayError, MAX_MESSAGE_BYTES, ProtocolError, } from "./protocol.js";
+/** Splits a byte stream into lines, refusing any line over the cap. */
+export function readLines(stream, onLine, onError) {
+    let buffer = "";
+    stream.setEncoding("utf8");
+    stream.on("data", (chunk) => {
+        buffer += chunk;
+        let newline;
+        while ((newline = buffer.indexOf("\n")) >= 0) {
+            const line = buffer.slice(0, newline);
+            buffer = buffer.slice(newline + 1);
+            if (line)
+                onLine(line);
+        }
+        if (Buffer.byteLength(buffer) > MAX_MESSAGE_BYTES) {
+            buffer = "";
+            onError(new ProtocolError("message_too_large"));
+        }
+    });
+}
+function writeLine(stream, frame) {
+    const line = JSON.stringify(frame);
+    if (Buffer.byteLength(line) > MAX_MESSAGE_BYTES)
+        throw new ProtocolError("message_too_large");
+    stream.write(`${line}\n`);
+}
+const errorFrame = (err) => {
+    const gatewayError = err instanceof GatewayError ? err : new GatewayError("internal", err instanceof Error ? err.message : String(err));
+    return { code: gatewayError.code, message: gatewayError.message };
+};
+/** The worker's side: requests out on `output`, answers in on `input`. */
+export function createStdioTransport(input, output) {
+    let nextId = 0;
+    const pending = new Map();
+    const failAll = (err) => {
+        for (const entry of pending.values())
+            (entry.kind === "call" ? entry.reject : entry.fail)(err);
+        pending.clear();
+    };
+    readLines(input, (line) => {
+        let frame;
+        try {
+            frame = JSON.parse(line);
+        }
+        catch {
+            failAll(new ProtocolError("message_not_json"));
+            return;
+        }
+        const entry = pending.get(frame.id);
+        if (!entry)
+            return;
+        const error = frame.error
+            ? new GatewayError(frame.error.code, frame.error.message)
+            : undefined;
+        if (entry.kind === "call") {
+            pending.delete(frame.id);
+            if (error)
+                entry.reject(error);
+            else
+                entry.resolve(frame.result ?? null);
+        }
+        else if (frame.event) {
+            entry.push(frame.event);
+        }
+        else {
+            pending.delete(frame.id);
+            if (error)
+                entry.fail(error);
+            else
+                entry.end();
+        }
+    }, failAll);
+    input.on("end", () => failAll(new GatewayError("internal", "The gateway connection closed.")));
+    return {
+        call(request) {
+            const id = ++nextId;
+            return new Promise((resolve, reject) => {
+                pending.set(id, { kind: "call", resolve, reject });
+                writeLine(output, { id, request });
+            });
+        },
+        async *stream(request) {
+            const id = ++nextId;
+            const queue = [];
+            let done = false;
+            let failure;
+            let wake;
+            const notify = () => {
+                wake?.();
+                wake = undefined;
+            };
+            pending.set(id, {
+                kind: "stream",
+                push: (event) => {
+                    queue.push(event);
+                    notify();
+                },
+                end: () => {
+                    done = true;
+                    notify();
+                },
+                fail: (err) => {
+                    failure = err;
+                    notify();
+                },
+            });
+            writeLine(output, { id, request });
+            for (;;) {
+                if (queue.length > 0) {
+                    yield queue.shift();
+                    continue;
+                }
+                if (failure)
+                    throw failure;
+                if (done)
+                    return;
+                await new Promise((resolve) => (wake = resolve));
+            }
+        },
+    };
+}
+/** Serves one worker's requests from `gateway`, answering on `output`. */
+export function serveStdioWorker(input, output, gateway) {
+    readLines(input, (line) => {
+        let frame;
+        try {
+            frame = JSON.parse(line);
+        }
+        catch {
+            return; // An unparseable line has no id to answer; the worker's own call times out with its process.
+        }
+        const { id, request } = frame;
+        const method = request?.method;
+        if (method === "llm.stream") {
+            void (async () => {
+                try {
+                    for await (const event of gateway.stream(request))
+                        writeLine(output, { id, event });
+                    writeLine(output, { id, end: true });
+                }
+                catch (err) {
+                    writeLine(output, { id, ok: false, error: errorFrame(err) });
+                }
+            })();
+            return;
+        }
+        void gateway.call(request).then((result) => writeLine(output, { id, ok: true, result: result ?? null }), (err) => writeLine(output, { id, ok: false, error: errorFrame(err) }));
+    }, () => {
+        // An oversized line from the worker: drop it; the worker is killed with its run.
+    });
+}
+/** Launches the worker as a child process speaking this transport on its stdio. */
+export function createProcessLauncher(spec) {
+    return {
+        run(input, gateway, signal) {
+            return new Promise((resolve) => {
+                const child = spawn(spec.command, spec.args, {
+                    env: spec.env ?? {},
+                    cwd: spec.cwd,
+                    stdio: ["pipe", "pipe", "inherit"],
+                });
+                const kill = () => child.kill("SIGKILL");
+                signal.addEventListener("abort", kill, { once: true });
+                child.on("error", () => resolve({ exitCode: null }));
+                child.on("exit", (code) => {
+                    signal.removeEventListener("abort", kill);
+                    resolve({ exitCode: code });
+                });
+                // A worker that exits mid-answer closes its stdin under a pending write: not an error here.
+                child.stdin.on("error", () => { });
+                serveStdioWorker(child.stdout, child.stdin, gateway);
+                writeLine(child.stdin, input);
+            });
+        },
+    };
+}

package/dist/native-worker/warm-delivery.d.ts

@@ -0,0 +1,16 @@
+/**
+ * How a claimed warm worker gets its input (native sandbox phase 6): the launcher runs this fixed
+ * command inside the worker's container (`docker exec -i`, or the Kubernetes exec API) with the
+ * WorkerInput on stdin. The capability is never in the command, so it stays out of argv, the
+ * environment, and Kubernetes audit logs. The file is written under a temporary name and hard-linked into
+ * place (a link, unlike a rename, never replaces an existing file), so the waiting worker never
+ * reads half of it, and a second delivery to one worker fails.
+ */
+/** Where a pool worker waits for its input: /tmp is its only writable filesystem. */
+export declare const WARM_INPUT_DIR = "/tmp/wardby-input";
+export declare const WARM_INPUT_FILE = "/tmp/wardby-input/input.json";
+/** The worker's exit code when no input arrived within NATIVE_WORKER_INPUT_WAIT_MS. */
+export declare const WARM_WORKER_UNCLAIMED_EXIT = 75;
+/** The delivery command's exit code when the worker already has an input. */
+export declare const WARM_DELIVERY_ALREADY_DELIVERED = 2;
+export declare function warmDeliveryCommand(file?: string): string[];

package/dist/native-worker/warm-delivery.js

@@ -0,0 +1,33 @@
+/**
+ * How a claimed warm worker gets its input (native sandbox phase 6): the launcher runs this fixed
+ * command inside the worker's container (`docker exec -i`, or the Kubernetes exec API) with the
+ * WorkerInput on stdin. The capability is never in the command, so it stays out of argv, the
+ * environment, and Kubernetes audit logs. The file is written under a temporary name and hard-linked into
+ * place (a link, unlike a rename, never replaces an existing file), so the waiting worker never
+ * reads half of it, and a second delivery to one worker fails.
+ */
+/** Where a pool worker waits for its input: /tmp is its only writable filesystem. */
+export const WARM_INPUT_DIR = "/tmp/wardby-input";
+export const WARM_INPUT_FILE = `${WARM_INPUT_DIR}/input.json`;
+/** The worker's exit code when no input arrived within NATIVE_WORKER_INPUT_WAIT_MS. */
+export const WARM_WORKER_UNCLAIMED_EXIT = 75;
+/** The delivery command's exit code when the worker already has an input. */
+export const WARM_DELIVERY_ALREADY_DELIVERED = 2;
+export function warmDeliveryCommand(file = WARM_INPUT_FILE) {
+    const script = [
+        'const fs = require("node:fs");',
+        'const path = require("node:path");',
+        `const file = ${JSON.stringify(file)};`,
+        `if (fs.existsSync(file)) process.exit(${WARM_DELIVERY_ALREADY_DELIVERED});`,
+        "fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });",
+        "const chunks = [];",
+        "process.stdin.on('data', (c) => chunks.push(c));",
+        "process.stdin.on('end', () => {",
+        "  const tmp = `${file}.partial`;",
+        "  fs.writeFileSync(tmp, Buffer.concat(chunks), { flag: 'wx', mode: 0o400 });",
+        `  try { fs.linkSync(tmp, file); } catch { fs.unlinkSync(tmp); process.exit(${WARM_DELIVERY_ALREADY_DELIVERED}); }`,
+        "  fs.unlinkSync(tmp);",
+        "});",
+    ].join("\n");
+    return ["node", "-e", script];
+}

package/dist/native-worker/warm-pool-ledger.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The warm pool's rows (native sandbox phase 6, docs/native-sandbox.md): one per pool worker,
+ * inserted before the worker is created. A run claims an idle worker with one conditional update
+ * (`FOR UPDATE SKIP LOCKED`), so two claims — from any replica or process — never take the same
+ * worker, and a run never holds two (`runId` is unique).
+ */
+import type { NativeWarmWorker, PrismaClient } from "#prisma";
+export type WarmPoolDb = Pick<PrismaClient, "$transaction" | "$queryRaw" | "nativeWarmWorker">;
+export type WarmWorkerRow = NativeWarmWorker;
+export declare class PrismaWarmPoolLedger {
+    private readonly db;
+    constructor(db: WarmPoolDb);
+    /**
+     * Inserts `warming` rows for the pool's deficit (size minus its warming and idle workers of this
+     * spec) and returns them. Serialized per spec, so concurrent callers never overshoot the size.
+     */
+    reserve(specHash: string, size: number, newToken: () => string, nameFor: (token: string) => string): Promise<{
+        id: string;
+        name: string;
+    }[]>;
+    /** A warming worker's isolation is proven: it becomes claimable. False when it was retired meanwhile. */
+    markIdle(id: string): Promise<boolean>;
+    /** Takes one idle worker of this spec, born after `bornAfter`, for the run; null when there is none. */
+    claim(runId: string, specHash: string, bornAfter: Date): Promise<{
+        id: string;
+        name: string;
+    } | null>;
+    forRun(runId: string): Promise<WarmWorkerRow | null>;
+    /** Takes an idle worker out of the pool for removal; false when it was claimed (or is gone). */
+    retire(id: string): Promise<boolean>;
+    remove(id: string): Promise<void>;
+    count(): Promise<number>;
+    /** Every pool row, with its run's status (the maintenance tick's view; the pool is small). */
+    workers(): Promise<(WarmWorkerRow & {
+        run: {
+            status: string;
+        } | null;
+    })[]>;
+}

package/dist/native-worker/warm-pool-ledger.js

@@ -0,0 +1,73 @@
+/**
+ * The warm pool's rows (native sandbox phase 6, docs/native-sandbox.md): one per pool worker,
+ * inserted before the worker is created. A run claims an idle worker with one conditional update
+ * (`FOR UPDATE SKIP LOCKED`), so two claims — from any replica or process — never take the same
+ * worker, and a run never holds two (`runId` is unique).
+ */
+export class PrismaWarmPoolLedger {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * Inserts `warming` rows for the pool's deficit (size minus its warming and idle workers of this
+     * spec) and returns them. Serialized per spec, so concurrent callers never overshoot the size.
+     */
+    async reserve(specHash, size, newToken, nameFor) {
+        return this.db.$transaction(async (tx) => {
+            await tx.$queryRaw `SELECT pg_advisory_xact_lock(hashtext(${`wardby-native-warm-pool:${specHash}`}))::text`;
+            const have = await tx.nativeWarmWorker.count({ where: { specHash, status: { in: ["warming", "idle"] } } });
+            const rows = Array.from({ length: Math.max(0, size - have) }, () => {
+                const id = newToken();
+                return { id, name: nameFor(id), specHash };
+            });
+            if (rows.length > 0)
+                await tx.nativeWarmWorker.createMany({ data: rows });
+            return rows.map(({ id, name }) => ({ id, name }));
+        });
+    }
+    /** A warming worker's isolation is proven: it becomes claimable. False when it was retired meanwhile. */
+    async markIdle(id) {
+        const { count } = await this.db.nativeWarmWorker.updateMany({
+            where: { id, status: "warming" },
+            data: { status: "idle", readyAt: new Date() },
+        });
+        return count === 1;
+    }
+    /** Takes one idle worker of this spec, born after `bornAfter`, for the run; null when there is none. */
+    async claim(runId, specHash, bornAfter) {
+        const rows = await this.db.$queryRaw `
+      UPDATE "NativeWarmWorker"
+      SET "status" = 'claimed', "runId" = ${runId}, "claimedAt" = now(), "updatedAt" = now()
+      WHERE "id" = (
+        SELECT "id" FROM "NativeWarmWorker"
+        WHERE "status" = 'idle' AND "specHash" = ${specHash} AND "createdAt" > ${bornAfter}
+        ORDER BY "readyAt" ASC
+        LIMIT 1
+        FOR UPDATE SKIP LOCKED
+      )
+      RETURNING "id", "name"`;
+        return rows[0] ?? null;
+    }
+    forRun(runId) {
+        return this.db.nativeWarmWorker.findUnique({ where: { runId } });
+    }
+    /** Takes an idle worker out of the pool for removal; false when it was claimed (or is gone). */
+    async retire(id) {
+        const { count } = await this.db.nativeWarmWorker.updateMany({
+            where: { id, status: "idle" },
+            data: { status: "retiring" },
+        });
+        return count === 1;
+    }
+    async remove(id) {
+        await this.db.nativeWarmWorker.deleteMany({ where: { id } });
+    }
+    count() {
+        return this.db.nativeWarmWorker.count();
+    }
+    /** Every pool row, with its run's status (the maintenance tick's view; the pool is small). */
+    workers() {
+        return this.db.nativeWarmWorker.findMany({ include: { run: { select: { status: true } } } });
+    }
+}

package/dist/native-worker/warm-pool.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The native sandbox warm pool (phase 6, docs/native-sandbox.md): up to NATIVE_SANDBOX_WARM_POOL_SIZE
+ * idle workers, each already isolated (on Kubernetes: attested and probed from inside), holding no
+ * run data and no capability. A run claims one with a compare-and-swap on its row
+ * (warm-pool-ledger.ts), its input arrives by exec only after the claim, and the worker is
+ * destroyed after that one run like any other. With no idle worker, or any doubt about the one it
+ * claimed, a run cold-launches exactly as without a pool.
+ *
+ * Maintenance runs in the process that calls the executor's `launch()`: every tick it reaps rows
+ * whose runs have ended, retires idle workers that are too old, of another spec, gone, or over the
+ * size (only ever unclaimed ones), and replenishes the deficit. Claims work from any process.
+ */
+import type { NativeWorkerState } from "./docker-launcher.js";
+import type { WorkerHandle } from "./launch.js";
+import type { WorkerInput } from "./protocol.js";
+import type { ManagedWorkerLauncher } from "./sandbox-executor.js";
+import type { PrismaWarmPoolLedger } from "./warm-pool-ledger.js";
+export declare const NATIVE_SANDBOX_WARM_DELIVERY_FAILED = "native_sandbox_warm_delivery_failed";
+/** What a launcher does for pool workers. Every operation is keyed by the worker's random token. */
+export interface WarmWorkerLauncher {
+    /** What its pool workers are built from (with the worker's wait): a claim takes only a matching one. */
+    warmSpecHash(waitMs: number): string;
+    /**
+     * Creates a pool worker and proves its isolation, resolving once it is claimable. On failure it
+     * removes what it created and throws.
+     */
+    startWarm(token: string, waitMs: number): Promise<void>;
+    /** The claimed worker still runs, as built: cheap reads, not a new isolation probe. */
+    reattestWarm(token: string, waitMs: number): Promise<boolean>;
+    /** Writes the run's input into the worker over exec stdin (warm-delivery.ts). */
+    deliver(token: string, input: WorkerInput): Promise<void>;
+    warmHandle(token: string): WorkerHandle;
+    inspectWarm(token: string): Promise<NativeWorkerState>;
+    killWarm(token: string): Promise<void>;
+    /** Removes the worker and everything made for it. Idempotent. */
+    removeWarm(token: string): Promise<void>;
+    /** The tokens of every pool worker this launcher holds, rows or not. */
+    listWarm(): Promise<string[]>;
+}
+export interface WarmPoolOptions {
+    ledger: PrismaWarmPoolLedger;
+    /** The cold launcher, which also runs pool workers. */
+    launcher: ManagedWorkerLauncher & WarmWorkerLauncher;
+    /** NATIVE_SANDBOX_WARM_POOL_SIZE. 0 still cleans up a pool left from an earlier configuration, once. */
+    size: number;
+    /** NATIVE_SANDBOX_WARM_MAX_AGE_MS. */
+    maxAgeMs: number;
+    /** How long starting and proving a pool worker may take; a `warming` row older than this was abandoned. */
+    warmTimeoutMs: number;
+    /** Marks a run's session ready once its input is delivered (when sessions start not ready: Kubernetes). */
+    onDelivered?: (runId: string) => Promise<void>;
+    intervalMs?: number;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    newToken?: () => string;
+}
+/** A ManagedWorkerLauncher that hands a run a warm worker when it can, and cold-launches otherwise. */
+export declare class PooledWorkerLauncher implements ManagedWorkerLauncher {
+    private readonly options;
+    readonly networkReadyAtLaunch: boolean | undefined;
+    readonly waitMs: number;
+    readonly specHash: string;
+    private timer;
+    private ticking;
+    /** The one pass queued behind a running one: a tick asked for mid-pass sees state from after the ask. */
+    private queued;
+    private readonly warming;
+    /** Tokens this process is still starting: never reaped as abandoned, however slow. */
+    private readonly warmingHere;
+    /** The first pass (orphan sweep included) has run. */
+    private swept;
+    constructor(options: WarmPoolOptions);
+    private get cold();
+    private now;
+    private sleep;
+    launch(input: WorkerInput): Promise<WorkerHandle>;
+    private confirmGone;
+    /** Removes a pool worker and its row. */
+    private discard;
+    private claimedToken;
+    handle(runId: string): WorkerHandle;
+    inspect(runId: string): Promise<NativeWorkerState>;
+    kill(runId: string): Promise<void>;
+    remove(runId: string): Promise<void>;
+    listWorkers(): Promise<{
+        name: string;
+        runHash: string;
+    }[]>;
+    removeByWorkerName(name: string): Promise<void>;
+    get resolveGatewayUrl(): (() => Promise<string>) | undefined;
+    /**
+     * Starts maintenance: one pass now, then one every interval. At size 0 a pass is a single count
+     * of pool rows until one appears: a replica still running a bigger size during a rolling update
+     * can refill the pool after this replica's first pass, and only a later pass retires those.
+     */
+    start(): Promise<void>;
+    stop(): void;
+    /** Asks for a pass soon, only in the process running maintenance: a short-lived CLI never warms workers. */
+    private nudge;
+    /** One maintenance pass; resolves once reaping and retiring are done (warming continues behind it). */
+    tick(): Promise<void>;
+    /** Resolves once every worker this process is warming has settled (tests, shutdown). */
+    settled(): Promise<void>;
+    private maintain;
+    private retire;
+    private replenish;
+}