@iislee/opencodex 2.11.0

package/src/adapters/kiro-retry.ts

@@ -0,0 +1,312 @@
+import type { AdapterFetchContext, AdapterRequest } from "./base";
+import { classifyKiroHttpError, safeKiroHttpErrorMessage } from "./kiro-errors";
+import { normalizeUpstreamHttpErrorResponse } from "./upstream-http-error";
+import { readBoundedResponseBody } from "../lib/bounded-body";
+import { resolveClientRetryAfter } from "../lib/retry-after";
+import { parseRetryAfterMs } from "../combos";
+import {
+  abortError,
+  cancelResponseBodyBestEffort,
+  fetchWithAttemptDeadline,
+  isConnectionResetError,
+  retryBackoffDelayMs,
+  sleepWithAbort,
+} from "../lib/upstream-retry";
+
+const RESET_ATTEMPTS = 3;
+const RESET_RETRY_BASE_MS = 150;
+const RESET_RETRY_MAX_MS = 1_000;
+const THROTTLE_ATTEMPTS = 3;
+const CANONICAL_RUNTIME_HOST = /^runtime\.([a-z]{2}(?:-[a-z]+)+-\d)\.kiro\.dev$/i;
+const ENDPOINT_ERROR_MARKERS = [
+  "unknownoperation",
+  "unknown operation",
+  "invalidsignature",
+  "invalid signature",
+  "endpoint not found",
+  "unsupported endpoint",
+];
+const CONNECT_ERROR_CODES = new Set(["ENOTFOUND", "EAI_AGAIN", "ECONNREFUSED", "ENETUNREACH", "EHOSTUNREACH"]);
+
+interface KiroThrottleProbe {
+  token: symbol;
+  promise: Promise<void>;
+  release: () => void;
+}
+
+let kiroThrottleCooldownUntil = 0;
+let kiroThrottleProbe: KiroThrottleProbe | undefined;
+
+function newKiroThrottleProbe(): KiroThrottleProbe {
+  let release!: () => void;
+  const promise = new Promise<void>(resolve => { release = resolve; });
+  const probe = { token: Symbol("kiro-throttle-probe"), promise, release };
+  kiroThrottleProbe = probe;
+  return probe;
+}
+
+function releaseKiroThrottleProbe(token: symbol | undefined): void {
+  if (!token || kiroThrottleProbe?.token !== token) return;
+  const probe = kiroThrottleProbe;
+  kiroThrottleProbe = undefined;
+  probe.release();
+}
+
+async function waitWithAbort(promise: Promise<void>, signal?: AbortSignal): Promise<void> {
+  if (!signal) return promise;
+  if (signal.aborted) throw abortError(signal);
+  let onAbort!: () => void;
+  const aborted = new Promise<never>((_resolve, reject) => {
+    onAbort = () => reject(abortError(signal));
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+  try {
+    await Promise.race([promise, aborted]);
+  } finally {
+    signal.removeEventListener("abort", onAbort);
+  }
+}
+
+async function waitForKiroCooldown(signal?: AbortSignal): Promise<void> {
+  // Re-check after every sleep because another throttled request can extend the shared deadline.
+  while (true) {
+    const remaining = kiroThrottleCooldownUntil - Date.now();
+    if (remaining <= 0) return;
+    await sleepWithAbort(remaining, signal);
+  }
+}
+
+async function enterKiroThrottleGate(signal?: AbortSignal): Promise<symbol | undefined> {
+  while (true) {
+    const active = kiroThrottleProbe;
+    if (active) {
+      await waitWithAbort(active.promise, signal);
+      continue;
+    }
+    if (kiroThrottleCooldownUntil <= Date.now()) return undefined;
+    const owned = newKiroThrottleProbe();
+    try {
+      await waitForKiroCooldown(signal);
+      return owned.token;
+    } catch (error) {
+      releaseKiroThrottleProbe(owned.token);
+      throw error;
+    }
+  }
+}
+
+function claimKiroThrottleProbe(
+  delayMs: number,
+  currentToken?: symbol,
+): { token?: symbol; wait?: Promise<void> } {
+  kiroThrottleCooldownUntil = Math.max(kiroThrottleCooldownUntil, Date.now() + Math.max(0, delayMs));
+  if (currentToken && kiroThrottleProbe?.token === currentToken) return { token: currentToken };
+  if (!kiroThrottleProbe) return { token: newKiroThrottleProbe().token };
+  return { wait: kiroThrottleProbe.promise };
+}
+
+/** Stream-level throttles arrive after HTTP 200, so record their cooldown for the next client retry. */
+export function noteKiroTransientThrottle(delayMs = 2_000): void {
+  kiroThrottleCooldownUntil = Math.max(kiroThrottleCooldownUntil, Date.now() + Math.max(0, delayMs));
+}
+
+export function resetKiroThrottleStateForTests(): void {
+  const active = kiroThrottleProbe;
+  kiroThrottleProbe = undefined;
+  kiroThrottleCooldownUntil = 0;
+  active?.release();
+}
+
+function errorChain(error: unknown): Error[] {
+  const chain: Error[] = [];
+  let current = error;
+  const seen = new Set<unknown>();
+  while (current instanceof Error && !seen.has(current)) {
+    seen.add(current);
+    chain.push(current);
+    current = (current as Error & { cause?: unknown }).cause;
+  }
+  return chain;
+}
+
+function endpointConnectFailure(error: unknown): boolean {
+  return errorChain(error).some(item => {
+    if (item.name === "AbortError" || item.name === "TimeoutError") return false;
+    const code = (item as Error & { code?: unknown }).code;
+    if (typeof code === "string" && CONNECT_ERROR_CODES.has(code)) return true;
+    const message = item.message.toLowerCase();
+    return message.includes("dns")
+      || message.includes("name resolution")
+      || message.includes("failed to lookup address")
+      || message.includes("connection refused")
+      || message.includes("failed to connect")
+      || message.includes("connect error");
+  });
+}
+
+function legacyUrl(requestUrl: string): string | undefined {
+  let url: URL;
+  try { url = new URL(requestUrl); } catch { return undefined; }
+  const match = CANONICAL_RUNTIME_HOST.exec(url.hostname);
+  if (!match || url.pathname !== "/" || url.search || url.hash) return undefined;
+  url.hostname = `q.${match[1]}.amazonaws.com`;
+  return url.toString();
+}
+
+async function fetchWithResetRecovery(
+  request: AdapterRequest,
+  url: string,
+  ctx: AdapterFetchContext,
+  timeoutMs: number,
+): Promise<Response> {
+  let lastError: unknown;
+  for (let attempt = 0; attempt < RESET_ATTEMPTS; attempt++) {
+    if (ctx.abortSignal?.aborted) throw abortError(ctx.abortSignal);
+    try {
+      const headers = new Headers(request.headers);
+      const recovered = attempt > 0;
+      if (recovered) headers.set("connection", "close");
+      return await fetchWithAttemptDeadline(url, {
+        method: request.method,
+        headers,
+        body: request.body,
+        ...(recovered ? { keepalive: false } : {}),
+      }, timeoutMs, ctx.abortSignal, ctx.stream);
+    } catch (error) {
+      if (ctx.abortSignal?.aborted || !isConnectionResetError(error) || attempt === RESET_ATTEMPTS - 1) throw error;
+      lastError = error;
+      await sleepWithAbort(retryBackoffDelayMs(attempt, {
+        baseDelayMs: RESET_RETRY_BASE_MS,
+        maxDelayMs: RESET_RETRY_MAX_MS,
+      }), ctx.abortSignal);
+    }
+  }
+  throw lastError ?? new Error("Kiro fetch failed");
+}
+
+async function inspectEndpointHttpFailure(
+  response: Response,
+  signal?: AbortSignal,
+): Promise<{ response: Response; fallback: boolean }> {
+  if (response.status === 404 || response.status === 405) return { response, fallback: true };
+  if (response.status !== 400 && response.status !== 403) return { response, fallback: false };
+
+  const body = await readBoundedResponseBody(response, { signal });
+  const headers = new Headers(response.headers);
+  headers.delete("content-encoding");
+  headers.delete("content-length");
+  const rebuilt = new Response(body.displaySafe ? body.text : "", {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+  const text = body.displaySafe ? body.text.toLowerCase() : "";
+  return { response: rebuilt, fallback: ENDPOINT_ERROR_MARKERS.some(marker => text.includes(marker)) };
+}
+
+async function normalizeFinalKiroHttpError(res: Response, signal?: AbortSignal): Promise<Response> {
+  return normalizeUpstreamHttpErrorResponse(res, {
+    signal,
+    formatMessage: payloadText => safeKiroHttpErrorMessage(res.status, res.headers, payloadText),
+  });
+}
+
+async function inspectKiroThrottle(
+  response: Response,
+  signal?: AbortSignal,
+): Promise<{ response: Response; transient: boolean; delayMs: number } | undefined> {
+  if (response.status !== 429) return undefined;
+  const body = await readBoundedResponseBody(response, { signal });
+  const headers = new Headers(response.headers);
+  headers.delete("content-encoding");
+  headers.delete("content-length");
+  const payloadText = body.displaySafe ? body.text : "";
+  const rebuilt = new Response(payloadText, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+  const failure = classifyKiroHttpError(response.status, headers, payloadText);
+  const retryAfter = resolveClientRetryAfter({
+    status: response.status,
+    message: failure.message,
+    upstreamRetryAfter: headers.get("retry-after"),
+  });
+  const delayMs = retryAfter === "0" ? 0 : parseRetryAfterMs(retryAfter) ?? 2_000;
+  return {
+    response: rebuilt,
+    transient: failure.retryable && failure.code === "rate_limit_exceeded",
+    delayMs,
+  };
+}
+
+async function fetchKiroAttempt(
+  request: AdapterRequest,
+  ctx: AdapterFetchContext,
+  timeoutMs: number,
+): Promise<Response> {
+  const legacy = legacyUrl(request.url);
+  let response: Response;
+  try {
+    response = await fetchWithResetRecovery(request, request.url, ctx, timeoutMs);
+  } catch (error) {
+    if (!legacy || !endpointConnectFailure(error)) throw error;
+    return fetchWithResetRecovery(request, legacy, ctx, timeoutMs);
+  }
+
+  if (legacy && !response.ok) {
+    const inspected = await inspectEndpointHttpFailure(response, ctx.abortSignal);
+    response = inspected.response;
+    if (inspected.fallback) {
+      cancelResponseBodyBestEffort(response);
+      response = await fetchWithResetRecovery(request, legacy, ctx, timeoutMs);
+    }
+  }
+  return response;
+}
+
+/**
+ * Kiro owns replay-safe reset recovery, one endpoint fallback, and bounded process-wide transient
+ * throttle recovery. The shared probe starts only after a 429, so healthy parallel traffic remains
+ * parallel while a throttled account cannot burn every caller's independent retry budget (#532).
+ */
+export async function fetchKiroWithRetry(request: AdapterRequest, ctx: AdapterFetchContext = {}): Promise<Response> {
+  const timeoutMs = ctx.timeoutMs ?? 200_000;
+  let probeToken: symbol | undefined;
+  try {
+    for (let attempt = 0; attempt < THROTTLE_ATTEMPTS; attempt++) {
+      if (!probeToken) probeToken = await enterKiroThrottleGate(ctx.abortSignal);
+      else await waitForKiroCooldown(ctx.abortSignal);
+
+      const response = await fetchKiroAttempt(request, ctx, timeoutMs);
+      const throttle = await inspectKiroThrottle(response, ctx.abortSignal);
+      if (!throttle || !throttle.transient) {
+        releaseKiroThrottleProbe(probeToken);
+        const finalResponse = throttle?.response ?? response;
+        return ctx.returnRawErrors
+          ? finalResponse
+          : normalizeFinalKiroHttpError(finalResponse, ctx.abortSignal);
+      }
+
+      const claim = claimKiroThrottleProbe(throttle.delayMs, probeToken);
+      if (!claim.token) {
+        cancelResponseBodyBestEffort(throttle.response);
+        await waitWithAbort(claim.wait!, ctx.abortSignal);
+        probeToken = undefined;
+        continue;
+      }
+      probeToken = claim.token;
+      if (attempt === THROTTLE_ATTEMPTS - 1) {
+        releaseKiroThrottleProbe(probeToken);
+        return ctx.returnRawErrors
+          ? throttle.response
+          : normalizeFinalKiroHttpError(throttle.response, ctx.abortSignal);
+      }
+      cancelResponseBodyBestEffort(throttle.response);
+    }
+    throw new Error("Kiro throttle retry loop exhausted without a response");
+  } catch (error) {
+    releaseKiroThrottleProbe(probeToken);
+    throw error;
+  }
+}

package/src/adapters/kiro-thinking.ts

@@ -0,0 +1,96 @@
+import type { AdapterEvent } from "../types";
+import type { TranslatorBudget } from "../lib/translator-budget";
+
+type ThinkingTag = "<thinking>" | "<think>" | "<reasoning>";
+type ParserState = "pre" | "thinking" | "streaming";
+
+const OPEN_TAGS: ThinkingTag[] = ["<thinking>", "<think>", "<reasoning>"];
+const MAX_OPEN_TAG = Math.max(...OPEN_TAGS.map(t => t.length));
+const MAX_CLOSE_TAG = Math.max(...OPEN_TAGS.map(t => `</${t.slice(1)}`.length));
+
+function closeTagFor(openTag: ThinkingTag): string {
+  return `</${openTag.slice(1)}`;
+}
+
+function isPossibleOpenTagPrefix(text: string): boolean {
+  return OPEN_TAGS.some(tag => tag.startsWith(text) && text.length < tag.length);
+}
+
+export class KiroThinkingParser {
+  private state: ParserState = "pre";
+  private preBuffer = "";
+  private thinkingBuffer = "";
+  private closeTag = "";
+
+  constructor(private readonly budget?: TranslatorBudget) {}
+
+  private replaceCarry(field: "preBuffer" | "thinkingBuffer", next: string): void {
+    const previous = this[field];
+    if (previous === next) return;
+    const previousBytes = Buffer.byteLength(previous);
+    const nextBytes = Buffer.byteLength(next);
+    const reservation = this.budget?.reserveTransient(nextBytes, { kind: "reasoning" });
+    this[field] = next;
+    reservation?.commitRetained();
+    this.budget?.releaseRetained(previousBytes, { kind: "reasoning" });
+  }
+
+  feed(text: string): AdapterEvent[] {
+    if (!text) return [];
+    if (this.state === "streaming") return [{ type: "text_delta", text }];
+    if (this.state === "thinking") {
+      this.replaceCarry("thinkingBuffer", this.thinkingBuffer + text);
+      return this.drainThinking();
+    }
+    this.replaceCarry("preBuffer", this.preBuffer + text);
+    const stripped = this.preBuffer.trimStart();
+    const openTag = OPEN_TAGS.find(tag => stripped.startsWith(tag));
+    if (openTag) {
+      this.state = "thinking";
+      this.closeTag = closeTagFor(openTag);
+      this.replaceCarry("thinkingBuffer", stripped.slice(openTag.length));
+      this.replaceCarry("preBuffer", "");
+      return this.drainThinking();
+    }
+    if (stripped.length <= MAX_OPEN_TAG && isPossibleOpenTagPrefix(stripped)) return [];
+    this.state = "streaming";
+    const out = this.preBuffer;
+    this.replaceCarry("preBuffer", "");
+    return out ? [{ type: "text_delta", text: out }] : [];
+  }
+
+  flush(): AdapterEvent[] {
+    if (this.state === "thinking") {
+      const out = this.thinkingBuffer;
+      this.replaceCarry("thinkingBuffer", "");
+      this.state = "streaming";
+      return out ? [{ type: "reasoning_raw_delta", text: out }] : [];
+    }
+    if (this.preBuffer) {
+      const out = this.preBuffer;
+      this.replaceCarry("preBuffer", "");
+      this.state = "streaming";
+      return [{ type: "text_delta", text: out }];
+    }
+    return [];
+  }
+
+  private drainThinking(): AdapterEvent[] {
+    const close = this.closeTag;
+    const idx = this.thinkingBuffer.indexOf(close);
+    if (idx >= 0) {
+      const thinking = this.thinkingBuffer.slice(0, idx);
+      const after = this.thinkingBuffer.slice(idx + close.length).trimStart();
+      this.replaceCarry("thinkingBuffer", "");
+      this.state = "streaming";
+      const events: AdapterEvent[] = [];
+      if (thinking) events.push({ type: "reasoning_raw_delta", text: thinking });
+      if (after) events.push({ type: "text_delta", text: after });
+      return events;
+    }
+    if (this.thinkingBuffer.length <= MAX_CLOSE_TAG) return [];
+    const send = this.thinkingBuffer.slice(0, -MAX_CLOSE_TAG);
+    this.replaceCarry("thinkingBuffer", this.thinkingBuffer.slice(-MAX_CLOSE_TAG));
+    return send ? [{ type: "reasoning_raw_delta", text: send }] : [];
+  }
+}

package/src/adapters/kiro-tool-fallback.ts

@@ -0,0 +1,36 @@
+import type { OcxContentPart, OcxToolCall, OcxToolResultMessage } from "../types";
+import { normalizeToolId } from "./kiro-wire";
+
+function stringifyValue(value: unknown): string {
+  try { return JSON.stringify(value); } catch { return String(value); }
+}
+
+function contentText(content: string | OcxContentPart[]): string {
+  if (typeof content === "string") return content;
+  return content
+    .map(part => {
+      if (part.type === "text") return part.text;
+      if (part.type === "image") return `[image:${part.detail ?? "auto"}]`;
+      return "";
+    })
+    .filter(Boolean)
+    .join("\n");
+}
+
+export function appendFallbackText(base: string, fallback: string): string {
+  return [base, fallback].filter(Boolean).join("\n\n");
+}
+
+export function toolCallFallbackText(toolCall: OcxToolCall): string {
+  return [
+    `Tool call fallback (${toolCall.name}, id ${normalizeToolId(toolCall.id)}):`,
+    stringifyValue(toolCall.arguments ?? {}),
+  ].join("\n");
+}
+
+export function toolResultFallbackText(toolResult: OcxToolResultMessage): string {
+  return [
+    `Tool result fallback (${toolResult.toolName}, id ${normalizeToolId(toolResult.toolCallId)}, ${toolResult.isError ? "error" : "success"}):`,
+    contentText(toolResult.content) || "(empty)",
+  ].join("\n");
+}

package/src/adapters/kiro-tools.ts

@@ -0,0 +1,215 @@
+import type { OcxParsedRequest, OcxTool } from "../types";
+import { namespacedToolName } from "../types";
+import { normalizeKiroModelId } from "../providers/kiro-models";
+import { createKiroToolNameRegistry, type KiroToolNameRegistry } from "./kiro-wire";
+
+const MAX_KIRO_TOOL_DESCRIPTION_UNVERIFIED = 1024;
+const MAX_KIRO_TOOL_DESCRIPTION_GPT_56_SOL = 9_216;
+// Issue #719's successful Kiro probe used 49 outbound tools at about 108 KiB. Leave one of those
+// slots for Kiro's private completion tool and headroom for the enclosing request/message fields.
+export const MAX_KIRO_TOOL_COUNT = 48;
+export const MAX_KIRO_TOOL_CATALOG_BYTES = 96_000;
+const textEncoder = new TextEncoder();
+
+// JSON Schema validation/annotation keywords that Kiro's runtimeservice tool-spec validator
+// rejects ("ValidationException: Invalid tool use format."). Codex's built-in tools omit these,
+// but the `memories__*` tools (add_ad_hoc_note/read/search/list) emit pattern/length/range
+// constraints via schemars, which trip the validator. Strip them everywhere in the schema tree;
+// the constraints are advisory for the model, so dropping them does not change tool behavior.
+const KIRO_REJECTED_SCHEMA_KEYS = new Set([
+  "additionalProperties",
+  "pattern",
+  "format",
+  "minLength",
+  "maxLength",
+  "minimum",
+  "maximum",
+  "exclusiveMinimum",
+  "exclusiveMaximum",
+  "multipleOf",
+  "minItems",
+  "maxItems",
+  "uniqueItems",
+  "minProperties",
+  "maxProperties",
+  "contentEncoding",
+  "contentMediaType",
+  "$schema",
+  // Validation-only composition/applicator keywords that Bedrock/Kiro do not support. Unlike
+  // `properties`/`$defs`, these are not plain property->schema maps the model needs, so they are
+  // dropped outright rather than recursed into.
+  "patternProperties",
+  "propertyNames",
+  "dependentSchemas",
+  "dependentRequired",
+  "if",
+  "then",
+  "else",
+  "contains",
+  "unevaluatedProperties",
+  "unevaluatedItems",
+  // Codex's Responses-only `encrypted: true` marker (openai/codex 5f4d06ef) stamped on v2
+  // collaboration tool schemas. Kiro/Bedrock validators reject a narrower, undocumented schema
+  // subset (issue #85 class); the marker is a ChatGPT-backend annotation with no meaning here.
+  "encrypted",
+]);
+
+// Keys whose values are maps of *property/definition name -> schema* (not schema keywords). Their
+// child keys must never be treated as schema keywords, or a legitimate property named e.g.
+// "format"/"pattern" would be deleted. We recurse into the value schemas but keep every name intact.
+const SCHEMA_MAP_KEYS = new Set(["properties", "$defs", "definitions"]);
+
+function sanitizeSchemaMap(value: unknown): unknown {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return sanitizeKiroSchema(value);
+  const out: Record<string, unknown> = {};
+  for (const [name, child] of Object.entries(value as Record<string, unknown>)) {
+    out[name] = sanitizeKiroSchema(child);
+  }
+  return out;
+}
+
+function sanitizeKiroSchema(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sanitizeKiroSchema);
+  if (!value || typeof value !== "object") return value;
+  const out: Record<string, unknown> = {};
+  for (const [key, child] of Object.entries(value as Record<string, unknown>)) {
+    if (KIRO_REJECTED_SCHEMA_KEYS.has(key)) continue;
+    if (key === "required" && Array.isArray(child) && child.length === 0) continue;
+    out[key] = SCHEMA_MAP_KEYS.has(key) ? sanitizeSchemaMap(child) : sanitizeKiroSchema(child);
+  }
+  return out;
+}
+
+function ensureRootObjectType(schema: unknown): Record<string, unknown> {
+  const obj = schema && typeof schema === "object" && !Array.isArray(schema)
+    ? schema as Record<string, unknown>
+    : {};
+  // Bedrock rejects oneOf/allOf/anyOf at the root ("input_schema does not support oneOf, allOf, or
+  // anyOf at the top level") and requires the root type to be "object". Flatten every root
+  // composition into the object schema while preserving the root's own properties/required and any
+  // other sibling keys. allOf merges required (AND); anyOf/oneOf drop required so a single valid
+  // branch still passes. Nested (non-root) composition is left intact — only the root is illegal.
+  const COMPOSITION_KEYS = ["oneOf", "anyOf", "allOf"] as const;
+  const hasComposition = COMPOSITION_KEYS.some(k => Array.isArray(obj[k]));
+  const t = obj.type;
+  const rootObjectType = t === "object" || (Array.isArray(t) && t.includes("object"));
+  if (!hasComposition) {
+    if (rootObjectType && t === "object") return obj;
+    return { ...obj, type: "object" };
+  }
+
+  const props: Record<string, unknown> = {};
+  const required = new Set<string>();
+  // Seed with the root's own properties/required so a schema like
+  // { type:"object", properties:{path}, required:["path"], oneOf:[...] } keeps them.
+  if (obj.properties && typeof obj.properties === "object") {
+    Object.assign(props, sanitizeKiroSchema(obj.properties) as Record<string, unknown>);
+  }
+  if (Array.isArray(obj.required)) {
+    for (const r of obj.required) if (typeof r === "string") required.add(r);
+  }
+  for (const key of COMPOSITION_KEYS) {
+    const variants = obj[key];
+    if (!Array.isArray(variants)) continue;
+    // allOf is conjunction: its required fields always apply. oneOf/anyOf are disjunction, so
+    // promoting their required would over-constrain a valid single-branch call.
+    const mergeRequired = key === "allOf";
+    for (const variant of variants) {
+      if (!variant || typeof variant !== "object" || Array.isArray(variant)) continue;
+      const v = variant as Record<string, unknown>;
+      if (v.properties && typeof v.properties === "object") {
+        Object.assign(props, sanitizeKiroSchema(v.properties) as Record<string, unknown>);
+      }
+      if (mergeRequired && Array.isArray(v.required)) {
+        for (const r of v.required) if (typeof r === "string") required.add(r);
+      }
+    }
+  }
+
+  // Keep all non-composition sibling keys (description, $defs, definitions, etc.); replace
+  // type/properties/required with the flattened object form.
+  const merged: Record<string, unknown> = {};
+  for (const [key, child] of Object.entries(obj)) {
+    if (key === "oneOf" || key === "anyOf" || key === "allOf") continue;
+    if (key === "type" || key === "properties" || key === "required") continue;
+    merged[key] = child;
+  }
+  merged.type = "object";
+  if (Object.keys(props).length > 0) merged.properties = props;
+  if (required.size > 0) merged.required = [...required];
+  return merged;
+}
+
+function toolDescriptionLimit(modelId: string): number {
+  return normalizeKiroModelId(modelId) === "gpt-5.6-sol"
+    ? MAX_KIRO_TOOL_DESCRIPTION_GPT_56_SOL
+    : MAX_KIRO_TOOL_DESCRIPTION_UNVERIFIED;
+}
+
+function truncateDescription(description: string, limit: number): string {
+  if (description.length <= limit) return description;
+  if (limit <= 1) return description.slice(0, limit);
+  return `${description.slice(0, limit - 1)}…`;
+}
+
+function serializedToolCatalogBytes(tools: readonly unknown[]): number {
+  return textEncoder.encode(JSON.stringify(tools)).byteLength;
+}
+
+function omittedToolCatalogNotice(kept: number, omitted: readonly OcxTool[], registry: KiroToolNameRegistry): string {
+  const names = omitted.slice(0, 12).map(tool => registry.alias(namespacedToolName(tool.namespace, tool.name)));
+  const remainder = omitted.length - names.length;
+  const summary = `${names.join(", ")}${remainder > 0 ? `, and ${remainder} more` : ""}`;
+  return `[opencodex] Kiro's outbound catalog budget allows ${kept} of ${kept + omitted.length} client tools this turn. Omitted and unavailable this turn: ${summary}.`;
+}
+
+export function convertKiroToolContext(
+  parsed: OcxParsedRequest,
+  registry: KiroToolNameRegistry = createKiroToolNameRegistry(),
+): { tools: unknown[]; systemAdditions: string[]; nameMap: Map<string, string>; registry: KiroToolNameRegistry } {
+  const tools = parsed.context.tools ?? [];
+  const descriptionLimit = toolDescriptionLimit(parsed.modelId);
+  // Validate every listed name even when tool_choice:none emulates a tool-free turn.
+  for (const tool of tools) registry.alias(namespacedToolName(tool.namespace, tool.name));
+  const effectiveTools = parsed.options.toolChoice === "none" ? [] : tools;
+  const convertedTools: unknown[] = [];
+  let omittedAt = effectiveTools.length;
+  for (const [index, tool] of effectiveTools.entries()) {
+    const description = tool.description || `Tool: ${tool.name}`;
+    // Send the full namespaced wire name (e.g. mcp__chrome-devtools__navigate_page) so Kiro echoes
+    // it back; the bridge's toolNsMap is keyed by this name and restores the MCP namespace Codex
+    // routes by. Kiro's runtimeservice rejects names with spaces or >64 chars, so normalize to a
+    // safe form and remember the mapping; the response parser restores the original wire name.
+    const wireName = namespacedToolName(tool.namespace, tool.name);
+    const toolName = registry.alias(wireName);
+    const converted = {
+      toolSpecification: {
+        name: toolName,
+        description: truncateDescription(description, descriptionLimit),
+        inputSchema: { json: ensureRootObjectType(sanitizeKiroSchema(tool.parameters ?? {})) },
+      },
+    };
+    // Preserve declaration order and only omit a suffix. Ranking tools would make a catalog change
+    // silently alter which capability disappears; this deterministic policy is paired with a
+    // model-visible omission notice so unavailable tools are explicit rather than assumed absent.
+    if (
+      convertedTools.length >= MAX_KIRO_TOOL_COUNT
+      || serializedToolCatalogBytes([...convertedTools, converted]) > MAX_KIRO_TOOL_CATALOG_BYTES
+    ) {
+      omittedAt = index;
+      break;
+    }
+    convertedTools.push(converted);
+  }
+  const omittedTools = effectiveTools.slice(omittedAt);
+  return {
+    tools: convertedTools,
+    systemAdditions: omittedTools.length > 0 ? [omittedToolCatalogNotice(convertedTools.length, omittedTools, registry)] : [],
+    nameMap: registry.nameMap,
+    registry,
+  };
+}
+
+export function convertKiroTools(parsed: OcxParsedRequest): unknown[] {
+  return convertKiroToolContext(parsed).tools;
+}