@bitkyc08/opencodex 2.7.33 → 2.7.34

package/src/adapters/cursor/protobuf-request.ts

@@ -22,6 +22,8 @@ import {
   McpToolResultSchema,
   McpToolsSchema,
   ModelDetailsSchema,
+  RequestedModelSchema,
+  RequestedModel_ModelParameterbytesSchema,
   ResumeActionSchema,
   RequestContextSchema,
   RequestContextEnvSchema,
@@ -43,6 +45,9 @@ import {
 
 const encoder = new TextEncoder();
 
+/** Parameter id advertised by Cursor's `default` model for its Cost/Balance/Intelligence control. */
+export const CURSOR_ROUTING_LEVEL_PARAMETER_ID = "optimization";
+
 /** Runtime timezone for protobuf RequestContextEnv (dynamic, never hardcoded). */
 function runtimeTimeZone(): string {
   try {
@@ -364,6 +369,16 @@ export function encodeCursorRunRequest(request: CursorRunRequest): Uint8Array {
       displayNameShort: request.modelId,
       aliases: [],
     }),
+    ...(request.routingLevel ? {
+      requestedModel: create(RequestedModelSchema, {
+        modelId: request.modelId,
+        maxMode: false,
+        parameters: [create(RequestedModel_ModelParameterbytesSchema, {
+          id: CURSOR_ROUTING_LEVEL_PARAMETER_ID,
+          value: request.routingLevel,
+        })],
+      }),
+    } : {}),
     // Mirror the client (Responses) tool definitions into the top-level AgentRunRequest.mcp_tools
     // channel. Advertising them ONLY via native-exec `requestContextArgs` (RequestContext.tools) is
     // insufficient: cursor models report those tools as unavailable and fall back to native tools.

package/src/adapters/cursor/request-builder.ts

@@ -8,7 +8,7 @@ import type {
 } from "../../types";
 import { isAllowedToolChoice, namespacedToolName, toolChoiceAliases, type OcxTool, type OcxToolChoice } from "../../types";
 import type { CursorRequestMessage, CursorRunRequest } from "./types";
-import { cursorCodexToWireModelId } from "./discovery";
+import { cursorWireModelSelection, type CursorRoutingLevel } from "./discovery";
 import { cursorEffortSuffix } from "./effort-map";
 import {
   cursorMcpToolEncodedSize,
@@ -97,10 +97,11 @@ function catalogLimitNote(kept: readonly OcxTool[], omitted: readonly OcxTool[])
 * `undefined` for non-reasoning models like `composer-2.5`. A fully-qualified id (one that isn't a
 * known effort base) passes through unchanged.
  */
-function normalizeCursorModelId(modelId: string, reasoning?: string): string {
-  const id = cursorCodexToWireModelId(modelId);
+function normalizeCursorModelId(modelId: string, reasoning?: string): { modelId: string; routingLevel?: CursorRoutingLevel } {
+  const selection = cursorWireModelSelection(modelId);
+  const id = selection.modelId;
   const suffix = cursorEffortSuffix(id, reasoning);
-  return suffix ? `${id}-${suffix}` : id;
+  return { ...selection, modelId: suffix ? `${id}-${suffix}` : id };
 }
 
 function contentPartToText(part: OcxContentPart | OcxAssistantContentPart): string | undefined {
@@ -166,8 +167,10 @@ export function createCursorRequest(parsed: OcxParsedRequest): CursorRunRequest
   const visibleTools = cursorToolsForActivePrompt(parsed.context.tools, activeText, parsed.options.toolChoice);
   const budget = applyCursorToolBudget(visibleTools, parsed.options.toolChoice);
   const limitNote = catalogLimitNote(budget.tools, budget.omitted);
+  const model = normalizeCursorModelId(parsed.modelId, parsed.options.reasoning);
   return {
-    modelId: normalizeCursorModelId(parsed.modelId, parsed.options.reasoning),
+    modelId: model.modelId,
+    ...(model.routingLevel ? { routingLevel: model.routingLevel } : {}),
     // The Cursor conversation id comes ONLY from remembered state (_cursorConversationId). Do NOT fall
     // back to the OpenAI Responses previous_response_id (resp_*): that is a Responses-chain id in a
     // different namespace and would start an unrelated Cursor conversation, breaking tool-result
@@ -176,6 +179,8 @@ export function createCursorRequest(parsed: OcxParsedRequest): CursorRunRequest
     system: [...(parsed.context.systemPrompt ?? []), ...(limitNote ? [limitNote] : [])],
     messages,
     rawMessages: parsed.context.messages,
+    ...(parsed._compactionRequest === true || parsed._contextCompactionBoundary === true ? { contextUsageReset: true } : {}),
+    ...(parsed._compactionRequest === true ? { contextUsageStoreCheckpoints: false } : {}),
     ...(budget.tools.length ? { tools: budget.tools } : {}),
     ...(parsed.options.toolChoice ? { toolChoice: parsed.options.toolChoice } : {}),
     ...(parsed.options.parallelToolCalls !== undefined ? { parallelToolCalls: parsed.options.parallelToolCalls } : {}),

package/src/adapters/cursor/transport.ts

@@ -24,8 +24,9 @@ export interface CursorTransportFactoryInput {
    */
   clientToolFinalizeGraceMs?: number;
   /**
-   * True when the inbound request's system/developer text declares the Codex full-access
-   * sandbox; consumed by nativeLocalExec:"codex-sandbox" policy (exec-policy.ts).
+   * True when inbound request text carries the legacy Codex full-access sandbox marker.
+   * This is retained as diagnostic/context only; exec-policy.ts does not trust it as
+   * native local exec authorization because the text is caller-controlled.
    */
   requestDeclaresFullAccess?: boolean;
 }

package/src/adapters/cursor/types.ts

@@ -1,8 +1,11 @@
 import type { OcxUsage } from "../../types";
 import type { OcxMessage, OcxRequestOptions, OcxTool } from "../../types";
+import type { CursorRoutingLevel } from "./discovery";
 
 export interface CursorRunRequest {
   modelId: string;
+  /** Cursor Router optimization parameter; valid only while modelId is the `default` wire model. */
+  routingLevel?: CursorRoutingLevel;
   conversationId: string;
   system: string[];
   messages: CursorRequestMessage[];
@@ -10,6 +13,17 @@ export interface CursorRunRequest {
   tools?: OcxTool[];
   toolChoice?: OcxRequestOptions["toolChoice"];
   parallelToolCalls?: boolean;
+  /**
+   * Clear provider-private context-usage carry-forward before this run. Used when Codex starts a
+   * newly observed compacted context epoch, so pre-compaction totals are not over-reported while
+   * historical previous_response_id replay remains idempotent.
+   */
+  contextUsageReset?: boolean;
+  /**
+   * Defaults to true. Set false for compaction summarizer turns: their checkpoints describe the
+   * pre-compaction history being summarized and must not become the next turn's carry-forward total.
+   */
+  contextUsageStoreCheckpoints?: boolean;
 }
 
 export interface CursorRequestMessage {

package/src/adapters/kiro-constants.ts

@@ -0,0 +1,12 @@
+export const KIRO_COMPLETION_TOOL_NAME = "codex_kiro_final_answer";
+export const KIRO_CONTINUATION_MESSAGE = "[system: conversation continues]";
+export const KIRO_COMPLETION_RETRY_MESSAGE =
+  `[system: The preceding assistant output did not explicitly complete the turn. 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_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

@@ -1,5 +1,13 @@
 import { parseUpstreamJsonPayload, safeUpstreamErrorString, sanitizeUpstreamErrorText } from "./upstream-http-error";
-const DETAIL_KEYS = ["__type", "code", "error", "name", "message", "Message", "errorMessage"];
+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));
@@ -79,10 +87,111 @@ function normalizedKiroErrorMessage(headers: Headers | Record<string, unknown>,
   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 normalizedKiroErrorMessage(headers, payloadText, status);
+  return classifyKiroFailure(headers, payloadText, status).message;
 }

package/src/adapters/kiro-events.ts

@@ -1,48 +1,167 @@
+import type { OcxUsage } from "../types";
 import { kiroTruncationReason } from "./kiro-truncation";
 
-export interface ParsedKiroEvent {
-  type: "content" | "tool_start" | "tool_input" | "tool_stop" | "truncation" | "usage" | "context_usage";
-  data?: string;
-  contextUsagePercentage?: number;
-  usage?: unknown;
-  name?: string;
-  toolUseId?: string;
-  input?: string;
+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 }
+  | { 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}`);
 }
 
-export function parseKiroEvent(payload: Uint8Array): ParsedKiroEvent | null {
-  let text: string;
+function parseObject(eventType: string, payload: Uint8Array): Record<string, unknown> {
+  let value: unknown;
   try {
-    text = new TextDecoder().decode(payload).trim();
+    value = JSON.parse(new TextDecoder().decode(payload));
   } catch {
-    return null;
+    return malformed(eventType, "expected valid JSON");
   }
-  if (!text.startsWith("{")) return null;
-  let parsed: Record<string, unknown>;
-  try {
-    parsed = JSON.parse(text);
-  } catch {
-    return null;
+  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);
   const truncationReason = kiroTruncationReason(parsed);
   if (truncationReason) return { type: "truncation", data: truncationReason };
-  if ("usage" in parsed) return { type: "usage", usage: parsed.usage };
-  if (typeof parsed.contextUsagePercentage === "number" && Number.isFinite(parsed.contextUsagePercentage)) {
-    return { type: "context_usage", contextUsagePercentage: parsed.contextUsagePercentage };
-  }
-  if ("content" in parsed && typeof parsed.content === "string") return { type: "content", data: parsed.content };
-  const toolUseId = typeof parsed.toolUseId === "string" ? parsed.toolUseId : undefined;
-  const name = typeof parsed.name === "string" ? parsed.name : undefined;
-  if (parsed.stop === true) return { type: "tool_stop", toolUseId };
-  if ("input" in parsed) {
-    const input =
-      typeof parsed.input === "object" && parsed.input !== null
-        ? JSON.stringify(parsed.input)
-        : typeof parsed.input === "string"
-          ? parsed.input
-          : "";
-    return { type: "tool_input", input, name, toolUseId };
+
+  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");
+      }
+      return {
+        type: "metadata",
+        ...(parseTokenUsage(eventType, parsed.tokenUsage) !== undefined
+          ? { usage: parseTokenUsage(eventType, parsed.tokenUsage) }
+          : {}),
+        ...(typeof contextUsagePercentage === "number" ? { contextUsagePercentage } : {}),
+      };
+    }
+    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"),
+      };
   }
-  if (name !== undefined) return { type: "tool_start", name, toolUseId };
   return null;
 }

package/src/adapters/kiro-retry.ts

@@ -1,6 +1,7 @@
 import type { AdapterFetchContext, AdapterRequest } from "./base";
 import { safeKiroHttpErrorMessage } from "./kiro-errors";
 import { normalizeUpstreamHttpErrorResponse } from "./upstream-http-error";
+import { readBoundedResponseBody } from "../lib/bounded-body";
 import {
   abortError,
   cancelResponseBodyBestEffort,
@@ -10,54 +11,137 @@ import {
   sleepWithAbort,
 } from "../lib/upstream-retry";
 
-const KIRO_RETRY_ATTEMPTS = 3;
-const KIRO_RETRY_BASE_MS = 250;
-const KIRO_RETRY_MAX_MS = 2_000;
+const RESET_ATTEMPTS = 3;
+const RESET_RETRY_BASE_MS = 150;
+const RESET_RETRY_MAX_MS = 1_000;
+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"]);
 
-function retryableKiroStatus(status: number): boolean {
-  return status === 429 || status === 500 || status === 502 || status === 503 || status === 504;
+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 retryableKiroFetchError(err: unknown): boolean {
-  return isConnectionResetError(err) || (err instanceof Error && err.name === "TimeoutError");
+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");
+  });
 }
 
-async function normalizeFinalKiroHttpError(res: Response, signal?: AbortSignal): Promise<Response> {
-  return normalizeUpstreamHttpErrorResponse(res, {
-    signal,
-    formatMessage: payloadText => safeKiroHttpErrorMessage(res.status, res.headers, payloadText),
-  });
+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();
 }
 
-export async function fetchKiroWithRetry(request: AdapterRequest, ctx: AdapterFetchContext = {}): Promise<Response> {
-  const timeoutMs = ctx.timeoutMs ?? 200_000;
+async function fetchWithResetRecovery(
+  request: AdapterRequest,
+  url: string,
+  ctx: AdapterFetchContext,
+  timeoutMs: number,
+): Promise<Response> {
   let lastError: unknown;
-  for (let attempt = 0; attempt < KIRO_RETRY_ATTEMPTS; attempt++) {
+  for (let attempt = 0; attempt < RESET_ATTEMPTS; attempt++) {
     if (ctx.abortSignal?.aborted) throw abortError(ctx.abortSignal);
     try {
-      const res = await fetchWithAttemptDeadline(request.url, {
+      const headers = new Headers(request.headers);
+      const recovered = attempt > 0;
+      if (recovered) headers.set("connection", "close");
+      return await fetchWithAttemptDeadline(url, {
         method: request.method,
-        headers: request.headers,
+        headers,
         body: request.body,
+        ...(recovered ? { keepalive: false } : {}),
       }, timeoutMs, ctx.abortSignal, ctx.stream);
-      if (!retryableKiroStatus(res.status) || attempt === KIRO_RETRY_ATTEMPTS - 1) {
-        return ctx.returnRawErrors ? res : normalizeFinalKiroHttpError(res, ctx.abortSignal);
-      }
-      cancelResponseBodyBestEffort(res);
-      await sleepWithAbort(retryBackoffDelayMs(attempt, {
-        baseDelayMs: KIRO_RETRY_BASE_MS,
-        maxDelayMs: KIRO_RETRY_MAX_MS,
-        headers: res.headers,
-      }), ctx.abortSignal);
-    } catch (err) {
-      if (ctx.abortSignal?.aborted) throw err;
-      if (!retryableKiroFetchError(err) || attempt === KIRO_RETRY_ATTEMPTS - 1) throw err;
-      lastError = err;
+    } catch (error) {
+      if (ctx.abortSignal?.aborted || !isConnectionResetError(error) || attempt === RESET_ATTEMPTS - 1) throw error;
+      lastError = error;
       await sleepWithAbort(retryBackoffDelayMs(attempt, {
-        baseDelayMs: KIRO_RETRY_BASE_MS,
-        maxDelayMs: KIRO_RETRY_MAX_MS,
+        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),
+  });
+}
+
+/**
+ * Kiro owns only replay-safe pre-header reset recovery and one canonical-to-legacy endpoint fallback.
+ * Client-level retry policy owns throttling, timeouts, and ordinary service failures.
+ */
+export async function fetchKiroWithRetry(request: AdapterRequest, ctx: AdapterFetchContext = {}): Promise<Response> {
+  const timeoutMs = ctx.timeoutMs ?? 200_000;
+  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;
+    response = await fetchWithResetRecovery(request, legacy, ctx, timeoutMs);
+    return ctx.returnRawErrors ? response : normalizeFinalKiroHttpError(response, ctx.abortSignal);
+  }
+
+  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 ctx.returnRawErrors ? response : normalizeFinalKiroHttpError(response, ctx.abortSignal);
+}