@wardby/cli 0.5.3 → 0.6.0

package/dist/native-worker/launch.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Starting a sandbox-mode run against the HTTP gateway (native sandbox phase 3):
+ * create its gateway session, launch a worker with the session's one-time
+ * capability on its stdin, and return. Nothing waits on the worker — whichever
+ * gateway replica serves its `finish` makes the terminal write. Phase 4's
+ * executors launch the worker in a container or pod; `processWorkerLauncher`
+ * runs it as a local child process.
+ */
+import { type NativeRunProviders, type RunnerDb } from "../core/runner.js";
+import type { Run } from "#prisma";
+import { PrismaGatewayLedger } from "./ledger.js";
+import type { WorkerInput } from "./protocol.js";
+import type { WorkerProcessSpec } from "./stdio.js";
+export interface WorkerHandle {
+    /** Resolves with the worker's exit code (null when it was killed or never started). */
+    exited: Promise<number | null>;
+    kill(): void;
+}
+/** Starts a worker for an HTTP-gateway input and returns at once. */
+export interface DetachedWorkerLauncher {
+    launch(input: WorkerInput): Promise<WorkerHandle>;
+    /**
+     * False when the worker's network isolation only takes effect after it starts (a Kubernetes
+     * NetworkPolicy): its session is then created not ready, and the launcher marks it ready once
+     * proven. Absent or true: ready at creation (Docker's network exists before the container).
+     */
+    readonly networkReadyAtLaunch?: boolean;
+}
+/** The worker as a local child process with an empty environment (by default), its input on stdin. */
+export declare function processWorkerLauncher(spec: WorkerProcessSpec): DetachedWorkerLauncher;
+export type StartSandboxRunOutcome = {
+    kind: "launched";
+    sessionId: string;
+    handle: WorkerHandle;
+} | {
+    kind: "ended";
+    run: Run;
+};
+export declare function startSandboxRun(options: {
+    runId: string;
+    providers: NativeRunProviders;
+    db: RunnerDb & ConstructorParameters<typeof PrismaGatewayLedger>[0];
+    gatewayUrl: string;
+    launcher: DetachedWorkerLauncher;
+}): Promise<StartSandboxRunOutcome>;

package/dist/native-worker/launch.js

@@ -0,0 +1,44 @@
+/**
+ * Starting a sandbox-mode run against the HTTP gateway (native sandbox phase 3):
+ * create its gateway session, launch a worker with the session's one-time
+ * capability on its stdin, and return. Nothing waits on the worker — whichever
+ * gateway replica serves its `finish` makes the terminal write. Phase 4's
+ * executors launch the worker in a container or pod; `processWorkerLauncher`
+ * runs it as a local child process.
+ */
+import { spawn } from "node:child_process";
+import { createSandboxSession } from "../core/runner.js";
+import { PrismaGatewayLedger } from "./ledger.js";
+/** The worker as a local child process with an empty environment (by default), its input on stdin. */
+export function processWorkerLauncher(spec) {
+    return {
+        async launch(input) {
+            const child = spawn(spec.command, spec.args, {
+                env: spec.env ?? {},
+                cwd: spec.cwd,
+                stdio: ["pipe", "ignore", "inherit"],
+            });
+            const exited = new Promise((resolve) => {
+                child.on("error", () => resolve(null));
+                child.on("exit", (code) => resolve(code));
+            });
+            child.stdin.on("error", () => { });
+            child.stdin.end(`${JSON.stringify(input)}\n`);
+            return { exited, kill: () => child.kill("SIGKILL") };
+        },
+    };
+}
+export async function startSandboxRun(options) {
+    const session = await createSandboxSession({
+        runId: options.runId,
+        providers: options.providers,
+        db: options.db,
+        ledger: new PrismaGatewayLedger(options.db),
+        gatewayUrl: options.gatewayUrl,
+        networkReady: options.launcher.networkReadyAtLaunch !== false,
+    });
+    if (session.kind === "ended")
+        return session;
+    const handle = await options.launcher.launch(session.input);
+    return { kind: "launched", sessionId: session.sessionId, handle };
+}

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

