@wardby/cli 0.5.3 → 0.7.0

package/dist/native-worker/kubernetes-launcher.js

@@ -0,0 +1,375 @@
+/**
+ * Launches, watches, stops, and removes native sandbox workers as Kubernetes pods
+ * (docs/native-sandbox.md), from the builders in kubernetes-isolation.ts. Like the Docker
+ * launcher it keeps no state of its own: names derive from the run id, state comes from the pod,
+ * and sessions live in Postgres, so any replica can act on any run.
+ *
+ * A pod's NetworkPolicy takes effect a few seconds after the pod starts (the CNI programs it), so
+ * the session is created not ready (`networkReadyAtLaunch = false`): the gateway refuses the
+ * worker until this launcher has read back the pod and policy it created, then proven from inside
+ * the pod that the gateway port answers while the gateway's deny port and an outside address do
+ * not — and only then marks the session ready.
+ */
+import { logger } from "../core/logger.js";
+import { DISABLED_POWER, wakeTimeoutMs } from "../core/power.js";
+import { KubernetesAlreadyExistsError } from "../providers/jobs/kubernetes-api.js";
+import { canonicalResources } from "../providers/jobs/kubernetes-isolation.js";
+import { NATIVE_GATEWAY_PORT } from "./docker-isolation.js";
+import { WORKER_TAIL_TIMEOUT_MS, withTimeout, workerTailFields } from "./docker-launcher.js";
+import { createHash } from "node:crypto";
+import { Readable } from "node:stream";
+import { buildNativeInputSecret, buildNativeRunNetworkPolicy, buildNativeRunPod, buildNativeWarmNetworkPolicy, buildNativeWarmPod, NATIVE_PROBE, NATIVE_RUN_SELECTOR, NATIVE_RUN_SHA_LABEL, NATIVE_WARM_SELECTOR, NATIVE_WARM_TOKEN_LABEL, NATIVE_WORKER_CONTAINER, nativeEnforcementProbe, nativeKubernetesNames, nativeWarmWorkerName, } from "./kubernetes-isolation.js";
+import { NATIVE_SANDBOX_LAUNCH_ABANDONED } from "./launch.js";
+import { warmDeliveryCommand } from "./warm-delivery.js";
+import { NATIVE_SANDBOX_WARM_DELIVERY_FAILED } from "./warm-pool.js";
+const k8sLog = logger.child({ module: "native-kubernetes-launcher" });
+export const NATIVE_SANDBOX_NETWORK_UNENFORCED = "native_sandbox_network_unenforced";
+export const NATIVE_SANDBOX_ISOLATION_MISMATCH = "native_sandbox_isolation_mismatch";
+export const NATIVE_SANDBOX_CAPACITY = "native_sandbox_capacity";
+/**
+ * A failed worker's log is read this far back before its tail is redacted and cut. The API server
+ * applies `limitBytes` from the start of the selected lines, so it would cut the end (the worker's
+ * final failure line): it is only a memory cap, far above what the line bound selects in practice.
+ */
+const WORKER_LOG_TAIL_LINES = 100;
+const WORKER_LOG_TAIL_BYTES = 1024 * 1024;
+/** The API server's refusal of a pod the namespace's ResourceQuota has no room for (403 "exceeded quota"). */
+export function isQuotaRejection(err) {
+    if (typeof err !== "object" || err === null)
+        return false;
+    const { code, body, message } = err;
+    const text = `${typeof body === "string" ? body : JSON.stringify(body ?? "")} ${typeof message === "string" ? message : ""}`;
+    return (code === 403 || code === undefined) && /exceeded quota/i.test(text);
+}
+/**
+ * An object as the API server would store it, for comparison: keys sorted, and missing, undefined,
+ * and empty arrays alike (it drops an empty `ingress: []`, which `policyTypes` already makes deny-all).
+ */
+export function canonical(value) {
+    if (Array.isArray(value))
+        return value.length === 0 ? undefined : value.map(canonical);
+    if (value === null || typeof value !== "object")
+        return value;
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+        const item = canonical(value[key]);
+        if (item !== undefined)
+            out[key] = item;
+    }
+    return out;
+}
+export class KubernetesNativeWorkerLauncher {
+    options;
+    networkReadyAtLaunch = false;
+    gatewayHost;
+    power;
+    constructor(options) {
+        this.options = options;
+        this.power = options.power ?? DISABLED_POWER;
+    }
+    get api() {
+        return this.options.api;
+    }
+    get ns() {
+        return this.options.namespace;
+    }
+    sleep(ms) {
+        return (this.options.sleep ?? ((t) => new Promise((resolve) => setTimeout(resolve, t))))(ms);
+    }
+    /** The gateway Service's ClusterIP: workers dial an address, so they need no DNS egress. */
+    resolveGatewayHost() {
+        if (this.options.gatewayUrl)
+            return Promise.resolve(new URL(this.options.gatewayUrl).hostname);
+        this.gatewayHost ??= (async () => {
+            const service = await this.api.readService(this.ns, this.options.gatewayService);
+            const ip = service?.spec?.clusterIP;
+            if (!ip || ip === "None") {
+                this.gatewayHost = undefined;
+                throw new Error(`native_sandbox_gateway_unavailable: Service "${this.options.gatewayService}" in "${this.ns}" has no ClusterIP.`);
+            }
+            return ip;
+        })();
+        return this.gatewayHost;
+    }
+    async resolveGatewayUrl() {
+        if (this.options.gatewayUrl)
+            return this.options.gatewayUrl;
+        return `http://${await this.resolveGatewayHost()}:${NATIVE_GATEWAY_PORT}/native-gateway/v1/call`;
+    }
+    async createIfMissing(create) {
+        try {
+            await create();
+        }
+        catch (err) {
+            if (!(err instanceof KubernetesAlreadyExistsError))
+                throw err;
+        }
+    }
+    async launch(input, launchOptions = {}) {
+        const runId = input.runId;
+        // Low-power mode: the gateway may be scaled to zero; wake it before anything is created. Guarded
+        // so mode off adds no await.
+        if (this.power.enabled) {
+            await this.power.ensureAwake("gateway", {
+                timeoutMs: wakeTimeoutMs(this.options.readyTimeoutMs ?? 120_000),
+                runId,
+            });
+        }
+        // A wake can take minutes: a run stopped meanwhile gets no pod.
+        if (launchOptions.stillWanted && !(await launchOptions.stillWanted())) {
+            throw new Error(`${NATIVE_SANDBOX_LAUNCH_ABANDONED}: the run ended while its worker was launching; no worker was started.`);
+        }
+        const names = nativeKubernetesNames(runId);
+        if ((await this.inspect(runId)).state === "missing") {
+            const pod = buildNativeRunPod({
+                runId,
+                namespace: this.ns,
+                image: this.options.image,
+                limits: this.options.limits,
+                activeDeadlineSeconds: this.options.deadlineSeconds,
+                runtimeClassName: this.options.runtimeClassName,
+                platform: this.options.platform,
+                priorityClassName: this.options.priorityClassName,
+            });
+            const policy = buildNativeRunNetworkPolicy(runId, this.ns);
+            await this.createIsolated(pod, policy, () => this.remove(runId), {
+                // The Secret before the pod that mounts it.
+                beforePod: () => this.createIfMissing(() => this.api.createSecret(this.ns, buildNativeInputSecret(input, this.ns))),
+            });
+            await this.options.onNetworkProven(runId);
+            // Read before the exit is reported, so the pod (and its log) still exists.
+            return this.handleByName(names.pod, (code) => this.logFailedExit(names.pod, code, input, launchOptions));
+        }
+        else {
+            k8sLog.info({ pod: names.pod }, "native worker pod already exists: attaching, not relaunching");
+        }
+        return this.handle(runId);
+    }
+    /** A non-zero exit, with the tail of the worker's log (bounded and redacted: workerTailFields), as the Docker launcher logs it. */
+    async logFailedExit(podName, code, input, launchOptions) {
+        if (code === 0)
+            return;
+        // One bound for the whole diagnostic, so a hung read never holds back the exit (and the run's end).
+        const by = Date.now() + (this.options.diagnosticTimeoutMs ?? WORKER_TAIL_TIMEOUT_MS);
+        let log;
+        try {
+            log = await withTimeout(this.api.readLogTail(this.ns, podName, NATIVE_WORKER_CONTAINER, WORKER_LOG_TAIL_LINES, WORKER_LOG_TAIL_BYTES), by - Date.now());
+        }
+        catch {
+            // The pod may already be gone, the read may be refused (no pods/log), or it timed out.
+            k8sLog.warn({ pod: podName, code, stderrTailOmitted: "log_read_failed" }, "native worker exited non-zero");
+            return;
+        }
+        // The read may always begin mid-text, even with fewer lines than the bound: the kubelet splits
+        // a line over 16 KiB into partial records (each counted as a line), and log rotation drops the
+        // oldest text, so the start is always masked as cut. The byte cap (counted from the start of
+        // the selected lines) cuts the end only when it is met.
+        const end = Buffer.byteLength(log) >= WORKER_LOG_TAIL_BYTES - 3;
+        const tail = await workerTailFields(log, input, launchOptions.secretValues, { start: true, end }, by - Date.now());
+        k8sLog.warn({ pod: podName, code, ...tail }, "native worker exited non-zero");
+    }
+    /**
+     * Policy first, so the pod never exists without it; then the pod; then attest and prove it. A
+     * quota rejection becomes native_sandbox_capacity. Any failure removes what was made.
+     */
+    async createIsolated(pod, policy, cleanup, hooks = {}) {
+        await this.createIfMissing(() => this.api.createNetworkPolicy(this.ns, policy));
+        await hooks.beforePod?.();
+        try {
+            await this.createIfMissing(() => this.api.createPod(this.ns, pod));
+        }
+        catch (err) {
+            if (!isQuotaRejection(err))
+                throw err;
+            await cleanup().catch(() => { });
+            throw new Error(`${NATIVE_SANDBOX_CAPACITY}: the namespace's ResourceQuota has no room for another native worker pod.`, { cause: err });
+        }
+        try {
+            await this.attest(pod, policy);
+            await this.proveIsolation(pod.metadata.name);
+        }
+        catch (err) {
+            await cleanup().catch(() => { });
+            throw err;
+        }
+    }
+    /** What the API server stored must still be what was built: an admission change voids the run. */
+    async attest(built, builtPolicy) {
+        if (!(await this.matches(built, builtPolicy))) {
+            throw new Error(`${NATIVE_SANDBOX_ISOLATION_MISMATCH}: the worker pod or its NetworkPolicy as stored differs from what was built.`);
+        }
+    }
+    async matches(built, builtPolicy) {
+        const [pod, policy] = await Promise.all([
+            this.api.readPod(this.ns, built.metadata.name),
+            this.api.readNetworkPolicy(this.ns, builtPolicy.metadata.name),
+        ]);
+        const stored = pod?.spec;
+        const want = built.spec;
+        const same = (a, b) => JSON.stringify(canonical(a)) === JSON.stringify(canonical(b));
+        const ok = !!stored &&
+            !!policy &&
+            same(policy.spec, builtPolicy.spec) &&
+            stored.automountServiceAccountToken === false &&
+            stored.hostNetwork !== true &&
+            stored.runtimeClassName === want.runtimeClassName &&
+            stored.priorityClassName === want.priorityClassName &&
+            stored.containers.length === 1 &&
+            stored.containers[0].image === want.containers[0].image &&
+            same(stored.containers[0].securityContext, want.containers[0].securityContext) &&
+            same(stored.containers[0].env, want.containers[0].env) &&
+            same(canonicalResources(stored.containers[0].resources), canonicalResources(want.containers[0].resources)) &&
+            (stored.initContainers ?? []).length === 0;
+        return ok;
+    }
+    /** Waits for the pod to run, then proves its egress from inside it (bounded). */
+    async proveIsolation(podName) {
+        const pollMs = this.options.pollMs ?? 1_000;
+        const readyBy = Date.now() + (this.options.readyTimeoutMs ?? 120_000);
+        for (;;) {
+            const pod = await this.api.readPod(this.ns, podName);
+            if (!pod)
+                throw new Error("native_sandbox_worker_lost: the worker pod disappeared before it was ready.");
+            const phase = pod.status?.phase ?? "Pending";
+            if (phase === "Running")
+                break;
+            if (phase === "Succeeded" || phase === "Failed") {
+                throw new Error(`native_sandbox_worker_exited: the worker pod ended before it was ready (${phase}).`);
+            }
+            if (Date.now() >= readyBy)
+                throw new Error("native_sandbox_worker_unready: the worker pod did not start in time.");
+            await this.sleep(pollMs);
+        }
+        const command = nativeEnforcementProbe(await this.resolveGatewayHost());
+        const provenBy = Date.now() + (this.options.enforcementTimeoutMs ?? 30_000);
+        let last;
+        for (;;) {
+            last = await this.api
+                .exec(this.ns, podName, NATIVE_WORKER_CONTAINER, command, { timeoutMs: 20_000 })
+                .catch(() => NATIVE_PROBE.gatewayUnreachable);
+            if (last === NATIVE_PROBE.proven)
+                return;
+            if (Date.now() >= provenBy)
+                break;
+            await this.sleep(pollMs);
+        }
+        const why = last === NATIVE_PROBE.denyReachable
+            ? "the gateway's deny port was reachable"
+            : last === NATIVE_PROBE.outsideReachable
+                ? "an outside address was reachable"
+                : "the gateway was unreachable";
+        throw new Error(`${NATIVE_SANDBOX_NETWORK_UNENFORCED}: the worker pod's isolation could not be proven (${why}).`);
+    }
+    handle(runId) {
+        return this.handleByName(nativeKubernetesNames(runId).pod);
+    }
+    handleByName(podName, onExit) {
+        const exited = (async () => {
+            for (;;) {
+                const state = await this.inspectByName(podName);
+                if (state.state === "exited") {
+                    await onExit?.(state.exitCode).catch(() => { });
+                    return state.exitCode;
+                }
+                if (state.state === "missing")
+                    return null;
+                await this.sleep(this.options.pollMs ?? 1_000);
+            }
+        })();
+        return { exited, kill: () => void this.api.deletePod(this.ns, podName, 0) };
+    }
+    async inspect(runId) {
+        return this.inspectByName(nativeKubernetesNames(runId).pod);
+    }
+    async inspectByName(podName) {
+        const pod = await this.api.readPod(this.ns, podName);
+        if (!pod)
+            return { state: "missing" };
+        const phase = pod.status?.phase;
+        if (phase === "Succeeded" || phase === "Failed") {
+            const terminated = pod.status?.containerStatuses?.find((c) => c.name === NATIVE_WORKER_CONTAINER)?.state
+                ?.terminated;
+            return { state: "exited", exitCode: terminated?.exitCode ?? 137 };
+        }
+        return { state: "running" };
+    }
+    async kill(runId) {
+        await this.api.deletePod(this.ns, nativeKubernetesNames(runId).pod, 0);
+    }
+    async remove(runId) {
+        await this.removeByWorkerName(nativeKubernetesNames(runId).pod);
+    }
+    async listWorkers() {
+        const pods = await this.api.listPods(this.ns, NATIVE_RUN_SELECTOR);
+        return pods
+            .map((pod) => ({ name: pod.metadata?.name ?? "", runHash: pod.metadata?.labels?.[NATIVE_RUN_SHA_LABEL] ?? "" }))
+            .filter((worker) => worker.name && worker.runHash);
+    }
+    async removeByWorkerName(name) {
+        if (!/^wardby-native-[0-9a-f]{20}$/.test(name))
+            return;
+        await this.api.deletePod(this.ns, name, 0);
+        await this.api.deleteSecret(this.ns, `${name}-input`);
+        await this.api.deleteNetworkPolicy(this.ns, name);
+    }
+    // --- Warm pool workers (native sandbox phase 6) ---
+    warmPod(token, waitMs) {
+        return buildNativeWarmPod({
+            token,
+            waitMs,
+            namespace: this.ns,
+            image: this.options.image,
+            limits: this.options.limits,
+            // A claimed worker keeps the run's whole deadline however long it waited.
+            activeDeadlineSeconds: Math.ceil(waitMs / 1000) + this.options.deadlineSeconds,
+            runtimeClassName: this.options.runtimeClassName,
+            platform: this.options.platform,
+            priorityClassName: this.options.priorityClassName,
+        });
+    }
+    warmSpecHash(waitMs) {
+        const { image, limits, runtimeClassName, platform, priorityClassName, gatewayService, gatewayUrl } = this.options;
+        const spec = { launcher: "kubernetes", ns: this.ns, image, limits, runtimeClassName, platform, priorityClassName };
+        return createHash("sha256")
+            .update(JSON.stringify({ ...spec, gatewayService, gatewayUrl, waitMs }))
+            .digest("hex");
+    }
+    async startWarm(token, waitMs) {
+        await this.createIsolated(this.warmPod(token, waitMs), buildNativeWarmNetworkPolicy(token, this.ns), () => this.removeWarm(token));
+    }
+    async reattestWarm(token, waitMs) {
+        const pod = await this.api.readPod(this.ns, nativeWarmWorkerName(token));
+        if (pod?.status?.phase !== "Running")
+            return false;
+        return this.matches(this.warmPod(token, waitMs), buildNativeWarmNetworkPolicy(token, this.ns));
+    }
+    async deliver(token, input) {
+        const code = await this.api.exec(this.ns, nativeWarmWorkerName(token), NATIVE_WORKER_CONTAINER, warmDeliveryCommand(), {
+            timeoutMs: 20_000,
+            stdin: Readable.from([`${JSON.stringify(input)}\n`]),
+        });
+        if (code !== 0) {
+            throw new Error(`${NATIVE_SANDBOX_WARM_DELIVERY_FAILED}: delivering the run's input exited ${code}.`);
+        }
+    }
+    warmHandle(token) {
+        return this.handleByName(nativeWarmWorkerName(token));
+    }
+    inspectWarm(token) {
+        return this.inspectByName(nativeWarmWorkerName(token));
+    }
+    async killWarm(token) {
+        await this.api.deletePod(this.ns, nativeWarmWorkerName(token), 0);
+    }
+    async removeWarm(token) {
+        const name = nativeWarmWorkerName(token);
+        await this.api.deletePod(this.ns, name, 0);
+        await this.api.deleteNetworkPolicy(this.ns, name);
+    }
+    async listWarm() {
+        const pods = await this.api.listPods(this.ns, NATIVE_WARM_SELECTOR);
+        return pods
+            .map((pod) => pod.metadata?.labels?.[NATIVE_WARM_TOKEN_LABEL] ?? "")
+            .filter((token) => /^[0-9a-f]{20}$/.test(token));
+    }
+}

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

