elanous 0.2.42 → 0.2.44

package/src/ux-sim/scenario.ts

@@ -9,13 +9,21 @@ import { streamCodexResponsesEvents } from '../llm.js';
 import { LogStore, StoreSink, type LogStoreRow } from '../mss/logging/log-store.js';
 import { getTestStateRoot } from '../nexus/paths.js';
 import { simRenderLogFrame } from './render-frame.js';
+import { assessDraftInventory, buildDraftInventory } from './draft-inventory-builder.js';
+
+export type ScenarioTrigger = {
+  id: string;
+  type: 'codex.responses.fetch' | 'codex.responses.fetch-network-error' | 'ux.draft-inventory.evaluate';
+  status?: number;
+  count?: number;
+};
 
 export interface ScenarioV0 {
   version: 0;
   id: string;
   isolation: 'test';
   seed: number;
-  triggers: [{ id: string; type: 'codex.responses.fetch' | 'codex.responses.fetch-network-error'; status?: number; count?: number }];
+  triggers: [ScenarioTrigger];
   expect: {
     screen: { mode: 'widget'; snapshot: { contains: string[]; excludes?: string[] } };
     logs: [{ category: string; event: string; level: string; count?: number; data?: Record<string, unknown> }];
@@ -82,10 +90,11 @@ export function parseScenarioV0(source: string): ScenarioV0 {
   const trigger = record(value.triggers[0], 'scenario.triggers[0]');
   exactKeys(trigger, ['id', 'type', 'status', 'count'], 'scenario.triggers[0]');
   const triggerId = requiredString(trigger.id, 'scenario.triggers[0].id');
-  if (trigger.type !== 'codex.responses.fetch' && trigger.type !== 'codex.responses.fetch-network-error') throw new Error(`unregistered scenario trigger: ${String(trigger.type)}`);
+  if (trigger.type !== 'codex.responses.fetch' && trigger.type !== 'codex.responses.fetch-network-error' && trigger.type !== 'ux.draft-inventory.evaluate') throw new Error(`unregistered scenario trigger: ${String(trigger.type)}`);
   if (trigger.type === 'codex.responses.fetch' && (!Number.isInteger(trigger.status) || (trigger.status as number) < 400 || (trigger.status as number) > 499)) throw new Error('codex.responses.fetch.status must be an HTTP 4xx status');
-  if (trigger.type === 'codex.responses.fetch-network-error' && trigger.status !== undefined) throw new Error('codex.responses.fetch-network-error does not accept status');
+  if ((trigger.type === 'codex.responses.fetch-network-error' || trigger.type === 'ux.draft-inventory.evaluate') && trigger.status !== undefined) throw new Error(`${trigger.type} does not accept status`);
   if (trigger.count !== undefined && (!Number.isInteger(trigger.count) || (trigger.count as number) < 1)) throw new Error('codex.responses.fetch.count must be a positive integer');
+  if (trigger.type === 'ux.draft-inventory.evaluate' && trigger.count !== 200) throw new Error('ux.draft-inventory.evaluate.count must be 200');
 
   const expect = record(value.expect, 'scenario.expect');
   exactKeys(expect, ['screen', 'logs'], 'scenario.expect');
@@ -125,7 +134,7 @@ export function parseScenarioV0(source: string): ScenarioV0 {
     id,
     isolation: 'test',
     seed: value.seed as number,
-    triggers: [{ id: triggerId, type: trigger.type, ...(trigger.status !== undefined ? { status: trigger.status as number } : {}), ...(trigger.count !== undefined ? { count: trigger.count as number } : {}) }],
+    triggers: [{ id: triggerId, type: trigger.type as ScenarioTrigger['type'], ...(trigger.status !== undefined ? { status: trigger.status as number } : {}), ...(trigger.count !== undefined ? { count: trigger.count as number } : {}) }],
     expect: {
       screen: {
         mode: 'widget',
@@ -243,6 +252,7 @@ async function runScenarioV0Exclusive(scenario: ScenarioV0): Promise<ScenarioRes
   const store = new LogStore(logsPath, { instance });
   const storeSink = new StoreSink(store, instance, { installExitHandlers: false });
   const expectedLog = scenario.expect.logs[0];
+  const trigger = scenario.triggers[0];
   const sink: LogSink = {
     name: storeSink.name,
     emit(rec) {
@@ -260,36 +270,69 @@ async function runScenarioV0Exclusive(scenario: ScenarioV0): Promise<ScenarioRes
           category: rec.category,
           event: rec.event,
           level: rec.level,
-          ...(expectedLog.data ? { data: projectSubset(rec.data, expectedLog.data) } : {}),
+          ...(expectedLog.data ? {
+            data: trigger.type === 'ux.draft-inventory.evaluate'
+              ? { runId, ...projectSubset(rec.data, expectedLog.data) }
+              : projectSubset(rec.data, expectedLog.data),
+          } : {}),
         });
       }
     },
   };
   const off = debug.registerSink(sink);
   const originalFetch = globalThis.fetch;
-  const trigger = scenario.triggers[0];
   let errorMessage: string | null = null;
   let fetchCount = 0;
-  globalThis.fetch = (async (input: RequestInfo | URL) => {
-    fetchCount++;
-    if (String(input) !== 'https://chatgpt.com/backend-api/codex/responses') throw new Error('scenario fake fetch received an unregistered URL');
-    if (trigger.type === 'codex.responses.fetch-network-error') throw new Error(`scenario network error seed=${scenario.seed}`);
-    return new Response('{"detail":"Bad Request"}', { status: trigger.status!, headers: { 'content-type': 'application/json' } });
-  }) as unknown as typeof fetch;
+  let triggerObserved = false;
+  let screenLines: string[] = [];
+  if (trigger.type.startsWith('codex.')) {
+    globalThis.fetch = (async (input: RequestInfo | URL) => {
+      fetchCount++;
+      if (String(input) !== 'https://chatgpt.com/backend-api/codex/responses') throw new Error('scenario fake fetch received an unregistered URL');
+      if (trigger.type === 'codex.responses.fetch-network-error') throw new Error(`scenario network error seed=${scenario.seed}`);
+      return new Response('{"detail":"Bad Request"}', { status: trigger.status!, headers: { 'content-type': 'application/json' } });
+    }) as unknown as typeof fetch;
+  }
 
   try {
-    try {
-      for await (const _event of streamCodexResponsesEvents('https://chatgpt.com/backend-api/codex/responses', 'scenario-fake-token', {
-        model: 'gpt-6-sol',
-        instructions: 'scenario test request',
-        input: [{ role: 'user', content: [{ type: 'input_text', text: `scenario test input seed=${scenario.seed}` }] }],
-        tools: [{ type: 'function', name: 'RunShell', description: 'test tool', parameters: {} }],
-      }, undefined, { promptCache: false })) { /* consume the deterministic fake response */ }
-    } catch (error) {
-      errorMessage = error instanceof Error ? error.message : String(error);
+    if (trigger.type === 'ux.draft-inventory.evaluate') {
+      const result = assessDraftInventory(buildDraftInventory(trigger.count));
+      const data = {
+        runId,
+        total: result.total,
+        byScenario: result.byScenario,
+        byAction: result.byAction,
+        triageByAction: result.triageByAction,
+        mismatchCount: result.mismatches.length,
+        protectedOrRunningClosed: result.protectedOrRunningClosed,
+      };
+      debug.log('ux.sim.draft-inventory', 'assessed', data);
+      screenLines = [
+        'Draft inventory simulation',
+        `total=${result.total}`,
+        `mismatches=${result.mismatches.length}`,
+        `protectedOrRunningClosed=${result.protectedOrRunningClosed}`,
+      ];
+      triggerObserved = result.total === trigger.count
+        && Object.values(result.byScenario).every((count) => count === 25)
+        && result.mismatches.length === 0
+        && result.protectedOrRunningClosed === 0;
+    } else {
+      try {
+        for await (const _event of streamCodexResponsesEvents('https://chatgpt.com/backend-api/codex/responses', 'scenario-fake-token', {
+          model: 'gpt-6-sol',
+          instructions: 'scenario test request',
+          input: [{ role: 'user', content: [{ type: 'input_text', text: `scenario test input seed=${scenario.seed}` }] }],
+          tools: [{ type: 'function', name: 'RunShell', description: 'test tool', parameters: {} }],
+        }, undefined, { promptCache: false })) { /* consume the deterministic fake response */ }
+      } catch (error) {
+        errorMessage = error instanceof Error ? error.message : String(error);
+      }
+      triggerObserved = fetchCount === (trigger.count ?? 1) && errorMessage !== null;
+      screenLines = errorMessage ? [errorMessage] : [];
     }
 
-    const screenText = simRenderLogFrame({ phase: 'idle', lines: errorMessage ? [errorMessage] : [] }, { width: 100, height: 12 }).text;
+    const screenText = simRenderLogFrame({ phase: 'idle', lines: screenLines }, { width: 100, height: 12 }).text;
     const containsMissing = scenario.expect.screen.snapshot.contains.filter((fragment) => !screenText.includes(fragment));
     const excludesFound = (scenario.expect.screen.snapshot.excludes ?? []).filter((fragment) => screenText.includes(fragment));
 
@@ -302,9 +345,10 @@ async function runScenarioV0Exclusive(scenario: ScenarioV0): Promise<ScenarioRes
     const logPass = rows.length === expectedCount && !levelMismatch && dataMismatch.length === 0;
     const screenPass = containsMissing.length === 0 && excludesFound.length === 0;
     const failureReasons: string[] = [];
-    const expectedTriggerCount = trigger.count ?? 1;
-    if (fetchCount !== expectedTriggerCount) failureReasons.push(`trigger-count-mismatch:expected-${expectedTriggerCount}-observed-${fetchCount}`);
-    if (errorMessage === null) failureReasons.push('provider-error-not-observed');
+    const expectedTriggerCount = trigger.type.startsWith('codex.') ? trigger.count ?? 1 : 1;
+    const observedTriggerCount = trigger.type.startsWith('codex.') ? fetchCount : triggerObserved ? 1 : 0;
+    if (trigger.type.startsWith('codex.') && fetchCount !== expectedTriggerCount) failureReasons.push(`trigger-count-mismatch:expected-${expectedTriggerCount}-observed-${fetchCount}`);
+    if (!triggerObserved) failureReasons.push(trigger.type.startsWith('codex.') ? 'provider-error-not-observed' : 'draft-inventory-evaluation-failed');
     if (!screenPass) failureReasons.push('screen-snapshot-mismatch');
     if (rows.length === 0 && expectedCount > 0) failureReasons.push('expected-log-event-absent');
     else if (rows.length !== expectedCount) failureReasons.push(`log-event-count-mismatch:expected-${expectedCount}-observed-${rows.length}`);
@@ -331,7 +375,7 @@ async function runScenarioV0Exclusive(scenario: ScenarioV0): Promise<ScenarioRes
       evidenceArtifact: '',
       runEvidence: { ...runEvidence, persisted: runEventPersisted },
       pass: failureReasons.length === 0,
-      trigger: { id: trigger.id, type: trigger.type, status: trigger.status ?? null, expectedCount: expectedTriggerCount, fetchCount, error: errorMessage },
+      trigger: { id: trigger.id, type: trigger.type, status: trigger.status ?? null, expectedCount: expectedTriggerCount, fetchCount: observedTriggerCount, error: errorMessage },
       screen: { pass: screenPass, containsMissing, excludesFound, snapshot: screenText },
       logs: {
         pass: logPass,

package/src/ux-sim/service-key-setup.ts

@@ -0,0 +1,113 @@
+import { createServer, type Server } from 'node:http';
+import {
+  CODEX_DEVICE_TOKEN_URL,
+  CODEX_DEVICE_USERCODE_URL,
+  CODEX_OAUTH_TOKEN_URL,
+} from '../oauth/codex.js';
+
+export type FakeOpenAiApiMode = 'ok' | 'unauthorized' | 'rate-limited' | 'disconnect' | 'slow';
+
+export type FakeCodexDeviceOAuthMode = 'complete' | 'denied' | 'expired-code';
+
+export interface FakeCodexDeviceOAuth {
+  /** Route only the production loginWithCodex fetch seam; unknown URLs fail closed. */
+  fetchImpl: typeof fetch;
+  /** Safe request facts only. Codes, verifiers and tokens are never retained. */
+  requests: () => Array<{ endpoint: 'device-code' | 'device-poll' | 'token'; grantType?: string }>;
+}
+
+/** Fake OpenAI device-code endpoints for the real loginWithCodex production path. */
+export function createFakeCodexDeviceOAuth(mode: FakeCodexDeviceOAuthMode = 'complete'): FakeCodexDeviceOAuth {
+  let polls = 0;
+  const calls: Array<{ endpoint: 'device-code' | 'device-poll' | 'token'; grantType?: string }> = [];
+  const fetchImpl = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = String(input);
+    if (url === CODEX_DEVICE_USERCODE_URL) {
+      calls.push({ endpoint: 'device-code' });
+      return new Response(JSON.stringify({
+        device_auth_id: 'fake-device-auth-id', user_code: 'FAKE-USER-CODE', interval: 0,
+        verification_uri: 'https://auth.openai.com/codex/device',
+      }), { status: 200, headers: { 'content-type': 'application/json' } });
+    }
+    if (url === CODEX_DEVICE_TOKEN_URL) {
+      calls.push({ endpoint: 'device-poll' });
+      polls++;
+      if (mode === 'denied') {
+        return new Response(JSON.stringify({ error: 'access_denied' }), { status: 400 });
+      }
+      if (mode === 'expired-code') {
+        return new Response(JSON.stringify({ error: 'expired_token' }), { status: 400 });
+      }
+      if (polls === 1) return new Response(JSON.stringify({ error: 'authorization_pending' }), { status: 403 });
+      return new Response(JSON.stringify({ authorization_code: 'fake-authorization-code', code_verifier: 'fake-code-verifier' }), { status: 200 });
+    }
+    if (url === CODEX_OAUTH_TOKEN_URL) {
+      const body = new URLSearchParams(typeof init?.body === 'string' ? init.body : '');
+      const grantType = body.get('grant_type') ?? undefined;
+      calls.push({ endpoint: 'token', ...(grantType ? { grantType } : {}) });
+      if (grantType === 'authorization_code') {
+        if (body.get('code') !== 'fake-authorization-code' || body.get('code_verifier') !== 'fake-code-verifier') {
+          return new Response(JSON.stringify({ error: 'invalid_grant' }), { status: 400 });
+        }
+        return new Response(JSON.stringify({
+          access_token: 'fake-initial-access-token', refresh_token: 'fake-initial-refresh-token', expires_in: 0,
+        }), { status: 200, headers: { 'content-type': 'application/json' } });
+      }
+      if (grantType === 'refresh_token' && body.get('refresh_token') === 'fake-initial-refresh-token') {
+        return new Response(JSON.stringify({
+          access_token: 'fake-refreshed-access-token', refresh_token: 'fake-rotated-refresh-token', expires_in: 3600,
+        }), { status: 200, headers: { 'content-type': 'application/json' } });
+      }
+      return new Response(JSON.stringify({ error: 'unsupported_grant_type' }), { status: 400 });
+    }
+    throw new Error('fake Codex OAuth blocked an unexpected endpoint');
+  }) as typeof fetch;
+  return { fetchImpl, requests: () => calls.map(call => ({ ...call })) };
+}
+
+/** Local OpenAI-compatible /v1/models endpoint for testing the production key verifier. */
+export async function startFakeOpenAiCompatibleApi(mode: FakeOpenAiApiMode, delayMs = 350): Promise<{
+  baseUrl: string;
+  requests: () => number;
+  close: () => Promise<void>;
+}> {
+  let requestCount = 0;
+  const timers = new Set<ReturnType<typeof setTimeout>>();
+  const server: Server = createServer((request, response) => {
+    requestCount++;
+    if (request.url !== '/v1/models') {
+      response.writeHead(404).end();
+      return;
+    }
+    if (mode === 'disconnect') {
+      request.socket.destroy();
+      return;
+    }
+    if (mode === 'slow') {
+      const timer = setTimeout(() => {
+        timers.delete(timer);
+        if (!response.destroyed) response.writeHead(200, { 'content-type': 'application/json' }).end('{"data":[]}');
+      }, delayMs);
+      timers.add(timer);
+      return;
+    }
+    const status = mode === 'ok' ? 200 : mode === 'unauthorized' ? 401 : 429;
+    response.writeHead(status, { 'content-type': 'application/json' }).end(mode === 'ok' ? '{"data":[]}' : '{}');
+  });
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => resolve());
+  });
+  const address = server.address();
+  if (!address || typeof address === 'string') throw new Error('fake OpenAI API did not bind a TCP port');
+  return {
+    baseUrl: `http://127.0.0.1:${address.port}/v1`,
+    requests: () => requestCount,
+    close: () => new Promise<void>((resolve, reject) => {
+      for (const timer of timers) clearTimeout(timer);
+      timers.clear();
+      server.close(error => error ? reject(error) : resolve());
+      server.closeAllConnections();
+    }),
+  };
+}

package/src/ux-sim/term-slash-device.ts

@@ -0,0 +1,74 @@
+// /term mock-device stage — invoke the production slash registry/handler with
+// mocked terminal ports so subcommand combinations never need another PTY.
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { SlashCommandRegistry } from '../dashboard/slash-runtime/registry.js';
+import { createDashboardTermSlashRuntime } from '../dashboard/term-slash-runtime.js';
+import { registerTermSlash, type TermSlashContext } from '../tui/slash/term.js';
+
+export interface TermSlashScenarioResult {
+  subcommand: string;
+  expected: string;
+  evidence: string;
+}
+
+const format = (text: string) => text;
+
+/** Run the fast command matrix through the same production handler used by TUI. */
+export async function runTermSlashMockScenarios(): Promise<TermSlashScenarioResult[]> {
+  const root = mkdtempSync(join(tmpdir(), 'term-slash-mock-'));
+  const previousState = process.env.ELANOUS_STATE_DIR;
+  const previousHome = process.env.ELANOUS_TEST_HOME;
+  process.env.ELANOUS_STATE_DIR = root;
+  process.env.ELANOUS_TEST_HOME = root;
+  try {
+    const calls: string[] = [];
+    const ctx = {
+      chatLines: [] as string[], setChatScrollOffset: () => {},
+      accent: format, warning: format, error: format, draw: () => {},
+      termSlash: {
+        slashRuntime: createDashboardTermSlashRuntime({ accent: format, muted: format, warning: format, error: format, text: format }),
+        openNewTerminal: (command?: string) => { calls.push(`new:${command}`); },
+        openSessionPicker: () => { calls.push('switch'); },
+        sessionRegistry: {
+          list: () => [], foreground: () => null, kill: (id: string) => { calls.push(`kill:${id}`); },
+        },
+        terminalMatrix: { list: () => [], get: () => null, listPipes: () => [] },
+        broadcastBus: { groups: () => [] },
+        channelBus: { channels: () => [] },
+      },
+    } as unknown as TermSlashContext;
+    const registry = new SlashCommandRegistry<TermSlashContext, never>();
+    registerTermSlash(registry);
+    const cases = [
+      ['help', [], '/term new'], ['help', ['experimental'], '/term matrix'],
+      ['new', ['echo', 'hi'], 'new:echo hi'], ['list', [], 'No terminal sessions.'],
+      ['attach', [], '/term attach requires'], ['detach', [], 'No foreground session'],
+      ['switch', [], 'switch'], ['kill', [], 'No session to kill'],
+      ['resume', [], 'No persisted sessions'], ['snapshot', [], 'Usage: /term snapshot'],
+      ['matrix', [], '(no terminals'], ['move', [], 'Usage: /term move'],
+      ['group', [], '(no broadcast groups'], ['channel', [], '(no channels'],
+      ['pipe', [], 'Usage: /term pipe'], ['readonly', [], 'Usage: /term readonly'],
+      ['recharacter', [], 'Usage: /term recharacter'],
+    ] as const;
+    const results: TermSlashScenarioResult[] = [];
+    for (const [subcommand, args, expected] of cases) {
+      const lineStart = ctx.chatLines.length;
+      const callStart = calls.length;
+      await registry.dispatch('term', [subcommand, ...args], ctx);
+      results.push({
+        subcommand,
+        expected,
+        evidence: [...ctx.chatLines.slice(lineStart), ...calls.slice(callStart)].join('\n'),
+      });
+    }
+    return results;
+  } finally {
+    if (previousState === undefined) delete process.env.ELANOUS_STATE_DIR;
+    else process.env.ELANOUS_STATE_DIR = previousState;
+    if (previousHome === undefined) delete process.env.ELANOUS_TEST_HOME;
+    else process.env.ELANOUS_TEST_HOME = previousHome;
+    rmSync(root, { recursive: true, force: true });
+  }
+}

package/src/ux-sim/turn-throw-sim.ts

@@ -0,0 +1,31 @@
+export interface TurnThrowSimOptions {
+  stage: string;
+  delayMs?: number;
+  error?: Error;
+  sleep?: (milliseconds: number) => Promise<void>;
+}
+
+export type TurnThrowSim = (stage: string) => Promise<void>;
+
+const defaultSleep = (milliseconds: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, milliseconds));
+
+export function createTurnThrowSim(options: TurnThrowSimOptions): TurnThrowSim {
+  if (!options.stage.trim()) throw new Error('turn throw simulation stage must be non-empty');
+  const delayMs = options.delayMs ?? 0;
+  if (!Number.isFinite(delayMs) || delayMs < 0) throw new Error('turn throw simulation delayMs must be a non-negative finite number');
+  return async (stage) => {
+    if (stage !== options.stage) return;
+    if (delayMs > 0) await (options.sleep ?? defaultSleep)(delayMs);
+    throw options.error ?? new Error(`simulated turn body failure at ${stage}`);
+  };
+}
+
+/** The production path remains inert unless the explicit simulation environment is configured. */
+export const runConfiguredTurnThrowSim: TurnThrowSim = async (stage) => {
+  const configuredStage = process.env.ELANOUS_UX_SIM_TURN_THROW_STAGE;
+  if (!configuredStage) return;
+  const parsedDelay = Number(process.env.ELANOUS_UX_SIM_TURN_THROW_DELAY_MS ?? '0');
+  const simulate = createTurnThrowSim({ stage: configuredStage, delayMs: parsedDelay });
+  await simulate(stage);
+};

