elanous 0.2.0 → 0.2.4

package/src/llm/provider-detect.ts

@@ -0,0 +1,247 @@
+import { access, readFile, stat } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { delimiter, join } from 'node:path';
+import { homedir } from 'node:os';
+import { execFile } from 'node:child_process';
+import { authStorePath } from '../oauth/store.js';
+import { envLiteral } from '../platform/env-literal.js';
+
+/** Discovery is read-only; agent-cli entries are not direct-call LLM providers. */
+export interface DetectedProvider {
+  provider: string;
+  auth: 'oauth' | 'apikey' | 'local' | 'agent-cli';
+  source: string;
+  available: boolean;
+  rank: number;
+  agent?: { cli: 'claude' | 'agy'; loggedIn: boolean | null; storedLoggedIn?: boolean | null; method?: string; via: string };
+}
+
+export interface ProviderDetectDeps {
+  env?: NodeJS.ProcessEnv;
+  home?: string;
+  /** elanous auth store path; default = the shared `authStorePath()` (no home-relative literal here — isolation gate). */
+  authStore?: string;
+  readFile?: (path: string) => Promise<string>;
+  access?: (path: string) => Promise<boolean>;
+  isFile?: (path: string) => Promise<boolean>;
+  isDirectory?: (path: string) => Promise<boolean>;
+  runCli?: (args: string[], options: { timeoutMs: number; env: NodeJS.ProcessEnv }) => Promise<string>;
+  now?: () => number;
+}
+
+const LIMIT_MS = 3_000;
+const CLAUDE_LIMIT_MS = 5_000;
+const ORDER = ['openai-codex', 'anthropic', 'grok', 'gemini', 'openrouter', 'openai', 'ollama', 'local'] as const;
+const AGENT_RANK = { 'claude-code': -2, antigravity: -1 } as const;
+const SOURCE_PRIORITY: Readonly<Record<string, number>> = {
+  'elanous-auth': 0,
+  'codex-auth': 1,
+  'gemini-auth': 1,
+  'grok-auth': 1,
+};
+const ENV_KEYS: Readonly<Record<string, readonly string[]>> = {
+  anthropic: ['ANTHROPIC_API_KEY'],
+  grok: ['XAI_API_KEY', 'GROK_API_KEY', 'GROK_CODE_XAI_API_KEY'],
+  gemini: ['GEMINI_API_KEY', 'GOOGLE_API_KEY'],
+  openrouter: ['OPENROUTER_API_KEY'],
+  openai: ['OPENAI_API_KEY'],
+};
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? value as Record<string, unknown> : null;
+}
+
+function populated(value: unknown): boolean {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function oauthUsable(value: unknown, now: number): boolean {
+  const state = record(value);
+  if (!state) return false;
+  const tokens = record(state.tokens) ?? state;
+  const accessToken = tokens.accessToken ?? tokens.access_token;
+  const refreshToken = tokens.refreshToken ?? tokens.refresh_token;
+  if (populated(refreshToken)) return true;
+  if (!populated(accessToken)) return false;
+  const rawExpiry = tokens.expiresAt ?? tokens.expires_at;
+  if (rawExpiry === undefined || rawExpiry === null) return true;
+  const expiry = typeof rawExpiry === 'string' ? Date.parse(rawExpiry) : rawExpiry;
+  return typeof expiry === 'number' && Number.isFinite(expiry) && expiry > now;
+}
+
+/** Claude status is queried via the official CLI; no keychain call or credential-file read/write is performed. */
+export async function detectProviders(deps: ProviderDetectDeps = {}): Promise<DetectedProvider[]> {
+  const env = deps.env ?? process.env;
+  const home = deps.home ?? env.HOME ?? homedir();
+  const clock = deps.now ?? Date.now;
+  const started = clock();
+  const file = deps.readFile ?? ((path: string) => readFile(path, 'utf8'));
+  const executable = deps.access ?? (async (path: string) => {
+    try { await access(path, constants.X_OK); return true; } catch { return false; }
+  });
+  const isFile = deps.isFile ?? (async (path: string) => {
+    try { return (await stat(path)).isFile(); } catch { return false; }
+  });
+  const isDirectory = deps.isDirectory ?? (async (path: string) => {
+    try { return (await stat(path)).isDirectory(); } catch { return false; }
+  });
+  const runCli = deps.runCli ?? ((args: string[], options: { timeoutMs: number; env: NodeJS.ProcessEnv }) => new Promise<string>((resolve, reject) => {
+    execFile('claude', args, { timeout: options.timeoutMs, maxBuffer: 64 * 1024, env: options.env }, (error, stdout) => {
+      if (error) reject(error);
+      else resolve(stdout);
+    });
+  }));
+  const claudeStatus = (statusEnv: NodeJS.ProcessEnv) => new Promise<Record<string, unknown> | null>((resolve) => {
+    const timer = setTimeout(() => resolve(null), CLAUDE_LIMIT_MS);
+    void Promise.resolve().then(() => runCli(['auth', 'status', '--json'], { timeoutMs: CLAUDE_LIMIT_MS, env: statusEnv }))
+      .then((value) => {
+        clearTimeout(timer);
+        try { resolve(record(JSON.parse(value) as unknown)); } catch { resolve(null); }
+      }, () => { clearTimeout(timer); resolve(null); });
+  });
+  const storedEnv = Object.fromEntries(Object.entries(env).filter(([name]) =>
+    name !== 'CLAUDE_CODE_OAUTH_TOKEN' && name !== 'CLAUDECODE' &&
+    name !== 'CLAUDE_CODE_ENTRYPOINT' && name !== 'ANTHROPIC_AUTH_TOKEN' &&
+    name !== 'ANTHROPIC_API_KEY' &&
+    !name.startsWith('CLAUDE_CODE_SESSION_'),
+  ));
+  const found = new Map<string, DetectedProvider>();
+  let accepting = true;
+  const add = (provider: string, auth: DetectedProvider['auth'], source: string) => {
+    if (!accepting || clock() - started >= LIMIT_MS) return;
+    const rank = ORDER.indexOf(provider as typeof ORDER[number]);
+    if (rank < 0) return;
+    const candidate = { provider, auth, source, available: true, rank: rank * 2 + (auth === 'apikey' ? 1 : 0) };
+    const previous = found.get(provider);
+    if (!previous || candidate.rank < previous.rank ||
+        (candidate.rank === previous.rank &&
+          (SOURCE_PRIORITY[source] ?? 2) < (SOURCE_PRIORITY[previous.source] ?? 2))) {
+      found.set(provider, candidate);
+    }
+  };
+  const agentEvidence = { cli: false, statusValid: false, credentials: false, env: [] as string[], loggedIn: null as boolean | null, storedLoggedIn: null as boolean | null, method: undefined as string | undefined };
+  const updateClaude = () => {
+    if (!accepting || clock() - started >= LIMIT_MS) return;
+    if (!agentEvidence.cli && !agentEvidence.credentials && agentEvidence.env.length === 0) return;
+    const source = agentEvidence.statusValid ? 'claude-auth-status'
+      : agentEvidence.credentials ? 'credentials-file'
+      : agentEvidence.env.length > 0 ? `env:${agentEvidence.env[0]}` : 'path:claude';
+    const via = [
+      ...(agentEvidence.statusValid ? ['claude-auth-status'] : agentEvidence.cli ? ['path:claude'] : []),
+      ...(agentEvidence.credentials ? ['credentials-file'] : []),
+      ...agentEvidence.env.map((name) => `env:${name}`),
+    ].join(', ');
+    found.set('claude-code', {
+      provider: 'claude-code', auth: 'agent-cli', source,
+      available: agentEvidence.loggedIn === true, rank: AGENT_RANK['claude-code'],
+      agent: { cli: 'claude', loggedIn: agentEvidence.loggedIn, storedLoggedIn: agentEvidence.storedLoggedIn,
+        ...(agentEvidence.method ? { method: agentEvidence.method } : {}), via },
+    });
+  };
+  const json = async (path: string): Promise<Record<string, unknown> | null> => {
+    try { return record(JSON.parse(await file(path)) as unknown); } catch { return null; }
+  };
+  const inspect = async () => {
+    // Read stores concurrently so a slow or unreadable store cannot hide the others.
+    const storePath = env.XDG_CONFIG_HOME?.trim()
+      ? join(env.XDG_CONFIG_HOME, 'elanous', 'auth.json')
+      : deps.authStore ?? authStorePath();
+    for (const [provider, keys] of Object.entries(ENV_KEYS)) {
+      const key = keys.find((name) => populated(env[name]));
+      if (key) add(provider, 'apikey', `env:${key}`);
+    }
+    if (populated(env.LOCAL_LLM_URL)) add('local', 'local', 'env:LOCAL_LLM_URL');
+    for (const name of ['CLAUDE_CODE_OAUTH_TOKEN', 'ANTHROPIC_AUTH_TOKEN']) {
+      if (populated(env[name])) agentEvidence.env.push(name);
+    }
+    updateClaude();
+    const agyInstall = Promise.resolve().then(() => isDirectory(join(home, '.gemini', 'antigravity-cli'))).catch(() => false);
+    const files = [
+      json(storePath).then((store) => {
+        const providers = record(store?.providers);
+        if (!providers) return;
+        for (const [name, state] of Object.entries(providers)) {
+          const provider = name.startsWith('openai-codex:') ? 'openai-codex' : name;
+          if (oauthUsable(state, clock())) add(provider, 'oauth', 'elanous-auth');
+        }
+      }),
+      json(join(env.CODEX_HOME?.trim() || join(home, '.codex'), 'auth.json')).then((codex) => {
+        if (oauthUsable(codex?.tokens, clock())) add('openai-codex', 'oauth', 'codex-auth');
+      }),
+      Promise.resolve().then(() => isFile(join(env.CLAUDE_CONFIG_DIR?.trim() || join(home, '.claude'), '.credentials.json'))).then((exists) => {
+        if (exists) { agentEvidence.credentials = true; updateClaude(); }
+      }).catch(() => {}),
+      json(join(home, '.gemini', 'oauth_creds.json')).then((gemini) => {
+        if (oauthUsable(gemini, clock())) add('gemini', 'oauth', 'gemini-auth');
+      }),
+      json(join(home, '.grok', 'auth.json')).then((grok) => {
+        if (grok && Object.values(grok).some((entry) => {
+          const scope = record(entry);
+          if (!scope) return false;
+          if (populated(scope.refresh_token)) return true;
+          if (!populated(scope.key)) return false;
+          if (scope.expires_at === undefined || scope.expires_at === null) return true;
+          const expiry = typeof scope.expires_at === 'string' ? Date.parse(scope.expires_at) : scope.expires_at;
+          return typeof expiry === 'number' && Number.isFinite(expiry) && expiry > clock();
+        })) add('grok', 'oauth', 'grok-auth');
+      }),
+    ];
+    const dirs = (env.PATH ?? '').split(delimiter).filter(Boolean);
+    const onPath = (name: string) => new Promise<boolean>((resolve) => {
+      let pending = dirs.length;
+      if (!pending) resolve(false);
+      for (const dir of dirs) {
+        const path = join(dir, name);
+        void Promise.resolve().then(async () =>
+          (await executable(path)) && (await isFile(path)),
+        ).then(
+          (available) => {
+            if (available) resolve(true);
+            else if (--pending === 0) resolve(false);
+          },
+          () => { if (--pending === 0) resolve(false); },
+        );
+      }
+    });
+    const pathChecks = [
+      onPath('ollama').then((exists) => { if (exists) add('ollama', 'local', 'path:ollama'); }),
+      onPath('claude').then(async (exists) => {
+        if (!exists || !accepting) return;
+        agentEvidence.cli = true;
+        updateClaude();
+        const [status, storedStatus] = await Promise.all([claudeStatus(env), claudeStatus(envLiteral(storedEnv))]);
+        if (!accepting) return;
+        if (typeof status?.loggedIn === 'boolean') {
+          agentEvidence.statusValid = true;
+          agentEvidence.loggedIn = status.loggedIn;
+          if (status.authMethod === 'claude.ai' || status.authMethod === 'oauth_token' ||
+              status.authMethod === 'api_key') agentEvidence.method = status.authMethod;
+        }
+        if (typeof storedStatus?.loggedIn === 'boolean') agentEvidence.storedLoggedIn = storedStatus.loggedIn;
+        updateClaude();
+      }),
+      Promise.all([onPath('agy'), agyInstall]).then(([cli, installed]) => {
+        if (cli && installed && accepting && clock() - started < LIMIT_MS) found.set('antigravity', {
+          provider: 'antigravity', auth: 'agent-cli', source: 'agy-install', available: true,
+          rank: AGENT_RANK.antigravity, agent: { cli: 'agy', loggedIn: null, via: 'install-dir' },
+        });
+      }),
+    ];
+    await Promise.all([...files, ...pathChecks]);
+    return [...found.values()].sort((a, b) => a.rank - b.rank);
+  };
+  // A wall-clock timer bounds even a dependency that never settles. Late reads cannot change the returned snapshot.
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    return await Promise.race([
+      inspect(),
+      new Promise<DetectedProvider[]>((resolve) => {
+        timer = setTimeout(() => resolve([...found.values()].sort((a, b) => a.rank - b.rank)), LIMIT_MS);
+      }),
+    ]);
+  } finally {
+    accepting = false;
+    if (timer) clearTimeout(timer);
+  }
+}

