@bitkyc08/opencodex 2.8.0 → 2.9.0

package/src/usage/log.ts

@@ -44,6 +44,12 @@ export interface PersistedUsageEntry {
   provider: string;
   model: string;
   surface?: "claude" | "claude-desktop" | "grok";
+  /** Matched configured key id; absent for environment/loopback admissions and
+   *  for every row written before attribution existed. */
+  apiKeyId?: string;
+  admissionKind?: "configured" | "environment" | "loopback";
+  /** The inbound wire, not the client product — see `surface`. */
+  inboundProtocol?: "responses" | "chat" | "messages";
   /** Best-effort chat/session correlation for Logs grouping (#330). */
   conversationId?: string;
   resolvedModel?: string;
@@ -94,6 +100,24 @@ export function isKnownUsageSurface(value: unknown): value is NonNullable<Persis
   return typeof value === "string" && KNOWN_USAGE_SURFACES.has(value as NonNullable<PersistedUsageEntry["surface"]>);
 }
 
+const KNOWN_ADMISSION_KINDS = new Set<NonNullable<PersistedUsageEntry["admissionKind"]>>([
+  "configured", "environment", "loopback",
+]);
+
+const KNOWN_INBOUND_PROTOCOLS = new Set<NonNullable<PersistedUsageEntry["inboundProtocol"]>>([
+  "responses", "chat", "messages",
+]);
+
+/** Same closed-set discipline as `isKnownUsageSurface`: an old or corrupted row
+ *  carrying an unexpected value drops the field instead of poisoning the enum. */
+export function isKnownAdmissionKind(value: unknown): value is NonNullable<PersistedUsageEntry["admissionKind"]> {
+  return typeof value === "string" && KNOWN_ADMISSION_KINDS.has(value as NonNullable<PersistedUsageEntry["admissionKind"]>);
+}
+
+export function isKnownInboundProtocol(value: unknown): value is NonNullable<PersistedUsageEntry["inboundProtocol"]> {
+  return typeof value === "string" && KNOWN_INBOUND_PROTOCOLS.has(value as NonNullable<PersistedUsageEntry["inboundProtocol"]>);
+}
+
 export function usageLogPath(): string {
   return join(getConfigDir(), "usage.jsonl");
 }
@@ -263,6 +287,11 @@ function capMetadataString(s: string): string {
   return s.length > MAX_METADATA_STRING_LEN ? s.slice(0, MAX_METADATA_STRING_LEN) : s;
 }
 
