@wardby/cli 0.5.3 → 0.7.0

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;

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

@@ -0,0 +1,86 @@
+/**
+ * A model request's hold: what the proxy reserves against the run's budget before forwarding it.
+ * After a mostly cached reply in the same conversation, the part of the prompt the previous reply
+ * read from (or wrote to) the cache is priced at the cache-read rate; everything else, including
+ * what the body grew by (one token per byte), at the input + cache-write rates. Capped at the
+ * ceiling, today's worst case (the whole body as uncached input), which a reply may never exceed.
+ */
+import { createHash } from "node:crypto";
+import { estimateReservationUsd } from "./metering.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 const CACHE_WINDOW_MS = 5 * 60_000;
+export const MIN_CACHED_SHARE = 0.5;
+function withoutCacheControl(value) {
+    if (Array.isArray(value))
+        return value.map(withoutCacheControl);
+    if (!value || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .filter(([key]) => key !== "cache_control")
+        .map(([key, inner]) => [key, withoutCacheControl(inner)]));
+}
+/**
+ * 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 function conversationKey(protocol, body) {
+    let basis;
+    if (protocol === "anthropic-messages") {
+        const messages = body.messages;
+        if (!Array.isArray(messages) || messages.length === 0)
+            return null;
+        // Claude Code's first message can carry the date, so a conversation crossing midnight starts a
+        // new key (its next request falls back to the worst case once).
+        basis = ["anthropic", withoutCacheControl(messages[0])];
+    }
+    else if (typeof body.prompt_cache_key === "string" && body.prompt_cache_key) {
+        basis = ["openai-key", body.prompt_cache_key];
+    }
+    else {
+        const input = body.input;
+        const first = typeof input === "string" ? input : Array.isArray(input) ? input[0] : undefined;
+        if (first === undefined)
+            return null;
+        basis = ["openai-first", body.instructions ?? null, first];
+    }
+    return createHash("sha256").update(JSON.stringify(basis)).digest("base64url");
+}
+export function estimateHold(input) {
+    const ceilingUsd = estimateReservationUsd(input.bodyBytes, input.maxOutputTokens, input.pricing);
+    const full = (fallback) => ({ holdUsd: ceilingUsd, ceilingUsd, basis: "full", fallback });
+    const previous = input.previous;
+    if (!previous)
+        return full("no_previous");
+    if (previous.model !== input.model)
+        return full("model_changed");
+    if (previous.costEstimated)
+        return full("previous_estimated");
+    if (previous.status !== "completed" || !previous.usage)
+        return full("previous_not_completed");
+    if (previous.requestBytes === null)
+        return full("no_request_bytes");
+    if (input.now.getTime() - previous.startedAt.getTime() > CACHE_WINDOW_MS)
+        return full("cache_expired");
+    if (input.bodyBytes < previous.requestBytes)
+        return full("body_shrank");
+    const usage = previous.usage;
+    const prevPrompt = usage.inputTokens + usage.cacheWriteTokens;
+    const cachedTokens = input.protocol === "anthropic-messages"
+        ? usage.cachedInputTokens + usage.cacheWriteTokens
+        : usage.cachedInputTokens;
+    if (prevPrompt <= 0 || cachedTokens < prevPrompt * MIN_CACHED_SHARE)
+        return full("low_cache_share");
+    const uncachedTokens = prevPrompt + (input.bodyBytes - previous.requestBytes) - cachedTokens;
+    const { pricing } = input;
+    const cacheReadRate = pricing.cachedInputPerMTok ?? pricing.inputPerMTok;
+    const cacheWriteRate = pricing.cacheWritePerMTok ?? pricing.inputPerMTok;
+    const holdUsd = (cachedTokens * cacheReadRate +
+        uncachedTokens * (pricing.inputPerMTok + cacheWriteRate) +
+        input.maxOutputTokens * pricing.outputPerMTok) /
+        1_000_000;
+    return { holdUsd: Math.min(holdUsd, ceilingUsd), ceilingUsd, basis: "cached", cachedTokens, uncachedTokens };
+}

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

@@ -0,0 +1,70 @@
+import { type ModelPricing } from "../llm/pricing-core.js";
+import type { PreviousReply, ProxyUsage } from "./types.js";
+export interface InterruptedFacts {
+    /** Anthropic message_start usage already read (inputTokens includes cache reads, not writes). */
+    readUsage?: {
+        inputTokens: number;
+        cachedInputTokens: number;
+        cacheWriteTokens: number;
+    };
+    /** Output tokens the upstream reported so far (Anthropic message_delta), if any. */
+    reportedOutputTokens?: number;
+    /** message_start's output count: a placeholder (usually 1), so only a floor, never the count. */
+    outputFloorTokens?: number;
+    /** A stream that failed before its response started: the provider generated no output. */
+    beforeResponse?: boolean;
+    /** UTF-8 bytes of output relayed to the client before the break: text, tool input, thinking. */
+    relayedOutputBytes: number;
+    /** The input of the request's own prompt, from its conversation's previous reply (previousInput). */
+    previous?: ProxyUsage;
+    /** UTF-8 bytes of the request body the proxy forwarded, when known. */
+    bodyBytes?: number;
+    /** Median outputTokens of the session's completed replies for the same model, if any. */
+    medianOutputTokens?: number;
+    /** The request's hold and the output tokens it reserved for. */
+    reservationUsd: number;
+    maxOutputTokens: number;
+    /** The request's worst case (its ceiling); the estimate never exceeds it. Defaults to the hold. */
+    ceilingUsd?: number;
+}
+export interface InterruptedEstimate {
+    usage: ProxyUsage;
+    costUsd: number;
+}
+/** Output tokens for relayed text: ceil(bytes / 3), a deliberately high count. */
+export declare function relayedOutputTokens(bytes: number): number;
+/**
+ * Prompt tokens for request-body bytes in a settled estimate: ceil(bytes / 3), the same high count
+ * as the native gateway's byte estimate. Coding-agent bodies are mostly code, JSON and English,
+ * which tokenize at about 3.5 to 4.5 bytes a token, so a token per 3 bytes stays above the real
+ * count. Text that tokenizes tighter is mostly multi-byte UTF-8 (3 bytes a character, rarely more
+ * than a token each), and base64 images are billed by size, not bytes, so both still lean high.
+ * The hold itself still counts a token per byte (hold.ts): this is only the settled estimate.
+ */
+export declare function bodyInputTokens(bytes: number): number;
+/**
+ * The input of a cut request from its conversation's previous reply: that reply's prompt and cache
+ * split, plus the body's growth since (bodyInputTokens) as uncached input (uncachedInput).
+ * Undefined when that reply can't stand for this prompt, as for the hold (hold.ts): another model,
+ * estimated or unfinished, an unknown or larger body, or a cache that had expired by the time the
+ * request was reserved. The estimate then prices the whole body as uncached input.
+ */
+export declare function previousInput(input: {
+    model: string;
+    bodyBytes: number | undefined;
+    previous: PreviousReply | null;
+    pricing: ModelPricing;
+    /** When the request was reserved: the hold's own clock. */
+    now: Date;
+}): ProxyUsage | undefined;
+/**
+ * The best known cost of a reply that broke before its final usage (spec PR 1
+ * › 1b): usage already read, else the input from its conversation's previous
+ * reply (previousInput), else the whole body as uncached input
+ * (bodyInputTokens), else (body size unknown) the input part of the hold; plus
+ * the output seen so far. With no output seen, the model's median completed
+ * reply, or none while there is no completed reply (a deliberate rule: one cut
+ * must not book a whole reserved reply). A stream that failed before its
+ * response started generated none. Never more than the request's worst case.
+ */
+export declare function estimateInterrupted(facts: InterruptedFacts, pricing: ModelPricing): InterruptedEstimate;

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

