@bitkyc08/opencodex 2.6.17 → 2.6.18

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

@@ -0,0 +1,301 @@
+import { create, fromJson, toBinary, type JsonValue } from "@bufbuild/protobuf";
+import { ValueSchema } from "@bufbuild/protobuf/wkt";
+import type { OcxRequestOptions, OcxTool } from "../../types";
+import { namespacedToolName } from "../../types";
+import { McpToolDefinitionSchema, type McpToolDefinition } from "./gen/agent_pb";
+
+export const OCX_RESPONSES_TOOL_PROVIDER = "opencodex-responses";
+export const CODEX_EXEC_COMMAND_TOOL = "exec_command";
+export const CODEX_APPLY_PATCH_TOOL = "apply_patch";
+export const CURSOR_EXEC_COMMAND_TOOL = CODEX_EXEC_COMMAND_TOOL;
+export const CURSOR_SHELL_ALIAS_SYSTEM_NOTE = 'Shell commands use the `exec_command` tool with JSON arguments like {"cmd":"..."}.';
+export const CURSOR_SHELL_ALIAS_USER_HINT = "Use exec_command for this shell command.";
+const NEIGHBOR_AGENT_TOOL_NAMES = ["Read", "Grep", "Glob", "Bash", "LS"] as const;
+
+export const CURSOR_GENERIC_TOOL_USE_USER_HINT = [
+  "For generic tool-use/count demos, satisfy the request with repeated `exec_command` calls for harmless commands.",
+  "`exec_command` is the Codex Responses bridge exec tool exposed through Cursor's tool protocol; do not describe it as an external MCP server tool.",
+  "Do not use `run_shell` unless this turn's tool catalog lists it.",
+  "A request for N tools means N separate `exec_command` invocations/results; never satisfy it with one chained shell command such as `cmd1 && cmd2`.",
+  "For independent read-only or output-only commands, emit all requested `exec_command` calls in the same response before waiting when the runtime supports parallel tool calls.",
+  "The Cursor bridge may suspend after the first returned bridge tool call, so emit sibling calls together before any result is needed.",
+  "If parallel emission is unavailable, continue with separate `exec_command` calls until the requested count has returned.",
+  "Do not use `tool_search`, external MCP, or resource discovery just to pad the count unless explicitly asked.",
+  "Do not suggest or switch to neighboring-agent tools such as `Grep`, `Read`, `Glob`, `Bash`, or `LS` unless this turn's catalog lists those exact names.",
+].join(" ");
+
+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;
+
+function isBareCodexExecCommandTool(tool: Pick<OcxTool, "namespace" | "name">): boolean {
+  return !tool.namespace && tool.name === CODEX_EXEC_COMMAND_TOOL;
+}
+
+export function cursorRequestHasShellAlias(tools: readonly Pick<OcxTool, "namespace" | "name">[] | undefined): boolean {
+  return tools?.some(isBareCodexExecCommandTool) ?? false;
+}
+
+export function cursorRequestAdvertisesApplyPatch(
+  tools: readonly Pick<OcxTool, "namespace" | "name" | "freeform">[] | undefined,
+  toolChoice?: OcxRequestOptions["toolChoice"],
+): boolean {
+  return tools?.some(tool => !tool.namespace && tool.name === CODEX_APPLY_PATCH_TOOL && tool.freeform === true && toolChoiceAllows(tool, toolChoice)) ?? false;
+}
+
+export function cursorToolWireName(tool: Pick<OcxTool, "namespace" | "name">): string {
+  return namespacedToolName(tool.namespace, tool.name);
+}
+
+/**
+ * Cursor's harness shows MCP tools to the model as `mcp_<providerIdentifier>_<toolName>`; models
+ * sometimes call that display name verbatim instead of the advertised short name (live 20:41/21:00
+ * sessions: `mcp_opencodex-responses_exec_command`). Fold the display prefix back to the advertised
+ * wire name so both spellings resolve to the same client tool instead of "unknown Responses tool".
+ */
+const CURSOR_MCP_DISPLAY_PREFIX = `mcp_${OCX_RESPONSES_TOOL_PROVIDER}_`;
+
+export function normalizeCursorWireName(name: string): string {
+  return name.startsWith(CURSOR_MCP_DISPLAY_PREFIX) ? name.slice(CURSOR_MCP_DISPLAY_PREFIX.length) : name;
+}
+
+export function responsesToolNameFromCursorWire(name: string, cursorToolNameMap?: ReadonlyMap<string, string>): string {
+  const normalized = normalizeCursorWireName(name);
+  return cursorToolNameMap?.get(normalized) ?? normalized;
+}
+
+export function cursorToolInputSchema(tool: OcxTool): unknown {
+  return isBareCodexExecCommandTool(tool) ? CURSOR_EXEC_COMMAND_INPUT_SCHEMA : (tool.parameters ?? {});
+}
+
+function activeTextMentionsExecCommand(text: string): boolean {
+  return /\bexec_command\b/i.test(text);
+}
+
+function looksLikeShellCommandRequest(text: string): boolean {
+  const hasKnownCommand = /(?:^|[\s`$])(?:echo|pwd|ls|cat|grep|rg|find|python3?|node|bun|npm|pnpm|yarn|git|curl|wget|chmod|mkdir|rm|cp|mv|touch|docker|kubectl|make|cargo|go|pytest)(?=\s|$|[`:;|&])/i.test(text);
+  const hasRunIntent = /\b(?:run|execute|exec)\b/i.test(text) || /\b(?:stdout|stderr|exit\s+code)\b/i.test(text);
+  const hasShellTarget = /\b(?:shell|terminal|command|cmd)\b/i.test(text);
+  return /\b(?:run|execute|exec)\s*:/i.test(text) || hasKnownCommand || (hasRunIntent && hasShellTarget);
+}
+
+export function isGenericToolUseCountDemoPrompt(text: string): boolean {
+  const trimmed = text.trim();
+  if (trimmed.length === 0) return false;
+  return [
+    /\b(?:use|call|invoke|try|exercise)\s+(?:any\s+)?\d+\s+tools?\b/i,
+    /\buse\s+any\s+tools?\b/i,
+    /\bactually\s+(?:call|use|invoke)\s+(?:the\s+)?tools?\b/i,
+    /\b\d+\s+tools?\b/i,
+    /\btools?\s+\d+\b/i,
+    /\btool\s+use\b/i,
+    /아무\s*(?:tool|tools?|도구|툴)/i,
+    /(?:tool|tools?|도구|툴)\s*\d+\s*(?:개|번)?/i,
+    /\d+\s*(?:개|번)?\s*(?:tool|tools?|도구|툴)/i,
+    /(?:도구|툴).{0,12}(?:써|사용|호출).{0,12}\d+\s*(?:개|번)?/i,
+  ].some(pattern => pattern.test(trimmed));
+}
+
+export function requestedCursorToolUseCount(text: string): number | undefined {
+  const patterns = [
+    /\b(?:use|call|invoke|try|exercise)\s+(?:any\s+)?(\d+)\s+tools?\b/i,
+    /\b(\d+)\s+tools?\b/i,
+    /\btools?\s+(\d+)\b/i,
+    /(?:tool|tools?|도구|툴)\s*(\d+)\s*(?:개|번)?/i,
+    /(\d+)\s*(?:개|번)?\s*(?:tool|tools?|도구|툴)/i,
+    /(?:도구|툴).{0,12}(?:써|사용|호출).{0,12}(\d+)\s*(?:개|번)?/i,
+  ];
+  for (const pattern of patterns) {
+    const match = pattern.exec(text);
+    const count = Number(match?.[1]);
+    if (Number.isInteger(count) && count > 0 && count <= 50) return count;
+  }
+  return undefined;
+}
+
+function cursorGenericToolUseHint(text: string): string {
+  const count = requestedCursorToolUseCount(text);
+  if (!count) return CURSOR_GENERIC_TOOL_USE_USER_HINT;
+  return [
+    `This turn requests ${count} tool uses: emit exactly ${count} separate \`exec_command\` function calls/results.`,
+    `One \`exec_command\` containing chained commands counts as 1 tool call, not ${count}.`,
+    `Prefer one parallel tool-call batch containing all ${count} independent \`exec_command\` calls before waiting for results.`,
+    CURSOR_GENERIC_TOOL_USE_USER_HINT,
+  ].join(" ");
+}
+
+function activeTextMentionsGenericToolUseHint(text: string): boolean {
+  return text.includes("Codex native exec tool")
+    || text.includes("Codex Responses bridge exec tool")
+    || text.includes("generic tool-use/count demos");
+}
+
+export function shouldAppendCursorGenericToolUseHint(
+  tools: readonly Pick<OcxTool, "namespace" | "name">[] | undefined,
+  text: string,
+): boolean {
+  const trimmed = text.trim();
+  return trimmed.length > 0
+    && cursorRequestHasShellAlias(tools)
+    && isGenericToolUseCountDemoPrompt(trimmed)
+    && !activeTextMentionsGenericToolUseHint(trimmed);
+}
+
+export function appendCursorGenericToolUseHint(
+  tools: readonly Pick<OcxTool, "namespace" | "name">[] | undefined,
+  text: string,
+): string {
+  if (!shouldAppendCursorGenericToolUseHint(tools, text)) return text;
+  return `${text}${text.endsWith("\n") ? "\n" : "\n\n"}${cursorGenericToolUseHint(text)}`;
+}
+
+export function shouldUseNativeExecOnlyForGenericToolUse(
+  tools: readonly Pick<OcxTool, "namespace" | "name">[] | undefined,
+  text: string,
+): boolean {
+  const trimmed = text.trim();
+  if (trimmed.length === 0 || !cursorRequestHasShellAlias(tools) || !isGenericToolUseCountDemoPrompt(trimmed)) return false;
+  return !/\b(?:mcp|resource|resources|tool_search|plugin|plugins|app connector|github)\b/i.test(trimmed)
+    && !/(?:리소스|플러그인|깃허브|github)/i.test(trimmed);
+}
+
+export function cursorToolsForActivePrompt<T extends Pick<OcxTool, "namespace" | "name">>(
+  tools: readonly T[] | undefined,
+  activeText: string,
+  toolChoice?: OcxRequestOptions["toolChoice"],
+): readonly T[] | undefined {
+  if (!shouldUseNativeExecOnlyForGenericToolUse(tools, activeText)) return tools;
+  const execTools = tools?.filter(isBareCodexExecCommandTool);
+  if (execTools?.length && !execTools.some(tool => toolChoiceAllows(tool, toolChoice))) return tools;
+  return execTools && execTools.length > 0 ? execTools : tools;
+}
+
+export function shouldAppendCursorShellAliasHint(
+  tools: readonly Pick<OcxTool, "namespace" | "name">[] | undefined,
+  text: string,
+): boolean {
+  const trimmed = text.trim();
+  return trimmed.length > 0
+    && cursorRequestHasShellAlias(tools)
+    && !activeTextMentionsExecCommand(trimmed)
+    && looksLikeShellCommandRequest(trimmed);
+}
+
+export function appendCursorShellAliasHint(
+  tools: readonly Pick<OcxTool, "namespace" | "name">[] | undefined,
+  text: string,
+): string {
+  if (!shouldAppendCursorShellAliasHint(tools, text)) return text;
+  return `${text}${text.endsWith("\n") ? "\n" : "\n\n"}${CURSOR_SHELL_ALIAS_USER_HINT}`;
+}
+
+function toolChoiceAllows(tool: Pick<OcxTool, "namespace" | "name">, toolChoice: OcxRequestOptions["toolChoice"] | undefined): boolean {
+  if (!toolChoice || toolChoice === "auto" || toolChoice === "required") return true;
+  if (toolChoice === "none") return false;
+  if ("allowedTools" in toolChoice) {
+    return toolChoice.allowedTools.includes(tool.name) || toolChoice.allowedTools.includes(cursorToolWireName(tool));
+  }
+  return tool.name === toolChoice.name || cursorToolWireName(tool) === toolChoice.name;
+}
+
+function quotedNames(names: readonly string[]): string {
+  return names.map(name => `\`${name}\``).join(", ");
+}
+
+function unavailableNeighborAgentToolNames(wireNames: readonly string[]): string[] {
+  const advertised = new Set(wireNames);
+  return NEIGHBOR_AGENT_TOOL_NAMES.filter(name => !advertised.has(name));
+}
+
+function discoveryToolLabel(wireNames: readonly string[]): string | undefined {
+  const labels: string[] = [];
+  if (wireNames.includes("tool_search")) labels.push("`tool_search`");
+  if (wireNames.some(name => name.startsWith("mcp__"))) labels.push("MCP");
+  if (wireNames.some(name => /resource/i.test(name))) labels.push("resource discovery");
+  return labels.length > 0 ? labels.join(", ") : undefined;
+}
+
+export function buildCursorToolGuidanceSystemNote(
+  tools: readonly Pick<OcxTool, "namespace" | "name" | "freeform">[] | undefined,
+  toolChoice?: OcxRequestOptions["toolChoice"],
+): string | undefined {
+  if (!tools?.length) return undefined;
+  const wireNames = [...new Set(
+    tools
+      .filter(tool => toolChoiceAllows(tool, toolChoice))
+      .map(tool => cursorToolWireName(tool)),
+  )];
+  if (wireNames.length === 0) return undefined;
+
+  const listedNames = quotedNames(wireNames);
+  const hasBareExec = wireNames.includes(CODEX_EXEC_COMMAND_TOOL);
+  const hasApplyPatch = cursorRequestAdvertisesApplyPatch(tools, toolChoice);
+  const discoveryTools = discoveryToolLabel(wireNames);
+  const unavailableNeighborNames = unavailableNeighborAgentToolNames(wireNames);
+  const notes = [
+    `Cursor tool calls: available tool names are exactly ${listedNames}.`,
+    "Use the current tool catalog as ground truth and call only those exact names with their listed argument keys.",
+    unavailableNeighborNames.length > 0
+      ? `This turn does not expose neighboring-agent tool names ${quotedNames(unavailableNeighborNames)}; do not call or suggest them unless the catalog lists them.`
+      : undefined,
+    hasBareExec
+      ? "`exec_command` is the Codex Responses bridge exec tool for this turn, exposed through Cursor's tool protocol; it is not an external MCP server tool."
+      : undefined,
+    hasBareExec
+      ? "Your tool list may display it under the longer name `mcp_opencodex-responses_exec_command`; both names are the SAME tool — call whichever your list shows, and do not comment on the naming difference to the user."
+      : undefined,
+    "Cursor product features (Chronicle, screen recording, Notes, Plans, background agents) are available only if this turn's catalog lists a matching tool; do not offer or promise them otherwise.",
+    hasBareExec
+      ? "For file read/search/listing, use `exec_command` when no more specific listed tool is available."
+      : undefined,
+    hasApplyPatch
+      ? "For file edits, use the `apply_patch` tool, not built-in file write/delete tools."
+      : undefined,
+    hasBareExec
+      ? "For tool-count demos, each counted tool must be a separate `exec_command` invocation/result; do not collapse several requested tools into one chained shell command."
+      : undefined,
+    "For independent read-only tool-count or batch requests, prefer one response containing multiple tool calls before waiting for results when the runtime supports parallel tool calls.",
+    hasBareExec
+      ? "For bridge tool-count batches, emit sibling `exec_command` calls together before any result is needed because the bridge may suspend after a returned tool call."
+      : undefined,
+    discoveryTools
+      ? `Use ${discoveryTools} only for explicit discovery/resource tasks, not generic tool-count demos.`
+      : undefined,
+    "Do not count or report a tool call unless a tool result was actually returned.",
+  ].filter((note): note is string => typeof note === "string");
+  return notes.join(" ");
+}
+
+export function encodeCursorInputSchema(schema: unknown): Uint8Array {
+  const value: JsonValue = schema && typeof schema === "object"
+    ? schema as JsonValue
+    : { type: "object", properties: {}, required: [] };
+  return toBinary(ValueSchema, fromJson(ValueSchema, value));
+}
+
+export function buildCursorToolDefinitions(
+  tools: readonly OcxTool[] | undefined,
+  toolChoice?: OcxRequestOptions["toolChoice"],
+): McpToolDefinition[] {
+  if (!tools?.length) return [];
+  return tools.filter(tool => toolChoiceAllows(tool, toolChoice)).map(tool => {
+    const wireName = cursorToolWireName(tool);
+    return create(McpToolDefinitionSchema, {
+      name: wireName,
+      toolName: wireName,
+      providerIdentifier: OCX_RESPONSES_TOOL_PROVIDER,
+      description: tool.description,
+      inputSchema: encodeCursorInputSchema(cursorToolInputSchema(tool)),
+    });
+  });
+}