@@ -0,0 +1,62 @@
+/**
+ * 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;
+}
+export interface WorkerLaunchOptions {
+    /**
+     * Asked after any slow wait (a low-power wake) and before a worker is created: false means the
+     * run ended meanwhile, and the launch stops with NATIVE_SANDBOX_LAUNCH_ABANDONED, creating nothing.
+     */
+    stillWanted?: () => Promise<boolean>;
+    /**
+     * Every secret value the worker may be handed (each user tool's readable or brokered secrets),
+     * for masking a failed worker's output tail before the launcher logs it; the run's capability is
+     * masked from the input itself. Rejects when any read fails. Absent or rejected: no tail is
+     * logged (fail closed).
+     */
+    secretValues?: () => Promise<readonly string[]>;
+}
+/** The run ended while its worker was launching, so none was created. */
+export declare const NATIVE_SANDBOX_LAUNCH_ABANDONED = "native_sandbox_launch_abandoned";
+/** Starts a worker for an HTTP-gateway input and returns at once. */
+export interface DetachedWorkerLauncher {
+    launch(input: WorkerInput, options?: WorkerLaunchOptions): 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;
+    stillWanted?: () => Promise<boolean>;
+}): Promise<StartSandboxRunOutcome>;

package/dist/native-worker/launch.js