@@ -0,0 +1,104 @@
+import { computeCost } from "../llm/pricing-core.js";
+import { CACHE_WINDOW_MS } from "./hold.js";
+/** Output tokens for relayed text: ceil(bytes / 3), a deliberately high count. */
+export function relayedOutputTokens(bytes) {
+    return bytes > 0 ? Math.ceil(bytes / 3) : 0;
+}
+/**
+ * Prompt tokens for request-body bytes in a settled estimate: ceil(bytes / 3), the same high count
+ * as the native gateway's byte estimate. Coding-agent bodies are mostly code, JSON and English,
+ * which tokenize at about 3.5 to 4.5 bytes a token, so a token per 3 bytes stays above the real
+ * count. Text that tokenizes tighter is mostly multi-byte UTF-8 (3 bytes a character, rarely more
+ * than a token each), and base64 images are billed by size, not bytes, so both still lean high.
+ * The hold itself still counts a token per byte (hold.ts): this is only the settled estimate.
+ */
+export function bodyInputTokens(bytes) {
+    return bytes > 0 ? Math.ceil(bytes / 3) : 0;
+}
+/**
+ * New prompt tokens as usage, at the higher of the model's fresh-input and cache-write rates: the
+ * provider may write them to its cache (Claude Code marks the latest message; OpenAI GPT-5.6 and
+ * later bill cache writes above input), or bill them as input.
+ */
+function uncachedInput(tokens, pricing) {
+    const written = (pricing.cacheWritePerMTok ?? pricing.inputPerMTok) > pricing.inputPerMTok;
+    return { inputTokens: written ? 0 : tokens, cacheWriteTokens: written ? tokens : 0 };
+}
+/**
+ * The input of a cut request from its conversation's previous reply: that reply's prompt and cache
+ * split, plus the body's growth since (bodyInputTokens) as uncached input (uncachedInput).
+ * Undefined when that reply can't stand for this prompt, as for the hold (hold.ts): another model,
+ * estimated or unfinished, an unknown or larger body, or a cache that had expired by the time the
+ * request was reserved. The estimate then prices the whole body as uncached input.
+ */
+export function previousInput(input) {
+    const { previous, bodyBytes } = input;
+    if (!previous || previous.model !== input.model || previous.costEstimated)
+        return undefined;
+    if (previous.status !== "completed" || !previous.usage)
+        return undefined;
+    if (bodyBytes === undefined || previous.requestBytes === null || bodyBytes < previous.requestBytes)
+        return undefined;
+    if (input.now.getTime() - previous.startedAt.getTime() > CACHE_WINDOW_MS)
+        return undefined;
+    const growth = uncachedInput(bodyInputTokens(bodyBytes - previous.requestBytes), input.pricing);
+    const usage = previous.usage;
+    return {
+        inputTokens: usage.inputTokens + growth.inputTokens,
+        cachedInputTokens: usage.cachedInputTokens,
+        cacheWriteTokens: usage.cacheWriteTokens + growth.cacheWriteTokens,
+        outputTokens: 0,
+        reasoningTokens: 0,
+    };
+}
+/**
+ * The best known cost of a reply that broke before its final usage (spec PR 1
+ * › 1b): usage already read, else the input from its conversation's previous
+ * reply (previousInput), else the whole body as uncached input
+ * (bodyInputTokens), else (body size unknown) the input part of the hold; plus
+ * the output seen so far. With no output seen, the model's median completed
+ * reply, or none while there is no completed reply (a deliberate rule: one cut
+ * must not book a whole reserved reply). A stream that failed before its
+ * response started generated none. Never more than the request's worst case.
+ */
+export function estimateInterrupted(facts, pricing) {
+    const relayed = relayedOutputTokens(facts.relayedOutputBytes);
+    const output = relayed > 0 || facts.beforeResponse ? relayed : (facts.medianOutputTokens ?? 0);
+    const clamp = (cost) => Math.max(0, Math.min(cost, facts.ceilingUsd ?? facts.reservationUsd));
+    if (facts.readUsage) {
+        const usage = {
+            ...facts.readUsage,
+            outputTokens: facts.reportedOutputTokens ?? Math.max(facts.outputFloorTokens ?? 0, output),
+            reasoningTokens: 0,
+        };
+        return { usage, costUsd: clamp(computeCost(pricing, usage)) };
+    }
+    if (facts.previous) {
+        const usage = {
+            inputTokens: facts.previous.inputTokens,
+            cachedInputTokens: facts.previous.cachedInputTokens,
+            cacheWriteTokens: facts.previous.cacheWriteTokens,
+            outputTokens: output,
+            reasoningTokens: 0,
+        };
+        return { usage, costUsd: clamp(computeCost(pricing, usage)) };
+    }
+    if (facts.bodyBytes !== undefined) {
+        const usage = {
+            ...uncachedInput(bodyInputTokens(facts.bodyBytes), pricing),
+            cachedInputTokens: 0,
+            outputTokens: output,
+            reasoningTokens: 0,
+        };
+        return { usage, costUsd: clamp(computeCost(pricing, usage)) };
+    }
+    const usage = {
+        inputTokens: 0,
+        cachedInputTokens: 0,
+        cacheWriteTokens: 0,
+        outputTokens: output,
+        reasoningTokens: 0,
+    };
+    const inputPart = facts.reservationUsd - (facts.maxOutputTokens * pricing.outputPerMTok) / 1_000_000;
+    return { usage, costUsd: clamp(inputPart + (usage.outputTokens * pricing.outputPerMTok) / 1_000_000) };
+}

