auramaxx 0.0.1

package/server/lib/agent-profiles.ts

@@ -0,0 +1,419 @@
+import { createHash } from 'crypto';
+import { expandPermissions } from './permissions';
+import type { AgentTokenPayload } from '../types';
+import { normalizeScope } from './credential-scope';
+
+export type AgentProfileId =
+  | 'strict'
+  | 'dev'
+  | 'admin';
+
+export const LOCAL_AGENT_PROFILE_MODES = ['strict', 'dev', 'admin'] as const;
+export type LocalAgentProfileMode = typeof LOCAL_AGENT_PROFILE_MODES[number];
+
+export interface AgentPolicyProfileV1 {
+  id: AgentProfileId;
+  version: 'v1';
+  displayName: string;
+  description: string;
+  rationale: string;
+  permissions: string[];
+  credentialAccess: {
+    readScopes: string[];
+    writeScopes: string[];
+    excludeFields: string[];
+    maxReads?: number;
+  };
+  tokenDefaults: {
+    ttlSeconds: number;
+    maxReads?: number;
+  };
+  warnings: string[];
+}
+
+export interface ResolveProfileInput {
+  profileId: string;
+  profileVersion?: string;
+  overrides?: {
+    ttlSeconds?: number;
+    maxReads?: number;
+    scope?: string[];
+    readScopes?: string[];
+    writeScopes?: string[];
+    excludeFields?: string[];
+  };
+}
+
+export interface ResolvedProfilePolicy {
+  profile: {
+    id: AgentProfileId;
+    version: 'v1';
+    displayName: string;
+    rationale: string;
+  };
+  permissions: string[];
+  ttlSeconds: number;
+  credentialAccess: NonNullable<AgentTokenPayload['credentialAccess']>;
+  warnings: string[];
+  overrideDelta: string[];
+  effectivePolicyHash: string;
+}
+
+export class AgentProfileError extends Error {
+  code: string;
+  constructor(code: string, message: string) {
+    super(message);
+    this.name = 'AgentProfileError';
+    this.code = code;
+  }
+}
+
+const BUILTIN_PROFILES: AgentPolicyProfileV1[] = [
+  {
+    id: 'strict',
+    version: 'v1',
+    displayName: 'Strict',
+    description: 'Manual-approval-first baseline profile for local agents.',
+    rationale: 'Use when you want every agent token request reviewed by a human.',
+    permissions: ['secret:read'],
+    credentialAccess: {
+      readScopes: ['vault:agent'],
+      writeScopes: [],
+      excludeFields: ['password', 'cvv', 'privateKey', 'seedPhrase', 'refresh_token'],
+      maxReads: 50,
+    },
+    tokenDefaults: { ttlSeconds: 900, maxReads: 50 },
+    warnings: ['Pair with trust.localAutoApprove=false for strict local approval flow. Credential access is limited to the agent vault only.'],
+  },
+  {
+    id: 'dev',
+    version: 'v1',
+    displayName: 'Dev',
+    description: 'Developer profile for local agent automation with non-financial scope.',
+    rationale: 'Use for day-to-day local dev workflows without granting financial operations.',
+    permissions: ['wallet:list', 'secret:read', 'secret:write', 'action:create', 'action:read', 'action:resolve'],
+    credentialAccess: {
+      readScopes: ['vault:*'],
+      writeScopes: ['vault:*'],
+      excludeFields: ['cvv', 'seedPhrase', 'privateKey', 'refresh_token'],
+      maxReads: 500,
+    },
+    tokenDefaults: { ttlSeconds: 3600, maxReads: 500 },
+    warnings: ['Includes secret:write. Prefer dedicated non-primary vaults for agent-managed credentials.'],
+  },
+  {
+    id: 'admin',
+    version: 'v1',
+    displayName: 'Admin',
+    description: 'Full-access local agent profile.',
+    rationale: 'Use only when you explicitly trust the local agent process with broad access.',
+    permissions: ['admin:*'],
+    credentialAccess: {
+      readScopes: ['*'],
+      writeScopes: ['*'],
+      excludeFields: [],
+    },
+    tokenDefaults: { ttlSeconds: 3600 },
+    warnings: ['Dangerous profile: grants admin:* (full access). Not recommended for primary vault workflows.'],
+  },
+];
+
+export function listProfiles(): AgentPolicyProfileV1[] {
+  return BUILTIN_PROFILES.map((p) => ({ ...p }));
+}
+
+export function getProfile(id: string, version: string = 'v1'): AgentPolicyProfileV1 {
+  const anyVersion = BUILTIN_PROFILES.find((p) => p.id === id);
+  if (!anyVersion) {
+    throw new AgentProfileError('AGENT_PROFILE_NOT_FOUND', `Unknown profile: ${id}@${version}`);
+  }
+  const profile = BUILTIN_PROFILES.find((p) => p.id === id && p.version === version);
+  if (!profile) {
+    throw new AgentProfileError('AGENT_PROFILE_VERSION_UNSUPPORTED', `Unsupported profile version: ${id}@${version}`);
+  }
+  return profile;
+}
+
+function canonicalScopes(scopes: string[] | undefined): string[] {
+  const normalized = (scopes || []).map(normalizeScope);
+  if (normalized.some((scope) => scope.includes('**') || scope.includes('(') || scope.includes(')'))) {
+    throw new AgentProfileError('AGENT_PROFILE_SCOPE_INVALID', 'Scope selectors contain unsupported wildcard/pattern syntax');
+  }
+  return Array.from(new Set(normalized)).sort();
+}
+
+function canonicalStringList(values: string[] | undefined): string[] {
+  return Array.from(new Set((values || []).map((v) => v.trim()).filter(Boolean))).sort();
+}
+
+function hashPolicy(policy: Omit<ResolvedProfilePolicy, 'effectivePolicyHash'>): string {
+  const stable = JSON.stringify({
+    permissions: Array.from(new Set(policy.permissions)).sort(),
+    credentialAccess: {
+      read: Array.from(new Set(policy.credentialAccess.read || [])).sort(),
+      write: Array.from(new Set(policy.credentialAccess.write || [])).sort(),
+      excludeFields: Array.from(new Set(policy.credentialAccess.excludeFields || [])).sort(),
+      maxReads: typeof policy.credentialAccess.maxReads === 'number' ? policy.credentialAccess.maxReads : null,
+    },
+    ttlSeconds: policy.ttlSeconds,
+    maxReads: typeof policy.credentialAccess.maxReads === 'number' ? policy.credentialAccess.maxReads : null,
+    rateBudget: {
+      state: 'none',
+      requests: null,
+      windowSeconds: null,
+      source: 'none',
+    },
+  });
+  return createHash('sha256').update(stable).digest('hex');
+}
+
+export function resolveProfileToEffectivePolicy(input: ResolveProfileInput): ResolvedProfilePolicy {
+  const profile = getProfile(input.profileId, input.profileVersion || 'v1');
+  const overrides = input.overrides || {};
+
+  const profileReadScopes = canonicalScopes(profile.credentialAccess.readScopes);
+  const profileWriteScopes = canonicalScopes(profile.credentialAccess.writeScopes);
+  const profileExclude = canonicalStringList(profile.credentialAccess.excludeFields);
+
+  const overrideDelta: string[] = [];
+
+  let ttlSeconds = profile.tokenDefaults.ttlSeconds;
+  if (overrides.ttlSeconds !== undefined) {
+    if (overrides.ttlSeconds <= 0 || overrides.ttlSeconds > ttlSeconds) {
+      throw new AgentProfileError('AGENT_PROFILE_OVERRIDE_NOT_ALLOWED', 'ttlSeconds override must be positive and tighten-only');
+    }
+    ttlSeconds = overrides.ttlSeconds;
+    overrideDelta.push('ttlSeconds');
+  }
+
+  let maxReads = profile.credentialAccess.maxReads ?? profile.tokenDefaults.maxReads;
+  if (overrides.maxReads !== undefined) {
+    if (overrides.maxReads <= 0 || (typeof maxReads === 'number' && overrides.maxReads > maxReads)) {
+      throw new AgentProfileError('AGENT_PROFILE_OVERRIDE_NOT_ALLOWED', 'maxReads override must be positive and tighten-only');
+    }
+    maxReads = overrides.maxReads;
+    overrideDelta.push('maxReads');
+  }
+
+  const profilePermissions = Array.from(new Set(expandPermissions(profile.permissions))).sort();
+  const scopePermissions = overrides.scope ? Array.from(new Set(expandPermissions(overrides.scope))).sort() : profilePermissions;
+  if (overrides.scope) {
+    if (!scopePermissions.every((permission) => profilePermissions.includes(permission))) {
+      throw new AgentProfileError('AGENT_PROFILE_OVERRIDE_NOT_ALLOWED', 'scope override cannot broaden profile permissions');
+    }
+    overrideDelta.push('scope');
+  }
+
+  const readScopes = overrides.readScopes ? canonicalScopes(overrides.readScopes) : profileReadScopes;
+  const writeScopes = overrides.writeScopes ? canonicalScopes(overrides.writeScopes) : profileWriteScopes;
+
+  if (overrides.readScopes) {
+    if (!readScopes.every((scope) => profileReadScopes.includes(scope))) {
+      throw new AgentProfileError('AGENT_PROFILE_OVERRIDE_NOT_ALLOWED', 'readScopes override cannot broaden profile scope');
+    }
+    overrideDelta.push('readScopes');
+  }
+
+  if (overrides.writeScopes) {
+    if (!writeScopes.every((scope) => profileWriteScopes.includes(scope))) {
+      throw new AgentProfileError('AGENT_PROFILE_OVERRIDE_NOT_ALLOWED', 'writeScopes override cannot broaden profile scope');
+    }
+    overrideDelta.push('writeScopes');
+  }
+
+  if (readScopes.length === 0 && writeScopes.length === 0) {
+    throw new AgentProfileError('AGENT_PROFILE_SCOPE_EMPTY', 'Resolved profile selectors are empty');
+  }
+
+  const excludeFields = overrides.excludeFields ? canonicalStringList(overrides.excludeFields) : profileExclude;
+  if (overrides.excludeFields) {
+    const attemptedRemoval = profileExclude.some((field) => !excludeFields.includes(field));
+    if (attemptedRemoval) {
+      throw new AgentProfileError('AGENT_PROFILE_OVERRIDE_NOT_ALLOWED', 'excludeFields override cannot remove profile-required exclusions');
+    }
+    overrideDelta.push('excludeFields');
+  }
+
+  const resolvedBase: Omit<ResolvedProfilePolicy, 'effectivePolicyHash'> = {
+    profile: {
+      id: profile.id,
+      version: profile.version,
+      displayName: profile.displayName,
+      rationale: profile.rationale,
+    },
+    permissions: scopePermissions,
+    ttlSeconds,
+    credentialAccess: {
+      read: readScopes,
+      write: writeScopes,
+      excludeFields,
+      ...(typeof maxReads === 'number' ? { maxReads } : {}),
+    },
+    warnings: [...profile.warnings],
+    overrideDelta: Array.from(new Set(overrideDelta)).sort(),
+  };
+
+  return {
+    ...resolvedBase,
+    effectivePolicyHash: hashPolicy(resolvedBase),
+  };
+}
+
+export function summarizeEffectivePolicy(policy: ResolvedProfilePolicy): string {
+  return [
+    `${policy.profile.id}@${policy.profile.version}`,
+    `permissions=${policy.permissions.join(',')}`,
+    `ttl=${policy.ttlSeconds}s`,
+    `read=${(policy.credentialAccess.read || []).join(',') || 'none'}`,
+    `write=${(policy.credentialAccess.write || []).join(',') || 'none'}`,
+  ].join(' | ');
+}
+
+// ---------------------------------------------------------------------------
+// Human-readable profile/policy descriptions
+// ---------------------------------------------------------------------------
+
+const PERMISSION_DESCRIPTIONS: Record<string, string> = {
+  'swap': 'Swap tokens via DEX',
+  'send:hot': 'Send from hot wallets',
+  'send:temp': 'Send from temp wallets',
+  'fund': 'Transfer cold → hot',
+  'launch': 'Launch tokens',
+  'wallet:create:hot': 'Create hot wallets',
+  'wallet:create:temp': 'Create temp wallets',
+  'wallet:export': 'Export private keys',
+  'wallet:list': 'List wallets',
+  'wallet:rename': 'Rename wallets',
+  'wallet:write': 'Modify wallets',
+  'wallet:tx:add': 'Add transactions',
+  'wallet:asset:add': 'Add assets',
+  'wallet:asset:remove': 'Remove assets',
+  'secret:read': 'Read credentials',
+  'secret:write': 'Write credentials',
+  'totp:read': 'Read TOTP codes',
+  'action:create': 'Create action requests',
+  'action:read': 'View action requests',
+  'action:resolve': 'Approve/reject requests',
+  'apikey:get': 'Read API keys',
+  'apikey:set': 'Manage API keys',
+  'workspace:modify': 'Modify workspace',
+  'strategy:read': 'View strategies',
+  'strategy:manage': 'Manage strategies',
+  'app:storage': 'App storage',
+  'app:storage:all': 'Full app storage',
+  'app:accesskey': 'App access keys',
+  'adapter:manage': 'Manage adapters',
+  'addressbook:write': 'Modify address book',
+  'bookmark:write': 'Modify bookmarks',
+  'trade:all': 'All trading operations',
+  'extension:*': 'All extensions',
+  'admin:*': 'Full admin access',
+};
+
+function formatTtlReadable(seconds: number): string {
+  if (seconds < 60) return `${seconds} seconds`;
+  if (seconds < 3600) return `${Math.floor(seconds / 60)} minutes`;
+  const hours = Math.floor(seconds / 3600);
+  return hours === 1 ? '1 hour' : `${hours} hours`;
+}
+
+function describeScopes(scopes: string[]): string {
+  if (scopes.length === 0) return 'None';
+  if (scopes.includes('*')) return 'All credentials';
+  if (scopes.length === 1 && scopes[0] === 'vault:*') return 'All vaults';
+  return scopes.map((s) => {
+    if (s.startsWith('vault:')) return `Vault "${s.slice(6)}"`;
+    if (s.startsWith('tag:')) return `Tag "${s.slice(4)}"`;
+    return s;
+  }).join(', ');
+}
+
+export interface ProfileDescription {
+  name: string;
+  summary: string;
+  permissions: string[];
+  vaultAccess: string;
+  canWrite: boolean;
+  hiddenFields: string[];
+  ttl: string;
+  maxReads: string;
+  warnings: string[];
+}
+
+export function describeProfile(profileId: string, version: string = 'v1'): ProfileDescription {
+  const profile = getProfile(profileId, version);
+  return describeProfilePolicy(profile);
+}
+
+export function describeProfilePolicy(profile: AgentPolicyProfileV1): ProfileDescription {
+  const permissions = profile.permissions.map((p) => PERMISSION_DESCRIPTIONS[p] || p);
+  const readScopes = profile.credentialAccess.readScopes;
+  const writeScopes = profile.credentialAccess.writeScopes;
+  const canWrite = writeScopes.length > 0;
+  const vaultAccess = describeScopes(readScopes);
+  const hiddenFields = profile.credentialAccess.excludeFields;
+  const ttl = formatTtlReadable(profile.tokenDefaults.ttlSeconds);
+  const maxReads = profile.credentialAccess.maxReads
+    ? `${profile.credentialAccess.maxReads} reads`
+    : 'Unlimited';
+
+  const parts: string[] = [];
+  parts.push(profile.description);
+  if (canWrite) {
+    parts.push(`Read/write access to ${vaultAccess.toLowerCase()}.`);
+  } else {
+    parts.push(`Read-only access to ${vaultAccess.toLowerCase()}.`);
+  }
+  if (hiddenFields.length > 0) {
+    parts.push(`Hidden fields: ${hiddenFields.join(', ')}.`);
+  }
+  parts.push(`Expires after ${ttl}.`);
+
+  return {
+    name: profile.displayName,
+    summary: parts.join(' '),
+    permissions,
+    vaultAccess,
+    canWrite,
+    hiddenFields,
+    ttl,
+    maxReads,
+    warnings: profile.warnings,
+  };
+}
+
+export function describeResolvedPolicy(policy: ResolvedProfilePolicy): ProfileDescription {
+  const permissions = policy.permissions.map((p) => PERMISSION_DESCRIPTIONS[p] || p);
+  const readScopes = policy.credentialAccess.read || [];
+  const writeScopes = policy.credentialAccess.write || [];
+  const canWrite = writeScopes.length > 0;
+  const vaultAccess = describeScopes(readScopes);
+  const hiddenFields = policy.credentialAccess.excludeFields || [];
+  const ttl = formatTtlReadable(policy.ttlSeconds);
+  const maxReads = typeof policy.credentialAccess.maxReads === 'number'
+    ? `${policy.credentialAccess.maxReads} reads`
+    : 'Unlimited';
+
+  const parts: string[] = [];
+  if (canWrite) {
+    parts.push(`Read/write access to ${vaultAccess.toLowerCase()}.`);
+  } else {
+    parts.push(`Read-only access to ${vaultAccess.toLowerCase()}.`);
+  }
+  if (hiddenFields.length > 0) {
+    parts.push(`Hidden fields: ${hiddenFields.join(', ')}.`);
+  }
+  parts.push(`Expires after ${ttl}.`);
+
+  return {
+    name: policy.profile.displayName,
+    summary: parts.join(' '),
+    permissions,
+    vaultAccess,
+    canWrite,
+    hiddenFields,
+    ttl,
+    maxReads,
+    warnings: policy.warnings,
+  };
+}

