@wardby/cli 0.6.0 → 0.7.0

package/dist/providers/coding-proxy/dependency-cache/service.js

@@ -0,0 +1,409 @@
+import { createHash } from "node:crypto";
+import { pipeline, Transform } from "node:stream";
+import { logger } from "../../../core/logger.js";
+import { BlobStoreError } from "../../storage/types.js";
+import { capabilityHash } from "../proxy.js";
+import { DEPENDENCY_CACHE_ECOSYSTEM, deriveSnapshotKey, isLockHash, newBlobKey, parseProjectPath, } from "./key.js";
+const cacheLog = logger.child({ module: "dependency-cache" });
+const ARCHIVE_SCAN_VERSION = 1;
+const MAX_ARCHIVE_ENTRIES = 1_000_000;
+/** Uploads streaming at once across every run. */
+export const DEFAULT_MAX_CONCURRENT_UPLOADS = 4;
+const SNAPSHOT_ID = /^[a-z0-9]{1,64}$/;
+/** Matches a `/cache/...` path; a number is the refusal's status code. */
+function matchRoute(method, pathname) {
+    const prefix = `/cache/${DEPENDENCY_CACHE_ECOSYSTEM}/`;
+    if (!pathname.startsWith(prefix))
+        return 404;
+    const rest = pathname.slice(prefix.length);
+    const expect = (wanted, route, id) => (method === wanted ? { route, id } : 405);
+    if (rest === "lookup")
+        return expect("GET", "lookup");
+    if (rest === "seal")
+        return expect("POST", "seal");
+    if (rest === "blob")
+        return expect("PUT", "upload");
+    if (rest.startsWith("blob/")) {
+        const id = rest.slice("blob/".length);
+        return SNAPSHOT_ID.test(id) ? expect("GET", "download", id) : 404;
+    }
+    return 404;
+}
+class CacheRefusal extends Error {
+    status;
+    code;
+    constructor(status, code) {
+        super(code);
+        this.status = status;
+        this.code = code;
+    }
+}
+function send(response, status, body, close = false) {
+    if (response.headersSent || response.destroyed)
+        return;
+    response.writeHead(status, {
+        "content-type": "application/json",
+        "cache-control": "no-store",
+        ...(close ? { connection: "close" } : {}),
+    });
+    response.end(JSON.stringify(body));
+}
+/**
+ * The archive scan the worker ran before uploading, recorded with the
+ * snapshot. Protocol: an upload carries `x-wardby-archive-scan-version`,
+ * `x-wardby-archive-entries` and `x-wardby-archive-unpacked-bytes`, all three
+ * or none (a partial or malformed set is refused). Only an upload accepted
+ * before the run's seal stores them, so they come from trusted pre-agent
+ * worker code, never from the agent. A lookup returns them as `manifest` (and
+ * `nearest.manifest`) with the sha256 this proxy computed and recorded for the
+ * row, so a worker trusts them only for bytes that verify against that digest.
+ * Optional so workers deployed before validation metadata remain compatible.
+ */
+function verifiedArchiveHeaders(headers) {
+    const version = headers["x-wardby-archive-scan-version"];
+    const entries = headers["x-wardby-archive-entries"];
+    const unpackedBytes = headers["x-wardby-archive-unpacked-bytes"];
+    if (version === undefined && entries === undefined && unpackedBytes === undefined)
+        return null;
+    if (typeof version !== "string" || typeof entries !== "string" || typeof unpackedBytes !== "string")
+        throw new CacheRefusal(400, "bad_request");
+    const parsedVersion = Number(version);
+    const parsedEntries = Number(entries);
+    const parsedUnpackedBytes = Number(unpackedBytes);
+    if (parsedVersion !== ARCHIVE_SCAN_VERSION ||
+        !Number.isSafeInteger(parsedEntries) ||
+        parsedEntries < 1 ||
+        parsedEntries > MAX_ARCHIVE_ENTRIES ||
+        !Number.isSafeInteger(parsedUnpackedBytes) ||
+        parsedUnpackedBytes < 0)
+        throw new CacheRefusal(400, "bad_request");
+    return { archiveScanVersion: parsedVersion, archiveEntries: parsedEntries, unpackedBytes: parsedUnpackedBytes };
+}
+function lookupManifest(row) {
+    const { archiveScanVersion, archiveEntries, unpackedBytes } = row;
+    if (archiveScanVersion !== ARCHIVE_SCAN_VERSION ||
+        archiveEntries === null ||
+        unpackedBytes === null ||
+        !Number.isSafeInteger(archiveEntries) ||
+        archiveEntries < 1 ||
+        archiveEntries > MAX_ARCHIVE_ENTRIES ||
+        !Number.isSafeInteger(unpackedBytes) ||
+        unpackedBytes < 0)
+        return undefined;
+    return { scanVersion: ARCHIVE_SCAN_VERSION, sha256: row.sha256, entries: archiveEntries, unpackedBytes };
+}
+export class DependencyCacheService {
+    options;
+    uploadMs;
+    now;
+    /** `runId\0projectPath` and key ids of uploads streaming right now (per replica). */
+    uploading = new Set();
+    activeUploads = 0;
+    constructor(options) {
+        this.options = options;
+        this.uploadMs = options.uploadMs;
+        this.now = options.now ?? (() => new Date());
+    }
+    /**
+     * Answers one `/cache/...` request. `token` is the registry token the
+     * request carried. `releaseBodyTimer` lifts the server's per-request body
+     * timer; it is called only for an authenticated, eligible upload that holds
+     * its upload slot (the upload window bounds it from then on).
+     */
+    async handle(request, response, token, releaseBodyTimer = () => { }) {
+        const url = new URL(request.url ?? "/", "http://proxy");
+        const matched = matchRoute(request.method, url.pathname);
+        const isUpload = typeof matched === "object" && matched.route === "upload";
+        // Filled in once the token is known to belong to a run, for the refusal log.
+        const known = {};
+        try {
+            if (matched === 404)
+                throw new CacheRefusal(404, "not_found");
+            if (matched === 405)
+                throw new CacheRefusal(405, "method_not_allowed");
+            await this.route(matched.route, matched.id, url.searchParams, token, request, response, releaseBodyTimer, known);
+        }
+        catch (error) {
+            if (error instanceof CacheRefusal) {
+                // One line per refusal: a fixed route name and code, and the run when the token named one
+                // (never the token, the query or the URL).
+                cacheLog.info({
+                    event: "dependency_cache.refused",
+                    ...(known.runId ? { runId: known.runId } : {}),
+                    route: typeof matched === "object" ? matched.route : "unknown",
+                    status: error.status,
+                    code: error.code,
+                }, "dependency cache request refused");
+                // An upload refused before its body was read: close rather than read it.
+                send(response, error.status, { error: error.code }, isUpload);
+                return;
+            }
+            cacheLog.error({ event: "dependency_cache.failed", err: error }, "dependency cache request failed");
+            if (!response.headersSent)
+                send(response, 500, { error: "internal_error" }, isUpload);
+            else if (!response.destroyed)
+                response.destroy();
+        }
+    }
+    async route(route, id, params, token, request, response, releaseBodyTimer, known) {
+        const context = await this.options.registry.findRunByRegistryTokenHash(capabilityHash(token), this.now());
+        if (!context)
+            throw new CacheRefusal(401, "invalid_capability");
+        known.runId = context.runId;
+        // The feature is off for this run: indistinguishable from a proxy without it.
+        if (!context.dependencyCache || !context.cacheImage)
+            throw new CacheRefusal(404, "not_found");
+        const session = await this.options.store.session(context.runId);
+        if (!session)
+            throw new CacheRefusal(401, "invalid_capability");
+        if (route === "seal") {
+            await this.options.store.seal(context.runId, this.now());
+            send(response, 200, { sealed: true });
+            return;
+        }
+        if (session.sealedAt)
+            throw new CacheRefusal(409, "sealed");
+        for (const name of new Set(params.keys()))
+            if (params.getAll(name).length > 1)
+                throw new CacheRefusal(400, "bad_request");
+        const projectPath = parseProjectPath(params.get("project"));
+        if (projectPath === null)
+            throw new CacheRefusal(400, "invalid_project");
+        const lockHash = params.get("lock") ?? "";
+        if (!isLockHash(lockHash) || !session.lockHashes.includes(lockHash))
+            throw new CacheRefusal(409, "plan_required");
+        const key = deriveSnapshotKey({
+            repository: context.repository,
+            projectPath,
+            lockHash,
+            workerImage: context.cacheImage,
+        });
+        if (route === "lookup")
+            await this.lookup(key, session.createdAt, response);
+        else if (route === "download")
+            await this.download(context.runId, key, id ?? "", response);
+        else
+            await this.upload(context, session.createdAt, key, request, response, releaseBodyTimer);
+    }
+    /** When the run's upload window closes (epoch ms): the one deadline lookups report and uploads enforce. */
+    uploadDeadline(sessionCreatedAt) {
+        return sessionCreatedAt.getTime() + this.uploadMs;
+    }
+    async lookup(key, sessionCreatedAt, response) {
+        const row = await this.options.store.findByIdentity(key);
+        const nearest = row ? null : await this.options.store.findNearest(key, key.lockHash);
+        const manifest = row ? lookupManifest(row) : undefined;
+        const nearestManifest = nearest ? lookupManifest(nearest) : undefined;
+        send(response, 200, {
+            key: key.keyId,
+            hit: row !== null,
+            ...(manifest ? { manifest } : {}),
+            ...(nearest ? { nearest: { id: nearest.id, ...(nearestManifest ? { manifest: nearestManifest } : {}) } } : {}),
+            maxBytes: this.options.maxSnapshotBytes,
+            uploadExpiresInMs: Math.max(0, Math.floor(this.uploadDeadline(sessionCreatedAt) - this.now().getTime())),
+        });
+    }
+    /**
+     * Serves the run's derived key (by its keyId) or the snapshot a lookup
+     * offers as nearest for the same project and lockfile, recomputed now with
+     * the same query: nothing is remembered between requests, and no other id
+     * is ever served.
+     */
+    async download(runId, key, id, response) {
+        let row = null;
+        if (id === key.keyId)
+            row = await this.options.store.findByIdentity(key);
+        else {
+            const nearest = await this.options.store.findNearest(key, key.lockHash);
+            if (nearest?.id === id)
+                row = nearest;
+        }
+        if (!row)
+            throw new CacheRefusal(404, "not_found");
+        let stream;
+        try {
+            stream = await this.options.blobs.getStream(row.blobKey);
+        }
+        catch (error) {
+            if (!(error instanceof BlobStoreError && error.code === "not_found"))
+                throw error;
+            // A row without its blob would answer hits forever: drop it.
+            await this.options.store.delete(row.id);
+            cacheLog.info({ event: "dependency_cache.blob_missing", runId, snapshotId: row.id }, "dependency cache snapshot had no blob and was removed");
+            throw new CacheRefusal(404, "not_found");
+        }
+        try {
+            await this.options.store.touch(row.id, this.now());
+        }
+        catch (error) {
+            cacheLog.warn({ event: "dependency_cache.touch_failed", err: error }, "dependency cache: lastUsedAt not updated");
+        }
+        response.writeHead(200, {
+            "content-type": "application/gzip",
+            "content-length": String(row.sizeBytes),
+            "x-wardby-sha256": row.sha256,
+            "cache-control": "no-store",
+        });
+        // Hash and count while streaming. The flush runs only once the blob was
+        // read to its end (a client abort destroys the pipeline before it), so only
+        // a complete read that disagrees with the row (or a blob longer than it)
+        // condemns the snapshot. The response then fails at once (the pipeline
+        // destroys it) instead of ending, or leaving the client waiting for the
+        // rest of its content-length.
+        const hash = createHash("sha256");
+        let bytes = 0;
+        const corrupt = () => {
+            void this.dropCorrupt(runId, row, bytes);
+            return new Error("snapshot_corrupt");
+        };
+        const verify = new Transform({
+            transform(chunk, _encoding, callback) {
+                bytes += chunk.length;
+                if (bytes > row.sizeBytes)
+                    return callback(corrupt());
+                hash.update(chunk);
+                callback(null, chunk);
+            },
+            flush: (callback) => {
+                if (bytes === row.sizeBytes && hash.digest("hex") === row.sha256)
+                    callback();
+                else
+                    callback(corrupt());
+            },
+        });
+        pipeline(stream, verify, response, (error) => {
+            if (error && !response.destroyed)
+                response.destroy();
+        });
+    }
+    /** Removes a snapshot whose blob failed its row's checksum, so the key can be rebuilt. */
+    async dropCorrupt(runId, row, readBytes) {
+        try {
+            // Only while the row still names the blob that was streamed: a re-upload may have replaced it.
+            if (!(await this.options.store.deleteIfBlob(row.id, row.blobKey)))
+                return;
+            await this.discard(row.blobKey);
+            cacheLog.warn({
+                event: "snapshot_corrupt",
+                runId,
+                expectedBytes: row.sizeBytes,
+                readBytes,
+            }, "dependency cache snapshot failed its checksum and was removed");
+        }
+        catch (error) {
+            cacheLog.warn({ event: "dependency_cache.corrupt_cleanup_failed", err: error }, "dependency cache: cleanup failed");
+        }
+    }
+    async upload(context, sessionCreatedAt, key, request, response, releaseBodyTimer) {
+        const deadline = this.uploadDeadline(sessionCreatedAt);
+        if (this.now().getTime() >= deadline)
+            throw new CacheRefusal(409, "upload_expired");
+        const encoding = request.headers["content-encoding"];
+        if (encoding && encoding !== "identity")
+            throw new CacheRefusal(400, "bad_request");
+        const length = request.headers["content-length"];
+        if (length !== undefined && (!/^\d+$/.test(length) || Number(length) > this.options.maxSnapshotBytes))
+            throw new CacheRefusal(413, "too_large");
+        const verifiedArchive = verifiedArchiveHeaders(request.headers);
+        const projectSlot = `${context.runId}\0${key.projectPath}`;
+        if (this.uploading.has(projectSlot) || this.uploading.has(key.keyId))
+            throw new CacheRefusal(409, "upload_in_progress");
+        if (await this.options.store.hasUploaded(context.runId, key.ecosystem, key.projectPath))
+            throw new CacheRefusal(409, "already_uploaded");
+        if (await this.options.store.findByIdentity(key)) {
+            send(response, 200, { stored: false, reason: "exists" }, true);
+            return;
+        }
+        if (this.activeUploads >= (this.options.maxConcurrentUploads ?? DEFAULT_MAX_CONCURRENT_UPLOADS))
+            throw new CacheRefusal(503, "busy");
+        // Re-checked after the awaits above: the slot is taken synchronously.
+        if (this.uploading.has(projectSlot) || this.uploading.has(key.keyId))
+            throw new CacheRefusal(409, "upload_in_progress");
+        this.uploading.add(projectSlot);
+        this.uploading.add(key.keyId);
+        this.activeUploads += 1;
+        releaseBodyTimer();
+        try {
+            await this.storeUpload(context, deadline, key, request, response, verifiedArchive);
+        }
+        finally {
+            this.uploading.delete(projectSlot);
+            this.uploading.delete(key.keyId);
+            this.activeUploads -= 1;
+        }
+    }
+    async storeUpload(context, deadline, key, request, response, verifiedArchive) {
+        const blobKey = newBlobKey(key);
+        let expired = false;
+        const timer = setTimeout(() => {
+            expired = true;
+            request.destroy();
+        }, Math.max(0, deadline - this.now().getTime()));
+        let stored;
+        try {
+            stored = await this.options.blobs.putStream(blobKey, request, {
+                contentType: "application/gzip",
+                maxBytes: this.options.maxSnapshotBytes,
+            });
+        }
+        catch (error) {
+            if (error instanceof BlobStoreError && error.code === "blob_too_large")
+                throw new CacheRefusal(413, "too_large");
+            if (expired)
+                throw new CacheRefusal(409, "upload_expired");
+            // The client went away mid-upload: nothing to answer.
+            if (request.destroyed || response.destroyed)
+                return;
+            throw error;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        // Checked only now, after the last byte arrived: every byte of an
+        // accepted upload was sent before the seal (so before the agent ran).
+        const session = await this.options.store.session(context.runId);
+        const refusal = !session || session.sealedAt ? "sealed" : this.now().getTime() >= deadline ? "upload_expired" : null;
+        if (refusal) {
+            await this.discard(blobKey);
+            throw new CacheRefusal(409, refusal);
+        }
+        let outcome;
+        try {
+            outcome = await this.options.store.insert({
+                ecosystem: key.ecosystem,
+                repository: key.repository,
+                projectPath: key.projectPath,
+                lockHash: key.lockHash,
+                workerImage: key.workerImage,
+                blobKey,
+                sha256: stored.sha256,
+                sizeBytes: stored.sizeBytes,
+                archiveScanVersion: verifiedArchive?.archiveScanVersion ?? null,
+                archiveEntries: verifiedArchive?.archiveEntries ?? null,
+                unpackedBytes: verifiedArchive?.unpackedBytes ?? null,
+                createdByRunId: context.runId,
+            });
+        }
+        catch (error) {
+            await this.discard(blobKey);
+            throw error;
+        }
+        if (outcome === "exists") {
+            // Another upload of this key committed first; its object is untouched.
+            await this.discard(blobKey);
+            send(response, 200, { stored: false, reason: "exists" });
+            return;
+        }
+        cacheLog.info({ event: "dependency_cache.stored", runId: context.runId, sizeBytes: stored.sizeBytes }, "dependency cache snapshot stored");
+        send(response, 201, { stored: true, sha256: stored.sha256, sizeBytes: stored.sizeBytes });
+    }
+    /** Removes an upload's own blob object (unique to the upload, so no row refers to it). */
+    async discard(blobKey) {
+        try {
+            await this.options.blobs.delete(blobKey);
+        }
+        catch (error) {
+            cacheLog.warn({ event: "dependency_cache.discard_failed", err: error }, "dependency cache: blob not removed");
+        }
+    }
+}

package/dist/providers/coding-proxy/dependency-cache/store.d.ts

@@ -0,0 +1,85 @@
+import type { DependencyCacheSessionState } from "../registry/store.js";
+/**
+ * The value every snapshot row stores in its `policyHash` column, and the only
+ * value lookups match. The column and its unique index predate dropping the
+ * agent's package policy from the key (see key.ts for why), so they stay
+ * unchanged; rows written before carry a real policy hash, never match again,
+ * and age out through eviction.
+ */
+export declare const POLICY_ANY = "any";
+/** The parts every snapshot of one project shares, whatever its lockfile. */
+export interface SnapshotScope {
+    ecosystem: string;
+    repository: string;
+    projectPath: string;
+    workerImage: string;
+}
+export interface SnapshotIdentity extends SnapshotScope {
+    lockHash: string;
+}
+export interface NewSnapshot extends SnapshotIdentity {
+    blobKey: string;
+    sha256: string;
+    sizeBytes: number;
+    archiveScanVersion: number | null;
+    archiveEntries: number | null;
+    unpackedBytes: number | null;
+    createdByRunId: string;
+}
+export interface SnapshotRow extends SnapshotIdentity {
+    id: string;
+    blobKey: string;
+    sha256: string;
+    sizeBytes: number;
+    archiveScanVersion: number | null;
+    archiveEntries: number | null;
+    unpackedBytes: number | null;
+    createdAt: Date;
+    lastUsedAt: Date;
+    createdByRunId: string | null;
+}
+/** What eviction needs of every snapshot. */
+export type EvictionRow = Pick<SnapshotRow, "id" | "repository" | "blobKey" | "sizeBytes" | "createdAt" | "lastUsedAt">;
+/** DependencySnapshot rows and the session fields the cache reads (Postgres in production). */
+export interface DependencyCacheStore {
+    session(runId: string): Promise<DependencyCacheSessionState | null>;
+    /** Sets the session's sealedAt unless it is already set. */
+    seal(runId: string, now: Date): Promise<void>;
+    /** Like `seal`, but only for a run whose agent has the cache on (a model request's seal, ModelRequestSeal). */
+    sealForModelRequest(runId: string, now: Date): Promise<void>;
+    findByIdentity(identity: SnapshotIdentity): Promise<SnapshotRow | null>;
+    /** The most recent snapshot in the scope whose lockHash differs (ties broken by id), or null. */
+    findNearest(scope: SnapshotScope, excludeLockHash: string): Promise<SnapshotRow | null>;
+    /** Whether the run already created a snapshot for this project. */
+    hasUploaded(runId: string, ecosystem: string, projectPath: string): Promise<boolean>;
+    /** "exists" when a snapshot with the same identity (or blob key) is already stored. */
+    insert(snapshot: NewSnapshot): Promise<"inserted" | "exists">;
+    touch(id: string, now: Date): Promise<void>;
+    delete(id: string): Promise<void>;
+    /** Deletes the row only while it still points at `blobKey` (a re-upload may have replaced it); true when deleted. */
+    deleteIfBlob(id: string, blobKey: string): Promise<boolean>;
+    listForEviction(): Promise<EvictionRow[]>;
+    /** Runs `work` while holding the cluster-wide eviction lock; returns false (without running it) when another holder has it. */
+    withEvictionLock(work: () => Promise<void>): Promise<boolean>;
+}
+/** In-memory adapter for tests. `sessions` may be shared with a MemoryRegistryStore's `cacheSessions`. */
+export declare class MemoryDependencyCacheStore implements DependencyCacheStore {
+    readonly sessions: Map<string, DependencyCacheSessionState>;
+    readonly rows: SnapshotRow[];
+    private evicting;
+    /** Runs whose agent has the cache off (sealForModelRequest leaves them alone). */
+    readonly cacheOff: Set<string>;
+    constructor(sessions?: Map<string, DependencyCacheSessionState>);
+    session(runId: string): Promise<DependencyCacheSessionState | null>;
+    seal(runId: string, now: Date): Promise<void>;
+    sealForModelRequest(runId: string, now: Date): Promise<void>;
+    findByIdentity(identity: SnapshotIdentity): Promise<SnapshotRow | null>;
+    findNearest(scope: SnapshotScope, excludeLockHash: string): Promise<SnapshotRow | null>;
+    hasUploaded(runId: string, ecosystem: string, projectPath: string): Promise<boolean>;
+    insert(snapshot: NewSnapshot): Promise<"inserted" | "exists">;
+    touch(id: string, now: Date): Promise<void>;
+    delete(id: string): Promise<void>;
+    deleteIfBlob(id: string, blobKey: string): Promise<boolean>;
+    listForEviction(): Promise<EvictionRow[]>;
+    withEvictionLock(work: () => Promise<void>): Promise<boolean>;
+}

package/dist/providers/coding-proxy/dependency-cache/store.js

@@ -0,0 +1,95 @@
+import { randomUUID } from "node:crypto";
+/**
+ * The value every snapshot row stores in its `policyHash` column, and the only
+ * value lookups match. The column and its unique index predate dropping the
+ * agent's package policy from the key (see key.ts for why), so they stay
+ * unchanged; rows written before carry a real policy hash, never match again,
+ * and age out through eviction.
+ */
+export const POLICY_ANY = "any";
+const sameScope = (row, scope) => row.ecosystem === scope.ecosystem &&
+    row.repository === scope.repository &&
+    row.projectPath === scope.projectPath &&
+    row.workerImage === scope.workerImage;
+/** In-memory adapter for tests. `sessions` may be shared with a MemoryRegistryStore's `cacheSessions`. */
+export class MemoryDependencyCacheStore {
+    sessions;
+    rows = [];
+    evicting = false;
+    /** Runs whose agent has the cache off (sealForModelRequest leaves them alone). */
+    cacheOff = new Set();
+    constructor(sessions = new Map()) {
+        this.sessions = sessions;
+    }
+    async session(runId) {
+        const session = this.sessions.get(runId);
+        return session ? { ...session, lockHashes: [...session.lockHashes] } : null;
+    }
+    async seal(runId, now) {
+        const session = this.sessions.get(runId);
+        if (session && !session.sealedAt)
+            session.sealedAt = now;
+    }
+    async sealForModelRequest(runId, now) {
+        if (!this.cacheOff.has(runId))
+            await this.seal(runId, now);
+    }
+    async findByIdentity(identity) {
+        return this.rows.find((row) => sameScope(row, identity) && row.lockHash === identity.lockHash) ?? null;
+    }
+    async findNearest(scope, excludeLockHash) {
+        const candidates = this.rows
+            .filter((row) => sameScope(row, scope) && row.lockHash !== excludeLockHash)
+            .sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime() || (a.id < b.id ? 1 : a.id > b.id ? -1 : 0));
+        return candidates[0] ?? null;
+    }
+    async hasUploaded(runId, ecosystem, projectPath) {
+        return this.rows.some((row) => row.createdByRunId === runId && row.ecosystem === ecosystem && row.projectPath === projectPath);
+    }
+    async insert(snapshot) {
+        if ((await this.findByIdentity(snapshot)) || this.rows.some((row) => row.blobKey === snapshot.blobKey))
+            return "exists";
+        const now = new Date();
+        this.rows.push({ ...snapshot, id: `c${randomUUID().replaceAll("-", "")}`, createdAt: now, lastUsedAt: now });
+        return "inserted";
+    }
+    async touch(id, now) {
+        const row = this.rows.find((candidate) => candidate.id === id);
+        if (row)
+            row.lastUsedAt = now;
+    }
+    async delete(id) {
+        const index = this.rows.findIndex((row) => row.id === id);
+        if (index >= 0)
+            this.rows.splice(index, 1);
+    }
+    async deleteIfBlob(id, blobKey) {
+        const index = this.rows.findIndex((row) => row.id === id && row.blobKey === blobKey);
+        if (index < 0)
+            return false;
+        this.rows.splice(index, 1);
+        return true;
+    }
+    async listForEviction() {
+        return this.rows.map(({ id, repository, blobKey, sizeBytes, createdAt, lastUsedAt }) => ({
+            id,
+            repository,
+            blobKey,
+            sizeBytes,
+            createdAt,
+            lastUsedAt,
+        }));
+    }
+    async withEvictionLock(work) {
+        if (this.evicting)
+            return false;
+        this.evicting = true;
+        try {
+            await work();
+            return true;
+        }
+        finally {
+            this.evicting = false;
+        }
+    }
+}

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

