@wardby/cli 0.2.1 → 0.4.0

package/dist/providers/coding-proxy/registry/store.d.ts

@@ -0,0 +1,127 @@
+import type { PackageAllowlist } from "../../../coding/registry/allowlist.js";
+import type { DeclaredDependency } from "../../../coding/registry/types.js";
+export interface RegistryRunContext {
+    runId: string;
+    deadlineAt: Date;
+    allowlist: PackageAllowlist;
+    policy: unknown;
+}
+export interface RegistryFetchRecord {
+    runId: string;
+    ecosystem: string;
+    name: string;
+    version?: string;
+    filename?: string;
+    integrity?: string;
+    sizeBytes?: number;
+    outcome: "served" | "refused";
+    reason?: string;
+}
+/** A registry-verified version fact as stored: always with its publish time. */
+export interface StoredVersionFact {
+    name: string;
+    version: string;
+    publishedAt: Date;
+    integrity: string;
+    downloadUrl: string;
+    dependencies: readonly DeclaredDependency[];
+}
+/** One exact version a lockfile plan approved for a run. */
+export interface ApprovedVersion {
+    name: string;
+    version: string;
+    integrity: string;
+}
+/** One exact version a lockfile plan definitively refused for a run. */
+export interface PlanRefusedVersion {
+    name: string;
+    version: string;
+    code: string;
+    reason: string;
+    /** Set for a too-new refusal: it lapses once the version is old enough. */
+    publishedAt?: Date | null;
+}
+/** Run-scoped store over the registry-only token session lookup and the
+ *  RegistryAllowance/RegistryFetch tables (Task 5). Backs the registry proxy:
+ *  it never sees the model capability, only the derived registry token. */
+export interface RegistryStore {
+    findRunByRegistryTokenHash(hash: string, now: Date): Promise<RegistryRunContext | null>;
+    isAllowedDependency(runId: string, ecosystem: string, name: string): Promise<boolean>;
+    addAllowances(runId: string, ecosystem: string, names: readonly string[]): Promise<void>;
+    recordFetch(record: RegistryFetchRecord): Promise<void>;
+    usage(runId: string): Promise<{
+        files: number;
+        bytes: number;
+    }>;
+    /** Number of refused RegistryFetch rows recorded for the run. */
+    refusalCount(runId: string): Promise<number>;
+    listFetches(runId: string): Promise<(RegistryFetchRecord & {
+        createdAt: Date;
+    })[]>;
+    /** Stored facts for these versions (any not stored are absent). */
+    getVersionFacts(ecosystem: string, versions: readonly {
+        name: string;
+        version: string;
+    }[]): Promise<StoredVersionFact[]>;
+    /** Stores facts; one already stored is kept as it is (facts are immutable). */
+    putVersionFacts(ecosystem: string, facts: readonly StoredVersionFact[]): Promise<void>;
+    /** Approves exact versions for the run (an existing approval is kept). */
+    approveVersions(runId: string, ecosystem: string, versions: readonly ApprovedVersion[]): Promise<void>;
+    /** The run's approval of this exact version, with its download URL (from
+     *  the version's fact), or null. */
+    findApprovedVersion(runId: string, ecosystem: string, name: string, version: string): Promise<{
+        integrity: string;
+        downloadUrl: string;
+    } | null>;
+    /** Stores the run's plan refusals (an existing one is kept). */
+    refusePlanVersions(runId: string, ecosystem: string, versions: readonly PlanRefusedVersion[]): Promise<void>;
+    /** The run's plan refusal of this exact version, or null. */
+    findPlanRefusal(runId: string, ecosystem: string, name: string, version: string): Promise<{
+        code: string;
+        reason: string;
+        publishedAt: Date | null;
+    } | null>;
+}
+/** In-memory adapter for tests. `contexts` is settable directly so tests can
+ *  seed a run without going through a full proxy session. */
+export declare class MemoryRegistryStore implements RegistryStore {
+    readonly contexts: Map<string, RegistryRunContext>;
+    readonly allowances: Set<string>;
+    readonly fetches: (RegistryFetchRecord & {
+        createdAt: Date;
+    })[];
+    /** `ecosystem\0name\0version` -> fact. */
+    readonly facts: Map<string, StoredVersionFact>;
+    /** `runId\0ecosystem\0name\0version` -> approval. */
+    readonly approvals: Map<string, ApprovedVersion>;
+    /** `runId\0ecosystem\0name\0version` -> plan refusal. */
+    readonly planRefusals: Map<string, PlanRefusedVersion>;
+    findRunByRegistryTokenHash(hash: string, now: Date): Promise<RegistryRunContext | null>;
+    isAllowedDependency(runId: string, ecosystem: string, name: string): Promise<boolean>;
+    addAllowances(runId: string, ecosystem: string, names: readonly string[]): Promise<void>;
+    recordFetch(record: RegistryFetchRecord): Promise<void>;
+    usage(runId: string): Promise<{
+        files: number;
+        bytes: number;
+    }>;
+    refusalCount(runId: string): Promise<number>;
+    listFetches(runId: string): Promise<(RegistryFetchRecord & {
+        createdAt: Date;
+    })[]>;
+    getVersionFacts(ecosystem: string, versions: readonly {
+        name: string;
+        version: string;
+    }[]): Promise<StoredVersionFact[]>;
+    putVersionFacts(ecosystem: string, facts: readonly StoredVersionFact[]): Promise<void>;
+    approveVersions(runId: string, ecosystem: string, versions: readonly ApprovedVersion[]): Promise<void>;
+    findApprovedVersion(runId: string, ecosystem: string, name: string, version: string): Promise<{
+        integrity: string;
+        downloadUrl: string;
+    } | null>;
+    refusePlanVersions(runId: string, ecosystem: string, versions: readonly PlanRefusedVersion[]): Promise<void>;
+    findPlanRefusal(runId: string, ecosystem: string, name: string, version: string): Promise<{
+        code: string;
+        reason: string;
+        publishedAt: Date | null;
+    } | null>;
+}