@@ -0,0 +1,109 @@
+/**
+ * The native sandbox gateway's durable state (native sandbox phase 3): one
+ * session per sandbox-mode run, and one call row per worker callId. Modelled on
+ * the coding proxy's PrismaProxyLedger — a model call reserves against the
+ * session budget under a row lock on the session before the provider is
+ * called, and is settled at its actual cost after — so any control-plane
+ * replica can serve any call, and a restart loses nothing.
+ */
+import type { Prisma, PrismaClient } from "#prisma";
+export type GatewayLedgerDb = Pick<PrismaClient, "$transaction" | "$queryRaw" | "nativeGatewaySession" | "nativeGatewayCall">;
+export interface GatewaySessionRecord {
+    id: string;
+    runId: string;
+    status: "active" | "finished" | "cancelled";
+    deadlineAt: Date;
+    budgetUsd: number;
+    snapshot: unknown;
+    networkReadyAt: Date | null;
+}
+export interface CreateGatewaySessionInput {
+    runId: string;
+    capabilityHash: string;
+    deadlineAt: Date;
+    budgetUsd: number;
+    snapshot: Prisma.InputJsonValue;
+    /** Set at creation when the launcher's isolation exists before the worker does (Docker). */
+    networkReadyAt?: Date | null;
+}
+export type ReserveOutcome = {
+    outcome: "reserved";
+} | {
+    outcome: "duplicate";
+} | {
+    outcome: "inactive";
+    reason: "ended" | "expired";
+} | {
+    outcome: "budget_exhausted";
+};
+export interface SettledUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cachedInputTokens: number;
+    cacheWriteTokens: number;
+    costUsd: number;
+}
+export interface GatewayTotals {
+    tokensIn: number;
+    tokensOut: number;
+    costUsd: number;
+    cachedInputTokens: number;
+    cacheWriteTokens: number;
+    /** Settled cost plus every live (reserved or uncertain) reservation: what the budget is checked against. */
+    heldUsd: number;
+}
+export type ClaimOutcome = {
+    outcome: "claimed";
+} | {
+    outcome: "in_flight";
+} | {
+    outcome: "done";
+    result: unknown;
+};
+export interface DelegationState {
+    status: "pending" | "waiting_budget" | "completed";
+    childRunId: string | null;
+    childAgentId: string | null;
+    /** When the delegation was first called: its wait bounds count from here. */
+    createdAt: Date;
+}
+export declare class PrismaGatewayLedger {
+    private readonly db;
+    constructor(db: GatewayLedgerDb);
+    createSession(input: CreateGatewaySessionInput): Promise<GatewaySessionRecord>;
+    /** The session a capability belongs to, whatever its status; the caller decides what each status allows. */
+    findSessionByCapabilityHash(capabilityHash: string): Promise<GatewaySessionRecord | null>;
+    /** Records that the worker's network isolation was proven: the gateway serves it from now on. */
+    markNetworkReady(sessionId: string, at?: Date): Promise<void>;
+    /** markNetworkReady by the session's run (a launcher knows the run, not the session). */
+    markNetworkReadyForRun(runId: string, at?: Date): Promise<void>;
+    endSession(sessionId: string, status: "finished" | "cancelled"): Promise<void>;
+    /** Reserves `reservationUsd` for a model call, or says why not. Serialized per session. */
+    reserve(input: {
+        sessionId: string;
+        callId: string;
+        reservationUsd: number;
+        now: Date;
+    }): Promise<ReserveOutcome>;
+    /** Settles a reserved (or uncertain) model call at what it actually cost. */
+    complete(sessionId: string, callId: string, usage: SettledUsage): Promise<void>;
+    /** Frees a reservation the provider never billed (it refused the request). */
+    release(sessionId: string, callId: string): Promise<void>;
+    /** The outcome is unknown (the connection broke mid-call): the reservation stays held. */
+    markUncertain(sessionId: string, callId: string): Promise<void>;
+    totals(sessionId: string): Promise<GatewayTotals>;
+    /** Claims a one-shot call by callId: the first claimant runs it, a repeat waits or replays. */
+    claim(sessionId: string, callId: string, method: string): Promise<ClaimOutcome>;
+    recordResult(sessionId: string, callId: string, result: Prisma.InputJsonValue): Promise<void>;
+    /** A delegation's durable progress: its sub-agent, whether it waits for budget, and its child run once started. */
+    setDelegation(sessionId: string, callId: string, state: {
+        status: "pending" | "waiting_budget";
+        childAgentId: string;
+        childRunId?: string;
+    }): Promise<void>;
+    delegation(sessionId: string, callId: string): Promise<DelegationState | null>;
+    /** The sub-agents other delegations of this run are waiting for budget to start. */
+    waitingChildAgentIds(sessionId: string, exceptCallId: string): Promise<string[]>;
+    /** Delegations of this session whose child run is started and not yet reported. */
+    openDelegationChildren(sessionId: string): Promise<string[]>;
+}