package/src/llm/provider-probe.ts

@@ -0,0 +1,57 @@
+import type { LLMProvider } from '../llm.js';
+
+export interface ProviderProbeResult {
+  success: boolean;
+  durationMs: number;
+  model: string;
+  error?: string;
+}
+
+export interface ProviderProbeOptions {
+  timeoutMs?: number;
+}
+
+const PROBE_PROMPT = 'Reply with OK.';
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+/** Make one bounded, tool-free request without exposing response text or provider errors. */
+export async function probeProvider(
+  provider: LLMProvider,
+  options: ProviderProbeOptions = {},
+): Promise<ProviderProbeResult> {
+  const started = performance.now();
+  const model = provider.defaultModel;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const controller = new AbortController();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let timedOut = false;
+  const request = (async () => {
+    let receivedText = false;
+    for await (const chunk of provider.chat(
+      [{ role: 'user', content: PROBE_PROMPT }],
+      { model, maxTokens: 16, tools: [], toolChoice: 'none', signal: controller.signal },
+    )) {
+      if (chunk.length > 0) receivedText = true;
+    }
+    return receivedText;
+  })();
+  try {
+    const receivedText = await Promise.race([
+      request,
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(() => {
+          timedOut = true;
+          controller.abort();
+          reject(new Error('timeout'));
+        }, timeoutMs);
+      }),
+    ]);
+    return receivedText
+      ? { success: true, durationMs: performance.now() - started, model }
+      : { success: false, durationMs: performance.now() - started, model, error: 'empty response' };
+  } catch {
+    return { success: false, durationMs: performance.now() - started, model, error: timedOut ? 'timeout' : 'probe failed' };
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}

