mixdog 0.7.6 → 0.7.7

package/setup/wizard.mjs

@@ -5,7 +5,6 @@
  * Callers must set process.env.CLAUDE_PLUGIN_DATA before importing this
  * module (install.mjs does that) so src/shared/config.mjs can resolve paths.
  */
-import { createInterface } from 'node:readline';
 import { spawnSync } from 'node:child_process';
 import { readFileSync, writeFileSync, existsSync, mkdirSync, renameSync } from 'node:fs';
 import { join, dirname, basename } from 'node:path';
@@ -18,6 +17,15 @@ import {
   mergeSearchConfig,
 } from './config-merge.mjs';
 import { DEFAULT_MODELS } from '../src/search/lib/config.mjs';
+import {
+  select,
+  multiselect,
+  confirm,
+  text,
+  password,
+  createProgressBar,
+  createSpinner,
+} from './tui.mjs';
 
 let _linuxSecretsCapable;
 const KEYTAR_SERVICE = 'mixdog';
@@ -134,61 +142,13 @@ function defaultIo() {
       say: (line) => { if (line) console.log(line); },
     };
   }
-  const rl = createInterface({ input: process.stdin, output: process.stdout });
-  const ask = (prompt) => new Promise((resolve) => {
-    rl.question(prompt, (answer) => resolve(answer));
-  });
-  const askSecret = (prompt) => readHiddenLine(prompt).finally(() => {
-    rl.resume();
-  });
   return {
     interactive: true,
-    ask,
-    askSecret,
     say: (line) => { if (line) console.log(line); },
-    close: () => rl.close(),
+    close: () => {},
   };
 }
 
