fix(streaming): use per-message stream ids and oauth resolver

src/agent/providers/index.ts

@@ -0,0 +1,34 @@
+/**
+ * Provider Management
+ *
+ * Unified exports for LLM provider management:
+ * - Registry: Provider metadata, status checking, listing
+ * - Resolver: API key resolution, model resolution
+ */
+
+// Registry exports
+export {
+  type AuthMethod,
+  type ProviderInfo,
+  type ProviderMeta,
+  PROVIDER_ALIAS,
+  isOAuthProvider,
+  isProviderAvailable,
+  getCurrentProvider,
+  getProviderMeta,
+  getDefaultModel,
+  getProviderList,
+  getAvailableProviders,
+  formatProviderStatus,
+  getLoginInstructions,
+} from "./registry.js";
+
+// Resolver exports
+export {
+  type ProviderConfig,
+  resolveProviderConfig,
+  resolveApiKey,
+  resolveBaseUrl,
+  resolveModelId,
+  resolveModel,
+} from "./resolver.js";

src/agent/providers/oauth/cli-credentials.ts

@@ -0,0 +1,363 @@
+/**
+ * CLI Credentials Reader
+ *
+ * Read OAuth credentials from external CLI tools:
+ * - Claude Code: ~/.claude/.credentials.json or macOS Keychain
+ * - Codex: ~/.codex/auth.json or macOS Keychain
+ *
+ * Based on OpenClaw's implementation.
+ */
+
+import { execSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+
+// ============================================================
+// Types
+// ============================================================
+
+export type OAuthCredential = {
+  type: "oauth";
+  provider: string;
+  access: string;
+  refresh: string;
+  expires: number;
+};
+
+export type TokenCredential = {
+  type: "token";
+  provider: string;
+  token: string;
+  expires: number;
+};
+
+export type ClaudeCliCredential = (OAuthCredential | TokenCredential) & {
+  provider: "anthropic";
+};
+
+export type CodexCliCredential = OAuthCredential & {
+  provider: "openai-codex";
+  accountId?: string;
+};
+
+// ============================================================
+// Paths
+// ============================================================
+
+const CLAUDE_CLI_CREDENTIALS_PATH = ".claude/.credentials.json";
+const CLAUDE_CLI_KEYCHAIN_SERVICE = "Claude Code-credentials";
+const CLAUDE_CLI_KEYCHAIN_ACCOUNT = "Claude Code";
+
+const CODEX_CLI_AUTH_FILENAME = "auth.json";
+const CODEX_CLI_KEYCHAIN_SERVICE = "Codex Auth";
+
+function resolveHomePath(relativePath: string): string {
+  const home = os.homedir();
+  return path.join(home, relativePath);
+}
+
+function resolveCodexHomePath(): string {
+  const configured = process.env.CODEX_HOME;
+  const home = configured ? configured.replace(/^~/, os.homedir()) : resolveHomePath(".codex");
+  try {
+    return fs.realpathSync(home);
+  } catch {
+    return home;
+  }
+}
+
+function computeCodexKeychainAccount(codexHome: string): string {
+  const hash = createHash("sha256").update(codexHome).digest("hex");
+  return `cli|${hash.slice(0, 16)}`;
+}
+
+// ============================================================
+// Claude Code Credentials
+// ============================================================
+
+function readClaudeCliKeychainCredentials(): ClaudeCliCredential | null {
+  if (process.platform !== "darwin") return null;
+
+  try {
+    const result = execSync(
+      `security find-generic-password -s "${CLAUDE_CLI_KEYCHAIN_SERVICE}" -w`,
+      { encoding: "utf8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"] },
+    );
+
+    const data = JSON.parse(result.trim());
+    const claudeOauth = data?.claudeAiOauth;
+    if (!claudeOauth || typeof claudeOauth !== "object") return null;
+
+    const accessToken = claudeOauth.accessToken;
+    const refreshToken = claudeOauth.refreshToken;
+    const expiresAt = claudeOauth.expiresAt;
+
+    if (typeof accessToken !== "string" || !accessToken) return null;
+    if (typeof expiresAt !== "number" || expiresAt <= 0) return null;
+
+    if (typeof refreshToken === "string" && refreshToken) {
+      return {
+        type: "oauth",
+        provider: "anthropic",
+        access: accessToken,
+        refresh: refreshToken,
+        expires: expiresAt,
+      };
+    }
+
+    return {
+      type: "token",
+      provider: "anthropic",
+      token: accessToken,
+      expires: expiresAt,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function readClaudeCliFileCredentials(): ClaudeCliCredential | null {
+  const credPath = resolveHomePath(CLAUDE_CLI_CREDENTIALS_PATH);
+
+  try {
+    if (!fs.existsSync(credPath)) return null;
+    const raw = JSON.parse(fs.readFileSync(credPath, "utf8"));
+    if (!raw || typeof raw !== "object") return null;
+
+    const claudeOauth = raw.claudeAiOauth;
+    if (!claudeOauth || typeof claudeOauth !== "object") return null;
+
+    const accessToken = claudeOauth.accessToken;
+    const refreshToken = claudeOauth.refreshToken;
+    const expiresAt = claudeOauth.expiresAt;
+
+    if (typeof accessToken !== "string" || !accessToken) return null;
+    if (typeof expiresAt !== "number" || expiresAt <= 0) return null;
+
+    if (typeof refreshToken === "string" && refreshToken) {
+      return {
+        type: "oauth",
+        provider: "anthropic",
+        access: accessToken,
+        refresh: refreshToken,
+        expires: expiresAt,
+      };
+    }
+
+    return {
+      type: "token",
+      provider: "anthropic",
+      token: accessToken,
+      expires: expiresAt,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read Claude Code CLI credentials.
+ * Priority: macOS Keychain > File (~/.claude/.credentials.json)
+ */
+export function readClaudeCliCredentials(): ClaudeCliCredential | null {
+  // Try keychain first (macOS only)
+  const keychainCreds = readClaudeCliKeychainCredentials();
+  if (keychainCreds) return keychainCreds;
+
+  // Fall back to file
+  return readClaudeCliFileCredentials();
+}
+
+/**
+ * Check if Claude Code credentials exist and are valid.
+ */
+export function hasValidClaudeCliCredentials(): boolean {
+  const creds = readClaudeCliCredentials();
+  if (!creds) return false;
+  // Check if not expired (with 5 minute buffer)
+  return creds.expires > Date.now() + 5 * 60 * 1000;
+}
+
+/**
+ * Get the access token from Claude Code credentials.
+ */
+export function getClaudeCliAccessToken(): string | null {
+  const creds = readClaudeCliCredentials();
+  if (!creds) return null;
+  if (creds.type === "oauth") return creds.access;
+  if (creds.type === "token") return creds.token;
+  return null;
+}
+
+// ============================================================
+// Codex CLI Credentials
+// ============================================================
+
+function readCodexKeychainCredentials(): CodexCliCredential | null {
+  if (process.platform !== "darwin") return null;
+
+  const codexHome = resolveCodexHomePath();
+  const account = computeCodexKeychainAccount(codexHome);
+
+  try {
+    const secret = execSync(
+      `security find-generic-password -s "${CODEX_CLI_KEYCHAIN_SERVICE}" -a "${account}" -w`,
+      { encoding: "utf8", timeout: 5000, stdio: ["pipe", "pipe", "pipe"] },
+    ).trim();
+
+    const parsed = JSON.parse(secret);
+    const tokens = parsed.tokens;
+    const accessToken = tokens?.access_token;
+    const refreshToken = tokens?.refresh_token;
+    if (typeof accessToken !== "string" || !accessToken) return null;
+    if (typeof refreshToken !== "string" || !refreshToken) return null;
+
+    const lastRefreshRaw = parsed.last_refresh;
+    const lastRefresh =
+      typeof lastRefreshRaw === "string" || typeof lastRefreshRaw === "number"
+        ? new Date(lastRefreshRaw).getTime()
+        : Date.now();
+    const expires = Number.isFinite(lastRefresh)
+      ? lastRefresh + 60 * 60 * 1000
+      : Date.now() + 60 * 60 * 1000;
+
+    return {
+      type: "oauth",
+      provider: "openai-codex",
+      access: accessToken,
+      refresh: refreshToken,
+      expires,
+      accountId: typeof tokens?.account_id === "string" ? tokens.account_id : undefined,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function readCodexFileCredentials(): CodexCliCredential | null {
+  const authPath = path.join(resolveCodexHomePath(), CODEX_CLI_AUTH_FILENAME);
+
+  try {
+    if (!fs.existsSync(authPath)) return null;
+    const raw = JSON.parse(fs.readFileSync(authPath, "utf8"));
+    if (!raw || typeof raw !== "object") return null;
+
+    const tokens = raw.tokens;
+    if (!tokens || typeof tokens !== "object") return null;
+
+    const accessToken = tokens.access_token;
+    const refreshToken = tokens.refresh_token;
+    if (typeof accessToken !== "string" || !accessToken) return null;
+    if (typeof refreshToken !== "string" || !refreshToken) return null;
+
+    let expires: number;
+    try {
+      const stat = fs.statSync(authPath);
+      expires = stat.mtimeMs + 60 * 60 * 1000;
+    } catch {
+      expires = Date.now() + 60 * 60 * 1000;
+    }
+
+    return {
+      type: "oauth",
+      provider: "openai-codex",
+      access: accessToken,
+      refresh: refreshToken,
+      expires,
+      accountId: typeof tokens.account_id === "string" ? tokens.account_id : undefined,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read Codex CLI credentials.
+ * Priority: macOS Keychain > File (~/.codex/auth.json)
+ */
+export function readCodexCliCredentials(): CodexCliCredential | null {
+  // Try keychain first (macOS only)
+  const keychainCreds = readCodexKeychainCredentials();
+  if (keychainCreds) return keychainCreds;
+
+  // Fall back to file
+  return readCodexFileCredentials();
+}
+
+/**
+ * Check if Codex credentials exist and are valid.
+ */
+export function hasValidCodexCliCredentials(): boolean {
+  const creds = readCodexCliCredentials();
+  if (!creds) return false;
+  return creds.expires > Date.now() + 5 * 60 * 1000;
+}
+
+/**
+ * Get the access token from Codex credentials.
+ */
+export function getCodexCliAccessToken(): string | null {
+  const creds = readCodexCliCredentials();
+  if (!creds) return null;
+  return creds.access;
+}
+
+// ============================================================
+// Unified Interface
+// ============================================================
+
+export type CliCredentialSource = "claude-code" | "codex";
+
+export interface CliCredentialStatus {
+  source: CliCredentialSource;
+  available: boolean;
+  expires?: number;
+  expiresIn?: string;
+}
+
+/**
+ * Get status of all CLI credential sources.
+ */
+export function getCliCredentialStatus(): CliCredentialStatus[] {
+  const results: CliCredentialStatus[] = [];
+
+  // Claude Code
+  const claudeCreds = readClaudeCliCredentials();
+  if (claudeCreds) {
+    const expiresIn = claudeCreds.expires - Date.now();
+    results.push({
+      source: "claude-code",
+      available: expiresIn > 0,
+      expires: claudeCreds.expires,
+      expiresIn: formatDuration(expiresIn),
+    });
+  } else {
+    results.push({ source: "claude-code", available: false });
+  }
+
+  // Codex
+  const codexCreds = readCodexCliCredentials();
+  if (codexCreds) {
+    const expiresIn = codexCreds.expires - Date.now();
+    results.push({
+      source: "codex",
+      available: expiresIn > 0,
+      expires: codexCreds.expires,
+      expiresIn: formatDuration(expiresIn),
+    });
+  } else {
+    results.push({ source: "codex", available: false });
+  }
+
+  return results;
+}
+
+function formatDuration(ms: number): string {
+  if (ms <= 0) return "expired";
+  const hours = Math.floor(ms / (60 * 60 * 1000));
+  const minutes = Math.floor((ms % (60 * 60 * 1000)) / (60 * 1000));
+  if (hours > 0) return `${hours}h ${minutes}m`;
+  return `${minutes}m`;
+}

src/agent/providers/oauth/index.ts

@@ -0,0 +1,7 @@
+/**
+ * OAuth Credential Reading
+ *
+ * Read OAuth credentials from external CLI tools (Claude Code, Codex).
+ */
+
+export * from "./cli-credentials.js";

src/agent/providers/registry.ts

@@ -0,0 +1,276 @@
+/**
+ * Provider Registry
+ *
+ * Central registry for all LLM providers with metadata,
+ * status checking, and display formatting.
+ */
+
+import { credentialManager } from "../credentials.js";
+import {
+  hasValidClaudeCliCredentials,
+  hasValidCodexCliCredentials,
+} from "./oauth/cli-credentials.js";
+
+// ============================================================
+// Types
+// ============================================================
+
+export type AuthMethod = "api-key" | "oauth";
+
+export interface ProviderInfo {
+  id: string;
+  name: string;
+  authMethod: AuthMethod;
+  available: boolean;
+  configured: boolean;
+  current: boolean;
+  defaultModel: string;
+  models: string[];
+  loginUrl?: string | undefined;
+  loginCommand?: string | undefined;
+}
+
+/** Static provider metadata (without runtime status) */
+export interface ProviderMeta {
+  id: string;
+  name: string;
+  authMethod: AuthMethod;
+  defaultModel: string;
+  models: string[];
+  loginUrl?: string | undefined;
+  loginCommand?: string | undefined;
+}
+
+// ============================================================
+// Provider Registry
+// ============================================================
+
+const PROVIDER_REGISTRY: Record<string, ProviderMeta> = {
+  "claude-code": {
+    id: "claude-code",
+    name: "Claude Code (OAuth)",
+    authMethod: "oauth",
+    defaultModel: "claude-opus-4-5",
+    models: ["claude-opus-4-5", "claude-sonnet-4-5", "claude-haiku-4-5"],
+    loginCommand: "claude login",
+  },
+  "openai-codex": {
+    id: "openai-codex",
+    name: "Codex (OAuth)",
+    authMethod: "oauth",
+    defaultModel: "gpt-5.2",
+    models: ["gpt-5.2", "gpt-5.2-codex", "gpt-5.1-codex", "gpt-5.1-codex-mini", "gpt-5.1-codex-max"],
+    loginCommand: "codex login",
+  },
+  "anthropic": {
+    id: "anthropic",
+    name: "Anthropic (API Key)",
+    authMethod: "api-key",
+    defaultModel: "claude-sonnet-4-5",
+    models: ["claude-opus-4-5", "claude-sonnet-4-5", "claude-haiku-4-5"],
+    loginUrl: "https://console.anthropic.com/",
+  },
+  "openai": {
+    id: "openai",
+    name: "OpenAI",
+    authMethod: "api-key",
+    defaultModel: "gpt-4o",
+    models: ["gpt-4o", "gpt-4o-mini", "o1", "o1-mini"],
+    loginUrl: "https://platform.openai.com/api-keys",
+  },
+  "kimi-coding": {
+    id: "kimi-coding",
+    name: "Kimi Code",
+    authMethod: "api-key",
+    defaultModel: "kimi-k2-thinking",
+    models: ["kimi-k2-thinking", "k2p5"],
+    loginUrl: "https://kimi.moonshot.cn/",
+  },
+  "google": {
+    id: "google",
+    name: "Google AI",
+    authMethod: "api-key",
+    defaultModel: "gemini-2.0-flash",
+    models: ["gemini-2.0-flash", "gemini-1.5-pro"],
+    loginUrl: "https://aistudio.google.com/apikey",
+  },
+  "groq": {
+    id: "groq",
+    name: "Groq",
+    authMethod: "api-key",
+    defaultModel: "llama-3.3-70b-versatile",
+    models: ["llama-3.3-70b-versatile", "mixtral-8x7b-32768"],
+    loginUrl: "https://console.groq.com/keys",
+  },
+  "mistral": {
+    id: "mistral",
+    name: "Mistral",
+    authMethod: "api-key",
+    defaultModel: "mistral-large-latest",
+    models: ["mistral-large-latest", "codestral-latest"],
+    loginUrl: "https://console.mistral.ai/api-keys",
+  },
+  "xai": {
+    id: "xai",
+    name: "xAI (Grok)",
+    authMethod: "api-key",
+    defaultModel: "grok-beta",
+    models: ["grok-beta", "grok-vision-beta"],
+    loginUrl: "https://console.x.ai/",
+  },
+  "openrouter": {
+    id: "openrouter",
+    name: "OpenRouter",
+    authMethod: "api-key",
+    defaultModel: "anthropic/claude-3.5-sonnet",
+    models: ["anthropic/claude-3.5-sonnet", "openai/gpt-4o"],
+    loginUrl: "https://openrouter.ai/keys",
+  },
+};
+
+/**
+ * Provider alias mapping for OAuth providers.
+ * Maps friendly names to actual pi-ai provider names.
+ */
+export const PROVIDER_ALIAS: Record<string, string> = {
+  "claude-code": "anthropic", // Claude Code OAuth uses anthropic API
+  "openai-codex": "openai", // Codex OAuth uses OpenAI API
+};
+
+// ============================================================
+// Status Checking
+// ============================================================
+
+/**
+ * Check if a provider is configured with API key in credentials.json5
+ */
+function isApiKeyConfigured(providerId: string): boolean {
+  const config = credentialManager.getLlmProviderConfig(providerId);
+  return !!config?.apiKey;
+}
+
+/**
+ * Check if OAuth provider has valid credentials
+ */
+function isOAuthAvailable(providerId: string): boolean {
+  if (providerId === "claude-code") {
+    return hasValidClaudeCliCredentials();
+  }
+  if (providerId === "openai-codex") {
+    return hasValidCodexCliCredentials();
+  }
+  return false;
+}
+
+/**
+ * Check if a provider uses OAuth authentication
+ */
+export function isOAuthProvider(providerId: string): boolean {
+  const info = PROVIDER_REGISTRY[providerId];
+  return info?.authMethod === "oauth";
+}
+
+/**
+ * Check if provider is available (has valid credentials)
+ */
+export function isProviderAvailable(providerId: string): boolean {
+  const info = PROVIDER_REGISTRY[providerId];
+  if (!info) return false;
+
+  if (info.authMethod === "oauth") {
+    return isOAuthAvailable(providerId);
+  }
+  return isApiKeyConfigured(providerId);
+}
+
+/**
+ * Get current provider from credentials
+ */
+export function getCurrentProvider(): string {
+  return credentialManager.getLlmProvider() ?? "kimi-coding";
+}
+
+// ============================================================
+// Provider Listing
+// ============================================================
+
+/**
+ * Get static provider metadata
+ */
+export function getProviderMeta(providerId: string): ProviderMeta | undefined {
+  return PROVIDER_REGISTRY[providerId];
+}
+
+/**
+ * Get default model for a provider
+ */
+export function getDefaultModel(providerId: string): string | undefined {
+  return PROVIDER_REGISTRY[providerId]?.defaultModel;
+}
+
+/**
+ * Get list of all providers with their runtime status
+ */
+export function getProviderList(): ProviderInfo[] {
+  const currentProvider = getCurrentProvider();
+
+  return Object.values(PROVIDER_REGISTRY).map((meta) => {
+    const isOAuth = meta.authMethod === "oauth";
+    const available = isOAuth ? isOAuthAvailable(meta.id) : isApiKeyConfigured(meta.id);
+
+    // Check if this is the current provider
+    // For claude-code, check if current is "anthropic" and OAuth is available
+    let isCurrent = currentProvider === meta.id;
+    if (meta.id === "claude-code" && currentProvider === "anthropic") {
+      isCurrent = hasValidClaudeCliCredentials();
+    }
+
+    return {
+      ...meta,
+      available,
+      configured: available,
+      current: isCurrent,
+    };
+  });
+}
+
+/**
+ * Get available providers only
+ */
+export function getAvailableProviders(): ProviderInfo[] {
+  return getProviderList().filter((p) => p.available);
+}
+
+// ============================================================
+// Display Helpers
+// ============================================================
+
+/**
+ * Format provider for display
+ */
+export function formatProviderStatus(provider: ProviderInfo): string {
+  const status = provider.available ? "✓" : "✗";
+  const current = provider.current ? " (current)" : "";
+  const auth = provider.authMethod === "oauth" ? " [OAuth]" : "";
+  return `${status} ${provider.name}${auth}${current}`;
+}
+
+/**
+ * Get login instructions for a provider
+ */
+export function getLoginInstructions(providerId: string): string {
+  const info = PROVIDER_REGISTRY[providerId];
+  if (!info) return `Unknown provider: ${providerId}`;
+
+  if (info.authMethod === "oauth") {
+    if (info.loginCommand) {
+      return `Run: ${info.loginCommand}\nThen restart Super Multica to use the credentials.`;
+    }
+  }
+
+  if (info.loginUrl) {
+    return `Get your API key at: ${info.loginUrl}\nThen add it to ~/.super-multica/credentials.json5`;
+  }
+
+  return "No login instructions available.";
+}

src/agent/providers/resolver.ts

@@ -0,0 +1,166 @@
+/**
+ * Provider Resolver
+ *
+ * Resolves provider configuration for making API calls,
+ * including API keys, OAuth tokens, and model selection.
+ */
+
+import { getModel } from "@mariozechner/pi-ai";
+import { credentialManager } from "../credentials.js";
+import {
+  readClaudeCliCredentials,
+  readCodexCliCredentials,
+} from "./oauth/cli-credentials.js";
+import {
+  PROVIDER_ALIAS,
+  getProviderMeta,
+  getDefaultModel,
+  isOAuthProvider,
+} from "./registry.js";
+import type { AgentOptions } from "../types.js";
+
+// ============================================================
+// Types
+// ============================================================
+
+export interface ProviderConfig {
+  provider: string;
+  model?: string | undefined;
+  apiKey?: string | undefined;
+  baseUrl?: string | undefined;
+  // OAuth specific
+  accessToken?: string | undefined;
+  refreshToken?: string | undefined;
+  expires?: number | undefined;
+}
+
+// ============================================================
+// Provider Config Resolution
+// ============================================================
+
+/**
+ * Get provider config for making API calls.
+ * Handles both OAuth and API Key authentication.
+ */
+export function resolveProviderConfig(providerId: string): ProviderConfig | null {
+  const meta = getProviderMeta(providerId);
+  if (!meta) return null;
+
+  if (meta.authMethod === "oauth") {
+    if (providerId === "claude-code") {
+      const creds = readClaudeCliCredentials();
+      if (!creds) return null;
+
+      const accessToken = creds.type === "oauth" ? creds.access : creds.token;
+      return {
+        provider: "anthropic", // Use anthropic API
+        apiKey: accessToken,
+        accessToken,
+        refreshToken: creds.type === "oauth" ? creds.refresh : undefined,
+        expires: creds.expires,
+      };
+    }
+
+    if (providerId === "openai-codex") {
+      const creds = readCodexCliCredentials();
+      if (!creds) return null;
+
+      return {
+        provider: "openai-codex",
+        accessToken: creds.access,
+        refreshToken: creds.refresh,
+        expires: creds.expires,
+      };
+    }
+  }
+
+  // API Key based
+  const config = credentialManager.getLlmProviderConfig(providerId);
+  if (!config?.apiKey) return null;
+
+  return {
+    provider: providerId,
+    model: config.model,
+    apiKey: config.apiKey,
+    baseUrl: config.baseUrl,
+  };
+}
+
+// ============================================================
+// API Key Resolution
+// ============================================================
+
+/**
+ * Get API Key based on provider.
+ * Priority: explicit key > OAuth credentials > credentials.json5 config.
+ */
+export function resolveApiKey(provider: string, explicitKey?: string): string | undefined {
+  if (explicitKey) return explicitKey;
+
+  // Try OAuth providers first (claude-code, openai-codex)
+  const providerConfig = resolveProviderConfig(provider);
+  if (providerConfig?.apiKey) {
+    return providerConfig.apiKey;
+  }
+  if (providerConfig?.accessToken) {
+    return providerConfig.accessToken;
+  }
+
+  // Fall back to credentials.json5
+  return credentialManager.getLlmProviderConfig(provider)?.apiKey;
+}
+
+/**
+ * Get Base URL based on provider.
+ * Priority: explicit URL > credentials.json5 config.
+ */
+export function resolveBaseUrl(provider: string, explicitUrl?: string): string | undefined {
+  if (explicitUrl) return explicitUrl;
+  return credentialManager.getLlmProviderConfig(provider)?.baseUrl;
+}
+
+/**
+ * Get Model ID based on provider.
+ * Priority: explicit model > credentials.json5 config > default.
+ */
+export function resolveModelId(provider: string, explicitModel?: string): string | undefined {
+  if (explicitModel) return explicitModel;
+  return credentialManager.getLlmProviderConfig(provider)?.model ?? getDefaultModel(provider);
+}
+
+// ============================================================
+// Model Resolution
+// ============================================================
+
+/**
+ * Resolve model for pi-ai based on provider and options.
+ */
+export function resolveModel(options: AgentOptions) {
+  if (options.provider && options.model) {
+    // Map provider alias (e.g., claude-code -> anthropic)
+    const actualProvider = PROVIDER_ALIAS[options.provider] ?? options.provider;
+
+    // Type assertion needed because provider/model come from dynamic user config
+    return (getModel as (p: string, m: string) => ReturnType<typeof getModel>)(
+      actualProvider,
+      options.model,
+    );
+  }
+
+  // If only provider specified, use default model for that provider
+  if (options.provider) {
+    const actualProvider = PROVIDER_ALIAS[options.provider] ?? options.provider;
+    const defaultModel = getDefaultModel(options.provider) ?? getDefaultModel(actualProvider);
+    if (defaultModel) {
+      return (getModel as (p: string, m: string) => ReturnType<typeof getModel>)(
+        actualProvider,
+        defaultModel,
+      );
+    }
+  }
+
+  return getModel("kimi-coding", "kimi-k2-thinking");
+}
+
+// Re-export for convenience
+export { isOAuthProvider };