mixdog 0.9.63 → 0.9.64

package/src/runtime/agent/orchestrator/providers/anthropic.mjs

@@ -51,283 +51,9 @@ import {
     toAnthropicToolChoice,
 } from './lib/anthropic-request-utils.mjs';
 
-const require = createRequire(import.meta.url);
-let _Anthropic = null;
-function loadAnthropic() {
-    if (!_Anthropic) {
-        const mod = require('@anthropic-ai/sdk');
-        _Anthropic = mod.default || mod.Anthropic || mod;
-    }
-    return _Anthropic;
-}
-
-// Abort-aware mid-stream backoff sleep → shared sleepWithAbort
-// (retry-classifier.mjs). abortMessage preserves the prior fallback text.
-function _midstreamSleepWithAbort(ms, signal) {
-    return sleepWithAbort(ms, signal, undefined, 'Anthropic mid-stream retry backoff aborted');
-}
-
-// 4-BP cache policy aligned with anthropic-oauth — system + tier3 +
-// messages-tail. Tool schemas sit before system and are covered by the system
-// breakpoint, so they do not spend a separate cache_control slot. 1h TTL
-// requires the extended-cache-ttl beta header, which we set on the client via
-// defaultHeaders below.
-
-// BP3 (tier3) rides its own `system` role block (the 3rd system block, tagged
-// cacheTier:'tier3'). buildSystemBlocks applies the tier3 1h cache_control to
-// that block; BP1/BP2 take the system TTL. Mirrors anthropic-oauth.mjs.
-
-function buildSystemBlocks(systemMsgs, systemTtl, tier3Ttl) {
-    // systemMsgs is an array of { content, cacheTier }. Each non-empty element
-    // becomes its own content block: cacheTier:'tier3' (BP3 sessionMarker) gets
-    // tier3Ttl, every other block (BP1/BP2) gets systemTtl. A null TTL leaves
-    // the corresponding block uncached.
-    const items = Array.isArray(systemMsgs)
-        ? systemMsgs
-            .map(m => ({
-                text: typeof m?.content === 'string' ? m.content.trim() : '',
-                tier: m?.cacheTier === 'tier3' ? 'tier3' : 'system',
-            }))
-            .filter(it => it.text)
-        : [];
-    // Anthropic caps cache_control breakpoints at 4 per request; defensively
-    // cap it here too so an unexpectedly large systemMsgs array can never
-    // mark more than 4 blocks (extras keep their text, just lose the
-    // cache_control breakpoint, not the block itself). Mirrors
-    // anthropic-oauth.mjs.
-    const MAX_SYSTEM_BREAKPOINTS = 4;
-    let bpCount = 0;
-    return items.map(it => {
-        const block = { type: 'text', text: it.text };
-        const ttl = it.tier === 'tier3' ? tier3Ttl : systemTtl;
-        if (ttl && bpCount < MAX_SYSTEM_BREAKPOINTS) {
-            block.cache_control = ttl;
-            bpCount++;
-        }
-        return block;
-    });
-}
-
-const MODELS = [
-    { id: 'claude-opus-4-8', name: 'Claude Opus 4.8', provider: 'anthropic', family: 'opus', contextWindow: 1000000 },
-    { id: 'claude-opus-4-7', name: 'Claude Opus 4.7', provider: 'anthropic', family: 'opus', contextWindow: 1000000 },
-    { id: 'claude-opus-4-6', name: 'Claude Opus 4.6', provider: 'anthropic', family: 'opus', contextWindow: 1000000 },
-    { id: 'claude-sonnet-4-6', name: 'Claude Sonnet 4.6', provider: 'anthropic', family: 'sonnet', contextWindow: 1000000 },
-    { id: 'claude-haiku-4-5-20251001', name: 'Claude Haiku 4.5', provider: 'anthropic', family: 'haiku', contextWindow: 200000 },
-];
-const ANTHROPIC_VERSION = '2023-06-01';
-
-function _prettyName(id, family) {
-    const v = String(id || '').match(/^claude-[a-z]+-(\d+)(?:-(\d+))?/i);
-    const base = family ? family[0].toUpperCase() + family.slice(1) : 'Claude';
-    return v ? `${base} ${v[1]}${v[2] ? `.${v[2]}` : ''}` : base;
-}
-
-function _defaultContextForModel(id, family) {
-    const text = String(id || '');
-    const version = text.match(/^claude-[a-z]+-(\d+)(?:-(\d+))?/i);
-    if (Number(version?.[1] || 0) >= 5) return 1000000;
-    if (/^claude-(opus|sonnet)-4-(6|7|8)(?:$|-)/i.test(text)) return 1000000;
-    if (family && family !== 'other') return 200000;
-    return 200000;
-}
-
-function _capabilitySupported(capability) {
-    return capability === true || capability?.supported === true;
-}
-
-function _normalizeAnthropicModel(raw, provider = 'anthropic') {
-    const id = raw?.id || raw?.name || raw?.model;
-    if (!id) return null;
-    const familyMatch = String(id).match(/^claude-([a-z]+)/i);
-    const family = familyMatch ? familyMatch[1].toLowerCase() : 'other';
-    const dated = /-\d{8}$/.test(String(id));
-    const versioned = !dated && /^claude-[a-z]+-\d+(?:-\d+)?$/i.test(String(id));
-    const effortValues = effortValuesForModel(raw?.capabilities, id);
-    return {
-        id,
-        display: raw?.display_name || raw?.displayName || raw?.display || _prettyName(id, family),
-        family,
-        provider,
-        contextWindow: raw?.context_window || raw?.max_context_window || raw?.max_input_tokens || raw?.input_token_limit || raw?.inputTokenLimit || _defaultContextForModel(id, family),
-        outputTokens: raw?.max_tokens || raw?.max_output_tokens || raw?.output_token_limit || raw?.outputTokenLimit || null,
-        tier: dated ? 'dated' : versioned ? 'version' : 'family',
-        latest: false,
-        supportsReasoning: effortValues.length > 0 || _capabilitySupported(raw?.capabilities?.thinking),
-        reasoningOptions: effortValues.length ? [{ type: 'effort', values: effortValues }] : [],
-    };
-}
-// Family-based heuristic so new model ids (including custom user-configured
-// ones) resolve a sensible max_tokens without requiring a code change.
-// The API-key provider has no catalog cache of its own — it reads the same
-// anthropic-oauth-models.json disk cache (read-only) that the OAuth provider
-// maintains. Both providers hit the same Anthropic /v1/models catalog, so a
-// per-model outputTokens entry is valid regardless of which auth path wrote
-// it. If this provider is ever run standalone without the OAuth provider
-// ever having populated the cache, loadSync() simply returns null and we
-// fall through to the shared static heuristic in anthropic-max-tokens.mjs.
-const ANTHROPIC_OAUTH_MODEL_CACHE_TTL_MS = 24 * 60 * 60_000;
-const _sharedOAuthModelCache = makeModelCache({
-    fileName: 'anthropic-oauth-models.json',
-    ttlMs: ANTHROPIC_OAUTH_MODEL_CACHE_TTL_MS,
-    version: 1,
-});
-
-// In-memory mirror populated by this provider's own listModels() fetch.
-// API-key-only installs never have the OAuth provider write the shared disk
-// cache, so without this mirror catalog outputTokens would stay invisible to
-// resolveMaxTokens until an OAuth session runs. listModels() results flow in
-// here (memory only — the disk cache stays OAuth-owned/read-only for us).
-let _apiKeyCatalogMirror = null;
-
-function _catalogOutputTokensFromSharedCache(model) {
-    if (!model) return null;
-    try {
-        const models = Array.isArray(_apiKeyCatalogMirror)
-            ? _apiKeyCatalogMirror
-            : _sharedOAuthModelCache.loadSync();
-        if (!Array.isArray(models)) return null;
-        const entry = models.find(m => m?.id === model);
-        const out = Number(entry?.outputTokens);
-        return Number.isFinite(out) && out > 0 ? out : null;
-    } catch {
-        return null;
-    }
-}
-
-function resolveMaxTokens(model) {
-    return resolveAnthropicMaxTokens(model, { catalogLookup: _catalogOutputTokensFromSharedCache });
-}
-
-// Test-only escape hatch for scripts/anthropic-maxtokens-test.mjs.
-export const _test = {
-    resolveMaxTokens,
-    deferredAnthropicTools,
-    requestAnthropicTools,
-    sanitizeInputSchema: (schema, toolName) => sanitizeAnthropicInputSchema(schema, toolName, 'anthropic'),
-};
-
-// Anthropic forbids oneOf / allOf / anyOf at the TOP level of input_schema.
-// Mirror the same sanitizer as anthropic-oauth.mjs so both providers are safe.
-// Map the orchestrator-level opts.toolChoice into Anthropic's tool_choice.
-// Only 'none' is activated: it lets the hard-cap final turn keep the tool
-// DEFINITIONS in-request (so the tools->system->messages prefix — and its
-// prompt-cache prefix — stay byte-identical to prior turns) while forbidding
-// tool USE, so the model can only emit text. Forced values
-// ('required'->{type:'any'}, {name}->{type:'tool'}) are deliberately NOT
-// mapped: Anthropic returns a 400 for any forced tool_choice while
-// extended/adaptive thinking is enabled, and the only caller that sets
-// opts.toolChoice='required' (the forced-first-tool turn) runs with
-// effort/thinking active on reasoning models — activating it would convert a
-// previously-harmless no-op into a hard 400 on exactly that turn. Attached
-// only when the request actually carries tools (see _doSend). Mirrors
-// anthropic-oauth.mjs.
-function deferredAnthropicTools(activeTools, messages, opts) {
-    return sharedDeferredAnthropicTools(activeTools, messages, opts, 'anthropic');
-}
-function requestAnthropicTools(tools, messages, opts) {
-    return sharedRequestAnthropicTools(tools, messages, opts, 'anthropic');
-}
-function toAnthropicMessages(messages) {
-    // Marker-free lowering. cache_control is applied AFTER sanitization by
-    // applyAnthropicCacheMarkers() so that block drops/inserts/reorders
-    // performed by sanitizeAnthropicContentPairs cannot move or delete a
-    // marked block (the root cause of the sporadic COLD-turn cache miss:
-    // pre-sanitize markers landed on blocks the sanitizer then rewrote, so
-    // the provider-visible breakpoint diverged from the cached one).
-    const result = [];
-    for (let idx = 0; idx < messages.length; idx++) {
-        const m = messages[idx];
-        if (m.role === 'system') continue;
-        if (m.role === 'assistant' && (m.toolCalls?.length || m.assistantBlocks?.length || m.thinkingBlocks?.length)) {
-            let content;
-            if (m.assistantBlocks?.length) {
-                content = m.assistantBlocks.slice();
-            } else {
-                content = [];
-                // Adaptive-thinking round-trip: prior-turn thinking blocks are
-                // REQUIRED back, unmodified (signature intact; empty thinking
-                // field allowed), and MUST precede tool_use blocks.
-                if (Array.isArray(m.thinkingBlocks)) {
-                    for (const tb of m.thinkingBlocks) {
-                        if (tb && typeof tb === 'object') content.push(tb);
-                    }
-                }
-                if (m.content) content.push({ type: 'text', text: m.content });
-                for (const tc of m.toolCalls || []) {
-                    content.push({
-                        type: 'tool_use',
-                        id: tc.id,
-                        name: tc.name,
-                        input: tc.arguments,
-                    });
-                }
-            }
-            result.push({ role: 'assistant', content });
-            continue;
-        }
-        if (m.role === 'tool') {
-            const last = result[result.length - 1];
-            const native = m.nativeToolSearch;
-            const nativeProvider = String(native?.provider || '').toLowerCase();
-            const anthropicNative = new Set(['anthropic', 'anthropic-oauth']);
-            const references = (!nativeProvider || anthropicNative.has(nativeProvider))
-                && Array.isArray(native?.toolReferences)
-                ? native.toolReferences.map((name) => String(name || '').trim()).filter(Boolean)
-                : [];
-            const block = {
-                type: 'tool_result',
-                tool_use_id: m.toolCallId || '',
-                content: references.length
-                    ? references.map((tool_name) => ({ type: 'tool_reference', tool_name }))
-                    : normalizeContentForAnthropic(m.content),
-                ...((m.toolKind === 'error' || m.isError === true) ? { is_error: true } : {}),
-            };
-            if (last?.role === 'user' && Array.isArray(last.content)) {
-                last.content.push(block);
-            }
-            else {
-                result.push({ role: 'user', content: [block] });
-            }
-            continue;
-        }
-        // First-party client parity: fold a user text turn that directly follows a
-        // tool_result turn into that tool_result's content (empty end_turn
-        // livelock prevention; see foldUserTextIntoToolResultTail).
-        //   EXCEPTION: steering-origin user messages (human/TUI interjections)
-        //   keep their own user turn so provenance survives — folding them would
-        //   disguise user input as tool output. Anthropic accepts a user text
-        //   message after a tool_result message, so the turn stays request-valid.
-        const isSteering = m.role === 'user' && m.meta?.source === 'steering';
-        if (m.role === 'user' && !isSteering
-            && foldUserTextIntoToolResultTail(result, normalizeContentForAnthropic(m.content))) {
-            continue;
-        }
-        result.push({ role: m.role, content: normalizeContentForAnthropic(m.content) });
-    }
-    return sanitizeAnthropicContentPairs(result);
-}
-
-// Test-only: expose the lowering so the steering-provenance test can assert
-// the API-key provider keeps steering-tagged user turns distinct (mirrors
-// anthropic-oauth._buildRequestBodyForCacheSmoke coverage).
-export function _toAnthropicMessagesForTest(messages) {
-    return toAnthropicMessages(messages);
-}
+import { loadAnthropic, _midstreamSleepWithAbort, buildSystemBlocks, MODELS, ANTHROPIC_VERSION, _normalizeAnthropicModel, _setApiKeyCatalogMirror, resolveMaxTokens, deferredAnthropicTools, requestAnthropicTools, toAnthropicMessages } from './anthropic-messages.mjs';
+export { _test, _toAnthropicMessagesForTest } from './anthropic-messages.mjs';
 
