@bitkyc08/opencodex 2.10.2 → 2.11.0

package/src/adapters/google.ts

@@ -30,7 +30,7 @@ import {
   type TranslatorBudget,
 } from "../lib/translator-budget";
 import { buildNonOpenAIToolCatalogNudgeForTools } from "./tool-catalog-nudge";
-import { mapReasoningEffort } from "../reasoning-effort";
+import { configuredReasoningEfforts, mapReasoningEffort } from "../reasoning-effort";
 
 // 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
@@ -340,12 +340,22 @@ export function createGoogleAdapter(provider: OcxProviderConfig): ProviderAdapte
       if (parsed.options.temperature !== undefined) generationConfig.temperature = parsed.options.temperature;
       if (parsed.options.topP !== undefined) generationConfig.topP = parsed.options.topP;
       if (parsed.options.stopSequences) generationConfig.stopSequences = parsed.options.stopSequences;
-      const directFlashThinking = provider.googleMode !== "vertex"
-        && provider.googleMode !== "cloud-code-assist"
-        && (parsed.modelId === "gemini-3.5-flash" || parsed.modelId === "gemini-3.6-flash")
+      // Effort → thinkingLevel follows the configured ladder: any model advertising reasoning
+      // efforts (registry preset or user config) sends the mapped level, so a picker-selected
+      // effort actually reaches the wire (gemini-3.1-pro-preview ships a ladder). The original
+      // gemini-3.5/3.6-flash direct-mode slice stays hardcoded so unladdered configs keep their
+      // current behavior; Vertex participates only through an explicitly configured ladder (the
+      // seed google-vertex entry ships none). Image models are excluded — thinkingConfig would
+      // suppress the responseModalities fallback below. CCA maps effort on its envelope path.
+      const thinkingEligible = provider.googleMode !== "cloud-code-assist"
+        && !isImageCapableModel(parsed.modelId)
+        && (configuredReasoningEfforts(provider, parsed.modelId) !== undefined
+          || (provider.googleMode !== "vertex"
+            && (parsed.modelId === "gemini-3.5-flash" || parsed.modelId === "gemini-3.6-flash")));
+      const thinkingLevel = thinkingEligible
         ? mapReasoningEffort(provider, parsed.modelId, parsed.options.reasoning)
         : undefined;
-      if (directFlashThinking) generationConfig.thinkingConfig = { thinkingLevel: directFlashThinking };
+      if (thinkingLevel) generationConfig.thinkingConfig = { thinkingLevel };
       if (!generationConfig.thinkingConfig && isImageCapableModel(parsed.modelId)) {
         generationConfig.responseModalities = ["TEXT", "IMAGE"];
       }

package/src/adapters/openai-chat.ts

