@iislee/opencodex 2.11.0

package/src/adapters/identity.ts

@@ -0,0 +1,44 @@
+/**
+ * Central identity neutralization.
+ *
+ * Codex sends the SAME GPT-5 identity line to EVERY model at request time (the per-model catalog
+ * `base_instructions` is ignored on the wire). For routed, non-OpenAI providers that line is both
+ * wrong (the model isn't GPT-5) and a liability: the previous fix replaced it with text that
+ * advertised "...served through / running via the opencodex proxy", which leaked our proxy identity
+ * into the upstream payload — a signature no first-party client (Claude Code, Gemini CLI, Kiro) ever
+ * sends, and a likely ToS trigger.
+ *
+ * The neutral replacement keeps ONLY the necessary instruction (don't misreport as GPT-5/OpenAI)
+ * and names no proxy. Provider-native identity blocks (e.g. the anthropic OAuth "You are a Claude
+ * agent..." prefix) are layered on TOP of this by the individual adapters; this module never claims
+ * to be a specific first-party client.
+ */
+
+/** Historical exact identity line Codex injected for every model. */
+export const CODEX_GPT5_IDENTITY_LINE = "You are Codex, a coding agent based on GPT-5.";
+
+/** Codex CLI 0.145.0+ wording (#622) — still GPT-5 identity, slightly different phrasing. */
+export const CODEX_GPT5_IDENTITY_LINE_AGENT = "You are Codex, an agent based on GPT-5.";
+
+/**
+ * Known Codex GPT-5 identity sentences. Narrow: only "coding agent" / "an agent" + GPT-5(.x)?
+ * Avoid a broad `You are Codex.*` rewrite that could touch unrelated content.
+ */
+const CODEX_GPT5_IDENTITY_RE =
+  /You are Codex, (?:a coding agent|an agent) based on GPT-5(?:\.[0-9]+)*\./g;
+
+/** Proxy-neutral replacement: no "opencodex proxy" mention, just the GPT-5/OpenAI disclaimer. */
+export const NEUTRAL_IDENTITY_LINE = "You are a coding agent. Do not claim to be GPT-5 or to be made by OpenAI.";
+
+/**
+ * Replace Codex's hardcoded GPT-5 identity line with the proxy-neutral line. Safe to call on any
+ * system text: when the line is absent (already neutralized, or a provider that never received it)
+ * the input is returned unchanged. This is the single chokepoint every adapter routes through, so
+ * the leak can't reappear in one adapter while being fixed in another.
+ */
+export function neutralizeIdentity(systemText: string): string {
+  return systemText.replace(CODEX_GPT5_IDENTITY_RE, NEUTRAL_IDENTITY_LINE);
+}
+
+/** The catalog (static, on-disk) replacement for `base_instructions`. Same neutral wording. */
+export const NEUTRAL_IDENTITY_CATALOG = NEUTRAL_IDENTITY_LINE;

package/src/adapters/image.ts

@@ -0,0 +1,23 @@
+import type { OcxContentPart } from "../types";
+
+/**
+ * Parse a `data:<media-type>;base64,<data>` URL into its parts. Codex sends inline images as base64
+ * data URLs (`into_data_url()`), which Anthropic/Google need split into media_type + raw base64.
+ * Returns null for non-data URLs (e.g. a remote https image), which callers pass through differently.
+ */
+export function parseDataUrl(url: string): { mediaType: string; base64: string } | null {
+  const m = url.match(/^data:([^;,]+);base64,(.*)$/s);
+  if (!m) return null;
+  return { mediaType: m[1], base64: m[2] };
+}
+
+/**
+ * Flatten tool-result content to a string for chat/Gemini tool messages (which are text-only). After
+ * the vision sidecar runs, images are already text; this is the fallback for an undescribed image
+ * (vision model via view_image): a short marker, never the token-exploding image_url.
+ */
+export function contentPartsToText(content: string | OcxContentPart[]): string {
+  if (typeof content === "string") return content;
+  const text = content.map(p => (p.type === "text" ? p.text : "[image]")).join("");
+  return text || "[image]";
+}