package/server/lib/ai.ts

@@ -0,0 +1,285 @@
+/**
+ * AI Client Module
+ * ================
+ * Multi-provider AI abstraction supporting:
+ *   - Claude CLI (subscription/OAuth via `claude` binary)
+ *   - Claude API (direct Anthropic SDK with API key)
+ *   - Codex CLI (OpenAI's `codex` binary)
+ *   - OpenAI API (direct OpenAI SDK with API key)
+ *
+ * Provider selection read from system defaults (ai.provider); model auto-derived per provider.
+ * Extracted from strategy/hooks.ts so it's reusable beyond strategies.
+ */
+
+import Anthropic from '@anthropic-ai/sdk';
+import OpenAI from 'openai';
+import { execFile } from 'child_process';
+import {
+  ensureApiKeysMigrated,
+  hasActiveApiKeyCredential,
+  readApiKeyValueByService,
+} from './apikey-migration';
+import { getDefault, onDefaultChanged } from './defaults';
+
+// ─── Types ─────────────────────────────────────────────────────────
+
+export type AiProviderMode = 'claude-cli' | 'claude-api' | 'codex-cli' | 'openai-api';
+
+export type ModelTier = 'fast' | 'standard' | 'powerful';
+
+export interface ProviderStatus {
+  mode: AiProviderMode;
+  label: string;
+  available: boolean;
+  reason: string;
+  models: string[];
+}
+
+// ─── Model Maps ────────────────────────────────────────────────────
+
+/** Claude model short names → full SDK model IDs */
+const MODEL_MAP: Record<string, string> = {
+  haiku: 'claude-haiku-4-5-20251001',
+  sonnet: 'claude-sonnet-4-5-20250929',
+  opus: 'claude-opus-4-6',
+};
+
+/** Codex/OpenAI model short names → full SDK model IDs */
+const CODEX_MODEL_MAP: Record<string, string> = {
+  'codex-mini': 'gpt-5.1-codex-mini',
+  'codex': 'gpt-5.3-codex',
+  'codex-max': 'gpt-5.1-codex-max',
+};
+
+/** Available models per provider */
+export const PROVIDER_MODELS: Record<AiProviderMode, string[]> = {
+  'claude-cli': ['haiku', 'sonnet', 'opus'],
+  'claude-api': ['haiku', 'sonnet', 'opus'],
+  'codex-cli': ['codex-mini', 'codex', 'codex-max'],
+  'openai-api': ['codex-mini', 'codex', 'codex-max'],
+};
+
+/** Model tiers per provider — fast/standard/powerful mapped to model short names */
+export const MODEL_TIERS: Record<AiProviderMode, Record<ModelTier, string>> = {
+  'claude-cli':  { fast: 'haiku', standard: 'sonnet', powerful: 'opus' },
+  'claude-api':  { fast: 'haiku', standard: 'sonnet', powerful: 'opus' },
+  'codex-cli':   { fast: 'codex-mini', standard: 'codex', powerful: 'codex-max' },
+  'openai-api':  { fast: 'codex-mini', standard: 'codex', powerful: 'codex-max' },
+};
+
+/** Permissions that trigger the 'powerful' tier (financial operations) */
+const POWERFUL_PERMISSIONS = new Set(['swap', 'send:hot', 'send:temp', 'fund', 'launch', 'admin:*']);
+
+/** Permissions that trigger the 'standard' tier (write operations) */
+const STANDARD_PERMISSIONS = new Set(['wallet:create:hot', 'wallet:create:temp']);
+
+/**
+ * Select a model tier based on hook name and token permissions.
+ * - init/shutdown → fast (lightweight lifecycle hooks)
+ * - Financial or admin permissions → powerful
+ * - Write permissions → standard
+ * - No token or read-only → fast
+ */
+export function selectModelTier(hookName: string, permissions: string[]): ModelTier {
+  // Lifecycle hooks always use fast tier
+  if (hookName === 'init' || hookName === 'shutdown') return 'fast';
+
+  // Check for powerful-tier permissions
+  for (const perm of permissions) {
+    if (POWERFUL_PERMISSIONS.has(perm)) return 'powerful';
+  }
+
+  // Check for standard-tier permissions
+  for (const perm of permissions) {
+    if (STANDARD_PERMISSIONS.has(perm)) return 'standard';
+  }
+
+  // No token or read-only permissions
+  return 'fast';
+}
+
+// ─── Cached Clients ────────────────────────────────────────────────
+
+let cachedAnthropicClient: Anthropic | null = null;
+let cachedOpenAiClient: OpenAI | null = null;
+
+/** @internal Reset cached clients (for testing only) */
+export function __resetCachedClient() {
+  cachedAnthropicClient = null;
+  cachedOpenAiClient = null;
+}
+
+// Reset cached clients when provider changes
+onDefaultChanged('ai.provider', () => {
+  cachedAnthropicClient = null;
+  cachedOpenAiClient = null;
+});
+
+// ─── Provider & Model Selection ────────────────────────────────────
+
+/**
+ * Get the active AI provider mode from system defaults.
+ */
+export async function getProviderMode(): Promise<AiProviderMode> {
+  return getDefault<AiProviderMode>('ai.provider', 'claude-cli');
+}
+
+/**
+ * Get the system-wide default model (standard tier), derived from the active provider.
+ */
+export async function getDefaultModel(): Promise<string> {
+  const provider = await getProviderMode();
+  return MODEL_TIERS[provider].standard;
+}
+
+/**
+ * Resolve a model short name to the full SDK model ID based on provider.
+ * CLI modes return the short name directly (CLIs handle them natively).
+ * API modes map to full model IDs.
+ */
+export function resolveModelId(name: string, provider: AiProviderMode): string {
+  switch (provider) {
+    case 'claude-cli':
+      return name; // Claude CLI handles short names natively
+    case 'claude-api':
+      return MODEL_MAP[name] || name;
+    case 'codex-cli':
+      return name; // Codex CLI handles short names natively
+    case 'openai-api':
+      return CODEX_MODEL_MAP[name] || name;
+    default:
+      return name;
+  }
+}
+
+// ─── SDK Clients ───────────────────────────────────────────────────
+
+/**
+ * Get an Anthropic SDK client (for claude-api mode).
+ * Priority: ANTHROPIC_API_KEY env → vault API key credential (service: 'anthropic').
+ */
+export async function getAnthropicClient(): Promise<Anthropic> {
+  if (cachedAnthropicClient) return cachedAnthropicClient;
+
+  if (process.env.ANTHROPIC_API_KEY) {
+    cachedAnthropicClient = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+    return cachedAnthropicClient;
+  }
+
+  await ensureApiKeysMigrated();
+  const apiKey = readApiKeyValueByService('anthropic');
+  if (apiKey) {
+    cachedAnthropicClient = new Anthropic({ apiKey });
+    return cachedAnthropicClient;
+  }
+
+  throw new Error(
+    'No Anthropic credentials found. Add an API key via Settings, set ANTHROPIC_API_KEY, or use Claude CLI mode (subscription).'
+  );
+}
+
+/**
+ * Get an OpenAI SDK client (for openai-api mode).
+ * Priority: OPENAI_API_KEY env → vault API key credential (service: 'openai').
+ */
+export async function getOpenAiClient(): Promise<OpenAI> {
+  if (cachedOpenAiClient) return cachedOpenAiClient;
+
+  if (process.env.OPENAI_API_KEY) {
+    cachedOpenAiClient = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+    return cachedOpenAiClient;
+  }
+
+  await ensureApiKeysMigrated();
+  const apiKey = readApiKeyValueByService('openai');
+  if (apiKey) {
+    cachedOpenAiClient = new OpenAI({ apiKey });
+    return cachedOpenAiClient;
+  }
+
+  throw new Error(
+    'No OpenAI credentials found. Add an API key via Settings or set OPENAI_API_KEY.'
+  );
+}
+
+// ─── Provider Status ───────────────────────────────────────────────
+
+/** Check if a CLI binary is available in PATH */
+function checkCliAvailable(binary: string): Promise<boolean> {
+  return new Promise((resolve) => {
+    execFile('which', [binary], (err) => {
+      resolve(!err);
+    });
+  });
+}
+
+/** Check if an API key exists for a service (env or vault credential) */
+async function hasApiKey(service: string, envVar: string): Promise<boolean> {
+  if (process.env[envVar]) return true;
+  await ensureApiKeysMigrated();
+  return hasActiveApiKeyCredential(service);
+}
+
+/**
+ * Get availability status for each provider.
+ * Used by the dashboard UI to show status indicators.
+ */
+export async function getProviderStatus(): Promise<ProviderStatus[]> {
+  const [claudeCliOk, codexCliOk, anthropicKeyOk, openaiKeyOk] = await Promise.all([
+    checkCliAvailable('claude'),
+    checkCliAvailable('codex'),
+    hasApiKey('anthropic', 'ANTHROPIC_API_KEY'),
+    hasApiKey('openai', 'OPENAI_API_KEY'),
+  ]);
+
+  return [
+    {
+      mode: 'claude-cli',
+      label: 'Claude Max (CLI)',
+      available: claudeCliOk,
+      reason: claudeCliOk ? 'claude CLI found in PATH' : 'claude CLI not found in PATH',
+      models: PROVIDER_MODELS['claude-cli'],
+    },
+    {
+      mode: 'claude-api',
+      label: 'Claude API Key',
+      available: anthropicKeyOk,
+      reason: anthropicKeyOk ? 'Anthropic API key configured' : 'No Anthropic API key configured',
+      models: PROVIDER_MODELS['claude-api'],
+    },
+    {
+      mode: 'codex-cli',
+      label: 'Codex Max (CLI)',
+      available: codexCliOk,
+      reason: codexCliOk ? 'codex CLI found in PATH' : 'codex CLI not found in PATH',
+      models: PROVIDER_MODELS['codex-cli'],
+    },
+    {
+      mode: 'openai-api',
+      label: 'OpenAI API Key',
+      available: openaiKeyOk,
+      reason: openaiKeyOk ? 'OpenAI API key configured' : 'No OpenAI API key configured',
+      models: PROVIDER_MODELS['openai-api'],
+    },
+  ];
+}
+
+// ─── Backward Compatibility ────────────────────────────────────────
+
+/**
+ * @deprecated Use getProviderMode() instead.
+ * Kept temporarily for backward compatibility.
+ */
+export async function shouldUseCli(): Promise<boolean> {
+  const mode = await getProviderMode();
+  return mode === 'claude-cli' || mode === 'codex-cli';
+}
+
+/**
+ * @deprecated Use getProviderMode() instead.
+ * Returns 'sdk' if provider uses direct API, 'cli' otherwise.
+ */
+export async function getAiProvider(): Promise<'sdk' | 'cli'> {
+  const mode = await getProviderMode();
+  return (mode === 'claude-api' || mode === 'openai-api') ? 'sdk' : 'cli';
+}