@remodex/rmx 1.0.2

package/src/server/responses/policy-fallback.ts

@@ -0,0 +1,152 @@
+import { comboFailureDecision } from "../../combos/failover";
+import { readBoundedResponseBody } from "../../lib/bounded-body";
+import { readJsonRequestBody } from "../request-decompress";
+import { finishRequestAttempt, type RequestLogContext } from "../request-log";
+import type { OcxConfig } from "../../types";
+import type { RouteCandidateTrace, RouteDecisionTraceV1 } from "../../routing/trace";
+import { handleResponses as handleResponsesCore } from "./core";
+
+type CoreHandler = typeof handleResponsesCore;
+type CoreOptions = Parameters<CoreHandler>[3];
+
+export interface PolicyFallbackDeps {
+  runCore?: CoreHandler;
+}
+
+function candidateKey(candidate: Pick<RouteCandidateTrace, "provider" | "model">): string {
+  return `${candidate.provider}\u0000${candidate.model}`;
+}
+
+/**
+ * Rank the remaining candidates from the ORIGINAL policy trace. The initial
+ * decision stays immutable; fallback execution belongs in attempts[], not in a
+ * rewritten decision trace.
+ */
+export function rankPolicyFallbackCandidates(
+  trace: RouteDecisionTraceV1,
+  tried: ReadonlySet<string>,
+): RouteCandidateTrace[] {
+  return trace.candidates
+    .map((candidate, index) => ({ candidate, index }))
+    .filter(({ candidate }) =>
+      candidate.eligible
+      && candidate.exclusions.length === 0
+      && !tried.has(candidateKey(candidate)))
+    .sort((left, right) => {
+      const scoreDelta = (right.candidate.score?.total ?? Number.NEGATIVE_INFINITY)
+        - (left.candidate.score?.total ?? Number.NEGATIVE_INFINITY);
+      return scoreDelta || left.index - right.index;
+    })
+    .map(({ candidate }) => candidate);
+}
+
+function requestWithCandidate(
+  req: Request,
+  rawBody: Record<string, unknown>,
+  candidate: Pick<RouteCandidateTrace, "provider" | "model">,
+): Request {
+  const headers = new Headers(req.headers);
+  headers.delete("content-encoding");
+  headers.delete("content-length");
+  headers.set("content-type", "application/json");
+  return new Request(req.url, {
+    method: req.method,
+    headers,
+    body: JSON.stringify({ ...rawBody, model: `${candidate.provider}/${candidate.model}` }),
+    signal: req.signal,
+  });
+}
+
+function errorCodeFromText(text: string): string | undefined {
+  if (!text) return undefined;
+  try {
+    const payload = JSON.parse(text) as { error?: { code?: unknown; type?: unknown }; code?: unknown };
+    const candidate = payload.error?.code ?? payload.error?.type ?? payload.code;
+    return typeof candidate === "string" ? candidate : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function shouldHopPolicyCandidate(response: Response, signal?: AbortSignal): Promise<boolean> {
+  if (response.status < 400 || signal?.aborted) return false;
+  try {
+    const inspected = await readBoundedResponseBody(response.clone(), { signal });
+    const text = inspected.displaySafe ? inspected.text : "";
+    return comboFailureDecision(response.status, text, { code: errorCodeFromText(text) }) === "hop";
+  } catch {
+    return false;
+  }
+}
+
+function isPolicyDecision(trace: RouteDecisionTraceV1 | undefined): trace is RouteDecisionTraceV1 {
+  return trace?.routeKind === "policy" && !!trace.profile;
+}
+
+/** Finalize the failed physical attempt so the retry receives a fresh attempt row. */
+function finishFailedPolicyAttempt(logCtx: RequestLogContext, status: number): void {
+  const attempt = logCtx.activeAttempt;
+  if (attempt) {
+    const startedAt = logCtx.activeAttemptStartedAt ?? Date.now();
+    finishRequestAttempt(attempt, status, Math.max(0, Date.now() - startedAt), attempt.usage ?? logCtx.usage);
+  }
+  delete logCtx.activeAttempt;
+  delete logCtx.activeAttemptStartedAt;
+  delete logCtx.usage;
+  delete logCtx.usageFromBridge;
+  delete logCtx.upstreamError;
+  delete logCtx.terminalHttpStatus;
+  delete logCtx.terminalIncompleteReason;
+}
+
+/**
+ * Run a Responses request and, only for an explicitly selected policy profile,
+ * hop to the next eligible policy candidate after a retryable pre-success
+ * failure. The initial policy trace remains the canonical selection evidence;
+ * physical retries continue to accumulate in the existing request attempts.
+ */
+export async function handleResponsesWithPolicyFallback(
+  req: Request,
+  config: OcxConfig,
+  logCtx: RequestLogContext,
+  options: CoreOptions = {},
+  deps: PolicyFallbackDeps = {},
+): Promise<Response> {
+  const runCore = deps.runCore ?? handleResponsesCore;
+  let rawBody: Record<string, unknown> | null = null;
+  try {
+    const parsed = await readJsonRequestBody(req.clone());
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) rawBody = parsed as Record<string, unknown>;
+  } catch {
+    // Core owns the client-facing parse/decompression error.
+  }
+
+  let response = await runCore(req, config, logCtx, options);
+  const initialTrace = logCtx.routeDecision;
+  const initialRequestedModel = logCtx.requestedModel;
+  if (!rawBody || !isPolicyDecision(initialTrace)) return response;
+
+  const tried = new Set<string>([
+    candidateKey({ provider: initialTrace.selected.provider, model: initialTrace.selected.model }),
+  ]);
+
+  while (await shouldHopPolicyCandidate(response, req.signal)) {
+    if (req.signal.aborted) return response;
+    const next = rankPolicyFallbackCandidates(initialTrace, tried)[0];
+    if (!next) return response;
+    tried.add(candidateKey(next));
+
+    finishFailedPolicyAttempt(logCtx, response.status);
+    const retryRequest = requestWithCandidate(req, rawBody, next);
+    try {
+      response = await runCore(retryRequest, config, logCtx, options);
+    } finally {
+      logCtx.requestedModel = initialRequestedModel;
+      logCtx.routeDecision = initialTrace;
+    }
+  }
+
+  return response;
+}
+
+export const handleResponses = handleResponsesWithPolicyFallback;

package/src/server/responses/terminal-guard.ts

@@ -0,0 +1,230 @@
+import type {
+  AdapterEvent,
+  OcxAssistantContentPart,
+  OcxAssistantMessage,
+  OcxParsedRequest,
+  OcxUsage,
+} from "../../types";
+
+const ACTIONABLE_REQUEST_RE = /(?:\b(?:add|change|check|continue|create|debug|delete|deploy|edit|execute|fix|implement|inspect|keep going|modify|patch|proceed|refactor|remove|review|run|test|update|write)\b|继续|接着|往下|升级|修改|改(?:一下|下)?|修复|实现|添加|新增|删除|重构|更新|运行|执行|检查|查看|排查|调试|创建|写入|提交|推送|部署|看下|改成|修一下)/iu;
+const PLAN_ONLY_REQUEST_RE = /(?:暂时不要(?:调用|使用)工具|不要调用工具|不用执行|只回复(?:计划|方案)|(?:只|先|给|说|写|出|来)(?:我)?(?:一个|个|一下|份)?[^。！？\n]{0,8}?(?:计划|方案|草案|提案|思路)|(?:计划|方案|草案|提案|思路)(?:就(?:行|好|可以)|即可)|\b(?:just give|provide)\s+(?:me\s+)?(?:a\s+)?plan\b|\b(?:do not|don't)\s+(?:use|call)\s+tools?\b|\b(?:write|draft|outline|propose|give|provide|create|make|share|suggest|sketch)\s+(?:me\s+)?(?:a\s+|an\s+|the\s+|your\s+)?(?:(?:brief|concise|short|detailed|high[-\s]?level|rough|quick|step[-\s]?by[-\s]?step|implementation|migration|refactor(?:ing)?|design|technical)\s+)*(?:plan|proposal|draft|outline|approach|strategy|design\s+doc)\b)/iu;
+const PLAN_INTENT_RE = /(?:\b(?:i(?:'|’)m going to|i will|i(?:'|’)ll|let me|next i)\b|我(?:先|会|将|接下来)|下一步)/iu;
+const PLAN_OR_COMPLETION_RE = /(?:\b(?:i(?:'|’)m going to|i will|i(?:'|’)ll|let me|next i|i(?:'|’)ve (?:already )?(?:added|applied|changed|completed|fixed|implemented|modified|updated))\b|\b(?:done|completed|fixed|implemented|updated|applied)\b|我(?:先|会|将|接下来)|下一步|已(?:经)?(?:修改|修复|完成|应用|更新|实现|处理)|完成了|已经好了)/iu;
+const WAITING_FOR_USER_RE = /(?:[?？]\s*$|需要我|请(?:确认|选择|提供)|是否|要不要|可以吗|\b(?:do you want|should i|which file|please confirm|please provide)\b)/iu;
+const EXPLICIT_CONTINUE_RE = /^(?:继续|接着|往下|go on|continue|proceed|keep going)\s*[.!。！]?$/iu;
+const MAX_ANNOUNCEMENT_CHARS = 280;
+
+export const TERMINAL_GUARD_NUDGE =
+  "你刚才只描述了计划，没有执行任何工具。不要再次解释计划，现在立即调用必要工具执行用户任务。" +
+  "只有工具返回后才总结；如果确实无法执行，请明确说明阻塞原因。";
+
+export type TerminalGuardDecision = "pass" | "continue" | "ambiguous";
+
+export interface TerminalTurnAnalysis {
+  decision: TerminalGuardDecision;
+  reason: "normal" | "waiting_for_user" | "no_tools" | "no_actionable_request" | "no_execution_claim" | "recent_tool_activity" | "substantive_answer" | "suspicious_no_tool";
+  assistantText: string;
+  userText: string;
+  hasToolCall: boolean;
+}
+
+function messageText(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (!Array.isArray(value)) return "";
+  return value
+    .filter((part): part is { type?: unknown; text?: unknown } => !!part && typeof part === "object")
+    .filter(part => part.type === "text" && typeof part.text === "string")
+    .map(part => part.text as string)
+    .join("");
+}
+
+function latestUserText(parsed: OcxParsedRequest): string {
+  for (let i = parsed.context.messages.length - 1; i >= 0; i -= 1) {
+    const message = parsed.context.messages[i];
+    if (message.role === "user") return messageText(message.content);
+  }
+  return "";
+}
+
+function recentTurnHasToolActivity(parsed: OcxParsedRequest): boolean {
+  let latestUserIndex = -1;
+  for (let i = parsed.context.messages.length - 1; i >= 0; i -= 1) {
+    if (parsed.context.messages[i]?.role === "user") {
+      latestUserIndex = i;
+      break;
+    }
+  }
+  if (latestUserIndex < 0) return false;
+  let lastAssistant: OcxAssistantMessage | undefined;
+  for (let i = latestUserIndex - 1; i >= 0; i -= 1) {
+    const message = parsed.context.messages[i];
+    if (message.role === "assistant") {
+      lastAssistant = message;
+      break;
+    }
+  }
+  if (lastAssistant?.role === "assistant") {
+    const hasToolCall = lastAssistant.content.some(part => part.type === "toolCall");
+    const text = lastAssistant.content
+      .filter(part => part.type === "text")
+      .map(part => part.text)
+      .join("");
+    if (!hasToolCall && PLAN_INTENT_RE.test(text)) return false;
+  }
+  for (let i = latestUserIndex - 1; i >= 0 && parsed.context.messages[i]?.role !== "user"; i -= 1) {
+    const message = parsed.context.messages[i];
+    if (message.role === "toolResult") return true;
+    if (message.role === "assistant" && message.content.some(part => part.type === "toolCall")) return true;
+  }
+  return false;
+}
+
+function assistantText(events: readonly AdapterEvent[]): string {
+  return events
+    .filter((event): event is Extract<AdapterEvent, { type: "text_delta" }> => event.type === "text_delta")
+    .map(event => event.text)
+    .join("");
+}
+
+export function analyzeTerminalTurn(parsed: OcxParsedRequest, events: readonly AdapterEvent[]): TerminalTurnAnalysis {
+  const userText = latestUserText(parsed);
+  const text = assistantText(events);
+  const hasToolCall = events.some(event => event.type === "tool_call_start");
+  if (hasToolCall) {
+    return { decision: "pass", reason: "normal", assistantText: text, userText, hasToolCall };
+  }
+  if (!parsed.context.tools || parsed.context.tools.length === 0 || parsed.options.toolChoice === "none") {
+    return { decision: "pass", reason: "no_tools", assistantText: text, userText, hasToolCall };
+  }
+  if (!ACTIONABLE_REQUEST_RE.test(userText)) {
+    return { decision: "pass", reason: "no_actionable_request", assistantText: text, userText, hasToolCall };
+  }
+  if (PLAN_ONLY_REQUEST_RE.test(userText)) {
+    return { decision: "pass", reason: "no_actionable_request", assistantText: text, userText, hasToolCall };
+  }
+  if (EXPLICIT_CONTINUE_RE.test(userText) && recentTurnHasToolActivity(parsed)) {
+    return { decision: "pass", reason: "recent_tool_activity", assistantText: text, userText, hasToolCall };
+  }
+  if (WAITING_FOR_USER_RE.test(text)) {
+    return { decision: "pass", reason: "waiting_for_user", assistantText: text, userText, hasToolCall };
+  }
+  if (text.trim().length > MAX_ANNOUNCEMENT_CHARS) {
+    return { decision: "pass", reason: "substantive_answer", assistantText: text, userText, hasToolCall };
+  }
+  if (!PLAN_OR_COMPLETION_RE.test(text)) {
+    return { decision: "ambiguous", reason: "no_execution_claim", assistantText: text, userText, hasToolCall };
+  }
+  return { decision: "continue", reason: "suspicious_no_tool", assistantText: text, userText, hasToolCall };
+}
+
+function assistantMessageFromEvents(events: readonly AdapterEvent[]): OcxAssistantMessage | undefined {
+  let text = "";
+  let thinking = "";
+  let signature: string | undefined;
+  const redacted: string[] = [];
+  for (const event of events) {
+    if (event.type === "text_delta") text += event.text;
+    else if (event.type === "thinking_delta") thinking += event.thinking;
+    else if (event.type === "thinking_signature") signature = event.signature;
+    else if (event.type === "redacted_thinking") redacted.push(event.data);
+  }
+  const content: OcxAssistantContentPart[] = [];
+  if (thinking || signature || redacted.length > 0) {
+    content.push({ type: "thinking", thinking, ...(signature ? { signature } : {}), ...(redacted.length > 0 ? { redacted } : {}) });
+  }
+  if (text) content.push({ type: "text", text });
+  if (content.length === 0) return undefined;
+  return { role: "assistant", content, timestamp: Date.now() };
+}
+
+export function buildContinuationRequest(parsed: OcxParsedRequest, events: readonly AdapterEvent[]): OcxParsedRequest {
+  const messages = [...parsed.context.messages];
+  const assistant = assistantMessageFromEvents(events);
+  if (assistant) messages.push(assistant);
+  messages.push({ role: "developer", content: TERMINAL_GUARD_NUDGE, timestamp: Date.now() });
+  return { ...parsed, context: { ...parsed.context, messages } };
+}
+
+export interface GuardedEventStreamOptions {
+  parsed: OcxParsedRequest;
+  firstEvents: AsyncIterable<AdapterEvent>;
+  continuation: (parsed: OcxParsedRequest) => AsyncIterable<AdapterEvent> | Promise<AsyncIterable<AdapterEvent>>;
+  adapterName?: string;
+  maxAutoContinuations?: number;
+}
+
+function mergeUsage(first: OcxUsage | undefined, second: OcxUsage | undefined): OcxUsage | undefined {
+  if (!first) return second;
+  if (!second) return first;
+  const sumOptional = (key: keyof OcxUsage): number | undefined => {
+    const left = first[key];
+    const right = second[key];
+    return typeof left === "number" || typeof right === "number"
+      ? (typeof left === "number" ? left : 0) + (typeof right === "number" ? right : 0)
+      : undefined;
+  };
+  const cachedInputTokens = sumOptional("cachedInputTokens");
+  const cacheReadInputTokens = sumOptional("cacheReadInputTokens");
+  const cacheCreationInputTokens = sumOptional("cacheCreationInputTokens");
+  const reasoningOutputTokens = sumOptional("reasoningOutputTokens");
+  const inputTokens = first.inputTokens + second.inputTokens;
+  const outputTokens = first.outputTokens + second.outputTokens;
+  return {
+    inputTokens,
+    outputTokens,
+    totalTokens: inputTokens + outputTokens,
+    ...(cachedInputTokens !== undefined ? { cachedInputTokens } : {}),
+    ...(cacheReadInputTokens !== undefined ? { cacheReadInputTokens } : {}),
+    ...(cacheCreationInputTokens !== undefined ? { cacheCreationInputTokens } : {}),
+    ...(reasoningOutputTokens !== undefined ? { reasoningOutputTokens } : {}),
+    ...(first.estimated || second.estimated ? { estimated: true } : {}),
+  };
+}
+
+/** Preserve normal terminals, but withhold one suspicious no-tool terminal for a bounded re-ask. */
+export async function* guardTerminalEventStream(options: GuardedEventStreamOptions): AsyncGenerator<AdapterEvent> {
+  const maxContinuations = Math.max(0, Math.min(2, Math.floor(options.maxAutoContinuations ?? 1)));
+  let parsed = options.parsed;
+  let continuations = 0;
+  let accumulatedUsage: OcxUsage | undefined;
+  let source: AsyncIterable<AdapterEvent> = options.firstEvents;
+
+  while (true) {
+    const seen: AdapterEvent[] = [];
+    let terminalSeen = false;
+    for await (const event of source) {
+      if (event.type === "done") {
+        terminalSeen = true;
+        const analysis = options.adapterName === "anthropic"
+          ? analyzeTerminalTurn(parsed, seen)
+          : { decision: "pass" as const };
+        const normalStop = event.stopReason !== "max_tokens" && event.stopReason !== "content_filter";
+        if (normalStop && analysis.decision === "continue" && continuations < maxContinuations) {
+          accumulatedUsage = mergeUsage(accumulatedUsage, event.usage);
+          continuations += 1;
+          parsed = buildContinuationRequest(parsed, seen);
+          yield { type: "assistant_boundary" };
+          try {
+            source = await options.continuation(parsed);
+          } catch (error) {
+            yield { type: "error", message: error instanceof Error ? error.message : String(error) };
+            return;
+          }
+          break;
+        }
+        const usage = mergeUsage(accumulatedUsage, event.usage);
+        yield usage ? { ...event, usage } : event;
+        return;
+      }
+      if (event.type === "incomplete" || event.type === "error") {
+        terminalSeen = true;
+        const usage = mergeUsage(accumulatedUsage, event.usage);
+        yield usage ? { ...event, usage } : event;
+        return;
+      }
+      seen.push(event);
+      yield event;
+    }
+    if (!terminalSeen) return;
+  }
+}

package/src/server/responses/upstream-error.ts

@@ -0,0 +1,48 @@
+/**
+ * Upstream connection failures share one message shape across the three catch sites in
+ * core.ts. A TLS certificate/hostname mismatch deserves its own wording: the generic
+ * "Provider unreachable" reads as if Remodex built a wrong endpoint, which sent issue
+ * #553 looking for an adapter URL bug that does not exist. Name the likely cause and the
+ * command that settles it.
+ */
+export function describeUpstreamConnectFailure(err: unknown, connectMs: number): string {
+  if (err instanceof Error && err.name === "TimeoutError") {
+    return `Provider connect timeout after ${connectMs}ms`;
+  }
+  const detail = err instanceof Error ? err.message : String(err);
+  const code = err instanceof Error ? (err as { code?: unknown }).code : undefined;
+  // `code` is the reliable signal. The message fallback is anchored to the head because Bun
+  // renders this rejection as `ERR_TLS_CERT_ALTNAME_INVALID fetching "<url>"`; matching the
+  // bare substring anywhere would also fire on text that merely quotes the code back at us.
+  // Only transport failures reach these call sites, so that is defensive rather than load-bearing.
+  if (code === "ERR_TLS_CERT_ALTNAME_INVALID" || detail.startsWith("ERR_TLS_CERT_ALTNAME_INVALID")) {
+    const host = extractHostname(detail);
+    const target = host ?? "the provider host";
+    const probe = host ?? "<host>";
+    return `Provider TLS certificate does not match ${target}: ${redactUrlUserinfo(detail)}. `
+      + "Remodex did not rewrite this hostname — a certificate that does not cover it normally "
+      + "means TLS interception (corporate proxy, VPN, or local MITM tooling) or a poisoned DNS "
+      + `answer. Check with: openssl s_client -connect ${probe}:443 -servername ${probe} `
+      + "</dev/null | openssl x509 -noout -subject -ext subjectAltName";
+  }
+  return `Provider unreachable: ${redactUrlUserinfo(detail)}`;
+}
+
+/**
+ * A provider base URL may carry credentials as userinfo (`https://user:token@host/`), and the
+ * runtime error echoes the URL it was fetching. Strip it before the message reaches a client
+ * or a log line.
+ */
+function redactUrlUserinfo(detail: string): string {
+  return detail.replace(/(https?:\/\/)[^/\s"'@]*@/g, "$1<redacted>@");
+}
+
+function extractHostname(detail: string): string | null {
+  const match = detail.match(/https?:\/\/([^/\s"']+)/);
+  if (!match?.[1]) return null;
+  try {
+    return new URL(`https://${match[1]}`).hostname || null;
+  } catch {
+    return null;
+  }
+}

package/src/server/responses-image-gen-repair.ts

@@ -0,0 +1,132 @@
+import { collectResponsesToolGroups } from "../responses/tool-groups";
+import { relaySseWithPayloadRewrite, type SsePayloadRewrite } from "./sse-payload-rewrite";
+import type { TranslatorBudget } from "../lib/translator-budget";
+
+interface NamespacedTool {
+  namespace: string;
+  name: string;
+}
+
+const IMAGE_GEN_NAMESPACE = "image_gen";
+const IMAGE_GEN_DOTTED_PREFIX = `${IMAGE_GEN_NAMESPACE}.`;
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * Restrict the generic bridge map to Codex's standalone image namespace and accept the dotted
+ * alias emitted by earlier compatibility attempts. Legacy flat dotted declarations are recovered
+ * from the raw request because the generic parser does not assign them a namespace. Exact declared
+ * names avoid splitting arbitrary double-underscore function names that belong to unrelated tools.
+ */
+export function imageGenToolCallAliases(
+  toolNsMap: ReadonlyMap<string, NamespacedTool>,
+  requestBody?: unknown,
+  translatorBudget?: TranslatorBudget,
+): Map<string, NamespacedTool> {
+  const aliases = new Map<string, NamespacedTool>();
+  const retainAlias = (key: string, tool: NamespacedTool) => {
+    if (aliases.has(key)) {
+      aliases.set(key, tool);
+      return;
+    }
+    translatorBudget?.chargeRetained(
+      Buffer.byteLength(key) + Buffer.byteLength(tool.namespace) + Buffer.byteLength(tool.name),
+      { kind: "request_copies" },
+    );
+    aliases.set(key, tool);
+  };
+  for (const [wireName, tool] of toolNsMap) {
+    if (tool.namespace !== IMAGE_GEN_NAMESPACE) continue;
+    retainAlias(wireName, tool);
+    retainAlias(`${tool.namespace}.${tool.name}`, tool);
+  }
+  for (const group of collectResponsesToolGroups(requestBody)) {
+    for (const tool of group) {
+      if (
+        !isPlainObject(tool)
+        || tool.type !== "function"
+        || typeof tool.name !== "string"
+        || !tool.name.startsWith(IMAGE_GEN_DOTTED_PREFIX)
+        || tool.name.length === IMAGE_GEN_DOTTED_PREFIX.length
+      ) continue;
+      const localName = tool.name.slice(IMAGE_GEN_DOTTED_PREFIX.length);
+      const target = { namespace: IMAGE_GEN_NAMESPACE, name: localName };
+      retainAlias(`${IMAGE_GEN_NAMESPACE}__${localName}`, target);
+      retainAlias(tool.name, target);
+    }
+  }
+  return aliases;
+}
+
+/** Recursively restore only exact image-gen function-call aliases in a parsed Responses payload. */
+function restoreImageGenCalls(
+  value: unknown,
+  aliases: ReadonlyMap<string, NamespacedTool>,
+): { value: unknown; changed: boolean } {
+  if (Array.isArray(value)) {
+    let changed = false;
+    const restored = value.map(entry => {
+      const result = restoreImageGenCalls(entry, aliases);
+      changed ||= result.changed;
+      return result.value;
+    });
+    return changed ? { value: restored, changed: true } : { value, changed: false };
+  }
+  if (!isPlainObject(value)) return { value, changed: false };
+
+  let changed = false;
+  const restored: Record<string, unknown> = {};
+  for (const [key, entry] of Object.entries(value)) {
+    const result = restoreImageGenCalls(entry, aliases);
+    restored[key] = result.value;
+    changed ||= result.changed;
+  }
+
+  const name = typeof value.name === "string" ? value.name : undefined;
+  const target = value.type === "function_call" && name ? aliases.get(name) : undefined;
+  if (target) {
+    restored.name = target.name;
+    restored.namespace = target.namespace;
+    changed = true;
+  }
+  return changed ? { value: restored, changed: true } : { value, changed: false };
+}
+
+/** Restore image-gen function calls in a non-streaming Responses JSON document. */
+export function restoreImageGenCallsInJson(
+  text: string,
+  aliases: ReadonlyMap<string, NamespacedTool>,
+): string {
+  if (aliases.size === 0) return text;
+  let payload: unknown;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    return text;
+  }
+  const restored = restoreImageGenCalls(payload, aliases);
+  return restored.changed ? JSON.stringify(restored.value) : text;
+}
+
+/** Payload rewrite for composition with other client-facing SSE transforms. */
+export function createImageGenCallRestoreRewrite(
+  aliases: ReadonlyMap<string, NamespacedTool>,
+): SsePayloadRewrite | undefined {
+  if (aliases.size === 0) return undefined;
+  return (payload) => restoreImageGenCallsInJson(payload, aliases);
+}
+
+/**
+ * Restore upstream-safe image-gen aliases only on the client-facing SSE branch. The inspection and
+ * continuation-cache branch must retain raw upstream names so a replay can be sent back unchanged.
+ */
+export function relaySseWithImageGenCallRestore(
+  body: ReadableStream<Uint8Array>,
+  aliases: ReadonlyMap<string, NamespacedTool>,
+  translatorBudget: TranslatorBudget,
+): ReadableStream<Uint8Array> {
+  const rewrite = createImageGenCallRestoreRewrite(aliases);
+  return rewrite ? relaySseWithPayloadRewrite(body, rewrite, translatorBudget) : body;
+}