@opengeni/codex 0.2.3 → 0.2.5

package/src/model-output-truncation.ts

@@ -0,0 +1,590 @@
+/**
+ * Canonical model-facing tool-output truncation.
+ *
+ * Ported from openai/codex `rust-v0.144.6` (commit
+ * 5d1fbf26c43abc65a203928b2e31561cb039e06d):
+ *
+ * - `codex-rs/utils/string/src/truncate.rs`
+ * - `codex-rs/utils/output-truncation/src/lib.rs`
+ * - `codex-rs/core/src/context_manager/history.rs`
+ *
+ * The live gpt-5.6 model catalog declares a 10,000-token truncation policy.
+ * Codex applies a 1.2x allowance before serializing a function-call output, so
+ * the effective textual payload budget is 12,000 approximate tokens. Images,
+ * files, and encrypted content are preserved; textual content shares one
+ * sequential budget and carries an explicit head/tail truncation marker.
+ *
+ * This module deliberately has no database or Agents SDK dependency. Both the
+ * runtime request seam and the database history boundary call the same pure
+ * function, so replayed conversation truth is identical to live model input.
+ */
+
+import { MODEL_TOOL_OUTPUT_OVERSIZED_IMAGE_CARD_DATA_URL } from "./oversized-image-card";
+
+export { MODEL_TOOL_OUTPUT_OVERSIZED_IMAGE_CARD_DATA_URL } from "./oversized-image-card";
+
+export type ModelHistoryItem = Record<string, unknown>;
+
+export const CODEX_MODEL_TOOL_OUTPUT_TRUNCATION_TOKENS = 10_000;
+export const CODEX_TOOL_OUTPUT_SERIALIZATION_ALLOWANCE = 1.2;
+export const DEFAULT_MODEL_TOOL_OUTPUT_TRUNCATION_TOKENS =
+  CODEX_MODEL_TOOL_OUTPUT_TRUNCATION_TOKENS;
+
+const APPROX_BYTES_PER_TOKEN = 4;
+// Twelve decimal digits already describe ~4 TB at four bytes/token, far beyond
+// any JavaScript string the runtime can materialize. Bounding the digit run is
+// security-significant: otherwise a forged multi-megabyte run of digits could
+// make `markerBytes` as large as the entire untrusted tool result and bypass the
+// cap below.
+const TOKEN_TRUNCATION_MARKER = /…\d{1,12} tokens truncated…/u;
+const TOOL_RESULT_TYPES = new Set([
+  "function_call_result",
+  "function_call_output",
+  "computer_call_result",
+  "custom_tool_call_output",
+  "shell_call_output",
+  "apply_patch_call_output",
+]);
+const STRUCTURAL_STRING_KEYS = new Set([
+  "type",
+  "role",
+  "status",
+  "name",
+  "id",
+  "callId",
+  "call_id",
+  "namespace",
+  "detail",
+  "mimeType",
+  "media_type",
+]);
+const MODEL_TOOL_OUTPUT_MAX_DEPTH = 12;
+const MODEL_TOOL_OUTPUT_MAX_CONTAINER_ENTRIES = 255;
+const MODEL_TOOL_OUTPUT_MAX_TOTAL_ENTRIES = 2_048;
+const MODEL_TOOL_OUTPUT_MAX_PROPERTY_KEY_BYTES = 256;
+const MODEL_TOOL_OUTPUT_MAX_STRUCTURAL_STRING_TOKENS = 64;
+const MODEL_TOOL_OUTPUT_STRUCTURAL_STRING_BUDGET_TOKENS = 1_024;
+export const MODEL_TOOL_OUTPUT_OPAQUE_PAYLOAD_MAX_BYTES = 8 * 1024 * 1024;
+
+const DEPTH_OMISSION_MARKER =
+  "[OpenGeni omitted subtree: maximum structured tool-output depth exceeded]";
+const CYCLE_OMISSION_MARKER = "[OpenGeni omitted subtree: cyclic tool output]";
+const STRUCTURAL_STRING_OMISSION_MARKER =
+  "[OpenGeni omitted structural string: structural budget exhausted]";
+const TEXT_FIELD_OMISSION_MARKER = /^\[omitted text field \d+ \.\.\.\]$/u;
+const TEXT_ITEMS_OMISSION_MARKER = /^\[omitted \d+ text items \.\.\.\]$/u;
+const STRUCTURAL_ENTRIES_OMISSION_MARKER =
+  /^\[OpenGeni omitted \d+ structured (?:array items|object properties)\]$/u;
+const OPAQUE_PAYLOAD_OMISSION_MARKER =
+  /^\[OpenGeni omitted (?:image|file|encrypted) payload: \d+ bytes exceeded the bounded model-input allowance\]$/u;
+const STRUCTURAL_PROPERTIES_MARKER_KEY = "__opengeni_omitted_properties__";
+
+type OpaqueProtocolKind = "image" | "file" | "encrypted";
+
+type ModelOutputBoundState = {
+  remaining: number;
+  remainingStructural: number;
+  remainingEntries: number;
+  remainingOpaqueBytes: number;
+  opaqueOmissions: number;
+  lastOpaqueOmissionMarker: string | null;
+  omitted: number;
+  seen: WeakSet<object>;
+};
+
+export function modelToolOutputSerializationBudgetTokens(
+  policyTokens = DEFAULT_MODEL_TOOL_OUTPUT_TRUNCATION_TOKENS,
+): number {
+  return Math.ceil(Math.max(0, policyTokens) * CODEX_TOOL_OUTPUT_SERIALIZATION_ALLOWANCE);
+}
+
+export function approximateTokenCount(value: string): number {
+  return Math.ceil(Buffer.byteLength(value, "utf8") / APPROX_BYTES_PER_TOKEN);
+}
+
+/** Exact Codex-style middle truncation for a token policy. */
+export function truncateMiddleWithTokenBudget(value: string, maxTokens: number): string {
+  if (value.length === 0) return value;
+  const maxBytes = Math.max(0, maxTokens) * APPROX_BYTES_PER_TOKEN;
+  const valueBytes = Buffer.byteLength(value, "utf8");
+  if (maxTokens > 0 && valueBytes <= maxBytes) return value;
+  // Codex applies this transform once while recording history, so its marker
+  // sits just outside the content budget. OpenGeni deliberately enforces the
+  // same policy both at canonical persistence and at the final provider seam.
+  // Recognize only an output whose excess is no larger than its own canonical
+  // marker; this makes that repeated enforcement byte-idempotent without letting
+  // an arbitrary oversized string bypass the cap merely by containing marker-like
+  // text. The first application remains byte-for-byte Codex 0.144.6 behavior.
+  const existingMarker = value.match(TOKEN_TRUNCATION_MARKER)?.[0];
+  if (existingMarker && valueBytes <= maxBytes + Buffer.byteLength(existingMarker, "utf8")) {
+    return value;
+  }
+  if (maxBytes === 0) {
+    return `…${approximateTokenCount(value)} tokens truncated…`;
+  }
+
+  const leftBudget = Math.floor(maxBytes / 2);
+  const rightBudget = maxBytes - leftBudget;
+  // Do not materialize `Array.from(value)`: production tool results can be
+  // multi-megabyte strings and one JS element per code point multiplies peak
+  // memory. A single UTF-8 buffer gives bounded scans at the two cut points.
+  const bytes = Buffer.from(value, "utf8");
+  let leftEnd = Math.min(leftBudget, bytes.length);
+  while (leftEnd > 0 && leftEnd < bytes.length && isUtf8ContinuationByte(bytes[leftEnd]!)) {
+    leftEnd -= 1;
+  }
+  let rightStart = Math.max(0, bytes.length - rightBudget);
+  while (rightStart < bytes.length && isUtf8ContinuationByte(bytes[rightStart]!)) {
+    rightStart += 1;
+  }
+  const left = bytes.subarray(0, leftEnd).toString("utf8");
+  const right = bytes.subarray(rightStart).toString("utf8");
+  const removedBytes = Math.max(0, valueBytes - maxBytes);
+  const removedTokens = Math.ceil(removedBytes / APPROX_BYTES_PER_TOKEN);
+  return `${left}…${removedTokens} tokens truncated…${right}`;
+}
+
+function isUtf8ContinuationByte(value: number): boolean {
+  return (value & 0xc0) === 0x80;
+}
+
+/**
+ * Bound every model-visible tool-result item. Non-result items are returned by
+ * reference. Result items are cloned only when their textual output changes.
+ */
+export function boundModelToolOutputItem<T extends ModelHistoryItem>(
+  item: T,
+  policyTokens = DEFAULT_MODEL_TOOL_OUTPUT_TRUNCATION_TOKENS,
+): T {
+  const type = typeof item.type === "string" ? item.type : "";
+  if (!TOOL_RESULT_TYPES.has(type)) return item;
+  const budget = modelToolOutputSerializationBudgetTokens(policyTokens);
+  const boundedOutput = boundToolOutputValue(item.output, budget);
+  return boundedOutput === item.output ? item : ({ ...item, output: boundedOutput } as T);
+}
+
+export function boundModelToolOutputItems<T extends ModelHistoryItem>(
+  items: readonly T[],
+  policyTokens = DEFAULT_MODEL_TOOL_OUTPUT_TRUNCATION_TOKENS,
+): T[] {
+  return items.map((item) => boundModelToolOutputItem(item, policyTokens));
+}
+
+function boundToolOutputValue(output: unknown, budgetTokens: number): unknown {
+  const state = modelOutputBoundState(budgetTokens);
+  if (typeof output === "string") {
+    if (isGeneratedModelOutputMarker(output)) {
+      observeGeneratedMarkerBudget(output, state);
+      return output;
+    }
+    // Text-transport computer/view_image tools use a data URL because Chat
+    // Completions has no structured image result. It is still image protocol,
+    // not textual tool output; truncating its base64 permanently corrupts it.
+    if (isImageDataUrl(output)) return boundOpaqueProtocolString(output, state, "image");
+    return truncateMiddleWithTokenBudget(output, budgetTokens);
+  }
+  if (Array.isArray(output)) {
+    // Responses content arrays have an explicit text/image/file protocol and
+    // follow Codex's sequential item policy exactly. Shell/apply adapters can
+    // instead return arrays of objects containing stdout/stderr; those share
+    // the same total text budget through the generic leaf walker.
+    // Inspect only the prefix the boundary can retain. Cardinality itself does
+    // not make an otherwise-valid Responses content list invalid, and scanning
+    // an untrusted 100k-item tail merely to classify it defeats the bound.
+    const isProtocolContent = isResponsesProtocolContentPrefix(output);
+    return isProtocolContent
+      ? boundStructuredOutputItems(output, state)
+      : boundTextLeaves(output, state);
+  }
+  if (!output || typeof output !== "object") return output;
+
+  const record = output as Record<string, unknown>;
+  // Shell/apply-patch result objects are not structured Responses content, but
+  // can contain arbitrarily large stdout/stderr leaves. Preserve useful shape
+  // while sharing bounded text, structural, entry, depth, and opaque-protocol
+  // budgets across the whole value.
+  return boundTextLeaves(record, state);
+}
+
+function modelOutputBoundState(budgetTokens: number): ModelOutputBoundState {
+  return {
+    remaining: Math.max(0, budgetTokens),
+    remainingStructural: MODEL_TOOL_OUTPUT_STRUCTURAL_STRING_BUDGET_TOKENS,
+    remainingEntries: MODEL_TOOL_OUTPUT_MAX_TOTAL_ENTRIES,
+    remainingOpaqueBytes: MODEL_TOOL_OUTPUT_OPAQUE_PAYLOAD_MAX_BYTES,
+    opaqueOmissions: 0,
+    lastOpaqueOmissionMarker: null,
+    omitted: 0,
+    seen: new WeakSet(),
+  };
+}
+
+function boundStructuredOutputItems(items: unknown[], state: ModelOutputBoundState): unknown[] {
+  let omitted = 0;
+  let changed = false;
+  const out: unknown[] = [];
+  let processed = 0;
+  // A canonical first pass can contain one typed structural trailer beyond the
+  // ordinary 255 retained parts. Preserve that exact terminal trailer when a
+  // durable/provider/recovery boundary applies the function again. Limiting
+  // this exception to an already-bounded array prevents an arbitrary huge tail
+  // with a marker-shaped last element from bypassing the first-pass count.
+  const terminalStructuralMarker =
+    items.length <= MODEL_TOOL_OUTPUT_MAX_CONTAINER_ENTRIES + 1 &&
+    isTypedStructuralArrayOmissionMarker(items.at(-1))
+      ? items.at(-1)
+      : null;
+  let preservedTerminalStructuralMarker = false;
+  for (let index = 0; index < items.length; index += 1) {
+    const item = items[index];
+    if (processed >= MODEL_TOOL_OUTPUT_MAX_CONTAINER_ENTRIES || state.remainingEntries <= 0) {
+      if (terminalStructuralMarker && index <= items.length - 1) {
+        out.push(terminalStructuralMarker);
+        preservedTerminalStructuralMarker = true;
+      }
+      break;
+    }
+    processed += 1;
+    state.remainingEntries -= 1;
+    const record = item as Record<string, unknown>;
+    if (record.type === "input_text" && isGeneratedModelOutputMarker(record.text)) {
+      const bounded = boundTextLeaves(item, state, 1);
+      out.push(bounded);
+      if (item === terminalStructuralMarker) preservedTerminalStructuralMarker = true;
+      if (bounded !== item) changed = true;
+      continue;
+    }
+    if (record.type === "input_text" && state.remaining === 0) {
+      omitted += 1;
+      changed = true;
+      continue;
+    }
+    const bounded = boundResponsesProtocolContentItem(record, state);
+    out.push(bounded);
+    if (item === terminalStructuralMarker) preservedTerminalStructuralMarker = true;
+    if (bounded !== item) changed = true;
+  }
+  if (omitted > 0) {
+    out.push({
+      type: "input_text",
+      text: `[omitted ${omitted} text items ...]`,
+    });
+  }
+  const structurallyOmitted = preservedTerminalStructuralMarker ? 0 : items.length - processed;
+  if (structurallyOmitted > 0) {
+    out.push(typedStructuredArrayOmissionMarker(structurallyOmitted));
+    changed = true;
+  }
+  return changed ? out : items;
+}
+
+function boundResponsesProtocolContentItem(
+  item: Record<string, unknown>,
+  state: ModelOutputBoundState,
+): Record<string, unknown> {
+  const opaqueOmissionsBefore = state.opaqueOmissions;
+  const bounded = boundTextLeaves(item, state, 1) as Record<string, unknown>;
+  // Agents interprets fileId/file_id (and nested image.id) as a provider file
+  // reference. Replacing only that string with our data URL would manufacture
+  // a fictitious file_id. Normalize the whole overflowing image part instead,
+  // removing every ID field while staying inside the Responses content union.
+  if (item.type === "input_image" && state.opaqueOmissions > opaqueOmissionsBefore) {
+    return {
+      type: "input_image",
+      imageUrl: MODEL_TOOL_OUTPUT_OVERSIZED_IMAGE_CARD_DATA_URL,
+    };
+  }
+  // A marker string in `input_file.file` is interpreted by pinned Agents as a
+  // file_url. Replace the whole content part instead, so every generated
+  // omission remains inside the Responses text/image/file union without
+  // inventing a URL or file ID. This also covers cumulative opaque exhaustion.
+  if (item.type === "input_file" && state.opaqueOmissions > opaqueOmissionsBefore) {
+    return typedProtocolTextMarker(
+      state.lastOpaqueOmissionMarker ??
+        "[OpenGeni omitted file payload: 0 bytes exceeded the bounded model-input allowance]",
+    );
+  }
+  return bounded;
+}
+
+function boundTextLeaves(
+  value: unknown,
+  state: ModelOutputBoundState,
+  depth = 0,
+  opaqueKind: OpaqueProtocolKind | null = null,
+): unknown {
+  if (typeof value === "string") {
+    if (isGeneratedModelOutputMarker(value)) {
+      observeGeneratedMarkerBudget(value, state);
+      return value;
+    }
+    if (opaqueKind || isImageDataUrl(value)) {
+      return boundOpaqueProtocolString(value, state, opaqueKind ?? "image");
+    }
+    if (state.remaining === 0) {
+      state.omitted += 1;
+      return `[omitted text field ${state.omitted} ...]`;
+    }
+    const cost = approximateTokenCount(value);
+    if (cost <= state.remaining) {
+      state.remaining -= cost;
+      return value;
+    }
+    const bounded = truncateMiddleWithTokenBudget(value, state.remaining);
+    state.remaining = 0;
+    return bounded;
+  }
+  if (!value || typeof value !== "object") return value;
+  if (depth >= MODEL_TOOL_OUTPUT_MAX_DEPTH) return DEPTH_OMISSION_MARKER;
+  if (state.seen.has(value)) return CYCLE_OMISSION_MARKER;
+  state.seen.add(value);
+  if (Array.isArray(value)) {
+    const out: unknown[] = [];
+    let processed = 0;
+    let changed = false;
+    for (let index = 0; index < value.length; index += 1) {
+      const entry = value[index];
+      if (processed >= MODEL_TOOL_OUTPUT_MAX_CONTAINER_ENTRIES || state.remainingEntries <= 0) {
+        // A prior pass can add exactly one structural trailer beyond the normal
+        // item allowance. Retain only that final trailer for replay idempotence;
+        // marker-shaped untrusted entries otherwise consume the same caps as
+        // every other entry and cannot form an unbounded bypass.
+        if (
+          index === value.length - 1 &&
+          typeof entry === "string" &&
+          STRUCTURAL_ENTRIES_OMISSION_MARKER.test(entry)
+        ) {
+          out.push(entry);
+        }
+        break;
+      }
+      processed += 1;
+      state.remainingEntries -= 1;
+      const bounded = boundTextLeaves(entry, state, depth + 1, opaqueKind);
+      out.push(bounded);
+      if (bounded !== entry) changed = true;
+    }
+    const omitted = value.length - out.length;
+    if (omitted > 0) {
+      out.push(structuredEntriesOmissionMarker(omitted, "array"));
+      changed = true;
+    }
+    state.seen.delete(value);
+    return changed ? out : value;
+  }
+  const record = value as Record<string, unknown>;
+  const recordOpaqueKind = nonTextProtocolKind(record.type) ?? opaqueKind;
+  const entries = Object.entries(record);
+  const out: Record<string, unknown> = {};
+  let processed = 0;
+  let omitted = 0;
+  let changed = false;
+  for (let index = 0; index < entries.length; index += 1) {
+    const [key, entry] = entries[index]!;
+    if (processed >= MODEL_TOOL_OUTPUT_MAX_CONTAINER_ENTRIES || state.remainingEntries <= 0) {
+      // As with arrays, a bounded prior pass may have appended one final marker
+      // property after filling the normal property allowance. Preserve only
+      // that terminal marker; forged/interspersed marker properties remain
+      // ordinary bounded input.
+      if (index === entries.length - 1 && isGeneratedStructuralMarkerProperty(key, entry)) {
+        out[key] = entry;
+        break;
+      }
+      omitted += entries.length - index;
+      break;
+    }
+    processed += 1;
+    state.remainingEntries -= 1;
+    if (Buffer.byteLength(key, "utf8") > MODEL_TOOL_OUTPUT_MAX_PROPERTY_KEY_BYTES) {
+      omitted += 1;
+      changed = true;
+      continue;
+    }
+    const childOpaqueKind = opaqueKindForChild(recordOpaqueKind, key);
+    if (typeof entry === "string" && childOpaqueKind) {
+      const bounded = boundTextLeaves(entry, state, depth + 1, childOpaqueKind);
+      out[key] = bounded;
+      if (bounded !== entry) changed = true;
+      continue;
+    }
+    if (typeof entry === "string" && STRUCTURAL_STRING_KEYS.has(key)) {
+      const bounded = boundStructuralString(entry, state);
+      out[key] = bounded;
+      if (bounded !== entry) changed = true;
+      continue;
+    }
+    const bounded = boundTextLeaves(entry, state, depth + 1, childOpaqueKind);
+    out[key] = bounded;
+    if (bounded !== entry) changed = true;
+  }
+  if (omitted > 0) {
+    out[uniqueStructuralMarkerKey(out)] = structuredEntriesOmissionMarker(omitted, "object");
+    changed = true;
+  }
+  state.seen.delete(value);
+  return changed ? out : value;
+}
+
+function boundStructuralString(value: string, state: ModelOutputBoundState): string {
+  if (isGeneratedModelOutputMarker(value)) {
+    observeGeneratedMarkerBudget(value, state);
+    return value;
+  }
+  if (state.remainingStructural === 0) return STRUCTURAL_STRING_OMISSION_MARKER;
+  const cost = approximateTokenCount(value);
+  const allowance = Math.min(
+    MODEL_TOOL_OUTPUT_MAX_STRUCTURAL_STRING_TOKENS,
+    state.remainingStructural,
+  );
+  if (cost <= allowance) {
+    state.remainingStructural -= cost;
+    return value;
+  }
+  state.remainingStructural -= allowance;
+  return truncateMiddleWithTokenBudget(value, allowance);
+}
+
+function boundOpaqueProtocolString(
+  value: string,
+  state: ModelOutputBoundState,
+  kind: OpaqueProtocolKind,
+): string {
+  // A prior pass can only have produced this exact static value. Treat it as a
+  // consumed image allowance so applying the boundary again is byte-idempotent
+  // even when more image fields follow it in the same structured result.
+  if (kind === "image" && value === MODEL_TOOL_OUTPUT_OVERSIZED_IMAGE_CARD_DATA_URL) {
+    state.remainingOpaqueBytes = 0;
+    return value;
+  }
+  const bytes = Buffer.byteLength(value, "utf8");
+  if (bytes <= state.remainingOpaqueBytes) {
+    state.remainingOpaqueBytes -= bytes;
+    return value;
+  }
+  state.remainingOpaqueBytes = 0;
+  if (kind === "image") {
+    state.opaqueOmissions += 1;
+    return MODEL_TOOL_OUTPUT_OVERSIZED_IMAGE_CARD_DATA_URL;
+  }
+  const marker = `[OpenGeni omitted ${kind} payload: ${bytes} bytes exceeded the bounded model-input allowance]`;
+  state.opaqueOmissions += 1;
+  state.lastOpaqueOmissionMarker = marker;
+  return marker;
+}
+
+function nonTextProtocolKind(value: unknown): OpaqueProtocolKind | null {
+  if (value === "image" || value === "input_image" || value === "computer_screenshot") {
+    return "image";
+  }
+  if (value === "file" || value === "input_file") return "file";
+  if (value === "encrypted_content") return "encrypted";
+  return null;
+}
+
+function opaqueKindForChild(
+  kind: OpaqueProtocolKind | null,
+  key: string,
+): OpaqueProtocolKind | null {
+  if (!kind) return null;
+  const opaqueKeys =
+    kind === "image"
+      ? ["image", "image_url", "imageUrl", "file_id", "fileId", "id", "data", "url", "source"]
+      : kind === "file"
+        ? [
+            "file",
+            "file_data",
+            "fileData",
+            "file_url",
+            "fileUrl",
+            "file_id",
+            "fileId",
+            "id",
+            "data",
+            "url",
+            "content",
+            "source",
+          ]
+        : ["encrypted_content", "content", "data"];
+  return opaqueKeys.includes(key) ? kind : null;
+}
+
+function structuredEntriesOmissionMarker(count: number, container: "array" | "object"): string {
+  return `[OpenGeni omitted ${count} structured ${container === "array" ? "array items" : "object properties"}]`;
+}
+
+function typedProtocolTextMarker(text: string): Record<string, unknown> {
+  return { type: "input_text", text };
+}
+
+function typedStructuredArrayOmissionMarker(count: number): Record<string, unknown> {
+  return typedProtocolTextMarker(structuredEntriesOmissionMarker(count, "array"));
+}
+
+function isTypedStructuralArrayOmissionMarker(value: unknown): boolean {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const record = value as Record<string, unknown>;
+  return (
+    record.type === "input_text" &&
+    typeof record.text === "string" &&
+    STRUCTURAL_ENTRIES_OMISSION_MARKER.test(record.text) &&
+    record.text.includes("structured array items")
+  );
+}
+
+function isGeneratedModelOutputMarker(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    (value === DEPTH_OMISSION_MARKER ||
+      value === CYCLE_OMISSION_MARKER ||
+      value === STRUCTURAL_STRING_OMISSION_MARKER ||
+      TEXT_FIELD_OMISSION_MARKER.test(value) ||
+      TEXT_ITEMS_OMISSION_MARKER.test(value) ||
+      STRUCTURAL_ENTRIES_OMISSION_MARKER.test(value) ||
+      OPAQUE_PAYLOAD_OMISSION_MARKER.test(value))
+  );
+}
+
+function observeGeneratedMarkerBudget(value: string, state: ModelOutputBoundState): void {
+  if (TEXT_FIELD_OMISSION_MARKER.test(value) || TEXT_ITEMS_OMISSION_MARKER.test(value)) {
+    state.remaining = 0;
+  }
+  if (value === STRUCTURAL_STRING_OMISSION_MARKER) state.remainingStructural = 0;
+  if (OPAQUE_PAYLOAD_OMISSION_MARKER.test(value)) state.remainingOpaqueBytes = 0;
+}
+
+function isGeneratedStructuralMarkerProperty(key: string, value: unknown): boolean {
+  return (
+    key.startsWith(STRUCTURAL_PROPERTIES_MARKER_KEY) &&
+    typeof value === "string" &&
+    STRUCTURAL_ENTRIES_OMISSION_MARKER.test(value)
+  );
+}
+
+function uniqueStructuralMarkerKey(record: Record<string, unknown>): string {
+  let key = STRUCTURAL_PROPERTIES_MARKER_KEY;
+  let suffix = 1;
+  while (Object.hasOwn(record, key)) {
+    key = `${STRUCTURAL_PROPERTIES_MARKER_KEY}_${suffix}`;
+    suffix += 1;
+  }
+  return key;
+}
+
+function isResponsesProtocolContentPrefix(output: unknown[]): boolean {
+  if (output.length === 0) return false;
+  const retainedPrefixLength = Math.min(output.length, MODEL_TOOL_OUTPUT_MAX_CONTAINER_ENTRIES);
+  for (let index = 0; index < retainedPrefixLength; index += 1) {
+    const item = output[index];
+    if (!item || typeof item !== "object" || Array.isArray(item)) return false;
+    const record = item as Record<string, unknown>;
+    if (record.type === "input_text" && typeof record.text === "string") continue;
+    if (record.type === "input_image") continue;
+    if (record.type === "input_file") continue;
+    return false;
+  }
+  return true;
+}
+
+function isImageDataUrl(value: string): boolean {
+  return /^data:image\/[a-z0-9.+-]+;base64,/i.test(value);
+}

package/src/oversized-image-card.ts

@@ -0,0 +1,18 @@
+/**
+ * Protocol-valid image shown to the model when an inline tool image exceeds the
+ * hard model-input allowance. The image channel cannot carry a text marker, so
+ * the omission itself is rendered as a legible PNG instead of corrupting the
+ * original base64 or pretending the placeholder is the real screenshot.
+ *
+ * Generated with the dependency-free bitmap/PNG encoder documented in
+ * `scripts/gen-screenshot-error-card.mjs`; the source image is 1,076x284 RGBA
+ * and 5,255 bytes. Rendered text:
+ *
+ *   SCREEN CAPTURE OMITTED
+ *   THE SCREEN CAPTURE IS TOO LARGE.
+ *   THIS IS A PLACEHOLDER, NOT THE REAL SCREEN.
+ *   DO NOT SAY THIS IS THE REAL SCREEN.
+ *   TELL THE USER TO TAKE A SMALLER CAPTURE.
+ */
+export const MODEL_TOOL_OUTPUT_OVERSIZED_IMAGE_CARD_DATA_URL =
+  "data:image/png;base64,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";