+/** Test seam: the normalization branch old rows take is worth asserting directly. */
+export function normalizeUsageEntryForTest(entry: PersistedUsageEntry): PersistedUsageEntry {
+  return normalizeUsageEntry(entry);
+}
+
 function normalizeUsageEntry(entry: PersistedUsageEntry): PersistedUsageEntry {
   const attempts = normalizedAttempts(entry.attempts);
   return {
@@ -271,6 +300,15 @@ function normalizeUsageEntry(entry: PersistedUsageEntry): PersistedUsageEntry {
     provider: entry.provider,
     model: entry.model,
     ...(isKnownUsageSurface(entry.surface) ? { surface: entry.surface } : {}),
+    ...(typeof entry.apiKeyId === "string" && entry.apiKeyId.trim()
+      // Deliberately NOT capped. `capMetadataString` protects free-form metadata
+      // from unbounded growth, but this is a lookup key: truncating it makes the
+      // persisted id stop matching the configured one, and the rollup silently
+      // reports zero for a key that is very much in use.
+      ? { apiKeyId: entry.apiKeyId }
+      : {}),
+    ...(isKnownAdmissionKind(entry.admissionKind) ? { admissionKind: entry.admissionKind } : {}),
+    ...(isKnownInboundProtocol(entry.inboundProtocol) ? { inboundProtocol: entry.inboundProtocol } : {}),
     ...(typeof entry.conversationId === "string" && entry.conversationId.trim()
       ? { conversationId: entry.conversationId.trim().slice(0, 128) }
       : {}),
@@ -349,9 +387,22 @@ export type UsageLogRevision = {
 };
 
 let usageReadCacheStats = { fullReads: 0, tailReads: 0, parsedLines: 0 };
+const MANAGEMENT_USAGE_MAX_READ_BYTES = 64 * 1024 * 1024;
+const MANAGEMENT_USAGE_READ_CHUNK_BYTES = 1024 * 1024;
+const MANAGEMENT_USAGE_MAX_ENTRIES = 200_000;
+const MANAGEMENT_USAGE_FLIGHT_STALE_MS = 30_000;
+export interface ManagementUsageSnapshot {
+  entries: PersistedUsageEntry[];
+  revision: UsageLogRevision;
+  truncatedPrefixBytes: number;
+  entriesTruncated: boolean;
+  entriesDropped: number;
+}
 let managementUsageReadInflight: {
   key: string;
-  promise: Promise<{ entries: PersistedUsageEntry[]; revision: UsageLogRevision }>;
+  promise: Promise<ManagementUsageSnapshot>;
+  startedAt: number;
+  abort: AbortController;
 } | null = null;
 
 /** Test-only observability for proving that unchanged prefixes are not reparsed. */
@@ -361,6 +412,7 @@ export function usageReadCacheStatsForTests(): Readonly<typeof usageReadCacheSta
 
 export function resetUsageReadCacheForTests(): void {
   usageReadCacheStats = { fullReads: 0, tailReads: 0, parsedLines: 0 };
+  managementUsageReadInflight?.abort.abort();
   managementUsageReadInflight = null;
 }
 
@@ -413,12 +465,16 @@ export function currentUsageLogRevision(): UsageLogRevision | null {
   }
 }
 
-async function parseUsageTextCooperatively(text: string): Promise<PersistedUsageEntry[]> {
+async function parseUsageTextCooperatively(text: string, signal: AbortSignal): Promise<{
+  entries: PersistedUsageEntry[];
+  entriesDropped: number;
+}> {
   const lines = text.split(/\r?\n/);
   usageReadCacheStats.parsedLines += lines.filter(line => line.trim()).length;
   const entries: PersistedUsageEntry[] = [];
   const batchSize = 1_000;
   for (let offset = 0; offset < lines.length; offset += batchSize) {
+    if (signal.aborted) throw signal.reason;
     entries.push(...parseUsageLines(lines.slice(offset, offset + batchSize)));
     if (offset + batchSize < lines.length) {
       // JSON parsing dominates large-log startup. Yield between bounded batches so
@@ -426,22 +482,56 @@ async function parseUsageTextCooperatively(text: string): Promise<PersistedUsage
       await new Promise<void>(resolve => setTimeout(resolve, 0));
     }
   }
-  return entries;
+  if (entries.length <= MANAGEMENT_USAGE_MAX_ENTRIES) return { entries, entriesDropped: 0 };
+  const entriesDropped = entries.length - MANAGEMENT_USAGE_MAX_ENTRIES;
+  return { entries: entries.slice(-MANAGEMENT_USAGE_MAX_ENTRIES), entriesDropped };
 }
 
 async function readUsageEntriesFullCooperatively(
   path: string,
-): Promise<{ entries: PersistedUsageEntry[]; revision: UsageLogRevision }> {
+  signal: AbortSignal,
+  maxReadBytes: number,
+): Promise<ManagementUsageSnapshot> {
   let fd: number | undefined;
   try {
     fd = openSync(path, "r");
     const stat = fstatSync(fd);
     const size = Number(stat.size);
-    const bytes = readExactly(fd, size, 0);
-    if (bytes === null) throw new Error("usage log changed while it was being read");
-    const entries = await parseUsageTextCooperatively(bytes.toString("utf-8"));
+    const start = Math.max(0, size - maxReadBytes);
+    const chunks: Buffer[] = [];
+    for (let position = start; position < size;) {
+      if (signal.aborted) throw signal.reason;
+      const length = Math.min(MANAGEMENT_USAGE_READ_CHUNK_BYTES, size - position);
+      const chunk = readExactly(fd, length, position);
+      if (chunk === null) throw new Error("usage log changed while it was being read");
+      chunks.push(chunk);
+      position += length;
+    }
+    let bytes = Buffer.concat(chunks);
+    let truncatedPrefixBytes = start;
+    if (start > 0) {
+      const preceding = readExactly(fd, 1, start - 1);
+      if (preceding === null) throw new Error("usage log changed while it was being read");
+      if (preceding[0] !== 0x0a) {
+        const newline = bytes.indexOf(0x0a);
+        if (newline < 0) {
+          truncatedPrefixBytes += bytes.byteLength;
+          bytes = Buffer.alloc(0);
+        } else {
+          truncatedPrefixBytes += newline + 1;
+          bytes = bytes.subarray(newline + 1);
+        }
+      }
+    }
+    const parsed = await parseUsageTextCooperatively(bytes.toString("utf-8"), signal);
     usageReadCacheStats.fullReads += 1;
-    return { entries, revision: usageLogRevision(path, stat) };
+    return {
+      entries: parsed.entries,
+      revision: usageLogRevision(path, stat),
+      truncatedPrefixBytes,
+      entriesTruncated: parsed.entriesDropped > 0,
+      entriesDropped: parsed.entriesDropped,
+    };
   } finally {
     if (fd !== undefined) closeSync(fd);
   }
@@ -452,22 +542,30 @@ async function readUsageEntriesFullCooperatively(
  * callers share work only when they observed the same exact file revision. Parsed rows
  * are returned to the request and never retained in module state.
  */
-export async function readUsageSnapshotForManagement(): Promise<{
+export async function readUsageSnapshotForManagement(maxReadBytes = MANAGEMENT_USAGE_MAX_READ_BYTES): Promise<{
   entries: PersistedUsageEntry[];
   revision: UsageLogRevision | null;
+  truncatedPrefixBytes: number;
+  entriesTruncated: boolean;
+  entriesDropped: number;
 }> {
+  if (!Number.isSafeInteger(maxReadBytes) || maxReadBytes <= 0) throw new RangeError("management usage max read bytes must be positive");
   const path = usageLogPath();
-  if (!existsSync(path)) return { entries: [], revision: null };
+  if (!existsSync(path)) return { entries: [], revision: null, truncatedPrefixBytes: 0, entriesTruncated: false, entriesDropped: 0 };
   const observed = currentUsageLogRevision();
-  const key = usageLogRevisionKey(observed);
-  if (managementUsageReadInflight?.key === key) {
-    const shared = await managementUsageReadInflight.promise;
-    return { entries: shared.entries.slice(), revision: shared.revision };
+  const key = `${usageLogRevisionKey(observed)}\0${maxReadBytes}`;
+  const existing = managementUsageReadInflight;
+  if (existing?.key === key && Date.now() - existing.startedAt <= MANAGEMENT_USAGE_FLIGHT_STALE_MS) {
+    const shared = await existing.promise;
+    return { ...shared, entries: shared.entries.slice() };
   }
-  const promise = readUsageEntriesFullCooperatively(path);
-  managementUsageReadInflight = { key, promise };
+  existing?.abort.abort(new Error("management usage read superseded"));
+  const abort = new AbortController();
+  const promise = readUsageEntriesFullCooperatively(path, abort.signal, maxReadBytes);
+  managementUsageReadInflight = { key, promise, startedAt: Date.now(), abort };
   try {
-    return await promise;
+    const snapshot = await promise;
+    return { ...snapshot, entries: snapshot.entries.slice() };
   } finally {
     if (managementUsageReadInflight?.promise === promise) managementUsageReadInflight = null;
   }

package/src/usage/summary.ts

@@ -91,6 +91,17 @@ export interface UsageSummary {
 }
 
 const DAY_MS = 86_400_000;
+export const MAX_USAGE_MODEL_BREAKDOWN_ROWS = 256;
+
+function retainedBreakdownRows<T>(
+  rows: T[],
+  aggregateOverflow: (overflow: T[]) => T,
+): T[] {
+  if (rows.length <= MAX_USAGE_MODEL_BREAKDOWN_ROWS) return rows;
+  const keep = rows.slice(0, MAX_USAGE_MODEL_BREAKDOWN_ROWS - 1);
+  keep.push(aggregateOverflow(rows.slice(MAX_USAGE_MODEL_BREAKDOWN_ROWS - 1)));
+  return keep;
+}
 
 export function parseRange(input: string | null | undefined): UsageRange {
   if (input === "7d" || input === "30d" || input === "all") return input;
@@ -334,7 +345,21 @@ function buildDayGrid(range: UsageRange, since: number | null, now: number, entr
   const out = [...grid.values()].sort((a, b) => a.date.localeCompare(b.date));
   for (const day of out) {
     const models = dayModels.get(day.date);
-    if (models) day.models = [...models.values()].sort((a, b) => b.requests - a.requests);
+    if (models) {
+      const sorted = [...models.values()].sort((a, b) => b.requests - a.requests);
+      day.models = retainedBreakdownRows(sorted, overflow => {
+        const requests = new Set<string>();
+        let attemptCount = 0;
+        let totalTokens = 0;
+        for (const model of overflow) {
+          attemptCount += model.attemptCount;
+          totalTokens += model.totalTokens;
+          const requestKey = `${day.date}\0${usageModelKey(model.provider, model.model)}`;
+          for (const requestId of dayModelRequests.get(requestKey) ?? []) requests.add(requestId);
+        }
+        return { model: "other", provider: "other", requests: requests.size, attemptCount, totalTokens };
+      });
+    }
   }
   return out;
 }
@@ -414,7 +439,47 @@ function buildModels(entries: PersistedUsageEntry[], totalTokens: number): Usage
   }
   const models = [...byKey.values()];
   for (const m of models) m.shareRatio = totalTokens === 0 ? 0 : m.totalTokens / totalTokens;
-  return models.sort((a, b) => b.requests - a.requests);
+  const sorted = models.sort((a, b) => b.requests - a.requests);
+  return retainedBreakdownRows(sorted, overflow => {
+    const statusesByRequest = new Map<string, UsageStatus[]>();
+    const other: UsageModel = {
+      provider: "other",
+      model: "other",
+      requests: 0,
+      attemptCount: 0,
+      measuredRequests: 0,
+      reportedRequests: 0,
+      estimatedRequests: 0,
+      totalTokens: 0,
+      inputTokens: 0,
+      outputTokens: 0,
+      shareRatio: 0,
+    };
+    for (const model of overflow) {
+      other.attemptCount += model.attemptCount;
+      other.totalTokens += model.totalTokens;
+      other.inputTokens += model.inputTokens;
+      other.outputTokens += model.outputTokens;
+      if (model.estimatedCostUsd !== undefined) {
+        other.estimatedCostUsd = (other.estimatedCostUsd ?? 0) + model.estimatedCostUsd;
+      }
+      const key = usageModelKey(model.provider, model.model);
+      for (const [requestId, statuses] of statusesByKey.get(key) ?? []) {
+        const combined = statusesByRequest.get(requestId) ?? [];
+        combined.push(...statuses);
+        statusesByRequest.set(requestId, combined);
+      }
+    }
+    other.requests = statusesByRequest.size;
+    for (const statuses of statusesByRequest.values()) {
+      const status = foldAttributionStatuses(statuses);
+      if (isMeasuredStatus(status)) other.measuredRequests += 1;
+      if (status === "reported") other.reportedRequests += 1;
+      else if (status === "estimated") other.estimatedRequests += 1;
+    }
+    other.shareRatio = totalTokens === 0 ? 0 : other.totalTokens / totalTokens;
+    return other;
+  });
 }
 
 function buildProviders(entries: PersistedUsageEntry[], totalTokens: number): UsageProvider[] {

package/src/vision/index.ts

@@ -7,6 +7,8 @@ import type { CodexAuthContext } from "../codex/auth-context";
 import { getAccountSet } from "../oauth/store";
 import type { ResolvedOpenAiForwardSidecar } from "../providers/openai-sidecar";
 import type { SidecarOutcomeRecorder } from "../web-search/executor";
+import { enforceAppOwnedMemoryBudget } from "../lib/app-owned-memory";
+import type { TranslatorBudget } from "../lib/translator-budget";
 
 export { describeImage } from "./describe";
 export { describeImageAnthropic, parseAnthropicVisionSSE } from "./anthropic-describe";
@@ -16,6 +18,8 @@ const DEFAULT_ANTHROPIC_VISION_MODEL = "claude-sonnet-5";
 const DEFAULT_TIMEOUT_MS = 45_000;
 const DEFAULT_MAX_DESCRIPTIONS_PER_TURN = 8;
 const DESCRIPTION_CACHE_MAX_ENTRIES = 256;
+export const VISION_DESCRIPTION_CACHE_MAX_BYTES = 1024 * 1024;
+const descriptionEncoder = new TextEncoder();
 /** Max images described in parallel — keeps first-token latency bounded without flooding the backend. */
 const VISION_CONCURRENCY = 3;
 /** Per-image description hard cap (chars) so multi-image turns can't blow the main model's context. */
@@ -27,47 +31,109 @@ export interface VisionDescriptionCache {
   get(key: string): string | undefined;
   set(key: string, value: string): void;
   clear(): void;
+  snapshot?(): { count: number; bytes: number; oldestAt: number | null };
+  evictOldest?(): number;
 }
 
 class BoundedLruDescriptionCache implements VisionDescriptionCache {
-  private readonly entries = new Map<string, string>();
+  private readonly entries = new Map<string, { value: string; sizeBytes: number; storedAt: number }>();
+  private bytes = 0;
 
-  constructor(private readonly maxEntries: number) {}
+  constructor(private readonly maxEntries: number, private readonly maxBytes: number) {}
 
   get(key: string): string | undefined {
-    const value = this.entries.get(key);
-    if (value === undefined) return undefined;
+    const entry = this.entries.get(key);
+    if (entry === undefined) return undefined;
     this.entries.delete(key);
-    this.entries.set(key, value);
-    return value;
+    entry.storedAt = Date.now();
+    this.entries.set(key, entry);
+    return entry.value;
   }
 
   set(key: string, value: string): void {
-    this.entries.delete(key);
-    this.entries.set(key, value);
-    while (this.entries.size > this.maxEntries) {
-      const oldest = this.entries.keys().next().value;
-      if (oldest === undefined) break;
-      this.entries.delete(oldest);
+    const existing = this.entries.get(key);
+    if (existing) {
+      this.entries.delete(key);
+      this.bytes -= existing.sizeBytes;
+    }
+    const sizeBytes = descriptionEncoder.encode(key).byteLength + descriptionEncoder.encode(value).byteLength;
+    if (sizeBytes > this.maxBytes || this.maxEntries <= 0) return;
+    while (this.entries.size + 1 > this.maxEntries || this.bytes + sizeBytes > this.maxBytes) {
+      if (this.evictOldest() === 0) return;
     }
+    this.entries.set(key, { value, sizeBytes, storedAt: Date.now() });
+    this.bytes += sizeBytes;
   }
 
   clear(): void {
     this.entries.clear();
+    this.bytes = 0;
+  }
+
+  snapshot(): { count: number; bytes: number; oldestAt: number | null } {
+    return {
+      count: this.entries.size,
+      bytes: this.bytes,
+      oldestAt: this.entries.values().next().value?.storedAt ?? null,
+    };
+  }
+
+  evictOldest(): number {
+    const oldest = this.entries.keys().next().value;
+    if (oldest === undefined) return 0;
+    const entry = this.entries.get(oldest);
+    if (!entry) return 0;
+    this.entries.delete(oldest);
+    this.bytes -= entry.sizeBytes;
+    return entry.sizeBytes;
   }
 }
 
-let descriptionCache: VisionDescriptionCache = new BoundedLruDescriptionCache(DESCRIPTION_CACHE_MAX_ENTRIES);
+let descriptionCacheLimits = {
+  maxEntries: DESCRIPTION_CACHE_MAX_ENTRIES,
+  maxBytes: VISION_DESCRIPTION_CACHE_MAX_BYTES,
+};
+
+function defaultDescriptionCache(): VisionDescriptionCache {
+  return new BoundedLruDescriptionCache(descriptionCacheLimits.maxEntries, descriptionCacheLimits.maxBytes);
+}
+
+let descriptionCache: VisionDescriptionCache = defaultDescriptionCache();
 
 /** Replace the process cache (primarily for deterministic tests). Passing undefined restores the default LRU. */
 export function setVisionDescriptionCache(cache?: VisionDescriptionCache): void {
-  descriptionCache = cache ?? new BoundedLruDescriptionCache(DESCRIPTION_CACHE_MAX_ENTRIES);
+  descriptionCache = cache ?? defaultDescriptionCache();
 }
 
 export function resetVisionDescriptionCache(): void {
   descriptionCache.clear();
 }
 
+export function setVisionDescriptionCacheLimitsForTests(
+  limits?: { maxEntries?: number; maxBytes?: number },
+): void {
+  descriptionCacheLimits = limits
+    ? { maxEntries: limits.maxEntries ?? DESCRIPTION_CACHE_MAX_ENTRIES, maxBytes: limits.maxBytes ?? VISION_DESCRIPTION_CACHE_MAX_BYTES }
+    : { maxEntries: DESCRIPTION_CACHE_MAX_ENTRIES, maxBytes: VISION_DESCRIPTION_CACHE_MAX_BYTES };
+  descriptionCache = defaultDescriptionCache();
+}
+
+export function visionDescriptionRetainedStoreSnapshot(): {
+  count: number;
+  bytes: number;
+  evictableBytes: number;
+  pinnedBytes: number;
+  oldestAt: number | null;
+} {
+  const snapshot = descriptionCache.snapshot?.();
+  if (!snapshot) return { count: 0, bytes: 0, evictableBytes: 0, pinnedBytes: 0, oldestAt: null };
+  return { ...snapshot, evictableBytes: snapshot.bytes, pinnedBytes: 0 };
+}
+
+export function evictOldestVisionDescriptionForBudget(): number {
+  return descriptionCache.evictOldest?.() ?? 0;
+}
+
 /** Runtime config is permissive: zero is intentional; malformed values fall back to the bounded default. */
 export function resolveMaxDescriptionsPerTurn(value: unknown): number {
   if (value === 0) return 0;
@@ -279,6 +345,7 @@ export async function describeImagesInPlace(
   selectedForwardHeaders: Headers,
   abortSignal?: AbortSignal,
   recordSidecarOutcome?: SidecarOutcomeRecorder,
+  translatorBudget?: TranslatorBudget,
 ): Promise<void> {
   // 1. Gather every image part across messages, each with its own message's text as context.
   const jobs: ImageJob[] = [];
@@ -338,9 +405,13 @@ export async function describeImagesInPlace(
       } catch (error) {
         outcome = { text: "", error: error instanceof Error ? error.message : String(error) };
       }
-      const successfulText = outcome.error ? "" : outcome.text.trim();
-      if (identity.persistent && successfulText) descriptionCache.set(identity.key, successfulText);
-      resolveOutcome(outcome);
+      const successfulText = outcome.error ? "" : clamp(outcome.text.trim(), DESC_MAX_CHARS);
+      if (identity.persistent && successfulText) {
+        descriptionCache.set(identity.key, successfulText);
+        enforceAppOwnedMemoryBudget();
+      }
+      const resolvedOutcome = outcome.error ? outcome : { ...outcome, text: successfulText };
+      resolveOutcome(resolvedOutcome);
     });
   }
 
@@ -351,7 +422,19 @@ export async function describeImagesInPlace(
   let oi = 0;
   for (const { msg, parts } of targets) {
     const newParts: OcxContentPart[] = [];
-    for (const p of parts) newParts.push(p.type === "image" ? renderDescription(outcomes[oi++]) : p);
+    for (const p of parts) {
+      if (p.type !== "image") {
+        newParts.push(p);
+        continue;
+      }
+      const replacement = renderDescription(outcomes[oi++]);
+      const reservation = translatorBudget?.reserveTransient(
+        descriptionEncoder.encode(replacement.text).byteLength,
+        { kind: "request_copies" },
+      );
+      newParts.push(replacement);
+      reservation?.commitRetained();
+    }
     msg.content = newParts;
   }
 }
@@ -362,15 +445,22 @@ export async function describeImagesInPlace(
  * raw images would 400 or silently confuse it. Replace each image with an explicit marker so the
  * model (and the user, via its reply) knows the image was dropped rather than ignored.
  */
-export function stripImagesInPlace(parsed: OcxParsedRequest): boolean {
+export function stripImagesInPlace(parsed: OcxParsedRequest, translatorBudget?: TranslatorBudget): boolean {
   let stripped = false;
   for (const msg of parsed.context.messages) {
     if (!carriesImages(msg.role) || !Array.isArray(msg.content)) continue;
     const parts = msg.content as OcxContentPart[];
     if (!parts.some(p => p.type === "image")) continue;
-    msg.content = parts.map(p => p.type === "image"
-      ? { type: "text", text: "[image omitted: this model is text-only and the vision sidecar is unavailable (no ChatGPT login)]" } as OcxContentPart
-      : p);
+    msg.content = parts.map(p => {
+      if (p.type !== "image") return p;
+      const replacement = { type: "text", text: "[image omitted: this model is text-only and the vision sidecar is unavailable (no ChatGPT login)]" } as OcxContentPart;
+      const reservation = translatorBudget?.reserveTransient(
+        descriptionEncoder.encode((replacement as OcxTextContent).text).byteLength,
+        { kind: "request_copies" },
+      );
+      reservation?.commitRetained();
+      return replacement;
+    });
     stripped = true;
   }
   return stripped;

package/src/web-search/loop.ts

@@ -1,4 +1,4 @@
-import type { AdapterRequest, ProviderAdapter } from "../adapters/base";
+import type { AdapterRequest, IncomingMeta, ProviderAdapter } from "../adapters/base";
 import type { AdapterEvent, OcxMessage, OcxParsedRequest, OcxProviderConfig, OcxThinkingContent, OcxUsage } from "../types";
 import { namespacedToolName } from "../types";
 import { bridgeToResponsesSSE } from "../bridge";
@@ -8,6 +8,11 @@ import { clearableDeadline } from "../lib/abort";
 import { redactSecretString } from "../lib/redact";
 import { readBoundedResponseBody } from "../lib/bounded-body";
 import { fetchWithResetRetry } from "../lib/upstream-retry";
+import {
+  isTranslatorBudgetExceededError,
+  TRANSLATOR_MAX_TURN_BYTES,
+  TranslatorBudgetExceededError,
+} from "../lib/translator-budget";
 import { formatWebSearchResults } from "./format-result";
 import { parseStreamWithProgress, RoutedModelInactivityError, WebSearchStreamProtocolError } from "./progress-stream";
 import { WEB_SEARCH_TOOL_NAME } from "./synthetic-tool";
@@ -204,6 +209,7 @@ class LoopError extends Error {
 export interface WebSearchLoopDeps {
   parsed: OcxParsedRequest;
   adapter: ProviderAdapter;
+  incomingMeta: IncomingMeta;
   /** Which executor runs searches. Defaults to "openai" so existing callers keep the ChatGPT path (audit F4). */
   backend?: "openai" | "anthropic";
   /** Required for the openai backend; unused (and typically undefined) for the anthropic backend. */
@@ -247,6 +253,7 @@ export interface WebSearchLoopDeps {
  * inject the answer as a tool_result, and loop (bounded by `maxSearches`).
  */
 export async function runWithWebSearch(deps: WebSearchLoopDeps): Promise<Response> {
+  const translatorBudget = deps.incomingMeta.translatorBudget;
   const { parsed, selectedForwardHeaders, forwardProvider, hostedTool, settings, maxSearches, abortSignal, recordSidecarOutcome } = deps;
   const backend = deps.backend ?? "openai";
   const anthropicSidecar = deps.anthropicSidecar;
@@ -312,14 +319,17 @@ export async function runWithWebSearch(deps: WebSearchLoopDeps): Promise<Respons
         const request = await requestAdapter.buildRequest(iterParsed, {
           headers: selectedForwardHeaders,
           abortSignal: headerDeadline.signal,
+          translatorBudget,
         });
         try {
           deps.onRequestBuilt?.(request);
         } catch {
           // Diagnostics are best-effort and must never abort a web-search iteration.
         }
-        const response = requestAdapter.fetchResponse
-          ? await requestAdapter.fetchResponse(request, {
+        let response: Response;
+        try {
+          response = requestAdapter.fetchResponse
+            ? await requestAdapter.fetchResponse(request, {
               abortSignal: headerDeadline.signal,
               timeoutMs: connectTimeoutMs,
               returnRawErrors: true,
@@ -337,7 +347,10 @@ export async function runWithWebSearch(deps: WebSearchLoopDeps): Promise<Respons
                 });
               },
               { abortSignal: headerDeadline.signal, label: "web-search-loop" },
-            );
+              );
+        } finally {
+          request.releaseBodyObservation?.();
+        }
         return { response, responseAdapter: requestAdapter };
       };
 
@@ -385,6 +398,7 @@ export async function runWithWebSearch(deps: WebSearchLoopDeps): Promise<Respons
       }
       return prepared;
     } catch (error) {
+      if (isTranslatorBudgetExceededError(error)) throw error;
       if (headerDeadline.didExpire()) {
         throw new LoopError(504, `Provider response-header timeout after ${connectTimeoutMs}ms during web-search`);
       }
@@ -412,6 +426,7 @@ export async function runWithWebSearch(deps: WebSearchLoopDeps): Promise<Respons
       for await (const event of parseStreamWithProgress(prepared.response, parse, {
         signal,
         inactivityTimeoutMs: routedModelStallTimeoutMs,
+        translatorBudget,
       })) {
         if (event.type === "heartbeat") yield event;
         // Kiro's explicit-completion protocol marks ordinary assistant text as commentary while
@@ -424,6 +439,7 @@ export async function runWithWebSearch(deps: WebSearchLoopDeps): Promise<Respons
         else events.push(event);
       }
     } catch (error) {
+      if (isTranslatorBudgetExceededError(error)) throw error;
       if (signal.aborted) throw new LoopError(499, "client closed request during web-search");
       if (error instanceof RoutedModelInactivityError) throw new LoopError(504, error.message);
       if (error instanceof WebSearchStreamProtocolError) throw new LoopError(502, error.message);
@@ -436,7 +452,12 @@ export async function runWithWebSearch(deps: WebSearchLoopDeps): Promise<Respons
       throw new LoopError(502, `Web-search adapter stream protocol error: expected one final terminal event, received ${terminalIndexes.length}`);
     }
     const terminal = events[terminalIndexes[0]!];
-    if (terminal.type === "error") throw new LoopError(502, terminal.message);
+    if (terminal.type === "error") {
+      if (terminal.code === "translation_buffer_limit") {
+        throw new TranslatorBudgetExceededError("retained_collectors", TRANSLATOR_MAX_TURN_BYTES);
+      }
+      throw new LoopError(502, terminal.message);
+    }
     return scanEventsForWebSearch(events);
   };
 
@@ -603,7 +624,17 @@ export async function runWithWebSearch(deps: WebSearchLoopDeps): Promise<Respons
             yield* runSearchCall(call, callIndex === 0 ? iterationThinking : []);
           }
         } catch (e) {
-          yield { type: "error", message: e instanceof LoopError ? e.message : (e instanceof Error ? e.message : String(e)) };
+          if (isTranslatorBudgetExceededError(e)) {
+            yield {
+              type: "error",
+              status: 502,
+              errorType: "upstream_error",
+              code: e.code,
+              message: "upstream translation buffer exceeded the safe limit",
+            };
+          } else {
+            yield { type: "error", message: e instanceof LoopError ? e.message : (e instanceof Error ? e.message : String(e)) };
+          }
           return;
         }
       }
@@ -621,6 +652,7 @@ export async function runWithWebSearch(deps: WebSearchLoopDeps): Promise<Respons
       internalAbort.abort("client closed responses stream");
     }, undefined,
     {
+      translatorBudget,
       ...(deps.forceEmptyResponseId ? { responseId: "" } : {}),
       hideThinkingSummary: parsed.options.hideThinkingSummary,
       ...(deps.stallTimeoutSec !== undefined ? { stallTimeoutSec: deps.stallTimeoutSec } : {}),