package/src/adapters/kiro-constants.ts

@@ -0,0 +1,16 @@
+export const KIRO_COMPLETION_TOOL_NAME = "codex_kiro_final_answer";
+export const KIRO_CONTINUATION_MESSAGE =
+  "Continue from the prior conversation. Do not quote or mention this instruction.";
+export const KIRO_COMPLETION_RETRY_MESSAGE =
+  `Continue the existing task without quoting this instruction. If the task is complete, call ${KIRO_COMPLETION_TOOL_NAME} now with the complete final answer. Otherwise issue the next real tool call now. Do not ask the user for another task or emit another progress-only message.`;
+
+export const KIRO_TOOL_RESULT_CARRIER_MESSAGE = "The requested tool result is attached.";
+export const KIRO_EMPTY_TOOL_RESULT_MESSAGE = "The tool completed without textual output.";
+
+export const KIRO_COMPLETION_INSTRUCTIONS =
+  `When tools are available, ordinary assistant text is mid-task commentary and does not end the turn. Continue using tools after progress updates. When the task is fully complete and no more tool calls are needed, call ${KIRO_COMPLETION_TOOL_NAME} exactly once with the complete user-facing final answer in \`answer\`. Do not provide the final answer as ordinary assistant text.`;
+
+export type KiroCompletionMode = "disabled" | "required" | "text_fallback";
+
+/** Bound proxy-authored prompt additions independently of caller-owned instructions/history. */
+export const MAX_KIRO_INJECTED_INSTRUCTION_CHARS = 16_384;

package/src/adapters/kiro-errors.ts

