cartethyia 2.7.4 → 2.7.5

package/src/transport/routing/router.ts

@@ -12,6 +12,7 @@ import {
   type ProviderRoutingSetting,
   type Reservation,
   type RouteCandidate,
+  type RoutedCandidate,
   type RoutePlan,
   type EligibilityDecision,
   type RouteContinuationAffinity,
@@ -34,22 +35,100 @@ import {
 } from "./candidate-index";
 import { totalRemainingCredit, totalRemainingPercent, type ProviderQuotaWindow } from "../../providers/quota/quota-contracts";
 import { getCachedQuotaEntry, quotaLens } from "../../providers/quota/cache";
+import { readQuotaSnapshot } from "../../providers/quota/snapshot";
+import type { CartethyiaDatabase } from "../../persistence/db-handle";
 import type { RedisClient } from "../../persistence/redis";
 import { sharedClaudeSlowLanes } from "../../providers/integrations/claude/claude-slow-lane";
 
+/**
+ * Filters quota windows to those relevant to the candidate model.
+ * Providers like Antigravity report separate quotas for distinct model families
+ * (Gemini vs Claude/GPT), and Grok reports per-product buckets.
+ * Evaluating a Claude exhaustion against a Gemini request would incorrectly
+ * mark the account exhausted for Gemini when Gemini capacity is still available.
+ */
+export function filterCandidateQuotaWindows(
+  windows: readonly ProviderQuotaWindow[],
+  candidate: { readonly provider_id?: string; readonly model_id?: string },
+): readonly ProviderQuotaWindow[] {
+  if (windows.length === 0) return windows;
+  const providerId = candidate.provider_id?.toLowerCase() ?? "";
+  const modelId = candidate.model_id?.toLowerCase() ?? "";
+  windows = windows.filter((window) => window.modelIds === undefined || window.modelIds.includes(modelId));
+
+  if (providerId === "antigravity") {
+    const isGemini = /gemini|tab_flash/i.test(modelId);
+    const isClaude = /claude|opus|sonnet/i.test(modelId);
+    if (isGemini) {
+      return windows.filter((w) => {
+        const text = `${w.kind} ${w.label}`.toLowerCase();
+        if (text.includes("gemini") || text.includes("google")) return true;
+        return !text.includes("claude") && !text.includes("gpt");
+      });
+    }
+    if (isClaude) {
+      return windows.filter((w) => {
+        const text = `${w.kind} ${w.label}`.toLowerCase();
+        if (text.includes("claude") || text.includes("gpt")) return true;
+        return !text.includes("gemini") && !text.includes("google");
+      });
+    }
+  }
+
+  if (providerId === "grok") {
+    return windows.filter((w) => {
+      if (w.kind.startsWith("product:")) {
+        const product = w.kind.split(":")[1]?.toLowerCase();
+        return product ? modelId.includes(product) : true;
+      }
+      return true;
+    });
+  }
+
+  return windows;
+}
+
 /**
  * True when the account's remaining allowance is at or below its provider's
  * floor. Credit mode sums the absolute remaining credit; percent mode uses the
  * aggregate credit percentage and the lowest independent percentage window.
  * No reading means unknown, which is not below the floor.
  */
-function belowUsageFloor(state: {
-  readonly usage_floor?: number;
-  readonly usage_floor_unit?: "credit" | "percent";
-  readonly quota_windows?: readonly unknown[] | undefined;
-}): boolean {
-  const windows = state.quota_windows as readonly ProviderQuotaWindow[] | undefined;
-  if (windows === undefined || windows.length === 0) return false;
+function belowUsageFloor(state: RoutedCandidate): boolean {
+  const rawWindows = state.quota_windows;
+  // A successful Start Plan balance (`quota_entitlements_known`) authoritatively
+  // lists its model grants: when the provider is zcode-start and no window
+  // matches the requested model, the account is below the floor even with an
+  // empty/absent window list — there is no grant to fund the model.
+  if (state.provider_id === "zcode-start" && state.quota_entitlements_known === true) {
+    if (rawWindows === undefined || rawWindows.length === 0) return true;
+    const knownGrants = rawWindows.some((window) => window.modelIds !== undefined);
+    if (!knownGrants) return true;
+  }
+  if (rawWindows === undefined || rawWindows.length === 0) return false;
+  const relevant = filterCandidateQuotaWindows(rawWindows, state);
+  // Model-scoped grants (Start Plan) are checked separately: a grant that has
+  // not started, has expired, or is exhausted cannot fund the requested model,
+  // so it must not count as credit.
+  const now = Date.now();
+  const grants = relevant.filter((window) => window.modelIds !== undefined);
+  if (state.provider_id === "zcode-start" && grants.length === 0 && rawWindows.some((window) => window.modelIds !== undefined)) {
+    return true;
+  }
+  if (
+    grants.length > 0 &&
+    !grants.some((window) => {
+      if (window.startsAt && Date.parse(window.startsAt) > now) return false;
+      if (window.resetsAt && Date.parse(window.resetsAt) <= now) return false;
+      if (typeof window.remaining === "number" && window.remaining <= 0) return false;
+      if (typeof window.remainingPercent === "number" && window.remainingPercent <= 0) return false;
+      const remaining = state.usage_floor_unit === "credit" ? window.remaining : window.remainingPercent;
+      return state.usage_floor === undefined || remaining == null || remaining > state.usage_floor;
+    })
+  ) {
+    return true;
+  }
+  const windows = relevant.filter((window) => window.modelIds === undefined);
   const credit = totalRemainingCredit(windows);
   const percent = totalRemainingPercent(windows);
   const exhaustedIndependentWindow = windows.some(
@@ -67,6 +146,21 @@ function belowUsageFloor(state: {
   return remaining !== null && remaining <= floor;
 }
 
+/**
+ * Routing priority for an account's remaining allowance when two candidates sit
+ * in the same rank group: positive remaining credit first, then unknown, then
+ * known-zero last. Free-tier models skip the preference entirely — a free model
+ * routes to any account, as the provider's own directory stated it is free.
+ */
+function creditPriority(candidate: RoutedCandidate): number {
+  if (candidate.free_tier === true) return 0;
+  const windows = candidate.quota_windows;
+  if (windows === undefined || windows.length === 0) return 0;
+  const credit = totalRemainingCredit(windows);
+  if (credit === null) return 0;
+  return credit > 0 ? 1 : -1;
+}
+
 /**
  * Normalizes a requested model name before alias lookup. Coding-agent CLIs
  * version their model ids with variant suffixes (`claude-opus-5[1m]`,
@@ -233,10 +327,17 @@ function spreadDeadline(cooldownUntil: number | undefined): { cooldown_until?: n
 function earliestWindowResetMs(
   windows: readonly ProviderQuotaWindow[] | undefined,
   nowMs: number,
+  candidate: RouteCandidate,
 ): number | undefined {
   if (windows === undefined) return undefined;
+  windows = filterCandidateQuotaWindows(windows, candidate);
   let earliest: number | undefined;
   for (const window of windows) {
+    if (window.startsAt && Date.parse(window.startsAt) > nowMs) {
+      const at = Date.parse(window.startsAt);
+      if (earliest === undefined || at < earliest) earliest = at;
+      continue;
+    }
     if (typeof window.resetsAt !== "string" || window.resetsAt.length === 0) continue;
     const at = Date.parse(window.resetsAt);
     if (!Number.isFinite(at) || at <= nowMs) continue;
@@ -249,7 +350,7 @@ function earliestWindowResetMs(
  * The earliest instant any cooling candidate recovers, in epoch ms.
  *
  * `undefined` when no decision carries a deadline — which is the honest answer
- * for a set whose exclusions have no reset (`disabled`, `locked`), and keeps
+ * for a set whose exclusions have no reset (`disabled`), and keeps
  * `accountsRateLimitedError` from reporting a number nobody measured. The
  * minimum, not the maximum: the client can be served as soon as the *first*
  * account comes back, so quoting the slowest would hold it off longer than it
@@ -268,36 +369,22 @@ function earliestResetMs(
 }
 
 export class EligibilityEvaluator {
-  evaluate(candidate: RouteCandidate): EligibilityDecision {
-    const state = candidate as RouteCandidate & {
-      readonly health_status?: string;
-      readonly cooldown_kind?: "hard" | "soft";
-      readonly cooldown_until?: number;
-      readonly account_locked?: boolean;
-      readonly locked?: boolean;
-      readonly usage_floor?: number;
-      readonly usage_floor_unit?: "credit" | "percent";
-      readonly quota_windows?: readonly ProviderQuotaWindow[] | undefined;
-      /** Slow-lane stamp applied at plan time; see `applySlowLane`. */
-      readonly lane?: "slow";
-    };
-    if (state.account_locked || state.locked)
-      return { eligible: false, reason: "locked", candidate };
-    if (state.health_status === "disabled")
+  evaluate(candidate: RoutedCandidate): EligibilityDecision {
+    if (candidate.health_status === "disabled")
       return { eligible: false, reason: "disabled", candidate };
-    if (state.health_status === "model_cooldown")
-      return { eligible: false, reason: "model_cooldown", candidate, ...spreadDeadline(state.cooldown_until) };
-    if (state.health_status === "cooldown" && state.cooldown_kind === "hard")
-      return { eligible: false, reason: "cooldown_hard", candidate, ...spreadDeadline(state.cooldown_until) };
+    if (candidate.health_status === "model_cooldown")
+      return { eligible: false, reason: "model_cooldown", candidate, ...spreadDeadline(candidate.cooldown_until) };
+    if (candidate.health_status === "cooldown" && candidate.cooldown_kind === "hard")
+      return { eligible: false, reason: "cooldown_hard", candidate, ...spreadDeadline(candidate.cooldown_until) };
     // The floor is checked here, not after selection: an account below its
     // floor must not win the route. An account with no reading is left
     // eligible — a missing quota fetch is not proof the allowance is gone.
-    if (belowUsageFloor(state))
+    if (belowUsageFloor(candidate))
       return {
         eligible: false,
         reason: "quota_exhausted",
         candidate,
-        ...spreadDeadline(earliestWindowResetMs(state.quota_windows, Date.now())),
+        ...spreadDeadline(earliestWindowResetMs(candidate.quota_windows, Date.now(), candidate)),
       };
     // A slow lane is orthogonal to cooldown, never a member of it: the account
     // still serves on spare capacity when the request carries the slow usage
@@ -308,10 +395,10 @@ export class EligibilityEvaluator {
     // exclusion, not that it overrides one. An account with no usable allowance
     // is not rescued by the lane — the lane is a latency budget against spare
     // capacity, and an account below its floor has none.
-    if (state.lane === "slow")
+    if (candidate.lane === "slow")
       return { eligible: true, reason: "slow", candidate };
-    if (state.health_status === "cooldown")
-      return { eligible: true, reason: "cooldown", candidate, ...spreadDeadline(state.cooldown_until) };
+    if (candidate.health_status === "cooldown")
+      return { eligible: true, reason: "cooldown", candidate, ...spreadDeadline(candidate.cooldown_until) };
     return { eligible: true, reason: "healthy", candidate };
   }
 
@@ -332,6 +419,7 @@ export class RoutingEngine {
   constructor(
     private readonly admission: AdmissionController = new InMemoryAdmissionController(),
     private readonly redis?: RedisClient,
+    private readonly db?: CartethyiaDatabase,
   ) {}
 
   private getRoundRobin(key: string): RoundRobinState {
@@ -467,13 +555,32 @@ export class RoutingEngine {
       accountId,
       this.redis,
     ).catch(() => undefined);
-    const quotaWindows = cached?.quota.windows ?? [];
+    // The live cache is authoritative when warm; when it is cold (e.g. right
+    // after a restart, before the sweep re-reads accounts), fall back to the
+    // persisted quota snapshot — the durable source of truth — so routing
+    // still prefers accounts that actually have remaining credit. The snapshot
+    // is never fresher than the cache, but a stale balance beats an unknown
+    // one for ordering, and the sweep refreshes it on schedule.
+    let quota = cached?.quota;
+    if (quota === undefined && this.db !== undefined) {
+      const stored = await readQuotaSnapshot(this.db, accountId).catch(() => null);
+      quota = stored?.quota;
+    }
+    const rawWindows = quota?.windows;
+    // The cache is authoritative when it has a reading; when it does not,
+    // keep whatever the candidate already carried (the credit ordering reads
+    // these windows, and a miss must not erase a stamped value).
+    const quotaWindows =
+      rawWindows === undefined
+        ? undefined
+        : candidate.provider_id === "zcode-start" ? rawWindows : filterCandidateQuotaWindows(rawWindows, candidate);
     return {
       ...candidate,
       ...(setting?.usageFloor == null
         ? {}
         : { usage_floor: setting.usageFloor, usage_floor_unit: setting.usageFloorUnit }),
-      quota_windows: quotaWindows,
+      ...(quotaWindows === undefined ? {} : { quota_windows: quotaWindows }),
+      ...(quota?.source === "zcode-start" && quota.error === null ? { quota_entitlements_known: true } : {}),
     };
   }
 
@@ -641,6 +748,11 @@ export class RoutingEngine {
     const pinnedDecisions = pinned.map((candidate) => this.eligibility.evaluate(candidate));
     const blocked = pinnedDecisions.find((decision) => !decision.eligible);
     if (blocked !== undefined) {
+      // A rebaseable continuation (complete conversation replay) is not owed
+      // to this account: the recorded exchange may travel as history to a
+      // fresh Run on an eligible account. Cooling/blocked pinned account must
+      // not turn that into a hard refusal — fall through to normal routing.
+      if (affinity.rebaseable) return null;
       const reason = blocked.reason;
       if (
         reason === "cooldown_hard" ||
@@ -810,11 +922,14 @@ export class RoutingEngine {
       );
     }
 
-    // Single sort by rank (fresh → slow → cooling → saturated), stable.
+    // Single sort by rank (fresh → slow → cooling → saturated), stable. Within
+    // the same rank, accounts with remaining credit come first unless the model
+    // is free tier, which routes to any account.
     eligible = [...eligible].sort((left, right) => {
       const leftRank = decisions.get(admissionKey(left))?.rank ?? ROUTING_RANK.FRESH;
       const rightRank = decisions.get(admissionKey(right))?.rank ?? ROUTING_RANK.FRESH;
-      return leftRank - rightRank;
+      if (leftRank !== rightRank) return leftRank - rightRank;
+      return creditPriority(right) - creditPriority(left);
     });
 
     // Provider routing rotates accounts within the same rank group only; it can

package/src/transport/shutdown-notice.ts

@@ -15,7 +15,7 @@
  */
 import { GatewayError, type GatewayErrorCode } from "../protocol/gateway-error";
 
-export interface ShutdownNotice {
+interface ShutdownNotice {
   readonly code: Extract<GatewayErrorCode, "shutting_down">;
   readonly message: string;
   readonly reason?: string;
@@ -27,7 +27,7 @@ export interface ShutdownNotice {
  * with it before swapping the image so its callers are told the process is
  * coming straight back.
  */
-export const UPDATE_SHUTDOWN_REASON = "update";
+const UPDATE_SHUTDOWN_REASON = "update";
 
 export function shutdownNotice(reason: string | undefined): ShutdownNotice {
   if (reason === UPDATE_SHUTDOWN_REASON) {

package/src/transport/surface/adapters.ts

@@ -26,7 +26,7 @@ export function eventText(event: CanonicalEvent): string | undefined {
 // The endpoint path is authoritative: user-agent sniffing and prompt-text
 // marker scanning never override it, so routing cannot depend on client
 // identity strings or prompt content.
-export type WinningSource =
+type WinningSource =
   "explicit_marker" | "body_shape" | "endpoint_path";
 
 export interface SurfaceInput {
@@ -35,7 +35,7 @@ export interface SurfaceInput {
   path: string;
 }
 
-export interface SurfaceDetection {
+interface SurfaceDetection {
   surface: SourceSurface;
   winning_source: WinningSource;
   /**
@@ -64,7 +64,7 @@ export interface SurfaceAdapter {
  * it explicitly. Both detection lookups read this table, so adding a surface
  * is one row here plus its adapter.
  */
-export interface SurfaceDescriptor {
+interface SurfaceDescriptor {
   readonly surface: SourceSurface;
   readonly pathPrefix: string;
 }

package/src/transport/surface/chat/encode.ts

@@ -37,8 +37,8 @@ import type { ChatEncodeOptions, ChunkBase, JsonObject } from "./parse";
  */
 export function repairToolArguments(raw: string): string {
   if (raw.length === 0) return "{}";
-  const repaired = repairToolArgumentText(raw);
   try {
+    const repaired = repairToolArgumentText(raw);
     const parsed: unknown = JSON.parse(repaired);
     if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return raw;
     return repaired;
@@ -52,7 +52,7 @@ function repairToolArgumentText(json: string): string {
   return jsonrepair(json);
 }
 
-export function bytesToString(value: string | Uint8Array): string {
+function bytesToString(value: string | Uint8Array): string {
   return typeof value === "string" ? value : new TextDecoder().decode(value);
 }
 
@@ -84,7 +84,7 @@ export function getModel(options: ChatEncodeOptions, events: CanonicalEvent[]):
  * placeholder — passing the provider's own bytes through is the whole point of
  * the extension — but never an explicit configuration.
  */
-export function resolveObfuscation(options: ChatEncodeOptions): {
+function resolveObfuscation(options: ChatEncodeOptions): {
   value: string | undefined;
   pinned: boolean;
 } {
@@ -96,7 +96,7 @@ export function resolveObfuscation(options: ChatEncodeOptions): {
   return { value: undefined, pinned: false };
 }
 
-export function eventObfuscation(event: CanonicalEvent): string | undefined {
+function eventObfuscation(event: CanonicalEvent): string | undefined {
   if (event.type !== "content_delta" || event.content.kind !== "extension") return undefined;
   if (!event.content.name.includes("obfuscat")) return undefined;
   const payload = event.content.payload;
@@ -106,13 +106,13 @@ export function eventObfuscation(event: CanonicalEvent): string | undefined {
 }
 
 /** Audio output payload carried as an `audio` extension content part. */
-export function eventAudio(event: CanonicalEvent): Record<string, unknown> | undefined {
+function eventAudio(event: CanonicalEvent): Record<string, unknown> | undefined {
   if (event.type !== "content_delta" || event.content.kind !== "extension") return undefined;
   if (event.content.name !== "audio") return undefined;
   return isRecord(event.content.payload) ? event.content.payload : undefined;
 }
 
-export function eventReasoningText(event: CanonicalEvent): string | undefined {
+function eventReasoningText(event: CanonicalEvent): string | undefined {
   if (event.type !== "content_delta" || event.content.kind !== "reasoning") return undefined;
   return reasoningTextOf(event.content);
 }
@@ -144,7 +144,7 @@ function mergedReasoningText(events: readonly CanonicalEvent[]): string {
 export function finishReason(stopReason: CanonicalStopReason | undefined): string {
   return chatFinishReason(stopReason);
 }
-export function eventToolCall(
+function eventToolCall(
   event: CanonicalEvent,
 ): { state: ToolCallState; hasArguments: boolean } | undefined {
   if (event.type === "tool_call_delta") {

package/src/transport/surface/chat/parse.ts

@@ -32,7 +32,7 @@ export interface JsonObject {
   [key: string]: unknown;
 }
 
-export interface ParsedToolCall {
+interface ParsedToolCall {
   id: string;
   name: string;
   arguments: string;
@@ -57,7 +57,7 @@ export interface ChunkBase {
 
 
 
-export function isSurfaceInput(value: unknown): value is SurfaceInput {
+function isSurfaceInput(value: unknown): value is SurfaceInput {
   return isRecord(value) && "body" in value && "path" in value && typeof value.path === "string";
 }
 
@@ -75,7 +75,7 @@ export function requestBody(input: unknown): unknown {
   return decodeBody(isSurfaceInput(input) ? input.body : input);
 }
 
-export function nonNegativeNumber(value: unknown): number | undefined {
+function nonNegativeNumber(value: unknown): number | undefined {
   const number = asNumber(value);
   return number !== undefined && number >= 0 ? number : undefined;
 }
@@ -87,13 +87,13 @@ const AUDIO_FORMAT_MEDIA_TYPE: Readonly<Record<string, string>> = {
   mpeg: "audio/mpeg",
 };
 
-export function audioFormatToMediaType(format: string | undefined): string {
+function audioFormatToMediaType(format: string | undefined): string {
   if (format === undefined || format.length === 0) return "audio/mpeg";
   if (format.includes("/")) return format;
   return AUDIO_FORMAT_MEDIA_TYPE[format.toLowerCase()] ?? "audio/mpeg";
 }
 
-export function parseContentPart(value: unknown): ContentPart {
+function parseContentPart(value: unknown): ContentPart {
   if (typeof value === "string") return textPart(value);
   if (!isRecord(value)) {
     throw new Error("Malformed content part: expected string or object");
@@ -173,7 +173,7 @@ export function parseContentPart(value: unknown): ContentPart {
   throw new Error(`Malformed content part: unsupported type "${type ?? "unknown"}"`);
 }
 
-export function parseContent(value: unknown): ContentPart[] {
+function parseContent(value: unknown): ContentPart[] {
   if (typeof value === "string") return [textPart(value)];
   if (!Array.isArray(value)) return [];
   return value.map((part) => parseContentPart(part));
@@ -271,7 +271,7 @@ export function parseMessage(value: unknown): CanonicalMessage {
 }
 
 
-export function addExtension(
+function addExtension(
   controls: GenerationControls,
   key: `extension:${string}`,
   value: unknown,

package/src/transport/surface/completion.ts

@@ -9,7 +9,7 @@ import { usageToChatWire, type OpenAiUsage } from "../../providers/provider-usag
 import { TEXT_ENCODER } from "../../protocol/sse-frame";
 import { SurfaceStreamEncoder } from "./stream-frame";
 
-export interface CompletionEncodingOptions {
+interface CompletionEncodingOptions {
   response_id?: string;
   model?: string;
   created?: number;
@@ -150,7 +150,7 @@ export class CompletionStreamEncoder extends SurfaceStreamEncoder<CanonicalEvent
   }
 }
 
-export class CompletionAdapter implements SurfaceAdapter {
+class CompletionAdapter implements SurfaceAdapter {
   readonly surface = "completion" as const;
 
   matchesBodyShape(body: unknown): boolean {

package/src/transport/surface/content-parts.ts

@@ -12,7 +12,7 @@ export function textPart(text: string): ContentPart {
  * `document.source`). Each parser reads its own shape and hands the extracted
  * values here so the data-URI split happens once.
  */
-export interface RawFileBlock {
+interface RawFileBlock {
   /** Inline payload — may be raw base64 or a whole `data:` URI. */
   readonly data?: unknown;
   readonly media_type?: string | undefined;

package/src/transport/surface/dialects.ts

@@ -6,7 +6,7 @@ import { completeRequiredSchema } from "../../protocol/codecs";
 import type { ToolDefinition } from "../../protocol/canonical-model";
 
 /** Tool-definition dialects preserve each surface's distinct wire fields. */
-export type ToolDialect = "chat" | "responses" | "messages";
+type ToolDialect = "chat" | "responses" | "messages";
 
 /**
  * Parses a tool definition from one wire dialect.
@@ -165,7 +165,7 @@ function classifyNativeToolType(type: string): Exclude<ToolDefinition["tool_type
 
 export const CANONICAL_REASONING_EFFORTS: ReadonlySet<string> = new Set(REASONING_EFFORTS);
 
-export function isReasoningEffort(value: unknown): value is NonNullable<ReasoningIntent["effort"]> {
+function isReasoningEffort(value: unknown): value is NonNullable<ReasoningIntent["effort"]> {
   return typeof value === "string" && CANONICAL_REASONING_EFFORTS.has(value as NonNullable<ReasoningIntent["effort"]>);
 }
 

package/src/transport/surface/messages/parse.ts

@@ -53,7 +53,7 @@ export interface MessagesStreamEvent extends MessagesWireObject {
     | "message_stop";
 }
 
-export function contentArray(value: unknown, label: string): unknown[] {
+function contentArray(value: unknown, label: string): unknown[] {
   if (stringValue(value)) return [value];
   if (!Array.isArray(value)) throw new Error(`Messages ${label} must be a string or block array`);
   return value;
@@ -165,7 +165,7 @@ export function parseBlock(value: unknown): ContentPart {
   };
 }
 
-export function parseBlocks(value: unknown, label: string): ContentPart[] {
+function parseBlocks(value: unknown, label: string): ContentPart[] {
   return contentArray(value, label).map(parseBlock);
 }
 
@@ -207,7 +207,7 @@ export function parseTools(value: unknown): ToolDefinition[] | undefined {
 
 
 /** Reads `thinking.block_binding.prefix_mismatch_behavior` when present. */
-export function prefixMismatchBehavior(value: unknown): "drop_block" | "error" | undefined {
+function prefixMismatchBehavior(value: unknown): "drop_block" | "error" | undefined {
   if (!isRecord(value)) return undefined;
   const behavior = value["prefix_mismatch_behavior"];
   if (behavior === "drop_block" || behavior === "error") return behavior;

package/src/transport/surface/responses/adapter.ts

@@ -7,7 +7,7 @@ import { hasOwn, parseResponsesRequest, unwrapBody } from "./parse";
 import { encodeResponsesEvents, encodeResponsesWireEvents } from "./encode";
 
 /** The OpenAI Responses public surface adapter. */
-export class ResponsesAdapter implements SurfaceAdapter {
+class ResponsesAdapter implements SurfaceAdapter {
   readonly surface = "responses" as const;
 
   /** Check only top-level Responses shape markers, never arbitrary prompt text. */

package/src/transport/surface/responses/errors.ts

@@ -1,15 +1,6 @@
 import { GatewayError } from "../../../protocol/gateway-error";
 
 /** Typed failures for the OpenAI Responses surface. */
-export class ResponsesReasoningError extends GatewayError {
-  readonly field: "include" | "store" | "reasoning.encrypted_content";
-
-  constructor(field: "include" | "store" | "reasoning.encrypted_content", message: string) {
-    super("capability_unsupported", 400, message, { field });
-    this.name = "ResponsesReasoningError";
-    this.field = field;
-  }
-}
 
 /** Stable typed failure for malformed canonical sequence numbers. */
 export class ResponsesSequenceError extends GatewayError {

package/src/transport/vision-handoff-cache.ts

@@ -0,0 +1,58 @@
+/**
+ * In-process cache of vision-handoff descriptions.
+ *
+ * The key is a deterministic hash of the *set* of image payloads the handoff
+ * actually described (the last image-carrying user turn). Re-sending the same
+ * attachment — the same image in a later turn, or the same conversation
+ * replayed — skips a second vision call entirely. Bounded and TTL'd so it can
+ * never grow without limit.
+ *
+ * The cache is keyed by the active image set rather than a single image
+ * because one vision model call describes the whole set in a single block of
+ * text; you cannot reliably split that block back into per-image descriptions.
+ * A repeated single-image request still hits, as does any repeated set.
+ */
+import { createHash } from "node:crypto";
+
+const CACHE_MAX_ENTRIES = 512;
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+
+interface CacheEntry {
+  readonly description: string;
+  readonly at: number;
+}
+
+const store = new Map<string, CacheEntry>();
+
+/** Deterministic hash of one canonical image part's payload. */
+export function hashImagePart(part: { kind: "image"; payload: unknown }): string {
+  const payload =
+    typeof part.payload === "string" ? part.payload : JSON.stringify(part.payload);
+  return createHash("sha256").update(`image:${payload}`).digest("hex");
+}
+
+/** Look up a previously stored description for an active image set hash. */
+export function getCachedVisionDescription(hash: string): string | undefined {
+  const entry = store.get(hash);
+  if (entry === undefined) return undefined;
+  if (Date.now() - entry.at > CACHE_TTL_MS) {
+    store.delete(hash);
+    return undefined;
+  }
+  return entry.description;
+}
+
+/** Clear the vision-handoff description cache (test isolation). */
+export function clearCachedVisionDescriptions(): void {
+  store.clear();
+}
+
+/** Store the description produced for an active image set hash. */
+export function setCachedVisionDescription(hash: string, description: string): void {
+  store.set(hash, { description, at: Date.now() });
+  // Evict the oldest (first-inserted) entry when over the cap.
+  if (store.size > CACHE_MAX_ENTRIES) {
+    const oldestKey = store.keys().next().value as string | undefined;
+    if (oldestKey !== undefined) store.delete(oldestKey);
+  }
+}