package/dist/providers/coding-proxy/memory-ledger.d.ts

@@ -1,18 +1,31 @@
-import { type CreateProxySessionInput, type ProxyLedger, type ProxyRequest, type ProxySession, type ProxyUsage, type ReserveProxyRequestInput, type ReserveProxyRequestResult } from "./types.js";
+import { type PreviousReply, type CreateProxySessionInput, type ProxyLedger, type ProxyRefusalRecord, type ProxyRequest, type ProxySession, type ProxyUsage, type ReserveProxyRequestInput, type ReserveProxyRequestResult } from "./types.js";
 /** Deterministic contract adapter. Sharing one instance simulates a proxy restart. */
 export declare class MemoryProxyLedger implements ProxyLedger {
+    private readonly options;
     private readonly sessions;
     private readonly sessionByCapability;
     private readonly requests;
     private readonly requestBySessionKey;
+    private readonly startedAt;
+    constructor(options?: {
+        now?: () => Date;
+    });
     createSession(input: CreateProxySessionInput): Promise<void>;
     findSessionByCapabilityHash(capabilityHash: string): Promise<ProxySession | null>;
     reserve(input: ReserveProxyRequestInput): Promise<ReserveProxyRequestResult>;
     complete(requestId: string, usage: ProxyUsage, actualCostUsd: number, upstreamStatus: number): Promise<ProxyRequest>;
     release(requestId: string, upstreamStatus: number): Promise<void>;
-    markUncertain(requestId: string, upstreamStatus?: number): Promise<void>;
+    markUncertain(requestId: string, upstreamStatus?: number, estimate?: {
+        usage: ProxyUsage;
+        costUsd: number;
+    }): Promise<void>;
+    settlementHints(sessionId: string, model: string): Promise<{
+        medianOutputTokens?: number;
+    }>;
+    previousReply(sessionId: string, conversationKey: string): Promise<PreviousReply | null>;
     cancelSession(sessionId: string): Promise<void>;
     budgetExhausted(sessionId: string): Promise<boolean>;
+    budgetRefusal(sessionId: string): Promise<ProxyRefusalRecord | null>;
     recordUpstreamFailure(sessionId: string, code: string): Promise<void>;
     upstreamFailure(sessionId: string): Promise<string | null>;
     getRequest(requestId: string): Promise<ProxyRequest | null>;

package/dist/providers/coding-proxy/memory-ledger.js

@@ -5,6 +5,7 @@ function cloneSession(session) {
         allowedModels: [...session.allowedModels],
         deadlineAt: new Date(session.deadlineAt),
         budgetExhaustedAt: session.budgetExhaustedAt ? new Date(session.budgetExhaustedAt) : null,
+        budgetRefusal: session.budgetRefusal ? { ...session.budgetRefusal } : null,
         upstreamFailure: session.upstreamFailure ?? null,
         terms: session.terms
             ? { version: session.terms.version, entry: { ...session.terms.entry, efforts: [...session.terms.entry.efforts] } }
@@ -20,10 +21,15 @@ function cloneRequest(request) {
 }
 /** Deterministic contract adapter. Sharing one instance simulates a proxy restart. */
 export class MemoryProxyLedger {
+    options;
     sessions = new Map();
     sessionByCapability = new Map();
     requests = new Map();
     requestBySessionKey = new Map();
+    startedAt = new Map();
+    constructor(options = {}) {
+        this.options = options;
+    }
     async createSession(input) {
         if ([...this.sessions.values()].some((session) => session.runId === input.runId)) {
             throw new Error("proxy_session_exists");
@@ -54,22 +60,47 @@ export class MemoryProxyLedger {
         const existingId = this.requestBySessionKey.get(lookupKey);
         if (existingId)
             return { outcome: "duplicate", request: cloneRequest(this.requests.get(existingId)) };
-        let committedOrHeld = 0;
+        let spent = 0;
+        let heldReserved = 0;
+        let heldUncertain = 0;
+        let done = 0;
         for (const request of this.requests.values()) {
             if (request.sessionId !== input.sessionId)
                 continue;
-            if (request.status === "completed")
-                committedOrHeld += request.actualCostUsd;
-            if (request.status === "reserved" || request.status === "uncertain")
-                committedOrHeld += request.reservationUsd;
+            // An uncertain request settled at an estimate counts at it; one without an estimate keeps its hold.
+            const settled = request.status === "completed" || (request.status === "uncertain" && request.costEstimated);
+            if (settled) {
+                spent += request.actualCostUsd;
+                done += 1;
+            }
+            else if (request.status === "reserved")
+                heldReserved += request.reservationUsd;
+            else if (request.status === "uncertain")
+                heldUncertain += request.reservationUsd;
         }
+        const committedOrHeld = spent + heldReserved + heldUncertain;
         if (committedOrHeld + input.reservationUsd >= session.budgetUsd) {
-            session.budgetExhaustedAt ??= new Date(input.now);
-            return { outcome: "budget_exhausted" };
+            const details = {
+                budgetUsd: session.budgetUsd,
+                spentUsd: spent,
+                heldReservedUsd: heldReserved,
+                heldUncertainUsd: heldUncertain,
+                refusedHoldUsd: input.reservationUsd,
+                ...(input.reservationBasis ? { refusedHoldBasis: input.reservationBasis } : {}),
+                ...(input.ceilingUsd !== undefined ? { refusedHoldCeilingUsd: input.ceilingUsd } : {}),
+                model: input.model,
+                turn: done + 1,
+            };
+            if (!session.budgetExhaustedAt) {
+                session.budgetExhaustedAt = new Date(input.now);
+                session.budgetRefusal = { source: "proxy", ...details };
+            }
+            return { outcome: "budget_exhausted", details };
         }
         const request = { ...input, pricing: { ...input.pricing }, status: "reserved" };
         this.requests.set(request.id, request);
         this.requestBySessionKey.set(lookupKey, request.id);
+        this.startedAt.set(request.id, new Date(input.now));
         return { outcome: "reserved", request: cloneRequest(request) };
     }
     async complete(requestId, usage, actualCostUsd, upstreamStatus) {
@@ -86,6 +117,7 @@ export class MemoryProxyLedger {
         request.actualCostUsd = actualCostUsd;
         request.usage = { ...usage };
         request.upstreamStatus = upstreamStatus;
+        request.costEstimated = false;
         return cloneRequest(request);
     }
     async release(requestId, upstreamStatus) {
@@ -95,12 +127,52 @@ export class MemoryProxyLedger {
         request.status = "released";
         request.upstreamStatus = upstreamStatus;
     }
-    async markUncertain(requestId, upstreamStatus) {
+    async markUncertain(requestId, upstreamStatus, estimate) {
         const request = this.requiredRequest(requestId);
         if (request.status !== "reserved")
             return;
         request.status = "uncertain";
         request.upstreamStatus = upstreamStatus;
+        if (estimate) {
+            request.actualCostUsd = estimate.costUsd;
+            request.usage = { ...estimate.usage };
+            request.costEstimated = true;
+        }
+    }
+    async settlementHints(sessionId, model) {
+        const outputs = [];
+        for (const request of this.requests.values()) {
+            if (request.sessionId !== sessionId || request.model !== model)
+                continue;
+            if (request.status !== "completed" || !request.usage)
+                continue;
+            outputs.push(request.usage.outputTokens);
+        }
+        outputs.sort((a, b) => a - b);
+        return {
+            // The lower middle for an even count, as Postgres's percentile_disc(0.5).
+            ...(outputs.length > 0 ? { medianOutputTokens: outputs[Math.ceil(outputs.length / 2) - 1] } : {}),
+        };
+    }
+    async previousReply(sessionId, conversationKey) {
+        let latest;
+        // Map iteration follows insertion order: the last match is the latest request.
+        for (const request of this.requests.values()) {
+            if (request.sessionId !== sessionId || request.conversationKey !== conversationKey)
+                continue;
+            if (request.status === "completed" || request.status === "uncertain")
+                latest = request;
+        }
+        if (!latest)
+            return null;
+        return {
+            model: latest.model,
+            status: latest.status,
+            costEstimated: latest.costEstimated === true,
+            ...(latest.usage ? { usage: { ...latest.usage } } : {}),
+            requestBytes: latest.requestBytes ?? null,
+            startedAt: this.startedAt.get(latest.id) ?? new Date(0),
+        };
     }
     async cancelSession(sessionId) {
         const session = this.sessions.get(sessionId);
@@ -110,6 +182,10 @@ export class MemoryProxyLedger {
     async budgetExhausted(sessionId) {
         return Boolean(this.sessions.get(sessionId)?.budgetExhaustedAt);
     }
+    async budgetRefusal(sessionId) {
+        const refusal = this.sessions.get(sessionId)?.budgetRefusal;
+        return refusal ? { ...refusal } : null;
+    }
     async recordUpstreamFailure(sessionId, code) {
         const session = this.sessions.get(sessionId);
         if (session)