@remodex/rmx 1.0.2

package/src/adapters/cursor/effort-map.ts

@@ -0,0 +1,139 @@
+/**
+ * Per-model Cursor reasoning-effort mapping.
+ *
+ * Cursor model ids encode the reasoning effort as a suffix (`claude-4.6-opus-high`), and the available
+ * tiers differ per model — `claude-4.6-opus` tops out at `-max`, `claude-opus-4-8` at `-xhigh`,
+ * `claude-4.6-sonnet` only has `-medium`, and most `composer`/`gemini` models take no suffix at all.
+ * Grok Fast puts its mode marker after the effort (`grok-4.5-high-fast`). A bare id for a model that
+ * requires a suffix is rejected `ERROR_BAD_MODEL_NAME` (devlog 350.105).
+ *
+ * Canonical effort order is always low < medium < high < xhigh < max (max is the top tier, confirmed
+ * against Anthropic docs and Cursor's live lineup). Tiers are stored in ascending canonical order.
+ *
+ * `CURSOR_MODEL_EFFORT_TIERS` is the real catalog (from the Cursor `GetUsableModels` naming, mirrored in
+ * jawcode's bundle), each base model -> its available suffixes in ascending order. `cursorEffortSuffix`
+ * is literal-first: when the requested effort is one of the model's tiers, the effort you name is the
+ * suffix Cursor receives. It only clamps Codex effort ranks for efforts outside that model's tier set.
+ */
+
+const CURSOR_MODEL_EFFORT_TIERS: Record<string, readonly string[]> = {
+  "claude-4.5-opus": ["high"],
+  "claude-4.6-opus": ["high", "max"],
+  "claude-4.6-sonnet": ["medium"],
+  // max is always the top tier (canonical order: low < medium < high < xhigh < max), confirmed
+  // against Anthropic's effort ladder docs and Cursor's live model lineup.
+  "claude-fable-5": ["low", "medium", "high", "xhigh", "max"],
+  "claude-opus-4-7": ["low", "medium", "high", "xhigh", "max"],
+  "claude-opus-4-8": ["low", "medium", "high", "xhigh", "max"],
+  "claude-opus-5": ["low", "medium", "high", "xhigh", "max"],
+  "claude-sonnet-5": ["low", "medium", "high", "xhigh", "max"],
+  "glm-5.2": ["high", "max"],
+  // GetUsableModels (2026-07-28) lists kimi-k3 only as effort-suffixed kimi-k3-{low,high,max};
+  // the bare id returns not_found. Tiers mirror the native Kimi provider's K3 ladder.
+  "kimi-k3": ["low", "high", "max"],
+  // Cursor renamed the Grok 4.5 slugs to cursor-grok-4.5-{low,medium,high} and
+  // cursor-grok-4.5-{low,medium,high}-fast. The bare Fast id returns not_found.
+  "grok-4.5": ["low", "medium", "high"],
+  "grok-4.5-fast": ["low", "medium", "high"],
+  "gpt-5.1": ["low", "high"],
+  "gpt-5.1-codex-max": ["low", "medium", "high", "xhigh"],
+  "gpt-5.1-codex-mini": ["low", "high"],
+  "gpt-5.2": ["low", "high", "xhigh"],
+  "gpt-5.2-codex": ["low", "high", "xhigh"],
+  "gpt-5.3-codex": ["low", "high", "xhigh"],
+  "gpt-5.4": ["low", "medium", "high", "xhigh"],
+  "gpt-5.4-mini": ["low", "medium", "high", "xhigh"],
+  "gpt-5.4-nano": ["low", "medium", "high", "xhigh"],
+  "gpt-5.5": ["low", "medium", "high"],
+  "gpt-5.5-extra": ["high"],
+  "gpt-5.6-sol": ["low", "medium", "high", "xhigh", "max"],
+  "gpt-5.6-terra": ["low", "medium", "high", "xhigh", "max"],
+  "gpt-5.6-luna": ["low", "medium", "high", "xhigh", "max"],
+};
+
+/** All effort suffixes accepted when matching live Cursor model ids to configured base ids. */
+export const CANONICAL_EFFORT_SUFFIXES: ReadonlySet<string> = new Set([
+  "none",
+  ...Object.values(CURSOR_MODEL_EFFORT_TIERS).flat(),
+]);
+
+const CANONICAL_CODEX_EFFORT_ORDER = ["low", "medium", "high", "xhigh", "max"] as const;
+
+function normalizeRequestedEffort(reasoning: string | undefined): string | undefined {
+  const normalized = reasoning?.toLowerCase();
+  return normalized === "ultra" ? "max" : normalized;
+}
+
+/** Collapse a Codex reasoning-effort label to a low/medium/high rank for clamping onto a model's tiers. */
+function codexEffortRank(reasoning: string | undefined): "low" | "medium" | "high" {
+  switch (normalizeRequestedEffort(reasoning) ?? "") {
+    case "none":
+    case "minimal":
+    case "low":
+      return "low";
+    case "medium":
+      return "medium";
+    case "high":
+    case "max":
+    case "xhigh":
+      return "high";
+    default:
+      // No explicit effort: a bare reasoning-model id is invalid, so pick the model's top tier.
+      return "high";
+  }
+}
+
+/**
+ * The Cursor effort suffix to use for `baseModelId` given a Codex reasoning effort, or `undefined` when
+ * the model takes no suffix (bare). Literal model tiers pass through; unknown efforts clamp by rank.
+ */
+export function cursorEffortSuffix(baseModelId: string, reasoning: string | undefined): string | undefined {
+  const tiers = CURSOR_MODEL_EFFORT_TIERS[baseModelId];
+  if (!tiers || tiers.length === 0) return undefined;
+  const requested = normalizeRequestedEffort(reasoning);
+  if (requested && tiers.includes(requested)) return requested;
+  switch (codexEffortRank(reasoning)) {
+    case "low":
+      return tiers[0];
+    case "high":
+      return tiers[tiers.length - 1];
+    case "medium":
+      return tiers[Math.floor((tiers.length - 1) / 2)];
+  }
+}
+
+/** The Codex-facing picker ladder for a Cursor model, sorted in canonical Codex effort order. */
+export function cursorModelEffortLadder(baseModelId: string): string[] | undefined {
+  const tiers = CURSOR_MODEL_EFFORT_TIERS[baseModelId];
+  if (!tiers || tiers.length === 0) return undefined;
+  const tierSet = new Set(tiers);
+  return CANONICAL_CODEX_EFFORT_ORDER.filter(effort => tierSet.has(effort));
+}
+
+/** Base models known to carry a reasoning-effort suffix (everything else is sent bare). */
+export function cursorModelHasEffortTiers(baseModelId: string): boolean {
+  return (CURSOR_MODEL_EFFORT_TIERS[baseModelId]?.length ?? 0) > 0;
+}
+
+/**
+ * Compose Cursor's flattened model id from a Codex-facing base id and effort tier. Discovery uses
+ * this for the ids returned by GetUsableModels. Parameterized Grok Fast requests bypass the flat id
+ * and send the base model plus requested_model parameters instead.
+ */
+export function cursorWireModelIdWithEffort(baseModelId: string, effortSuffix: string): string {
+  if (baseModelId.endsWith("-fast")) {
+    return `${baseModelId.slice(0, -"-fast".length)}-${effortSuffix}-fast`;
+  }
+  return `${baseModelId}-${effortSuffix}`;
+}
+
+/**
+ * Compose the exact flattened id sent by AgentService/Run. Discovery normalizes Cursor's optional
+ * `cursor-` prefix only for catalog matching, but regular Grok 4.5 requests require that prefix on
+ * the wire. Keep this separate from {@link cursorWireModelIdWithEffort} so discovery can continue
+ * comparing canonical, prefix-free ids. Grok Fast uses requested_model parameters instead.
+ */
+export function cursorRequestWireModelIdWithEffort(baseModelId: string, effortSuffix: string): string {
+  const flattened = cursorWireModelIdWithEffort(baseModelId, effortSuffix);
+  return baseModelId === "grok-4.5" ? `cursor-${flattened}` : flattened;
+}