package/src/adapters/cursor/transport-retry.ts

@@ -0,0 +1,116 @@
+import type { CursorRunRequest, CursorServerMessage } from "./types";
+import type { CursorTransport, CursorTransportFactory, CursorTransportFactoryInput } from "./transport";
+
+export const CURSOR_RETRY_ATTEMPTS = 3;
+export const CURSOR_RETRY_BASE_MS = 250;
+export const CURSOR_RETRY_MAX_MS = 2_000;
+
+/**
+ * True only for clearly transient failures that occur BEFORE the run request is committed to the
+ * wire (connection refused/reset/timeout, immediate HTTP/2 GOAWAY, gRPC/Connect "unavailable").
+ * Conservative by design: auth, invalid-request, and anything ambiguous is non-retryable so we
+ * never replay a turn the Cursor server might already have accepted.
+ */
+export function isRetryableCursorError(err: unknown): boolean {
+  const code = typeof err === "object" && err && "code" in err ? String((err as { code?: unknown }).code ?? "") : "";
+  const message = err instanceof Error ? err.message : typeof err === "string" ? err : "";
+  const haystack = `${code} ${message}`.toLowerCase();
+  if (/auth|unauthor|forbidden|invalid|permission|denied|not found|unsupported/.test(haystack)) return false;
+  return (
+    haystack.includes("econnreset") ||
+    haystack.includes("econnrefused") ||
+    haystack.includes("etimedout") ||
+    haystack.includes("enetunreach") ||
+    haystack.includes("eai_again") ||
+    haystack.includes("goaway") ||
+    haystack.includes("nghttp2") ||
+    haystack.includes("socket hang up") ||
+    haystack.includes("connection reset") ||
+    haystack.includes("unavailable") ||
+    haystack.includes("timed out")
+  );
+}
+
+export function cursorRetryDelayMs(attempt: number): number {
+  const exp = Math.min(CURSOR_RETRY_BASE_MS * 2 ** attempt, CURSOR_RETRY_MAX_MS);
+  return Math.floor(exp * (0.8 + Math.random() * 0.4));
+}
+
+function abortError(signal?: AbortSignal): unknown {
+  return signal?.reason ?? new DOMException("The operation was aborted", "AbortError");
+}
+
+export async function abortAwareSleep(ms: number, signal?: AbortSignal): Promise<void> {
+  if (ms <= 0) return;
+  if (signal?.aborted) throw abortError(signal);
+  await new Promise<void>((resolve, reject) => {
+    let timer: ReturnType<typeof setTimeout>;
+    const cleanup = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+    };
+    const onAbort = () => {
+      cleanup();
+      reject(abortError(signal));
+    };
+    timer = setTimeout(() => {
+      cleanup();
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+/**
+ * A transport is safe to retry only if it explicitly reports the run request was never committed.
+ * A transport without `requestCommitted` is treated as committed (not retryable) — fail safe.
+ */
+function requestUncommitted(transport: CursorTransport): boolean {
+  return typeof transport.requestCommitted === "function" && transport.requestCommitted() === false;
+}
+
+/**
+ * Run a Cursor turn with bounded retry on pre-commit transient failures.
+ *
+ * `onEvent` receives every server message. Retry happens only when ALL hold:
+ *  - nothing has been emitted yet this turn,
+ *  - the failing transport reports the run request was not committed to the wire,
+ *  - the error is a transient pre-commit failure.
+ * Otherwise the error propagates (the adapter maps it to a user-facing message).
+ */
+export async function runCursorTurnWithRetry(
+  makeTransport: (input: CursorTransportFactoryInput) => CursorTransport,
+  input: CursorTransportFactoryInput,
+  request: CursorRunRequest,
+  signal: AbortSignal | undefined,
+  onEvent: (message: CursorServerMessage, transport: CursorTransport) => void,
+): Promise<void> {
+  let lastError: unknown;
+  for (let attempt = 0; attempt < CURSOR_RETRY_ATTEMPTS; attempt++) {
+    if (signal?.aborted) throw abortError(signal);
+    const transport = makeTransport(input);
+    let emittedAny = false;
+    try {
+      for await (const message of transport.run(request, signal)) {
+        emittedAny = true;
+        onEvent(message, transport);
+      }
+      return;
+    } catch (err) {
+      lastError = err;
+      const canRetry =
+        !emittedAny &&
+        attempt < CURSOR_RETRY_ATTEMPTS - 1 &&
+        !signal?.aborted &&
+        requestUncommitted(transport) &&
+        isRetryableCursorError(err);
+      if (!canRetry) throw err;
+      await abortAwareSleep(cursorRetryDelayMs(attempt), signal);
+    } finally {
+      await transport.close?.();
+    }
+  }
+  throw lastError ?? new Error("Cursor transport failed");
+}
+
+export type { CursorTransportFactory };

package/src/adapters/cursor/transport.ts

@@ -0,0 +1,47 @@
+import type { OcxProviderConfig } from "../../types";
+import type { CursorClientMessage, CursorRunRequest, CursorServerMessage } from "./types";
+
+export interface CursorTransport {
+  run(request: CursorRunRequest, signal?: AbortSignal): AsyncIterable<CursorServerMessage>;
+  writeClient(message: CursorClientMessage): void | Promise<void>;
+  close?(): void | Promise<void>;
+  /**
+   * Whether the run request has been committed to the wire. The retry orchestrator only re-dials
+   * failures that happened BEFORE this becomes true, so a turn the Cursor server may already have
+   * accepted is never replayed. Absent (undefined) is treated as "committed" — safe by default.
+   */
+  requestCommitted?(): boolean;
+}
+
+export interface CursorTransportFactoryInput {
+  provider: OcxProviderConfig;
+  headers?: Headers;
+  /** Pre-first-frame deadline (dial + first server frame). Defaults to 30s when omitted. */
+  firstFrameTimeoutMs?: number;
+  /**
+   * Grace window (ms) before a drained client-tool turn is finalized, so a sibling tool call
+   * announced in a later receive chunk can revoke a premature finalize. Defaults to 50ms.
+   */
+  clientToolFinalizeGraceMs?: number;
+}
+
+export type CursorTransportFactory = (input: CursorTransportFactoryInput) => CursorTransport;
+
+export class CursorTransportDisabledError extends Error {
+  readonly code = "cursor_transport_disabled";
+
+  constructor(message = "live Cursor transport is disabled") {
+    super(message);
+    this.name = "CursorTransportDisabledError";
+  }
+}
+
+export function createDisabledCursorTransport(): CursorTransport {
+  return {
+    async *run() {
+      throw new CursorTransportDisabledError();
+    },
+    writeClient() {},
+    close() {},
+  };
+}

package/src/adapters/cursor/types.ts

@@ -0,0 +1,36 @@
+import type { OcxUsage } from "../../types";
+import type { OcxMessage, OcxRequestOptions, OcxTool } from "../../types";
+
+export interface CursorRunRequest {
+  modelId: string;
+  conversationId: string;
+  system: string[];
+  messages: CursorRequestMessage[];
+  rawMessages?: OcxMessage[];
+  tools?: OcxTool[];
+  toolChoice?: OcxRequestOptions["toolChoice"];
+  parallelToolCalls?: boolean;
+}
+
+export interface CursorRequestMessage {
+  role: "user" | "assistant" | "developer" | "tool";
+  content: string;
+}
+
+export type CursorServerMessage =
+  | { type: "text"; text: string }
+  | { type: "thinking"; thinking: string }
+  | { type: "tool_call_start"; id: string; name: string }
+  | { type: "tool_call_delta"; arguments: string }
+  | { type: "tool_call_end"; id?: string }
+  | { type: "done"; usage?: OcxUsage }
+  | { type: "error"; message: string; usage?: OcxUsage }
+  | { type: "heartbeat" }
+  | { type: "kv_get"; key: string }
+  | { type: "kv_set"; key: string; value: Uint8Array }
+  | { type: "exec"; execCase: string; requestId: string };
+
+export type CursorClientMessage =
+  | { type: "kv_value"; key: string; value?: Uint8Array }
+  | { type: "kv_stored"; key: string }
+  | { type: "exec_result"; requestId: string; ok: boolean; message: string };

package/src/adapters/cursor.ts

@@ -0,0 +1,99 @@
+import type { AdapterEvent, OcxProviderConfig } from "../types";
+import type { ProviderAdapter } from "./base";
+import { cursorExecDeniedMessage } from "./cursor/exec-policy";
+import { safeCursorErrorMessage } from "./cursor/cursor-errors";
+import { createCursorKvStore, type CursorKvStore } from "./cursor/kv-store";
+import { mapCursorServerMessage } from "./cursor/message-mapper";
+import { createCursorRequest, generatedCursorConversationId } from "./cursor/request-builder";
+import { createLiveCursorTransport, CursorMissingCredentialError } from "./cursor/live-transport";
+import { runCursorTurnWithRetry } from "./cursor/transport-retry";
+import {
+  createDisabledCursorTransport,
+  CursorTransportDisabledError,
+  type CursorTransportFactory,
+} from "./cursor/transport";
+
+export const CURSOR_API_URL = "https://api2.cursor.sh";
+
+export {
+  CURSOR_EXEC_CASES_DENIED,
+  cursorExecDeniedMessage,
+  type CursorDeniedExecCase,
+} from "./cursor/exec-policy";
+
+const CURSOR_TRANSPORT_DISABLED_MESSAGE = [
+  "An explicit disabled Cursor transport was injected.",
+  "Production Cursor requests use live transport when a Cursor access token is configured.",
+].join(" ");
+
+export interface CursorAdapterDeps {
+  createTransport?: CursorTransportFactory;
+  kv?: CursorKvStore;
+}
+
+function safeCursorTransportError(err: unknown): string {
+  if (err instanceof CursorTransportDisabledError) return CURSOR_TRANSPORT_DISABLED_MESSAGE;
+  if (err instanceof CursorMissingCredentialError) {
+    return "Cursor live transport is enabled, but no Cursor access token is configured. Set provider.apiKey or OPENCODEX_CURSOR_TEST_TOKEN.";
+  }
+  const message = err instanceof Error ? err.message : typeof err === "string" ? err : undefined;
+  if (message) return safeCursorErrorMessage(message);
+  return "Cursor upstream error: transport failed before completion.";
+}
+
+export function createCursorAdapter(provider: OcxProviderConfig, deps: CursorAdapterDeps = {}): ProviderAdapter {
+  return {
+    name: "cursor",
+
+    buildRequest() {
+      return {
+        url: provider.baseUrl || CURSOR_API_URL,
+        method: "POST",
+        headers: {},
+        body: "",
+      };
+    },
+
+    async *parseStream(): AsyncGenerator<AdapterEvent> {
+      yield {
+        type: "error",
+        message: "Cursor adapter uses runTurn; the fetch/parseStream path is disabled.",
+      };
+    },
+
+    async runTurn(_parsed, incoming, emit) {
+      if (incoming.abortSignal?.aborted) {
+        emit({ type: "error", message: "Cursor turn was aborted before start." });
+        return;
+      }
+      try {
+        const makeTransport = deps.createTransport ?? createLiveCursorTransport;
+        const kv = deps.kv ?? createCursorKvStore();
+        _parsed._cursorConversationId ??= generatedCursorConversationId();
+        const request = createCursorRequest(_parsed);
+        await runCursorTurnWithRetry(
+          makeTransport,
+          { provider, headers: incoming.headers },
+          request,
+          incoming.abortSignal,
+          (message, activeTransport) => {
+            if (incoming.abortSignal?.aborted) {
+              emit({ type: "error", message: "Cursor turn was aborted." });
+              return;
+            }
+            const events = mapCursorServerMessage(message, {
+              kv,
+              writeClient: clientMessage => {
+                void activeTransport.writeClient(clientMessage);
+              },
+            });
+            for (const event of events) emit(event);
+          },
+        );
+      } catch (err) {
+        const partialUsage = (err as { partialUsage?: import("../types").OcxUsage }).partialUsage;
+        emit({ type: "error", message: safeCursorTransportError(err), ...(partialUsage ? { usage: partialUsage } : {}) });
+      }
+    },
+  };
+}

package/src/adapters/google.ts

@@ -21,6 +21,7 @@ import { sanitizeGeminiToolParameters } from "./google-tool-schema";
 import { neutralizeIdentity } from "./identity";
 import { antigravityUsesReplayCache, applyAntigravityReplay, clearAntigravityReplay, observeAntigravityReplay } from "./google-antigravity-replay";
 import { resolveAntigravityWireModelId } from "../providers/antigravity-models";
+import { buildNonOpenAIToolCatalogNudgeForTools } from "./tool-catalog-nudge";
 
 // Google-family models (Gemini/Vertex/Antigravity) tend to emit long running commentary between
 // tool calls. This steers them to keep the BETWEEN-STEP text to one line and reason internally
@@ -87,7 +88,12 @@ function toolResultImageParts(content: string | OcxContentPart[]): unknown[] {
 function messagesToGeminiFormat(parsed: OcxParsedRequest): { systemInstruction?: unknown; contents: unknown[] } {
   // Neutralize Codex's GPT-5 identity line (Gemini/Antigravity share this path) so a routed model
   // never misreports as GPT-5/OpenAI, and never leaks the proxy identity upstream.
-  const systemText = neutralizeIdentity([...(parsed.context.systemPrompt ?? []), GOOGLE_BREVITY_INSTRUCTION].join("\n\n"));
+  const toolCatalogNudge = buildNonOpenAIToolCatalogNudgeForTools(parsed.context.tools, parsed.options.toolChoice);
+  const systemText = neutralizeIdentity([
+    ...(parsed.context.systemPrompt ?? []),
+    ...(toolCatalogNudge ? [toolCatalogNudge] : []),
+    GOOGLE_BREVITY_INSTRUCTION,
+  ].join("\n\n"));
   const systemInstruction = { parts: [{ text: systemText }] };
 
   const contents: unknown[] = [];

package/src/adapters/kiro.ts

@@ -29,6 +29,7 @@ import { extractKiroImages, type KiroImage } from "./kiro-images";
 import { fetchKiroWithRetry } from "./kiro-retry";
 import { convertKiroToolContext } from "./kiro-tools";
 import { neutralizeIdentity } from "./identity";
+import { buildNonOpenAIToolCatalogNudgeFromNames } from "./tool-catalog-nudge";
 
 const AMZ_TARGET = "AmazonCodeWhispererStreamingService.GenerateAssistantResponse";
 const SDK_VERSION = "1.0.27";
@@ -57,6 +58,16 @@ interface KiroHistoryEntry {
   userInputMessage?: KiroUserInputMessage;
   assistantResponseMessage?: { content: string; toolUses?: KiroToolUse[] };
 }
+
+function kiroToolWireNames(tools: readonly unknown[]): string[] {
+  return tools
+    .map(tool => {
+      const spec = (tool as { toolSpecification?: { name?: unknown } }).toolSpecification;
+      return typeof spec?.name === "string" ? spec.name : undefined;
+    })
+    .filter((name): name is string => typeof name === "string");
+}
+
 function userContentText(content: string | OcxContentPart[]): string {
   if (typeof content === "string") return content;
   return content.map(p => (p.type === "text" ? p.text : "")).filter(Boolean).join("\n");
@@ -202,6 +213,10 @@ export function buildKiroPayload(parsed: OcxParsedRequest, profileArn: string |
   // Neutralize Codex's GPT-5 identity line so a routed Kiro model never misreports as GPT-5/OpenAI
   // and the proxy identity never leaks upstream.
   if (!parsed.previousResponseId && parsed.context.systemPrompt?.length) systemParts.push(neutralizeIdentity(parsed.context.systemPrompt.join("\n\n")));
+  const toolCatalogNudge = !parsed.previousResponseId
+    ? buildNonOpenAIToolCatalogNudgeFromNames(kiroToolWireNames(kiroTools))
+    : undefined;
+  if (toolCatalogNudge) systemParts.push(toolCatalogNudge);
   if (toolContext.systemAdditions.length > 0) systemParts.push(...toolContext.systemAdditions);
   const systemPrefix = systemParts.length > 0 ? `${systemParts.join("\n\n")}\n\n` : "";
   const structuredToolIds = new Set<string>();