npm - @bitkyc08/opencodex - Versions diffs - 2.25.0 → 2.26.0 - Mend

@bitkyc08/opencodex 2.25.0 → 2.26.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (99) hide show

package/bin/ocx.mjs +59 -7
package/gui/dist/assets/index-RL6b1bTV.js +102 -0
package/gui/dist/index.html +1 -1
package/package.json +1 -1
package/src/adapters/base.ts +18 -0
package/src/adapters/client-fingerprint.ts +0 -2
package/src/adapters/cursor/http1-bidi.ts +361 -0
package/src/adapters/cursor/live-models.ts +117 -30
package/src/adapters/cursor/live-transport.ts +137 -56
package/src/adapters/cursor/native-exec-fs.ts +1 -1
package/src/adapters/cursor/native-exec-network.ts +1 -1
package/src/adapters/cursor/native-exec-shell.ts +0 -1
package/src/adapters/cursor/protobuf-request.ts +89 -21
package/src/adapters/cursor/tool-definitions.ts +18 -7
package/src/adapters/cursor/tool-result-normalize.ts +92 -0
package/src/adapters/cursor/transport.ts +7 -0
package/src/adapters/cursor.ts +2 -0
package/src/adapters/google-http.ts +38 -10
package/src/adapters/google.ts +23 -3
package/src/adapters/openai-chat.ts +38 -13
package/src/adapters/openai-responses.ts +129 -9
package/src/adapters/registry.ts +30 -1
package/src/bridge.ts +50 -12
package/src/chat/inbound.ts +1 -0
package/src/claude/agents-inject.ts +3 -2
package/src/cli/dispatch.ts +19 -6
package/src/cli/help.ts +2 -1
package/src/cli/integrations.ts +35 -0
package/src/cli/minimax.ts +8 -2
package/src/cli/registry.ts +13 -2
package/src/clients/config-export.ts +120 -1
package/src/codex/account-store.ts +17 -1
package/src/codex/auth-api.ts +51 -17
package/src/codex/catalog/effort.ts +8 -5
package/src/codex/catalog/provider-fetch.ts +39 -27
package/src/codex/catalog/sync.ts +30 -8
package/src/codex/inject.ts +39 -13
package/src/codex/main-account.ts +29 -1
package/src/codex/plan-from-token.ts +140 -0
package/src/codex/plan.ts +25 -0
package/src/codex/prompt-journal.ts +6 -2
package/src/codex/quota-rejection.ts +21 -7
package/src/codex/refresh.ts +4 -2
package/src/codex/sync.ts +106 -3
package/src/codex/warmup.ts +187 -81
package/src/config.ts +85 -46
package/src/generated/compatibility-version.json +127 -83
package/src/grok/inject.ts +1 -1
package/src/images/loop.ts +1 -0
package/src/integrations/registry.ts +7 -0
package/src/lab/automation/config-persistence.ts +2 -2
package/src/lab/automation/persistence.ts +2 -2
package/src/lab/ledger/purge.ts +2 -2
package/src/lab/subject/behavior-fingerprint.ts +2 -2
package/src/lib/config-ownership.ts +5 -2
package/src/lib/destination-policy.ts +18 -1
package/src/lib/provider-outbound.ts +7 -0
package/src/lib/redact.ts +11 -0
package/src/lib/tool-argument-integers.ts +50 -6
package/src/lib/upstream-http-version.ts +57 -0
package/src/lib/upstream-retry.ts +2 -1
package/src/lib/windows-atomic-replace.ts +155 -0
package/src/lib/windows-service-wrappers.ts +72 -0
package/src/oauth/google-antigravity.ts +2 -2
package/src/oauth/index.ts +60 -8
package/src/providers/antigravity-models.ts +58 -4
package/src/providers/command-code-efforts.ts +36 -9
package/src/providers/context-cap.ts +9 -0
package/src/providers/derive.ts +4 -0
package/src/providers/fastwire.ts +453 -0
package/src/providers/registry.ts +21 -1
package/src/providers/service-tier.ts +173 -89
package/src/responses/parser.ts +25 -16
package/src/responses/reasoning-replay-cache.ts +30 -0
package/src/responses/thought-signature-replay.ts +74 -4
package/src/router.ts +6 -0
package/src/routing/compatibility/behavior.ts +27 -16
package/src/server/index.ts +10 -1
package/src/server/management/oauth-account-routes.ts +10 -2
package/src/server/management/shared.ts +1 -1
package/src/server/management/system-routes.ts +15 -0
package/src/server/request-log.ts +57 -3
package/src/server/responses/agent-task-recovery.ts +6 -1
package/src/server/responses/core.ts +209 -40
package/src/server/responses/fetch-helpers.ts +15 -36
package/src/server/responses/responses-field-backfill.ts +173 -0
package/src/server/responses-reasoning-summary-rewrite.ts +171 -0
package/src/service.ts +38 -36
package/src/storage/cleanup.ts +2 -2
package/src/tray/windows.ts +3 -2
package/src/types.ts +101 -14
package/src/update/job.ts +9 -18
package/src/update/transactional-install.d.mts +22 -0
package/src/update/transactional-install.mjs +259 -0
package/src/usage/cost.ts +34 -5
package/src/usage/log.ts +74 -4
package/src/vision/anthropic-describe.ts +10 -6
package/src/web-search/anthropic-executor.ts +8 -6
package/gui/dist/assets/index-DxJ7kXj9.js +0 -102