package/src/adapters/cursor/exec-policy.ts

@@ -0,0 +1,88 @@
+import type { OcxProviderConfig } from "../../types";
+import type { CursorClientMessage } from "./types";
+
+export type CursorNativeExecMode = "off" | "codex-sandbox" | "on";
+
+/** Codex permissions template marker, e.g. "`sandbox_mode` is `danger-full-access`". */
+export const CURSOR_SANDBOX_FULL_ACCESS_RE = /sandbox_mode[^\n]{0,80}danger-full-access/i;
+
+/**
+ * Config-owner-selected policy; explicit mode wins, legacy boolean maps to "on".
+ * The UNSET default is "off". `nativeLocalExec: "on"` is the only non-legacy setting that
+ * authorizes Cursor server-driven local read/write/delete/ls/grep/shell/fetch execution.
+ * `nativeLocalExec: "codex-sandbox"` is kept as a recognized legacy/deprecated spelling but is
+ * fail-closed: Remodex has no trustworthy per-request attestation that caller-supplied
+ * Responses instructions/system/developer prose reflects a real Codex sandbox state.
+ */
+export function resolveCursorNativeExecMode(provider: OcxProviderConfig): CursorNativeExecMode {
+  const mode = provider.nativeLocalExec;
+  if (mode === "off" || mode === "codex-sandbox" || mode === "on") return mode;
+  return provider.unsafeAllowNativeLocalExec === true ? "on" : "off";
+}
+
+/**
+ * True when the request itself declares the Codex full-access sandbox. Carriers are the
+ * system/instructions entries and developer-role messages ONLY. This is diagnostic/context
+ * metadata; request text is caller-controlled and never authorizes native local exec.
+ */
+export function cursorRequestDeclaresFullAccess(
+  request: { system: string[]; messages: Array<{ role: string; content: string }> },
+): boolean {
+  for (const entry of request.system) {
+    if (CURSOR_SANDBOX_FULL_ACCESS_RE.test(entry)) return true;
+  }
+  for (const message of request.messages) {
+    if (message.role === "developer" && CURSOR_SANDBOX_FULL_ACCESS_RE.test(message.content)) return true;
+  }
+  return false;
+}
+
+/** Effective per-request allowance: only server-local config opt-in enables native exec. */
+export function effectiveCursorNativeExecAllow(provider: OcxProviderConfig, requestDeclaresFullAccess: boolean): boolean {
+  const mode = resolveCursorNativeExecMode(provider);
+  void requestDeclaresFullAccess;
+  return mode === "on";
+}
+
+export const CURSOR_EXEC_CASES_DENIED = [
+  "readArgs",
+  "lsArgs",
+  "grepArgs",
+  "writeArgs",
+  "deleteArgs",
+  "shellArgs",
+  "shellStreamArgs",
+  "diagnosticsArgs",
+  "mcpArgs",
+  "fetchArgs",
+  "recordScreenArgs",
+  "computerUseArgs",
+  "unknownExecCase",
+] as const;
+
+export type CursorDeniedExecCase = (typeof CURSOR_EXEC_CASES_DENIED)[number];
+
+export function cursorExecDeniedMessage(execCase: string): string {
+  return [
+    `Cursor legacy mock transport cannot execute ${execCase}.`,
+    "Production Cursor requests use the live protobuf native exec bridge.",
+    "The legacy mock path returns a non-executing placeholder for tests only.",
+  ].join(" ");
+}
+
+export function cursorExecResult(requestId: string, execCase: string): CursorClientMessage {
+  if (execCase === "requestContextArgs") {
+    return {
+      type: "exec_result",
+      requestId,
+      ok: true,
+      message: "Cursor request context is empty in legacy mock transport mode.",
+    };
+  }
+  return {
+    type: "exec_result",
+    requestId,
+    ok: false,
+    message: cursorExecDeniedMessage(execCase),
+  };
+}