@@ -0,0 +1,197 @@
+import { parseUpstreamJsonPayload, safeUpstreamErrorString, sanitizeUpstreamErrorText } from "./upstream-http-error";
+const DETAIL_KEYS = ["__type", "code", "error", "name", "reason", "message", "Message", "errorMessage"];
+
+export interface KiroErrorClassification {
+  message: string;
+  status: number;
+  errorType: string;
+  code: string;
+  retryable: boolean;
+}
+
+function headerValue(headers: Headers | Record<string, unknown>, name: string): string | undefined {
+  if (headers instanceof Headers) return name.startsWith(":") ? undefined : safeUpstreamErrorString(headers.get(name));
+  return safeUpstreamErrorString(headers[name]) || safeUpstreamErrorString(headers[name.toLowerCase()]);
+}
+
+function payloadDetails(payloadText: string): string[] {
+  const trimmed = payloadText.trim();
+  if (!trimmed) return [];
+  if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) return [trimmed];
+  const parsed = parseUpstreamJsonPayload(trimmed);
+  if (parsed === undefined) return [];
+  if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+    const obj = parsed as Record<string, unknown>;
+    return DETAIL_KEYS.map(key => safeUpstreamErrorString(obj[key])).filter((v): v is string => !!v);
+  }
+  if (typeof parsed === "string" && parsed.trim()) return [parsed.trim()];
+  return [];
+}
+
+function classifyKiroText(status: number | undefined, text: string): string {
+  const lower = text.toLowerCase();
+  const rateQuota = /requests?\s+per\s+(?:min|minute|second)|rpm|tpm/.test(lower);
+  const quotaExhausted =
+    lower.includes("insufficient_quota") ||
+    lower.includes("quota exhausted") ||
+    lower.includes("account quota exceeded") ||
+    lower.includes("monthly quota exceeded") ||
+    lower.includes("daily quota exceeded") ||
+    lower.includes("exceeded your current quota");
+  if (quotaExhausted && !rateQuota) return "Kiro quota exhausted";
+  if (
+    status === 429 ||
+    lower.includes("throttlingexception") ||
+    lower.includes("too many requests") ||
+    lower.includes("rate limited") ||
+    lower.includes("rate limit")
+  ) return "Kiro rate limit exceeded";
+  if (
+    status === 401 ||
+    status === 403 ||
+    lower.includes("accessdenied") ||
+    lower.includes("access denied") ||
+    lower.includes("unauthorized") ||
+    lower.includes("unrecognizedclient") ||
+    lower.includes("expiredtoken") ||
+    lower.includes("expired token") ||
+    lower.includes("invalid token") ||
+    lower.includes("authentication")
+  ) return "Kiro authentication failed";
+  if (
+    status === 503 ||
+    lower.includes("overloaded") ||
+    lower.includes("server is busy") ||
+    lower.includes("temporarily unavailable")
+  ) return "Kiro server overloaded";
+  if (
+    status === 400 ||
+    lower.includes("validationexception") ||
+    lower.includes("invalid request") ||
+    lower.includes("profile arn") ||
+    lower.includes("model unavailable") ||
+    lower.includes("model not found") ||
+    lower.includes("unsupported model") ||
+    lower.includes("region") ||
+    lower.includes("schema") ||
+    lower.includes("malformed")
+  ) return "Kiro invalid request";
+  return "Kiro upstream error";
+}
+
+function normalizedKiroErrorMessage(headers: Headers | Record<string, unknown>, payloadText: string, status?: number): string {
+  const headerType = headerValue(headers, ":exception-type") || headerValue(headers, ":error-type");
+  const parts = [headerType, ...payloadDetails(payloadText)].filter((part): part is string => !!part);
+  const detail = parts.length > 0 ? sanitizeUpstreamErrorText(parts.join(": ")).slice(0, 500) : status ? `HTTP ${status}` : "";
+  const prefix = classifyKiroText(status, [detail, headerType].filter(Boolean).join(" "));
+  return detail ? `${prefix}: ${detail}` : prefix;
+}
+
+function isContentLengthError(text: string): boolean {
+  const lower = text.toLowerCase();
+  return lower.includes("content_length_exceeds_threshold") || lower.includes("content length exceeds");
+}
+
+function classifyKiroFailure(
+  headers: Headers | Record<string, unknown>,
+  payloadText: string,
+  status?: number,
+): KiroErrorClassification {
+  const message = normalizedKiroErrorMessage(headers, payloadText, status);
+  const headerType = headerValue(headers, ":exception-type") || headerValue(headers, ":error-type") || "";
+  const evidence = [headerType, ...payloadDetails(payloadText), message].join(" ").toLowerCase();
+  if (isContentLengthError(evidence)) {
+    return {
+      message: "Kiro rejected the request because the conversation exceeds the model's context window. Compact or reduce the history, or start a new session.",
+      status: 400,
+      errorType: "invalid_request_error",
+      code: "context_length_exceeded",
+      retryable: false,
+    };
+  }
+  if (
+    evidence.includes("insufficient_quota")
+    || evidence.includes("quota exhausted")
+    || evidence.includes("quota exceeded")
+  ) {
+    return { message, status: 429, errorType: "insufficient_quota", code: "insufficient_quota", retryable: false };
+  }
+  if (
+    status === 429
+    || evidence.includes("throttlingexception")
+    || evidence.includes("too many requests")
+    || evidence.includes("rate limit")
+  ) {
+    return { message, status: 429, errorType: "rate_limit_error", code: "rate_limit_exceeded", retryable: true };
+  }
+  if (
+    status === 401
+    || status === 403
+    || evidence.includes("accessdenied")
+    || evidence.includes("unauthorized")
+    || evidence.includes("unrecognizedclient")
+    || evidence.includes("expiredtoken")
+    || evidence.includes("expired token")
+    || evidence.includes("invalid token")
+    || evidence.includes("authentication")
+  ) {
+    return { message, status: status === 403 ? 403 : 401, errorType: status === 403 ? "permission_error" : "authentication_error", code: status === 403 ? "permission_denied" : "invalid_api_key", retryable: false };
+  }
+  if (
+    status === 400
+    || evidence.includes("validationexception")
+    || evidence.includes("invalid request")
+    || evidence.includes("model unavailable")
+    || evidence.includes("model not found")
+    || evidence.includes("unsupported model")
+    || evidence.includes("profile arn")
+    || evidence.includes("malformed")
+  ) {
+    return { message, status: 400, errorType: "invalid_request_error", code: "invalid_request_error", retryable: false };
+  }
+  if (
+    status === 503
+    || evidence.includes("overloaded")
+    || evidence.includes("server is busy")
+    || evidence.includes("temporarily unavailable")
+  ) {
+    return { message, status: 503, errorType: "server_error", code: "server_is_overloaded", retryable: true };
+  }
+  return {
+    message,
+    status: status && status >= 500 ? status : 502,
+    errorType: "server_error",
+    code: "upstream_server_error",
+    retryable: true,
+  };
+}
+
+export function safeKiroErrorMessage(headers: Record<string, unknown>, payloadText: string): string {
+  return normalizedKiroErrorMessage(headers, payloadText);
+}
+
+export function classifyKiroStreamError(
+  headers: Record<string, unknown>,
+  payloadText: string,
+): KiroErrorClassification {
+  return classifyKiroFailure(headers, payloadText);
+}
+
+export function classifyKiroHttpError(
+  status: number,
+  headers: Headers | Record<string, unknown>,
+  payloadText: string,
+): KiroErrorClassification {
+  return classifyKiroFailure(headers, payloadText, status);
+}
+
+export function classifyKiroEventError(reason: string | undefined, message: string | undefined): KiroErrorClassification {
+  const safeReason = reason ? sanitizeUpstreamErrorText(reason).slice(0, 160) : "";
+  const safeMessage = message ? sanitizeUpstreamErrorText(message).slice(0, 500) : "Kiro request failed";
+  const payload = JSON.stringify({ reason: safeReason, message: safeMessage });
+  return classifyKiroFailure({}, payload);
+}
+
+export function safeKiroHttpErrorMessage(status: number, headers: Headers | Record<string, unknown>, payloadText: string): string {
+  return classifyKiroFailure(headers, payloadText, status).message;
+}

