@bitkyc08/opencodex 2.7.17 → 2.7.19

package/src/adapters/openai-chat.ts

@@ -2,6 +2,7 @@ import type { ProviderAdapter } from "./base";
 import type { AdapterEvent, OcxAssistantMessage, OcxContentPart, OcxMessage, OcxParsedRequest, OcxProviderConfig, OcxTextContent, OcxThinkingContent, OcxToolCall, OcxUsage } from "../types";
 import { isAllowedToolChoice, modelInList, namespacedToolName, resolveToolChoiceWireName, toolAllowedByChoice } from "../types";
 import { mapReasoningEffort } from "../reasoning-effort";
+import { redactSecretString } from "../lib/redact";
 import { contentPartsToText } from "./image";
 import { neutralizeIdentity } from "./identity";
 import { buildNonOpenAIToolCatalogNudgeForTools, shouldInjectNonOpenAIToolCatalogNudge } from "./tool-catalog-nudge";
@@ -13,6 +14,52 @@ export function stripBracketedModelSuffix(modelId: string): string {
   return modelId.replace(/\[[^\]]*\]\s*$/, "");
 }
 
+// 260715 (issue #126): surface upstream error detail through the web-search sidecar loop.
+// loop.ts only appends a suffix to "Provider error N" when the adapter exposes
+// formatErrorBody; without it, strict OpenAI-compatible backends (NVIDIA NIM pydantic
+// validation, "This model only supports single tool-calls at once!", etc.) were reduced
+// to a bare status code. JSON-only extraction: recognized string fields are returned,
+// HTML/non-JSON bodies yield "" so raw markup is never echoed to the client.
+export function formatOpenAIChatErrorBody(status: number, _headers: Headers, payloadText: string): string {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(payloadText);
+  } catch {
+    return "";
+  }
+  const detail = extractErrorDetail(parsed);
+  if (!detail) return "";
+  return redactSecretString(detail).slice(0, 400);
+}
+
+function extractErrorDetail(parsed: unknown): string | undefined {
+  if (typeof parsed === "string") return parsed.trim() || undefined;
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
+  const obj = parsed as Record<string, unknown>;
+  // OpenAI shape: { error: { message } } or { error: "..." }
+  const err = obj.error;
+  if (typeof err === "string" && err.trim()) return err.trim();
+  if (err !== null && typeof err === "object" && !Array.isArray(err)) {
+    const msg = (err as Record<string, unknown>).message;
+    if (typeof msg === "string" && msg.trim()) return msg.trim();
+  }
+  // FastAPI/pydantic shape (NVIDIA NIM): { detail: "..." } or { detail: [{ msg, loc }, ...] }
+  const det = obj.detail;
+  if (typeof det === "string" && det.trim()) return det.trim();
+  if (Array.isArray(det)) {
+    const msgs = det
+      .map(item => (item !== null && typeof item === "object" && typeof (item as Record<string, unknown>).msg === "string"
+        ? ((item as Record<string, unknown>).msg as string).trim()
+        : ""))
+      .filter(m => m.length > 0);
+    if (msgs.length > 0) return msgs.join("; ");
+  }
+  // Generic fallbacks: { message } / RFC7807 { title }
+  if (typeof obj.message === "string" && obj.message.trim()) return obj.message.trim();
+  if (typeof obj.title === "string" && obj.title.trim()) return obj.title.trim();
+  return undefined;
+}
+
 function messagesToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderConfig): unknown[] {
   const out: unknown[] = [];
   const { context, options } = parsed;
@@ -125,6 +172,88 @@ function safeToolName(name: string | undefined): string {
   return sanitized;
 }
 
+const ZEN_SCHEMA_MAP_KEYS = new Set(["properties", "$defs", "definitions"]);
+const ZEN_DROPPED_SCHEMA_KEYS = new Set(["encrypted"]);
+
+function sanitizeZenSchemaMap(value: unknown): unknown {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return sanitizeZenToolParameters(value);
+  const out: Record<string, unknown> = {};
+  for (const [name, child] of Object.entries(value as Record<string, unknown>)) {
+    out[name] = sanitizeZenToolParameters(child);
+  }
+  return out;
+}
+
+function sanitizeZenToolParameters(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sanitizeZenToolParameters);
+  if (!value || typeof value !== "object") return value;
+  const input = value as Record<string, unknown>;
+  const out: Record<string, unknown> = {};
+  for (const [key, child] of Object.entries(input)) {
+    if (ZEN_DROPPED_SCHEMA_KEYS.has(key)) continue;
+    if (key === "required" && Array.isArray(child) && child.length === 0) continue;
+    if (key === "type" && Array.isArray(child)) {
+      const nonNull = child.filter(entry => entry !== "null");
+      if (child.includes("null")) out.nullable = true;
+      if (nonNull.length > 0) out.type = nonNull[0];
+      continue;
+    }
+    out[key] = ZEN_SCHEMA_MAP_KEYS.has(key) ? sanitizeZenSchemaMap(child) : sanitizeZenToolParameters(child);
+  }
+  return out;
+}
+
+function ensureZenRootObjectSchema(schema: unknown): Record<string, unknown> {
+  const obj = schema && typeof schema === "object" && !Array.isArray(schema)
+    ? schema as Record<string, unknown>
+    : {};
+  const compositionKeys = ["oneOf", "anyOf", "allOf"] as const;
+  const hasComposition = compositionKeys.some(key => Array.isArray(obj[key]));
+  const rootType = obj.type;
+  const rootObjectType = rootType === "object" || (Array.isArray(rootType) && rootType.includes("object"));
+  if (!hasComposition) {
+    const base = sanitizeZenToolParameters(obj) as Record<string, unknown>;
+    return rootObjectType && base.type === "object" ? base : { ...base, type: "object" };
+  }
+
+  const props: Record<string, unknown> = {};
+  const required = new Set<string>();
+  if (obj.properties && typeof obj.properties === "object") {
+    Object.assign(props, sanitizeZenSchemaMap(obj.properties) as Record<string, unknown>);
+  }
+  if (Array.isArray(obj.required)) {
+    for (const entry of obj.required) if (typeof entry === "string") required.add(entry);
+  }
+  for (const key of compositionKeys) {
+    const variants = obj[key];
+    if (!Array.isArray(variants)) continue;
+    const mergeRequired = key === "allOf";
+    for (const variant of variants) {
+      if (!variant || typeof variant !== "object" || Array.isArray(variant)) continue;
+      const rec = variant as Record<string, unknown>;
+      if (rec.properties && typeof rec.properties === "object") {
+        Object.assign(props, sanitizeZenSchemaMap(rec.properties) as Record<string, unknown>);
+      }
+      if (mergeRequired && Array.isArray(rec.required)) {
+        for (const entry of rec.required) if (typeof entry === "string") required.add(entry);
+      }
+    }
+  }
+
+  const merged = sanitizeZenToolParameters(obj) as Record<string, unknown>;
+  delete merged.oneOf;
+  delete merged.anyOf;
+  delete merged.allOf;
+  merged.type = "object";
+  if (Object.keys(props).length > 0) merged.properties = props;
+  if (required.size > 0) merged.required = [...required];
+  return merged;
+}
+
+function shouldSanitizeZenToolParameters(provider: OcxProviderConfig): boolean {
+  return provider.baseUrl.replace(/\/+$/, "") === "https://opencode.ai/zen/v1";
+}
+
 const XAI_SCHEMA_BASE_URLS = new Set(["api.x.ai", "cli-chat-proxy.grok.com"]);
 
 function isXaiSchemaTarget(provider: OcxProviderConfig): boolean {
@@ -193,6 +322,23 @@ function toolsToChatFormat(parsed: OcxParsedRequest, provider: OcxProviderConfig
   return formatted.length > 0 ? formatted : undefined;
 }
 
+function toolsToChatFormatForProvider(parsed: OcxParsedRequest, provider: OcxProviderConfig): unknown[] | undefined {
+  const base = toolsToChatFormat(parsed, provider);
+  if (!base || !shouldSanitizeZenToolParameters(provider)) return base;
+  return base.map(tool => {
+    if (!tool || typeof tool !== "object") return tool;
+    const functionDef = (tool as { function?: Record<string, unknown> }).function;
+    if (!functionDef || typeof functionDef !== "object") return tool;
+    return {
+      ...tool,
+      function: {
+        ...functionDef,
+        parameters: ensureZenRootObjectSchema(functionDef.parameters ?? {}),
+      },
+    };
+  });
+}
+
 function toolChoiceToChatFormat(tc: OcxParsedRequest["options"]["toolChoice"], tools: OcxParsedRequest["context"]["tools"]): unknown {
   if (!tc) return undefined;
   if (isAllowedToolChoice(tc)) return tc.mode === "required" ? "required" : "auto";
@@ -231,6 +377,8 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
   return {
     name: "openai-chat",
 
+    formatErrorBody: formatOpenAIChatErrorBody,
+
     buildRequest(parsed: OcxParsedRequest) {
       const hasCredential = typeof provider.apiKey === "string" && provider.apiKey.trim().length > 0;
       if ((provider.authMode === "key" || provider.authMode === "oauth") && !provider.keyOptional && !hasCredential) {
@@ -238,7 +386,7 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
       }
 
       const messages = messagesToChatFormat(parsed, provider);
-      const tools = toolsToChatFormat(parsed, provider);
+      const tools = toolsToChatFormatForProvider(parsed, provider);
       const toolChoice = toolChoiceToChatFormat(parsed.options.toolChoice, parsed.context.tools);
 
       const body: Record<string, unknown> = {
@@ -297,6 +445,10 @@ export function createOpenAIChatAdapter(provider: OcxProviderConfig): ProviderAd
 
       const url = `${provider.baseUrl}/chat/completions`;
       const headers: Record<string, string> = { "Content-Type": "application/json" };
+      // Precedence preserved from pre-#128 behavior: apiKey Authorization first, then
+      // provider.headers may override (user/registry-configured headers win). Registry
+      // staticHeaders (e.g. opencode-free x-opencode-client) flow in via derive.ts and
+      // never carry Authorization, so keyless providers are unaffected.
       if (hasCredential) headers["Authorization"] = `Bearer ${provider.apiKey}`;
       if (provider.headers) Object.assign(headers, provider.headers);
 

package/src/adapters/openai-responses.ts

@@ -136,9 +136,135 @@ function scrubOcxCompactionItems(body: unknown): unknown {
  * Extend this when another native slug rejects a hosted tool (e.g. `code_interpreter`).
  */
 const UNSUPPORTED_HOSTED_TOOLS: ReadonlyArray<{ match: (model: string) => boolean; tools: ReadonlySet<string> }> = [
-  { match: model => model.includes("codex-spark"), tools: new Set(["image_generation"]) },
+  { match: model => model.includes("codex-spark"), tools: new Set(["image_generation", "tool_search"]) },
 ];
 
+/**
+ * Strip unsupported `reasoning` sub-parameters for native slugs that reject them (e.g. Spark).
+ * codex-rs injects `reasoning.context` and `reasoning.summary` based on catalog flags; Spark's
+ * backend rejects both. The catalog fix prevents `use_responses_lite` from being set, but this
+ * is a defense-in-depth guard so stale on-disk catalogs don't break until the user runs `ocx sync`.
+ */
+function stripUnsupportedReasoningParams(body: unknown): unknown {
+  if (!isPlainObject(body)) return body;
+  const model = typeof body.model === "string" ? body.model : "";
+  if (!model.includes("codex-spark")) return body;
+  if (!isPlainObject(body.reasoning)) return body;
+  const reasoning = body.reasoning as Record<string, unknown>;
+  // Spark supports reasoning.effort but rejects context, summary, and generate_summary.
+  const { context: _ctx, summary: _sum, generate_summary: _gs, ...rest } = reasoning;
+  if (_ctx === undefined && _sum === undefined && _gs === undefined) return body;
+  return { ...body, reasoning: Object.keys(rest).length > 0 ? rest : undefined };
+}
+
+/**
+ * Comprehensive Spark compatibility layer. codex-rs emits five tool types (function,
+ * namespace, tool_search, web_search, custom) plus extensions (defer_loading,
+ * parallel_tool_calls, tool_search_call/output items). Spark's serving path only
+ * supports flat function tools and hosted web_search. This function:
+ * - Flattens namespace tools → promotes inner functions to top level
+ * - Drops unsupported tool types (tool_search, custom)
+ * - Strips defer_loading from function tools
+ * - Strips namespace from input items
+ * - Drops tool_search_call/tool_search_output input items
+ * - Sets parallel_tool_calls to false
+ */
+function stripSparkCompatibility(body: unknown): unknown {
+  if (!isPlainObject(body)) return body;
+  const model = typeof body.model === "string" ? body.model : "";
+  if (!model.includes("codex-spark")) return body;
+
+  let changed = false;
+
+  const SPARK_SAFE_TOOL_TYPES = new Set(["function", "web_search", "web_search_preview"]);
+
+  let tools = body.tools;
+  if (Array.isArray(tools)) {
+    const flattened: unknown[] = [];
+    for (const t of tools) {
+      if (isPlainObject(t) && t.type === "namespace") {
+        changed = true;
+        if (Array.isArray(t.tools)) {
+          for (const inner of t.tools) flattened.push(inner);
+        }
+      } else if (isPlainObject(t) && typeof t.type === "string" && !SPARK_SAFE_TOOL_TYPES.has(t.type)) {
+        changed = true;
+      } else {
+        flattened.push(t);
+      }
+    }
+    // Strip defer_loading from promoted/remaining function tools.
+    tools = flattened.map(t => {
+      if (isPlainObject(t) && t.type === "function" && "defer_loading" in t) {
+        const { defer_loading: _, ...rest } = t;
+        changed = true;
+        return rest;
+      }
+      return t;
+    });
+  }
+
+  // Clean input items: strip namespace, drop tool_search_call/tool_search_output.
+  const SPARK_UNSUPPORTED_INPUT_TYPES = new Set([
+    "tool_search_call", "tool_search_output",
+    "custom_tool_call", "custom_tool_call_output",
+  ]);
+  let input = body.input;
+  if (Array.isArray(input)) {
+    const cleaned: unknown[] = [];
+    for (const item of input) {
+      if (isPlainObject(item) && typeof item.type === "string" && SPARK_UNSUPPORTED_INPUT_TYPES.has(item.type)) {
+        changed = true;
+        continue;
+      }
+      // Process additional_tools items: filter their inner tools array the same way.
+      if (isPlainObject(item) && item.type === "additional_tools" && Array.isArray(item.tools)) {
+        const innerTools = item.tools as unknown[];
+        const filteredInner: unknown[] = [];
+        for (const t of innerTools) {
+          if (isPlainObject(t) && t.type === "namespace") {
+            changed = true;
+            if (Array.isArray(t.tools)) {
+              for (const fn of t.tools) filteredInner.push(fn);
+            }
+          } else if (isPlainObject(t) && typeof t.type === "string" && !SPARK_SAFE_TOOL_TYPES.has(t.type)) {
+            changed = true; // drop custom, tool_search, etc.
+          } else {
+            filteredInner.push(t);
+          }
+        }
+        // Strip defer_loading from remaining function tools.
+        const cleanedInner = filteredInner.map(t => {
+          if (isPlainObject(t) && t.type === "function" && "defer_loading" in t) {
+            const { defer_loading: _, ...rest } = t;
+            changed = true;
+            return rest;
+          }
+          return t;
+        });
+        cleaned.push({ ...item, tools: cleanedInner });
+        continue;
+      }
+      if (isPlainObject(item) && "namespace" in item) {
+        const { namespace: _, ...rest } = item;
+        changed = true;
+        cleaned.push(rest);
+      } else {
+        cleaned.push(item);
+      }
+    }
+    if (changed) input = cleaned;
+  }
+
+  // Force parallel_tool_calls off for Spark.
+  const extraOverrides: Record<string, unknown> = {};
+  if (body.parallel_tool_calls === true) { extraOverrides.parallel_tool_calls = false; changed = true; }
+
+  return changed
+    ? { ...body, ...(tools !== body.tools ? { tools } : {}), ...(input !== body.input ? { input } : {}), ...extraOverrides }
+    : body;
+}
+
 function isPlainObject(v: unknown): v is Record<string, unknown> {
   return !!v && typeof v === "object" && !Array.isArray(v);
 }
@@ -331,7 +457,7 @@ export function createResponsesPassthroughAdapter(provider: OcxProviderConfig):
         url,
         method: "POST",
         headers,
-        body: JSON.stringify(stripItemIdsWhenUnstored(stripInvalidItemIds(stripUnsupportedHostedTools(sanitizeReasoningInputContent(scrubOcxCompactionItems(outBody)))))),
+        body: JSON.stringify(stripSparkCompatibility(stripUnsupportedReasoningParams(stripItemIdsWhenUnstored(stripInvalidItemIds(stripUnsupportedHostedTools(sanitizeReasoningInputContent(scrubOcxCompactionItems(outBody)))))))),
       };
     },
 

package/src/cli/claude.ts

@@ -54,6 +54,9 @@ export function buildClaudeEnv(config: OcxConfig, port: number, base: ClaudeLaun
   if ((config.apiKeys?.length ?? 0) > 0) {
     setDefault("ANTHROPIC_AUTH_TOKEN", config.apiKeys![0].key);
   }
+  if (!env.ANTHROPIC_AUTH_TOKEN && config.claudeCode?.authMode === "proxy") {
+    env.ANTHROPIC_AUTH_TOKEN = "opencodex-proxy";
+  }
   // NOTE: do NOT set _CLAUDE_CODE_ASSUME_FIRST_PARTY_BASE_URL here. While it enables
   // Design/Remote Control, it DISABLES gateway model discovery (Claude Code's eligibility
   // check returns false when isFirstPartyBaseUrl() is true). Model routing through the

package/src/codex/catalog.ts

@@ -851,6 +851,17 @@ function deriveEntry(template: RawEntry | null, slug: string, desc: string, prio
       applyNativeOpenAiContextOverride(e);
       if (isGpt56NativeSlug(slug)) ensureGpt56ReasoningLevels(e);
       else ensureUltraReasoningLevel(e);
+     // Non-5.6 natives (5.5, 5.4, 5.4-mini, spark) do not support responses-lite;
+     // the template may carry the flag from a 5.6 entry — strip it so codex-rs does
+     // not inject reasoning.context: "all_turns" for models that reject it.
+     if (!isGpt56NativeSlug(slug)) {
+        // Spark NEEDS use_responses_lite: true — it controls the tool delivery format
+        // (AdditionalTools in input vs top-level tools). The reasoning params that
+        // use_responses_lite triggers (context: "all_turns", summary) are stripped
+        // separately in the passthrough adapter (stripUnsupportedReasoningParams).
+        if (!slug.includes("codex-spark")) delete e.use_responses_lite;
+        delete e.supports_websockets;
+      }
     }
     return ensureStrictCatalogFields(normalizeServiceTiers(e));
   }
@@ -1179,7 +1190,8 @@ async function fetchProviderModels(name: string, prov: OcxProviderConfig, ttlMs:
       provider: name,
       owned_by: m.owned_by,
       ...catalogHintsFromModelsApiItem(name, m),
-    }, contextCap));
+    }, contextCap))
+      .filter(m => shouldExposeProviderModel(name, m.id));
     const liveIds = new Set(live.map(m => m.id));
     // Dated-release aliases (Anthropic pattern): older models may appear in the live catalog
     // ONLY under their dated id (claude-haiku-4-5-20251001) while the config names the