@@ -3,6 +3,7 @@ import type { AdapterEvent, OcxAssistantMessage, OcxContentPart, OcxMessage, Ocx
 import { isAllowedToolChoice, modelInList, namespacedToolName, resolveToolChoiceWireName, toolAllowedByChoice } from "../types";
 import { mapReasoningEffort, modelRecordValue } from "../reasoning-effort";
 import { debugProviderDiagnostic } from "../lib/debug";
+import { sseFieldValue } from "../lib/sse-decoder";
 import { isDebugEnabled } from "../lib/debug-settings";
 import { isCyberPolicyCode } from "../lib/errors";
 import { redactSecretString } from "../lib/redact";
@@ -818,6 +819,26 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
       if (provider.promptCacheKey && parsed.options.promptCacheKey !== undefined) {
         body.prompt_cache_key = parsed.options.promptCacheKey;
       }
+      // Responses `text.format` -> chat `response_format`. json_object maps 1:1; json_schema
+      // re-nests the flattened Responses fields under `json_schema` — the exact inverse of
+      // responseFormatToText in src/chat/inbound.ts. Forwarded unconditionally (like `stop`):
+      // response_format is a first-class Chat Completions field, it is only present when the
+      // caller explicitly asked for structured output, and a backend that rejects it should
+      // fail loud rather than silently return prose the caller will try to JSON.parse.
+      const textFormat = parsed.options.textFormat;
+      if (textFormat?.type === "json_object") {
+        body.response_format = { type: "json_object" };
+      } else if (textFormat?.type === "json_schema") {
+        body.response_format = {
+          type: "json_schema",
+          json_schema: {
+            name: textFormat.name ?? "response",
+            ...(textFormat.description !== undefined ? { description: textFormat.description } : {}),
+            ...(textFormat.schema !== undefined ? { schema: textFormat.schema } : {}),
+            ...(textFormat.strict !== undefined ? { strict: textFormat.strict } : {}),
+          },
+        };
+      }
 
       if (tools) {
         // Default-ON for chat-completions providers (user decision 260709): the buffered
@@ -927,8 +948,9 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
       // Yields adapter events and returns "terminate" for a terminal frame ([DONE] / error) that
       // must end the stream, or "continue" otherwise. Mutates the closure's terminal-signal state.
       const handleDataLine = function* (line: string): Generator<AdapterEvent, "continue" | "terminate"> {
-        if (!line.startsWith("data: ")) return "continue";
-        const payload = line.slice(6).trim();
+        const rawPayload = sseFieldValue(line, "data");
+        if (rawPayload === null) return "continue";
+        const payload = rawPayload.trim();
         if (payload === "[DONE]") {
           yield* flushToolCalls();
           const stopReason = stopReasonFor(finishReason);

package/src/adapters/openai-responses.ts

@@ -1048,7 +1048,8 @@ function stripInputImagesDeep(value: unknown): unknown {
  */
 function buildRoutedCompactionBody(body: unknown): unknown {
   if (!isPlainObject(body)) return body;
-  const { tools: _tools, tool_choice: _toolChoice, parallel_tool_calls: _parallel, ...rest } = body;
+  // `text` goes with the tool fields: the summary must be prose, not schema-constrained JSON.
+  const { tools: _tools, tool_choice: _toolChoice, parallel_tool_calls: _parallel, text: _text, ...rest } = body;
   const input = Array.isArray(body.input) ? body.input : [];
   const kept = input.filter(item => !isPlainObject(item)
     // `additional_tools` is how Codex Desktop's responses-lite shape carries tools;

package/src/bridge.ts

@@ -827,8 +827,10 @@ export function bridgeToResponsesSSE(
               if (currentReasoning) closeCurrentReasoning();
               if (currentRawReasoning) closeCurrentRawReasoning();
               flushHiddenRawReasoning();
-              // Reasoning consumed by a text turn, not a tool call: no cache target.
-              rawReasoningForNextToolCall = "";
+              // Reasoning consumed by a REAL text turn, not a tool call: no cache target.
+              // Empty text deltas must not wipe reasoning that precedes a tool call
+              // (chat-completions providers emit empty content deltas mid-tool-turn).
+              if (event.text.length > 0) rawReasoningForNextToolCall = "";
               if (currentToolCall) closeCurrentToolCall();
               // Only flush on an explicit phase change. A later delta that omits `phase` must
               // keep appending to the current message rather than wiping the earlier phase.
@@ -880,7 +882,7 @@ export function bridgeToResponsesSSE(
               if (currentMsg) closeCurrentMessage("commentary");
               if (currentRawReasoning) closeCurrentRawReasoning();
               flushHiddenRawReasoning();
-              rawReasoningForNextToolCall = "";
+              if (event.thinking.length > 0) rawReasoningForNextToolCall = "";
               if (currentToolCall) closeCurrentToolCall();
               if (!currentReasoning) {
                 const itemId = `rs_${uuid()}`;
@@ -1561,7 +1563,9 @@ function buildResponseJSONWithBudget(
         if (currentText && e.phase !== undefined && currentTextPhase !== e.phase) flushText("commentary");
         if (currentSummaryReasoning) flushSummaryReasoning();
         if (currentRawReasoning) flushRawReasoning();
-        rawReasoningForNextToolCall = "";
+        // Empty text deltas (batch chat responses always carry content, often "") must
+        // not wipe reasoning that precedes a tool call (#950 non-streaming path).
+        if (e.text.length > 0) rawReasoningForNextToolCall = "";
         if (currentToolCallId) flushToolCall();
         // Compaction turns keep the summary out of normal message output (replay dedup — see
         // bridgeToResponsesSSE); it ships only inside the synthetic compaction item below.
@@ -1580,7 +1584,7 @@ function buildResponseJSONWithBudget(
       case "thinking_delta":
         if (currentText) flushText("commentary");
         if (currentRawReasoning) flushRawReasoning();
-        rawReasoningForNextToolCall = "";
+        if (e.thinking.length > 0) rawReasoningForNextToolCall = "";
         if (currentToolCallId) flushToolCall();
         {
           ({ value: currentSummaryReasoning, bytes: currentSummaryReasoningBytes } = appendBatchString(

package/src/chat/outbound.ts

@@ -7,7 +7,7 @@
  */
 type Rec = Record<string, unknown>;
 
-import { decodeServerSentEvents } from "../lib/sse-decoder";
+import { decodeServerSentEvents, sseFieldValue } from "../lib/sse-decoder";
 import { isTranslatorBudgetExceededError, type TranslatorBudget } from "../lib/translator-budget";
 import { classifyError, CYBER_POLICY_ERROR_CODE, isCyberPolicyCode, isCyberPolicyMessage } from "../lib/errors";
 
@@ -671,8 +671,9 @@ export async function collectChatCompletion(
         const rawFrame = buffer.slice(0, sep);
         buffer = replaceRetained(buffer, buffer.slice(sep + 2), "live_transient");
         for (const line of rawFrame.split("\n")) {
-          if (!line.startsWith("data: ")) continue;
-          const data = line.slice(6).trim();
+          const rawData = sseFieldValue(line, "data");
+          if (rawData === null) continue;
+          const data = rawData.trim();
           if (!data || data === "[DONE]") continue;
           let parsed: unknown;
           try { parsed = JSON.parse(data); } catch { continue; }

package/src/claude/desktop-3p.ts

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
-import { copyFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { atomicWriteFile } from "../config";
@@ -103,6 +103,45 @@ interface Desktop3pMetadata {
   [key: string]: unknown;
 }
 
+export type Desktop3pLibraryKind =
+  | "not_installed"
+  | "standard"
+  | "gateway_ours"
+  | "gateway_drifted"
+  | "foreign"
+  | "no_owned_state"
+  | "broken"
+  | "unsafe";
+
+export interface Desktop3pLibraryInspection {
+  kind: Desktop3pLibraryKind;
+  libraryPath: string;
+  selectedProfilePath: string | null;
+  appliedId: string | null;
+  /** Paths of opencodex-owned rows that are not selected by Desktop. */
+  residualPaths: string[];
+  /** Bounded reason code; never includes metadata or profile contents. */
+  reason?: "metadata_unreadable" | "unsafe_applied_id" | "invalid_owned_profile";
+  fingerprint?: string;
+  /**
+   * Whether Desktop's applied selection is our owned entry, by ID match alone.
+   * `null` = undeterminable (no metadata, unreadable metadata, or no appliedId);
+   * a readable appliedId with no owned entry is a KNOWN false, not unknown.
+   * Deliberately independent of profile-file health: the status contract
+   * predates this inspector and callers render tri-state.
+   */
+  ownedProfileActive: boolean | null;
+}
+
+export interface Desktop3pRemovalResult {
+  ok: boolean;
+  changed: boolean;
+  kind: "removed" | "noop" | "cleanup_incomplete" | "unsafe" | "write_failed";
+  libraryPath: string;
+  residualPaths?: string[];
+  reason?: string;
+}
+
 let desktop3pRegistry = new Map<string, string>();
 let desktop3pAliasesByRoute = new Map<string, string>();
 
@@ -327,6 +366,186 @@ function parseMetadata(path: string): Desktop3pMetadata {
   return { ...parsed, entries: parsed.entries };
 }
 
+const SAFE_DESKTOP_PROFILE_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isOwnedDesktopEntry(entry: Desktop3pMetadataEntry | undefined): boolean {
+  return entry?.name === "opencodex" || entry?.name === "opencodex-standard";
+}
+
+/** A gateway row is removable; the selected standard row must always remain. */
+function isOwnedDesktopGatewayEntry(entry: Desktop3pMetadataEntry | undefined): boolean {
+  return entry?.name === "opencodex";
+}
+
+function profilePath(libraryPath: string, id: string): string {
+  return join(libraryPath, `${id}.json`);
+}
+
+/**
+ * Read Desktop's selected config without changing its library.
+ *
+ * This is intentionally separate from the eager writer below: status probes must
+ * never manufacture a config-library directory on a machine without Desktop.
+ */
+export function inspectDesktop3pConfigLibrary(
+  options: Desktop3pConfigLibraryOptions & { appliedFingerprint?: string | null } = {},
+): Desktop3pLibraryInspection {
+  const libraryPath = resolveDesktop3pConfigLibraryPath(options);
+  if (!existsSync(libraryPath)) {
+    return { kind: "not_installed", libraryPath, selectedProfilePath: null, appliedId: null, residualPaths: [], ownedProfileActive: null };
+  }
+
+  const metadataPath = join(libraryPath, "_meta.json");
+  if (!existsSync(metadataPath)) {
+    return { kind: "no_owned_state", libraryPath, selectedProfilePath: null, appliedId: null, residualPaths: [], ownedProfileActive: null };
+  }
+
+  let metadata: Desktop3pMetadata;
+  try {
+    metadata = parseMetadata(metadataPath);
+  } catch {
+    return {
+      kind: "unsafe", libraryPath, selectedProfilePath: null, appliedId: null, residualPaths: [], reason: "metadata_unreadable", ownedProfileActive: null,
+    };
+  }
+  const appliedId = typeof metadata.appliedId === "string" ? metadata.appliedId : null;
+  if (appliedId === null) {
+    return { kind: "no_owned_state", libraryPath, selectedProfilePath: null, appliedId: null, residualPaths: [], ownedProfileActive: null };
+  }
+  const selected = metadata.entries.find(entry => entry?.id === appliedId);
+  // A readable appliedId with no owned entry is a KNOWN false, not unknown.
+  const ownedProfileActive = isOwnedDesktopEntry(selected);
+  if (!SAFE_DESKTOP_PROFILE_ID.test(appliedId)) {
+    return {
+      kind: "unsafe", libraryPath, selectedProfilePath: null, appliedId, residualPaths: [], reason: "unsafe_applied_id", ownedProfileActive,
+    };
+  }
+
+  const selectedProfilePath = profilePath(libraryPath, appliedId);
+  const residualPaths = metadata.entries
+    .filter(entry => isOwnedDesktopGatewayEntry(entry) && entry.id !== appliedId && SAFE_DESKTOP_PROFILE_ID.test(entry.id))
+    .flatMap(entry => [profilePath(libraryPath, entry.id), `${profilePath(libraryPath, entry.id)}.bak`])
+    .filter(existsSync);
+  if (!existsSync(selectedProfilePath)) {
+    return { kind: "broken", libraryPath, selectedProfilePath, appliedId, residualPaths, ownedProfileActive };
+  }
+
+  let profile: Record<string, unknown>;
+  let fingerprint: string;
+  try {
+    const source = readFileSync(selectedProfilePath, "utf8");
+    const parsed = JSON.parse(source) as unknown;
+    if (!isRecord(parsed)) return { kind: "broken", libraryPath, selectedProfilePath, appliedId, residualPaths, ownedProfileActive };
+    profile = parsed;
+    fingerprint = createHash("sha256").update(source).digest("hex").slice(0, 16);
+  } catch {
+    return { kind: "broken", libraryPath, selectedProfilePath, appliedId, residualPaths, ownedProfileActive };
+  }
+  if (!isOwnedDesktopEntry(selected)) {
+    return { kind: "foreign", libraryPath, selectedProfilePath, appliedId, residualPaths, fingerprint, ownedProfileActive };
+  }
+  if (profile.inferenceProvider === undefined) {
+    return { kind: "standard", libraryPath, selectedProfilePath, appliedId, residualPaths, fingerprint, ownedProfileActive };
+  }
+  const validGateway = profile.inferenceProvider === "gateway"
+    && profile.inferenceCredentialKind === "static"
+    && typeof profile.inferenceGatewayBaseUrl === "string"
+    && typeof profile.inferenceGatewayApiKey === "string";
+  if (!validGateway) {
+    return {
+      kind: "unsafe", libraryPath, selectedProfilePath, appliedId, residualPaths, fingerprint, reason: "invalid_owned_profile", ownedProfileActive,
+    };
+  }
+  return {
+    kind: options.appliedFingerprint && options.appliedFingerprint === fingerprint ? "gateway_ours" : "gateway_drifted",
+    libraryPath, selectedProfilePath, appliedId, residualPaths, fingerprint, ownedProfileActive,
+  };
+}
+
+/**
+ * Select a credential-free standard profile before deleting an owned gateway.
+ * The old metadata row remains as a retry locator only until both its profile
+ * and backup are absent; successful cleanup removes it in the same operation.
+ */
+export function removeDesktop3pStandardPivot(
+  options: Desktop3pConfigLibraryOptions & {
+    appliedFingerprint?: string | null;
+    unlink?: (path: string) => void;
+  } = {},
+): Desktop3pRemovalResult {
+  const inspected = inspectDesktop3pConfigLibrary(options);
+  if (inspected.kind === "not_installed" || inspected.kind === "no_owned_state") {
+    return { ok: true, changed: false, kind: "noop", libraryPath: inspected.libraryPath };
+  }
+  if (inspected.kind === "broken" || inspected.kind === "unsafe" || inspected.kind === "gateway_drifted") {
+    return { ok: false, changed: false, kind: "unsafe", libraryPath: inspected.libraryPath, reason: inspected.reason };
+  }
+  if (!inspected.appliedId || !SAFE_DESKTOP_PROFILE_ID.test(inspected.appliedId)) {
+    return { ok: false, changed: false, kind: "unsafe", libraryPath: inspected.libraryPath, reason: "unsafe_applied_id" };
+  }
+
+  const metadataPath = join(inspected.libraryPath, "_meta.json");
+  try {
+    const metadata = parseMetadata(metadataPath);
+    const selectedId = inspected.appliedId;
+    // When Desktop is actively using our gateway, pivot only that selected row
+    // first. Any second owned row is residue for a later standard-mode retry;
+    // this preserves the selected-row preference after an interrupted cleanup.
+    const targetIds = inspected.kind === "gateway_ours"
+      ? [selectedId]
+      : metadata.entries
+        .filter(isOwnedDesktopGatewayEntry)
+        .map(entry => entry.id)
+        .filter(id => SAFE_DESKTOP_PROFILE_ID.test(id));
+    if (targetIds.length === 0) return { ok: true, changed: false, kind: "noop", libraryPath: inspected.libraryPath };
+
+    let metadataAfterPivot = metadata;
+    if (inspected.kind === "gateway_ours") {
+      const standardId = randomUUID();
+      const standardPath = profilePath(inspected.libraryPath, standardId);
+      atomicWriteFile(standardPath, "{}\n");
+      const standardEntry: Desktop3pMetadataEntry = { id: standardId, name: "opencodex-standard" };
+      metadataAfterPivot = { ...metadata, appliedId: standardId, entries: [...metadata.entries, standardEntry] };
+      atomicWriteFile(metadataPath, JSON.stringify(metadataAfterPivot, null, 2) + "\n");
+    }
+
+    const residualPaths: string[] = [];
+    for (const id of targetIds) {
+      for (const candidate of [profilePath(inspected.libraryPath, id), `${profilePath(inspected.libraryPath, id)}.bak`]) {
+        try {
+          if (existsSync(candidate)) (options.unlink ?? unlinkSync)(candidate);
+        } catch {
+          // Only the path is allowed to leave this credential-bearing cleanup boundary.
+        }
+        if (existsSync(candidate)) residualPaths.push(candidate);
+      }
+    }
+    const ownedResiduePaths = metadataAfterPivot.entries
+      .filter(entry => isOwnedDesktopGatewayEntry(entry) && !targetIds.includes(entry.id) && SAFE_DESKTOP_PROFILE_ID.test(entry.id))
+      .flatMap(entry => [profilePath(inspected.libraryPath, entry.id), `${profilePath(inspected.libraryPath, entry.id)}.bak`])
+      .filter(existsSync);
+    if (residualPaths.length > 0 || ownedResiduePaths.length > 0) {
+      return {
+        ok: false, changed: true, kind: "cleanup_incomplete", libraryPath: inspected.libraryPath,
+        residualPaths: [...new Set([...residualPaths, ...ownedResiduePaths])],
+      };
+    }
+    // Do not leave a metadata row pointing at a deleted profile. For a foreign
+    // selection this only removes proven opencodex residues; appliedId is kept.
+    atomicWriteFile(
+      metadataPath,
+      JSON.stringify({ ...metadataAfterPivot, entries: metadataAfterPivot.entries.filter(entry => !targetIds.includes(entry.id)) }, null, 2) + "\n",
+    );
+    return { ok: true, changed: true, kind: "removed", libraryPath: inspected.libraryPath };
+  } catch {
+    return { ok: false, changed: false, kind: "write_failed", libraryPath: inspected.libraryPath };
+  }
+}
+
 /** Write and apply the opencodex config in Claude Desktop 3P's config library. */
 export function writeDesktop3pConfig(
   port: number,
@@ -343,7 +562,8 @@ export function writeDesktop3pConfig(
   try {
     mkdirSync(libraryPath, { recursive: true, mode: 0o700 });
     const metadata = parseMetadata(metadataPath);
-    const existing = metadata.entries.find(entry => entry?.name === "opencodex" && typeof entry.id === "string");
+    const selected = metadata.entries.find(entry => entry?.id === metadata.appliedId && isOwnedDesktopGatewayEntry(entry));
+    const existing = selected ?? metadata.entries.find(entry => isOwnedDesktopGatewayEntry(entry) && typeof entry.id === "string");
     const id = existing?.id ?? randomUUID();
     configPath = join(libraryPath, `${id}.json`);
     const entry: Desktop3pMetadataEntry = existing ? { ...existing, id, name: "opencodex" } : { id, name: "opencodex" };

package/src/claude/outbound.ts

@@ -16,6 +16,7 @@ import {
   TranslatorBudgetExceededError,
   type TranslatorBudget,
 } from "../lib/translator-budget";
+import { sseFieldOffset, sseFieldValue } from "../lib/sse-decoder";
 
 type Rec = Record<string, unknown>;
 
@@ -588,10 +589,16 @@ export function responsesSseToAnthropicSse(
                       while (lineStart <= rawFrame.length) {
                         const newline = rawFrame.indexOf("\n", lineStart);
                         const lineEnd = newline === -1 ? rawFrame.length : newline;
-                        if (rawFrame.startsWith("event: ", lineStart)) {
-                          eventName = rawFrame.slice(lineStart + 7, lineEnd).trim();
-                        } else if (rawFrame.startsWith("data: ", lineStart)) {
-                          const fragmentStart = lineStart + 6;
+                        // The space after the colon is optional in text/event-stream (#1170);
+                        // compute the value offset the same way sseFieldValue does, without
+                        // slicing the line first — the byte accounting below is keyed to
+                        // offsets into rawFrame.
+                        const eventOffset = sseFieldOffset(rawFrame, lineStart, lineEnd, "event");
+                        const dataOffset = sseFieldOffset(rawFrame, lineStart, lineEnd, "data");
+                        if (eventOffset !== -1) {
+                          eventName = rawFrame.slice(eventOffset, lineEnd).trim();
+                        } else if (dataOffset !== -1) {
+                          const fragmentStart = dataOffset;
                           const fragmentBytes = utf8SliceBytes(rawFrame, fragmentStart, lineEnd);
                           const fragmentReservation = translatorBudget.reserveTransient(fragmentBytes, { kind: "live_transient" });
                           let fragmentCommitted = false;
@@ -861,8 +868,10 @@ export async function collectAnthropicMessage(
         let eventName = "";
         let dataLine = "";
         for (const line of rawFrame.split("\n")) {
-          if (line.startsWith("event: ")) eventName = line.slice(7).trim();
-          else if (line.startsWith("data: ")) dataLine += line.slice(6);
+          const eventValue = sseFieldValue(line, "event");
+          if (eventValue !== null) { eventName = eventValue.trim(); continue; }
+          const dataValue = sseFieldValue(line, "data");
+          if (dataValue !== null) dataLine += dataValue;
         }
         if (!eventName || !dataLine) continue;
         let data: unknown;

package/src/cli/account-api.ts

@@ -21,6 +21,8 @@ export interface AccountRow {
   masked?: string;
   active: boolean;
   needsReauth?: boolean;
+  /** Codex pool selection order, higher used earlier. Absent where ordering does not apply. */
+  priority?: number;
   quota?: CodexQuotaDto | null;
 }
 
@@ -172,6 +174,7 @@ interface CodexAccountDto {
   plan?: string;
   isMain?: boolean;
   needsReauth?: boolean;
+  priority?: number;
   quota?: CodexQuotaDto | null;
 }
 
@@ -219,6 +222,7 @@ export async function fetchCodexRows(
     plan: a.plan,
     active: a.id === activeId,
     needsReauth: a.needsReauth,
+    priority: typeof a.priority === "number" ? a.priority : 0,
     ...(forceRefresh ? { quota: projectQuota(a.quota) } : {}),
   }));
   return { rows, activeId, autoSwitchThreshold, status: 200 };

package/src/cli/account-extended.ts

@@ -1,4 +1,10 @@
 import { loadConfig } from "../config";
+import {
+  MAX_ACCOUNT_PRIORITY,
+  MIN_ACCOUNT_PRIORITY,
+  normalizeAccountPriority,
+  parseAccountPriority,
+} from "../codex/pool-rotation";
 import {
   apiError,
   apiJson,
@@ -18,6 +24,7 @@ const EXTENDED_USAGE = `Usage:
   ocx account refresh <provider> [--json]
   ocx account auto-switch <provider> <on|off|status|threshold <0-100>> [--json]
   ocx account alias <provider> <id|main> <display-name|-> [--json]
+  ocx account priority <provider> <id|main> [<-100..100|first|earlier|normal|later|last|reset>] [--json]
   ocx account remove <provider> <id|main> --yes [--json]
   ocx account clear-cooldown <provider> <id|main> [--json]
   ocx account add-key <provider> [--label <label>] [--json]`;
@@ -316,6 +323,111 @@ export async function cmdClearCooldown(args: string[], deps: AccountDeps): Promi
   return 0;
 }
 
+/**
+ * Named selection orders. The words convey sequence rather than rank because the
+ * pool moves down the list only when everything above it is drained — "high
+ * priority" would suggest the account gets more traffic, which is not what
+ * ordering does.
+ */
+const PRIORITY_PRESETS: Record<string, number> = {
+  first: 2,
+  earlier: 1,
+  normal: 0,
+  later: -1,
+  last: -2,
+};
+
+function priorityPresetName(priority: number): string | null {
+  return Object.entries(PRIORITY_PRESETS).find(([, value]) => value === priority)?.[0] ?? null;
+}
+
+function formatPriority(priority: number): string {
+  const preset = priorityPresetName(priority);
+  const signed = priority > 0 ? `+${priority}` : String(priority);
+  return preset ? `${signed} (${preset})` : signed;
+}
+
+/** `null` = reset to the default; `undefined` = unparseable. */
+function parsePriorityArgument(raw: string): number | null | undefined {
+  const word = raw.trim().toLowerCase();
+  if (word === "reset") return null;
+  // Own keys only: `in` also matches "constructor", "__proto__", and friends.
+  if (Object.hasOwn(PRIORITY_PRESETS, word)) return PRIORITY_PRESETS[word];
+  // The regex only rules out shapes Number() would coerce ("1e2", " 1 ", ""); the range
+  // itself comes from the core parser so the CLI cannot drift from what the API accepts.
+  if (!/^[+-]?\d+$/.test(word)) return undefined;
+  return parseAccountPriority(Number(word)) ?? undefined;
+}
+
+export async function cmdPriority(args: string[], deps: AccountDeps): Promise<number> {
+  const wantsJson = flag(args, "--json");
+  const name = args.shift();
+  const requestedId = args.shift();
+  const requestedPriority = args.shift();
+  if (!name || !requestedId || args.length) return usage();
+  const classified = configAndType(deps, name);
+  if ("error" in classified) return usage(`Error: ${classified.error}`);
+  if (classified.type !== "codex") {
+    return usage("Error: selection order only applies to the openai Codex account pool");
+  }
+  const id = requestedId === "main" ? MAIN_ID : requestedId;
+
+  // Validate before touching the network so a typo never reaches the proxy.
+  let priority: number | null | undefined;
+  if (requestedPriority !== undefined) {
+    priority = parsePriorityArgument(requestedPriority);
+    if (priority === undefined) {
+      return usage(`Error: selection order must be an integer ${MIN_ACCOUNT_PRIORITY}..${MAX_ACCOUNT_PRIORITY}, one of ${Object.keys(PRIORITY_PRESETS).join("/")}, or reset`);
+    }
+  }
+
+  const baseUrl = await resolveBaseUrl(deps);
+  if (!baseUrl) return proxyUnreachable();
+
+  // No value means "show" — a read must not rewrite what it is reporting.
+  if (priority === undefined) {
+    const result = await fetchCodexRows(deps, baseUrl);
+    const failed = familyFailure(result, `failed to read ${name} accounts`);
+    if (failed !== null) return failed;
+    const row = result.rows.find(candidate => candidate.id === id);
+    if (!row) return usage(`Error: no ${name} account ${requestedId}`);
+    const current = normalizeAccountPriority(row.priority);
+    if (wantsJson) {
+      console.log(JSON.stringify(
+        { ok: true, provider: name, id, priority: current, preset: priorityPresetName(current) },
+        null,
+        2,
+      ));
+    } else {
+      console.log(`${name}: ${requestedId} selection order is ${formatPriority(current)}`);
+    }
+    return 0;
+  }
+
+  const response = await apiJson(deps, baseUrl, "PUT", "/api/codex-auth/accounts/priority", { id, priority });
+  if (response.status === 0) return proxyUnreachable();
+  if (response.status !== 200) return apiError(response.json, `failed to set selection order for ${requestedId}`);
+  const applied = typeof response.json.priority === "number" ? response.json.priority : (priority ?? 0);
+  if (wantsJson) {
+    console.log(JSON.stringify(
+      { ok: true, provider: name, id, priority: applied, preset: priorityPresetName(applied) },
+      null,
+      2,
+    ));
+  } else {
+    console.log(`${name}: ${requestedId} selection order is now ${formatPriority(applied)}`);
+  }
+  // Not cmdUse's note: re-ordering takes effect on the next unbound request rather than
+  // only on new sessions, because preemption moves those requests up immediately.
+  console.error("Takes effect from the next unbound request; running threads keep their current account until drained.");
+  // The release is not optional and not conditional on the value changing, so it has to be
+  // stated: this route is the only way to clear a pin without immediately setting another,
+  // which means a write storing the order an account already had still releases it. Without
+  // this line that is a silent side effect of a command that looks purely declarative.
+  console.error('Also releases any manual "use this account now" pin, on any account.');
+  return 0;
+}
+
 export async function cmdAlias(args: string[], deps: AccountDeps): Promise<number> {
   const wantsJson = flag(args, "--json");
   const name = args.shift();