package/src/version/packed-revision.json

@@ -1 +1 @@
-{"commit":"926bcef26005c8e0f54f77b9fc51a1dd6143d2ec"}
+{"commit":"0580f24a8d55c5fd3689092912fda3ebbe826034"}

package/src/web-search/exa.ts

@@ -0,0 +1,77 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import type { WebSearchHit, WebSearchProvider, WebSearchQuery, WebSearchResult } from './provider.js';
+
+const EXA_SEARCH_API = 'https://api.exa.ai/search';
+
+export interface ExaWebSearchDeps {
+  fetch?: (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+  getEnv?: (name: string) => string | undefined;
+  readFile?: (path: string) => string;
+  homeDir?: () => string;
+}
+
+interface ExaResult {
+  url?: unknown;
+  title?: unknown;
+  highlights?: unknown;
+  text?: unknown;
+  score?: unknown;
+  publishedDate?: unknown;
+}
+
+function resolveExaApiKey(deps: ExaWebSearchDeps): string {
+  const fromEnvironment = deps.getEnv ? deps.getEnv('EXA_API_KEY') : process.env.EXA_API_KEY;
+  if (fromEnvironment?.trim()) return fromEnvironment.trim();
+  try {
+    const path = `${(deps.homeDir ?? homedir)()}/.cache/exa_api_key`;
+    return (deps.readFile ?? ((file) => readFileSync(file, 'utf8')))(path).trim();
+  } catch {
+    return '';
+  }
+}
+
+export function buildExaWebSearchProvider(deps: ExaWebSearchDeps = {}): WebSearchProvider {
+  return {
+    id: 'exa',
+    displayName: 'Exa',
+    available: () => resolveExaApiKey(deps).length > 0,
+    async search(query: WebSearchQuery, signal?: AbortSignal): Promise<WebSearchResult> {
+      const apiKey = resolveExaApiKey(deps);
+      if (!apiKey) throw new Error('Exa API key not configured');
+      const limit = Math.max(1, Math.min(query.limit ?? 5, 20));
+      let response: Response;
+      try {
+        response = await (deps.fetch ?? fetch)(EXA_SEARCH_API, {
+          method: 'POST',
+          headers: { 'x-api-key': apiKey, 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            query: query.query,
+            numResults: limit,
+            contents: { highlights: { maxCharacters: 500 } },
+          }),
+          signal,
+        });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(message.split(apiKey).join('[redacted]'));
+      }
+      if (!response.ok) throw new Error(`Exa search HTTP ${response.status}`);
+      const payload = await response.json() as { results?: ExaResult[] };
+      const hits: WebSearchHit[] = (Array.isArray(payload.results) ? payload.results : [])
+        .map((result) => ({
+          url: String(result.url ?? ''),
+          title: String(result.title ?? result.url ?? '(untitled)'),
+          snippet: Array.isArray(result.highlights)
+            ? result.highlights.filter((value): value is string => typeof value === 'string').join('\n')
+            : String(result.text ?? ''),
+          ...(typeof result.score === 'number' ? { score: result.score } : {}),
+          ...(typeof result.publishedDate === 'string' && !Number.isNaN(Date.parse(result.publishedDate))
+            ? { publishedAt: Date.parse(result.publishedDate) }
+            : {}),
+        }))
+        .filter((hit) => hit.url);
+      return { hits, providerName: 'exa', durationMs: 0 };
+    },
+  };
+}