@@ -1193,6 +1205,8 @@ async function fetchProviderModels(name: string, prov: OcxProviderConfig, ttlMs:
       if (dated) {
         // Reapply config hints so alias-keyed overrides (modelContextWindows etc.) win.
         live.push(applyProviderConfigHints(name, prov, { ...dated, id: m.id }, contextCap));
+      } else if (shouldRetainConfiguredProviderModel(name, m.id)) {
+        live.push(m);
       } else {
         droppedConfiguredIds.push(m.id);
       }
@@ -1213,6 +1227,16 @@ async function fetchProviderModels(name: string, prov: OcxProviderConfig, ttlMs:
   }
 }
 
+function shouldExposeProviderModel(providerName: string, modelId: string): boolean {
+  if (providerName === "opencode-free") return modelId === "big-pickle" || modelId.endsWith("-free");
+  return true;
+}
+
+function shouldRetainConfiguredProviderModel(providerName: string, modelId: string): boolean {
+  if (providerName === "opencode-free") return modelId === "big-pickle" || modelId.endsWith("-free");
+  return false;
+}
+
 /**
  * Narrow a raw routed-model list to what Codex's catalog / clients should see: drop the
  * `disabledModels` blocklist AND, for any provider with a non-empty `selectedModels` allowlist, keep

package/src/oauth/callback-server.ts

@@ -235,12 +235,16 @@ export abstract class OAuthCallbackFlow {
         while (true) {
           const result = await Promise.race([
             callbackPromise,
-            requestManualInput()
+            requestManualInput(expectedState)
               .then((input): CallbackResult | null => {
                 const parsed = parseCallbackInput(input);
                 if (!parsed.code) return null;
-                if (expectedState && parsed.state !== expectedState) return null;
-                return { code: parsed.code, state: parsed.state ?? "" };
+                // Kind-aware state enforcement: url/query-shaped input is an authorization
+                // RESPONSE and must carry a matching state — missing state is rejected, not
+                // downgraded to raw. Only a syntactically raw code (same PKCE session) is
+                // exempt, so the CLI/GUI paste fallback still works.
+                if (parsed.kind !== "raw" && expectedState && parsed.state !== expectedState) return null;
+                return { code: parsed.code, state: parsed.state ?? expectedState };
               })
               .catch((): CallbackResult | null => null),
           ]);
@@ -255,14 +259,19 @@ export abstract class OAuthCallbackFlow {
   }
 }
 
-/** Parse a redirect URL or code string to extract code and state. */
-export function parseCallbackInput(input: string): { code?: string; state?: string } {
+/**
+ * Parse a redirect URL or code string to extract code and state.
+ * `kind` records the syntactic shape so callers can enforce state on authorization
+ * responses (url/query) while exempting raw in-session codes.
+ */
+export function parseCallbackInput(input: string): { kind: "url" | "query" | "raw"; code?: string; state?: string } {
   const value = input.trim();
-  if (!value) return {};
+  if (!value) return { kind: "raw" };
 
   try {
     const url = new URL(value);
     return {
+      kind: "url",
       code: url.searchParams.get("code") ?? undefined,
       state: url.searchParams.get("state") ?? undefined,
     };
@@ -273,6 +282,7 @@ export function parseCallbackInput(input: string): { code?: string; state?: stri
   if (value.includes("code=")) {
     const params = new URLSearchParams(value.replace(/^[?#]/, ""));
     return {
+      kind: "query",
       code: params.get("code") ?? undefined,
       state: params.get("state") ?? undefined,
     };
@@ -280,5 +290,5 @@ export function parseCallbackInput(input: string): { code?: string; state?: stri
 
   // Assume raw code, possibly with state after #
   const [code, state] = value.split("#", 2);
-  return { code, state };
+  return { kind: "raw", code, state };
 }

package/src/oauth/index.ts

@@ -1,4 +1,5 @@
 import type { OAuthController, OAuthCredentials } from "./types";
+import { parseCallbackInput } from "./callback-server";
 import type { OcxConfig, OcxProviderConfig, RefreshPolicy } from "../types";
 import { loadConfig, resolveEnvValue, saveConfig } from "../config";
 import { maskEmail } from "../lib/privacy";
@@ -362,10 +363,95 @@ export async function runLogin(provider: string, ctrl: OAuthController, opts?: L
  * GUI async login: start the flow, return the auth URL EARLY (the flow keeps running in the
  * background until the callback server captures the redirect), with a concurrency guard and an
  * error surfaced via getLoginStatus().
+ *
+ * Manual fallback: when the browser cannot reach the loopback callback (remote GUI, SSH, blocked
+ * localhost), the GUI can POST the final redirect URL or authorization code via
+ * submitManualLoginCode(), which feeds OAuthController.onManualCodeInput.
  */
 const loginState = new Map<string, { error?: string; done: boolean }>();
 const loginAbort = new Map<string, AbortController>();
 
+/** Pending paste for a login in progress: either a waiter or a stashed early submission. */
+interface ManualCodeSlot {
+  pendingInput?: string;
+  resolve?: (value: string) => void;
+  /** Registered by the callback flow so submits can validate state synchronously. */
+  expectedState?: string;
+}
+const loginManual = new Map<string, ManualCodeSlot>();
+
+function clearManualCodeSlot(provider: string): void {
+  loginManual.delete(provider);
+}
+
+function ensureManualCodeSlot(provider: string): ManualCodeSlot {
+  let slot = loginManual.get(provider);
+  if (!slot) {
+    slot = {};
+    loginManual.set(provider, slot);
+  }
+  return slot;
+}
+
+/** Wait for a GUI/CLI paste of the OAuth redirect URL or code (or return a stashed early submit). */
+function waitForManualLoginCode(provider: string, signal: AbortSignal, expectedState?: string): Promise<string> {
+  if (signal.aborted) {
+    return Promise.reject(new Error(`OAuth callback cancelled: ${signal.reason}`));
+  }
+  const slot = ensureManualCodeSlot(provider);
+  if (expectedState !== undefined) slot.expectedState = expectedState;
+  if (slot.pendingInput !== undefined) {
+    const value = slot.pendingInput;
+    slot.pendingInput = undefined;
+    return Promise.resolve(value);
+  }
+  return new Promise<string>((resolve, reject) => {
+    const onAbort = () => {
+      if (slot.resolve === resolve) slot.resolve = undefined;
+      reject(new Error(`OAuth callback cancelled: ${signal.reason}`));
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    slot.resolve = (value: string) => {
+      signal.removeEventListener("abort", onAbort);
+      if (slot.resolve === resolve) slot.resolve = undefined;
+      resolve(value);
+    };
+  });
+}
+
+/**
+ * Feed a pasted redirect URL or authorization code into an in-progress GUI login.
+ * Returns ok:false when no login is waiting (or input is empty). Invalid pastes are accepted
+ * here and re-prompted by the OAuth callback loop if they cannot be parsed / fail state checks.
+ */
+export function submitManualLoginCode(provider: string, input: string): { ok: true } | { ok: false; error: string } {
+  const trimmed = input.trim();
+  if (!trimmed) return { ok: false, error: "empty code" };
+  const st = loginState.get(provider);
+  if (!st || st.done) return { ok: false, error: "no login in progress" };
+  const slot = ensureManualCodeSlot(provider);
+  // Synchronous validation (validated request/ack): reject un-parseable input and
+  // authorization responses (url/query kind) whose state is missing or mismatched
+  // once the flow has registered its expected state. Raw codes stay in-session-PKCE
+  // protected. Early posts (flow not yet waiting, no expectedState) are stashed and
+  // re-validated by the callback loop.
+  const parsed = parseCallbackInput(trimmed);
+  if (!parsed.code) return { ok: false, error: "no authorization code found in input" };
+  if (parsed.kind !== "raw" && slot.expectedState !== undefined) {
+    if (parsed.state === undefined) return { ok: false, error: "redirect URL is missing the state parameter" };
+    if (parsed.state !== slot.expectedState) return { ok: false, error: "state mismatch — paste the redirect URL from THIS login attempt" };
+  }
+  if (slot.resolve) {
+    const resolve = slot.resolve;
+    slot.resolve = undefined;
+    resolve(trimmed);
+  } else {
+    // Race: GUI may POST before the flow reaches onManualCodeInput — stash for the waiter.
+    slot.pendingInput = trimmed;
+  }
+  return { ok: true };
+}
+
 export interface OAuthAccountSummary { id: string; email?: string; active: boolean; needsReauth?: boolean; expiresAt?: number }
 
 export function getLoginStatus(provider: string): { loggedIn: boolean; email?: string; source?: OAuthCredentials["source"]; error?: string; done: boolean; activeAccountId?: string; accounts?: OAuthAccountSummary[] } {
@@ -400,6 +486,7 @@ export function oauthLoginSummary(): Array<{ provider: string; loggedIn: boolean
 export function clearLoginState(provider: string): void {
   loginAbort.get(provider)?.abort("cleared");
   loginAbort.delete(provider);
+  clearManualCodeSlot(provider);
   loginState.delete(provider);
 }
 
@@ -409,6 +496,7 @@ export function cancelLoginFlow(provider: string): boolean {
   if (!ctrl && (!existing || existing.done)) return false;
   ctrl?.abort("cancelled");
   loginAbort.delete(provider);
+  clearManualCodeSlot(provider);
   loginState.set(provider, { done: true, error: "Login cancelled" });
   return true;
 }
@@ -420,6 +508,7 @@ export async function startLoginFlow(provider: string, opts?: LoginOpts): Promis
   if (existing && !existing.done) {
     throw new Error(`A login for ${provider} is already in progress`);
   }
+  clearManualCodeSlot(provider);
   loginState.set(provider, { done: false });
   const abort = new AbortController();
   loginAbort.set(provider, abort);
@@ -431,12 +520,15 @@ export async function startLoginFlow(provider: string, opts?: LoginOpts): Promis
         resolve({ url, instructions });
       },
       onProgress: () => {},
+      // GUI fallback when the browser cannot hit the loopback callback server.
+      onManualCodeInput: (expectedState?: string) => waitForManualLoginCode(provider, abort.signal, expectedState),
       signal: abort.signal,
     };
     // Background: runLogin persists the credential + upserts the provider entry to disk config.
     runLogin(provider, ctrl, opts)
       .then(() => {
         loginAbort.delete(provider);
+        clearManualCodeSlot(provider);
         loginState.set(provider, { done: true });
         // Local-token import (grok-cli / Claude Code keychain) completes WITHOUT firing onAuth —
         // resolve so the GUI call returns instead of hanging.
@@ -444,6 +536,7 @@ export async function startLoginFlow(provider: string, opts?: LoginOpts): Promis
       })
       .catch((e: unknown) => {
         loginAbort.delete(provider);
+        clearManualCodeSlot(provider);
         const msg = e instanceof Error ? e.message : String(e);
         loginState.set(provider, { done: true, error: msg });
         if (!urlResolved) reject(e);

package/src/oauth/types.ts

@@ -31,7 +31,7 @@ export interface ProviderAccountSet {
 export interface OAuthController {
   onAuth?(info: { url: string; instructions?: string }): void;
   onProgress?(message: string): void;
-  onManualCodeInput?(): Promise<string>;
+  onManualCodeInput?(expectedState?: string): Promise<string>;
   signal?: AbortSignal;
 }
 

package/src/providers/derive.ts

@@ -48,6 +48,7 @@ export interface DerivedProviderPreset {
   oauthProvider?: string;
   dashboardUrl?: string;
   note?: string;
+  keyOptional?: boolean;
 }
 
 export function listRegistryEntries(): readonly ProviderRegistryEntry[] {
@@ -69,6 +70,7 @@ export function providerConfigSeed(entry: ProviderRegistryEntry): OcxProviderCon
     authMode: entry.authKind === "local" ? undefined : entry.authKind,
     ...(entry.keyOptional !== undefined ? { keyOptional: entry.keyOptional } : {}),
     ...(entry.modelSuffixBracketStrip !== undefined ? { modelSuffixBracketStrip: entry.modelSuffixBracketStrip } : {}),
+    ...(entry.staticHeaders ? { headers: { ...entry.staticHeaders } } : {}),
     ...(entry.defaultModel ? { defaultModel: entry.defaultModel } : {}),
     ...(entry.models ? { models: [...entry.models] } : {}),
     ...(entry.liveModels !== undefined ? { liveModels: entry.liveModels } : {}),
@@ -193,6 +195,7 @@ export function enrichProviderFromRegistry(name: string, prov: OcxProviderConfig
   if (prov.escapeBuiltinToolNames === undefined && seed.escapeBuiltinToolNames !== undefined) prov.escapeBuiltinToolNames = seed.escapeBuiltinToolNames;
   if (prov.keyOptional === undefined && seed.keyOptional !== undefined) prov.keyOptional = seed.keyOptional;
   if (prov.modelSuffixBracketStrip === undefined && seed.modelSuffixBracketStrip !== undefined) prov.modelSuffixBracketStrip = seed.modelSuffixBracketStrip;
+  if (!prov.headers && seed.headers) prov.headers = { ...seed.headers };
 }
 
 export function deriveFeaturedProviderIds(): string[] {
@@ -227,6 +230,7 @@ function entryToPreset(entry: ProviderRegistryEntry): DerivedProviderPreset {
     ...(entry.authKind === "oauth" ? { oauthProvider: entry.oauthId ?? entry.id } : {}),
     ...(entry.dashboardUrl ? { dashboardUrl: entry.dashboardUrl } : {}),
     ...(entry.note ? { note: entry.note } : {}),
+    ...(entry.keyOptional ? { keyOptional: true } : {}),
   };
 }