@bitkyc08/opencodex 2.42.0 → 2.43.0

package/src/adapters/cursor/tool-schemas.ts

@@ -0,0 +1,195 @@
+import type { OcxTool } from "../../types";
+import { CODEX_SHELL_COMMAND_TOOL, isBareCodexExecCommandTool, isBareCodexShellBridgeTool, isCodexShellBridgeToolName } from "./tool-naming";
+
+export const CURSOR_EXEC_COMMAND_INPUT_SCHEMA = {
+  type: "object",
+  properties: {
+    cmd: { type: "string", description: "Shell command to execute." },
+    workdir: { type: "string", description: "Working directory for the command. Defaults to the turn cwd." },
+    shell: { type: "string", description: "Shell binary to launch. Defaults to the user's default shell." },
+    tty: { type: "boolean", description: "True allocates a PTY for the command; false or omitted uses plain pipes." },
+    yield_time_ms: { type: "number", description: "Wait before yielding output. Defaults to 10000 ms; effective range is 250-30000 ms." },
+    max_output_tokens: { type: "number", description: "Output token budget. Defaults to 10000 tokens; larger requests may be capped by policy." },
+  },
+  required: ["cmd"],
+  additionalProperties: false,
+} as const;
+
+/**
+ * Structured single-replacement schema advertised to Cursor models in addition to the freeform
+ * `apply_patch` tool. Cursor-trained models reliably emit exact-match replacements (the native
+ * Edit shape) but cannot produce Codex's freeform patch grammar, so every file edit attempt on the
+ * Cursor route produced malformed `apply_patch` payloads that the Codex client rejected locally
+ * (#1017). Calls to this tool are converted server-side into a valid apply_patch payload.
+ */
+export const CURSOR_EDIT_FILE_INPUT_SCHEMA = {
+  type: "object",
+  properties: {
+    file_path: { type: "string", description: "Path of the file to edit, relative to the workspace root." },
+    old_string: { type: "string", description: "Exact text to replace. Must match the current file content, including line breaks." },
+    new_string: { type: "string", description: "Replacement text. Empty removes the matched text." },
+  },
+  required: ["file_path", "old_string", "new_string"],
+  additionalProperties: false,
+} as const;
+
+/** Structured multi-replacement schema; mirrors Cursor's native MultiEdit shape. */
+export const CURSOR_MULTI_EDIT_INPUT_SCHEMA = {
+  type: "object",
+  properties: {
+    file_path: { type: "string", description: "Path of the file to edit, relative to the workspace root." },
+    edits: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          old_string: { type: "string", description: "Exact text to replace. Must match the current file content, including line breaks." },
+          new_string: { type: "string", description: "Replacement text. Empty removes the matched text." },
+        },
+        required: ["old_string", "new_string"],
+        additionalProperties: false,
+      },
+      description: "Ordered replacement edits for this file. Each old_string must match the current file content.",
+    },
+  },
+  required: ["file_path", "edits"],
+  additionalProperties: false,
+} as const;
+
+/**
+ * Responses/Codex-side schema used ONLY for arg-key normalization after Cursor returns a call.
+ * Cursor models are trained to emit `cmd`; Codex `shell_command` / `exec_command` validate
+ * `command`. Keeping `cmd` out of this schema lets `normalizeArgKeys` rewrite `cmd` → `command`.
+ */
+export const CODEX_SHELL_BRIDGE_ARG_NORMALIZE_SCHEMA = {
+  type: "object",
+  properties: {
+    command: { type: "string", description: "Shell command to execute." },
+    workdir: { type: "string", description: "Working directory for the command. Defaults to the turn cwd." },
+    shell: { type: "string", description: "Shell binary to launch. Defaults to the user's default shell." },
+    tty: { type: "boolean", description: "True allocates a PTY for the command; false or omitted uses plain pipes." },
+    yield_time_ms: { type: "number", description: "Wait before yielding output. Defaults to 10000 ms; effective range is 250-30000 ms." },
+    max_output_tokens: { type: "number", description: "Output token budget. Defaults to 10000 tokens; larger requests may be capped by policy." },
+    max_output_chars: { type: "number", description: "Output character budget when the Responses tool uses chars instead of tokens." },
+  },
+  required: ["command"],
+} as const;
+
+
+/** Schema advertised to Cursor for this tool (may use Cursor-preferred field names like `cmd`). */
+export function cursorToolInputSchema(tool: OcxTool): unknown {
+  return isBareCodexExecCommandTool(tool) ? CURSOR_EXEC_COMMAND_INPUT_SCHEMA : (tool.parameters ?? {});
+}
+
+/**
+ * Schema used to normalize completed Cursor tool args back to Responses/Codex field names.
+ * Must NOT reuse `cursorToolInputSchema` for the shell bridge: advertising `cmd` while also
+ * treating `cmd` as canonical prevents the `cmd` → `command` rewrite Codex requires (#399).
+ */
+export function cursorToolArgNormalizeSchema(tool: OcxTool): unknown {
+  if (isBareCodexShellBridgeTool(tool)) {
+    return shellBridgeArgNormalizeSchema(tool);
+  }
+  return tool.parameters ?? {};
+}
+
+function shellBridgeArgNormalizeSchema(tool: OcxTool): unknown {
+  const parameters = tool.parameters;
+  if (!parameters || typeof parameters !== "object") return CODEX_SHELL_BRIDGE_ARG_NORMALIZE_SCHEMA;
+  const base = parameters as Record<string, unknown>;
+  const rawProps = base.properties && typeof base.properties === "object"
+    ? { ...(base.properties as Record<string, unknown>) }
+    : {};
+  const required = Array.isArray(base.required) ? [...base.required as unknown[]] : [];
+  const requiresCommand = required.includes("command") || "command" in rawProps;
+  const requiresCmd = required.includes("cmd") || "cmd" in rawProps;
+  const shouldRewriteCmdToCommand = tool.name === CODEX_SHELL_COMMAND_TOOL || requiresCommand;
+
+  if (!shouldRewriteCmdToCommand && requiresCmd) {
+    return parameters;
+  }
+
+  // Drop Cursor-preferred aliases so normalizeArgKeys can rewrite them to Responses keys.
+  delete rawProps.cmd;
+  const properties = {
+    ...CODEX_SHELL_BRIDGE_ARG_NORMALIZE_SCHEMA.properties,
+    ...rawProps,
+    command: rawProps.command ?? CODEX_SHELL_BRIDGE_ARG_NORMALIZE_SCHEMA.properties.command,
+  };
+  return {
+    ...base,
+    type: "object",
+    properties,
+    required: requiresCommand ? required : ["command"],
+  };
+}
+
+/**
+ * Required command payload keys for a shell bridge tool, derived from the advertised schema when present.
+ */
+export function shellBridgeRequiredCommandKeys(
+  toolName: string,
+  schema?: unknown,
+): readonly ("cmd" | "command")[] {
+  if (schema && typeof schema === "object") {
+    const required = (schema as Record<string, unknown>).required;
+    if (Array.isArray(required)) {
+      const keys = required.filter((key): key is "cmd" | "command" => key === "cmd" || key === "command");
+      if (keys.length > 0) return keys;
+    }
+  }
+  return toolName === CODEX_SHELL_COMMAND_TOOL ? ["command"] : ["cmd"];
+}
+
+/** Normalize-schema defaults used when validating stateless synthetic shell-bridge calls. */
+export function defaultShellBridgeArgNormalizeSchema(toolName: string): unknown {
+  return toolName === CODEX_SHELL_COMMAND_TOOL
+    ? CODEX_SHELL_BRIDGE_ARG_NORMALIZE_SCHEMA
+    : {
+      type: "object",
+      properties: CURSOR_EXEC_COMMAND_INPUT_SCHEMA.properties,
+      required: ["cmd"],
+    };
+}
+
+export function cursorShellBridgeDropError(toolName: string): string {
+  return `Cursor emitted ${toolName} without a non-empty command; the tool call was dropped.`;
+}
+
+/**
+ * Extract a non-empty shell command from completed Cursor bridge args using the schema's required
+ * command key (`cmd` for bare exec_command, `command` for shell_command).
+ */
+export function nonEmptyShellBridgeCommandFromArgs(
+  finalArgs: string,
+  toolName: string,
+  schema?: unknown,
+): string | undefined {
+  let parsed: unknown;
+  try {
+    parsed = finalArgs.length > 0 ? JSON.parse(finalArgs) : {};
+  } catch {
+    return undefined;
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
+  const record = parsed as Record<string, unknown>;
+  const requiredKeys = shellBridgeRequiredCommandKeys(toolName, schema);
+  const candidateKeys = new Set<"cmd" | "command">([
+    ...requiredKeys,
+    requiredKeys.includes("cmd") ? "command" : "cmd",
+  ]);
+  for (const key of candidateKeys) {
+    const value = record[key];
+    if (typeof value === "string" && value.trim().length > 0) return value.trim();
+  }
+  return undefined;
+}
+
+export function cursorShellBridgeArgsValid(
+  finalArgs: string,
+  toolName: string,
+  schema?: unknown,
+): boolean {
+  return !isCodexShellBridgeToolName(toolName)
+    || nonEmptyShellBridgeCommandFromArgs(finalArgs, toolName, schema) !== undefined;
+}

package/src/adapters/cursor/types.ts

@@ -31,7 +31,7 @@ export interface CursorRunRequest {
   /**
    * Corrective active-turn text for the single envelope-echo retry (devlog 260826 gap-10).
    * When set on an external tool-result continuation, buildPreparedCursorRunRequest uses it as
-   * the userMessageAction text instead of the standard continuation text; rawMessages stay
+   * the userMessageAction prefix instead of the standard continuation text; rawMessages stay
    * untouched so history replay is unchanged.
    */
   echoRetryContinuationText?: string;
@@ -40,9 +40,12 @@ export interface CursorRunRequest {
   messages: CursorRequestMessage[];
   rawMessages?: readonly OcxMessage[];
   /**
-   * Images for the active user/developer turn. Encoded as SelectedImage blobIdWithData refs under
+   * Images for the active user/developer turn or an external model's trailing tool-result run.
+   * Encoded as SelectedImage blobIdWithData refs under
    * UserMessage.selected_context (bytes live in the request-scoped KV store for getBlobArgs
-   * hydration). History stays text-only. data: URLs only in this slice.
+   * hydration). Bounded sourceLabel metadata from tool images is appended to the active action,
+   * outside prunable history; it is not a new image wire field. Native Composer selection stays
+   * unchanged. History stays text-only. data: URLs only in this slice.
    */
   selectedImages?: readonly ResolvedCursorImage[];
   tools?: OcxTool[];

package/src/adapters/exec-tool-result-normalize.ts

@@ -113,7 +113,7 @@ export const EMPTY_EXEC_OUTPUT_MESSAGE =
  * that drifts apart is how a model gets told two different things about the same isolate.
  */
 export const CODE_MODE_RESULT_ECHO_SENTENCE =
-  "Nothing in the isolate is echoed automatically: a bare trailing `await tools.<name>(...)` or final expression value is DISCARDED, and the cell reports empty output. Pass anything you need to read to `text(...)` (or `notify(...)`) in the same cell — for example `text(JSON.stringify(await tools.exec_command({cmd: \"ls\"})))` — and treat an empty result as your own missing `text(...)` call rather than a failed command or lost context.";
+  "Nothing in the isolate is echoed automatically: a bare trailing `await tools.<name>(...)` or final expression value is DISCARDED, and the cell reports empty output. Pass anything you need to read to `text(...)` (or `notify(...)`) in the same cell — for example `text(JSON.stringify(await tools.exec_command({cmd: 'ls'})))` — and treat an empty result as your own missing `text(...)` call rather than a failed command or lost context.";
 
 /**
  * Codex exec / shell-bridge tool names (flat and MCP-prefixed display aliases). An empty result

package/src/adapters/google-errors.ts

@@ -1,4 +1,5 @@
 import { parseUpstreamJsonPayload, safeUpstreamErrorString, sanitizeUpstreamErrorText } from "./upstream-http-error";
+import { isLocationUnsupportedMessage } from "../lib/errors";
 
 /** Pull the human detail out of the Google API error envelope `{error:{message,status,code}}`. */
 function googleErrorDetail(payloadText: string): { message?: string; status?: string } {
@@ -65,9 +66,16 @@ function classifyGoogle(label: string, status: number | undefined, enumStatus: s
   if (status === 401 || enumStatus === "UNAUTHENTICATED" || lower.includes("unauthenticated") || lower.includes("invalid authentication") || lower.includes("expired")) {
     return `${label} authentication failed`;
   }
-  if (status === 403 || enumStatus === "PERMISSION_DENIED" || lower.includes("permission denied") || lower.includes("access denied")) {
+  if (status === 403 || enumStatus === "PERMISSION_DENIED" || lower.includes("permission_denied") || lower.includes("permission denied") || lower.includes("access denied")) {
     return `${label} access denied`;
   }
+  // Google rejects unsupported geographic / datacenter locations with HTTP 400
+  // FAILED_PRECONDITION. The payload is not malformed, so it must not fall through to
+  // "invalid request" (#3467). Only the observed 400/precondition envelope permits
+  // this inference; other explicit enums and server statuses remain authoritative.
+  if (status === 400 && (!enumStatus || enumStatus === "FAILED_PRECONDITION") && isLocationUnsupportedMessage(lower)) {
+    return `${label} location not supported`;
+  }
   if (status === 503 || enumStatus === "UNAVAILABLE" || lower.includes("overloaded") || lower.includes("unavailable")) {
     return `${label} server overloaded`;
   }

package/src/adapters/google.ts

@@ -52,6 +52,7 @@ const GOOGLE_BREVITY_INSTRUCTION = [
   "- Do detailed reasoning internally, not as visible intermediate output.",
   "- Prefer taking the next tool action over explaining; keep calling tools until the task is complete.",
   "- This applies only to intermediate progress text. Your final answer after the work is done is exempt: write it in full and at whatever length the task requires.",
+  "- Formatting: The client environment renders standard Markdown and does not support LaTeX math delimiters ($...$, $$...$$, \\(...\\), \\[...\\]). Do not use LaTeX math delimiters or LaTeX markup (such as \\text{}, \\times, \\le, \\ge, etc.) for variables, formulas, dimensions, or units. Use clean plain text, Markdown, and Unicode symbols (e.g. 180°, 2560 × 1920 px, ≤, ≥, Δ, ±) instead.",
 ].join("\n");
 
 const ANTIGRAVITY_REJECTED_CLAUDE_SDK_PARAGRAPH =

package/src/adapters/kiro-calibration.ts

@@ -0,0 +1,181 @@
+/**
+ * Per-conversation calibration of the Kiro input estimate.
+ *
+ * The estimator in `lib/token-estimate` is a fixed heuristic: constants derived from recorded
+ * traffic, applied to every account and every conversation identically. It is close on average
+ * and necessarily wrong in the particular, because how densely a prompt tokenizes depends on
+ * what is in it — a Korean design discussion and a repository of minified JSON do not share a
+ * ratio, and no constant can serve both.
+ *
+ * Kiro, however, tells us the answer. Mid-stream it reports `contextUsagePercentage`, which
+ * against a known window is an authoritative token count for the exact payload just sent. Today
+ * that number is used once, as a floor under the current turn's total, and then discarded. The
+ * conversation's own measured tokens-per-character is therefore recomputed from scratch, and
+ * mispredicted the same way, on every single turn.
+ *
+ * This module keeps it. After a TERMINAL attempt that produced both an estimate and a reported
+ * percentage, the realised ratio `charged / estimated` is folded into a per-conversation
+ * correction and applied to the next turn of that conversation, so a long conversation converges
+ * on the rate it actually exhibits rather than the rate the average conversation exhibits.
+ *
+ * "Terminal" matters: the adapter's bounded completion retry streams a second time for the same
+ * user turn against a rebuilt payload, so the caller commits an observation only once that turn
+ * is genuinely over.
+ *
+ * Four properties keep this from being able to make the gauge worse:
+ *
+ * - **Bounded.** The factor is clamped, so a single anomalous reading cannot distort the
+ *   estimate by an unbounded amount, and a malformed or hostile percentage cannot either.
+ * - **Smoothed.** Each observation moves the factor part of the way rather than replacing it, so
+ *   one cache-affected or truncated turn cannot swing the gauge.
+ * - **Bounded in memory.** Conversation-scoped with an eviction cap and no persistence. This is
+ *   a hint that improves with use, not state anything depends on.
+ * - **Subordinate to the truth.** The existing upstream floor is untouched. Calibration only
+ *   sharpens the estimate BEFORE upstream reports; it can never lower a value upstream has
+ *   already justified.
+ *
+ * Deliberately not in `lib/token-estimate`: that module is pure, shared by every provider, and
+ * must stay so. This is Kiro-specific state and lives with the Kiro adapter.
+ */
+
+/**
+ * Clamp for the correction factor.
+ *
+ * Wide enough to absorb the genuine spread between conversation kinds, narrow enough that a
+ * wrong reading cannot produce a nonsensical gauge. A factor below 1 shrinks the estimate, so
+ * the lower bound is the more dangerous side and is kept nearer 1.
+ */
+const MIN_FACTOR = 0.7;
+const MAX_FACTOR = 3;
+
+/**
+ * Weight given to a new observation. 0.35 reaches most of the way to a persistent new rate
+ * within a few turns while still requiring more than one reading to move far.
+ */
+const SMOOTHING = 0.35;
+
+/**
+ * Maximum conversations tracked. Entries are small, but the map must not grow with uptime.
+ *
+ * Eviction is least-recently-USED, not oldest-inserted: `touch` re-inserts on every estimate and
+ * every observation, so an active long conversation survives an arbitrary number of short ones
+ * started after it. Insertion order would have evicted exactly the conversation most worth
+ * keeping.
+ */
+const MAX_TRACKED_CONVERSATIONS = 256;
+
+/**
+ * A ratio this far from 1 is not a mis-calibrated estimate, it is a different measurement:
+ * a compaction, a cache boundary, or a percentage reported against a window we did not expect.
+ * Learning from it would teach the wrong lesson, so it is ignored entirely.
+ */
+const MAX_PLAUSIBLE_OBSERVATION = 6;
+
+/**
+ * One conversation's calibration state.
+ *
+ * `factor` is the learned correction. `rawEstimate` is the uncorrected estimate most recently
+ * applied: the stream records what upstream charged, but by then the value it holds has already
+ * been corrected, and learning from that would make the factor measure its own residual error
+ * instead of the heuristic's — each round would close only the part it had not yet fixed and the
+ * factor would converge short of the true ratio.
+ *
+ * Both live in ONE entry so they cannot desynchronise. Held as two maps, a conversation could be
+ * refreshed in one and evicted from the other, and the pair could retain twice the documented
+ * bound in distinct ids.
+ */
+interface Calibration {
+  factor?: number;
+  rawEstimate?: number;
+}
+
+/** Insertion-ordered, so the first key is the least recently touched entry. */
+const calibrations = new Map<string, Calibration>();
+
+/** Re-insert to move an entry to the most-recently-used end, then evict from the old end. */
+function touch(conversationId: string, update: (current: Calibration) => Calibration): void {
+  const current = calibrations.get(conversationId) ?? {};
+  calibrations.delete(conversationId);
+  calibrations.set(conversationId, update(current));
+  while (calibrations.size > MAX_TRACKED_CONVERSATIONS) {
+    const oldest = calibrations.keys().next();
+    if (oldest.done) break;
+    calibrations.delete(oldest.value);
+  }
+}
+
+function clamp(value: number): number {
+  return Math.min(MAX_FACTOR, Math.max(MIN_FACTOR, value));
+}
+
+/**
+ * Record what a conversation was actually charged against what we estimated.
+ *
+ * `estimated` must be the RAW estimate — what the fixed heuristic produced before any correction
+ * was applied — and `charged` the token count implied by the upstream percentage. Passing the
+ * already-corrected value instead would make the factor measure its own residual error rather
+ * than the heuristic's, so each round would learn only the part it had not yet fixed and the
+ * factor would settle short of the true ratio, permanently under-correcting.
+ *
+ * Non-finite, non-positive, or implausible inputs are ignored rather than clamped, because a bad
+ * reading carries no information worth smoothing in.
+ */
+export function recordKiroCalibration(
+  conversationId: string | undefined,
+  estimated: number,
+  charged: number,
+): void {
+  if (!conversationId) return;
+  if (!Number.isFinite(estimated) || !Number.isFinite(charged)) return;
+  if (estimated <= 0 || charged <= 0) return;
+  const entry = calibrations.get(conversationId);
+  // Prefer the raw estimate recorded at build time; fall back to the caller's value when this
+  // conversation was never seen by `calibrateKiroEstimate` (a first turn, or a rebuilt retry).
+  const baseline = entry?.rawEstimate ?? estimated;
+  if (!Number.isFinite(baseline) || baseline <= 0) return;
+  const observed = charged / baseline;
+  if (!Number.isFinite(observed) || observed <= 0 || observed > MAX_PLAUSIBLE_OBSERVATION) return;
+
+  // Smooth from 1 (the "no correction" prior) on the FIRST observation too. Jumping straight to
+  // `clamp(observed)` would let a single cache-affected or truncated turn set the factor outright,
+  // which is exactly the swing the smoothing exists to prevent.
+  const previous = entry?.factor ?? 1;
+  const next = clamp(previous + (observed - previous) * SMOOTHING);
+
+  // The observation for this turn is consumed: dropping the raw estimate keeps a later record for
+  // the same conversation from being scored a second time against a stale baseline, which would
+  // re-learn the same correction from a payload that has since grown.
+  touch(conversationId, () => ({ factor: next }));
+}
+
+/**
+ * Apply a conversation's learned correction to an estimate. Unknown conversations are returned
+ * unchanged, so the first turn behaves exactly as it did before calibration existed.
+ */
+export function calibrateKiroEstimate(conversationId: string | undefined, estimate: number): number {
+  if (!conversationId || !Number.isFinite(estimate) || estimate <= 0) return estimate;
+  touch(conversationId, current => ({ ...current, rawEstimate: estimate }));
+  const factor = calibrations.get(conversationId)?.factor;
+  return factor === undefined ? estimate : Math.ceil(estimate * factor);
+}
+
+/**
+ * Carry a conversation's state to the id upstream actually returned.
+ *
+ * The estimate is stored under the id the request was BUILT with, but Kiro can answer with a
+ * different conversation id, and the stream then records under that one. Without this the record
+ * would miss its own raw estimate and silently fall back to the corrected value — the exact
+ * feedback bug the raw estimate exists to avoid.
+ */
+export function rekeyKiroCalibration(fromConversationId: string | undefined, toConversationId: string | undefined): void {
+  if (!fromConversationId || !toConversationId || fromConversationId === toConversationId) return;
+  const entry = calibrations.get(fromConversationId);
+  if (!entry) return;
+  calibrations.delete(fromConversationId);
+  touch(toConversationId, current => ({ ...current, ...entry }));
+}
+
+/** Test seam: drop all learned state. */
+export function resetKiroCalibration(): void {
+  calibrations.clear();
+}

package/src/adapters/kiro.ts

@@ -5,6 +5,7 @@ import { resolveKiroApiRegion, resolveKiroRequestProfile } from "../oauth/kiro";
 import { KIRO_MODEL_CONTEXT_WINDOWS, normalizeKiroModelId } from "../providers/kiro-models";
 import { modelRecordValue } from "../reasoning-effort";
 import { parseKiroEvent } from "./kiro-events";
+import { calibrateKiroEstimate, recordKiroCalibration, rekeyKiroCalibration } from "./kiro-calibration";
 import {
   classifyKiroEventError,
   classifyKiroHttpError,
@@ -186,6 +187,85 @@ function estimateKiroTokens(text: string, modelId?: string): number {
   return estimateTokens(text, modelId ? `kiro/${modelId}` : "kiro");
 }
 
+/** Hangul/Han/kana ranges, matching the shared estimator's own CJK classification. */
+function kiroCjkCount(text: string): number {
+  let cjk = 0;
+  for (let i = 0; i < text.length; i++) {
+    const c = text.charCodeAt(i);
+    if (
+      (c >= 0xac00 && c <= 0xd7a3) || (c >= 0x1100 && c <= 0x11ff) || (c >= 0x3130 && c <= 0x318f)
+      || (c >= 0x4e00 && c <= 0x9fff) || (c >= 0x3400 && c <= 0x4dbf) || (c >= 0x3040 && c <= 0x30ff)
+    ) cjk++;
+  }
+  return cjk;
+}
+
+/**
+ * Token estimate for walked payload text, with the wire expansion applied to the Latin portion
+ * only. Splitting here rather than inside the shared estimator keeps that module pure and
+ * provider-neutral: the expansion is a fact about Kiro's wire, not about tokenization.
+ */
+function estimateKiroWireTokens(text: string, modelId: string): number {
+  if (!text) return 0;
+  const cjk = kiroCjkCount(text);
+  if (cjk === 0) return Math.ceil(estimateKiroTokens(text, modelId) * KIRO_LATIN_WIRE_EXPANSION);
+  const latinTokens = estimateKiroTokens("x".repeat(text.length - cjk), modelId);
+  const cjkTokens = estimateKiroTokens("\uac00".repeat(cjk), modelId);
+  return Math.ceil(latinTokens * KIRO_LATIN_WIRE_EXPANSION + cjkTokens);
+}
+
+/**
+ * Structural cost of one conversation entry, in tokens.
+ *
+ * The walker below concatenates message TEXT, but the wire carries JSON: per-entry keys
+ * (`userInputMessage`, `content`, `modelId`, `origin`) and role framing. That is charged
+ * upstream and is invisible to a text-only count, so without it a long conversation drifts
+ * further below the real charge with every turn added — an error proportional to entry COUNT,
+ * which no per-character ratio can recover.
+ *
+ * Regressing serialized bodies against what the walker counts, over eleven payload sizes from
+ * 3 to 701 entries:
+ *
+ *     bodyBytes = 1.0422 * walkedChars + 66.7 * entries + 68
+ *
+ * 66.7 bytes at the measured 2.433 bytes per charged token is 27.4 tokens per entry. The
+ * earlier value of 12 was a conservative hand-fit taken before that regression existed, and
+ * being less than half the real cost is precisely why the estimate decayed with conversation
+ * length: an under-charge of ~15 tokens per entry is invisible across four messages and
+ * dominant across seven hundred.
+ *
+ * Cross-checked against 4,090 recorded requests, where real traffic averages 1,310 bytes per
+ * message: 66.7 bytes is 5% of that, so this term charges framing and is not quietly absorbing
+ * message content.
+ */
+const KIRO_ENTRY_FRAMING_TOKENS = 27;
+
+/**
+ * Multiplier reconciling the LATIN text estimate with what the wire charges for that same text.
+ *
+ * The shared estimator counts Latin text at 2.8 chars/token, while the wire charges 2.433 bytes
+ * per token at 1.0422 bytes per walked character — an effective 2.334 chars/token, and
+ * 2.8 / 2.334 = 1.199.
+ *
+ * The evidence that the split between this term and `KIRO_ENTRY_FRAMING_TOKENS` is right is its
+ * stability: holding framing at 27, the multiplier the charge implies stays within 1.189-1.209
+ * across a 230x range of conversation sizes. A mis-specified split drifts with size, and the
+ * earlier 1.12/12 pair did — its accuracy fell from 0.92 at four messages to 0.87 at seven
+ * hundred.
+ *
+ * LATIN ONLY, deliberately. 2.433 bytes/token is a property of this traffic mix, which is Latin
+ * and code. A Hangul character is three UTF-8 bytes but roughly one token, so its bytes-per-token
+ * is entirely different and a Latin-derived byte rate says nothing about it. Scaling CJK by this
+ * factor bills Hangul at 1.25 chars/token, against recorded ground truth that already places the
+ * shared 1.5 ratio at 0.90 of the authoritative count — an over-charge that would compact Korean
+ * threads early.
+ *
+ * This is NOT JSON escaping, despite what an earlier version of this comment claimed. Measured
+ * directly, `JSON.stringify` expands prose by 1.012 (Latin) to 1.019 (Korean), nowhere near 1.2.
+ * Escaping is real but small, and is already inside the byte measurement this factor comes from.
+ */
+const KIRO_LATIN_WIRE_EXPANSION = 1.2;
+
 function estimateKiroPayloadInputTokens(payload: Record<string, unknown>, modelId: string): number {
   const conversationState = (payload as {
     conversationState?: {
@@ -216,7 +296,9 @@ function estimateKiroPayloadInputTokens(payload: Record<string, unknown>, modelI
       if (assistant.toolUses?.length) parts.push(serializeForUsage(assistant.toolUses));
     }
   }
-  return estimateKiroTokens(parts.join("\n"), modelId) + imageTokens;
+  return estimateKiroWireTokens(parts.join("\n"), modelId)
+    + imageTokens
+    + entries.length * KIRO_ENTRY_FRAMING_TOKENS;
 }
 
 function shouldCountStablePromptOverhead(parsed: OcxParsedRequest): boolean {
@@ -990,6 +1072,11 @@ async function* parseKiroAttempt(
   // the attempt boundary. Anything the inner parser leaves behind is flushed before the terminal.
   const deferred: AdapterEvent[] = [];
   const retention = createKiroAttemptRetention(budget);
+  // Shared box: the inner parser stages its calibration observation here on the completion path,
+  // and this wrapper decides whether the attempt was terminal enough to commit it. A box rather
+  // than a return field because the completion path has a dozen terminal returns and threading a
+  // field through every one of them is exactly the kind of edit that misses one.
+  const attemptCalibration: { value?: { conversationId: string; estimated: number; charged: number } } = {};
   const attempt = parseKiroAttemptEvents(
     response,
     budget,
@@ -1001,12 +1088,22 @@ async function* parseKiroAttempt(
     conversationId,
     deferred,
     retention,
+    attemptCalibration,
     contextInputEstimate,
     priorEmittedOutput,
   );
   let handedOff = false;
   try {
     const result = yield* attempt;
+    // A staged observation only counts when this attempt is the LAST one for the user turn. An
+    // attempt that asks for the bounded fallback streams again against a rebuilt payload, so
+    // committing here would move the factor twice for one turn and score the second observation
+    // against a payload the first had already inflated.
+    const staged = attemptCalibration.value;
+    attemptCalibration.value = undefined;
+    if (staged && !result.needsFallback) {
+      recordKiroCalibration(staged.conversationId, staged.estimated, staged.charged);
+    }
     for (const event of deferred.splice(0)) {
       try { yield event; } finally { retention.releaseEvent(event); }
     }
@@ -1028,10 +1125,13 @@ async function* parseKiroAttemptEvents(
   conversationId: string | undefined,
   deferred: AdapterEvent[],
   retention: KiroAttemptRetention,
+  attemptCalibration: { value?: { conversationId: string; estimated: number; charged: number } },
   contextInputEstimate?: number,
   priorEmittedOutput = false,
 ): AsyncGenerator<AdapterEvent, KiroAttemptParseResult> {
   const emptyResult = (): KiroAttemptParseResult => ({ assistantText: "", sawReasoning: false });
+  // Every early return below is a failure path that stages nothing; only the completion path
+  // writes `attemptCalibration`, and the wrapper decides whether to commit it.
   if (!response.body) {
     return {
       ...emptyResult(),
@@ -1346,7 +1446,13 @@ async function* parseKiroAttemptEvents(
           if (ev.stopReason !== undefined) stopReason = ev.stopReason;
           break;
         case "message_metadata":
-          if (isValidKiroConversationId(ev.conversationId)) returnedConversationId = ev.conversationId;
+          if (isValidKiroConversationId(ev.conversationId)) {
+            // Kiro can answer under a different conversation id than the request was built with.
+            // Carry the calibration entry across so the record below finds its own raw estimate
+            // instead of silently falling back to the already-corrected value.
+            rekeyKiroCalibration(returnedConversationId, ev.conversationId);
+            returnedConversationId = ev.conversationId;
+          }
           break;
         case "content":
           if (ev.modelId) {
@@ -1475,6 +1581,29 @@ async function* parseKiroAttemptEvents(
         ...(contextWindowState.value ? { upstreamContextWindow: contextWindowState.value } : {}),
       });
     }
+    // Upstream just told us what this payload cost. The ratio between that and our pre-request
+    // estimate is this conversation's own measured error, and it is the only feedback the
+    // estimator ever receives.
+    //
+    // Staged, not recorded. An attempt that sets `needsFallback` is not over: the adapter rebuilds
+    // the payload and streams a second time for the SAME user turn. Learning here would apply the
+    // fresh factor to that rebuild and then learn again from it, so one turn would move the factor
+    // twice and the second observation would score a payload the first had already inflated. Only
+    // the outer parser knows whether an attempt is terminal, so it commits.
+    //
+    // Subtract the output first. `contextUsageTotalFloor` is the absolute context size AFTER the
+    // response (`OcxUsage.contextTotalTokens`, types/request.ts), while `contextInputEstimate`
+    // covers the request payload alone. Dividing one by the other would charge generated tokens to
+    // prompt-tokenization error, so a short prompt answered at length would learn a large factor
+    // and inflate every later request in that conversation — the premature compaction this work
+    // exists to prevent.
+    const chargedTotal = contextUsageTotalFloor();
+    if (chargedTotal !== undefined && contextInputEstimate !== undefined) {
+      const chargedInput = chargedTotal - finalUsage.outputTokens;
+      if (chargedInput > 0 && returnedConversationId) {
+        attemptCalibration.value = { conversationId: returnedConversationId, estimated: contextInputEstimate, charged: chargedInput };
+      }
+    }
     // Native stop metadata proves that this inference ended, but it does not prove that ordinary
     // text is a final answer. Kiro has emitted END_TURN for progress prose, so tool-enabled turns
     // still require the private completion call to distinguish commentary from completion (#531).
@@ -1934,7 +2063,10 @@ export function createKiroAdapter(provider: OcxProviderConfig): ProviderAdapter
     if (profileArn) headers["x-amzn-kiro-profile-arn"] = profileArn;
     const built = buildKiroPayload(parsed, profileArn, forcedCompletionMode, wireClient);
     await normalizeKiroImages(built.payload);
-    const contextInputEstimate = estimateKiroPayloadInputTokens(built.payload, parsed.modelId);
+    // Apply what earlier turns of THIS conversation measured. An unseen conversation is
+    // unchanged, so a first turn behaves exactly as it would without calibration.
+    const rawContextInputEstimate = estimateKiroPayloadInputTokens(built.payload, parsed.modelId);
+    const contextInputEstimate = calibrateKiroEstimate(built.conversationId, rawContextInputEstimate);
     const body = JSON.stringify(built.payload);
     debugProviderDiagnostic("kiro", "request", {
       region,