@wardby/cli 0.2.0 → 0.3.0

package/dist/providers/auth/delegating.js

@@ -10,6 +10,63 @@
 import { createRemoteJWKSet, jwtVerify, errors as joseErrors } from "jose";
 import { AudienceError, NotSupportedError } from "./types.js";
 import { requireSubject } from "./subject.js";
+import { ROLE_NAMES, isRoleName } from "../../mcp/auth/resource-server.js";
+/**
+ * Parses AUTH_ROLE_MAP. Whitespace around entries and around `=` is ignored;
+ * an unknown wardby role, or a malformed or empty entry, is a startup error.
+ * The LAST `=` splits an entry (wardby role names never contain one).
+ */
+export function parseRoleMap(value) {
+    const map = new Map();
+    const entries = value.split(",").map((e) => e.trim());
+    if (entries.every((e) => !e))
+        throw new Error("AUTH_ROLE_MAP is empty.");
+    for (const entry of entries) {
+        if (!entry)
+            continue;
+        const at = entry.lastIndexOf("=");
+        const idpValue = at > 0 ? entry.slice(0, at).trim() : "";
+        const role = at > 0 ? entry.slice(at + 1).trim() : "";
+        if (!idpValue || !role)
+            throw new Error(`AUTH_ROLE_MAP entry "${entry}" must look like idpValue=wardbyRole.`);
+        if (!isRoleName(role))
+            throw new Error(`AUTH_ROLE_MAP maps "${idpValue}" to unknown role "${role}" (known: ${ROLE_NAMES.join(", ")}).`);
+        map.set(idpValue, [...new Set([...(map.get(idpValue) ?? []), role])]);
+    }
+    return map;
+}
+/**
+ * Resolves `claim` in a verified payload: an exact top-level name wins (claim
+ * names may themselves contain dots and slashes), otherwise a dotted path.
+ */
+function resolveClaim(payload, claim) {
+    if (Object.prototype.hasOwnProperty.call(payload, claim))
+        return payload[claim];
+    if (!claim.includes("."))
+        return undefined;
+    let value = payload;
+    for (const part of claim.split(".")) {
+        if (typeof value !== "object" || value === null || Array.isArray(value))
+            return undefined;
+        if (!Object.prototype.hasOwnProperty.call(value, part))
+            return undefined;
+        value = value[part];
+    }
+    return value;
+}
+/**
+ * Maps a resolved claim (a string, or an array of strings) through the role
+ * map; unmapped values are ignored, and any other shape yields no roles.
+ */
+function rolesFromClaim(value, map) {
+    const values = typeof value === "string" ? [value] : Array.isArray(value) ? value : [];
+    const roles = new Set();
+    for (const v of values)
+        if (typeof v === "string")
+            for (const r of map.get(v) ?? [])
+                roles.add(r);
+    return [...roles];
+}
 /**
  * Every spelling of the configured audience a token may legitimately carry.
  *
@@ -53,9 +110,16 @@ export class DelegatingAuthProvider {
     config;
     audiences;
     jwks;
+    roleMap;
     constructor(config, jwks) {
         if (!config.issuer || !config.audience)
             throw new Error("AUTH_ISSUER and AUTH_AUDIENCE are required.");
+        // Half a configuration would silently give everyone no roles while
+        // looking configured — refuse to start instead.
+        if ((config.roleClaim !== undefined || config.roleMap !== undefined) && (!config.roleClaim || !config.roleMap))
+            throw new Error("AUTH_ROLE_CLAIM and AUTH_ROLE_MAP must be set together (or both left unset).");
+        if (config.roleMap)
+            this.roleMap = parseRoleMap(config.roleMap);
         this.config = config;
         this.audiences = audienceCandidates(config.audience);
         if (jwks) {
@@ -80,6 +144,13 @@ export class DelegatingAuthProvider {
                 email: typeof payload.email === "string" ? payload.email : undefined,
                 roles: Array.isArray(payload.roles) ? payload.roles.map(String) : [],
                 scopes: scopesFromClaim(payload.scope ?? payload.scp),
+                // Read from the bearer token validated above for this issuer and
+                // audience (signature, expiry too); the IdP should mint that audience
+                // only into access tokens. Unconfigured, every caller has no roles
+                // and privileged operations are refused.
+                wardbyRoles: this.config.roleClaim && this.roleMap
+                    ? rolesFromClaim(resolveClaim(payload, this.config.roleClaim), this.roleMap)
+                    : [],
             };
         }
         catch (err) {

package/dist/providers/auth/index.d.ts

@@ -3,9 +3,11 @@
  * kind. Both adapters implement the same AuthProvider (incl. verifyBearer),
  * so the resource-server middleware and tool handlers never branch on mode.
  */