package/dist/providers/coding-proxy/registry/store.js

@@ -0,0 +1,70 @@
+/** In-memory adapter for tests. `contexts` is settable directly so tests can
+ *  seed a run without going through a full proxy session. */
+export class MemoryRegistryStore {
+    contexts = new Map();
+    allowances = new Set();
+    fetches = [];
+    /** `ecosystem\0name\0version` -> fact. */
+    facts = new Map();
+    /** `runId\0ecosystem\0name\0version` -> approval. */
+    approvals = new Map();
+    /** `runId\0ecosystem\0name\0version` -> plan refusal. */
+    planRefusals = new Map();
+    async findRunByRegistryTokenHash(hash, now) {
+        const context = this.contexts.get(hash);
+        return context && context.deadlineAt > now ? context : null;
+    }
+    async isAllowedDependency(runId, ecosystem, name) {
+        return this.allowances.has(`${runId}\0${ecosystem}\0${name}`);
+    }
+    async addAllowances(runId, ecosystem, names) {
+        for (const name of names)
+            this.allowances.add(`${runId}\0${ecosystem}\0${name}`);
+    }
+    async recordFetch(record) {
+        this.fetches.push({ ...record, createdAt: new Date() });
+    }
+    async usage(runId) {
+        const served = this.fetches.filter((fetch) => fetch.runId === runId && fetch.outcome === "served");
+        return { files: served.length, bytes: served.reduce((sum, fetch) => sum + (fetch.sizeBytes ?? 0), 0) };
+    }
+    async refusalCount(runId) {
+        return this.fetches.filter((fetch) => fetch.runId === runId && fetch.outcome === "refused").length;
+    }
+    async listFetches(runId) {
+        return this.fetches.filter((fetch) => fetch.runId === runId);
+    }
+    async getVersionFacts(ecosystem, versions) {
+        return versions.flatMap(({ name, version }) => this.facts.get(`${ecosystem}\0${name}\0${version}`) ?? []);
+    }
+    async putVersionFacts(ecosystem, facts) {
+        for (const fact of facts) {
+            const key = `${ecosystem}\0${fact.name}\0${fact.version}`;
+            if (!this.facts.has(key))
+                this.facts.set(key, fact);
+        }
+    }
+    async approveVersions(runId, ecosystem, versions) {
+        for (const approval of versions) {
+            const key = `${runId}\0${ecosystem}\0${approval.name}\0${approval.version}`;
+            if (!this.approvals.has(key))
+                this.approvals.set(key, approval);
+        }
+    }
+    async findApprovedVersion(runId, ecosystem, name, version) {
+        const approval = this.approvals.get(`${runId}\0${ecosystem}\0${name}\0${version}`);
+        const fact = this.facts.get(`${ecosystem}\0${name}\0${version}`);
+        return approval && fact ? { integrity: approval.integrity, downloadUrl: fact.downloadUrl } : null;
+    }
+    async refusePlanVersions(runId, ecosystem, versions) {
+        for (const refusal of versions) {
+            const key = `${runId}\0${ecosystem}\0${refusal.name}\0${refusal.version}`;
+            if (!this.planRefusals.has(key))
+                this.planRefusals.set(key, refusal);
+        }
+    }
+    async findPlanRefusal(runId, ecosystem, name, version) {
+        const refusal = this.planRefusals.get(`${runId}\0${ecosystem}\0${name}\0${version}`);
+        return refusal ? { code: refusal.code, reason: refusal.reason, publishedAt: refusal.publishedAt ?? null } : null;
+    }
+}

