acdev 1.0.10 → 1.0.11

package/src/config.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { checkClaudeAuth, publicClaudeAuthMethod } from './claude-auth.js';
+import { checkOpenRouterAuth } from './openrouter-auth.js';
 import { maskSecret } from './env.js';
 import { checkGhAuth, githubTokenFromEnv, originRemoteInfo } from './gh-auth.js';
 import { normalizeJiraBaseUrl } from './jira.js';
@@ -10,7 +11,10 @@ import {
   isValidModelId,
   isNoModel,
   isClaudeCatalogId,
+  isOpenRouterModelId,
+  isModelIdForProvider,
   curatedModelOptions,
+  OPENROUTER_MODEL_OPTIONS,
 } from './models.js';
 import { dataDir } from './paths.js';
 
@@ -21,6 +25,9 @@ export const KNOWN_TOOLS = ['Read', 'Glob', 'Grep', 'Edit', 'Write', 'Bash'];
 
 export const TICKET_SOURCES = /** @type {const} */ (['github', 'jira']);
 
+/** LLM backends. Claude = Agent SDK; OpenRouter = @openrouter/agent. */
+export const LLM_PROVIDERS = /** @type {const} */ (['claude', 'openrouter']);
+
 /**
  * Shared post-PR actions for Jira and GitHub Issues rules.
  * - Jira `set_status` / `close_issue`: workflow transitions (close → Done-like status).
@@ -39,6 +46,7 @@ export const GITHUB_AFTER_PR_ACTIONS = AFTER_PR_ACTIONS;
 
 const ALLOWED_TOOLS_SET = new Set(KNOWN_TOOLS);
 const ALLOWED_TICKET_SOURCES = new Set(TICKET_SOURCES);
+const ALLOWED_LLM_PROVIDERS = new Set(LLM_PROVIDERS);
 const ALLOWED_AFTER_PR_ACTIONS = new Set(AFTER_PR_ACTIONS);
 
 /** @typedef {'none' | 'set_status' | 'add_label' | 'close_issue'} AfterPrAction */
