@bitkyc08/opencodex 2.41.0 → 2.43.0-preview.20260906

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/identity.ts

@@ -22,11 +22,17 @@ export const CODEX_GPT5_IDENTITY_LINE = "You are Codex, a coding agent based on
 export const CODEX_GPT5_IDENTITY_LINE_AGENT = "You are Codex, an agent based on GPT-5.";
 
 /**
- * Known Codex GPT-5 identity sentences. Narrow: only "coding agent" / "an agent" + GPT-5(.x)?
+ * Known Codex identity sentences. Narrow: only "coding agent" / "an agent" + GPT-<major>(.minor)*.
  * Avoid a broad `You are Codex.*` rewrite that could touch unrelated content.
+ *
+ * The major version is a wildcard because Codex writes the CURRENT generation into this line and
+ * bumps it: `gpt-6-astra` (upstream #42607) ships "You are Codex, an agent based on GPT-6.".
+ * Pinning `GPT-5` meant a GPT-6-era prompt routed to a third-party provider kept telling that
+ * model it was Codex-on-GPT-6 — the exact misattribution this chokepoint exists to remove, silently
+ * reintroduced by a version bump.
  */
 const CODEX_GPT5_IDENTITY_RE =
-  /You are Codex, (?:a coding agent|an agent) based on GPT-5(?:\.[0-9]+)*\./g;
+  /You are Codex, (?:a coding agent|an agent) based on GPT-[0-9]+(?:\.[0-9]+)*\./g;
 
 /** Proxy-neutral replacement: no "opencodex proxy" mention, just the GPT-5/OpenAI disclaimer. */
 export const NEUTRAL_IDENTITY_LINE = "You are a coding agent. Do not claim to be GPT-5 or to be made by OpenAI.";

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();
+}