package/src/adapters/kiro-events.ts

@@ -0,0 +1,179 @@
+import type { OcxUsage } from "../types";
+import { kiroTruncationReason } from "./kiro-truncation";
+
+export type ParsedKiroEvent =
+  | { type: "content"; data?: string; modelId?: string }
+  | { type: "reasoning"; data?: string }
+  | { type: "tool"; name?: string; toolUseId?: string; input?: string; stop?: boolean }
+  | { type: "truncation"; data: string }
+  | { type: "metadata"; usage?: OcxUsage; contextUsagePercentage?: number; stopReason?: string }
+  | { type: "message_metadata"; conversationId?: string }
+  | { type: "invalid_state"; message?: string }
+  | { type: "error"; reason?: string; message?: string };
+
+const KNOWN_EVENT_TYPES = new Set([
+  "assistantResponseEvent",
+  "reasoningContentEvent",
+  "toolUseEvent",
+  "messageMetadataEvent",
+  "metadataEvent",
+  "invalidStateEvent",
+  "error",
+]);
+
+function malformed(eventType: string, detail: string): never {
+  throw new Error(`invalid Kiro ${eventType} payload: ${detail}`);
+}
+
+function parseObject(eventType: string, payload: Uint8Array): Record<string, unknown> {
+  let value: unknown;
+  try {
+    value = JSON.parse(new TextDecoder().decode(payload));
+  } catch {
+    return malformed(eventType, "expected valid JSON");
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return malformed(eventType, "expected an object");
+  }
+  return value as Record<string, unknown>;
+}
+
+function optionalString(eventType: string, obj: Record<string, unknown>, key: string): string | undefined {
+  const value = obj[key];
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "string") return malformed(eventType, `${key} must be a string`);
+  return value;
+}
+
+function optionalBoolean(eventType: string, obj: Record<string, unknown>, key: string): boolean | undefined {
+  const value = obj[key];
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "boolean") return malformed(eventType, `${key} must be a boolean`);
+  return value;
+}
+
+function tokenCount(eventType: string, obj: Record<string, unknown>, key: string, required: boolean): number {
+  const value = obj[key];
+  if (value === undefined && !required) return 0;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+    return malformed(eventType, `${key} must be a non-negative safe integer`);
+  }
+  return value;
+}
+
+function parseTokenUsage(eventType: string, value: unknown): OcxUsage | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "object" || Array.isArray(value)) {
+    return malformed(eventType, "tokenUsage must be an object");
+  }
+  const usage = value as Record<string, unknown>;
+  const uncached = tokenCount(eventType, usage, "uncachedInputTokens", true);
+  const cacheRead = tokenCount(eventType, usage, "cacheReadInputTokens", false);
+  const cacheWrite = tokenCount(eventType, usage, "cacheWriteInputTokens", false);
+  const outputTokens = tokenCount(eventType, usage, "outputTokens", true);
+  const totalTokens = tokenCount(eventType, usage, "totalTokens", true);
+  const inputTokens = uncached + cacheRead + cacheWrite;
+  if (!Number.isSafeInteger(inputTokens)) return malformed(eventType, "input token usage overflowed");
+  return {
+    inputTokens,
+    outputTokens,
+    totalTokens,
+    cachedInputTokens: cacheRead,
+    cacheReadInputTokens: cacheRead,
+    cacheCreationInputTokens: cacheWrite,
+  };
+}
+
+/** Decode a known Kiro event using its Smithy `:event-type` header. */
+export function parseKiroEvent(eventType: string, payload: Uint8Array): ParsedKiroEvent | null {
+  // Unknown event types are intentionally ignored without parsing or logging their payload.
+  if (!KNOWN_EVENT_TYPES.has(eventType)) return null;
+  const parsed = parseObject(eventType, payload);
+  // A metadataEvent's `stopReason` is Kiro's own terminal verdict and must reach the parser
+  // intact. The generic truncation sniffer matches substrings ("max_tokens", "length",
+  // "context_length") across several keys, so it would swallow MAX_TOKENS before the switch
+  // below ever runs. Gate on position rather than on the value: a value allowlist would keep
+  // eating future reasons such as LENGTH_LIMIT, which matches the pattern today.
+  const nativeStopReason = eventType === "metadataEvent"
+    ? optionalString(eventType, parsed, "stopReason")
+    : undefined;
+  if (nativeStopReason === undefined) {
+    const truncationReason = kiroTruncationReason(parsed);
+    if (truncationReason) return { type: "truncation", data: truncationReason };
+  }
+
+  switch (eventType) {
+    case "assistantResponseEvent":
+      return {
+        type: "content",
+        ...(optionalString(eventType, parsed, "content") !== undefined
+          ? { data: optionalString(eventType, parsed, "content") }
+          : {}),
+        ...(optionalString(eventType, parsed, "modelId") !== undefined
+          ? { modelId: optionalString(eventType, parsed, "modelId") }
+          : {}),
+      };
+    case "reasoningContentEvent":
+      return {
+        type: "reasoning",
+        ...(optionalString(eventType, parsed, "text") !== undefined
+          ? { data: optionalString(eventType, parsed, "text") }
+          : {}),
+      };
+    case "toolUseEvent":
+      return {
+        type: "tool",
+        ...(optionalString(eventType, parsed, "name") !== undefined
+          ? { name: optionalString(eventType, parsed, "name") }
+          : {}),
+        ...(optionalString(eventType, parsed, "toolUseId") !== undefined
+          ? { toolUseId: optionalString(eventType, parsed, "toolUseId") }
+          : {}),
+        ...(optionalString(eventType, parsed, "input") !== undefined
+          ? { input: optionalString(eventType, parsed, "input") }
+          : {}),
+        ...(optionalBoolean(eventType, parsed, "stop") !== undefined
+          ? { stop: optionalBoolean(eventType, parsed, "stop") }
+          : {}),
+      };
+    case "messageMetadataEvent":
+      return {
+        type: "message_metadata",
+        conversationId:
+          optionalString(eventType, parsed, "conversationId")
+          ?? optionalString(eventType, parsed, "utteranceId"),
+      };
+    case "metadataEvent": {
+      const contextUsagePercentage = parsed.contextUsagePercentage;
+      if (
+        contextUsagePercentage !== undefined
+        && (typeof contextUsagePercentage !== "number" || !Number.isFinite(contextUsagePercentage))
+      ) {
+        return malformed(eventType, "contextUsagePercentage must be a finite number");
+      }
+      const stopReason = optionalString(eventType, parsed, "stopReason");
+      return {
+        type: "metadata",
+        ...(parseTokenUsage(eventType, parsed.tokenUsage) !== undefined
+          ? { usage: parseTokenUsage(eventType, parsed.tokenUsage) }
+          : {}),
+        ...(typeof contextUsagePercentage === "number" ? { contextUsagePercentage } : {}),
+        ...(stopReason !== undefined ? { stopReason } : {}),
+      };
+    }
+    case "invalidStateEvent":
+      return { type: "invalid_state", message: optionalString(eventType, parsed, "message") };
+    case "error":
+      return {
+        type: "error",
+        reason:
+          optionalString(eventType, parsed, "reason")
+          ?? optionalString(eventType, parsed, "type")
+          ?? optionalString(eventType, parsed, "__type"),
+        message:
+          optionalString(eventType, parsed, "message")
+          ?? optionalString(eventType, parsed, "Message"),
+      };
+  }
+  return null;
+}