package/src/adapters/cursor/framing.ts

@@ -0,0 +1,250 @@
+export const CONNECT_FRAME_HEADER_BYTES = 5;
+export const CONNECT_FLAG_COMPRESSED = 0x01;
+export const CONNECT_FLAG_END_STREAM = 0x02;
+export const MAX_CONNECT_FRAME_PAYLOAD_BYTES = 0xffffffff;
+
+export type ConnectFrameErrorCode =
+  | "invalid_offset"
+  | "invalid_flags"
+  | "payload_too_large"
+  | "frame_incomplete";
+
+export interface ConnectFrame {
+  flags: number;
+  payload: Uint8Array;
+  compressed: boolean;
+  endStream: boolean;
+}
+
+export interface DecodedConnectFrame {
+  frame: ConnectFrame;
+  readBytes: number;
+}
+
+export interface DecodedConnectFrames {
+  frames: ConnectFrame[];
+  remainder: Uint8Array;
+}
+
+interface CopyReservation {
+  commitRetained(): void;
+  release(): void;
+}
+
+interface InspectedConnectFrame {
+  flags: number;
+  length: number;
+  payloadStart: number;
+  readBytes: number;
+}
+
+export class ConnectFrameError extends Error {
+  constructor(
+    public readonly code: ConnectFrameErrorCode,
+    message: string,
+  ) {
+    super(message);
+    this.name = "ConnectFrameError";
+  }
+}
+
+export function isConnectFrameCompressed(flags: number): boolean {
+  return (flags & CONNECT_FLAG_COMPRESSED) === CONNECT_FLAG_COMPRESSED;
+}
+
+export function isConnectFrameEndStream(flags: number): boolean {
+  return (flags & CONNECT_FLAG_END_STREAM) === CONNECT_FLAG_END_STREAM;
+}
+
+export function encodeConnectFrame(
+  payload: Uint8Array,
+  options: { flags?: number; compressed?: boolean; endStream?: boolean } = {},
+): Uint8Array {
+  if (payload.length > MAX_CONNECT_FRAME_PAYLOAD_BYTES) {
+    throw new ConnectFrameError("payload_too_large", `Connect frame payload too large: ${payload.length}`);
+  }
+
+  let flags = options.flags ?? 0;
+  assertByte(flags, "invalid_flags", `Connect frame flags must be a byte: ${flags}`);
+  if (options.compressed) flags |= CONNECT_FLAG_COMPRESSED;
+  if (options.endStream) flags |= CONNECT_FLAG_END_STREAM;
+
+  const frame = new Uint8Array(CONNECT_FRAME_HEADER_BYTES + payload.length);
+  frame[0] = flags;
+  new DataView(frame.buffer, frame.byteOffset, frame.byteLength)
+    .setUint32(1, payload.length, false);
+  frame.set(payload, CONNECT_FRAME_HEADER_BYTES);
+  return frame;
+}
+
+export function tryDecodeConnectFrame(
+  input: Uint8Array,
+  offset = 0,
+  maxPayloadBytes = MAX_CONNECT_FRAME_PAYLOAD_BYTES,
+  reservePayloadCopy?: (bytes: number) => CopyReservation | undefined,
+): DecodedConnectFrame | null {
+  assertOffset(input, offset);
+  const inspected = inspectConnectFrame(input, offset, maxPayloadBytes);
+  if (!inspected) return null;
+  const payloadEnd = inspected.payloadStart + inspected.length;
+  const reservation = reservePayloadCopy?.(inspected.length);
+  let payload: Uint8Array;
+  try {
+    payload = input.slice(inspected.payloadStart, payloadEnd);
+    reservation?.commitRetained();
+  } catch (error) {
+    reservation?.release();
+    throw error;
+  }
+  return {
+    frame: {
+      flags: inspected.flags,
+      payload,
+      compressed: isConnectFrameCompressed(inspected.flags),
+      endStream: isConnectFrameEndStream(inspected.flags),
+    },
+    readBytes: inspected.readBytes,
+  };
+}
+
+export function decodeConnectFrame(input: Uint8Array, offset = 0): DecodedConnectFrame {
+  const decoded = tryDecodeConnectFrame(input, offset);
+  if (!decoded) {
+    throw new ConnectFrameError("frame_incomplete", "Incomplete Connect frame");
+  }
+  return decoded;
+}
+
+export function decodeConnectFrames(input: Uint8Array): ConnectFrame[] {
+  const frames: ConnectFrame[] = [];
+  let offset = 0;
+  while (offset < input.length) {
+    const decoded = decodeConnectFrame(input, offset);
+    frames.push(decoded.frame);
+    offset += decoded.readBytes;
+  }
+  return frames;
+}
+
+export function decodeAvailableConnectFrames(
+  input: Uint8Array,
+  maxPayloadBytes = MAX_CONNECT_FRAME_PAYLOAD_BYTES,
+  availableFrameSlots = Number.POSITIVE_INFINITY,
+  reservePayloadCopy?: (bytes: number) => CopyReservation | undefined,
+): DecodedConnectFrames {
+  const planned: Array<InspectedConnectFrame & { reservation?: CopyReservation }> = [];
+  let offset = 0;
+  let remainderReservation: CopyReservation | undefined;
+  try {
+    while (offset < input.length && planned.length < availableFrameSlots) {
+      const inspected = inspectConnectFrame(input, offset, maxPayloadBytes);
+      if (!inspected) break;
+      const reservation = reservePayloadCopy?.(inspected.length);
+      planned.push({ ...inspected, reservation });
+      offset += inspected.readBytes;
+    }
+    const remainderBytes = offset === input.length ? 0 : bufferedPayloadBytes(input, offset);
+    remainderReservation = reservePayloadCopy?.(remainderBytes);
+
+    // Keep every reservation transient until every batch allocation succeeds. A later admission
+    // failure can then roll the entire batch back without needing ownership of unreturned frames.
+    const frames = planned.map(({ flags, length, payloadStart }) => {
+      const payload = input.slice(payloadStart, payloadStart + length);
+      return {
+        flags,
+        payload,
+        compressed: isConnectFrameCompressed(flags),
+        endStream: isConnectFrameEndStream(flags),
+      };
+    });
+    const remainder = offset === input.length ? new Uint8Array() : input.slice(offset);
+    for (const entry of planned) entry.reservation?.commitRetained();
+    remainderReservation?.commitRetained();
+    return { frames, remainder };
+  } catch (error) {
+    for (const entry of planned) entry.reservation?.release();
+    remainderReservation?.release();
+    throw error;
+  }
+}
+
+/**
+ * Cursor-based sibling of decodeAvailableConnectFrames for callers that keep
+ * their own raw backlog: consumes complete frames from the FRONT of `input`
+ * and reports how many bytes were consumed (headers included) instead of
+ * materializing a remainder copy, and hands payload VIEWS (not copies) back so
+ * the caller can transfer the already-charged bytes to the frame lifecycle
+ * instead of reserving a second copy. The caller advances its own cursor by
+ * `consumedBytes` and never pays an O(backlog) copy per drain.
+ */
+export function consumeConnectFrames(
+  input: Uint8Array,
+  maxPayloadBytes = MAX_CONNECT_FRAME_PAYLOAD_BYTES,
+  availableFrameSlots = Number.POSITIVE_INFINITY,
+): { frames: ConnectFrame[]; consumedBytes: number } {
+  const planned: InspectedConnectFrame[] = [];
+  let offset = 0;
+  while (offset < input.length && planned.length < availableFrameSlots) {
+    const inspected = inspectConnectFrame(input, offset, maxPayloadBytes);
+    if (!inspected) break;
+    planned.push(inspected);
+    offset += inspected.readBytes;
+  }
+  // Zero-copy handoff for large payloads: VIEWS into the caller's backlog
+  // buffer (safe: append-only at its end, compaction/growth replace the
+  // buffer, a consumed region is never mutated in place). Small payloads are
+  // COPIED instead — a small view would pin the whole backlog buffer (up to
+  // 32 MiB) alive while the frame waits in the work queue.
+  const COPY_PIN_THRESHOLD_BYTES = 64 * 1024;
+  const frames = planned.map(({ flags, length, payloadStart }) => ({
+    flags,
+    payload: length <= COPY_PIN_THRESHOLD_BYTES
+      ? input.slice(payloadStart, payloadStart + length)
+      : input.subarray(payloadStart, payloadStart + length),
+    compressed: isConnectFrameCompressed(flags),
+    endStream: isConnectFrameEndStream(flags),
+  }));
+  return { frames, consumedBytes: offset };
+}
+
+function inspectConnectFrame(
+  input: Uint8Array,
+  offset: number,
+  maxPayloadBytes: number,
+): InspectedConnectFrame | null {
+  if (input.length - offset < CONNECT_FRAME_HEADER_BYTES) return null;
+  const view = new DataView(input.buffer, input.byteOffset + offset, input.byteLength - offset);
+  const flags = view.getUint8(0);
+  const length = view.getUint32(1, false);
+  if (length > maxPayloadBytes) {
+    throw new ConnectFrameError("payload_too_large", `Connect frame payload too large: ${length}`);
+  }
+  const readBytes = CONNECT_FRAME_HEADER_BYTES + length;
+  if (input.length - offset < readBytes) return null;
+  return { flags, length, payloadStart: offset + CONNECT_FRAME_HEADER_BYTES, readBytes };
+}
+
+function bufferedPayloadBytes(input: Uint8Array, start: number): number {
+  let offset = start;
+  let payloadBytes = 0;
+  while (input.byteLength - offset >= CONNECT_FRAME_HEADER_BYTES) {
+    const length = new DataView(input.buffer, input.byteOffset + offset, input.byteLength - offset).getUint32(1, false);
+    const available = Math.min(length, input.byteLength - offset - CONNECT_FRAME_HEADER_BYTES);
+    payloadBytes += available;
+    if (available < length) break;
+    offset += CONNECT_FRAME_HEADER_BYTES + length;
+  }
+  return payloadBytes;
+}
+
+function assertOffset(input: Uint8Array, offset: number): void {
+  if (!Number.isInteger(offset) || offset < 0 || offset > input.length) {
+    throw new ConnectFrameError("invalid_offset", `Invalid Connect frame offset: ${offset}`);
+  }
+}
+
+function assertByte(value: number, code: ConnectFrameErrorCode, message: string): void {
+  if (!Number.isInteger(value) || value < 0 || value > 0xff) {
+    throw new ConnectFrameError(code, message);
+  }
+}