package/src/llm.ts

@@ -4,6 +4,7 @@
 
 import { createHash } from 'node:crypto';
 import type { LLMUsage } from './prompt-cache/types.js';
+import type { ModelRole } from './user-config.js';
 // ⭐ grok 자격 해석 — 구독(OAuth) 1순위 · API 키 2순위. ACP 경로와 «같은» 규칙.
 import { isGrokUnauthorized, refreshGrokSubscriptionToken, resolveFreshGrokCredential, resolveGrokCredential } from './grok/credential.js';
 import {
@@ -323,7 +324,9 @@ export interface LLMOpts {
   signal?: AbortSignal;
   /** Optional per-request usage telemetry from the provider stream. */
   onUsage?(usage: LLMUsage): void;
-    /**
+  /** Optional model role attached to this request's usage observation. */
+  usageRole?: ModelRole;
+  /**
    * ⭐⭐⭐ `B3`(2026-08-19 · 대표 지시 ②) — ***턴 «안»으로 들어오는 사용자 발화의 배수구.***
    *
    * 대표: *"큐잉된게 설계된 타이밍에 들어가서 인터럽트? 비슷한게 걸리면서 기존 작업을 트리아지 해야"*
@@ -3870,8 +3873,7 @@ export const PROVIDERS: Record<string, LLMProvider> = {
   anthropic: AnthropicProvider,
   local: LocalProvider,
   gemini: GeminiProvider,
-  // 대표 2026-09-23 — codex 처럼 «팩토리를 감싼» 항목. ⛔ 자동 폴백 후보(AUTOMATIC_PROVIDER_ORDER)엔 «없다» —
-  //   과금 경로라 명시 선택(config·`openrouter/` 모델·`--role-llm`)으로만 온다.
+  // OpenRouter is considered for auto selection only after subscription and other key candidates.
   openrouter: {
     name: 'openrouter',
     get defaultModel() { return OPENROUTER_MODEL; },
@@ -3882,7 +3884,7 @@ export const PROVIDERS: Record<string, LLMProvider> = {
 };
 
 const AUTOMATIC_PROVIDER_ORDER = ['grok', 'anthropic', 'gemini', 'local'] as const;
-const PROVIDER_DECISION_ORDER = ['grok', 'anthropic', 'openai', 'gemini', 'local'] as const;
+const PROVIDER_DECISION_ORDER = ['grok', 'anthropic', 'openai', 'gemini', 'local', 'openrouter'] as const;
 const SUBSCRIPTION_DECISION_ORDER = ['openai-codex', 'grok'] as const;
 
 type AutomaticProviderName = typeof AUTOMATIC_PROVIDER_ORDER[number];
@@ -3940,6 +3942,17 @@ function providerDecisionCandidates(): Array<LLMProvider & { name: ProviderDecis
   return PROVIDER_DECISION_ORDER.map((name) => PROVIDERS[name]! as LLMProvider & { name: ProviderDecisionName });
 }
 
+function codexOAuthAvailable(): boolean {
+  try {
+    const account = resolveCodexAccount(process.env, { storedHome: (key) => loadTokens(key)?.codexHome });
+    if (loadTokens(account.storeKey)) return true;
+    const home = effectiveCodexHome(account, null, process.env).home;
+    return !!home && readCodexMirrorTokens(join(home, 'auth.json')) !== null;
+  } catch {
+    return false;
+  }
+}
+
 function subscriptionDecision(): ProviderDecision | undefined {
   for (const provider of SUBSCRIPTION_DECISION_ORDER) {
     const model = defaultModelForProvider(provider);
@@ -4035,7 +4048,7 @@ export function decideProviderForConfig(
   const selectedModel = modelHint || configModel || defaultModelForProvider(provider);
   switch (provider) {
     case 'openai-codex':
-      return { provider, model: selectedModel, auth: loadTokens('openai-codex') ? 'oauth' : apiKey ? 'apikey' : 'none' };
+      return { provider, model: selectedModel, auth: codexOAuthAvailable() ? 'oauth' : apiKey ? 'apikey' : 'none' };
     case 'grok':
       return { provider, model: selectedModel, auth: authKindForProvider('grok', selectedModel, apiKey) };
     case 'openai':
@@ -4070,7 +4083,7 @@ function authKindForProvider(provider: string, model: string, apiKey?: string):
   if (provider === 'openrouter') return getOpenRouterApiKey() ? 'apikey' : 'none';
   if (provider === 'openai-codex') {
     try {
-      return loadTokens('openai-codex') ? 'oauth' : 'none';
+      return codexOAuthAvailable() ? 'oauth' : 'none';
     } catch {
       return 'none';
     }
@@ -4200,13 +4213,14 @@ export function getProvider(model?: string): LLMProvider {
     // ids (e.g. `claude-opus-4-7`) so prefix matching works. Existing
     // full ids pass through unchanged.
     const resolved = resolveModelAlias(model) ?? model;
-    const m = resolved.toLowerCase();
-    if (m.startsWith('local:')) return LocalProvider;
-    if (m.startsWith('gpt-') || m.startsWith('o1-') || m.startsWith('o3-') || m.startsWith('o4-')) return OpenAIProvider;
-    if (m.startsWith('claude-')) return AnthropicProvider;
-    if (m.startsWith('grok-')) return GrokProvider;
-    if (m.startsWith('gemini-')) return GeminiProvider;
-    if (m.startsWith('openrouter/')) return PROVIDERS.openrouter!;
+    // Preserve the historical Chat Completions route for gpt-* model-only
+    // requests, including future ids that the current catalog does not list.
+    if (resolved.toLowerCase().startsWith('gpt-')) return PROVIDERS.openai!;
+    const adapted = inferProviderFromModel(resolved);
+    if (adapted === 'openai-codex') return PROVIDERS['openai-codex']!;
+    const inferred = registryInferProviderFromModel(resolved);
+    if (inferred && PROVIDERS[inferred]) return PROVIDERS[inferred]!;
+    if (adapted && PROVIDERS[adapted]) return PROVIDERS[adapted]!;
     // Unknown prefix — look up by exact name match on defaults
     for (const p of Object.values(PROVIDERS)) {
       if (p.defaultModel === resolved) return p;
@@ -4236,8 +4250,9 @@ export function getProvider(model?: string): LLMProvider {
   for (const p of automaticProviderCandidates()) {
     if (p.available()) return p;
   }
+  if (PROVIDERS.openrouter!.available()) return PROVIDERS.openrouter!;
 
-  throw new Error(noProviderAvailableMessage());
+  throw new NoLlmProviderAvailableError();
 }
 
 /**
@@ -4246,9 +4261,16 @@ export function getProvider(model?: string): LLMProvider {
  * codex 구독을 «자동 후보로 안 쓰는» 경로라, codex 로그인이 «있는» 사람이 가장 먼저
  * 여기 떨어진다 — 그 사람에게 필요한 것은 키가 아니라 provider 한 줄이다.
  */
+export class NoLlmProviderAvailableError extends Error {
+  constructor() {
+    super(noProviderAvailableMessage());
+    this.name = 'NoLlmProviderAvailableError';
+  }
+}
+
 export function noProviderAvailableMessage(): string {
   const head = 'No LLM provider available.';
-  const keys = 'XAI_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, or LOCAL_LLM_URL';
+  const keys = 'XAI_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, OPENROUTER_API_KEY, or LOCAL_LLM_URL';
   let codexOauth = false;
   try {
     codexOauth = authKindForProvider('openai-codex', defaultModelForProvider('openai-codex')) === 'oauth';
@@ -4489,6 +4511,11 @@ export async function streamLLM(
     );
     const full = consumed.full;
     if (consumed.ok) {
+      if (consumed.usage !== 'unmeasured') {
+        try {
+          logAgentTurnUsage(activeModel, consumed.usage, { providerName: activeProvider.name, site: 'stream-llm', role: opts.usageRole });
+        } catch { /* best-effort observation */ }
+      }
       debug.log('llm.router.done', 'streamLLM', {
         provider: activeProvider.name,
         model: activeModel,
@@ -7803,7 +7830,6 @@ export function getInspectBudgetThreshold(messages: readonly LLMMessage[], model
 //  ⛔ 사람이 «실제로 친» 말(interjection)과 툴 결과는 여기 해당하지 않는다 — 그것은 보여야 한다.
 export const LOOP_SELF_NOTE_ROLE = 'system' as const;
 
-/** One `llm.usage` observation per provider usage event of the main tool loop (same shape as the side sites). */
 /** 과금 경로 — 자격 종류에서 파생(BACKLOG C6). oauth=구독 · local · apikey=API · 그 밖=모름. */
 export function billingRouteForProvider(provider: string | undefined, model: string): import('./budget/llm-cost.js').BillingRoute {
   if (!provider) return 'unknown';
@@ -7818,11 +7844,16 @@ export function billingRouteForProvider(provider: string | undefined, model: str
   }
 }
 
-export function logAgentTurnUsage(model: string, usage: LLMUsage, providerName?: string): void {
+/** Observe usage with optional site/role metadata; a provider-name string remains supported. */
+export function logAgentTurnUsage(model: string, usage: LLMUsage, providerNameOrOptions?: string | { providerName?: string; site?: string; role?: ModelRole }): void {
   try {
+    const providerName = typeof providerNameOrOptions === 'string' ? providerNameOrOptions : providerNameOrOptions?.providerName;
+    const site = (typeof providerNameOrOptions === 'string' ? undefined : providerNameOrOptions?.site) ?? 'agent-turn';
+    const role = typeof providerNameOrOptions === 'string' ? undefined : providerNameOrOptions?.role;
     const billing = billingRouteForProvider(providerName, model);
     debug.log('llm.usage', 'llm-usage', {
-      site: 'agent-turn',
+      site,
+      ...(role !== undefined ? { role } : {}),
       model,
       ...(usage.provider !== undefined && { provider: usage.provider }),
       // ⭐ `provider` 는 «선 어댑터»(openai/anthropic)다 — 과금 주체는 별칭 칸으로(BACKLOG B10).
@@ -8464,7 +8495,7 @@ export async function streamLLMWithTools(
         // ⭐ 주 에이전트 턴의 토큰·비용을 «게이트 없이» 남긴다(2026-09-24 실측: 이 줄이 없어 3시간 `llm.usage`
         //   18행이 전부 곁가지 두 자리였고, 하니스 런 비용의 거의 전부가 관측 밖이었다). 곁가지와 같은 모양 ·
         //   모르는 모델은 금액 대신 `cost.kind='unknown'`. runId 는 debug.log 가 붙인다. 실패해도 턴은 계속.
-        logAgentTurnUsage(activeModel, ev.usage, activeProvider.name);
+        logAgentTurnUsage(activeModel, ev.usage, { providerName: activeProvider.name, role: opts.usageRole });
         // Wave A1 (2026-05-04) — turn-level cache hit rate forensic.
         // Each provider's usage event carries inputTokens / outputTokens
         // / cacheReadInputTokens (when cache hit). Emit the per-turn
@@ -10601,7 +10632,9 @@ export async function streamLLMWithTools(
 // `baseUrl` in config.
 
 import type { LLMConfig as UCLLMConfig, UserConfig } from './user-config.js';
-import { loadTokens } from './oauth/store.js';
+import { loadTokens, readCodexMirrorTokens } from './oauth/store.js';
+import { resolveCodexAccount, effectiveCodexHome } from './oauth/codex-account.js';
+import { join } from 'node:path';
 import {
   CODEX_API_BASE_URL, getCodexUserAgent, loadFreshCodexAuthState,
 } from './oauth/codex.js';
@@ -10779,9 +10812,8 @@ function makeCodexProvider(cfg: UCLLMConfig): LLMProvider {
   // resolve (with refresh) inside the async generator so we never
   // block constructor-time callers. available() returns true if EITHER
   // OAuth tokens or an apiKey is configured.
-  const initialTokens = loadTokens('openai-codex');
   const apiKey = cfg.apiKey;
-  const hasOAuth = !!initialTokens;
+  const hasOAuth = codexOAuthAvailable();
   // store=true wave: closure-scoped state so multi-turn callers
   // (dashboard reusing the same provider across a chat session) get
   // delta-only continuation. Single-turn callers (eval-prompt-cli
@@ -11188,7 +11220,7 @@ export function getProviderForConfig(
     ? decision.provider.slice('auto:'.length)
     : decision.provider;
   if (provider === 'auto') {
-    if (resolvedProviderName === 'auto') throw new Error(noProviderAvailableMessage());
+    if (resolvedProviderName === 'auto') throw new NoLlmProviderAvailableError();
     if (!isKnownProviderName(resolvedProviderName)) {
       throw new Error(`unknown provider: ${resolvedProviderName}`);
     }

package/src/log-entry.ts

@@ -167,7 +167,7 @@ export interface RenderOpts {
   colorByAgent?: boolean;
   /** When true, foldHint appends the rich-mode "press f to expand"
    *  invitation. Omitted/false = count-only (essential/unknown).
-   *  Callers that know DashboardUiMode pass `mode === 'rich'`. */
+   *  The essential dashboard passes false. */
   expandHint?: boolean;
 }
 

package/src/log-pane/attachment-popup.ts

@@ -4,8 +4,7 @@
 // `├─ [Md #3] SMOKE.md (41.9KB)`) in the log pane, we open a small
 // anchored selector listing the actions they'd otherwise have to
 // type slash-commands for: drop, copy the token, copy the source
-// path. Mirrors the vw-selector-popup + context-menu pattern — a
-// SelectView wrapped in BoxView, mounted as a modal surface via
+// path. A SelectView wrapped in BoxView, mounted as a modal surface via
 // mountViewAsModalSurface (so it picks up the standard modal-stack
 // key routing, focus tracking, and context-key tier management).
 //

package/src/loops/loop-cli.ts

@@ -0,0 +1,37 @@
+import type { Command } from 'commander';
+import { writeStdoutJson } from '../cli/stdout-json.js';
+import { listLoops, loopStatus, runLoop, setLoopEnabled } from './registry.js';
+
+async function output(value: unknown, json: boolean): Promise<void> {
+  if (json) await writeStdoutJson(JSON.stringify(value) + '\n');
+  else console.log(typeof value === 'string' ? value : JSON.stringify(value, null, 2));
+}
+
+function handle(action: () => Promise<void> | void): Promise<void> {
+  return Promise.resolve().then(action).catch(error => {
+    console.error(`loop: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+  });
+}
+
+export function registerLoopCommands(program: Command): void {
+  const loop = program.command('loop').description('Inspect and control graph-backed loop agents');
+  loop.command('list').option('--json', 'Print JSON')
+    .action((opts: { json?: boolean }) => handle(() => output(listLoops(), !!opts.json)));
+  loop.command('status <id>').option('--json', 'Print JSON')
+    .action((id: string, opts: { json?: boolean }) => handle(() => output(loopStatus(id), !!opts.json)));
+  for (const [name, enabled] of [['start', true], ['stop', false]] as const) {
+    loop.command(`${name} <id>`).option('--yes', 'Apply the crontab change (otherwise preview only)')
+      .option('--json', 'Print JSON')
+      .action((id: string, opts: { yes?: boolean; json?: boolean }) => handle(async () => {
+        await output(await setLoopEnabled(id, enabled, !!opts.yes), !!opts.json);
+      }));
+  }
+  loop.command('run <id>').option('--dry-run', 'Walk the graph without executing commands')
+    .option('--json', 'Print JSON')
+    .action((id: string, opts: { dryRun?: boolean; json?: boolean }) => handle(async () => {
+      const state = await runLoop(id, !!opts.dryRun);
+      await output(state, !!opts.json);
+      if (state.status !== 'done' && state.status !== 'awaiting-approval') process.exitCode = 1;
+    }));
+}