@bitkyc08/opencodex 2.7.33 → 2.7.34

package/src/server/management-api.ts

@@ -1,12 +1,13 @@
 import { randomUUID } from "node:crypto";
 import { readFileSync } from "node:fs";
 import type { CatalogModel } from "../codex/catalog";
-import { invalidateCodexModelsCache, nativeModelRows } from "../codex/catalog";
+import { catalogModelSlug, invalidateCodexModelsCache, nativeModelRows, uniqueCatalogModelsForPublicList } from "../codex/catalog";
 import {
   DEFAULT_SUBAGENT_MODELS,
   codexAutoStartEnabled,
   hasOwnProvider,
   isValidProviderName,
+  multiAgentGuidanceEnabled,
   providerBaseUrlConfigError,
   providerHeadersConfigError,
   saveConfig,
@@ -813,21 +814,29 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
         ...(cm.inputModalities ? { inputModalities: cm.inputModalities } : {}),
       };
     });
-    // Custom metadata wins when a live/static routed row resolves to the same Codex-facing slug.
-    const customNamespaced = new Set(customModels.map(c => c.namespaced));
-    const dedupedRouted = models.map(m => {
+    const publicModels = uniqueCatalogModelsForPublicList(models);
+    const comboNamespaced = new Set(
+      publicModels.filter(model => model.provider === "combo").map(catalogModelSlug),
+    );
+    const visibleCustomModels = customModels.filter(model => !comboNamespaced.has(model.namespaced));
+    // Custom metadata wins when a physical live/static row resolves to the same Codex-facing
+    // slug, while a combo keeps the same precedence it has in routing and /v1/models.
+    const customNamespaced = new Set(visibleCustomModels.map(c => c.namespaced));
+    const dedupedRouted = publicModels.map(m => {
       // Codex-facing slug (one "/", slug-codec); disabledModels compares tolerate both forms.
-      const namespaced = routedSlug(m.provider, m.id);
-      if (customNamespaced.has(namespaced)) return null;
+      const namespaced = catalogModelSlug(m);
+      if (m.provider !== "combo" && customNamespaced.has(namespaced)) return null;
       const contextCap = providerContextCap(config, m.provider);
       return {
         ...m,
         namespaced,
-        disabled: [...disabled].some(stored => slugEquals(stored, m.provider, m.id)),
+        disabled: [...disabled].some(stored => (
+          stored === namespaced || slugEquals(stored, m.provider, m.id)
+        )),
         ...(contextCap !== undefined ? { contextCap, contextCapped: m.contextCapped === true } : {}),
       };
     }).filter(Boolean);
-    return jsonResponse([...native, ...dedupedRouted, ...customModels]);
+    return jsonResponse([...native, ...dedupedRouted, ...visibleCustomModels]);
   }
 
   if (url.pathname === "/api/provider-context-caps" && req.method === "GET") {
@@ -1091,10 +1100,13 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
     const nativeModels = listCatalogNativeSlugs()
       .filter(slug => !disabled.has(slug))
       .map(slug => ({ provider: "openai", model: slug, namespaced: slug }));
-    const routedModels = models
-      .map(m => ({ provider: m.provider, model: m.id, namespaced: routedSlug(m.provider, m.id) }))
-      .filter(m => ![...disabled].some(stored => slugEquals(stored, m.provider, m.model)));
+    const routedModels = uniqueCatalogModelsForPublicList(models)
+      .map(m => ({ provider: m.provider, model: m.id, namespaced: catalogModelSlug(m) }))
+      .filter(m => ![...disabled].some(stored => (
+        stored === m.namespaced || slugEquals(stored, m.provider, m.model)
+      )));
     return jsonResponse({
+      multiAgentGuidanceEnabled: multiAgentGuidanceEnabled(config),
       model: config.injectionModel ?? null,
       effort: config.injectionEffort ?? null,
       prompt: config.injectionPrompt ?? null,
@@ -1103,34 +1115,69 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
     });
   }
   if (url.pathname === "/api/injection-model" && req.method === "PUT") {
-    let body: { model?: unknown; effort?: unknown; prompt?: unknown };
-    try { body = await req.json(); } catch { return jsonResponse({ error: "invalid JSON body" }, 400); }
+    let parsedBody: unknown;
+    try { parsedBody = await req.json(); } catch {
+      return jsonResponse({ error: "invalid JSON body" }, 400);
+    }
+    if (!parsedBody || typeof parsedBody !== "object" || Array.isArray(parsedBody)) {
+      return jsonResponse({ error: "body must be a JSON object" }, 400);
+    }
+    const body = parsedBody as {
+      multiAgentGuidanceEnabled?: unknown;
+      model?: unknown;
+      effort?: unknown;
+      prompt?: unknown;
+    };
     const { isCodexReasoningEffort } = await import("../reasoning-effort");
-    const model = typeof body.model === "string" && body.model.length > 0 ? body.model : undefined;
-    let effort = config.injectionEffort;
-    // `effort` key semantics: absent -> unchanged; null/"" -> clear; ladder value -> set;
-    // anything else -> 400. Clearing the model always clears the effort (it is meaningless alone).
+
+    let nextEnabled = config.multiAgentGuidanceEnabled;
+    let nextModel = config.injectionModel;
+    let nextEffort = config.injectionEffort;
+    let nextPrompt = config.injectionPrompt;
+
+    if ("multiAgentGuidanceEnabled" in body) {
+      if (typeof body.multiAgentGuidanceEnabled !== "boolean") {
+        return jsonResponse({ error: "multiAgentGuidanceEnabled must be a boolean" }, 400);
+      }
+      nextEnabled = body.multiAgentGuidanceEnabled;
+    }
+    if ("model" in body) {
+      if (body.model === null || body.model === "") nextModel = undefined;
+      else if (typeof body.model === "string" && body.model.length > 0) nextModel = body.model;
+      else return jsonResponse({ error: "model must be a non-empty string or null" }, 400);
+    }
     if ("effort" in body) {
-      const requestedEffort = typeof body.effort === "string" && body.effort.length > 0 ? body.effort : undefined;
-      if (requestedEffort !== undefined && !isCodexReasoningEffort(requestedEffort)) {
-        return jsonResponse({ error: `unknown reasoning effort "${requestedEffort}"` }, 400);
+      if (body.effort === null || body.effort === "") nextEffort = undefined;
+      else if (typeof body.effort === "string" && isCodexReasoningEffort(body.effort)) {
+        nextEffort = body.effort;
+      } else {
+        return jsonResponse({ error: `unknown reasoning effort "${String(body.effort)}"` }, 400);
       }
-      effort = requestedEffort;
     }
-    if (!model) effort = undefined;
-    if (model) config.injectionModel = model;
-    else delete config.injectionModel;
-    if (effort) config.injectionEffort = effort;
-    else delete config.injectionEffort;
-    // `prompt` key semantics mirror `effort`: absent -> unchanged; null/"" -> clear;
-    // non-empty string -> set (custom <multi_agent_mode> body, {{model}}/{{effort}}/{{roster}} placeholders).
     if ("prompt" in body) {
-      if (typeof body.prompt === "string" && body.prompt.trim().length > 0) config.injectionPrompt = body.prompt;
-      else if (body.prompt === null || body.prompt === "") delete config.injectionPrompt;
+      if (typeof body.prompt === "string" && body.prompt.trim().length > 0) nextPrompt = body.prompt;
+      else if (body.prompt === null || body.prompt === "") nextPrompt = undefined;
       else return jsonResponse({ error: "prompt must be a string or null" }, 400);
     }
+    // Clearing the model always clears the effort (it is meaningless alone).
+    if (!nextModel) nextEffort = undefined;
+
+    config.multiAgentGuidanceEnabled = nextEnabled;
+    if (nextModel) config.injectionModel = nextModel;
+    else delete config.injectionModel;
+    if (nextEffort) config.injectionEffort = nextEffort;
+    else delete config.injectionEffort;
+    if (nextPrompt) config.injectionPrompt = nextPrompt;
+    else delete config.injectionPrompt;
+
     saveConfig(config);
-    return jsonResponse({ ok: true, model: config.injectionModel ?? null, effort: config.injectionEffort ?? null, prompt: config.injectionPrompt ?? null });
+    return jsonResponse({
+      ok: true,
+      multiAgentGuidanceEnabled: multiAgentGuidanceEnabled(config),
+      model: config.injectionModel ?? null,
+      effort: config.injectionEffort ?? null,
+      prompt: config.injectionPrompt ?? null,
+    });
   }
 
   // Hard reasoning-effort caps (devlog/260710_subagent_effort_intercept): a global ceiling and a
@@ -1169,9 +1216,11 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
     // Native gpt (passthrough) are also valid subagent picks — they're picker-visible models in the
     // catalog, just buried by priority. List them first so the user can feature them over routed.
     const { listCatalogNativeSlugs } = await import("../codex/catalog");
-    const visibleRouted = models
-      .filter(m => ![...disabled].some(stored => slugEquals(stored, m.provider, m.id)))
-      .map(m => routedSlug(m.provider, m.id));
+    const visibleRouted = [...new Set(models
+      .filter(m => ![...disabled].some(stored =>
+        stored === catalogModelSlug(m) || slugEquals(stored, m.provider, m.id)
+      ))
+      .map(catalogModelSlug))];
     const available = [
       ...listCatalogNativeSlugs().filter(ns => !disabled.has(ns)),
       ...visibleRouted,
@@ -1229,6 +1278,7 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
       tierModels: config.claudeCode?.tierModels ?? {},
       modelMap: config.claudeCode?.modelMap ?? {},
       systemEnv: config.claudeCode?.systemEnv === true,
+      autoConnectSupported: process.platform === "darwin",
       maxContextTokens: config.claudeCode?.maxContextTokens ?? null,
       alwaysEnableEffort: config.claudeCode?.alwaysEnableEffort === true,
       autoContext: config.claudeCode?.autoContext !== false,
@@ -1692,12 +1742,15 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
   }
 
   if (url.pathname === "/api/combos" && req.method === "GET") {
-    const { comboModelId, getCombo, listComboIds } = await import("../combos");
-    return jsonResponse({ combos: listComboIds(config).map(id => ({
-      id,
-      model: comboModelId(id),
-      ...getCombo(config, id)!,
-    })) });
+    const { comboPublicModelId, getCombo, listComboIds } = await import("../combos");
+    return jsonResponse({ combos: listComboIds(config).map(id => {
+      const combo = getCombo(config, id)!;
+      return {
+        id,
+        model: comboPublicModelId(id, combo),
+        ...combo,
+      };
+    }) });
   }
 
   if (url.pathname === "/api/combos" && req.method === "PUT") {
@@ -1711,18 +1764,109 @@ export async function handleManagementAPI(req: Request, url: URL, config: OcxCon
       return jsonResponse({ error: "id is required and must be a string" }, 400);
     }
     const id = body.id.trim();
-    const { comboConfigError, normalizeComboConfig, comboModelId, clearComboSelectionState, clearComboTargetCooldowns } = await import("../combos");
+    let renameFrom: string | undefined;
+    if (body.renameFrom !== undefined) {
+      if (typeof body.renameFrom !== "string" || !body.renameFrom.trim()) {
+        return jsonResponse({ error: "renameFrom must be a non-empty string" }, 400);
+      }
+      renameFrom = body.renameFrom.trim();
+      if (renameFrom === id) {
+        return jsonResponse({ error: "renameFrom must differ from id" }, 400);
+      }
+      if (!Object.hasOwn(config.combos ?? {}, renameFrom)) {
+        return jsonResponse({ error: `combo "${renameFrom}" does not exist` }, 400);
+      }
+      if (Object.hasOwn(config.combos ?? {}, id)) {
+        return jsonResponse({ error: `combo "${id}" already exists` }, 400);
+      }
+    }
+    const {
+      clearComboSelectionState,
+      clearComboTargetCooldowns,
+      comboConfigError,
+      comboModelId,
+      comboPublicModelId,
+      normalizeComboConfig,
+    } = await import("../combos");
     const error = comboConfigError(id, body.combo, config.providers, {
       requireEnabledTarget: true,
+      combos: config.combos,
+      excludeComboId: renameFrom ?? id,
     });
     if (error) return jsonResponse({ error }, 400);
     const normalized = normalizeComboConfig(body.combo as import("../types").OcxComboConfig);
-    config.combos = { ...(config.combos ?? {}), [id]: normalized };
+    const stored: import("../types").OcxComboConfig = normalized.alias === null
+      ? (({ alias: _alias, ...rest }) => rest)(normalized)
+      : normalized;
+    const sourceId = renameFrom ?? id;
+    const previous = config.combos?.[sourceId];
+    const oldPublicModel = previous ? comboPublicModelId(sourceId, previous) : null;
+    const newPublicModel = comboPublicModelId(id, normalized);
+    const nextCombos = { ...(config.combos ?? {}) };
+    if (renameFrom) delete nextCombos[renameFrom];
+    nextCombos[id] = stored;
+    config.combos = nextCombos;
+    let shouldSyncClaudeAgentDefs = false;
+    const migratedModels = new Set<string>();
+    if (oldPublicModel && oldPublicModel !== newPublicModel) {
+      migratedModels.add(oldPublicModel);
+    }
+    if (renameFrom) migratedModels.add(comboModelId(renameFrom));
+    if (migratedModels.size > 0) {
+      const migrateReference = (model: string): string => (
+        migratedModels.has(model) ? newPublicModel : model
+      );
+      const migrateAgentReference = (model: string): string => {
+        const migrated = migrateReference(model);
+        if (migrated !== model) shouldSyncClaudeAgentDefs = true;
+        return migrated;
+      };
+      const migrateReferences = (models: string[]): string[] => [
+        ...new Set(models.map(migrateReference)),
+      ];
+      if (config.disabledModels) {
+        config.disabledModels = migrateReferences(config.disabledModels);
+      }
+      if (config.subagentModels) {
+        config.subagentModels = [...new Set(config.subagentModels.map(migrateAgentReference))];
+      }
+      if (config.injectionModel && migratedModels.has(config.injectionModel)) {
+        config.injectionModel = newPublicModel;
+      }
+      if (config.shadowCallIntercept?.model && migratedModels.has(config.shadowCallIntercept.model)) {
+        config.shadowCallIntercept = {
+          ...config.shadowCallIntercept,
+          model: newPublicModel,
+        };
+      }
+      if (config.claudeCode) {
+        const claudeCode = { ...config.claudeCode };
+        for (const field of ["model", "smallFastModel"] as const) {
+          if (claudeCode[field]) claudeCode[field] = migrateAgentReference(claudeCode[field]);
+        }
+        if (claudeCode.tierModels) {
+          claudeCode.tierModels = Object.fromEntries(
+            Object.entries(claudeCode.tierModels).map(([tier, model]) => [tier, migrateAgentReference(model)]),
+          );
+        }
+        if (claudeCode.modelMap) {
+          claudeCode.modelMap = Object.fromEntries(
+            Object.entries(claudeCode.modelMap).map(([source, model]) => [source, migrateAgentReference(model)]),
+          );
+        }
+        config.claudeCode = claudeCode;
+      }
+    }
     saveConfig(config);
     clearComboSelectionState(id);
     clearComboTargetCooldowns(id);
+    if (renameFrom) {
+      clearComboSelectionState(renameFrom);
+      clearComboTargetCooldowns(renameFrom);
+    }
     await refreshCodexCatalogBestEffort();
-    return jsonResponse({ success: true, id, model: comboModelId(id), combo: normalized });
+    if (shouldSyncClaudeAgentDefs) await syncClaudeAgentDefsBestEffort();
+    return jsonResponse({ success: true, id, model: newPublicModel, combo: normalized });
   }
 
   if (url.pathname === "/api/combos" && req.method === "DELETE") {

package/src/server/ports.ts

@@ -73,14 +73,16 @@ export async function findAvailablePort(
 ): Promise<number> {
   const preferRetryMs = opts.preferRetryMs ?? 0;
   const allowEphemeral = opts.allowEphemeralFallback !== false;
-  if (preferRetryMs > 0) {
+  // Port 0 asks the OS to select an ephemeral port. Resolve it to that concrete
+  // port here so callers never persist or advertise an unusable `:0` endpoint.
+  if (preferredPort > 0 && preferRetryMs > 0) {
     if (await waitForPortAvailable(preferredPort, hostname, {
       timeoutMs: preferRetryMs,
       intervalMs: opts.preferRetryIntervalMs ?? 50,
     })) {
       return preferredPort;
     }
-  } else if (await isPortAvailable(preferredPort, hostname)) {
+  } else if (preferredPort > 0 && (await isPortAvailable(preferredPort, hostname))) {
     return preferredPort;
   }
 

package/src/server/request-log.ts

@@ -35,6 +35,8 @@ export interface RequestLogContext {
   firstOutputMs?: number;
   surface?: "claude";
   requestedModel?: string;
+  /** Internal structural combo identity; omitted from RequestLogEntry/JSONL. */
+  comboId?: string;
   requestedEffort?: string;
   requestedServiceTier?: string;
   requestedSpeedLabel?: string;
@@ -564,8 +566,7 @@ export function addFinalRequestLog(
     recoveryKinds: [...attempt.recoveryKinds],
     ...(attempt.usage ? { usage: { ...attempt.usage } } : {}),
   }));
-  const isCombo = (logCtx.requestedModel ?? "").startsWith("combo/")
-    && (attempts?.length ?? 0) > 0;
+  const isCombo = logCtx.comboId !== undefined && (attempts?.length ?? 0) > 0;
   const aggregate = isCombo ? aggregateAttemptUsage(attempts ?? []) : null;
   const loggedUsage = aggregate?.usage ?? existing.usage;
   const usageStatus = aggregate?.status ?? existing.status;

package/src/server/responses-item-id-repair.ts

@@ -0,0 +1,281 @@
+import { randomUUID } from "node:crypto";
+import type { ResponsesItemIdRepairConfig } from "../types";
+
+type RepairableItemType = "message" | "reasoning";
+
+interface ResponsesItemIdRepairState {
+  readonly repairMissingTerminalIds: boolean;
+  readonly placeholders: Record<RepairableItemType, ReadonlySet<string>>;
+  readonly outputIds: Record<RepairableItemType, Map<number, string>>;
+  readonly scope: string;
+}
+
+const REPAIRABLE_PREFIXES: Record<RepairableItemType, string> = {
+  message: "msg_",
+  reasoning: "rs_",
+};
+
+const ITEM_ID_EVENT_TYPES: Readonly<Record<string, RepairableItemType>> = {
+  "response.content_part.added": "message",
+  "response.content_part.done": "message",
+  "response.output_text.annotation.added": "message",
+  "response.output_text.delta": "message",
+  "response.output_text.done": "message",
+  "response.refusal.delta": "message",
+  "response.refusal.done": "message",
+  "response.reasoning_summary_part.added": "reasoning",
+  "response.reasoning_summary_part.done": "reasoning",
+  "response.reasoning_summary_text.delta": "reasoning",
+  "response.reasoning_summary_text.done": "reasoning",
+  "response.reasoning_text.delta": "reasoning",
+  "response.reasoning_text.done": "reasoning",
+};
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function nextSseBlock(buffer: string): { block: string; delimiter: string; rest: string } | null {
+  const match = buffer.match(/\r?\n\r?\n/);
+  if (!match || match.index === undefined) return null;
+  return {
+    block: buffer.slice(0, match.index),
+    delimiter: match[0],
+    rest: buffer.slice(match.index + match[0].length),
+  };
+}
+
+function sseDataPayload(block: string): string | null {
+  const data: string[] = [];
+  for (const line of block.split(/\r?\n/)) {
+    if (!line.startsWith("data:")) continue;
+    const value = line.slice(5);
+    data.push(value.startsWith(" ") ? value.slice(1) : value);
+  }
+  return data.length > 0 ? data.join("\n") : null;
+}
+
+function replaceSseDataPayload(block: string, payload: string): string {
+  const newline = block.includes("\r\n") ? "\r\n" : "\n";
+  const lines = block.split(/\r?\n/);
+  const rewritten: string[] = [];
+  let replaced = false;
+  for (const line of lines) {
+    if (!line.startsWith("data:")) {
+      rewritten.push(line);
+      continue;
+    }
+    if (!replaced) {
+      rewritten.push(`data: ${payload}`);
+      replaced = true;
+    }
+  }
+  return replaced ? rewritten.join(newline) : block;
+}
+
+function asOutputIndex(value: unknown): number | null {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : null;
+}
+
+function repairableItemType(item: Record<string, unknown>): RepairableItemType | null {
+  return item.type === "message" || item.type === "reasoning" ? item.type : null;
+}
+
+function mintCanonicalId(type: RepairableItemType, scope: string, outputIndex: number): string {
+  return `${REPAIRABLE_PREFIXES[type]}ocx_${scope}_${outputIndex}`;
+}
+
+function createRepairState(config: ResponsesItemIdRepairConfig): ResponsesItemIdRepairState {
+  return {
+    repairMissingTerminalIds: config.repairMissingTerminalIds === true,
+    placeholders: {
+      message: new Set(config.message ?? []),
+      reasoning: new Set(config.reasoning ?? []),
+    },
+    outputIds: {
+      message: new Map<number, string>(),
+      reasoning: new Map<number, string>(),
+    },
+    scope: randomUUID().replace(/-/g, ""),
+  };
+}
+
+function rememberMappedId(
+  state: ResponsesItemIdRepairState,
+  outputIndex: number,
+  item: Record<string, unknown>,
+): string | null {
+  const type = repairableItemType(item);
+  if (!type) return null;
+  const existing = state.outputIds[type].get(outputIndex);
+  if (existing) return existing;
+  const rawId = typeof item.id === "string" ? item.id : undefined;
+  if (!rawId) return null;
+  const mapped = state.placeholders[type].has(rawId)
+    ? mintCanonicalId(type, state.scope, outputIndex)
+    : state.repairMissingTerminalIds
+      ? rawId
+      : null;
+  if (!mapped) return null;
+  state.outputIds[type].set(outputIndex, mapped);
+  return mapped;
+}
+
+function rewriteOutputItem(
+  state: ResponsesItemIdRepairState,
+  outputIndex: number,
+  item: Record<string, unknown>,
+): { item: Record<string, unknown>; changed: boolean } {
+  const mapped = rememberMappedId(state, outputIndex, item);
+  if (!mapped) return { item, changed: false };
+  const currentId = typeof item.id === "string" ? item.id : undefined;
+  if (currentId === mapped) return { item, changed: false };
+  if (currentId === undefined && !state.repairMissingTerminalIds) return { item, changed: false };
+  return { item: { ...item, id: mapped }, changed: true };
+}
+
+function rewriteItemIdField(
+  state: ResponsesItemIdRepairState,
+  event: Record<string, unknown>,
+  outputIndex: number,
+): { event: Record<string, unknown>; changed: boolean } {
+  const eventType = typeof event.type === "string" ? ITEM_ID_EVENT_TYPES[event.type] : undefined;
+  if (!eventType) return { event, changed: false };
+  const mapped = state.outputIds[eventType].get(outputIndex);
+  if (!mapped) return { event, changed: false };
+  const currentId = typeof event.item_id === "string" ? event.item_id : undefined;
+  if (currentId === mapped) return { event, changed: false };
+  if (currentId === undefined && !state.repairMissingTerminalIds) return { event, changed: false };
+  return { event: { ...event, item_id: mapped }, changed: true };
+}
+
+function rewriteResponseSnapshot(
+  state: ResponsesItemIdRepairState,
+  response: Record<string, unknown>,
+): { response: Record<string, unknown>; changed: boolean } {
+  if (!Array.isArray(response.output)) return { response, changed: false };
+  let changed = false;
+  const output = response.output.map((item, outputIndex) => {
+    if (!isPlainObject(item)) return item;
+    const rewritten = rewriteOutputItem(state, outputIndex, item);
+    changed = changed || rewritten.changed;
+    return rewritten.item;
+  });
+  return changed ? { response: { ...response, output }, changed: true } : { response, changed: false };
+}
+
+function repairEventPayload(
+  payload: string,
+  state: ResponsesItemIdRepairState,
+): string {
+  let event: unknown;
+  try {
+    event = JSON.parse(payload);
+  } catch {
+    return payload;
+  }
+  if (!isPlainObject(event)) return payload;
+
+  let changed = false;
+  let nextEvent = event;
+  const outputIndex = asOutputIndex(event.output_index);
+  if (outputIndex !== null && isPlainObject(event.item)) {
+    const rewritten = rewriteOutputItem(state, outputIndex, event.item);
+    if (rewritten.changed) {
+      nextEvent = { ...nextEvent, item: rewritten.item };
+      changed = true;
+    }
+  }
+  if (outputIndex !== null) {
+    const rewritten = rewriteItemIdField(state, nextEvent, outputIndex);
+    if (rewritten.changed) {
+      nextEvent = rewritten.event;
+      changed = true;
+    }
+  }
+  if (isPlainObject(event.response)) {
+    const rewritten = rewriteResponseSnapshot(state, event.response);
+    if (rewritten.changed) {
+      nextEvent = { ...nextEvent, response: rewritten.response };
+      changed = true;
+    }
+  }
+  return changed ? JSON.stringify(nextEvent) : payload;
+}
+
+/**
+ * [Decision Log]
+ * - 목적과 의도: 일부 openai-responses 호환 게이트웨이가 재사용/누락하는 message·reasoning item id를
+ *   downstream SSE에서만 선택적으로 보정해 Codex Desktop 카드 상관관계를 안정화한다.
+ * - 기존 구현 및 제약 조건: 기본 passthrough는 바이트 단위 그대로 relay되고, local replay 상태는 raw
+ *   upstream 응답을 기억한다. function_call id / call_id는 upstream 의미가 있으므로 절대 바꾸면 안 된다.
+ * - 검토한 주요 대안: 모든 passthrough SSE를 항상 재작성하기, raw inspect 분기까지 함께 재작성하기,
+ *   function_call 포함 전체 item id를 정규화하기.
+ * - 선택한 방식: provider-local opt-in 설정이 있을 때만 client-facing SSE 분기에 한정해 exact
+ *   message/reasoning placeholder id와 missing terminal id를 item type + output_index 기준으로 보정하고,
+ *   event-level item_id는 명시적인 message/reasoning lifecycle allowlist에서만 바꾼다.
+ * - 다른 대안 대신 이 방식을 선택한 이유: disabled-by-default byte-for-byte passthrough를 유지하면서,
+ *   previous_response_id replay는 raw upstream snapshot을 계속 사용해 synthetic id가 upstream으로
+ *   역류하지 않게 막을 수 있다.
+ * - 장점, 단점 및 영향: 기본 경로는 변하지 않는다. malformed stream이 output_index를 다른 item
+ *   type에 재사용해도 function_call id/call_id는 보존된다. opt-in 게이트웨이는 sequential streams에서도
+ *   고유한 canonical id를 얻지만, 보정이 필요한 경우에만 JS stream 재작성 비용을 지불한다.
+ */
+export function relaySseWithResponsesItemIdRepair(
+  body: ReadableStream<Uint8Array>,
+  config: ResponsesItemIdRepairConfig,
+): ReadableStream<Uint8Array> {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  const encoder = new TextEncoder();
+  const state = createRepairState(config);
+  let buffer = "";
+
+  const emitProcessedBlocks = (
+    controller: ReadableStreamDefaultController<Uint8Array>,
+    flushFinal = false,
+  ): void => {
+    let next: { block: string; delimiter: string; rest: string } | null;
+    while ((next = nextSseBlock(buffer))) {
+      buffer = next.rest;
+      const payload = sseDataPayload(next.block);
+      const repairedPayload = payload ? repairEventPayload(payload, state) : undefined;
+      const block = payload && repairedPayload !== undefined && repairedPayload !== payload
+        ? replaceSseDataPayload(next.block, repairedPayload)
+        : next.block;
+      controller.enqueue(encoder.encode(block + next.delimiter));
+    }
+    if (flushFinal && buffer.length > 0) {
+      const payload = sseDataPayload(buffer);
+      const repairedPayload = payload ? repairEventPayload(payload, state) : undefined;
+      const block = payload && repairedPayload !== undefined && repairedPayload !== payload
+        ? replaceSseDataPayload(buffer, repairedPayload)
+        : buffer;
+      controller.enqueue(encoder.encode(block));
+      buffer = "";
+    }
+  };
+
+  return new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      const { done, value } = await reader.read();
+      if (done) {
+        buffer += decoder.decode();
+        emitProcessedBlocks(controller, true);
+        controller.close();
+        return;
+      }
+      buffer += decoder.decode(value, { stream: true });
+      emitProcessedBlocks(controller);
+    },
+    cancel(reason) {
+      reader.cancel(reason).catch(() => {});
+    },
+  });
+}
+
+export function hasResponsesItemIdRepair(config: ResponsesItemIdRepairConfig | undefined): boolean {
+  return config?.repairMissingTerminalIds === true
+    || (config?.message?.length ?? 0) > 0
+    || (config?.reasoning?.length ?? 0) > 0;
+}