@iislee/opencodex 2.11.0 → 2.35.0

package/src/adapters/cursor/envelope-echo.ts

@@ -0,0 +1,290 @@
+/**
+ * External Cursor output quarantine (devlog 260826 gaps 10-11).
+ *
+ * Gap 10: flattened tool-result history can prime an external model to echo the
+ * "[Tool Result]" envelope as its own reply.
+ *
+ * Gap 11: a model can invent a blocked native-tool attempt in visible commentary
+ * even though the only real current-turn tool is the advertised Codex bridge.
+ *
+ * Both failures are observable only at the output boundary. The sniffers below
+ * hold a bounded prefix until it either diverges or proves the failure, allowing
+ * cursor.ts to retry before any invalid text reaches the client.
+ */
+
+const ECHO_MARKERS = ["[Tool Result]", "[Tool Error]", "[tool_result]"] as const;
+const MAX_SNIFF_BYTES = 40;
+/** Mid-stream observer: max leading whitespace on a line before matching disarms. */
+const MAX_MIDSTREAM_LINE_INDENT = 128;
+/** Mid-stream observer: post-marker window watched for call-id corruption. */
+const MIDSTREAM_CORRUPTION_WINDOW = 512;
+/** Mid-stream observer: cumulative scan cap (UTF-16 code units, checked between feeds). */
+export const MAX_MIDSTREAM_SCAN_LENGTH = 512 * 1024;
+/** Mid-stream observer: findings retained per turn. */
+const MAX_MIDSTREAM_FINDINGS = 8;
+const MAX_ROUTING_COMMENTARY_BYTES = 512;
+/** Aggregate quarantine cap: past this, flush and disarm. */
+const MAX_HOLD_BYTES = 8 * 1024;
+const encoder = new TextEncoder();
+
+export class CursorToolResultEchoError extends Error {
+  readonly code = "cursor_tool_result_echo";
+  constructor(marker: string) {
+    super(
+      "Cursor external model echoed the replayed tool-result envelope (\"" + marker
+      + "\") instead of continuing the task.",
+    );
+    this.name = "CursorToolResultEchoError";
+  }
+}
+
+export class CursorRoutingCommentaryError extends Error {
+  readonly code = "cursor_routing_commentary_hallucination";
+  constructor() {
+    super("Cursor external model invented a blocked tool surface before any tool call occurred.");
+    this.name = "CursorRoutingCommentaryError";
+  }
+}
+
+export type EchoSnifferDecision =
+  | { kind: "hold" }
+  | { kind: "flush" }
+  | { kind: "echo"; marker: string };
+
+export interface MidstreamEchoFinding {
+  marker: string;
+  /** UTF-16 offset of the marker's line start within the turn's full text. */
+  offset: number;
+  callIdCorrupt: boolean;
+}
+
+/**
+ * Diagnostic-only mid-stream envelope-echo observer (devlog 260828 F1/F2).
+ *
+ * The prefix sniffer only watches the first ~40 bytes of a turn, but live
+ * probing caught grok-4.6 echoing "[Tool Result]" envelope blocks in the
+ * MIDDLE of an agent message — after legitimate leading text — one of them
+ * carrying a whitespace-spliced call-id ("fc_x mar-y" instead of "fc_x-y").
+ * Deltas at that point have already reached the client, so this observer
+ * never throws and never withholds output: it records findings so the
+ * adapter can emit a structured diagnostic at turn end. Only fixed marker
+ * enums, numeric offsets, and corruption booleans are retained — never
+ * content bytes.
+ */
+export class CursorMidstreamEchoObserver {
+  private lineBuffer = "";
+  private lineStartOffset = 0;
+  private totalLength = 0;
+  private disarmed = false;
+  private lineDisarmed = false;
+  private corruptionWatch: { finding: MidstreamEchoFinding; remaining: number; window: string } | undefined;
+  private readonly recorded: MidstreamEchoFinding[] = [];
+
+  feed(textDelta: string): void {
+    if (this.disarmed && !this.corruptionWatch) return;
+    let index = 0;
+    while (index < textDelta.length) {
+      const newline = textDelta.indexOf("\n", index);
+      const segment = newline === -1 ? textDelta.slice(index) : textDelta.slice(index, newline);
+      if (this.corruptionWatch) this.watchCorruption(segment + (newline === -1 ? "" : "\n"));
+      if (!this.disarmed && !this.lineDisarmed && segment.length > 0) {
+        this.lineBuffer += segment;
+        if (this.lineBuffer.length > MAX_MIDSTREAM_LINE_INDENT + 32) {
+          // Bound per-line work: nothing beyond the indent cap + longest marker can match.
+          this.lineDisarmed = !this.lineMatchesPrefixSoFar();
+          this.lineBuffer = this.lineBuffer.slice(0, MAX_MIDSTREAM_LINE_INDENT + 32);
+        }
+        this.checkLine();
+      }
+      if (newline === -1) break;
+      this.lineBuffer = "";
+      this.lineDisarmed = false;
+      this.lineStartOffset = this.totalLength + newline + 1;
+      index = newline + 1;
+    }
+    this.totalLength += textDelta.length;
+    if (this.totalLength > MAX_MIDSTREAM_SCAN_LENGTH) this.disarmed = true;
+  }
+
+  findings(): readonly MidstreamEchoFinding[] {
+    if (this.corruptionWatch) {
+      this.settleCorruption();
+    }
+    return this.recorded;
+  }
+
+  private lineMatchesPrefixSoFar(): boolean {
+    const probe = this.lineBuffer.replace(/^[ \t]*/, "");
+    return ECHO_MARKERS.some(marker => probe.startsWith(marker) || marker.startsWith(probe));
+  }
+
+  private checkLine(): void {
+    const indentMatch = /^[ \t]*/.exec(this.lineBuffer);
+    const indent = indentMatch ? indentMatch[0].length : 0;
+    if (indent > MAX_MIDSTREAM_LINE_INDENT) {
+      this.lineDisarmed = true;
+      return;
+    }
+    const probe = this.lineBuffer.slice(indent);
+    for (const marker of ECHO_MARKERS) {
+      if (probe.startsWith(marker)) {
+        // The prefix sniffer owns the very start of the turn; only offsets past
+        // its window count as mid-stream.
+        if (this.lineStartOffset === 0) {
+          this.lineDisarmed = true;
+          return;
+        }
+        const finding: MidstreamEchoFinding = {
+          marker,
+          offset: this.lineStartOffset,
+          callIdCorrupt: false,
+        };
+        this.corruptionWatch = { finding, remaining: MIDSTREAM_CORRUPTION_WINDOW, window: "" };
+        this.lineDisarmed = true;
+        return;
+      }
+    }
+    if (!ECHO_MARKERS.some(marker => marker.startsWith(probe)) && probe.length > 0) {
+      this.lineDisarmed = true;
+    }
+  }
+
+  private watchCorruption(text: string): void {
+    const watch = this.corruptionWatch;
+    if (!watch) return;
+    const take = Math.min(watch.remaining, text.length);
+    watch.window += text.slice(0, take);
+    watch.remaining -= take;
+    if (watch.remaining <= 0) this.settleCorruption();
+  }
+
+  private settleCorruption(): void {
+    const watch = this.corruptionWatch;
+    if (!watch) return;
+    const window = watch.window;
+    watch.finding.callIdCorrupt =
+      /fc_[0-9a-f]+[ \t]+mar-/.test(window)
+      || /call_id: \S+[ \t]+\S+_0\b/.test(window);
+    if (this.recorded.length < MAX_MIDSTREAM_FINDINGS) this.recorded.push(watch.finding);
+    // Window text is discarded here; only booleans/offsets survive.
+    this.corruptionWatch = undefined;
+  }
+}
+
+/**
+ * Incremental envelope-prefix sniffer. Leading whitespace is tolerated so a
+ * marker copied after a newline is still caught.
+ */
+export class CursorEnvelopeEchoSniffer {
+  private buffered = "";
+  private byteCount = 0;
+  private done = false;
+
+  get settled(): boolean {
+    return this.done;
+  }
+
+  feed(textDelta: string): EchoSnifferDecision {
+    if (this.done) return { kind: "flush" };
+    this.buffered += textDelta;
+    this.byteCount += encoder.encode(textDelta).byteLength;
+    const probe = this.buffered.replace(/^\s+/, "");
+    for (const marker of ECHO_MARKERS) {
+      if (probe.startsWith(marker)) {
+        this.done = true;
+        return { kind: "echo", marker };
+      }
+    }
+    const stillPrefix = ECHO_MARKERS.some(marker =>
+      probe.length < marker.length && marker.startsWith(probe),
+    );
+    if (stillPrefix && this.byteCount <= MAX_SNIFF_BYTES && this.buffered.length < MAX_HOLD_BYTES) {
+      return { kind: "hold" };
+    }
+    this.done = true;
+    return { kind: "flush" };
+  }
+
+  finish(): EchoSnifferDecision {
+    if (this.done) return { kind: "flush" };
+    this.done = true;
+    return { kind: "flush" };
+  }
+}
+
+export type RoutingCommentaryDecision =
+  | { kind: "hold" }
+  | { kind: "flush" }
+  | { kind: "hallucination" };
+
+const ROUTING_NATIVE_TOOL_NAME = /\b(shell|read|grep|list|bash)\b/giu;
+const ROUTING_TOOL_HINT =
+  /(?:\b(?:shell|read|grep|list|bash)\b|exec_command|shell_command|브리지|네이티브\s*(?:셸|쉘))/iu;
+const ROUTING_FAILURE_CLAIM =
+  /(?:blocked|unavailable|interrupted|차단|중단|막혀)/iu;
+const ROUTING_REDIRECT_CLAIM =
+  /(?:exec_command|shell_command|\bexec\b|브리지|redirected|fallback|switch(?:ed|ing)?|전환|우회|통과(?:되|하)|다른\s*(?:도구|경로)|경로로)/iu;
+
+/**
+ * Quarantines the first line of code-mode / bridge output long enough to reject
+ * an impossible routing claim. It requires a failure claim plus either an
+ * explicit redirect to another execution surface or two distinct unadvertised
+ * native-tool names; a legitimate sentence such as "Shell is unavailable on
+ * this OS" therefore passes.
+ */
+export class CursorRoutingCommentarySniffer {
+  private buffered = "";
+  private byteCount = 0;
+  private done = false;
+
+  get settled(): boolean {
+    return this.done;
+  }
+
+  feed(textDelta: string): RoutingCommentaryDecision {
+    if (this.done) return { kind: "flush" };
+    this.buffered += textDelta;
+    this.byteCount += encoder.encode(textDelta).byteLength;
+    if (this.matchesHallucination()) {
+      this.done = true;
+      return { kind: "hallucination" };
+    }
+    const lineBreakCount = (this.buffered.match(/\n/gu) ?? []).length;
+    const hasRoutingHint = ROUTING_TOOL_HINT.test(this.buffered) || ROUTING_FAILURE_CLAIM.test(this.buffered);
+    const pendingFailureClaim =
+      ROUTING_TOOL_HINT.test(this.buffered)
+      && ROUTING_FAILURE_CLAIM.test(this.buffered)
+      && lineBreakCount < 2;
+    if (
+      this.byteCount < MAX_ROUTING_COMMENTARY_BYTES
+      && this.buffered.length < MAX_HOLD_BYTES
+      && (lineBreakCount === 0 || pendingFailureClaim)
+      && (hasRoutingHint || this.byteCount < 64)
+    ) {
+      return { kind: "hold" };
+    }
+    this.done = true;
+    return { kind: "flush" };
+  }
+
+  finish(): RoutingCommentaryDecision {
+    if (this.done) return { kind: "flush" };
+    this.done = true;
+    return this.matchesHallucination() ? { kind: "hallucination" } : { kind: "flush" };
+  }
+
+  private matchesHallucination(): boolean {
+    if (!ROUTING_FAILURE_CLAIM.test(this.buffered)) return false;
+    const nativeTools = new Set(
+      [...this.buffered.matchAll(ROUTING_NATIVE_TOOL_NAME)].map(match => match[1]?.toLowerCase()),
+    );
+    if (nativeTools.size === 0) return false;
+    return ROUTING_REDIRECT_CLAIM.test(this.buffered) || nativeTools.size >= 2;
+  }
+}
+
+export const CURSOR_ECHO_RETRY_CONTINUATION_TEXT =
+  "Your previous reply copied an internal tool-output record verbatim and was rejected. Continue the original task now: issue the next required tool call, or answer in your own words if no tool is needed.";
+
+export const CURSOR_ROUTING_COMMENTARY_RETRY_TEXT =
+  "Your previous reply claimed an execution-surface failure that did not occur and was rejected. Use the current tool catalog as ground truth. Perform the requested operation through the advertised execution tool now, with no commentary before the tool call.";