package/src/web-search/index.ts

@@ -6,12 +6,13 @@
 // provider pass `providerId` to force the choice.
 
 import { buildGrokSubscriptionWebSearchProvider, buildGrokWebSearchProvider } from './grok.js';
+import { buildExaWebSearchProvider } from './exa.js';
 import { buildFirecrawlWebSearchProvider } from './firecrawl.js';
 import { buildTavilyWebSearchProvider } from './tavily.js';
 import { buildFreeWebSearchProvider } from './free.js';
 import { isPaidWebSearchEnabled, isTavilySearchEnabled } from '../user-config.js';
 import { debug } from '../debug/log.js';
-import { wantsXSearch } from './x-intent.js';
+import { wantsGrokSearch, wantsXSearch } from './x-intent.js';
 import {
   type WebSearchProvider,
   type WebSearchQuery,
@@ -27,17 +28,17 @@ export { WebSearchUnavailableError } from './provider.js';
  *  module load (before first call). Tests reset via
  *  _resetWebSearchProvidersForTests. */
 const providers: WebSearchProvider[] = [];
+let includeEnvironmentResearchExa = true;
 
 function registerBuiltins(): void {
-  // 순서 = 선호도. ⛔⭐ **tavily 는 config 게이트 뒤에 있다**(대표 2026-08-06 · 기본 OFF) —
-  //   상시 유료 검색이 고정비였다. 종전 근거(basic 1cr·~1s 로 grok 대비 30배 저렴·20배 빠름)는
-  //   여전히 참이지만 ***「싸다」와 「늘 켜 둔다」는 다른 축***이고, 지시는 후자를 껐다.
-  //   ⇒ 켜면 종전과 «똑같이» 1순위로 복귀한다: `elanous config set webSearch.tavily.enabled true`.
-  //   ⚠️ 등록 시점이라 config 변경은 **다음 기동부터** 먹는다(이미 뜬 프로세스엔 안 먹는다).
+  // General web cascade is Exa → Firecrawl; Grok is reserved for explicit X/Twitter intent.
+  // Other providers remain registered for explicit provider selection only.
+  // Provider registration snapshots config at module load; changing these gates requires a process restart.
+  providers.push(buildExaWebSearchProvider());
+  if (isPaidWebSearchEnabled('firecrawl')) providers.push(buildFirecrawlWebSearchProvider());
   if (isTavilySearchEnabled()) providers.push(buildTavilyWebSearchProvider());
   providers.push(buildGrokSubscriptionWebSearchProvider());
   if (isPaidWebSearchEnabled('grokApi')) providers.push(buildGrokWebSearchProvider({ id: 'grok-api' }));
-  if (isPaidWebSearchEnabled('firecrawl')) providers.push(buildFirecrawlWebSearchProvider());
   providers.push(buildFreeWebSearchProvider());
 }
 registerBuiltins();
@@ -70,14 +71,22 @@ export async function searchWeb(
   opts: { providerId?: string; signal?: AbortSignal } = {},
 ): Promise<WebSearchResult> {
   const xIntent = !opts.providerId && wantsXSearch(q.query);
+  const grokIntent = !opts.providerId && wantsGrokSearch(q.query);
   const candidates = opts.providerId
     ? providers.filter(p => p.id === opts.providerId || (opts.providerId === 'grok' && p.id === 'grok-api'))
-    : providers.filter(p => p.available());
-  if (xIntent) {
+    : providers.filter(p => p.available() && (grokIntent
+      ? p.id === 'grok' || p.id === 'grok-api' || p.id === 'exa' || p.id === 'firecrawl'
+      : p.id === 'exa' || p.id === 'firecrawl'));
+  if (grokIntent) {
     const grokIndex = candidates.findIndex(p => p.id === 'grok' || p.id === 'grok-api');
     if (grokIndex > 0) candidates.unshift(...candidates.splice(grokIndex, 1));
   }
   if (candidates.length === 0) {
+    const ordinaryProviderAvailable = providers.some(provider => provider.available() && (provider.id === 'exa' || provider.id === 'firecrawl'));
+    const grokAvailable = providers.some(provider => provider.available() && (provider.id === 'grok' || provider.id === 'grok-api'));
+    if (!opts.providerId && !grokIntent && grokAvailable && !ordinaryProviderAvailable) {
+      throw new WebSearchUnavailableError(['grok'], ['policy:Grok is reserved for explicit X/Twitter searches. Configure Exa or Firecrawl for general web search.']);
+    }
     throw new WebSearchUnavailableError(
       providers.map(p => p.id),
       providers.map(p => p.available() ? 'available (but id filter skipped)' : 'unavailable (check keys/binaries)'),
@@ -123,6 +132,8 @@ export async function searchWeb(
  *  providers. Kept separate from the public API. */
 export function _resetWebSearchProvidersForTests(includeBuiltins = true): void {
   providers.length = 0;
+  // `false` means tests want a credential-independent provider set, including research discovery.
+  includeEnvironmentResearchExa = includeBuiltins;
   if (includeBuiltins) registerBuiltins();
 }
 
@@ -132,3 +143,13 @@ export function _resetWebSearchProvidersForTests(includeBuiltins = true): void {
 export function getAvailableWebSearchProviders(): WebSearchProvider[] {
   return providers.filter(p => p.available());
 }
+
+/** Research-only provider snapshot. Exa stays out of the general registry/cascade so
+ * adding a research credential cannot change ordinary WebSearch or OmniSearch defaults. */
+export function getAvailableResearchWebSearchProviders(): WebSearchProvider[] {
+  const available = getAvailableWebSearchProviders();
+  if (available.some(provider => provider.id === 'exa')) return available;
+  if (!includeEnvironmentResearchExa) return available;
+  const exa = buildExaWebSearchProvider();
+  return exa.available() ? [...available, exa] : available;
+}

package/src/web-search/provider.ts

@@ -70,8 +70,11 @@ export interface WebSearchResult {
  *  a clear hint instead of treating it as a generic tool error. */
 export class WebSearchUnavailableError extends Error {
   constructor(public providers: string[], public reasons: string[]) {
+    const policyMessage = providers.length === 1 && reasons[0]?.startsWith('policy:') ? reasons[0]!.slice('policy:'.length) : undefined;
     super(
-      providers.length === 0
+      policyMessage
+        ? policyMessage
+        : providers.length === 0
         ? 'No web-search providers are registered. Register one via addWebSearchProvider() or enable the built-in Grok adapter by setting a Grok API key.'
         : `All registered web-search providers failed: ${providers.map((p, i) => `${p}: ${reasons[i] ?? 'unknown'}`).join('; ')}`,
     );

package/src/web-search/x-intent.ts

@@ -3,3 +3,8 @@ export function wantsXSearch(query: string): boolean {
   return /(?:^|[^\p{L}\p{N}_])(?:x에서|엑스에서|x\s+(?:반응|여론)|트위터(?:에서|의|에|로|는|가)?|트윗(?:에서|의|을|이|들|은|도)?)(?![\p{L}\p{N}_])/iu.test(query)
     || /(?:^|[^\p{L}\p{N}_])(?:x\.com(?![\p{L}\p{N}_.-])|twitter(?:\.com)?(?![\p{L}\p{N}_])|on\s+x(?![\p{L}\p{N}_])|x\s+reactions?(?![\p{L}\p{N}_]))/iu.test(query);
 }
+
+/** Grok is reserved for explicit X/Twitter intent; general freshness/community queries stay on web search. */
+export function wantsGrokSearch(query: string): boolean {
+  return wantsXSearch(query);
+}