package/dist/native-worker/ledger.js

@@ -0,0 +1,192 @@
+/**
+ * The native sandbox gateway's durable state (native sandbox phase 3): one
+ * session per sandbox-mode run, and one call row per worker callId. Modelled on
+ * the coding proxy's PrismaProxyLedger — a model call reserves against the
+ * session budget under a row lock on the session before the provider is
+ * called, and is settled at its actual cost after — so any control-plane
+ * replica can serve any call, and a restart loses nothing.
+ */
+const LEDGER_TX = { maxWait: 5_000, timeout: 20_000 };
+function toSession(row) {
+    return { ...row, budgetUsd: Number(row.budgetUsd) };
+}
+export class PrismaGatewayLedger {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    async createSession(input) {
+        return toSession(await this.db.nativeGatewaySession.create({ data: input }));
+    }
+    /** The session a capability belongs to, whatever its status; the caller decides what each status allows. */
+    async findSessionByCapabilityHash(capabilityHash) {
+        const row = await this.db.nativeGatewaySession.findUnique({ where: { capabilityHash } });
+        return row ? toSession(row) : null;
+    }
+    /** Records that the worker's network isolation was proven: the gateway serves it from now on. */
+    async markNetworkReady(sessionId, at = new Date()) {
+        await this.db.nativeGatewaySession.updateMany({
+            where: { id: sessionId, networkReadyAt: null },
+            data: { networkReadyAt: at },
+        });
+    }
+    /** markNetworkReady by the session's run (a launcher knows the run, not the session). */
+    async markNetworkReadyForRun(runId, at = new Date()) {
+        await this.db.nativeGatewaySession.updateMany({
+            where: { runId, networkReadyAt: null },
+            data: { networkReadyAt: at },
+        });
+    }
+    async endSession(sessionId, status) {
+        await this.db.nativeGatewaySession.updateMany({ where: { id: sessionId, status: "active" }, data: { status } });
+    }
+    /** Reserves `reservationUsd` for a model call, or says why not. Serialized per session. */
+    async reserve(input) {
+        return this.db.$transaction(async (tx) => {
+            const locked = await tx.$queryRaw `
+        SELECT "status", "deadlineAt", "budgetUsd" FROM "NativeGatewaySession" WHERE "id" = ${input.sessionId} FOR UPDATE`;
+            const session = locked[0];
+            if (!session || session.status !== "active")
+                return { outcome: "inactive", reason: "ended" };
+            if (input.now.getTime() >= session.deadlineAt.getTime())
+                return { outcome: "inactive", reason: "expired" };
+            const existing = await tx.nativeGatewayCall.findUnique({
+                where: { sessionId_callId: { sessionId: input.sessionId, callId: input.callId } },
+            });
+            if (existing)
+                return { outcome: "duplicate" };
+            const held = await heldUsd(tx, input.sessionId);
+            if (held + input.reservationUsd >= Number(session.budgetUsd)) {
+                await tx.nativeGatewaySession.updateMany({
+                    where: { id: input.sessionId, budgetExhaustedAt: null },
+                    data: { budgetExhaustedAt: input.now },
+                });
+                return { outcome: "budget_exhausted" };
+            }
+            await tx.nativeGatewayCall.create({
+                data: {
+                    sessionId: input.sessionId,
+                    callId: input.callId,
+                    method: "llm.stream",
+                    status: "reserved",
+                    reservationUsd: input.reservationUsd,
+                },
+            });
+            return { outcome: "reserved" };
+        }, LEDGER_TX);
+    }
+    /** Settles a reserved (or uncertain) model call at what it actually cost. */
+    async complete(sessionId, callId, usage) {
+        await this.db.nativeGatewayCall.updateMany({
+            where: { sessionId, callId, status: { in: ["reserved", "uncertain"] } },
+            data: {
+                status: "completed",
+                actualCostUsd: usage.costUsd,
+                inputTokens: usage.inputTokens,
+                outputTokens: usage.outputTokens,
+                cachedInputTokens: usage.cachedInputTokens,
+                cacheWriteTokens: usage.cacheWriteTokens,
+                completedAt: new Date(),
+            },
+        });
+    }
+    /** Frees a reservation the provider never billed (it refused the request). */
+    async release(sessionId, callId) {
+        await this.db.nativeGatewayCall.updateMany({
+            where: { sessionId, callId, status: "reserved" },
+            data: { status: "released", completedAt: new Date() },
+        });
+    }
+    /** The outcome is unknown (the connection broke mid-call): the reservation stays held. */
+    async markUncertain(sessionId, callId) {
+        await this.db.nativeGatewayCall.updateMany({
+            where: { sessionId, callId, status: "reserved" },
+            data: { status: "uncertain" },
+        });
+    }
+    async totals(sessionId) {
+        const completed = await this.db.nativeGatewayCall.aggregate({
+            where: { sessionId, status: "completed", method: "llm.stream" },
+            _sum: {
+                inputTokens: true,
+                outputTokens: true,
+                cachedInputTokens: true,
+                cacheWriteTokens: true,
+                actualCostUsd: true,
+            },
+        });
+        return {
+            tokensIn: completed._sum.inputTokens ?? 0,
+            tokensOut: completed._sum.outputTokens ?? 0,
+            cachedInputTokens: completed._sum.cachedInputTokens ?? 0,
+            cacheWriteTokens: completed._sum.cacheWriteTokens ?? 0,
+            costUsd: Number(completed._sum.actualCostUsd ?? 0),
+            heldUsd: await heldUsd(this.db, sessionId),
+        };
+    }
+    /** Claims a one-shot call by callId: the first claimant runs it, a repeat waits or replays. */
+    async claim(sessionId, callId, method) {
+        const created = await this.db.nativeGatewayCall.createMany({
+            data: [{ sessionId, callId, method, status: "pending" }],
+            skipDuplicates: true,
+        });
+        if (created.count === 1)
+            return { outcome: "claimed" };
+        const row = await this.db.nativeGatewayCall.findUnique({ where: { sessionId_callId: { sessionId, callId } } });
+        if (row?.status === "completed")
+            return { outcome: "done", result: row.result };
+        return { outcome: "in_flight" };
+    }
+    async recordResult(sessionId, callId, result) {
+        await this.db.nativeGatewayCall.updateMany({
+            where: { sessionId, callId },
+            data: { status: "completed", result, completedAt: new Date() },
+        });
+    }
+    /** A delegation's durable progress: its sub-agent, whether it waits for budget, and its child run once started. */
+    async setDelegation(sessionId, callId, state) {
+        await this.db.nativeGatewayCall.updateMany({
+            where: { sessionId, callId, status: { in: ["pending", "waiting_budget"] } },
+            data: {
+                status: state.status,
+                childAgentId: state.childAgentId,
+                ...(state.childRunId ? { childRunId: state.childRunId } : {}),
+            },
+        });
+    }
+    async delegation(sessionId, callId) {
+        const row = await this.db.nativeGatewayCall.findUnique({ where: { sessionId_callId: { sessionId, callId } } });
+        if (!row)
+            return null;
+        const status = row.status === "waiting_budget" ? "waiting_budget" : row.status === "completed" ? "completed" : "pending";
+        return { status, childRunId: row.childRunId, childAgentId: row.childAgentId, createdAt: row.createdAt };
+    }
+    /** The sub-agents other delegations of this run are waiting for budget to start. */
+    async waitingChildAgentIds(sessionId, exceptCallId) {
+        const rows = await this.db.nativeGatewayCall.findMany({
+            where: { sessionId, status: "waiting_budget", callId: { not: exceptCallId }, childAgentId: { not: null } },
+            select: { childAgentId: true },
+        });
+        return rows.map((row) => row.childAgentId);
+    }
+    /** Delegations of this session whose child run is started and not yet reported. */
+    async openDelegationChildren(sessionId) {
+        const rows = await this.db.nativeGatewayCall.findMany({
+            where: { sessionId, status: "pending", childRunId: { not: null } },
+            select: { childRunId: true },
+        });
+        return rows.map((row) => row.childRunId);
+    }
+}
+async function heldUsd(db, sessionId) {
+    const rows = await db.$queryRaw `
+    SELECT COALESCE(SUM(
+      CASE
+        WHEN "status" = 'completed' THEN COALESCE("actualCostUsd", 0)
+        WHEN "status" IN ('reserved', 'uncertain') THEN COALESCE("reservationUsd", 0)
+        ELSE 0
+      END
+    ), 0) AS "held"
+    FROM "NativeGatewayCall" WHERE "sessionId" = ${sessionId} AND "method" = 'llm.stream'`;
+    return Number(rows[0]?.held ?? 0);
+}

