elanous 0.2.42 → 0.2.44

package/src/session/streaming/stream-compositor.ts

@@ -46,9 +46,10 @@ export function createCompositorState(): CompositorState {
 /** 청크 이벤트를 상태에 반영(순수·in-place). delta/reasoning/tool 을 흡수. */
 export function applyChunk(
   state: CompositorState,
-  ev: { delta?: string; reasoning?: string; tool?: { id: string; name: string; phase: 'call' | 'result'; ok?: boolean } },
+  ev: { delta?: string; textOperation?: 'replace'; reasoning?: string; tool?: { id: string; name: string; phase: 'call' | 'result'; ok?: boolean } },
 ): void {
-  if (ev.delta) state.text += ev.delta;
+  if (ev.textOperation === 'replace') state.text = ev.delta ?? '';
+  else if (ev.delta) state.text += ev.delta;
   if (ev.reasoning) state.reasoning = ev.reasoning; // keep-latest(추론은 누적 아닌 최신 요약)
   if (ev.tool) {
     if (ev.tool.phase === 'call') {

package/src/session-runtime/index.ts

@@ -1,4 +1,5 @@
 import { buildGitSnapshot } from '../git-fs/index.js';
+import { classifyTuiChatIntent } from '../core-turn/short-question.js';
 import { debug } from '../debug/log.js';
 import { isResearchAgentIntent } from '../tool-hints/signals.js';
 import { resolve } from 'node:path';
@@ -185,6 +186,7 @@ export interface SessionRuntimeDispatchDeps {
     dispatch: (name: string, args: Record<string, unknown>) => Promise<unknown>;
     workingDirectory: string;
   };
+  inheritGeneralPurposeToolCatalog?: boolean;
   searchPlannerState?: SearchPlannerState;
   /** CC (2026-04-25) — forwarded from the LLM router's dispatch ctx
    *  (`turnIndex`). Lets the planner allow same-turn parallel fan-out
@@ -224,6 +226,16 @@ interface SessionToolFamilyRule {
   isAvailable?(toolName: string): boolean;
 }
 
+// Keep generic approvals (for example, Herdr session approvals) out of the decision-ledger lookup.
+const DECISION_PENDING_LOOKUP_TERMS = [
+  '결정 카드', '결정카드', '미결 결정', '열린 결정', '대기 결정', '결정 대기', '결정 승인 대기',
+  'pending decision', 'open decision', 'decision inbox',
+] as const;
+const OPS_SEATS_LOOKUP_TERMS = [
+  '자리 현황', '자리별 현황', '자리 상태', '자리별 상태', '좌석 현황',
+  'seat status', 'seat overview',
+] as const;
+
 const SESSION_TOOL_FAMILY_RULES: SessionToolFamilyRule[] = [
   {
     id: 'structural-search',
@@ -439,6 +451,7 @@ interface SessionNativeToolRule {
         dispatch: (name: string, args: Record<string, unknown>) => Promise<unknown>;
         workingDirectory: string;
       };
+      inheritGeneralPurposeToolCatalog?: boolean;
     },
   ): Promise<unknown>;
   /** ⛔ Opt-IN to the ToolRuntime registry path instead of `dispatch` above.
@@ -520,6 +533,7 @@ const SESSION_NATIVE_TOOL_RULES: SessionNativeToolRule[] = [
       hostTools: opts?.agentHostTools,
       dispatchTool: opts?.agentDispatchTool,
       buildChildToolCatalog: opts?.buildChildToolCatalog,
+      inheritGeneralPurposeToolCatalog: opts?.inheritGeneralPurposeToolCatalog,
     }),
     preferRuntime: true,
   },
@@ -843,7 +857,7 @@ const SESSION_SURFACE_PROFILES: Record<SessionSurfaceId, Omit<SessionSurfaceProf
     baselineContexts: ['external-world-guidance'],
     defaultHostFamilyIds: ['self-ops'],
     defaultRuntimeFamilyIds: [],
-    defaultNativeFamilyIds: ['web-search'],
+    defaultNativeFamilyIds: ['web-search', 'deep-research', 'web-fetch'],
   },
   'control/agent': {
     id: 'control/agent',
@@ -1811,6 +1825,38 @@ function buildEssentialSessionRuntimeToolSpecs(opts: {
   return [...nativeSpecs, ...hostSpecs, ...runtimeSpecs, ...mcpProxySpecs, ...optionalSpecs];
 }
 
+/** Build the full TUI-visible catalog for Agent children. The parent model's
+ *  turn catalog is intentionally surface/tier narrowed; children inherit the
+ *  available TUI catalog instead, while `dispatchSessionRuntimeTool` remains
+ *  the policy boundary and `dispatchAgent` still strips recursive Agent. */
+export function buildSubagentSessionRuntimeToolSpecs(opts: {
+  hostTools: readonly LLMToolDef[];
+  runtimeTools: readonly ToolRuntime<Record<string, unknown>, ToolRunResult>[];
+  optionalTools: readonly LLMToolSpec[];
+  toolAvailability?: Readonly<Record<string, boolean>>;
+}): LLMToolSpec[] {
+  const nativeSpecs = SESSION_NATIVE_TOOL_RULES.flatMap(rule => {
+    const spec = rule.build();
+    const catalogEntry = findNativeTool(spec.name);
+    return (!catalogEntry || isNativeToolModelExposed(catalogEntry))
+      && isNativeToolAvailable(spec.name, rule, opts.toolAvailability)
+      ? [spec]
+      : [];
+  });
+  const hostSpecs = opts.hostTools
+    .filter(tool => isToolAvailable(tool.name, opts.toolAvailability))
+    .map(toSpec);
+  const runtimeSpecs = opts.runtimeTools
+    .filter(tool => isToolAvailable(tool.spec.name, opts.toolAvailability))
+    .map(tool => tool.spec);
+  const optionalSpecs = opts.optionalTools
+    .filter(tool => isToolAvailable(tool.name, opts.toolAvailability));
+  return [...new Map(
+    [...nativeSpecs, ...hostSpecs, ...runtimeSpecs, ...optionalSpecs]
+      .map(spec => [spec.name, spec] as const),
+  ).values()];
+}
+
 export function buildSessionRuntimeToolSpecs(opts: {
   userText: string;
   hostTools: readonly LLMToolDef[];
@@ -1836,13 +1882,34 @@ export function buildSessionRuntimeToolSpecs(opts: {
     optionalTools: opts.optionalTools ?? [],
     toolAvailability: opts.toolAvailability,
   });
+  // These owner-read facts tools are valid ACP lookup targets, but are too
+  // specific to carry on every dashboard turn. Keep the advertised catalog
+  // aligned with the current question so a routed lookup can actually call it.
+  const lookupRoute = classifyTuiChatIntent(opts.userText).route === '조회';
+  const normalizedIntentText = opts.userText.toLowerCase();
+  const intentHostNames = lookupRoute ? [
+    ...(hasAny(normalizedIntentText, DECISION_PENDING_LOOKUP_TERMS) ? ['decisions_pending'] : []),
+    ...(hasAny(normalizedIntentText, OPS_SEATS_LOOKUP_TERMS) ? ['ops_seats'] : []),
+  ] : [];
+  const hostByName = new Map(opts.hostTools.map(tool => [tool.name, tool] as const));
+  const intentHostSpecs = intentHostNames
+    .filter(name => isToolAvailable(name, opts.toolAvailability))
+    .map(name => hostByName.get(name))
+    .filter((tool): tool is LLMToolDef => !!tool)
+    .map(toSpec);
   const droppedNames = new Set(['Edit', 'Write']);
-  const finalSpecs: LLMToolSpec[] = hasDevHarnessIntent(opts.userText)
-    ? essentialSpecs.filter(spec => !droppedNames.has(spec.name))
-    : essentialSpecs;
-  if (finalSpecs.length !== essentialSpecs.length) {
+  const dropWriteTools = hasDevHarnessIntent(opts.userText);
+  const droppedWriteSpecs = dropWriteTools
+    ? essentialSpecs.filter(spec => droppedNames.has(spec.name))
+    : [];
+  const finalSpecs: LLMToolSpec[] = [...new Map(
+    [...essentialSpecs, ...intentHostSpecs]
+      .filter(spec => !dropWriteTools || !droppedNames.has(spec.name))
+      .map(spec => [spec.name, spec] as const),
+  ).values()];
+  if (droppedWriteSpecs.length > 0) {
     debug.log('session-runtime.tools', 'harness-phrase-write-tools-dropped', {
-      dropped: ['Edit', 'Write'],
+      dropped: droppedWriteSpecs.map(spec => spec.name),
     });
   }
   // Forensic — final tool list returned to streamLLMWithTools. Lets
@@ -2122,6 +2189,7 @@ export async function dispatchSessionRuntimeTool(
         agentHostTools: deps.agentHostTools,
         agentDispatchTool: deps.agentDispatchTool,
         buildChildToolCatalog: deps.buildChildToolCatalog,
+        inheritGeneralPurposeToolCatalog: deps.inheritGeneralPurposeToolCatalog,
       });
     }
     rememberCandidateListingResult(name, normalizedArgs, result, scopedAnalysis, deps.searchPlannerState);

package/src/session-runtime/retry-policy.ts

@@ -226,7 +226,7 @@ export function providerNamesFromFallbackChain(chain: readonly string[]): string
   const seen = new Set<string>();
   for (const step of chain) {
     // `codex-credits`(체인 마지막 칸 · 크레딧)도 provider 는 openai-codex 다 — 이미 앞에 있으면 중복이라 빠진다.
-    const name = step === 'grok' ? 'grok' : step === 'zai' ? 'glm'
+    const name = step === 'grok' ? 'grok' : step === 'zai' ? 'glm' : step === 'openrouter' ? 'openrouter'
       : step === 'codex-rotate' || step === 'codex-credits' ? 'openai-codex' : undefined;
     if (!name || seen.has(name)) continue;
     seen.add(name);

package/src/setup/llm-env-detect.ts

@@ -168,6 +168,9 @@ export const AUXILIARY_AI_ENV_VARS: readonly AuxiliaryAiEnvVar[] = [
   { name: 'UPSTAGE_API_KEY',    usedBy: 'document parse' },
 ] as const;
 
+export { SERVICE_KEY_CATALOG, renderServiceKeyCatalogMarkdown } from './service-key-catalog.js';
+export type { ServiceKeyCatalogEntry } from './service-key-catalog.js';
+
 export function summarizeAuxiliaryAiEnv(
   env: NodeJS.ProcessEnv = process.env,
 ): AuxiliaryAiEnvVar[] {

package/src/setup/service-key-catalog.ts

@@ -0,0 +1,46 @@
+/** Service setup metadata shared by the CLI, runtime key loader, and manual. */
+export interface ServiceKeyCatalogEntry {
+  id: string;
+  label: string;
+  kind: 'api-key' | 'subscription' | 'oauth' | 'cli' | 'local';
+  envNames: readonly string[];
+  setupUrl: string;
+  usedBy: string;
+  cost: 'account-plan' | 'usage-based' | 'plan-dependent' | 'local';
+  verification: string;
+  demoRequired: boolean;
+}
+
+export const SERVICE_KEY_CATALOG: readonly ServiceKeyCatalogEntry[] = [
+  { id: 'codex', label: 'OpenAI Codex', kind: 'subscription', envNames: [], setupUrl: 'https://platform.openai.com/docs/codex/auth', usedBy: '씬 1 리서치 · 사이드탭 미션', cost: 'account-plan', verification: 'elanous auth status', demoRequired: true },
+  { id: 'claude-code', label: 'Claude Code', kind: 'subscription', envNames: [], setupUrl: 'https://docs.anthropic.com/en/docs/claude-code/overview', usedBy: '씬 1 비교 · 사이드탭 미션', cost: 'account-plan', verification: 'claude auth status', demoRequired: true },
+  { id: 'exa', label: 'Exa', kind: 'api-key', envNames: ['EXA_API_KEY'], setupUrl: 'https://dashboard.exa.ai/api-keys', usedBy: '씬 1 리서치 · 씬 2 흡수', cost: 'usage-based', verification: 'POST /search · 상태 코드만', demoRequired: true },
+  { id: 'firecrawl', label: 'Firecrawl', kind: 'api-key', envNames: ['FIRECRAWL_API_KEY'], setupUrl: 'https://www.firecrawl.dev/app/api-keys', usedBy: '씬 2 흡수', cost: 'usage-based', verification: 'POST /v2/scrape · 상태 코드만', demoRequired: true },
+  { id: 'xai', label: 'xAI / Grok API', kind: 'api-key', envNames: ['XAI_API_KEY', 'GROK_API_KEY'], setupUrl: 'https://console.x.ai/', usedBy: '씬 2 흡수 · Grok API', cost: 'usage-based', verification: 'GET /v1/models · 상태 코드만', demoRequired: true },
+  { id: 'tavily', label: 'Tavily', kind: 'api-key', envNames: ['TAVILY_API_KEY', 'TAVILY_KEY'], setupUrl: 'https://app.tavily.com/home', usedBy: '웹 검색 대체 경로', cost: 'usage-based', verification: 'POST /search · 상태 코드만', demoRequired: false },
+  { id: 'openrouter', label: 'OpenRouter · GLM', kind: 'api-key', envNames: ['OPENROUTER_API_KEY'], setupUrl: 'https://openrouter.ai/keys', usedBy: 'GLM · OpenRouter 모델', cost: 'usage-based', verification: 'GET /api/v1/key · 상태 코드만', demoRequired: true },
+  { id: 'linear', label: 'Linear API', kind: 'api-key', envNames: ['LINEAR_API_KEY'], setupUrl: 'https://linear.app/settings/api', usedBy: '씬 2 능동 비서', cost: 'plan-dependent', verification: 'GraphQL viewer · 상태 코드만', demoRequired: true },
+  { id: 'telegram', label: 'Telegram bot', kind: 'api-key', envNames: ['ELANOUS_TELEGRAM_BOT_TOKEN'], setupUrl: 'https://t.me/BotFather', usedBy: '씬 2 · 씬 3 채널', cost: 'local', verification: 'getMe · 상태 코드만', demoRequired: true },
+  { id: 'telegram-chat', label: 'Telegram chat ID', kind: 'api-key', envNames: ['ELANOUS_TELEGRAM_CHAT_ID'], setupUrl: 'https://core.telegram.org/bots/features#botfather', usedBy: '데모 알림 대상', cost: 'local', verification: 'getChat · 상태 코드만 · 미발송', demoRequired: true },
+  { id: 'google-workspace', label: 'Google Workspace', kind: 'oauth', envNames: [], setupUrl: 'https://developers.google.com/workspace/guides/get-started', usedBy: 'Gmail · Drive 커넥터', cost: 'account-plan', verification: '로그인 상태 확인 · 토큰 미표시', demoRequired: false },
+  { id: 'aside', label: 'Aside browser', kind: 'cli', envNames: [], setupUrl: 'https://github.com/elanous-ai/aside', usedBy: '브라우저 자동화', cost: 'plan-dependent', verification: 'aside status', demoRequired: true },
+  { id: 'github', label: 'GitHub CLI', kind: 'cli', envNames: [], setupUrl: 'https://cli.github.com/', usedBy: '공개 저장소 · 개발 플러그인', cost: 'local', verification: 'gh auth status', demoRequired: true },
+  { id: 'video-render', label: 'Video render', kind: 'local', envNames: [], setupUrl: 'https://ffmpeg.org/download.html', usedBy: '데모 하이라이트 렌더', cost: 'local', verification: 'ffmpeg -version', demoRequired: false },
+  { id: 'openai-api', label: 'OpenAI API', kind: 'api-key', envNames: ['OPENAI_API_KEY'], setupUrl: 'https://platform.openai.com/api-keys', usedBy: 'OpenAI 모델 · Codex API-key 경로', cost: 'usage-based', verification: 'GET /v1/models · 상태 코드만', demoRequired: false },
+  { id: 'anthropic-api', label: 'Anthropic API', kind: 'api-key', envNames: ['ANTHROPIC_API_KEY'], setupUrl: 'https://console.anthropic.com/settings/keys', usedBy: 'Claude API', cost: 'usage-based', verification: 'GET /v1/models · 상태 코드만', demoRequired: false },
+  { id: 'gemini-api', label: 'Google Gemini API', kind: 'api-key', envNames: ['GEMINI_API_KEY', 'GOOGLE_API_KEY'], setupUrl: 'https://aistudio.google.com/app/apikey', usedBy: 'Gemini 모델', cost: 'usage-based', verification: '모델 목록 · 상태 코드만', demoRequired: false },
+  { id: 'opengateway', label: 'OpenGateway', kind: 'api-key', envNames: ['OPENGATEWAY_API_KEY'], setupUrl: 'https://apis.opengateway.ai/', usedBy: 'OpenAI 호환 모델 대체 경로', cost: 'usage-based', verification: 'GET /v1/models · 상태 코드만', demoRequired: false },
+  { id: 'supadata', label: 'Supadata', kind: 'api-key', envNames: ['SUPADATA_API_KEY'], setupUrl: 'https://supadata.ai/', usedBy: 'YouTube 자막', cost: 'usage-based', verification: '자막 API · 상태 코드만', demoRequired: false },
+  { id: 'elevenlabs', label: 'ElevenLabs', kind: 'api-key', envNames: ['ELEVENLABS_API_KEY'], setupUrl: 'https://elevenlabs.io/app/settings/api-keys', usedBy: '음성 합성', cost: 'usage-based', verification: 'GET /v1/user · 상태 코드만', demoRequired: false },
+  { id: 'brave-search', label: 'Brave Search', kind: 'api-key', envNames: ['BRAVE_API_KEY'], setupUrl: 'https://brave.com/search/api/', usedBy: '웹 검색 대체 경로', cost: 'usage-based', verification: '검색 API · 상태 코드만', demoRequired: false },
+  { id: 'youtube-data', label: 'YouTube Data API', kind: 'api-key', envNames: ['YOUTUBE_API_KEY'], setupUrl: 'https://console.cloud.google.com/apis/credentials', usedBy: 'YouTube 메타데이터', cost: 'usage-based', verification: 'videos.list · 상태 코드만', demoRequired: false },
+  { id: 'apify', label: 'Apify', kind: 'api-key', envNames: ['APIFY_TOKEN'], setupUrl: 'https://console.apify.com/account/integrations', usedBy: 'X 수집', cost: 'usage-based', verification: '사용자 API · 상태 코드만', demoRequired: false },
+  { id: 'eodhd', label: 'EODHD', kind: 'api-key', envNames: ['EODHD_API_KEY'], setupUrl: 'https://eodhd.com/financial-apis/', usedBy: '시장 시세', cost: 'usage-based', verification: '시장 API · 상태 코드만', demoRequired: false },
+  { id: 'fds', label: 'FDS market data', kind: 'api-key', envNames: ['FDS_API_KEY'], setupUrl: 'https://elanous.ai', usedBy: '시장 시세', cost: 'plan-dependent', verification: '연결 미니 호출 · 상태 코드만', demoRequired: false },
+  { id: 'upstage', label: 'Upstage', kind: 'api-key', envNames: ['UPSTAGE_API_KEY'], setupUrl: 'https://console.upstage.ai/api-keys', usedBy: '문서 파싱', cost: 'usage-based', verification: '문서 API · 상태 코드만', demoRequired: false },
+] as const;
+
+export function renderServiceKeyCatalogMarkdown(): string {
+  const rows = SERVICE_KEY_CATALOG.map(item => `| ${item.id} | ${item.label} | ${item.kind} | ${item.envNames.join(', ') || '로그인/설치'} | ${item.setupUrl} | ${item.cost} | ${item.usedBy} | ${item.verification} | ${item.demoRequired ? '씬 사용' : '선택'} |`);
+  return ['| id | 서비스 | 인증 | 환경 이름 | 설정 위치 | 비용 유형 | 사용처 | 최소 확인 | 판정 |', '|---|---|---|---|---|---|---|---|---|', ...rows].join('\n');
+}

package/src/setup/service-keys.ts

@@ -0,0 +1,241 @@
+import { randomBytes } from 'node:crypto';
+import { closeSync, existsSync, fchmodSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { stdin, stdout } from 'node:process';
+import { SERVICE_KEY_CATALOG } from './llm-env-detect.js';
+
+const SERVICE_KEY_ENV_NAMES = new Set(SERVICE_KEY_CATALOG
+  .filter(item => item.kind === 'api-key')
+  .flatMap(item => item.envNames));
+
+/** Read a multi-line dotenv paste in raw mode. No pasted character is echoed; Ctrl-D finishes. */
+export async function readMaskedServiceEnvPaste(): Promise<string> {
+  if (!stdin.isTTY || typeof stdin.setRawMode !== 'function') throw new Error('secret input requires a terminal');
+  stdout.write('Paste .env assignments; input stays hidden. Press Ctrl-D when finished.\n');
+  const priorRaw = stdin.isRaw;
+  stdin.setRawMode(true);
+  stdin.resume();
+  stdin.setEncoding('utf8');
+  return new Promise((resolve, reject) => {
+    let value = '';
+    const cleanup = () => {
+      stdin.removeListener('data', onData);
+      stdin.setRawMode(priorRaw);
+    };
+    const onData = (chunk: string) => {
+      for (const char of chunk) {
+        const code = char.charCodeAt(0);
+        if (code === 4) {
+          stdout.write('\n');
+          cleanup();
+          resolve(value);
+          return;
+        }
+        if (code === 3) {
+          stdout.write('\n');
+          cleanup();
+          reject(new Error('cancelled'));
+          return;
+        }
+        if (char === '\r') continue;
+        if (char === '\n') {
+          value += '\n';
+          stdout.write('\n');
+          continue;
+        }
+        if (char === '\b' || code === 127) {
+          const characters = Array.from(value);
+          if (characters.length > 0) {
+            const removedNewline = characters.at(-1) === '\n';
+            characters.pop();
+            value = characters.join('');
+            stdout.write(removedNewline ? '\u001b[1A\r\u001b[K' : '\b \b');
+          }
+          continue;
+        }
+        if (code < 32) continue;
+        value += char;
+        stdout.write('*');
+      }
+    };
+    stdin.on('data', onData);
+  });
+}
+
+export type ParsedServiceKeyEnv = ReadonlyMap<string, string>;
+
+/** Parse dotenv assignments without expansion and never include values in errors. */
+export function parseServiceKeyEnv(text: string): ParsedServiceKeyEnv {
+  const values = new Map<string, string>();
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    const match = line.match(/^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/);
+    if (!match) throw new Error('invalid env assignment');
+    const name = match[1]!;
+    if (!SERVICE_KEY_ENV_NAMES.has(name)) throw new Error(`unsupported env name: ${name}`);
+    if (values.has(name)) throw new Error(`duplicate env name: ${name}`);
+    let value = match[2]!.trim();
+    if (value.startsWith('"') || value.startsWith("'")) {
+      const quote = value[0]!;
+      if (value.length < 2 || value.at(-1) !== quote) throw new Error(`invalid quoted value for ${name}`);
+      value = value.slice(1, -1);
+    } else {
+      value = value.replace(/\s+#.*$/, '').trim();
+    }
+    if (!value || value.includes('\0')) throw new Error(`empty or invalid value for ${name}`);
+    values.set(name, value);
+  }
+  return values;
+}
+
+export interface ServiceKeyStatus {
+  id: string;
+  label: string;
+  envNames: string[];
+  configured: boolean;
+  kind: string;
+}
+
+function cachePath(name: string, cacheDir: string): string {
+  if (!SERVICE_KEY_ENV_NAMES.has(name)) throw new Error(`unsupported env name: ${name}`);
+  return join(cacheDir, name.toLowerCase());
+}
+
+function cachedValue(name: string, cacheDir: string): string | undefined {
+  const path = cachePath(name, cacheDir);
+  if (!existsSync(path)) return undefined;
+  try {
+    const stat = lstatSync(path);
+    if (!stat.isFile()) return undefined;
+    return readFileSync(path, 'utf8').trim() || undefined;
+  } catch { return undefined; }
+}
+
+export function serviceKeyStatus(options: {
+  env?: NodeJS.ProcessEnv;
+  cacheDir?: string;
+} = {}): ServiceKeyStatus[] {
+  const env = options.env ?? process.env;
+  const cacheDir = options.cacheDir ?? (process.env.ELANOUS_KEY_CACHE_DIR?.trim() || join(homedir(), '.cache'));
+  return SERVICE_KEY_CATALOG.map(item => ({
+    id: item.id,
+    label: item.label,
+    envNames: [...item.envNames],
+    kind: item.kind,
+    configured: item.kind === 'api-key'
+      ? item.envNames.some(name => Boolean(env[name]?.trim() || cachedValue(name, cacheDir)))
+      : false,
+  }));
+}
+
+/** Persist accepted service keys into the established ~/.cache/<env lowercase> store. */
+export function storeServiceKeys(values: ParsedServiceKeyEnv, options: {
+  cacheDir?: string;
+  env?: NodeJS.ProcessEnv;
+} = {}): { stored: string[] } {
+  const cacheDir = options.cacheDir ?? (process.env.ELANOUS_KEY_CACHE_DIR?.trim() || join(homedir(), '.cache'));
+  const env = options.env ?? process.env;
+  for (const [name, value] of values) {
+    cachePath(name, cacheDir);
+    if (!value.trim() || value.includes('\0')) throw new Error(`invalid value for ${name}`);
+  }
+  mkdirSync(cacheDir, { recursive: true, mode: 0o700 });
+  const dirStat = lstatSync(cacheDir);
+  if (!dirStat.isDirectory()) throw new Error('invalid key cache directory');
+  for (const [name, value] of values) {
+    const path = cachePath(name, cacheDir);
+    const temp = `${path}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`;
+    try {
+      const fd = openSync(temp, 'wx', 0o600);
+      try {
+        fchmodSync(fd, 0o600);
+        writeFileSync(fd, `${value.trim()}\n`);
+        fsyncSync(fd);
+      } finally { closeSync(fd); }
+      renameSync(temp, path);
+      env[name] = value.trim();
+    } finally { rmSync(temp, { force: true }); }
+  }
+  return { stored: [...values.keys()].sort() };
+}
+
+export type ServiceKeyVerification = 'verified' | 'invalid' | 'rate-limited' | 'unavailable' | 'unsupported';
+
+export interface VerifyServiceKeyOptions {
+  /** Existing per-provider endpoint, such as llm.rotation[].baseUrl. */
+  baseUrl?: string;
+  cacheDir?: string;
+  env?: NodeJS.ProcessEnv;
+  fetchImpl?: typeof fetch;
+  timeoutMs?: number;
+}
+
+function modelsUrl(baseUrl: string | undefined, defaultRoot: string): string {
+  const root = (baseUrl || defaultRoot).replace(/\/+$/, '');
+  return `${root}/models`;
+}
+
+/** One bounded minimal request. Results contain only a category and status code; errors and URLs are discarded. */
+export async function verifyServiceKey(id: string, key: string, options: VerifyServiceKeyOptions = {}): Promise<{ result: ServiceKeyVerification; httpStatus?: number }> {
+  const env = options.env ?? process.env;
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const timeoutMs = Math.max(100, options.timeoutMs ?? 5_000);
+  let url: string;
+  let init: RequestInit;
+  const bearer = (endpoint: string): void => {
+    url = endpoint;
+    init = { method: 'GET', headers: { authorization: `Bearer ${key}` } };
+  };
+  switch (id) {
+    case 'exa':
+      url = 'https://api.exa.ai/search';
+      init = { method: 'POST', headers: { 'content-type': 'application/json', 'x-api-key': key }, body: JSON.stringify({ query: 'credential check', numResults: 1 }) };
+      break;
+    case 'firecrawl':
+      url = 'https://api.firecrawl.dev/v2/scrape';
+      init = { method: 'POST', headers: { 'content-type': 'application/json', authorization: `Bearer ${key}` }, body: JSON.stringify({ url: 'https://example.com', formats: ['markdown'] }) };
+      break;
+    case 'xai': bearer(modelsUrl(options.baseUrl, 'https://api.x.ai/v1')); break;
+    case 'tavily':
+      url = 'https://api.tavily.com/search';
+      init = { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ api_key: key, query: 'credential check', max_results: 1 }) };
+      break;
+    case 'openrouter': bearer('https://openrouter.ai/api/v1/key'); break;
+    case 'linear':
+      url = 'https://api.linear.app/graphql';
+      init = { method: 'POST', headers: { 'content-type': 'application/json', authorization: key }, body: JSON.stringify({ query: 'query { viewer { id } }' }) };
+      break;
+    case 'telegram': bearer(`https://api.telegram.org/bot${key}/getMe`); break;
+    case 'openai-api': bearer(modelsUrl(options.baseUrl || process.env.OPENAI_BASE_URL, 'https://api.openai.com/v1')); break;
+    case 'anthropic-api':
+      url = 'https://api.anthropic.com/v1/models';
+      init = { method: 'GET', headers: { 'x-api-key': key, 'anthropic-version': '2023-06-01' } };
+      break;
+    case 'gemini-api':
+      url = 'https://generativelanguage.googleapis.com/v1beta/models';
+      init = { method: 'GET', headers: { 'x-goog-api-key': key } };
+      break;
+    case 'opengateway': bearer('https://apis.opengateway.ai/v1/models'); break;
+    case 'telegram-chat': {
+      const bot = env.ELANOUS_TELEGRAM_BOT_TOKEN?.trim() || cachedValue('ELANOUS_TELEGRAM_BOT_TOKEN', options.cacheDir ?? (process.env.ELANOUS_KEY_CACHE_DIR?.trim() || join(homedir(), '.cache')));
+      if (!bot) return { result: 'unsupported' };
+      url = `https://api.telegram.org/bot${bot}/getChat?chat_id=${encodeURIComponent(key)}`;
+      init = { method: 'GET' };
+      break;
+    }
+    default: return { result: 'unsupported' };
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetchImpl(url!, { ...init!, signal: controller.signal });
+    if (response.status >= 200 && response.status < 300) return { result: 'verified', httpStatus: response.status };
+    if (response.status === 401 || response.status === 403) return { result: 'invalid', httpStatus: response.status };
+    if (response.status === 429) return { result: 'rate-limited', httpStatus: response.status };
+    return { result: 'unavailable', httpStatus: response.status };
+  } catch {
+    return { result: 'unavailable' };
+  } finally { clearTimeout(timer); }
+}