package/src/adapters/kiro-images.ts

@@ -0,0 +1,129 @@
+import type { OcxContentPart } from "../types";
+import { normalizeImageTargets, type NormalizeOptions, type NormalizeTarget } from "./anthropic-image-normalize";
+
+// CodeWhisperer native image part (matches Kiro IDE wire format): the base64 bytes live directly in
+// userInputMessage.images, NOT in userInputMessageContext. Verified against kiro-gateway.
+export interface KiroImage {
+  format: string; // "jpeg" | "png" | "webp" | "gif" — derived from the media subtype
+  source: { bytes: string }; // pure base64, no "data:...;base64," prefix
+}
+
+// Codex sends each image as a `data:` URL (base64) or a remote https URL. Only data URLs can be
+// inlined as bytes here; remote URLs are not fetchable at request-build time.
+function parseDataUrlImage(imageUrl: string): KiroImage | undefined {
+  if (!imageUrl.startsWith("data:")) return undefined;
+  const comma = imageUrl.indexOf(",");
+  if (comma === -1) return undefined;
+  const header = imageUrl.slice(5, comma);
+  const bytes = imageUrl.slice(comma + 1);
+  if (!bytes) return undefined;
+  const mediaType = header.split(";")[0] || "image/jpeg";
+  const subtype = (mediaType.includes("/") ? mediaType.split("/")[1] : mediaType) || "jpeg";
+  // CodeWhisperer/Bedrock expects "jpeg", not the "jpg" alias.
+  const format = subtype.toLowerCase() === "jpg" ? "jpeg" : subtype.toLowerCase();
+  return { format, source: { bytes } };
+}
+
+export function extractKiroImages(content: string | OcxContentPart[]): KiroImage[] {
+  if (typeof content === "string") return [];
+  const out: KiroImage[] = [];
+  for (const p of content) {
+    if (p.type !== "image") continue;
+    const img = parseDataUrlImage(p.imageUrl);
+    if (img) out.push(img);
+  }
+  return out;
+}
+
+/**
+ * Conservative POLICY caps for the CodeWhisperer GenerateAssistantResponse payload,
+ * whose limits are undocumented. Derived from adjacent AWS surfaces
+ * (devlog/260714_image_normalization_pipeline/050): Bedrock `Message` allows 20 images
+ * per message (Converse), and `InvokeModel` caps requests at 25,000,000 bytes — 18MiB
+ * bounds the IMAGE share of the body with headroom for text/tools.
+ */
+export const KIRO_IMAGE_BASE64_BUDGET = 18 * 1024 * 1024;
+export const KIRO_MAX_IMAGES_PER_MESSAGE = 20;
+
+const COUNT_CAP_NOTE = "[image omitted: exceeded the 20-image per-message cap; oldest images in this message were dropped]";
+
+/** A kiro wire message that can carry images (history userInputMessage or currentMessage). */
+interface KiroImageCarrier {
+  content?: string;
+  images?: KiroImage[];
+}
+
+function isCarrier(v: unknown): v is KiroImageCarrier {
+  return typeof v === "object" && v !== null;
+}
+
+/** Collect image-bearing userInputMessages in wire order (history oldest-first, then current). */
+function collectKiroImageCarriers(payload: unknown): KiroImageCarrier[] {
+  const state = (payload as { conversationState?: { history?: unknown[]; currentMessage?: { userInputMessage?: unknown } } })?.conversationState;
+  if (!state) return [];
+  const carriers: KiroImageCarrier[] = [];
+  for (const entry of state.history ?? []) {
+    const uim = (entry as { userInputMessage?: unknown })?.userInputMessage;
+    if (isCarrier(uim)) carriers.push(uim);
+  }
+  const current = state.currentMessage?.userInputMessage;
+  if (isCarrier(current)) carriers.push(current);
+  return carriers;
+}
+
+function appendNote(carrier: KiroImageCarrier, note: string): void {
+  carrier.content = carrier.content ? `${carrier.content}\n${note}` : note;
+}
+
+/**
+ * Apply the generous image pipeline to a built CodeWhisperer payload (mutates in
+ * place): per-message 20-image cap first (oldest dropped), then the shared tier
+ * machinery with the kiro budget and terminal-overflow DROP (kiro has no downstream
+ * guard). Test seams (encode/validate) forward into the core.
+ */
+export async function normalizeKiroImages(
+  payload: unknown,
+  opts?: Pick<NormalizeOptions, "encode" | "validate">,
+): Promise<void> {
+  const carriers = collectKiroImageCarriers(payload);
+  if (carriers.length === 0) return;
+
+  // Pre-pass: per-message count cap (drop oldest within the message).
+  for (const carrier of carriers) {
+    const images = carrier.images;
+    if (!images || images.length <= KIRO_MAX_IMAGES_PER_MESSAGE) continue;
+    images.splice(0, images.length - KIRO_MAX_IMAGES_PER_MESSAGE);
+    appendNote(carrier, COUNT_CAP_NOTE);
+  }
+
+  // Targets over the survivors, oldest→newest across carriers. Drops resolve the image
+  // by OBJECT IDENTITY at execution time (indices go stale after earlier splices) and
+  // delete an emptied images field per the builder's omission contract.
+  const targets: NormalizeTarget[] = [];
+  for (const carrier of carriers) {
+    for (const img of carrier.images ?? []) {
+      targets.push({
+        base64: typeof img.source?.bytes === "string" && img.source.bytes.length > 0 ? img.source.bytes : null,
+        mediaType: `image/${(img.format || "jpeg").toLowerCase()}`,
+        replace: (data: string, mediaType: string) => {
+          img.source.bytes = data;
+          img.format = (mediaType.split("/")[1] ?? "jpeg").toLowerCase();
+        },
+        drop: (note: string) => {
+          const arr = carrier.images;
+          if (arr) {
+            const idx = arr.indexOf(img);
+            if (idx !== -1) arr.splice(idx, 1);
+            if (arr.length === 0) delete carrier.images;
+          }
+          appendNote(carrier, note);
+        },
+      });
+    }
+  }
+  await normalizeImageTargets(targets, {
+    budget: KIRO_IMAGE_BASE64_BUDGET,
+    overflowAction: "drop",
+    ...(opts ?? {}),
+  });
+}