package/dist/native-worker/loopback.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The in-process harness transport: the worker and gateway in one process,
+ * with every message (worker input, requests, results, stream events, errors)
+ * forced through a JSON round trip so nothing crosses by reference — the same
+ * shape a real transport has. For tests and local development; never a
+ * sandbox (the worker runs in the server's own process).
+ */
+import type { NativeGateway, WorkerLauncher } from "./gateway.js";
+import { type GatewayTransport } from "./worker.js";
+export declare function createLoopbackTransport(gateway: NativeGateway): GatewayTransport;
+/** Runs the worker in this process over the loopback transport. */
+export declare const loopbackLauncher: WorkerLauncher;

package/dist/native-worker/loopback.js

@@ -0,0 +1,49 @@
+/**
+ * The in-process harness transport: the worker and gateway in one process,
+ * with every message (worker input, requests, results, stream events, errors)
+ * forced through a JSON round trip so nothing crosses by reference — the same
+ * shape a real transport has. For tests and local development; never a
+ * sandbox (the worker runs in the server's own process).
+ */
+import { GatewayError, parseMessage, WorkerInputSchema } from "./protocol.js";
+import { runNativeWorker } from "./worker.js";
+const wire = (value) => (value === undefined ? value : JSON.parse(JSON.stringify(value)));
+function asGatewayError(err) {
+    if (err instanceof GatewayError)
+        return new GatewayError(err.code, err.message);
+    return new GatewayError("internal", err instanceof Error ? err.message : String(err));
+}
+export function createLoopbackTransport(gateway) {
+    return {
+        async call(request) {
+            try {
+                return wire(await gateway.call(wire(request)));
+            }
+            catch (err) {
+                throw asGatewayError(err);
+            }
+        },
+        async *stream(request) {
+            try {
+                for await (const event of gateway.stream(wire(request)))
+                    yield wire(event);
+            }
+            catch (err) {
+                throw asGatewayError(err);
+            }
+        },
+    };
+}
+/** Runs the worker in this process over the loopback transport. */
+export const loopbackLauncher = {
+    async run(input, gateway) {
+        try {
+            const parsed = parseMessage(JSON.stringify(input), WorkerInputSchema);
+            await runNativeWorker(parsed, createLoopbackTransport(gateway));
+            return { exitCode: 0 };
+        }
+        catch {
+            return { exitCode: 1 };
+        }
+    },
+};

package/dist/native-worker/main.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Native sandbox worker process entry. Reads its WorkerInput as the first line
+ * on stdin, runs the run's engine against the gateway on stdin/stdout
+ * (stdio.ts), and exits 0 once it has sent its result. stdout carries only
+ * protocol frames; diagnostics (and the shared logger) go to stderr.
+ */
+export {};

package/dist/native-worker/main.js

@@ -0,0 +1,74 @@
+/**
+ * Native sandbox worker process entry. Reads its WorkerInput as the first line
+ * on stdin, runs the run's engine against the gateway on stdin/stdout
+ * (stdio.ts), and exits 0 once it has sent its result. stdout carries only
+ * protocol frames; diagnostics (and the shared logger) go to stderr.
+ */
+import { readFile, stat } from "node:fs/promises";
+import { parseMessage, WorkerInputSchema } from "./protocol.js";
+import { createHttpTransport } from "./http-transport.js";
+import { createStdioTransport } from "./stdio.js";
+import { WARM_WORKER_UNCLAIMED_EXIT } from "./warm-delivery.js";
+import { runNativeWorker } from "./worker.js";
+function firstLine() {
+    return new Promise((resolve, reject) => {
+        let buffer = "";
+        const onData = (chunk) => {
+            buffer += chunk.toString();
+            const newline = buffer.indexOf("\n");
+            if (newline >= 0) {
+                process.stdin.off("data", onData);
+                resolve(buffer.slice(0, newline));
+            }
+        };
+        process.stdin.on("data", onData);
+        process.stdin.once("end", () => reject(new Error("stdin closed before the worker input arrived")));
+    });
+}
+class UnclaimedError extends Error {
+}
+/**
+ * A warm pool worker (NATIVE_WORKER_INPUT_WAIT_MS set) starts before any run exists: it waits for
+ * its input file, delivered after a run claims it (warm-delivery.ts), and gives up after the wait.
+ */
+async function waitForFile(file, waitMs) {
+    const until = Date.now() + waitMs;
+    for (;;) {
+        if (await stat(file).then(() => true, () => false))
+            return;
+        if (Date.now() >= until)
+            throw new UnclaimedError("no run claimed this warm worker in time");
+        await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+}
+/**
+ * The input's source: a file when NATIVE_WORKER_INPUT_FILE names one (a Kubernetes pod mounts it
+ * read-only from the run's Secret; a warm worker waits for it), otherwise the first line on stdin
+ * (Docker, local).
+ */
+async function readInput() {
+    const file = process.env.NATIVE_WORKER_INPUT_FILE;
+    if (!file)
+        return firstLine();
+    const waitMs = Number(process.env.NATIVE_WORKER_INPUT_WAIT_MS ?? "");
+    if (Number.isFinite(waitMs) && waitMs > 0)
+        await waitForFile(file, waitMs);
+    return (await readFile(file, "utf8")).trim();
+}
+async function main() {
+    const input = parseMessage(await readInput(), WorkerInputSchema);
+    // The gateway answers only after the worker asks, so choosing the transport after the input
+    // line misses nothing.
+    const transport = input.gateway
+        ? createHttpTransport({ url: input.gateway.url, capability: input.gateway.capability })
+        : createStdioTransport(process.stdin, process.stdout);
+    await runNativeWorker(input, transport);
+}
+main().then(() => process.exit(0), (err) => {
+    if (err instanceof UnclaimedError) {
+        process.stderr.write(`native sandbox worker: ${err.message}\n`);
+        process.exit(WARM_WORKER_UNCLAIMED_EXIT);
+    }
+    process.stderr.write(`native sandbox worker failed: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});