-import type { PrismaClient } from "@prisma/client";
+import type { PrismaClient } from "#prisma";
 import type { AuthProviderKind, AuthConfig } from "../../config/providers.js";
 import type { AuthProvider } from "./types.js";
 export { DelegatingAuthProvider } from "./delegating.js";
 export { SelfHostedAuthProvider } from "./self-hosted.js";
+/** Configuration that is valid but almost certainly not what the operator meant. */
+export declare function authConfigWarnings(kind: AuthProviderKind, config: AuthConfig): string[];
 export declare function buildAuthProvider(kind: AuthProviderKind, config: AuthConfig, db: PrismaClient): AuthProvider;

package/dist/providers/auth/index.js

@@ -1,8 +1,19 @@
 import { DelegatingAuthProvider } from "./delegating.js";
 import { SelfHostedAuthProvider } from "./self-hosted.js";
+import { logger } from "../../core/logger.js";
 export { DelegatingAuthProvider } from "./delegating.js";
 export { SelfHostedAuthProvider } from "./self-hosted.js";
+/** Configuration that is valid but almost certainly not what the operator meant. */
+export function authConfigWarnings(kind, config) {
+    const warnings = [];
+    if (kind === "self-hosted" && (config.roleClaim || config.roleMap))
+        warnings.push("AUTH_ROLE_CLAIM / AUTH_ROLE_MAP are set but ignored with AUTH_PROVIDER=self-hosted: self-hosted roles " +
+            "come from the database (`wardby auth user grant --subject <s> --role <role>`).");
+    return warnings;
+}
 export function buildAuthProvider(kind, config, db) {
+    for (const warning of authConfigWarnings(kind, config))
+        logger.warn({ module: "auth" }, warning);
     if (kind === "self-hosted") {
         if (!config.audience || !config.signingKey || !config.credentialHashKey) {
             throw new Error("AUTH_AUDIENCE, AUTH_SIGNING_KEY, and AUTH_CREDENTIAL_HASH_KEY are required.");

package/dist/providers/auth/self-hosted.d.ts

@@ -1,4 +1,4 @@
-import type { PrismaClient } from "@prisma/client";
+import type { PrismaClient } from "#prisma";
 import type { AuthProfile, AuthProvider, AuthTokens, VerifiedToken } from "./types.js";
 import { Credentials } from "../../mcp/auth/self-hosted/credentials.js";
 import { Sessions } from "../../mcp/auth/self-hosted/session.js";
@@ -34,7 +34,7 @@ export declare class SelfHostedAuthProvider implements AuthProvider {
     consentPage(sessionToken: string, interactionId: string): Promise<{
         interaction: {
             client: {
-                metadata: import("@prisma/client/runtime/library").JsonValue;
+                metadata: import("@prisma/client/runtime/client").JsonValue;
                 createdAt: Date;
                 clientId: string;
             };
@@ -42,15 +42,16 @@ export declare class SelfHostedAuthProvider implements AuthProvider {
             id: string;
             createdAt: Date;
             state: string | null;
+            clientId: string;
             expiresAt: Date;
             resource: string;
-            clientId: string;
             consumedAt: Date | null;
             redirectUri: string;
             codeChallenge: string;
             requestedScope: string;
         };
         challenge: string;
+        scopes: string[];
     }>;
     consent(sessionToken: string, interactionId: string, challenge: string, approve: boolean): Promise<string>;
     handleToken(params: TokenParams): Promise<TokenResult>;

package/dist/providers/auth/self-hosted.js

@@ -3,7 +3,7 @@ import { SignJWT, jwtVerify } from "jose";
 import { z } from "zod";
 import { NotSupportedError } from "./types.js";
 import { requireSubject } from "./subject.js";
-import { SCOPES_SUPPORTED } from "../../mcp/auth/resource-server.js";
+import { SCOPES_SUPPORTED, limitScope } from "../../mcp/auth/resource-server.js";
 import { canonicalUrl } from "../../mcp/transport/http-limits.js";
 import { Credentials, DAY, decodeKey, lockUser } from "../../mcp/auth/self-hosted/credentials.js";
 import { Sessions } from "../../mcp/auth/self-hosted/session.js";
@@ -106,7 +106,7 @@ export class SelfHostedAuthProvider {
         const metadata = client?.metadata;
         if (!metadata?.redirect_uris?.includes(p.redirectUri) || !metadata.grant_types?.includes("authorization_code"))
             throw new Error("Invalid client or redirect.");
-        const scope = [...new Set(p.scope.split(/\s+/).filter((s) => SCOPES_SUPPORTED.includes(s)))].join(" ");
+        const scope = limitScope(p.scope, SCOPES_SUPPORTED);
         const request = await this.db.oAuthAuthorizationRequest.create({
             data: {
                 clientId: p.clientId,
@@ -129,7 +129,10 @@ export class SelfHostedAuthProvider {
         if (!interaction || interaction.consumedAt || interaction.expiresAt.getTime() <= Date.now())
             throw new Error("Invalid interaction.");
         const challenge = await this.sessions.challenge("consent", session.sessionId, interactionId);
-        return { interaction, challenge };
+        // Exactly what approving issues: the stored (supported-only) request.
+        // It's fixed when the interaction is created, so what the page shows
+        // can't drift from what consent() puts on the code.
+        return { interaction, challenge, scopes: interaction.requestedScope.split(" ").filter(Boolean) };
     }
     async consent(sessionToken, interactionId, challenge, approve) {
         const first = await this.sessions.get(sessionToken);
@@ -339,7 +342,16 @@ export class SelfHostedAuthProvider {
             family.clientId !== payload.client_id ||
             payload.scope !== family.scope)
             throw new Error("Invalid token.");
-        return { subject, scopes: family.scope.split(/\s+/).filter(Boolean), roles: [] };
+        // Roles are read from the database on every request (no caching), so a
+        // grant or revocation applies to live tokens immediately. Scopes stay
+        // exactly what the user consented to; roles decide whether the
+        // privileged ones are honoured (resource-server.ts requireScope).
+        return {
+            subject,
+            scopes: family.scope.split(/\s+/).filter(Boolean),
+            roles: [],
+            wardbyRoles: family.user.roles ?? [],
+        };
     }
     async cleanup() {
         const now = new Date();

package/dist/providers/auth/types.d.ts

@@ -32,6 +32,12 @@ export interface VerifiedToken {
     scopes: string[];
     email?: string;
     roles?: string[];
+    /**
+     * wardby roles (not the IdP's raw `roles`), decided by the provider at
+     * verification time: self-hosted reads AuthUser.roles live; delegating
+     * maps the configured signed claim through AUTH_ROLE_MAP. Absent = none.
+     */
+    wardbyRoles?: string[];
 }
 export interface AuthTokens {
     idToken: string;

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

@@ -12,6 +12,9 @@ export declare class MemoryProxyLedger implements ProxyLedger {
     release(requestId: string, upstreamStatus: number): Promise<void>;
     markUncertain(requestId: string, upstreamStatus?: number): Promise<void>;
     cancelSession(sessionId: string): Promise<void>;
+    budgetExhausted(sessionId: string): Promise<boolean>;
+    recordUpstreamFailure(sessionId: string, code: string): Promise<void>;
+    upstreamFailure(sessionId: string): Promise<string | null>;
     getRequest(requestId: string): Promise<ProxyRequest | null>;
     private requiredRequest;
 }

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

@@ -1,5 +1,11 @@
 function cloneSession(session) {
-    return { ...session, allowedModels: [...session.allowedModels], deadlineAt: new Date(session.deadlineAt) };
+    return {
+        ...session,
+        allowedModels: [...session.allowedModels],
+        deadlineAt: new Date(session.deadlineAt),
+        budgetExhaustedAt: session.budgetExhaustedAt ? new Date(session.budgetExhaustedAt) : null,
+        upstreamFailure: session.upstreamFailure ?? null,
+    };
 }
 function cloneRequest(request) {
     return {
@@ -48,8 +54,10 @@ export class MemoryProxyLedger {
             if (request.status === "reserved" || request.status === "uncertain")
                 committedOrHeld += request.reservationUsd;
         }
-        if (committedOrHeld + input.reservationUsd >= session.budgetUsd)
+        if (committedOrHeld + input.reservationUsd >= session.budgetUsd) {
+            session.budgetExhaustedAt ??= new Date(input.now);
             return { outcome: "budget_exhausted" };
+        }
         const request = { ...input, pricing: { ...input.pricing }, status: "reserved" };
         this.requests.set(request.id, request);
         this.requestBySessionKey.set(lookupKey, request.id);
@@ -90,6 +98,17 @@ export class MemoryProxyLedger {
         if (session)
             session.status = "cancelled";
     }
+    async budgetExhausted(sessionId) {
+        return Boolean(this.sessions.get(sessionId)?.budgetExhaustedAt);
+    }
+    async recordUpstreamFailure(sessionId, code) {
+        const session = this.sessions.get(sessionId);
+        if (session)
+            session.upstreamFailure ??= code;
+    }
+    async upstreamFailure(sessionId) {
+        return this.sessions.get(sessionId)?.upstreamFailure ?? null;
+    }
     async getRequest(requestId) {
         const request = this.requests.get(requestId);
         return request ? cloneRequest(request) : null;

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

@@ -8,8 +8,12 @@ export declare function fingerprintRequest(body: string): string;
 export interface TerminalUsage {
     terminal: boolean;
     usage?: ProxyUsage;
+    /** Set when the upstream ended the response as failed or incomplete: its error code. */
+    failure?: string;
 }
 export declare function terminalUsageFromSseFrame(frame: string): TerminalUsage;
+/** The safe error code in an upstream error body (a stream event or a rejected response's JSON), if any. */
+export declare function safeUpstreamErrorCode(record: Record<string, unknown>): string | undefined;
 /** Accumulates Anthropic's split input/output usage until message_stop. */
 export declare class AnthropicSseUsageTracker {
     private startUsage?;

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

@@ -74,13 +74,36 @@ export function terminalUsageFromSseFrame(frame) {
     if (!event || typeof event !== "object")
         return { terminal: false };
     const record = event;
-    if (record.type !== "response.completed" && record.type !== "response.failed")
+    // A stream-level error event (quota, rate limit, server error) ends the response with no usage.
+    if (record.type === "error")
+        return { terminal: true, failure: upstreamErrorCode(record) };
+    const failed = record.type === "response.failed" || record.type === "response.incomplete";
+    if (record.type !== "response.completed" && !failed)
         return { terminal: false };
     const response = record.response;
     if (!response || typeof response !== "object")
         throw new Error("invalid_upstream_terminal_event");
     const usage = response.usage;
-    return { terminal: true, usage: usage == null ? undefined : parseAuthoritativeUsage(usage) };
+    return {
+        terminal: true,
+        usage: usage == null ? undefined : parseAuthoritativeUsage(usage),
+        ...(failed ? { failure: upstreamErrorCode(response) } : {}),
+    };
+}
+const SAFE_ERROR_CODE = /^[A-Za-z0-9_.-]{1,64}$/;
+/** The upstream's own error code, never its message: codes are fixed identifiers, messages can echo input. */
+function upstreamErrorCode(record) {
+    return safeUpstreamErrorCode(record) ?? "unknown";
+}
+/** The safe error code in an upstream error body (a stream event or a rejected response's JSON), if any. */
+export function safeUpstreamErrorCode(record) {
+    const nested = (key) => {
+        const value = record[key];
+        return value && typeof value === "object" ? value : undefined;
+    };
+    const candidates = [nested("error")?.code, nested("error")?.type, nested("incomplete_details")?.reason, record.code];
+    const code = candidates.find((value) => typeof value === "string" && SAFE_ERROR_CODE.test(value));
+    return typeof code === "string" ? code : undefined;
 }
 function sseEvent(frame) {
     const lines = frame.split("\n");
@@ -118,6 +141,9 @@ export class AnthropicSseUsageTracker {
         if (!value)
             return { terminal: false };
         switch (value.type) {
+            // A stream-level error event (quota, rate limit, server error) ends the response with no usage.
+            case "error":
+                return { terminal: true, failure: upstreamErrorCode(value) };
             case "message_start": {
                 if (this.startUsage || !value.message || typeof value.message !== "object") {
                     throw new Error("invalid_upstream_sse");

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

@@ -1,9 +1,23 @@
-import type { PrismaClient } from "@prisma/client";
+import type { PrismaClient } from "#prisma";
 import type { CreateProxySessionInput, ProxyLedger, ProxyRequest, ProxySession, ProxyUsage, ReserveProxyRequestInput, ReserveProxyRequestResult } from "./types.js";
 export type PrismaProxyLedgerDb = Pick<PrismaClient, "$transaction" | "$queryRaw" | "$executeRaw">;
+/** How long a ledger transaction waits for a pool connection (Prisma's
+ *  default is 2 s). A model request fails outright when this runs out, so it
+ *  gets more room than the default; its pool is also kept apart from the
+ *  package registry's (coding-proxy/main.ts). */
+export declare const LEDGER_TRANSACTION_MAX_WAIT_MS = 5000;
+/** How long a ledger transaction may run once started (Prisma's default is
+ *  5 s). Each is a handful of small queries, but a proxy busy with package
+ *  installs (the registry's dependency walk parses large npm documents on the
+ *  same event loop) can stall between them; a live lockfile install expired
+ *  one ("A commit cannot be executed on an expired transaction") and failed
+ *  the model request. The row lock it holds is per session, so a longer
+ *  window only delays that run's own next request. */
+export declare const LEDGER_TRANSACTION_TIMEOUT_MS = 20000;
 export declare class PrismaProxyLedger implements ProxyLedger {
     private readonly db;
     constructor(db: PrismaProxyLedgerDb);
+    private transaction;
     createSession(input: CreateProxySessionInput): Promise<void>;
     findSessionByCapabilityHash(capabilityHash: string): Promise<ProxySession | null>;
     reserve(input: ReserveProxyRequestInput): Promise<ReserveProxyRequestResult>;
@@ -11,5 +25,8 @@ export declare class PrismaProxyLedger implements ProxyLedger {
     release(requestId: string, upstreamStatus: number): Promise<void>;
     markUncertain(requestId: string, upstreamStatus?: number): Promise<void>;
     cancelSession(sessionId: string): Promise<void>;
+    budgetExhausted(sessionId: string): Promise<boolean>;
+    recordUpstreamFailure(sessionId: string, code: string): Promise<void>;
+    upstreamFailure(sessionId: string): Promise<string | null>;
     getRequest(requestId: string): Promise<ProxyRequest | null>;
 }

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

@@ -1,3 +1,16 @@
+/** How long a ledger transaction waits for a pool connection (Prisma's
+ *  default is 2 s). A model request fails outright when this runs out, so it
+ *  gets more room than the default; its pool is also kept apart from the
+ *  package registry's (coding-proxy/main.ts). */
+export const LEDGER_TRANSACTION_MAX_WAIT_MS = 5_000;
+/** How long a ledger transaction may run once started (Prisma's default is
+ *  5 s). Each is a handful of small queries, but a proxy busy with package
+ *  installs (the registry's dependency walk parses large npm documents on the
+ *  same event loop) can stall between them; a live lockfile install expired
+ *  one ("A commit cannot be executed on an expired transaction") and failed
+ *  the model request. The row lock it holds is per session, so a longer
+ *  window only delays that run's own next request. */
+export const LEDGER_TRANSACTION_TIMEOUT_MS = 20_000;
 function sessionFromRow(row) {
     if (!Array.isArray(row.allowedModels) || !row.allowedModels.every((model) => typeof model === "string")) {
         throw new Error("invalid_proxy_session_models");
@@ -15,6 +28,9 @@ function sessionFromRow(row) {
         deadlineAt: row.deadlineAt,
         budgetUsd: Number(row.budgetUsd),
         status: row.status,
+        registryTokenHash: row.registryTokenHash,
+        budgetExhaustedAt: row.budgetExhaustedAt ?? null,
+        upstreamFailure: row.upstreamFailure ?? null,
     };
 }
 function requestFromRow(row) {
@@ -57,26 +73,33 @@ export class PrismaProxyLedger {
     constructor(db) {
         this.db = db;
     }
+    transaction(fn) {
+        return this.db.$transaction(fn, {
+            maxWait: LEDGER_TRANSACTION_MAX_WAIT_MS,
+            timeout: LEDGER_TRANSACTION_TIMEOUT_MS,
+        });
+    }
     async createSession(input) {
         const models = JSON.stringify(input.allowedModels);
         await this.db.$executeRaw `
       INSERT INTO "CodingProxySession"
         ("id", "runId", "capabilityHash", "credentialRef", "protocol", "allowedModels", "deadlineAt",
-         "budgetUsd", "status", "createdAt", "updatedAt")
+         "budgetUsd", "status", "registryTokenHash", "createdAt", "updatedAt")
       VALUES
         (${input.id}, ${input.runId}, ${input.capabilityHash}, ${input.credentialRef}, ${input.protocol}, ${models}::jsonb,
-         ${input.deadlineAt}, ${input.budgetUsd}, 'active', CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)
+         ${input.deadlineAt}, ${input.budgetUsd}, 'active', ${input.registryTokenHash}, CURRENT_TIMESTAMP, CURRENT_TIMESTAMP)
     `;
     }
     async findSessionByCapabilityHash(capabilityHash) {
         const rows = await this.db.$queryRaw `
-      SELECT "id", "runId", "capabilityHash", "credentialRef", "protocol", "allowedModels", "deadlineAt", "budgetUsd", "status"
+      SELECT "id", "runId", "capabilityHash", "credentialRef", "protocol", "allowedModels", "deadlineAt", "budgetUsd", "status", "registryTokenHash",
+             "budgetExhaustedAt", "upstreamFailure"
       FROM "CodingProxySession" WHERE "capabilityHash" = ${capabilityHash}
     `;
         return rows[0] ? sessionFromRow(rows[0]) : null;
     }
     async reserve(input) {
-        return this.db.$transaction(async (tx) => {
+        return this.transaction(async (tx) => {
             const sessions = await tx.$queryRaw `
           SELECT "id", "runId", "capabilityHash", "credentialRef", "protocol", "allowedModels", "deadlineAt", "budgetUsd", "status"
           FROM "CodingProxySession" WHERE "id" = ${input.sessionId} FOR UPDATE
@@ -107,6 +130,10 @@ export class PrismaProxyLedger {
           FROM "CodingProxyRequest" WHERE "sessionId" = ${input.sessionId}
         `;
             if (Number(totals[0]?.held ?? 0) + input.reservationUsd >= Number(row.budgetUsd)) {
+                await tx.$executeRaw `
+            UPDATE "CodingProxySession" SET "budgetExhaustedAt" = COALESCE("budgetExhaustedAt", ${input.now})
+            WHERE "id" = ${input.sessionId}
+          `;
                 return { outcome: "budget_exhausted" };
             }
             const pricing = JSON.stringify({
@@ -132,7 +159,7 @@ export class PrismaProxyLedger {
         });
     }
     async complete(requestId, usage, actualCostUsd, upstreamStatus) {
-        return this.db.$transaction(async (tx) => {
+        return this.transaction(async (tx) => {
             const initial = await requestById(tx, requestId);
             if (!initial)
                 throw new Error("unknown_proxy_request");
@@ -207,6 +234,24 @@ export class PrismaProxyLedger {
       WHERE "id" = ${sessionId} AND "status" = 'active'
     `;
     }
+    async budgetExhausted(sessionId) {
+        const rows = await this.db.$queryRaw `
+      SELECT "id" FROM "CodingProxySession" WHERE "id" = ${sessionId} AND "budgetExhaustedAt" IS NOT NULL
+    `;
+        return rows.length > 0;
+    }
+    async recordUpstreamFailure(sessionId, code) {
+        await this.db.$executeRaw `
+      UPDATE "CodingProxySession" SET "upstreamFailure" = ${code}, "updatedAt" = CURRENT_TIMESTAMP
+      WHERE "id" = ${sessionId} AND "upstreamFailure" IS NULL
+    `;
+    }
+    async upstreamFailure(sessionId) {
+        const rows = await this.db.$queryRaw `
+      SELECT "upstreamFailure" FROM "CodingProxySession" WHERE "id" = ${sessionId}
+    `;
+        return rows[0]?.upstreamFailure ?? null;
+    }
     getRequest(requestId) {
         return requestById(this.db, requestId);
     }

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

@@ -4,6 +4,12 @@ export declare const PROXY_MAX_BODY_BYTES: number;
 export declare const PROXY_MAX_OUTPUT_TOKENS = 1000000;
 export declare const PROXY_DEFAULT_MAX_OUTPUT_TOKENS = 4096;
 export declare const CLAUDE_CODE_ANTHROPIC_BETAS: readonly ["claude-code-20250219", "context-management-2025-06-27", "effort-2025-11-24", "interleaved-thinking-2025-05-14", "mid-conversation-system-2026-04-07", "prompt-caching-scope-2026-01-05", "thinking-token-count-2026-05-13"];
+/**
+ * The longest run_command timeout the Claude tool runner offers the model (its MAX_TIMEOUT_MS,
+ * src/claude-tool-runner/command.mjs; the proxy tests keep the two equal). A lower limit here let the
+ * command run, then refused the next request, which replays that tool call, as unsupported.
+ */
+export declare const MAX_COMMAND_TIMEOUT_MS = 120000;
 export declare class CodingProxyError extends Error {
     readonly status: number;
     readonly code: string;
@@ -51,6 +57,7 @@ export interface CodingProxyOptions {
     pricing?: (model: string, protocol: ProxyProtocol) => ModelPricing;
     pricingVersion?: string;
 }
+export declare function capabilityHash(capability: string): string;
 export declare class CodingProxy {
     private readonly ledger;
     private readonly credentials;
@@ -64,6 +71,10 @@ export declare class CodingProxy {
     constructor(options: CodingProxyOptions);
     createSession(input: CreateCodingProxySession): Promise<CreatedCodingProxySession>;
     cancelSession(sessionId: string): Promise<void>;
+    /** Whether this session's run was refused a model request for budget. */
+    budgetExhausted(sessionId: string): Promise<boolean>;
+    /** The code of the first upstream failure relayed for this session's run, if any. */
+    upstreamFailure(sessionId: string): Promise<string | null>;
     execute(input: ExecuteProxyRequest, sink: ProxyResponseSink): Promise<void>;
     private authenticate;
     private trackActive;
@@ -71,5 +82,7 @@ export declare class CodingProxy {
     private complete;
     private forwardJson;
     private forwardStream;
+    /** Best effort: the executor reads it to name the failure; it must never break the relay. */
+    private recordUpstreamFailure;
     private markUncertain;
 }