@@ -0,0 +1,49 @@
+/**
+ * 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 run ended while its worker was launching, so none was created. */
+export const NATIVE_SANDBOX_LAUNCH_ABANDONED = "native_sandbox_launch_abandoned";
+/** 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, {
+        ...(options.stillWanted ? { stillWanted: options.stillWanted } : {}),
+        secretValues: session.secretValues,
+    });
+    return { kind: "launched", sessionId: session.sessionId, handle };
+}

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

@@ -0,0 +1,125 @@
+/**
+ * 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";
+import { ReviewReadLedger } from "../core/review-reads.js";
+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;
+    /** The run's saved review reads (ReviewReadsState), or null before it reads a pull request. */
+    reviewReads?: unknown;
+}
+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>;
+    /**
+     * Adds one request's review reads to the session's saved ones, under the session's row lock:
+     * reads only add, so parallel tool calls of one run each keep what they read.
+     */
+    mergeReviewReads(sessionId: string, reads: ReviewReadLedger): 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). Without an estimate the
+     * reservation stays held; with one, the call counts at the estimate instead.
+     */
+    markUncertain(sessionId: string, callId: string, estimate?: SettledUsage): Promise<void>;
+    /**
+     * Median output tokens of the session's completed model calls (all on the run's one model), or
+     * undefined before the first one: the output of a call cut with nothing streamed.
+     */
+    medianOutputTokens(sessionId: string): Promise<number | undefined>;
+    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[]>;
+}