@@ -0,0 +1,32 @@
+import type { ModelPricing } from "../llm/pricing-core.js";
+import type { PreviousReply, ProxyProtocol, ReservationBasis } from "./types.js";
+/**
+ * Anthropic's prompt cache lives 5 minutes from when a request is processed, not from when its reply
+ * finishes: a previous request sent longer ago than this says nothing about the cache.
+ */
+export declare const CACHE_WINDOW_MS: number;
+export declare const MIN_CACHED_SHARE = 0.5;
+export type HoldFallback = "no_previous" | "model_changed" | "previous_estimated" | "previous_not_completed" | "no_request_bytes" | "cache_expired" | "body_shrank" | "low_cache_share";
+export interface HoldEstimate {
+    holdUsd: number;
+    ceilingUsd: number;
+    basis: ReservationBasis;
+    fallback?: HoldFallback;
+    cachedTokens?: number;
+    uncachedTokens?: number;
+}
+/**
+ * What identifies one conversation within a run (Claude Code runs several: the main one and its
+ * sub-agents). Anthropic: the first message without cache markers (the system prompt carries a
+ * per-version billing line). OpenAI: prompt_cache_key, else instructions + the first input item.
+ */
+export declare function conversationKey(protocol: ProxyProtocol, body: Record<string, unknown>): string | null;
+export declare function estimateHold(input: {
+    protocol: ProxyProtocol;
+    model: string;
+    bodyBytes: number;
+    maxOutputTokens: number;
+    pricing: ModelPricing;
+    previous: PreviousReply | null;
+    now: Date;
+}): HoldEstimate;