package/src/adapters/cursor/framing.ts

@@ -168,6 +168,45 @@ export function decodeAvailableConnectFrames(
   }
 }
 
+/**
+ * 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,

package/src/adapters/cursor/h2-pool.ts

@@ -0,0 +1,123 @@
+import http2 from "node:http2";
+import { registerOptionalShutdownHook } from "../../lib/optional-shutdown-hooks";
+
+const DEFAULT_MAX_SESSIONS = 8;
+const SESSION_CLOSE_TIMEOUT_MS = 2_000;
+
+interface PoolEntry {
+  readonly session: http2.ClientHttp2Session;
+  readonly streams: Set<http2.ClientHttp2Stream>;
+  usable: boolean;
+}
+
+/**
+ * HTTP/2 connection pool for Cursor Connect DISCOVERY calls (GetUsableModels).
+ * Sessions are keyed by origin (scheme+host+port) and reused to avoid fresh
+ * TCP+TLS per call. The Run path deliberately dials its own session: Run
+ * streams are long-lived bidi whose lifecycle/EOF semantics are owned by
+ * live-transport (see devlog 260822_senpi_cursor_transfer/190 — Run-path
+ * pooling is a separate, deliberate unit if ever taken).
+ */
+export class CursorH2SessionPool {
+  private readonly entries = new Map<string, PoolEntry>();
+  private closed = false;
+
+  constructor(private readonly maxSessions = DEFAULT_MAX_SESSIONS) {}
+
+  /**
+   * Lazily registered on first use so a process that never talks to Cursor registers
+   * nothing (optional-subsystem doctrine). The seam is synchronous and best-effort;
+   * shutdown() is fire-and-forget there because lifecycle's drainAndShutdown runs
+   * under its own absolute deadline.
+   */
+  private armShutdownHook: (() => void) | undefined = () => {
+    this.armShutdownHook = undefined;
+    registerOptionalShutdownHook("cursor-h2-pool", () => { void this.shutdown(); });
+  };
+
+  request(
+    url: string,
+    headers: http2.OutgoingHttpHeaders,
+  ): http2.ClientHttp2Stream {
+    if (this.closed) throw new Error("Cursor H2 session pool is closed");
+    this.armShutdownHook?.();
+    const origin = new URL(url).origin;
+    const entry = this.usableEntry(origin) ?? this.createEntry(origin);
+    try {
+      const stream = entry.session.request(headers);
+      entry.streams.add(stream);
+      stream.once("close", () => { entry.streams.delete(stream); });
+      return stream;
+    } catch (error) {
+      this.drain(entry, true);
+      throw error;
+    }
+  }
+
+  async shutdown(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    const pending: Promise<void>[] = [];
+    for (const entry of [...this.entries.values()]) {
+      for (const stream of [...entry.streams]) stream.destroy();
+      entry.session.close();
+      if (entry.session.destroyed) continue;
+      pending.push(new Promise<void>(resolve => {
+        const timer = setTimeout(resolve, SESSION_CLOSE_TIMEOUT_MS);
+        timer.unref?.();
+        entry.session.once("close", () => { clearTimeout(timer); resolve(); });
+      }));
+    }
+    this.entries.clear();
+    await Promise.all(pending);
+  }
+
+  get size(): number { return this.entries.size; }
+
+  private usableEntry(origin: string): PoolEntry | undefined {
+    const entry = this.entries.get(origin);
+    if (!entry) return undefined;
+    if (entry.usable && !entry.session.closed && !entry.session.destroyed) return entry;
+    this.drain(entry, false);
+    return undefined;
+  }
+
+  private createEntry(origin: string): PoolEntry {
+    const session = http2.connect(origin);
+    const entry: PoolEntry = {
+      session,
+      streams: new Set(),
+      usable: true,
+    };
+    this.entries.set(origin, entry);
+    session.once("goaway", () => { this.drain(entry, true); });
+    session.on("error", () => { this.drain(entry, false); });
+    session.once("close", () => {
+      // Identity check: a stale close event from an old session must not evict
+      // a healthy replacement entry that was created after drain() removed the old one.
+      if (this.entries.get(origin) === entry) this.entries.delete(origin);
+    });
+    // Enforce bound: evict oldest when over capacity.
+    while (this.entries.size > this.maxSessions) {
+      const oldest = this.entries.keys().next().value;
+      if (!oldest || oldest === origin) break;
+      const old = this.entries.get(oldest);
+      if (old) this.drain(old, true);
+    }
+    return entry;
+  }
+
+  private drain(entry: PoolEntry, closeSession: boolean): void {
+    entry.usable = false;
+    for (const stream of [...entry.streams]) stream.destroy();
+    entry.streams.clear();
+    if (closeSession) entry.session.close();
+    // Remove from map by finding the matching key.
+    for (const [key, value] of this.entries) {
+      if (value === entry) { this.entries.delete(key); break; }
+    }
+  }
+}
+
+/** Shared singleton pool for all Cursor adapter H2 traffic. */
+export const cursorH2Pool = new CursorH2SessionPool();