package/gui/dist/index.html CHANGED Viewed

@@ -16,7 +16,7 @@
         } catch (e) {}
       })();
     </script>
-    <script type="module" crossorigin src="/assets/index-DxJ7kXj9.js"></script>
+    <script type="module" crossorigin src="/assets/index-RL6b1bTV.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-DQsMZzI5.css">
   </head>
   <body>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@bitkyc08/opencodex",
-  "version": "2.25.0",
+  "version": "2.26.0",
   "description": "Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code",
   "type": "module",
   "main": "./bin/package-main.mjs",

package/src/adapters/base.ts CHANGED Viewed

@@ -1,11 +1,18 @@
 import type { AdapterEvent, OcxParsedRequest } from "../types";
 import type { TranslatorBudget } from "../lib/translator-budget";
+import type { AdapterTierMetadata } from "../providers/fastwire";
 /** Metadata about the caller's incoming request, for auth-forwarding adapters. */
 export interface IncomingMeta {
   headers: Headers;
   translatorBudget: TranslatorBudget;
   abortSignal?: AbortSignal;
+  /**
+   * Provider-scoped fetch prepared by the Responses router. Stateful transports that emit more
+   * than one physical HTTP request per logical turn must reuse it so every request participates in
+   * the same pacing queue and custom provider fetch seam.
+   */
+  providerFetch?: typeof globalThis.fetch;
   /**
    * Image-normalization ladder bias for upstream-413 tightened retries: every image
    * starts one tier lower (devlog/260714_image_normalization_pipeline/030). Only the
@@ -39,6 +46,9 @@ export interface ProviderAdapter {
     incoming: IncomingMeta,
     emit: (event: AdapterEvent) => void,
   ): Promise<void>;
+  /** Exact no-field observation for runTurn adapters, which expose no AdapterRequest object. */
+  tierLogForRunTurn?(parsed: OcxParsedRequest): AdapterTierMetadata | undefined;
 }
 export interface AdapterRequest {
@@ -67,6 +77,12 @@ export interface AdapterRequest {
           wireField: "reasoning_effort" | "reasoning.effort" | "thinking.type";
           wireValue: string;
         };
+    /**
+     * Exact tier outcome seeded after this adapter serialized the outbound request.
+     * This is a live shared observer: response-phase methods mutate `outcome`, so retain
+     * the reference rather than cloning or snapshotting it.
+     */
+    tierLog?: AdapterTierMetadata;
     usageLog?: {
       inputTokens?: number;
       estimated?: boolean;
@@ -82,4 +98,6 @@ export interface AdapterFetchContext {
   returnRawErrors?: boolean;
   /** Whether the upstream response will be consumed as a stream; adapters may select low-latency transport settings. */
   stream?: boolean;
+  /** Custom fetch executor to use for physical upstream network requests (defaults to globalThis.fetch). */
+  executor?: typeof globalThis.fetch;
 }

package/src/adapters/client-fingerprint.ts CHANGED Viewed

@@ -45,8 +45,6 @@ export function claudeCodeSessionId(token: string | undefined): string {
 export const ANTIGRAVITY_IDE_VERSION = "2.5.5";
 const ANTIGRAVITY_IDE_CLIENT_NAME = "aidev_client";
 const ANTIGRAVITY_IDE_PLATFORM = "windows/amd64";
-/** Secondary Google API client UA the Antigravity client library reports. */
-export const ANTIGRAVITY_GOOG_API_CLIENT_UA = "google-api-nodejs-client/10.3.0";
 /**
  * Real Antigravity IDE User-Agent format, decompiled from 2.5.5 Go LS (`setHeaders` @ `0x1018fbe00`):

package/src/adapters/cursor/http1-bidi.ts ADDED Viewed

@@ -0,0 +1,361 @@
+import { create, toBinary } from "@bufbuild/protobuf";
+import type { TranslatorBudget } from "../../lib/translator-budget";
+import { CURSOR_MAX_EFFECTIVE_CONNECT_PAYLOAD_BYTES } from "../../lib/translator-budget";
+import { readBoundedResponseBytes } from "../../lib/bounded-body";
+import { withUpstreamHttpVersionValue } from "../../lib/upstream-http-version";
+import { isPreConnectReachabilityError } from "../../lib/upstream-reachability";
+import { BidiRequestIdSchema } from "./gen/agent_pb";
+import { consumeConnectFrames, encodeConnectFrame } from "./framing";
+const CURSOR_RUN_SSE_PATH = "/agent.v1.AgentService/RunSSE";
+const CURSOR_BIDI_APPEND_PATH = "/aiserver.v1.BidiService/BidiAppend";
+const CURSOR_HTTP1_APPEND_TIMEOUT_MS = 30_000;
+const CURSOR_HTTP1_APPEND_RESPONSE_MAX_BYTES = 64 * 1024;
+const HEX = "0123456789abcdef";
+export interface CursorHttp1BidiCallbacks {
+  onCommitted(): void;
+  onData(chunk: Uint8Array): void;
+  onEnd(): void;
+  onError(error: Error): void;
+}
+export interface CursorHttp1BidiOptions {
+  baseUrl: string;
+  token: string;
+  clientVersion: string;
+  sessionId: string;
+  requestId: string;
+  translatorBudget: TranslatorBudget;
+  callbacks: CursorHttp1BidiCallbacks;
+  fetch?: typeof globalThis.fetch;
+}
+interface PendingAppend {
+  payload: Uint8Array;
+  seqno: bigint;
+  rawBytesCharged: boolean;
+}
+function varintLength(value: bigint): number {
+  let length = 1;
+  for (let current = value; current >= 0x80n; current >>= 7n) length += 1;
+  return length;
+}
+function writeVarint(target: Uint8Array, offset: number, value: bigint): number {
+  let current = value;
+  while (current >= 0x80n) {
+    target[offset++] = Number(current & 0x7fn) | 0x80;
+    current >>= 7n;
+  }
+  target[offset++] = Number(current);
+  return offset;
+}
+function requestIdMessageBytes(requestId: string): Uint8Array {
+  const value = new TextEncoder().encode(requestId);
+  const message = new Uint8Array(1 + varintLength(BigInt(value.byteLength)) + value.byteLength);
+  let offset = 0;
+  message[offset++] = 0x0a; // field 1, string request_id
+  offset = writeVarint(message, offset, BigInt(value.byteLength));
+  message.set(value, offset);
+  return message;
+}
+/** Exact encoded size of Cursor's aiserver.v1.BidiAppendRequest hex fallback shape. */
+export function cursorBidiAppendRequestSize(payloadBytes: number, requestId: string, seqno: bigint): number {
+  const hexBytes = payloadBytes * 2;
+  const requestIdBytes = requestIdMessageBytes(requestId).byteLength;
+  return (hexBytes > 0 ? 1 + varintLength(BigInt(hexBytes)) + hexBytes : 0)
+    + 1 + varintLength(BigInt(requestIdBytes)) + requestIdBytes
+    + (seqno > 0n ? 1 + varintLength(seqno) : 0);
+}
+/**
+ * Encode the compatibility request used by Cursor when HTTP/2 is disabled.
+ * The public client defaults to field 1's hexadecimal data when its binary-append
+ * feature gate is unavailable, so OpenCodex uses that backwards-compatible shape.
+ */
+export function encodeCursorBidiAppendRequest(
+  payload: Uint8Array,
+  requestId: string,
+  seqno: bigint,
+): Uint8Array {
+  const requestIdBytes = requestIdMessageBytes(requestId);
+  const output = new Uint8Array(cursorBidiAppendRequestSize(payload.byteLength, requestId, seqno));
+  let offset = 0;
+  if (payload.byteLength > 0) {
+    const hexBytes = payload.byteLength * 2;
+    output[offset++] = 0x0a; // field 1, string data
+    offset = writeVarint(output, offset, BigInt(hexBytes));
+    for (const byte of payload) {
+      output[offset++] = HEX.charCodeAt(byte >>> 4);
+      output[offset++] = HEX.charCodeAt(byte & 0x0f);
+    }
+  }
+  output[offset++] = 0x12; // field 2, BidiRequestId request_id
+  offset = writeVarint(output, offset, BigInt(requestIdBytes.byteLength));
+  output.set(requestIdBytes, offset);
+  offset += requestIdBytes.byteLength;
+  if (seqno > 0n) {
+    output[offset++] = 0x18; // field 3, int64 append_seqno
+    offset = writeVarint(output, offset, seqno);
+  }
+  return output;
+}
+function cursorHttp1Error(operation: "RunSSE" | "BidiAppend", status: number): Error {
+  return new Error(`Cursor HTTP/1.1 ${operation} failed with HTTP ${status || "unknown"}`);
+}
+function asError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}
+/** Bun accepts Uint8Array request bodies; TypeScript's DOM BodyInit omits that runtime shape. */
+function bunFetchBody(bytes: Uint8Array): BodyInit {
+  return bytes as unknown as BodyInit;
+}
+/**
+ * Cursor's HTTP/1.1 compatibility bridge: a server-streaming RunSSE request carries
+ * output, while each client message is posted separately through BidiAppend.
+ */
+export class CursorHttp1BidiConnection {
+  private readonly abortController = new AbortController();
+  private readonly fetchImpl: typeof globalThis.fetch;
+  private readonly runSseReady: Promise<void>;
+  private resolveRunSseReady!: () => void;
+  private rejectRunSseReady!: (reason?: unknown) => void;
+  private appendChain: Promise<void> = Promise.resolve();
+  private nextAppendSeqno = 0n;
+  private committed = false;
+  private paused = false;
+  private resumeWaiters: Array<() => void> = [];
+  private terminal = false;
+  private closed = false;
+  destroyed = false;
+  constructor(private readonly options: CursorHttp1BidiOptions) {
+    this.fetchImpl = options.fetch ?? globalThis.fetch;
+    this.runSseReady = new Promise<void>((resolve, reject) => {
+      this.resolveRunSseReady = resolve;
+      this.rejectRunSseReady = reject;
+    });
+    // A RunSSE failure can happen before the first append reaches its await; observe it here so
+    // the readiness promise never becomes an unhandled rejection.
+    void this.runSseReady.catch(() => undefined);
+  }
+  start(): void {
+    void this.runSse().catch(error => {
+      this.rejectRunSseReady(error);
+      this.fail(asError(error));
+    });
+  }
+  write(frameBytes: Uint8Array): boolean {
+    if (this.closed || this.terminal) return false;
+    let frame;
+    try {
+      const decoded = consumeConnectFrames(frameBytes, CURSOR_MAX_EFFECTIVE_CONNECT_PAYLOAD_BYTES, 2);
+      if (decoded.frames.length !== 1 || decoded.consumedBytes !== frameBytes.byteLength) {
+        throw new Error("Cursor HTTP/1.1 append requires exactly one complete Connect frame");
+      }
+      frame = decoded.frames[0]!;
+      if (frame.flags !== 0) throw new Error(`Cursor HTTP/1.1 append does not support Connect flags ${frame.flags}`);
+      this.options.translatorBudget.chargeRetained(frame.payload.byteLength, { kind: "request_copies" });
+    } catch (error) {
+      this.fail(asError(error));
+      return false;
+    }
+    const pending: PendingAppend = {
+      payload: frame.payload,
+      seqno: this.nextAppendSeqno++,
+      rawBytesCharged: true,
+    };
+    this.appendChain = this.appendChain
+      .then(() => this.postAppend(pending))
+      .catch(error => this.fail(asError(error)))
+      .finally(() => {
+        if (!pending.rawBytesCharged) return;
+        pending.rawBytesCharged = false;
+        this.options.translatorBudget.releaseRetained(pending.payload.byteLength, { kind: "request_copies" });
+      });
+    return true;
+  }
+  pause(): void {
+    this.paused = true;
+  }
+  resume(): void {
+    if (!this.paused) return;
+    this.paused = false;
+    const waiters = this.resumeWaiters;
+    this.resumeWaiters = [];
+    for (const resume of waiters) resume();
+  }
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    this.destroyed = true;
+    this.resume();
+    const reason = new DOMException("Cursor HTTP/1.1 connection closed", "AbortError");
+    this.rejectRunSseReady(reason);
+    this.abortController.abort(reason);
+    queueMicrotask(() => this.finish());
+  }
+  destroy(): void {
+    this.close();
+  }
+  private commonHeaders(contentType: string): Headers {
+    return new Headers({
+      "content-type": contentType,
+      "connect-protocol-version": "1",
+      authorization: `Bearer ${this.options.token}`,
+      "x-ghost-mode": "true",
+      "x-cursor-client-version": this.options.clientVersion,
+      "x-cursor-client-type": "cli",
+      "x-request-id": this.options.requestId,
+      "x-session-id": this.options.sessionId,
+    });
+  }
+  private requestUrl(path: string): string {
+    const url = new URL(path, this.options.baseUrl);
+    if (url.protocol !== "https:") {
+      throw new Error("Cursor HTTP/1.1 transport requires an HTTPS base URL");
+    }
+    return url.toString();
+  }
+  private http1Init(url: string, init: RequestInit): RequestInit {
+    return withUpstreamHttpVersionValue(url, init, "http1.1") ?? init;
+  }
+  private markCommitted(): void {
+    if (this.committed) return;
+    this.committed = true;
+    this.options.callbacks.onCommitted();
+  }
+  private async runSse(): Promise<void> {
+    const url = this.requestUrl(CURSOR_RUN_SSE_PATH);
+    const requestId = toBinary(BidiRequestIdSchema, create(BidiRequestIdSchema, {
+      requestId: this.options.requestId,
+    }));
+    const response = await this.fetchImpl(url, this.http1Init(url, {
+      method: "POST",
+      headers: this.commonHeaders("application/connect+proto"),
+      body: bunFetchBody(encodeConnectFrame(requestId)),
+      redirect: "manual",
+      signal: this.abortController.signal,
+    }));
+    if (response.status !== 200) {
+      void response.body?.cancel().catch(() => undefined);
+      throw cursorHttp1Error("RunSSE", response.status);
+    }
+    if (!response.body) throw new Error("Cursor HTTP/1.1 RunSSE returned no response body");
+    // Cursor has accepted the request id once RunSSE returns successful headers. Do not race the
+    // first BidiAppend ahead of that registration.
+    this.resolveRunSseReady();
+    const reader = response.body.getReader();
+    try {
+      while (!this.closed && !this.terminal) {
+        await this.waitWhilePaused();
+        if (this.closed || this.terminal) break;
+        const { value, done } = await reader.read();
+        if (done) break;
+        if (value && value.byteLength > 0) this.options.callbacks.onData(value);
+      }
+      this.finish();
+    } finally {
+      try { reader.releaseLock(); } catch { /* a pending abort may still own it */ }
+    }
+  }
+  private async postAppend(pending: PendingAppend): Promise<void> {
+    if (this.closed || this.terminal) return;
+    await this.runSseReady;
+    if (this.closed || this.terminal) return;
+    const encodedBytes = cursorBidiAppendRequestSize(
+      pending.payload.byteLength,
+      this.options.requestId,
+      pending.seqno,
+    );
+    const reservation = this.options.translatorBudget.reserveTransient(encodedBytes, { kind: "request_copies" });
+    let body: Uint8Array;
+    try {
+      body = encodeCursorBidiAppendRequest(pending.payload, this.options.requestId, pending.seqno);
+    } catch (error) {
+      reservation.release();
+      throw error;
+    }
+    if (pending.rawBytesCharged) {
+      pending.rawBytesCharged = false;
+      this.options.translatorBudget.releaseRetained(pending.payload.byteLength, { kind: "request_copies" });
+    }
+    try {
+      const url = this.requestUrl(CURSOR_BIDI_APPEND_PATH);
+      const timeout = AbortSignal.timeout(CURSOR_HTTP1_APPEND_TIMEOUT_MS);
+      const signal = AbortSignal.any([this.abortController.signal, timeout]);
+      let response: Response;
+      try {
+        response = await this.fetchImpl(url, this.http1Init(url, {
+          method: "POST",
+          headers: this.commonHeaders("application/proto"),
+          body: bunFetchBody(body),
+          redirect: "manual",
+          signal,
+        }));
+      } catch (error) {
+        // A proven DNS/TCP pre-connect failure means no append bytes reached Cursor and replay is
+        // safe. Every ambiguous rejection stays conservative: the server may have accepted the
+        // append before the response path failed, so suppress replay exactly as the h2 path does.
+        if (!isPreConnectReachabilityError(error)) this.markCommitted();
+        throw error;
+      }
+      this.markCommitted();
+      if (response.status !== 200) {
+        void response.body?.cancel().catch(() => undefined);
+        throw cursorHttp1Error("BidiAppend", response.status);
+      }
+      const result = await readBoundedResponseBytes(response, {
+        maxBytes: CURSOR_HTTP1_APPEND_RESPONSE_MAX_BYTES,
+        signal,
+      });
+      if (result.oversized) throw new Error("Cursor HTTP/1.1 BidiAppend response exceeds 64 KiB");
+    } finally {
+      reservation.release();
+    }
+  }
+  private waitWhilePaused(): Promise<void> {
+    if (!this.paused) return Promise.resolve();
+    return new Promise(resolve => this.resumeWaiters.push(resolve));
+  }
+  private fail(error: Error): void {
+    if (this.terminal) return;
+    this.terminal = true;
+    this.destroyed = true;
+    this.resume();
+    this.rejectRunSseReady(error);
+    if (!this.abortController.signal.aborted) this.abortController.abort(error);
+    this.options.callbacks.onError(error);
+  }
+  private finish(): void {
+    if (this.terminal) return;
+    this.terminal = true;
+    this.destroyed = true;
+    this.resume();
+    this.options.callbacks.onEnd();
+  }
+}

package/src/adapters/cursor/live-models.ts CHANGED Viewed

@@ -1,5 +1,6 @@
 /**
- * Live Cursor model discovery via the `GetUsableModels` RPC (HTTP/2 + Connect-unary protobuf).
+ * Live Cursor model discovery via the `GetUsableModels` Connect-unary protobuf RPC.
+ * HTTP/2 remains the default; an explicit HTTP/1.1 provider pin uses Bun fetch instead.
  *
  * Returns the account's actually-usable model ids (the full effort-suffixed variants Cursor offers
  * for THIS plan), so the routed catalog reflects reality instead of a static superset. Failures are
@@ -14,6 +15,14 @@
  */
 import http2 from "node:http2";
 import { fromBinary } from "@bufbuild/protobuf";
+import type { UpstreamHttpVersion } from "../../types";
+import { readBoundedResponseBytes } from "../../lib/bounded-body";
+import {
+  isPinnedHttp1,
+  UpstreamHttpVersionTargetError,
+  withUpstreamHttpVersionValue,
+} from "../../lib/upstream-http-version";
+import { isValidModelDiscoveryModelId } from "../../providers/model-discovery-limits";
 import { GetUsableModelsResponseSchema } from "./gen/agent_pb";
 const CURSOR_GET_USABLE_MODELS_PATH = "/agent.v1.AgentService/GetUsableModels";
@@ -27,11 +36,14 @@ export interface CursorUsableModelsOptions {
   baseUrl?: string;
   clientVersion?: string;
   timeoutMs?: number;
+  upstreamHttpVersion?: UpstreamHttpVersion;
+  /** Test/embedding seam. Production discovery uses Bun's global fetch in HTTP/1.1 mode. */
+  fetch?: typeof globalThis.fetch;
 }
 export type CursorUsableModelsResult =
   | { ok: true; models: string[] }
-  | { ok: false; error: "auth" | "http" | "transport" | "timeout" | "decode" | "empty" | "too_large"; detail?: string };
+  | { ok: false; error: "auth" | "http" | "policy" | "transport" | "timeout" | "decode" | "empty" | "too_large"; detail?: string };
 /** Test-only seam for management connectivity probes; production callers retain the HTTP/2 path. */
 export function setFetchCursorUsableModelsForTests(next: CursorUsableModelsFetcher | null): void {
@@ -40,10 +52,11 @@ export function setFetchCursorUsableModelsForTests(next: CursorUsableModelsFetch
 const RETRYABLE_DISCOVERY_ERRORS = new Set(["timeout", "transport"]);
 const DISCOVERY_RETRY_TIMEOUT_MS = 3_000;
+const CURSOR_MAX_DISCOVERED_MODELS = 500;
 /**
- * Live discovery with ONE bounded retry for transient pre-response failures (fresh HTTP/2
- * session each attempt). Completed non-2xx responses ("http"), auth, decode, and empty are
+ * Live discovery with ONE bounded retry for transient pre-response failures (a fresh transport
+ * attempt each time). Completed non-2xx responses ("http"), auth, decode, and empty are
  * deterministic and never retried. The retry attempt's deadline is capped so a cache-miss
  * catalog poll cannot stall much past the primary timeout (~11.5s worst case, accepted in
  * devlog 260723_cursor_context_continuity/030).
@@ -83,6 +96,104 @@ function resolveCursorDiscoveryBaseUrl(raw: string): { ok: true; baseUrl: string
 }
 async function fetchCursorUsableModelsOnce(opts: CursorUsableModelsOptions): Promise<CursorUsableModelsResult> {
+  if (isPinnedHttp1(opts.upstreamHttpVersion)) return fetchCursorUsableModelsHttp1Once(opts);
+  return fetchCursorUsableModelsHttp2Once(opts);
+}
+function cursorDiscoveryHeaders(opts: CursorUsableModelsOptions): Record<string, string> {
+  return {
+    "content-type": "application/proto",
+    "connect-protocol-version": "1",
+    authorization: `Bearer ${opts.apiKey}`,
+    "x-ghost-mode": "true",
+    "x-cursor-client-version": opts.clientVersion ?? CURSOR_DISCOVERY_CLIENT_VERSION,
+    "x-cursor-client-type": "cli",
+    "x-session-id": crypto.randomUUID(),
+  };
+}
+function decodeCursorUsableModels(bytes: Uint8Array): CursorUsableModelsResult {
+  try {
+    const response = fromBinary(GetUsableModelsResponseSchema, bytes);
+    // Account filtering uses wire `model_id` values only. Aliases like `composer-2-5` must not
+    // make stale configured ids such as `composer-2` look activated.
+    const ids: string[] = [];
+    const seenIds = new Set<string>();
+    for (const model of response.models ?? []) {
+      const rawId = (model as { modelId?: string }).modelId;
+      if (typeof rawId !== "string") continue;
+      const id = rawId.trim();
+      if (!isValidModelDiscoveryModelId(id) || seenIds.has(id)) continue;
+      seenIds.add(id);
+      ids.push(id);
+      if (ids.length >= CURSOR_MAX_DISCOVERED_MODELS) break;
+    }
+    return ids.length > 0 ? { ok: true, models: ids } : { ok: false, error: "empty" };
+  } catch {
+    return { ok: false, error: "decode", detail: "Invalid GetUsableModels protobuf response" };
+  }
+}
+async function fetchCursorUsableModelsHttp1Once(opts: CursorUsableModelsOptions): Promise<CursorUsableModelsResult> {
+  let requestUrl: string;
+  try {
+    const parsed = new URL(CURSOR_GET_USABLE_MODELS_PATH, opts.baseUrl ?? "https://api2.cursor.sh");
+    if (parsed.protocol !== "https:") {
+      return { ok: false, error: "policy", detail: "Cursor HTTP/1.1 discovery requires HTTPS" };
+    }
+    requestUrl = parsed.toString();
+  } catch {
+    return { ok: false, error: "transport", detail: "Cursor HTTP/1.1 discovery base URL is invalid" };
+  }
+  const timeoutMs = opts.timeoutMs ?? 8000;
+  const controller = new AbortController();
+  let timedOut = false;
+  const timer = setTimeout(() => {
+    timedOut = true;
+    controller.abort(new DOMException(`No response within ${timeoutMs}ms`, "TimeoutError"));
+  }, timeoutMs);
+  try {
+    const init = withUpstreamHttpVersionValue(requestUrl, {
+      method: "POST",
+      headers: cursorDiscoveryHeaders(opts),
+      redirect: "manual",
+      signal: controller.signal,
+    }, opts.upstreamHttpVersion);
+    const response = await (opts.fetch ?? globalThis.fetch)(requestUrl, init);
+    if (response.status === 401 || response.status === 403) {
+      void response.body?.cancel().catch(() => undefined);
+      return { ok: false, error: "auth", detail: `HTTP ${response.status}` };
+    }
+    if (response.status !== 200) {
+      void response.body?.cancel().catch(() => undefined);
+      return { ok: false, error: "http", detail: `HTTP ${response.status || "unknown"}` };
+    }
+    const contentLength = Number(response.headers.get("content-length") ?? 0);
+    if (Number.isFinite(contentLength) && contentLength > CURSOR_MODEL_DISCOVERY_MAX_BYTES) {
+      void response.body?.cancel().catch(() => undefined);
+      return { ok: false, error: "too_large", detail: "GetUsableModels response exceeds 4 MiB" };
+    }
+    const body = await readBoundedResponseBytes(response, {
+      maxBytes: CURSOR_MODEL_DISCOVERY_MAX_BYTES,
+      signal: controller.signal,
+    });
+    if (body.oversized) {
+      return { ok: false, error: "too_large", detail: "GetUsableModels response exceeds 4 MiB" };
+    }
+    return decodeCursorUsableModels(body.bytes);
+  } catch (error) {
+    if (error instanceof UpstreamHttpVersionTargetError) {
+      return { ok: false, error: "policy", detail: error.message };
+    }
+    return timedOut
+      ? { ok: false, error: "timeout", detail: `No response within ${timeoutMs}ms` }
+      : { ok: false, error: "transport", detail: "HTTP/1.1 request failed" };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+async function fetchCursorUsableModelsHttp2Once(opts: CursorUsableModelsOptions): Promise<CursorUsableModelsResult> {
   const baseUrl = (opts.baseUrl ?? "https://api2.cursor.sh").replace(/\/+$/, "");
   const timeoutMs = opts.timeoutMs ?? 8000;
@@ -118,13 +229,7 @@ async function fetchCursorUsableModelsOnce(opts: CursorUsableModelsOptions): Pro
       req = client.request({
         ":method": "POST",
         ":path": CURSOR_GET_USABLE_MODELS_PATH,
-        "content-type": "application/proto",
-        "connect-protocol-version": "1",
-        authorization: `Bearer ${opts.apiKey}`,
-        "x-ghost-mode": "true",
-        "x-cursor-client-version": opts.clientVersion ?? CURSOR_DISCOVERY_CLIENT_VERSION,
-        "x-cursor-client-type": "cli",
-        "x-session-id": crypto.randomUUID(),
+        ...cursorDiscoveryHeaders(opts),
       });
     } catch {
       return close({ ok: false, error: "transport", detail: "HTTP/2 request setup failed" });
@@ -161,25 +266,7 @@ async function fetchCursorUsableModelsOnce(opts: CursorUsableModelsOptions): Pro
         return close({ ok: false, error: "auth", detail: `HTTP ${status}` });
       }
       if (status !== 200) return close({ ok: false, error: "http", detail: `HTTP ${status || "unknown"}` });
-      try {
-        const response = fromBinary(GetUsableModelsResponseSchema, new Uint8Array(Buffer.concat(chunks)));
-        // Account filtering uses wire `model_id` values only. Aliases like `composer-2-5` must not
-        // make stale configured ids such as `composer-2` look activated.
-        const ids: string[] = [];
-        const seenIds = new Set<string>();
-        for (const model of response.models ?? []) {
-          const rawId = (model as { modelId?: string }).modelId;
-          if (typeof rawId !== "string") continue;
-          const id = rawId.trim();
-          if (id.length === 0 || /[\x00-\x1f]/.test(id) || seenIds.has(id)) continue;
-          seenIds.add(id);
-          ids.push(id);
-          if (ids.length === 500) break;
-        }
-        close(ids.length > 0 ? { ok: true, models: ids } : { ok: false, error: "empty" });
-      } catch {
-        close({ ok: false, error: "decode", detail: "Invalid GetUsableModels protobuf response" });
-      }
+      close(decodeCursorUsableModels(new Uint8Array(Buffer.concat(chunks))));
     });
     req.end(); // CRITICAL: no body argument (empty Buffer breaks Bun's HTTP/2 framing).