-function readHiddenLine(prompt) {
-  return new Promise((resolve, reject) => {
-    const stdin = process.stdin;
-    if (!stdin.isTTY) {
-      resolve('');
-      return;
-    }
-    const wasRaw = stdin.isRaw;
-    stdin.setRawMode(true);
-    stdin.resume();
-    process.stdout.write(prompt);
-    let value = '';
-    const onData = (chunk) => {
-      const s = chunk.toString('utf8');
-      for (const ch of s) {
-        if (ch === '\n' || ch === '\r' || ch === '\u0004') {
-          stdin.removeListener('data', onData);
-          stdin.setRawMode(wasRaw);
-          process.stdout.write('\n');
-          resolve(value);
-          return;
-        }
-        if (ch === '\u0003') {
-          stdin.removeListener('data', onData);
-          stdin.setRawMode(wasRaw);
-          reject(new Error('cancelled'));
-          return;
-        }
-        if (ch === '\u007f' || ch === '\b') {
-          value = value.slice(0, -1);
-          continue;
-        }
-        value += ch;
-      }
-    };
-    stdin.on('data', onData);
-  });
-}
-
 async function loadConfigModules() {
   const { ensureDataSeeds } = await import('../src/shared/seed.mjs');
   const { readSection, updateSection } = await import('../src/shared/config.mjs');
@@ -259,9 +219,9 @@ export async function stepDiscordToken(io, { updateSection, readSection, secrets
   } else {
     hadStoredToken = hasStoredSecret(SECRET_ACCOUNTS.discordToken);
     const tokenPrompt = hadStoredToken
-      ? 'Discord bot token (stored, Enter=keep): '
-      : 'Discord bot token [hidden] (Enter=skip whole step): ';
-    token = (await io.askSecret(tokenPrompt)).trim();
+      ? 'Discord bot token (stored — leave empty to keep)'
+      : 'Discord bot token (leave empty to skip whole step)';
+    token = (await password(tokenPrompt)).trim();
     enteredToken = !isSkippableAnswer(token);
     if (!enteredToken && !hadStoredToken) {
       io.say('• Skipped Discord setup.');
@@ -273,15 +233,12 @@ export async function stepDiscordToken(io, { updateSection, readSection, secrets
   const curDiscord = channels.discord && typeof channels.discord === 'object' ? channels.discord : {};
   const curAppId = String(curDiscord.applicationId || '').trim();
   const appIdBase = 'Application ID';
-  const appIdPrompt = curAppId
-    ? `${appIdBase} (current: ${curAppId}, Enter=keep): `
-    : `${appIdBase}: `;
-  const appIdRaw = await io.ask(appIdPrompt);
+  const appIdRaw = await text(appIdBase, {
+    placeholder: curAppId ? `${curAppId} (Enter to keep)` : '',
+    initial: '',
+  });
   const appIdToSet = isSkippableAnswer(appIdRaw) ? '' : String(appIdRaw).trim();
-  // The main channel is conventionally named "main" with interactive mode;
-  // only the channel ID varies, so we ask just that. Extra channels and
-  // monitor mode are configured later in the UI.
-  const chIdRaw = await io.ask('Main channel ID (Enter=skip channel): ');
+  const chIdRaw = await text('Main channel ID', { placeholder: 'Enter to skip channel', initial: '' });
   const channelId = isSkippableAnswer(chIdRaw) ? '' : String(chIdRaw).trim();
   const channelName = 'main';
   const mode = 'interactive';
@@ -321,19 +278,35 @@ function formatVoiceProgress(p) {
   return `${phase} · received ${mb} MB`;
 }
 
-async function installVoiceRuntime(dataDir, io) {
+async function installVoiceRuntime(dataDir) {
   const {
     ensureWhisperRuntime,
     ensureWhisperModel,
     ensureFfmpegRuntime,
   } = await import('../src/channels/lib/voice-runtime-fetcher.mjs');
+  let spinner = createSpinner('Downloading voice runtime…');
+  let bar = null;
   const onProgress = (p) => {
     const line = formatVoiceProgress(p);
-    if (line) io.say(`  ${line}`);
+    if (!line) return;
+    const downloaded = Number(p?.downloaded) || 0;
+    const total = Number(p?.total) || 0;
+    if (total > 0) {
+      if (!bar) {
+        spinner.stop('', true);
+        spinner = null;
+        bar = createProgressBar('Voice download', { total });
+      }
+      bar.update(downloaded, total);
+    } else if (spinner) {
+      spinner.update(line);
+    }
   };
   await ensureWhisperRuntime(dataDir, onProgress);
   const model = await ensureWhisperModel(dataDir, onProgress);
   await ensureFfmpegRuntime(dataDir, onProgress);
+  if (bar) bar.done('complete');
+  else if (spinner) spinner.stop('complete', true);
   return model?.modelId || 'large-v3-turbo';
 }
 
@@ -342,20 +315,14 @@ async function stepVoiceTranscription(io, ctx, discordTokenSaved) {
   if (!discordTokenSaved) return;
   io.say('\n── Step 2a/9: Voice transcription (음성 전사) ──');
   io.say('Install local Speech-to-text (whisper.cpp) for Discord voice messages.');
-  const raw = await io.ask('Enable voice transcription? [y/N] (Enter=skip): ');
-  if (isSkippableAnswer(raw)) {
-    io.say('• Skipped voice transcription.');
-    return;
-  }
-  const a = String(raw).trim().toLowerCase();
-  if (a !== 'y' && a !== 'yes') {
+  const enable = await confirm('Enable voice transcription?', { initial: false });
+  if (!enable) {
     io.say('• Skipped voice transcription.');
     return;
   }
   const { updateSection, dataDir } = ctx;
   try {
-    io.say('• Downloading voice runtime (this may take a while)…');
-    const modelId = await installVoiceRuntime(dataDir, io);
+    const modelId = await installVoiceRuntime(dataDir);
     const voice = { language: 'auto', model: modelId };
     updateSection('channels', (current) => mergeConfig(current, { voice }, {}));
     io.say('• Voice transcription runtime installed and channels voice config saved.');
@@ -370,8 +337,14 @@ async function stepAddressForm(io, { updateSection, readSection }) {
   const memory = readSection('memory');
   const curTitle = memory?.user?.title || '';
   const curName = memory?.user?.name || '';
-  const titleRaw = await io.ask(`How should Mixdog address you? user.title [${curTitle}]: `);
-  const nameRaw = await io.ask(`Your display name? user.name [${curName}]: `);
+  const titleRaw = await text('How should Mixdog address you? user.title', {
+    placeholder: curTitle || 'Enter to skip',
+    initial: '',
+  });
+  const nameRaw = await text('Your display name? user.name', {
+    placeholder: curName || 'Enter to skip',
+    initial: '',
+  });
   const title = isSkippableAnswer(titleRaw) ? '' : String(titleRaw).trim();
   const name = isSkippableAnswer(nameRaw) ? '' : String(nameRaw).trim();
   if (!title && !name) {
@@ -389,13 +362,8 @@ async function stepAddressForm(io, { updateSection, readSection }) {
 export async function stepWebhookReceiver(io, { updateSection, readSection, secretsCapable = true }) {
   io.say('\n── Step 3/9: Inbound webhooks (ngrok receiver) ──');
   io.say('Global webhook tunnel for inbound HTTP (channels.webhook). Per-endpoint registration is configured later in the UI.');
-  const enableRaw = await io.ask('Enable inbound webhooks? [y/N]: ');
-  if (isSkippableAnswer(enableRaw)) {
-    io.say('• Skipped webhook setup.');
-    return;
-  }
-  const enable = String(enableRaw).trim().toLowerCase();
-  if (enable !== 'y' && enable !== 'yes') {
+  const enableWebhooks = await confirm('Enable inbound webhooks?', { initial: false });
+  if (!enableWebhooks) {
     io.say('• Skipped webhook setup.');
     return;
   }
@@ -405,19 +373,19 @@ export async function stepWebhookReceiver(io, { updateSection, readSection, secr
   const curDomain = String(curWebhook.domain || curWebhook.ngrokDomain || '').trim();
   const domainBase =
     'Domain (ngrok, e.g. your-name.ngrok-free.dev — get it at dashboard.ngrok.com/domains)';
-  const domainPrompt = curDomain
-    ? `${domainBase} (current: ${curDomain}, Enter=keep): `
-    : `${domainBase}: `;
-  const domainRaw = await io.ask(domainPrompt);
+  const domainRaw = await text(domainBase, {
+    placeholder: curDomain ? `${curDomain} (Enter to keep)` : '',
+    initial: '',
+  });
   const webhook = { enabled: true };
   if (!isSkippableAnswer(domainRaw)) {
     webhook.domain = String(domainRaw).trim();
   }
   if (secretsCapable) {
     const authPrompt = hasStoredSecret(SECRET_ACCOUNTS.webhookAuth)
-      ? 'Auth Token (stored, Enter=keep): '
-      : 'ngrok Auth Token [hidden]: ';
-    webhook.authtoken = (await io.askSecret(authPrompt)).trim();
+      ? 'ngrok Auth Token (stored — leave empty to keep)'
+      : 'ngrok Auth Token';
+    webhook.authtoken = (await password(authPrompt)).trim();
   } else {
     io.say('• ngrok Auth Token: skipped (Linux keychain unavailable).');
   }
@@ -434,10 +402,16 @@ async function stepProviderKeys(io, { updateSection, secretsCapable = true }) {
     io.say('• Skipped provider API keys (Linux keychain unavailable).');
     return;
   }
-  io.say('Optional API keys (hidden). Enter to skip a provider.');
+  io.say('Optional API keys (hidden). Pick providers to configure.');
+  const providerOpts = AG_API_PROVIDERS.map((p) => ({
+    value: p.id,
+    label: p.name,
+    hint: p.env,
+  }));
+  const selectedIds = await multiselect('Which provider API keys to set?', providerOpts, { min: 0 });
   const providers = {};
-  for (const p of AG_API_PROVIDERS) {
-    const key = (await io.askSecret(`${p.name} API key (${p.env}, Enter=skip): `)).trim();
+  for (const p of AG_API_PROVIDERS.filter((x) => selectedIds.includes(x.id))) {
+    const key = (await password(`${p.name} API key (${p.env})`)).trim();
     if (!isSkippableAnswer(key)) {
       providers[p.id] = { apiKey: key, enabled: true };
     }
@@ -458,13 +432,8 @@ async function stepPresets(io, { readSection, updateSection, DEFAULT_PRESETS })
   if (existing.length > 0) {
     io.say(`Current presets: ${existing.join(', ')}`);
   }
-  const raw = await io.ask('Install default Mixdog presets? [y/N] (Enter=skip): ');
-  if (isSkippableAnswer(raw)) {
-    io.say('• Kept existing presets.');
-    return;
-  }
-  const a = String(raw).trim().toLowerCase();
-  if (a !== 'y' && a !== 'yes') {
+  const installDefaults = await confirm('Install default Mixdog presets?', { initial: false });
+  if (!installDefaults) {
     io.say('• Kept existing presets.');
     return;
   }
@@ -492,9 +461,15 @@ async function stepRolePresetMapping(io, { readSection, dataDir }) {
   const byName = new Map(roles.map((r) => [r.name, r]));
   for (const roleName of WORKFLOW_ROLES) {
     const cur = byName.get(roleName)?.preset || DEFAULT_USER_WORKFLOW.roles.find((r) => r.name === roleName)?.preset || '';
-    const raw = await io.ask(`Preset for role "${roleName}" [${cur}]: `);
-    if (isSkippableAnswer(raw)) continue;
-    const preset = String(raw).trim();
+    const options = [
+      { value: '__keep__', label: `Keep current${cur ? ` (${cur})` : ''}` },
+      ...presetIds.map((id) => ({ value: id, label: id })),
+    ];
+    const chosen = await select(`Preset for role "${roleName}"`, options, {
+      initial: cur && presetIds.includes(cur) ? cur : '__keep__',
+    });
+    if (chosen === '__keep__') continue;
+    const preset = String(chosen).trim();
     if (!presetIds.includes(preset)) {
       io.say(`  ! Unknown preset "${preset}" — left "${roleName}" unchanged.`);
       continue;
@@ -519,14 +494,6 @@ function resolveSearchBackendInput(raw) {
   return SEARCH_OAUTH_ALIASES[key] || null;
 }
 
-function parseYesNo(raw) {
-  if (isSkippableAnswer(raw)) return null;
-  const v = String(raw).trim().toLowerCase();
-  if (v === 'y' || v === 'yes' || v === 'true' || v === '1') return true;
-  if (v === 'n' || v === 'no' || v === 'false' || v === '0') return false;
-  return undefined;
-}
-
 /** Mirrors POST /search/config → mergeSearchConfig. */
 export async function stepSearchBackend(io, { updateSection, readSection, secretsCapable = true }) {
   io.say('\n── Step 7/9: Search backend ──');
@@ -534,13 +501,18 @@ export async function stepSearchBackend(io, { updateSection, readSection, secret
   const { hasStoredSecret, SECRET_ACCOUNTS, getSearchApiKey } = await import('../src/shared/config.mjs');
   const search = readSection('search') || {};
   const curProvider = String(search.provider || 'anthropic-oauth').trim() || 'anthropic-oauth';
-  const backendRaw = await io.ask(`Search provider [${curProvider}]: `);
+  const providerOptions = [
+    { value: 'anthropic-oauth', label: 'anthropic-oauth', hint: 'Claude OAuth' },
+    { value: 'openai-oauth', label: 'openai-oauth', hint: 'OpenAI OAuth' },
+    { value: 'grok-oauth', label: 'grok-oauth', hint: 'xAI Grok OAuth' },
+  ];
+  const backendRaw = await select('Search provider', providerOptions, {
+    initial: SEARCH_OAUTH_PROVIDERS.has(curProvider) ? curProvider : 'anthropic-oauth',
+  });
   let provider = curProvider;
   if (!isSkippableAnswer(backendRaw)) {
-    const resolved = resolveSearchBackendInput(backendRaw);
-    if (!resolved) {
-      io.say(`  ! Unknown provider "${String(backendRaw).trim()}" — keeping ${curProvider}.`);
-    } else if (!SEARCH_OAUTH_PROVIDERS.has(resolved)) {
+    const resolved = resolveSearchBackendInput(backendRaw) || String(backendRaw).trim();
+    if (!SEARCH_OAUTH_PROVIDERS.has(resolved)) {
       io.say(`  ! Provider "${resolved}" is not a supported OAuth backend — keeping ${curProvider}.`);
     } else {
       provider = resolved;
@@ -555,9 +527,9 @@ export async function stepSearchBackend(io, { updateSection, readSection, secret
     for (const p of SEARCH_RAW_KEY_PROVIDERS) {
       const hadKey = hasStoredSecret(SECRET_ACCOUNTS.searchApiKey(p.id));
       const keyPrompt = hadKey
-        ? `${p.name} API key (stored, Enter=keep): `
-        : `${p.name} API key [hidden] (Enter=skip): `;
-      const key = (await io.askSecret(keyPrompt)).trim();
+        ? `${p.name} API key (stored — leave empty to keep)`
+        : `${p.name} API key (leave empty to skip)`;
+      const key = (await password(keyPrompt)).trim();
       if (!isSkippableAnswer(key)) {
         searchProviders[p.id] = key;
       }
@@ -571,14 +543,22 @@ export async function stepSearchBackend(io, { updateSection, readSection, secret
     const curModel = (search.models && search.models.openai)
       || DEFAULT_MODELS.openai
       || '';
-    const modelRaw = await io.ask(`OpenAI model [${curModel}] (Enter=keep): `);
+    const modelRaw = await text('OpenAI model', {
+      placeholder: curModel ? `${curModel} (Enter to keep)` : 'Enter to keep',
+      initial: '',
+    });
     if (!isSkippableAnswer(modelRaw)) {
       const model = String(modelRaw).trim();
       if (model) payload.models = { ...(payload.models || {}), openai: model };
     }
     const curEffort = String(search.modelOptions?.openai?.effort || 'medium').trim() || 'medium';
-    const effortRaw = await io.ask(`OpenAI effort (low/medium/high) [${curEffort}] (Enter=keep): `);
-    if (!isSkippableAnswer(effortRaw)) {
+    const effortRaw = await select('OpenAI effort', [
+      { value: '__keep__', label: `Keep current (${curEffort})` },
+      { value: 'low', label: 'low' },
+      { value: 'medium', label: 'medium' },
+      { value: 'high', label: 'high' },
+    ], { initial: '__keep__' });
+    if (!isSkippableAnswer(effortRaw) && effortRaw !== '__keep__') {
       const effort = String(effortRaw).trim().toLowerCase();
       if (!OPENAI_SEARCH_EFFORT_VALUES.has(effort)) {
         io.say(`  ! Unknown effort "${effortRaw.trim()}" — keeping ${curEffort}.`);
@@ -588,11 +568,11 @@ export async function stepSearchBackend(io, { updateSection, readSection, secret
       }
     }
     const curFast = !!search.modelOptions?.openai?.fast;
-    const fastRaw = await io.ask(`OpenAI Fast mode [${curFast ? 'y' : 'N'}] (y/N, Enter=keep): `);
-    const fastParsed = parseYesNo(fastRaw);
-    if (fastParsed === undefined && !isSkippableAnswer(fastRaw)) {
-      io.say('  ! Fast mode: answer y or n — keeping current.');
-    } else if (fastParsed !== null) {
+    const fastKeep = await confirm(`OpenAI Fast mode (current: ${curFast ? 'on' : 'off'}) — enable?`, {
+      initial: curFast,
+    });
+    const fastParsed = fastKeep === curFast ? null : fastKeep;
+    if (fastParsed !== null) {
       const base = payload.modelOptions?.openai || search.modelOptions?.openai || {};
       const openaiOpts = { ...base };
       if (fastParsed) openaiOpts.fast = true;
@@ -606,7 +586,10 @@ export async function stepSearchBackend(io, { updateSection, readSection, secret
     const curModel = (search.models && search.models.xai)
       || DEFAULT_MODELS.xai
       || '';
-    const modelRaw = await io.ask(`xAI model [${curModel}] (Enter=keep): `);
+    const modelRaw = await text('xAI model', {
+      placeholder: curModel ? `${curModel} (Enter to keep)` : 'Enter to keep',
+      initial: '',
+    });
     if (!isSkippableAnswer(modelRaw)) {
       const model = String(modelRaw).trim();
       if (model) payload.models = { ...(payload.models || {}), xai: model };
@@ -648,8 +631,14 @@ export async function stepExplorerPreset(io, { readSection, updateSection, DEFAU
   if (validIds.size > 0) {
     io.say(`Available presets: ${[...validIds].join(', ')}`);
   }
-  const raw = await io.ask(`Preset for explorer (explore tool) [${curExplore}]: `);
-  if (isSkippableAnswer(raw)) {
+  const exploreOptions = [
+    { value: '__keep__', label: `Keep current (${curExplore})` },
+    ...[...validIds].map((id) => ({ value: id, label: id })),
+  ];
+  const raw = await select('Preset for explorer (explore tool)', exploreOptions, {
+    initial: validIds.has(curExplore) ? curExplore : '__keep__',
+  });
+  if (raw === '__keep__' || isSkippableAnswer(raw)) {
     io.say(`• Explorer preset unchanged (${curExplore}).`);
     return;
   }

package/src/agent/bridge-stall-watchdog.mjs

@@ -114,7 +114,7 @@ export function inspectBridgeEntry(entry, abortSeconds = DEFAULT_ABORT_S, now =
         return { verdict: 'stall', staleSeconds, stage, reason: 'tool-runtime-fallback', toolName: entry.lastToolCall || null };
     }
     if (stage === 'idle' || stage === 'done' || stage === 'error' || stage === 'cancelling') {
-        // Terminal stages never abort, but may need flush+hide after 120s (fix B).
+        // Terminal stages never abort, but may need flush+hide after the terminal-reap window (TERMINAL_REAP_MS, 1h) (fix B).
         const progressRef = entry.lastProgressAt || entry.doneAt || entry.updatedAt;
         if (progressRef && (now - progressRef) >= TERMINAL_REAP_MS) {
             return { verdict: 'terminal-reap', staleSeconds: Math.round((now - progressRef) / 1000), stage };
@@ -253,7 +253,7 @@ export function startBridgeStallWatchdog(params) {
         // alone only flips in-memory listHidden; the statusline aggregator
         // reads the on-disk JSON and keeps rendering a non-closed bridge worker
         // as idle until the store sweep. closeSession plants closed===true so
-        // the aggregator drops it immediately — one consistent 300s lifecycle.
+        // the aggregator drops it immediately — one consistent 1h lifecycle (TERMINAL_REAP_MS).
         if (res.verdict === 'terminal-reap' && !_reaped) {
             _reaped = true;
             const reapId = currentSessionId();

package/src/agent/index.mjs

@@ -441,14 +441,14 @@ function _cancelBridgeReap(sessionId) {
 // role/status filters and a brief flag mirror the legacy tool's shape, plus a
 // `tag` field resolved from the tag registry.
 function _bridgeListSessions(opts = {}) {
-  const sessions = listSessions();
+  const includeClosed = opts.includeClosed === true;
+  const sessions = listSessions({ includeClosed });
   if (sessions.length === 0) return 'No active sessions.';
   const now = Date.now();
   const brief = opts.brief !== false;
-  const includeClosed = opts.includeClosed === true;
   const roleFilter = typeof opts.role === 'string' && opts.role ? opts.role : null;
   const statusFilter = typeof opts.status === 'string' && opts.status ? opts.status : null;
-  let filtered = includeClosed ? sessions : sessions.filter((s) => s.closed !== true);
+  const filtered = sessions;
   if (filtered.length === 0) return 'No active sessions.';
   const rows = filtered.map((s) => {
     const runtime = getSessionRuntime(s.id);

package/src/agent/orchestrator/providers/anthropic-oauth.mjs

@@ -8,6 +8,8 @@
 import { readFileSync, existsSync, statSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
+import { createServer } from 'http';
+import { randomBytes, createHash } from 'crypto';
 import {
     traceBridgeFetch,
     traceBridgeSse,
@@ -208,6 +210,22 @@ const ANTHROPIC_VERSION = '2023-06-01';
 const DEFAULT_CREDENTIALS_PATH = join(homedir(), '.claude', '.credentials.json');
 const CLAUDE_CODE_CLIENT_ID = process.env.ANTHROPIC_OAUTH_CLIENT_ID || '9d1c250a-e61b-44d9-88ed-5944d1962f5e';
 const TOKEN_REFRESH_SKEW_MS = 5 * 60_000;
+const CLAUDE_AI_AUTHORIZE_URL = 'https://claude.com/cai/oauth/authorize';
+const ALL_OAUTH_SCOPES = [
+    'org:create_api_key',
+    'user:profile',
+    'user:inference',
+    'user:sessions:claude_code',
+    'user:mcp_servers',
+    'user:file_upload',
+];
+const OAUTH_LOGIN_SCOPE = ALL_OAUTH_SCOPES.join(' ');
+const OAUTH_CALLBACK_HOST = 'localhost';
+const OAUTH_CALLBACK_PORT = 54545;
+const OAUTH_CALLBACK_PATH = '/callback';
+const OAUTH_REDIRECT_URI = `http://${OAUTH_CALLBACK_HOST}:${OAUTH_CALLBACK_PORT}${OAUTH_CALLBACK_PATH}`;
+const OAUTH_LOGIN_TIMEOUT_MS = 5 * 60_000;
+const OAUTH_TOKEN_TIMEOUT_MS = 30_000;
 
 // Anthropic OAuth contract for first-party Claude Code clients.
 // Opus/Sonnet requests are gated on a specific system-prompt prefix.
@@ -1739,6 +1757,127 @@ export class AnthropicOAuthProvider {
     }
 }
 
+// --- Login flow (PKCE loopback, export for setup UI / CLI) ---
+
+function _oauthGeneratePKCE() {
+    const verifier = randomBytes(32).toString('base64url');
+    const challenge = createHash('sha256').update(verifier).digest('base64url');
+    return { verifier, challenge };
+}
+
+function _oauthCredentialsWritePath() {
+    for (const p of credentialCandidates()) {
+        if (existsSync(p)) return p;
+    }
+    return DEFAULT_CREDENTIALS_PATH;
+}
+
+function _oauthParseScopeField(scope) {
+    if (Array.isArray(scope)) return scope;
+    return String(scope || '').split(' ').filter(Boolean);
+}
+
+export async function loginOAuth() {
+    const pkce = _oauthGeneratePKCE();
+    const state = randomBytes(32).toString('base64url');
+    const url = new URL(CLAUDE_AI_AUTHORIZE_URL);
+    url.searchParams.set('code', 'true');
+    url.searchParams.set('client_id', CLAUDE_CODE_CLIENT_ID);
+    url.searchParams.set('response_type', 'code');
+    url.searchParams.set('redirect_uri', OAUTH_REDIRECT_URI);
+    url.searchParams.set('scope', OAUTH_LOGIN_SCOPE);
+    url.searchParams.set('code_challenge', pkce.challenge);
+    url.searchParams.set('code_challenge_method', 'S256');
+    url.searchParams.set('state', state);
+    process.stderr.write(`\n[anthropic-oauth] Open this URL to log in with Claude:\n${url.toString()}\n\n`);
+    try {
+        const { exec } = await import('child_process');
+        const opener = process.platform === 'win32' ? 'start' : process.platform === 'darwin' ? 'open' : 'xdg-open';
+        exec(`${opener} "${url.toString()}"`, { windowsHide: true });
+    } catch { /* user opens manually */ }
+
+    return new Promise((resolve) => {
+        const timeout = setTimeout(() => { server.close(); resolve(null); }, OAUTH_LOGIN_TIMEOUT_MS);
+        const server = createServer(async (req, res) => {
+            const u = new URL(req.url || '/', `http://${OAUTH_CALLBACK_HOST}:${OAUTH_CALLBACK_PORT}`);
+            if (u.pathname !== OAUTH_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');
+                clearTimeout(timeout);
+                server.close();
+                resolve(null);
+                return;
+            }
+            res.writeHead(200, { 'Content-Type': 'text/html' });
+            res.end('<html><body><h2>Claude login successful! You can close this tab.</h2></body></html>');
+            clearTimeout(timeout);
+            server.close();
+            try {
+                const tokenRes = await fetch(TOKEN_URL, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'anthropic-dangerous-direct-browser-access': 'true',
+                        'user-agent': `claude-cli/${resolveCliVersion()} (external, sdk-cli)`,
+                    },
+                    body: JSON.stringify({
+                        grant_type: 'authorization_code',
+                        code,
+                        redirect_uri: OAUTH_REDIRECT_URI,
+                        client_id: CLAUDE_CODE_CLIENT_ID,
+                        code_verifier: pkce.verifier,
+                        state,
+                    }),
+                    redirect: 'error',
+                    signal: AbortSignal.timeout(OAUTH_TOKEN_TIMEOUT_MS),
+                    dispatcher: getLlmDispatcher(),
+                });
+                if (!tokenRes.ok) { resolve(null); return; }
+                const json = await tokenRes.json();
+                const accessToken = json?.access_token || json?.accessToken;
+                const refreshToken = json?.refresh_token || json?.refreshToken;
+                if (!accessToken || !refreshToken) { resolve(null); return; }
+                const expiresAt = _normalizeExpiresAt(json?.expires_at ?? json?.expiresAt)
+                    || (typeof json?.expires_in === 'number' ? Date.now() + json.expires_in * 1000 : 0);
+                const scopes = _oauthParseScopeField(json?.scope);
+                const credPath = _oauthCredentialsWritePath();
+                let raw = {};
+                if (existsSync(credPath)) {
+                    raw = JSON.parse(readFileSync(credPath, 'utf-8'));
+                }
+                const existingOauth = raw.claudeAiOauth || {};
+                raw.claudeAiOauth = {
+                    ...existingOauth,
+                    accessToken,
+                    refreshToken,
+                    expiresAt,
+                    scopes,
+                    subscriptionType: existingOauth.subscriptionType ?? null,
+                };
+                _saveCredentialsFile(credPath, raw);
+                resolve({
+                    path: credPath,
+                    accessToken,
+                    refreshToken,
+                    expiresAt,
+                    scopes,
+                    subscriptionType: raw.claudeAiOauth.subscriptionType,
+                });
+            } catch {
+                resolve(null);
+            }
+        });
+        server.listen(OAUTH_CALLBACK_PORT, OAUTH_CALLBACK_HOST);
+        server.on('error', () => { clearTimeout(timeout); resolve(null); });
+    });
+}
+
 // Additive exports for test harnesses.
 // Lets the SSE parser be exercised in isolation against a synthetic
 // ReadableStream without needing a live OAuth session.