@@ -65,6 +73,8 @@ const DEFAULTS = {
   allowedTools: [...KNOWN_TOOLS],
   agentTimeoutMs: 900_000,
   model: DEFAULT_MODEL,
+  llmProvider: /** @type {'claude' | 'openrouter'} */ ('claude'),
+  lastModelsByProvider: /** @type {{ claude?: string, openrouter?: string }} */ ({}),
   ticketSource: /** @type {'github' | 'jira'} */ ('github'),
   jiraBaseUrl: '',
   /** PR body phrase for Jira tickets, e.g. "Relates to PROJ-123". */
@@ -73,6 +83,55 @@ const DEFAULTS = {
   githubRules: structuredClone(DEFAULT_GITHUB_RULES),
 };
 
+/**
+ * @param {unknown} value
+ * @returns {'claude' | 'openrouter'}
+ */
+export function normalizeLlmProvider(value) {
+  return value === 'openrouter' ? 'openrouter' : 'claude';
+}
+
+/**
+ * @param {unknown} raw
+ * @returns {{ claude?: string, openrouter?: string }}
+ */
+function normalizeLastModelsByProvider(raw) {
+  /** @type {{ claude?: string, openrouter?: string }} */
+  const out = {};
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return out;
+  const obj = /** @type {Record<string, unknown>} */ (raw);
+  if (typeof obj.claude === 'string' && isValidModelId(obj.claude.trim()) && isClaudeCatalogId(obj.claude.trim())) {
+    out.claude = obj.claude.trim();
+  }
+  if (
+    typeof obj.openrouter === 'string' &&
+    isValidModelId(obj.openrouter.trim()) &&
+    isOpenRouterModelId(obj.openrouter.trim())
+  ) {
+    out.openrouter = obj.openrouter.trim();
+  }
+  return out;
+}
+
+function rememberCurrentModel(config) {
+  const provider = normalizeLlmProvider(config.llmProvider);
+  const prev = normalizeLastModelsByProvider(config.lastModelsByProvider);
+  if (!isNoModel(config.model) && isModelIdForProvider(config.model, provider)) {
+    prev[provider] = String(config.model).trim();
+  }
+  config.lastModelsByProvider = prev;
+}
+
+function restoreModelForProvider(config, provider) {
+  const last = normalizeLastModelsByProvider(config.lastModelsByProvider);
+  const stored = last[provider];
+  if (stored && isModelIdForProvider(stored, provider)) {
+    config.model = stored;
+    return;
+  }
+  config.model = provider === 'openrouter' ? NO_MODEL : DEFAULT_MODEL;
+}
+
 /**
  * Migrate legacy OpenRouter model ids to a Claude model.
  * @param {unknown} raw
@@ -240,6 +299,8 @@ function persistable(config) {
     allowedTools: config.allowedTools,
     agentTimeoutMs: config.agentTimeoutMs,
     model: config.model,
+    llmProvider: normalizeLlmProvider(config.llmProvider),
+    lastModelsByProvider: normalizeLastModelsByProvider(config.lastModelsByProvider),
     ticketSource: config.ticketSource,
     jiraBaseUrl: config.jiraBaseUrl || '',
     jiraPrLinkPhrase: config.jiraPrLinkPhrase || 'Relates to',
@@ -297,6 +358,17 @@ export function loadConfig(repoRoot) {
 
   let needsSave = false;
 
+  if (raw.llmProvider === 'openrouter' || (isValidModelId(raw.model) && isOpenRouterModelId(String(raw.model)))) {
+    config.llmProvider = 'openrouter';
+  } else if (raw.llmProvider === 'claude' || raw.llmProvider == null) {
+    config.llmProvider = 'claude';
+  } else if (!ALLOWED_LLM_PROVIDERS.has(raw.llmProvider)) {
+    config.llmProvider = 'claude';
+    needsSave = true;
+  }
+
+  config.lastModelsByProvider = normalizeLastModelsByProvider(raw.lastModelsByProvider);
+
   if (isNoModel(config.model)) {
     if (String(config.model).trim() !== NO_MODEL) {
       config.model = NO_MODEL;
@@ -305,8 +377,14 @@ export function loadConfig(repoRoot) {
       config.model = NO_MODEL;
     }
   } else if (!isValidModelId(config.model)) {
-    config.model = DEFAULT_MODEL;
+    config.model = config.llmProvider === 'openrouter' ? NO_MODEL : DEFAULT_MODEL;
     needsSave = true;
+  } else if (config.llmProvider === 'openrouter') {
+    config.model = String(config.model).trim();
+    if (!isOpenRouterModelId(config.model)) {
+      restoreModelForProvider(config, 'openrouter');
+      needsSave = true;
+    }
   } else {
     const migrated = migrateLegacyModel(raw, config.model);
     if (migrated !== String(config.model).trim()) {
@@ -317,9 +395,7 @@ export function loadConfig(repoRoot) {
     }
   }
 
-  if (raw.llmProvider === 'openrouter' || raw.lastModelsByProvider != null) {
-    needsSave = true;
-  }
+  rememberCurrentModel(config);
 
   if (!ALLOWED_TICKET_SOURCES.has(config.ticketSource)) {
     config.ticketSource = 'github';
@@ -349,6 +425,24 @@ export function loadConfig(repoRoot) {
  * @returns {typeof DEFAULTS}
  */
 export function updateConfig(repoRoot, config, patch) {
+  if (patch.llmProvider !== undefined) {
+    if (!ALLOWED_LLM_PROVIDERS.has(patch.llmProvider)) {
+      throw new Error(
+        `Invalid llmProvider "${patch.llmProvider}". Allowed: ${LLM_PROVIDERS.join(', ')}`
+      );
+    }
+    const next = /** @type {'claude' | 'openrouter'} */ (patch.llmProvider);
+    if (next !== normalizeLlmProvider(config.llmProvider)) {
+      rememberCurrentModel(config);
+      config.llmProvider = next;
+      if (patch.model == null) {
+        restoreModelForProvider(config, next);
+      }
+    }
+  }
+
+  const provider = normalizeLlmProvider(config.llmProvider);
+
   if (patch.model != null) {
     if (isNoModel(patch.model)) {
       config.model = NO_MODEL;
@@ -356,15 +450,19 @@ export function updateConfig(repoRoot, config, patch) {
       throw new Error(
         `Invalid model "${patch.model}". Expected a non-empty model id or "${NO_MODEL}" for no selection`
       );
-    } else if (!isClaudeCatalogId(String(patch.model).trim())) {
+    } else if (!isModelIdForProvider(String(patch.model).trim(), provider)) {
       throw new Error(
-        `Invalid model "${patch.model}". Expected a Claude model id (no provider/ prefix)`
+        provider === 'openrouter'
+          ? `Invalid model "${patch.model}". Expected an OpenRouter model id (provider/model)`
+          : `Invalid model "${patch.model}". Expected a Claude model id (no provider/ prefix)`
       );
     } else {
       config.model = String(patch.model).trim();
     }
   }
 
+  rememberCurrentModel(config);
+
   if (patch.baseBranch !== undefined) {
     if (typeof patch.baseBranch !== 'string' || !patch.baseBranch.trim()) {
       throw new Error('baseBranch must be a non-empty string');
@@ -456,11 +554,14 @@ export function updateConfig(repoRoot, config, patch) {
  * }} [opts]
  */
 export function publicConfig(config, opts = {}) {
+  const llmProvider = normalizeLlmProvider(config.llmProvider);
   const model = isNoModel(config.model)
     ? NO_MODEL
-    : isValidModelId(config.model) && isClaudeCatalogId(config.model)
+    : isModelIdForProvider(config.model, llmProvider)
       ? String(config.model).trim()
-      : DEFAULT_MODEL;
+      : llmProvider === 'openrouter'
+        ? NO_MODEL
+        : DEFAULT_MODEL;
   const repoName = opts.repoRoot ? path.basename(opts.repoRoot) : undefined;
   const ticketSource = ALLOWED_TICKET_SOURCES.has(config.ticketSource)
     ? config.ticketSource
@@ -489,11 +590,19 @@ export function publicConfig(config, opts = {}) {
   const ghTokenMask = maskSecret(githubTokenFromEnv());
   const anthropicMask = maskSecret(process.env.ANTHROPIC_API_KEY);
   const claudeOauthMask = maskSecret(process.env.CLAUDE_CODE_OAUTH_TOKEN);
+  const openrouterMask = maskSecret(process.env.OPENROUTER_API_KEY);
+  const openrouterAuth = checkOpenRouterAuth();
+  const llmAuthOk = llmProvider === 'openrouter' ? openrouterAuth.ok : claudeAuth.ok === true;
 
-  const curatedModels = curatedModelOptions();
+  const curatedModels =
+    llmProvider === 'openrouter'
+      ? OPENROUTER_MODEL_OPTIONS.map((m) => ({ ...m }))
+      : curatedModelOptions();
 
   return {
     model,
+    llmProvider,
+    lastModelsByProvider: normalizeLastModelsByProvider(config.lastModelsByProvider),
     baseBranch: config.baseBranch,
     testCommand: config.testCommand ?? null,
     maxAgentTurns: config.maxAgentTurns,
@@ -525,7 +634,10 @@ export function publicConfig(config, opts = {}) {
     anthropicApiKeyMasked: anthropicMask.masked,
     claudeOauthTokenSet: claudeOauthMask.set,
     claudeOauthTokenMasked: claudeOauthMask.masked,
-    llmAuthOk: claudeAuth.ok === true,
+    openrouterApiKeySet: openrouterMask.set,
+    openrouterApiKeyMasked: openrouterMask.masked,
+    openrouterAuthOk: openrouterAuth.ok === true,
+    llmAuthOk,
     stubAgent: opts.stubAgent === true,
     ...(repoName ? { repoName } : {}),
   };

package/src/models.js

@@ -41,6 +41,16 @@ export const CLAUDE_MODEL_OPTIONS = [
 /** @deprecated Use CLAUDE_MODEL_OPTIONS */
 export const MODEL_OPTIONS = CLAUDE_MODEL_OPTIONS;
 
+/** Small fallback if OpenRouter's live catalog cannot be fetched. */
+export const OPENROUTER_MODEL_OPTIONS = [
+  { id: 'google/gemini-2.5-pro', label: 'Google: Gemini 2.5 Pro' },
+  { id: 'google/gemini-2.5-flash', label: 'Google: Gemini 2.5 Flash' },
+  { id: 'openai/gpt-4.1', label: 'OpenAI: GPT-4.1' },
+  { id: 'openai/gpt-4o', label: 'OpenAI: GPT-4o' },
+  { id: 'anthropic/claude-sonnet-4.5', label: 'Anthropic: Claude Sonnet 4.5' },
+  { id: 'anthropic/claude-opus-4.5', label: 'Anthropic: Claude Opus 4.5' },
+];
+
 export const DEFAULT_MODEL = 'claude-sonnet-5';
 
 /** Config value meaning no model selected (jobs blocked until user picks one). */
@@ -50,16 +60,19 @@ export const NO_MODEL = '-';
 export const MODEL_ID_RE = /^[a-zA-Z0-9][a-zA-Z0-9._:\/-]{0,127}$/;
 
 const ANTHROPIC_MODELS_URL = 'https://api.anthropic.com/v1/models';
+const OPENROUTER_MODELS_URL = 'https://openrouter.ai/api/v1/models';
 const ANTHROPIC_VERSION = '2023-06-01';
 const CACHE_TTL_MS = 5 * 60_000;
 const KEYCHAIN_SERVICE = 'Claude Code-credentials';
 
 /** @typedef {{ id: string, name?: string, label?: string }} ModelOption */
-/** @typedef {'anthropic' | 'fallback'} ModelsSource */
-/** @typedef {{ models: ModelOption[], selected: string, source: ModelsSource }} ModelsListResult */
+/** @typedef {'anthropic' | 'fallback' | 'openrouter' | 'openrouter-fallback'} ModelsSource */
+/** @typedef {{ models: ModelOption[], selected: string, source: ModelsSource, provider: 'claude' | 'openrouter' }} ModelsListResult */
 
-/** @type {{ expiresAt: number, result: Omit<ModelsListResult, 'selected'> } | null} */
-let cache = null;
+/** @type {{ expiresAt: number, result: Omit<ModelsListResult, 'selected' | 'provider'> } | null} */
+let claudeCache = null;
+/** @type {{ expiresAt: number, result: Omit<ModelsListResult, 'selected' | 'provider'> } | null} */
+let openrouterCache = null;
 
 /** @type {typeof fetch | null} */
 let fetchImpl = null;
@@ -98,7 +111,8 @@ export function _resetCredentialsTokenResolver() {
 }
 
 export function _resetModelsCache() {
-  cache = null;
+  claudeCache = null;
+  openrouterCache = null;
 }
 
 /**
@@ -166,13 +180,25 @@ export function isModelInCuratedCatalog(modelId) {
 }
 
 /**
- * Whether a model id is valid for Claude (direct ids without `/`).
+ * OpenRouter catalog ids are `provider/model` slugs.
+ * @param {string} id
+ * @returns {boolean}
+ */
+export function isOpenRouterModelId(id) {
+  return isValidModelId(id) && String(id).includes('/');
+}
+
+/**
+ * Whether a model id is valid for the given LLM provider.
  * @param {string} modelId
+ * @param {'claude' | 'openrouter'} [provider]
  * @returns {boolean}
  */
-export function isModelIdForProvider(modelId) {
+export function isModelIdForProvider(modelId, provider = 'claude') {
   if (isNoModel(modelId) || !isValidModelId(modelId)) return false;
-  return isClaudeCatalogId(String(modelId).trim());
+  const id = String(modelId).trim();
+  if (provider === 'openrouter') return isOpenRouterModelId(id);
+  return isClaudeCatalogId(id);
 }
 
 /**
@@ -394,21 +420,59 @@ export async function fetchAnthropicModels() {
 }
 
 /**
- * List Claude models for the UI.
+ * Fetch live models from OpenRouter (public catalog; key optional).
+ * @returns {Promise<ModelOption[]>}
+ */
+export async function fetchOpenRouterModels() {
+  const doFetch = fetchImpl || globalThis.fetch;
+  if (typeof doFetch !== 'function') {
+    throw new Error('fetch is not available');
+  }
+  /** @type {Record<string, string>} */
+  const headers = { Accept: 'application/json' };
+  const key = String(envResolver().OPENROUTER_API_KEY || '').trim();
+  if (key) headers.Authorization = `Bearer ${key}`;
+  const res = await doFetch(OPENROUTER_MODELS_URL, { method: 'GET', headers });
+  if (!res.ok) {
+    throw new Error(`OpenRouter Models API HTTP ${res.status}`);
+  }
+  const body = await res.json();
+  const rows = Array.isArray(body?.data) ? body.data : [];
+  /** @type {ModelOption[]} */
+  const models = [];
+  for (const row of rows) {
+    const id = typeof row?.id === 'string' ? row.id.trim() : '';
+    if (!isOpenRouterModelId(id)) continue;
+    const display =
+      typeof row.name === 'string'
+        ? row.name
+        : typeof row.display_name === 'string'
+          ? row.display_name
+          : '';
+    models.push(toOption(id, display));
+  }
+  if (models.length === 0) {
+    throw new Error('OpenRouter Models API returned no models');
+  }
+  return models;
+}
+
+/**
  * @param {{ selected?: string, force?: boolean }} [opts]
  * @returns {Promise<ModelsListResult>}
  */
-export async function listModels(opts = {}) {
+async function listClaudeModels(opts = {}) {
   const selectedRaw = opts.selected;
   const force = opts.force === true;
   const now = Date.now();
 
-  if (!force && cache && cache.expiresAt > now) {
-    const selected = reconcileModelForProvider(cache.result.models, selectedRaw);
+  if (!force && claudeCache && claudeCache.expiresAt > now) {
+    const selected = reconcileModelForProvider(claudeCache.result.models, selectedRaw);
     return {
-      ...cache.result,
-      models: cache.result.models,
+      ...claudeCache.result,
+      models: claudeCache.result.models,
       selected,
+      provider: 'claude',
     };
   }
 
@@ -420,13 +484,62 @@ export async function listModels(opts = {}) {
     const models = filterClaudeModels(mergeModelLists(curated, live));
     const selected = reconcileModelForProvider(models, selectedRaw);
     const result = { models, source: /** @type {ModelsSource} */ ('anthropic') };
-    cache = { expiresAt: now + CACHE_TTL_MS, result };
-    return { ...result, selected };
+    claudeCache = { expiresAt: now + CACHE_TTL_MS, result };
+    return { ...result, selected, provider: 'claude' };
   } catch {
     const models = curated;
     const selected = reconcileModelForProvider(models, selectedRaw);
     const result = { models, source: /** @type {ModelsSource} */ ('fallback') };
-    cache = { expiresAt: now + 30_000, result };
-    return { ...result, selected };
+    claudeCache = { expiresAt: now + 30_000, result };
+    return { ...result, selected, provider: 'claude' };
+  }
+}
+
+/**
+ * @param {{ selected?: string, force?: boolean }} [opts]
+ * @returns {Promise<ModelsListResult>}
+ */
+async function listOpenRouterModels(opts = {}) {
+  const selectedRaw = opts.selected;
+  const force = opts.force === true;
+  const now = Date.now();
+
+  if (!force && openrouterCache && openrouterCache.expiresAt > now) {
+    const selected = reconcileModelForProvider(openrouterCache.result.models, selectedRaw);
+    return {
+      ...openrouterCache.result,
+      models: openrouterCache.result.models,
+      selected,
+      provider: 'openrouter',
+    };
+  }
+
+  const curated = OPENROUTER_MODEL_OPTIONS.map((m) => ({ ...m }));
+
+  try {
+    const live = await fetchOpenRouterModels();
+    const models = mergeModelLists(curated, live);
+    const selected = reconcileModelForProvider(models, selectedRaw);
+    const result = { models, source: /** @type {ModelsSource} */ ('openrouter') };
+    openrouterCache = { expiresAt: now + CACHE_TTL_MS, result };
+    return { ...result, selected, provider: 'openrouter' };
+  } catch {
+    const models = curated;
+    const selected = reconcileModelForProvider(models, selectedRaw);
+    const result = { models, source: /** @type {ModelsSource} */ ('openrouter-fallback') };
+    openrouterCache = { expiresAt: now + 30_000, result };
+    return { ...result, selected, provider: 'openrouter' };
+  }
+}
+
+/**
+ * List models for the UI.
+ * @param {{ selected?: string, force?: boolean, provider?: 'claude' | 'openrouter' }} [opts]
+ * @returns {Promise<ModelsListResult>}
+ */
+export async function listModels(opts = {}) {
+  if (opts.provider === 'openrouter') {
+    return listOpenRouterModels(opts);
   }
+  return listClaudeModels(opts);
 }

package/src/openrouter-agent.js

@@ -0,0 +1,142 @@
+import { OpenRouter, stepCountIs } from '@openrouter/agent';
+import { extractUsageFromOpenRouter } from './usage.js';
+import { checkOpenRouterAuth, openRouterApiKey } from './openrouter-auth.js';
+import { buildOpenRouterCodingTools } from './openrouter-tools.js';
+
+/**
+ * @param {{
+ *   name?: string,
+ *   arguments?: unknown,
+ *   input?: unknown,
+ * }} call
+ */
+function toolUseEvent(call) {
+  const name = call?.name || 'tool';
+  const input = call?.arguments ?? call?.input ?? {};
+  return {
+    type: 'assistant',
+    message: {
+      content: [{ type: 'tool_use', name, input }],
+    },
+  };
+}
+
+/**
+ * Run the OpenRouter Agent SDK against a worktree with the same coding tools
+ * Claude Agent SDK exposes (Read/Glob/Grep/Edit/Write/Bash).
+ *
+ * @param {{
+ *   prompt: string,
+ *   worktreePath: string,
+ *   config: object,
+ *   onEvent: (message: unknown) => void,
+ *   callModelFn?: (args: object) => object,
+ * }} params
+ */
+export async function runOpenRouterQuery({
+  prompt,
+  worktreePath,
+  config,
+  onEvent,
+  callModelFn,
+}) {
+  const auth = checkOpenRouterAuth();
+  if (!auth.ok && !callModelFn) {
+    throw new Error(
+      'OpenRouter is not authenticated. Add OPENROUTER_API_KEY in Settings → Authentication.'
+    );
+  }
+
+  const timeoutMs = config.agentTimeoutMs ?? 900_000;
+  const maxTurns = Math.max(1, Number(config.maxAgentTurns) || 30);
+  const model = String(config.model || '').trim();
+  if (!model) {
+    throw new Error('No OpenRouter model selected');
+  }
+
+  const tools = buildOpenRouterCodingTools(worktreePath, config.allowedTools || []);
+  const abortController = new AbortController();
+  const started = Date.now();
+
+  const run = async () => {
+    let result;
+    if (callModelFn) {
+      result = callModelFn({
+        model,
+        input: prompt,
+        tools,
+        stopWhen: stepCountIs(maxTurns),
+        signal: abortController.signal,
+      });
+    } else {
+      const client = new OpenRouter({ apiKey: openRouterApiKey() });
+      result = client.callModel({
+        model,
+        input: prompt,
+        tools,
+        stopWhen: stepCountIs(maxTurns),
+        signal: abortController.signal,
+      });
+    }
+
+    if (result?.getToolCallsStream) {
+      void (async () => {
+        try {
+          for await (const call of result.getToolCallsStream()) {
+            onEvent(toolUseEvent(call));
+          }
+        } catch {
+          // stream may abort after success
+        }
+      })();
+    }
+
+    const resultText =
+      typeof result?.getText === 'function' ? await result.getText() : String(result ?? '');
+    let usageRaw = null;
+    if (typeof result?.getUsage === 'function') {
+      try {
+        usageRaw = await result.getUsage();
+      } catch {
+        usageRaw = null;
+      }
+    }
+
+    const usage = extractUsageFromOpenRouter(usageRaw, {
+      durationMs: Date.now() - started,
+      numTurns: usageRaw?.modelCalls,
+    });
+
+    const fakeResult = {
+      type: 'result',
+      subtype: 'success',
+      result: resultText,
+      num_turns: usage?.numTurns,
+      duration_ms: usage?.durationMs,
+      total_cost_usd: usage?.totalCostUsd,
+      usage: {
+        input_tokens: usage?.inputTokens,
+        output_tokens: usage?.outputTokens,
+        cache_read_input_tokens: usage?.cacheReadInputTokens,
+      },
+    };
+    onEvent(fakeResult);
+
+    return { resultText, usage };
+  };
+
+  let timeoutId;
+  try {
+    return await Promise.race([
+      run(),
+      new Promise((_, reject) => {
+        timeoutId = setTimeout(() => {
+          abortController.abort();
+          reject(new Error(`Agent timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+      }),
+    ]);
+  } finally {
+    if (timeoutId) clearTimeout(timeoutId);
+  }
+}

package/src/openrouter-auth.js

@@ -0,0 +1,41 @@
+/** @typedef {{ ok: true } | { ok: false, reason: 'missing' }} OpenRouterAuthResult */
+
+/** @type {() => NodeJS.ProcessEnv} */
+let envResolver = () => process.env;
+
+/** @param {() => NodeJS.ProcessEnv} fn */
+export function _setEnvResolver(fn) {
+  envResolver = fn;
+}
+
+export function _resetEnvResolver() {
+  envResolver = () => process.env;
+}
+
+/**
+ * OpenRouter API key from env (Settings writes OPENROUTER_API_KEY).
+ * @returns {string}
+ */
+export function openRouterApiKey() {
+  return String(envResolver().OPENROUTER_API_KEY || '').trim();
+}
+
+/**
+ * @returns {OpenRouterAuthResult}
+ */
+export function checkOpenRouterAuth() {
+  if (openRouterApiKey()) return { ok: true };
+  return { ok: false, reason: 'missing' };
+}
+
+/**
+ * @param {OpenRouterAuthResult} [_result]
+ */
+export function formatOpenRouterAuthError(_result) {
+  return [
+    '⚠ OpenRouter is not authenticated — server will still start.',
+    '  Open Settings → Authentication to add an OpenRouter API key',
+    '  (or set OPENROUTER_API_KEY in `.acdev/.env`).',
+    '  For UI-only testing without auth: pass `--stub-agent`.',
+  ].join('\n');
+}