-// Applies cache_control markers to the FINAL, already-sanitized Anthropic
-// message array — by INVARIANT, never by pre-sanitize index. Because
-// sanitizeAnthropicContentPairs has already run (and must NOT run again
-// after this), the blocks we mark here are exactly the blocks the provider
-// sees, so the cache breakpoint is stable across turns.
-//   message-anchor: prefer a safe tool_result tail, then a previous real user
-//                   text turn if another slot remains. Synthetic
-//                   <system-reminder> messages and current pure-text prompts
-//                   are excluded so per-call volatileTail/current prompt
-//                   content never becomes a 1h prefix key.
-// messageTtl === null disables the tail. BP3 (tier3) now rides a system block,
-// so it is no longer marked here.
-// ANTHROPIC_MSG_SLOTS=0 is honoured upstream by passing messageTtl = null.
 export class AnthropicProvider {
     // Anthropic reports usage.input_tokens EXCLUDING cache_read/cache_creation
     // (those are separate fields), so the live context-window footprint must
@@ -918,7 +644,7 @@ export class AnthropicProvider {
             const enriched = sanitizeModelList(await enrichModels(normalized), { provider: this.name });
             // Feed the resolver-visible mirror so API-key-only installs get
             // catalog outputTokens without depending on the OAuth disk cache.
-            if (enriched.length) _apiKeyCatalogMirror = enriched.slice();
+            if (enriched.length) _setApiKeyCatalogMirror(enriched.slice());
             return enriched.length ? enriched : MODELS;
         }
         catch (err) {

package/src/runtime/agent/orchestrator/providers/codex-client-meta.mjs

@@ -19,7 +19,7 @@ import os from 'node:os';
 // The backend gates model exposure AND per-request model access on the client
 // version (gpt-5.6-* require >= 0.144.0 per codex models-manager/models.json,
 // verified 2026-07-09), so keep this at the current release when bumping.
-export const CODEX_CLIENT_VERSION_FLOOR = '0.144.1';
+const CODEX_CLIENT_VERSION_FLOOR = '0.144.1';
 const VERSION_TTL_MS = 24 * 60 * 60_000;
 let _cache = { value: null, fetchedAt: 0 };
 let _refreshInFlight = null;
@@ -47,7 +47,7 @@ async function _refresh() {
  * fresh, otherwise kicks a background refresh and returns the floor. The
  * handshake must never await a registry fetch.
  */
-export function codexClientVersionSync() {
+function codexClientVersionSync() {
     if (_cache.value && Date.now() - _cache.fetchedAt < VERSION_TTL_MS) return _cache.value;
     if (!_refreshInFlight) {
         _refreshInFlight = _refresh().finally(() => { _refreshInFlight = null; });

package/src/runtime/agent/orchestrator/providers/custom-tool-wire.mjs

@@ -21,7 +21,7 @@ export function customToolInputFromArguments(name, args) {
   try { return JSON.stringify(args ?? {}); } catch { return String(args ?? ''); }
 }
 
-export function customToolArgumentsFromInput(name, input) {
+function customToolArgumentsFromInput(name, input) {
   const text = typeof input === 'string'
     ? input
     : (() => {

package/src/runtime/agent/orchestrator/providers/gemini-cache.mjs

@@ -104,7 +104,7 @@ export function _geminiCachePrefixHash({ model, systemInstruction, geminiTools,
 // overhead. This matches the default five-minute cache's per-session 25%
 // reuse threshold, so a cross-session hit cannot expire while opening.
 export const GEMINI_GLOBAL_CACHE_MIN_LIVE_MS = 75 * 1000;
-export const GEMINI_GLOBAL_CACHE_MAX_ENTRIES = 128;
+const GEMINI_GLOBAL_CACHE_MAX_ENTRIES = 128;
 // Grace window before deleting a superseded cachedContents name (see the
 // cross-session race note at the delete call site in gemini.mjs). Long enough
 // that a concurrent session still mid-flight on the old name has time to finish.
@@ -147,7 +147,7 @@ export function _invalidateGeminiCacheName(cacheName) {
     return removed;
 }
 
-export function _pruneGeminiGlobalCaches(now = Date.now()) {
+function _pruneGeminiGlobalCaches(now = Date.now()) {
     for (const [key, entry] of geminiGlobalCaches) {
         if (!entry?.cacheName || Number(entry.cacheExpiresAt || 0) <= now) {
             geminiGlobalCaches.delete(key);

package/src/runtime/agent/orchestrator/providers/gemini-stream.mjs

@@ -37,14 +37,14 @@ export function geminiTimeoutError(label, timeoutMs) {
     return err;
 }
 
-export function geminiTruncatedStreamError(message) {
+function geminiTruncatedStreamError(message) {
     return Object.assign(
         new Error(message),
         { name: 'TruncatedStreamError', code: 'TRUNCATED_STREAM', truncatedStream: true },
     );
 }
 
-export function geminiStreamCorruptionError(message, cause = null) {
+function geminiStreamCorruptionError(message, cause = null) {
     return Object.assign(
         new Error(message, cause ? { cause } : undefined),
         {
@@ -87,7 +87,7 @@ function normalizeGeminiSdkStreamError(err, label) {
 // stall after visible output was silently retried. Visible-text stalls also
 // gain streamStalled + partialContent so the loop's partial-final path can
 // keep the streamed output instead of dropping the turn.
-export function stampGeminiStreamFailure(err, {
+function stampGeminiStreamFailure(err, {
     relayedText = '',
     textLeakGuard = null,
     sawFunctionCall = false,
@@ -123,7 +123,7 @@ export function stampGeminiStreamFailure(err, {
 
 // True when a streamed Gemini chunk carries a native functionCall part (as
 // opposed to a tool call leaked as plain text, tracked by textLeakGuard).
-export function geminiChunkHasFunctionCall(chunk) {
+function geminiChunkHasFunctionCall(chunk) {
     const parts = chunk?.candidates?.[0]?.content?.parts;
     if (!Array.isArray(parts)) return false;
     return parts.some((p) => p && p.functionCall);
@@ -181,7 +181,7 @@ export function aggregateGeminiStreamChunks(responses) {
     return aggregatedResponse;
 }
 
-export function assertGeminiStreamCompleted({ sawStreamChunk, finishReason, promptBlockReason, label }) {
+function assertGeminiStreamCompleted({ sawStreamChunk, finishReason, promptBlockReason, label }) {
     if (!sawStreamChunk) {
         throw geminiTruncatedStreamError(`${label} truncated: empty stream`);
     }
@@ -205,7 +205,7 @@ export function geminiChunkText(chunk) {
     return text;
 }
 
-export function relayGeminiStreamText(t, { onTextDelta, textLeakGuard }) {
+function relayGeminiStreamText(t, { onTextDelta, textLeakGuard }) {
     if (!t) return;
     if (textLeakGuard) textLeakGuard.feedText(t);
     else if (onTextDelta) { try { onTextDelta(t); } catch {} }

package/src/runtime/agent/orchestrator/providers/grok-oauth-login.mjs

@@ -0,0 +1,196 @@
+// Grok OAuth browser login + PKCE exchange, extracted from grok-oauth.mjs.
+/**
+ * Grok CLI OAuth provider ("Grok Build").
+ *
+ * Authenticates against xAI's shared OAuth client via PKCE (discovery at
+ * https://auth.x.ai/.well-known/openid-configuration). Credentials come from
+ * Mixdog's own token store (grok-oauth.json).
+ *
+ * Every OAuth inference request routes through cli-chat-proxy.grok.com/v1,
+ * matching Grok Build's session-auth contract. Model discovery still merges
+ * api.x.ai and proxy catalogs because each publishes a different subset.
+ *
+ * Inference is delegated to an inner OpenAICompatProvider('xai') — the only
+ * preset wired for the Responses API — with the proxy URL + CLI headers
+ * injected via config.extraHeaders, bearer swapped for the OAuth access token.
+ */
+import { createServer } from 'http';
+import { randomBytes, randomUUID, createHash } from 'crypto';
+import { readFileSync, existsSync, mkdirSync, statSync, unlinkSync } from 'fs';
+import { join, resolve } from 'path';
+import { getPluginData } from '../config.mjs';
+import { writeJsonAtomicSync, withFileLock } from '../../../shared/atomic-file.mjs';
+import { boundProviderAuthPath } from '../../../shared/provider-auth-binding.mjs';
+import { enrichModels, getModelMetadataSync } from './model-catalog.mjs';
+import { sanitizeModelList } from './model-list-sanitize.mjs';
+import { makeModelCache } from './model-cache.mjs';
+import { OpenAICompatProvider } from './openai-compat.mjs';
+import { createTimeoutSignal } from '../stall-policy.mjs';
+import { populateHttpStatusFromMessage } from './retry-classifier.mjs';
+import { getLlmDispatcher, preconnect } from '../../../shared/llm/http-agent.mjs';
+import { normalizeGrokToolSchemas } from './lib/grok-tool-schema.mjs';
+
+// --- Constants ---
+// xAI's shared OAuth client. The consent screen renders this as "Grok Build".
+import { CLIENT_ID, SCOPE, CALLBACK_HOST, CALLBACK_PORT, CALLBACK_PATH, REDIRECT_URI, TOKEN_TIMEOUT_MS, LOGIN_TIMEOUT_MS, fetchDiscovery, _normalizeExpiresAt, _identityFromAccessToken, saveTokens, _scrubTokens } from './grok-oauth-tokens.mjs';
+
+export function generatePKCE() {
+    const verifier = randomBytes(32).toString('base64url');
+    const challenge = createHash('sha256').update(verifier).digest('base64url');
+    return { verifier, challenge };
+}
+
+export async function exchangeAuthorizationCode({ discovery, pkce, code }) {
+    const cleanCode = String(code || '').trim();
+    if (!cleanCode) throw new Error('[grok-oauth] authorization code is required');
+    const tokenRes = await fetch(discovery.token_endpoint, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({
+            grant_type: 'authorization_code',
+            client_id: CLIENT_ID,
+            code: cleanCode,
+            code_verifier: pkce.verifier,
+            redirect_uri: REDIRECT_URI,
+            // xAI re-validates the PKCE challenge at token exchange
+            // (not just the verifier), so echo it back. Omitting
+            // these makes the exchange fail. Matches the Grok CLI.
+            code_challenge: pkce.challenge,
+            code_challenge_method: 'S256',
+        }),
+        // Secret-bearing (authorization code + verifier): refuse
+        // redirects so they can't be replayed to an untrusted host.
+        redirect: 'error',
+        signal: AbortSignal.timeout(TOKEN_TIMEOUT_MS),
+    });
+    if (!tokenRes.ok) {
+        const text = await tokenRes.text().catch(() => '');
+        throw new Error(`[grok-oauth] token exchange ${tokenRes.status}: ${_scrubTokens(text).slice(0, 500)}`);
+    }
+    const json = await tokenRes.json();
+    if (!json.access_token || !json.refresh_token) {
+        throw new Error('[grok-oauth] token exchange response missing access_token or refresh_token');
+    }
+    const identity = _identityFromAccessToken(json.access_token);
+    const tokens = {
+        access_token: json.access_token,
+        refresh_token: json.refresh_token,
+        expires_at: typeof json.expires_in === 'number'
+            ? Date.now() + json.expires_in * 1000
+            : _normalizeExpiresAt(json.expires_at),
+        token_endpoint: discovery.token_endpoint,
+        user_id: identity.user_id || '',
+        principal_type: json.principal_type || identity.principal_type || '',
+        principal_id: json.principal_id || identity.principal_id || '',
+    };
+    saveTokens(tokens);
+    return tokens;
+}
+
+function parseOAuthCodeInput(input) {
+    const value = String(input || '').trim();
+    if (!value) return { code: '', state: '' };
+    try {
+        const url = new URL(value);
+        const code = url.searchParams.get('code') || '';
+        const state = url.searchParams.get('state') || '';
+        if (code || state) return { code, state };
+    } catch { /* not a URL */ }
+    if (value.includes('#')) {
+        const [code, state] = value.split('#', 2);
+        return { code: String(code || '').trim(), state: String(state || '').trim() };
+    }
+    if (value.includes('code=')) {
+        const params = new URLSearchParams(value.startsWith('?') ? value.slice(1) : value);
+        return { code: params.get('code') || '', state: params.get('state') || '' };
+    }
+    return { code: value, state: '' };
+}
+
+export async function beginOAuthLogin() {
+    const discovery = await fetchDiscovery();
+    const pkce = generatePKCE();
+    const state = randomBytes(16).toString('hex');
+    const nonce = randomBytes(16).toString('hex');
+    const url = new URL(discovery.authorization_endpoint);
+    url.searchParams.set('response_type', 'code');
+    url.searchParams.set('client_id', CLIENT_ID);
+    url.searchParams.set('redirect_uri', REDIRECT_URI);
+    url.searchParams.set('scope', SCOPE);
+    url.searchParams.set('state', state);
+    url.searchParams.set('nonce', nonce);
+    url.searchParams.set('code_challenge', pkce.challenge);
+    url.searchParams.set('code_challenge_method', 'S256');
+    url.searchParams.set('plan', 'generic');
+    url.searchParams.set('referrer', 'mixdog');
+
+    let server = null;
+    let timeout = null;
+    let finish = null;
+    const waitForCallback = new Promise((resolve, reject) => {
+        let settled = false;
+        finish = (value, error = null) => {
+            if (settled) return;
+            settled = true;
+            if (timeout) clearTimeout(timeout);
+            try { server?.close(); } catch { /* already closed */ }
+            if (error) reject(error);
+            else resolve(value);
+        };
+        server = createServer(async (req, res) => {
+            const u = new URL(req.url || '/', `http://${CALLBACK_HOST}:${CALLBACK_PORT}`);
+            if (u.pathname !== CALLBACK_PATH) {
+                res.writeHead(404);
+                res.end();
+                return;
+            }
+            const code = u.searchParams.get('code');
+            if (!code || u.searchParams.get('state') !== state) {
+                res.writeHead(400);
+                res.end('Invalid');
+                finish(null);
+                return;
+            }
+            res.writeHead(200, { 'Content-Type': 'text/html' });
+            res.end('<html><body><h2>Grok login successful! You can close this tab.</h2></body></html>');
+            try {
+                const tokens = await exchangeAuthorizationCode({ discovery, pkce, code });
+                finish(tokens);
+            } catch (err) {
+                finish(null, err instanceof Error ? err : new Error(String(err)));
+            }
+        });
+        timeout = setTimeout(() => finish(null), LOGIN_TIMEOUT_MS);
+        server.listen(CALLBACK_PORT, CALLBACK_HOST, async () => {
+            process.stderr.write(`\n[grok-oauth] Open this URL to log in (consent shows as "Grok Build"):\n${url.toString()}\n\n`);
+            try {
+                const { openInBrowser } = await import('../../../shared/open-url.mjs');
+                openInBrowser(url.toString());
+            } catch (err) {
+                process.stderr.write(`[grok-oauth] browser open failed: ${String(err?.message || err).slice(0, 200)}\n`);
+            }
+        });
+        server.on('error', (err) => finish(null, new Error(`[grok-oauth] callback server failed on ${CALLBACK_HOST}:${CALLBACK_PORT}: ${err?.message || err}`)));
+    });
+
+    return {
+        provider: 'grok-oauth',
+        url: url.toString(),
+        waitForCallback,
+        completeCode: async (input) => {
+            const parsed = parseOAuthCodeInput(input);
+            if (parsed.state && parsed.state !== state) throw new Error('[grok-oauth] OAuth state mismatch');
+            const tokens = await exchangeAuthorizationCode({ discovery, pkce, code: parsed.code });
+            finish?.(tokens);
+            return tokens;
+        },
+        cancel: () => {
+            finish?.(null);
+        },
+    };
+}
+
+export async function loginOAuth() {
+    const login = await beginOAuthLogin();
+    return await login.waitForCallback;
+}