package/dist/providers/coding-proxy/runtime.d.ts

@@ -1,12 +1,29 @@
 import type { PrismaClient } from "#prisma";
+import type { UpstreamFetch } from "../../coding/registry/types.js";
 import { startDenyPortListener } from "./deny-port.js";
+import { type PinnedProxyFetchOptions } from "./secure-fetch.js";
 import { startCodingProxyServer, type CodingProxyServerHandle } from "./server.js";
 import type { ProxyAuditSink } from "./types.js";
+/** Adapts the pinned upstream `fetch` (which only forwards `init.headers`)
+ *  to `UpstreamFetch`'s narrower init shape: `accept` becomes an `accept`
+ *  header, `acceptEncoding` an `accept-encoding` header (the pinned fetch
+ *  never decompresses; the caller that asks for gzip does), and a `content-type: application/json` header is set whenever a
+ *  body is present (every registry/OSV upstream call sends or expects
+ *  JSON). Exported so its header-mapping can be unit-tested directly,
+ *  without needing a live upstream. */
+export declare function createRegistryUpstream(pinned: typeof globalThis.fetch): UpstreamFetch;
 export interface CodingProxyRuntimeOptions {
     db: PrismaClient;
+    /** The package registry's own client, so its traffic (many concurrent
+     *  downloads during an install) cannot starve the budget ledger that every
+     *  model request needs. Defaults to `db`. */
+    registryDb?: PrismaClient;
     env?: NodeJS.ProcessEnv;
     startServer?: typeof startCodingProxyServer;
     startDenyPort?: typeof startDenyPortListener;
+    /** Overridable for tests: proves the OSV host and every adapter's
+     *  upstream hosts are actually passed to the pinned-fetch allowlist. */
+    createPinnedFetch?: (options: PinnedProxyFetchOptions) => typeof globalThis.fetch;
     audit?: ProxyAuditSink;
     onRequest?: (event: {
         protocol: "openai-responses" | "anthropic-messages" | "other";

package/dist/providers/coding-proxy/runtime.js

@@ -1,9 +1,40 @@
+import { REGISTRY_ADAPTERS } from "../../coding/registry/adapters.js";
 import { CODING_PROXY_ALIAS, CODING_PROXY_DENY_PORT, CODING_PROXY_PORT } from "../jobs/docker-isolation.js";
 import { startDenyPortListener } from "./deny-port.js";
 import { EnvironmentCredentialResolver } from "./environment-credentials.js";
 import { CodingProxy } from "./proxy.js";
 import { PrismaProxyLedger } from "./prisma-ledger.js";
+import { OsvAudit } from "./registry/audit.js";
+import { PrismaRegistryStore } from "./registry/prisma-store.js";
+import { DEFAULT_PLAN_MAX_ENTRIES, DEFAULT_PLAN_TIMEOUT_MS } from "./registry/plan.js";
+import { DEFAULT_GRAPH_TIMEOUT_MS, DEFAULT_MAX_GRAPH_PACKAGES, DEFAULT_PLAN_MAX_PER_RUN, RegistryService, } from "./registry/service.js";
+import { createPinnedProxyFetch } from "./secure-fetch.js";
 import { startCodingProxyServer } from "./server.js";
+const MIB = 1024 * 1024;
+function positiveInt(value, fallback) {
+    const parsed = Number(value);
+    return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+/** Adapts the pinned upstream `fetch` (which only forwards `init.headers`)
+ *  to `UpstreamFetch`'s narrower init shape: `accept` becomes an `accept`
+ *  header, `acceptEncoding` an `accept-encoding` header (the pinned fetch
+ *  never decompresses; the caller that asks for gzip does), and a `content-type: application/json` header is set whenever a
+ *  body is present (every registry/OSV upstream call sends or expects
+ *  JSON). Exported so its header-mapping can be unit-tested directly,
+ *  without needing a live upstream. */
+export function createRegistryUpstream(pinned) {
+    return (url, init = {}) => pinned(url, {
+        method: init.method ?? "GET",
+        body: init.body,
+        signal: init.signal,
+        redirect: "error",
+        headers: {
+            ...(init.accept ? { accept: init.accept } : {}),
+            ...(init.acceptEncoding ? { "accept-encoding": init.acceptEncoding } : {}),
+            ...(init.body ? { "content-type": "application/json" } : {}),
+        },
+    });
+}
 /** Starts the trusted proxy with the fixed worker-only Docker endpoint, plus the deny port the enforcement witness probes. */
 export async function startConfiguredCodingProxy(options) {
     const env = options.env ?? process.env;
@@ -12,11 +43,43 @@ export async function startConfiguredCodingProxy(options) {
         credentials: new EnvironmentCredentialResolver(env),
         audit: options.audit,
     });
+    const buildPinnedFetch = options.createPinnedFetch ?? createPinnedProxyFetch;
+    const upstreamHosts = [...new Set([...REGISTRY_ADAPTERS.values()].flatMap((adapter) => adapter.upstreamHosts))];
+    const pinned = buildPinnedFetch({ allowedHosts: [...upstreamHosts, "api.osv.dev"] });
+    const upstream = createRegistryUpstream(pinned);
+    const metadataTimeoutMs = positiveInt(env.REGISTRY_METADATA_TIMEOUT_MS, 30_000);
+    const maxMetadataBytes = positiveInt(env.REGISTRY_MAX_METADATA_MB, 64) * MIB;
+    const registry = new RegistryService({
+        adapters: REGISTRY_ADAPTERS,
+        store: new PrismaRegistryStore(options.registryDb ?? options.db),
+        audit: new OsvAudit({
+            fetch: upstream,
+            failOpen: env.REGISTRY_AUDIT_FAIL_OPEN === "true",
+            timeoutMs: metadataTimeoutMs,
+            maxBytes: maxMetadataBytes,
+        }),
+        upstream,
+        metadataTimeoutMs,
+        maxMetadataBytes,
+        maxGraphPackages: positiveInt(env.REGISTRY_MAX_GRAPH_PACKAGES, DEFAULT_MAX_GRAPH_PACKAGES),
+        graphTimeoutMs: positiveInt(env.REGISTRY_GRAPH_TIMEOUT_MS, DEFAULT_GRAPH_TIMEOUT_MS),
+        planMaxEntries: positiveInt(env.REGISTRY_PLAN_MAX_ENTRIES, DEFAULT_PLAN_MAX_ENTRIES),
+        planTimeoutMs: positiveInt(env.REGISTRY_PLAN_TIMEOUT_MS, DEFAULT_PLAN_TIMEOUT_MS),
+        planMaxPerRun: positiveInt(env.REGISTRY_PLAN_MAX_PER_RUN, DEFAULT_PLAN_MAX_PER_RUN),
+        proxyBase: `http://${CODING_PROXY_ALIAS}:${CODING_PROXY_PORT}/registry/`,
+        limits: {
+            maxFileBytes: positiveInt(env.REGISTRY_MAX_FILE_MB, 200) * MIB,
+            maxTotalBytes: positiveInt(env.REGISTRY_MAX_TOTAL_MB, 2048) * MIB,
+            maxFiles: positiveInt(env.REGISTRY_MAX_FILES, 5000),
+            idleTimeoutMs: positiveInt(env.REGISTRY_IDLE_TIMEOUT_MS, 120_000),
+        },
+    });
     const startServer = options.startServer ?? startCodingProxyServer;
     const server = await startServer(proxy, {
         host: "0.0.0.0",
         port: CODING_PROXY_PORT,
         expectedHost: `${CODING_PROXY_ALIAS}:${CODING_PROXY_PORT}`,
+        registry,
         onRequest: options.onRequest,
     });
     let deny;

package/dist/providers/coding-proxy/secure-fetch.js

@@ -37,7 +37,6 @@ export function createPinnedProxyFetch(options) {
                 throw blocked();
             const destination = await resolveDestination(url, {
                 allowedHosts,
-                allowPrivateHosts: false,
                 restrictToAllowedHosts: true,
                 resolve: options.resolve,
             });

package/dist/providers/coding-proxy/server.d.ts

@@ -1,9 +1,19 @@
+import type { ProxyAuditEvent } from "./types.js";
 import { type CodingProxy } from "./proxy.js";
+import { type RegistryService } from "./registry/service.js";
 import type { ProxyProtocol } from "./types.js";
+declare const proxyLog: import("pino").Logger<never, boolean>;
+/**
+ * Writes a proxy audit event to the operator log. The events carry ids,
+ * models, amounts, statuses and fixed reason codes only, never request or
+ * response content. `sink` defaults to the proxy's own logger.
+ */
+export declare function logProxyAudit(event: ProxyAuditEvent, sink?: Pick<typeof proxyLog, "info">): void;
 export interface CodingProxyServerConfig {
     host: string;
     port: number;
     expectedHost?: string;
+    registry?: Pick<RegistryService, "handle"> & Partial<Pick<RegistryService, "plan">>;
     onRequest?: (event: {
         protocol: ProxyProtocol | "other";
         status: number;
@@ -15,3 +25,4 @@ export interface CodingProxyServerHandle {
     close(): Promise<void>;
 }
 export declare function startCodingProxyServer(proxy: CodingProxy, config: CodingProxyServerConfig): Promise<CodingProxyServerHandle>;
+export {};

package/dist/providers/coding-proxy/server.js

@@ -1,8 +1,21 @@
 import { createServer } from "node:http";
+import { StringDecoder } from "node:string_decoder";
+import { pipeline, Readable } from "node:stream";
 import { HTTP_LIMITS, HttpBoundaryError, readBody } from "../../mcp/transport/http-limits.js";
 import { logger } from "../../core/logger.js";
 import { CodingProxyError, PROXY_MAX_BODY_BYTES } from "./proxy.js";
+import { RegistryError } from "../../coding/registry/types.js";
+import { MAX_PLAN_BODY_BYTES } from "./registry/service.js";
 const proxyLog = logger.child({ module: "coding-proxy" });
+/**
+ * Writes a proxy audit event to the operator log. The events carry ids,
+ * models, amounts, statuses and fixed reason codes only, never request or
+ * response content. `sink` defaults to the proxy's own logger.
+ */
+export function logProxyAudit(event, sink = proxyLog) {
+    const { type, ...fields } = event;
+    sink.info({ ...fields, event: `audit.${type}` }, "coding proxy audit");
+}
 function sendError(response, status, code) {
     response
         .writeHead(status, { "content-type": "application/json", "cache-control": "no-store" })
@@ -13,6 +26,79 @@ function bearer(value) {
         return "";
     return value.slice(7);
 }
+/** The registry's own auth: a registry-only token (`rrg_…`) carried as either
+ *  a bearer token or the password half of HTTP basic auth (some clients,
+ *  e.g. pip, only support basic auth for a package index). */
+function registryToken(authorization) {
+    if (!authorization)
+        return "";
+    const bearerToken = bearer(authorization);
+    if (bearerToken)
+        return bearerToken;
+    const basic = authorization.match(/^Basic ([A-Za-z0-9+/=]+)$/);
+    if (!basic)
+        return "";
+    const decoded = Buffer.from(basic[1], "base64").toString("utf8");
+    const colon = decoded.indexOf(":");
+    return colon >= 0 ? decoded.slice(colon + 1) : "";
+}
+/** Time a client has to upload a lockfile to the plan route. */
+const PLAN_UPLOAD_MS = 60_000;
+function sendRegistry(response, result) {
+    response
+        .writeHead(result.status, { "content-type": result.contentType, "cache-control": "no-store" })
+        .end(result.body);
+}
+/** Reads a lockfile body within MAX_PLAN_BODY_BYTES, decoding each chunk
+ *  as it arrives (no buffered copy of the raw bytes), and joins the text
+ *  once. A RegistryError says why it could not be read. */
+function readPlanBody(request, signal) {
+    const tooLarge = () => new RegistryError(413, "wardby_lockfile_too_large", "the lockfile is larger than 20 MiB");
+    const length = request.headers["content-length"];
+    if (length !== undefined && (!/^\d+$/.test(length) || Number(length) > MAX_PLAN_BODY_BYTES))
+        return Promise.reject(tooLarge());
+    const encoding = request.headers["content-encoding"];
+    if (encoding && encoding !== "identity")
+        return Promise.reject(new RegistryError(400, "wardby_bad_request", "the lockfile must not be content-encoded"));
+    return new Promise((resolve, reject) => {
+        const decoder = new StringDecoder("utf8");
+        const parts = [];
+        let size = 0;
+        const cleanup = () => {
+            request.off("data", data);
+            request.off("end", end);
+            request.off("error", failed);
+            request.off("aborted", failed);
+            signal.removeEventListener("abort", failed);
+        };
+        const fail = (error) => {
+            cleanup();
+            parts.length = 0;
+            request.pause();
+            reject(error);
+        };
+        const failed = () => fail(new RegistryError(400, "wardby_bad_request", "the lockfile could not be read"));
+        const data = (chunk) => {
+            size += chunk.length;
+            if (size > MAX_PLAN_BODY_BYTES)
+                fail(tooLarge());
+            else
+                parts.push(decoder.write(chunk));
+        };
+        const end = () => {
+            cleanup();
+            parts.push(decoder.end());
+            resolve(parts.join(""));
+        };
+        request.on("data", data);
+        request.once("end", end);
+        request.once("error", failed);
+        request.once("aborted", failed);
+        signal.addEventListener("abort", failed, { once: true });
+        if (signal.aborted)
+            failed();
+    });
+}
 function routeProtocol(method, url) {
     if (method !== "POST")
         return undefined;
@@ -60,6 +146,83 @@ export async function startCodingProxyServer(proxy, config) {
                 sendError(response, 403, "invalid_host");
                 return;
             }
+            if (request.url?.startsWith("/registry/")) {
+                if (!config.registry) {
+                    sendError(response, 404, "not_found");
+                    return;
+                }
+                const plan = request.url.match(/^\/registry\/([a-z0-9-]+)\/-\/plan(?:\?.*)?$/);
+                if (plan && request.method === "POST" && config.registry.plan) {
+                    // Lockfile verification. The registry authenticates the token and
+                    // takes a plan slot before it asks for the body, which is then read
+                    // within its own size and time bounds.
+                    const controller = new AbortController();
+                    response.on("close", () => {
+                        if (!response.writableFinished)
+                            controller.abort();
+                    });
+                    let bodyRead = false;
+                    const result = await config.registry.plan({
+                        ecosystem: plan[1],
+                        token: registryToken(request.headers.authorization),
+                        readBody: () => {
+                            bodyRead = true;
+                            return readPlanBody(request, AbortSignal.any([controller.signal, AbortSignal.timeout(PLAN_UPLOAD_MS)]));
+                        },
+                        signal: controller.signal,
+                    });
+                    // Refused before the body was read: close the connection rather
+                    // than read (or keep) what the client is still sending.
+                    if (!bodyRead)
+                        response.setHeader("connection", "close");
+                    if ("body" in result)
+                        sendRegistry(response, result);
+                    else {
+                        void result.stream.cancel().catch(() => undefined);
+                        sendError(response, 500, "internal_error");
+                    }
+                    return;
+                }
+                if (request.method !== "GET" && request.method !== "HEAD") {
+                    sendError(response, 405, "method_not_allowed");
+                    return;
+                }
+                const match = request.url.match(/^\/registry\/([a-z0-9-]+)\/(.*)$/);
+                if (!match) {
+                    sendError(response, 404, "not_found");
+                    return;
+                }
+                const controller = new AbortController();
+                response.on("close", () => controller.abort());
+                const result = await config.registry.handle({
+                    method: request.method,
+                    ecosystem: match[1],
+                    subpath: match[2].split("?")[0],
+                    token: registryToken(request.headers.authorization),
+                    signal: controller.signal,
+                });
+                response.statusCode = result.status;
+                response.setHeader("content-type", result.contentType);
+                if ("body" in result) {
+                    response.end(request.method === "HEAD" ? undefined : result.body);
+                    return;
+                }
+                if (request.method === "HEAD") {
+                    // The registry answers HEAD without starting a download; cancel
+                    // defensively anyway so a stream can never hold a reservation.
+                    void result.stream.cancel().catch(() => undefined);
+                    response.end();
+                    return;
+                }
+                // pipeline (not .pipe) destroys the source when the client
+                // disconnects or the response errors, which cancels the web stream
+                // so the registry releases the run's in-flight reservation.
+                pipeline(Readable.fromWeb(result.stream), response, (error) => {
+                    if (error && !response.destroyed)
+                        response.destroy();
+                });
+                return;
+            }
             if (request.method === "HEAD" && request.url === "/api/hello") {
                 response.writeHead(200, { "cache-control": "no-store" }).end();
                 return;

package/dist/providers/coding-proxy/types.d.ts

@@ -1,10 +1,24 @@
-import type { ModelPricing } from "../llm/pricing.js";
+import { type CatalogEntry } from "../llm/catalog-types.js";
+import type { ModelPricing } from "../llm/pricing-core.js";
 export type ProxySessionStatus = "active" | "cancelled";
 export type ProxyRequestStatus = "reserved" | "completed" | "released" | "uncertain";
 export type ProxyProtocol = "openai-responses" | "anthropic-messages";
 export interface PricingSnapshot extends ModelPricing {
     version: string;
 }
+/** The model terms a coding run was dispatched under: its catalog entry and that entry's price version. */
+export interface ProxyModelTerms {
+    version: string;
+    entry: CatalogEntry;
+}
+/**
+ * Validates and copies model terms, for both ledgers on write and the database ledger on read.
+ * Throws invalid_proxy_session_terms: unreadable terms must refuse the session, never fall back.
+ */
+export declare function normalizeProxyModelTerms(terms: {
+    version: unknown;
+    entry: unknown;
+}): ProxyModelTerms;
 export interface ProxyUsage {
     inputTokens: number;
     outputTokens: number;
@@ -22,6 +36,13 @@ export interface ProxySession {
     deadlineAt: Date;
     budgetUsd: number;
     status: ProxySessionStatus;
+    registryTokenHash?: string | null;
+    /** When the ledger first refused a request of this session for budget. */
+    budgetExhaustedAt?: Date | null;
+    /** The code of the first upstream failure the proxy relayed for this session. */
+    upstreamFailure?: string | null;
+    /** The run's catalog entry, copied at session creation; null on sessions from before the catalog. */
+    terms?: ProxyModelTerms | null;
 }
 export interface ProxyRequest {
     id: string;
@@ -45,6 +66,8 @@ export interface CreateProxySessionInput {
     allowedModels: string[];
     deadlineAt: Date;
     budgetUsd: number;
+    registryTokenHash: string;
+    terms?: ProxyModelTerms;
 }
 export interface ReserveProxyRequestInput {
     id: string;
@@ -76,6 +99,12 @@ export interface ProxyLedger {
     release(requestId: string, upstreamStatus: number): Promise<void>;
     markUncertain(requestId: string, upstreamStatus?: number): Promise<void>;
     cancelSession(sessionId: string): Promise<void>;
+    /** Whether a request of this session was ever refused for budget. */
+    budgetExhausted(sessionId: string): Promise<boolean>;
+    /** Records an upstream failure code on the session; only the first one is kept. */
+    recordUpstreamFailure(sessionId: string, code: string): Promise<void>;
+    /** The first upstream failure code relayed for this session, if any. */
+    upstreamFailure(sessionId: string): Promise<string | null>;
     getRequest(requestId: string): Promise<ProxyRequest | null>;
 }
 export interface ProxyAuditEvent {
@@ -92,6 +121,9 @@ export interface ProxyAuditEvent {
     cachedInputTokens?: number;
     cacheWriteTokens?: number;
     reasoningTokens?: number;
+    /** For a failed stream: the upstream response's content type and encoding headers, for diagnosis. */
+    contentType?: string;
+    contentEncoding?: string;
 }
 export type ProxyAuditSink = (event: ProxyAuditEvent) => void;
 export interface CredentialResolver {

package/dist/providers/coding-proxy/types.js

@@ -1 +1,12 @@
-export {};
+import { parseStoredEntry } from "../llm/catalog-types.js";
+/**
+ * Validates and copies model terms, for both ledgers on write and the database ledger on read.
+ * Throws invalid_proxy_session_terms: unreadable terms must refuse the session, never fall back.
+ */
+export function normalizeProxyModelTerms(terms) {
+    const entry = parseStoredEntry(terms.entry);
+    if (typeof terms.version !== "string" || terms.version.length === 0 || !entry) {
+        throw new Error("invalid_proxy_session_terms");
+    }
+    return { version: terms.version, entry };
+}