amicus 1.0.0

package/src/sidecar/start.js

@@ -0,0 +1,251 @@
+/**
+ * Sidecar Start Operations - Handles starting new sidecar sessions
+ * Spec Reference: §4.1, §9
+ */
+
+const crypto = require('crypto');
+const fs = require('fs');
+
+const { buildContext } = require('./context-builder');
+const {
+  SessionPaths,
+  saveInitialContext,
+  finalizeSession,
+  outputSummary,
+  createHeartbeat,
+  HEARTBEAT_INTERVAL
+} = require('./session-utils');
+const { runInteractive, checkElectronAvailable } = require('./interactive');
+const { buildPrompts } = require('../prompt-builder');
+const { runHeadless } = require('../headless');
+const { logger } = require('../utils/logger');
+const { acquireLock, releaseLock } = require('../utils/session-lock');
+const { loadMcpConfig, parseMcpSpec } = require('../opencode-client');
+const { mapAgentToOpenCode } = require('../utils/agent-mapping');
+const { discoverParentMcps } = require('../utils/mcp-discovery');
+
+/** Generate a unique 8-character hex task ID */
+function generateTaskId() {
+  return crypto.randomBytes(4).toString('hex');
+}
+
+/** Create session directory and save metadata */
+function createSessionMetadata(taskId, project, options) {
+  const { model, prompt, briefing, noUi, headless, agent, thinking } = options;
+
+  const sessionDir = SessionPaths.sessionDir(project, taskId);
+  fs.mkdirSync(sessionDir, { recursive: true, mode: 0o700 });
+
+  const effectiveBriefing = prompt || briefing;
+  const isHeadless = noUi !== undefined ? noUi : headless;
+
+  // Preserve fields from existing metadata (e.g., pid written by MCP handler)
+  const metaPath = SessionPaths.metadataFile(sessionDir);
+  let existing = {};
+  if (fs.existsSync(metaPath)) {
+    try {
+      existing = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+    } catch {
+      // ignore corrupt metadata
+    }
+  }
+
+  const metadata = {
+    ...existing,
+    taskId,
+    model,
+    project,
+    briefing: effectiveBriefing,
+    mode: isHeadless ? 'headless' : 'interactive',
+    agent: agent || (isHeadless ? 'build' : 'chat'),
+    thinking: thinking || 'medium',
+    status: 'running',
+    pid: existing.pid || process.pid,
+    createdAt: existing.createdAt || new Date().toISOString()
+  };
+
+  fs.writeFileSync(metaPath, JSON.stringify(metadata, null, 2), { mode: 0o600 });
+
+  return sessionDir;
+}
+
+/**
+ * Build MCP configuration from options.
+ * Merge priority: CLI --mcp > --mcp-config > file config > discovered parent MCPs
+ *
+ * @param {object} options
+ * @param {string} [options.mcp] - CLI --mcp spec
+ * @param {string} [options.mcpConfig] - CLI --mcp-config path
+ * @param {string} [options.clientType] - Parent client type for discovery
+ * @param {boolean} [options.noMcp] - Skip MCP inheritance from parent
+ * @param {string[]} [options.excludeMcp] - Server names to exclude
+ * @returns {object|null} MCP server configs or null
+ */
+function buildMcpConfig(options) {
+  const { mcp, mcpConfig, clientType, noMcp, excludeMcp } = options;
+  let mcpServers = null;
+
+  // Layer 1: Discover parent MCPs (unless --no-mcp)
+  if (!noMcp) {
+    const discovered = discoverParentMcps(clientType);
+    if (discovered) {
+      mcpServers = { ...discovered };
+      logger.info('Discovered parent MCP servers', { serverCount: Object.keys(mcpServers).length });
+    }
+  }
+
+  // Layer 2: File config (opencode.json) overrides discovered
+  const fileConfig = loadMcpConfig(mcpConfig);
+  if (fileConfig) {
+    mcpServers = mcpServers ? { ...mcpServers, ...fileConfig } : { ...fileConfig };
+    logger.debug('Loaded MCP config from file', { serverCount: Object.keys(fileConfig).length });
+  }
+
+  // Layer 3: CLI --mcp (highest priority)
+  if (mcp) {
+    const parsed = parseMcpSpec(mcp);
+    if (parsed) {
+      mcpServers = mcpServers || {};
+      mcpServers[parsed.name] = parsed.config;
+      logger.debug('Added CLI MCP server', { name: parsed.name });
+    } else {
+      logger.warn('Invalid MCP server spec', { mcp });
+    }
+  }
+
+  // Always exclude the sidecar itself to prevent recursive spawning.
+  // When launched from Cowork, the discovered MCP list includes "sidecar"
+  // which would cause an infinite spawn loop.
+  if (mcpServers && mcpServers.sidecar) {
+    delete mcpServers.sidecar;
+    logger.debug('Auto-excluded sidecar MCP (recursive spawn prevention)');
+  }
+
+  // Apply explicit exclusions
+  if (excludeMcp && Array.isArray(excludeMcp) && mcpServers) {
+    for (const name of excludeMcp) {
+      if (mcpServers[name]) {
+        delete mcpServers[name];
+        logger.debug('Excluded MCP server', { name });
+      }
+    }
+  }
+
+  // Return null if all servers were excluded
+  if (mcpServers && Object.keys(mcpServers).length === 0) {
+    mcpServers = null;
+  }
+
+  return mcpServers;
+}
+
+/** Start a new sidecar session - Spec Reference: §4.1, §9 */
+async function startSidecar(options) {
+  const {
+    model, prompt, briefing, sessionId, session = 'current',
+    cwd, project = process.cwd(), contextTurns = 50, contextSince,
+    contextMaxTokens = 80000, noUi, headless = false, timeout = 15,
+    agent, mcp, mcpConfig, summaryLength = 'normal', thinking,
+    client, sessionDir, noMcp, excludeMcp, opencodePort, coworkProcess, includeContext = true,
+    position = 'right', json = false, modelInput = null
+  } = options;
+
+  const effectivePrompt = prompt || briefing;
+  const effectiveSession = sessionId || session;
+  const effectiveProject = cwd || project;
+  const effectiveHeadless = noUi !== undefined ? noUi : headless;
+  const mcpServers = buildMcpConfig({ mcp, mcpConfig, clientType: client, noMcp, excludeMcp });
+  const taskId = options.taskId || generateTaskId();
+  const reasoning = thinking ? { effort: thinking } : undefined;
+
+  logger.info('Starting task', { taskId, model, mode: effectiveHeadless ? 'headless' : 'interactive' });
+
+  const context = includeContext !== false
+    ? buildContext(effectiveProject, effectiveSession, { contextTurns, contextSince, contextMaxTokens, sessionDir, client, coworkProcess })
+    : '[Context excluded by caller - briefing is self-contained]';
+  const { system: systemPrompt, userMessage } = buildPrompts(
+    effectivePrompt, context, effectiveProject, effectiveHeadless, agent, summaryLength, client
+  );
+
+  const sessDir = createSessionMetadata(taskId, effectiveProject, {
+    model, prompt: effectivePrompt, noUi: effectiveHeadless, agent, thinking
+  });
+  saveInitialContext(sessDir, systemPrompt, userMessage);
+  acquireLock(sessDir, effectiveHeadless ? 'headless' : 'interactive');
+
+  const heartbeat = createHeartbeat(HEARTBEAT_INTERVAL, sessDir);
+  let summary;
+  let result;
+
+  try {
+    if (effectiveHeadless) {
+      try {
+        result = await runHeadless(
+          model, systemPrompt, userMessage, taskId, effectiveProject,
+          timeout * 60 * 1000, agent || 'build', { mcp: mcpServers, summaryLength, reasoning, port: opencodePort }
+        );
+      } catch (err) {
+        if (!json) { throw err; }
+        // --json contract: stdout must always carry a parseable run doc,
+        // even when the engine throws rather than returning {error}.
+        result = { summary: '', completed: false, timedOut: false, aborted: false, error: err.message, taskId };
+      }
+      summary = result.summary || '## Sidecar Results: No Output\n\nHeadless mode completed without summary.';
+      if (result.timedOut) { logger.warn('Task timed out', { taskId }); }
+      if (result.error) { logger.error('Task error', { taskId, error: result.error }); }
+    } else {
+      const effectiveAgent = mapAgentToOpenCode(agent).agent;
+      logger.info('Launching interactive sidecar', { taskId, model, agent: effectiveAgent });
+      result = await runInteractive(
+        model, systemPrompt, userMessage, taskId, effectiveProject,
+        { agent, mcp: mcpServers, reasoning, client, windowPosition: position }
+      );
+      summary = result.summary || '';
+      if (result.error) { logger.error('Interactive task error', { taskId, error: result.error }); }
+    }
+  } finally {
+    heartbeat.stop();
+    releaseLock(sessDir);
+  }
+
+  if (!json) { outputSummary(summary); }
+  const metaPath = SessionPaths.metadataFile(sessDir);
+  const meta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+
+  // Persist OpenCode session ID for resume capability
+  if (result && result.opencodeSessionId) {
+    meta.opencodeSessionId = result.opencodeSessionId;
+    fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2), { mode: 0o600 });
+  }
+
+  // Mark error results as 'error' instead of 'complete'
+  if (result && result.error) {
+    meta.status = 'error';
+    meta.reason = result.error;
+    meta.completedAt = new Date().toISOString();
+    fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2), { mode: 0o600 });
+    logger.error('Session completed with error', { taskId, error: result.error });
+  } else {
+    finalizeSession(sessDir, summary, effectiveProject, meta, { quietStdout: json });
+  }
+
+  if (json) {
+    const { buildRunResult } = require('../utils/result-schema');
+    const finalMeta = JSON.parse(fs.readFileSync(metaPath, 'utf-8'));
+    const doc = buildRunResult({
+      taskId, metadata: finalMeta, result, summary,
+      modelInput, sessionDir: sessDir,
+    });
+    console.log(JSON.stringify(doc, null, 2));
+  }
+}
+
+module.exports = {
+  generateTaskId,
+  createSessionMetadata,
+  buildMcpConfig,
+  checkElectronAvailable,
+  runInteractive,
+  startSidecar,
+  HEARTBEAT_INTERVAL
+};

package/src/utils/agent-mapping.js

@@ -0,0 +1,138 @@
+/**
+ * Agent Mapping Module
+ *
+ * Maps agent names to OpenCode's native agent framework.
+ *
+ * OpenCode Native Agents (https://opencode.ai/docs/agents/):
+ *   - Chat: Reads auto, writes/bash ask permission (interactive default)
+ *   - Build: Default primary agent with full tool access
+ *   - Plan: Read-only agent for analysis and planning
+ *   - General: Full-access agent for research
+ *   - Explore: Read-only agent for codebase exploration
+ *
+ * Custom agents defined in ~/.config/opencode/agents/ or .opencode/agents/
+ * are passed through directly to OpenCode.
+ */
+
+/**
+ * OpenCode's primary agent names (for main sessions)
+ * Note: OpenCode API expects lowercase agent names
+ * 'chat' is a custom sidecar agent: reads auto, writes/bash ask. When client=cowork, gets a general-purpose prompt.
+ */
+const PRIMARY_AGENTS = ['chat', 'build', 'plan'];
+
+/**
+ * All OpenCode native agent names (lowercase)
+ */
+const OPENCODE_AGENTS = [...PRIMARY_AGENTS, 'general', 'explore'];
+
+/**
+ * Agents safe for headless (--no-ui) mode.
+ * 'chat' requires user permission for writes/bash and stalls in headless.
+ */
+const HEADLESS_SAFE_AGENTS = ['build', 'plan', 'explore', 'general'];
+
+/**
+ * Map an agent name to OpenCode native agent configuration
+ *
+ * @param {string} agent - Agent name (OpenCode native or custom)
+ * @returns {{agent: string}} OpenCode agent configuration
+ *
+ * @example
+ * mapAgentToOpenCode('Build')   // { agent: 'build' }
+ * mapAgentToOpenCode('Plan')    // { agent: 'plan' }
+ * mapAgentToOpenCode('custom')  // { agent: 'custom' }
+ */
+function mapAgentToOpenCode(agent) {
+  // Handle undefined/null/empty - default to chat (reads auto, writes ask)
+  if (!agent || (typeof agent === 'string' && agent.trim() === '')) {
+    return { agent: 'chat' };
+  }
+
+  // Normalize for case-insensitive matching of native agents
+  const normalized = agent.toLowerCase();
+
+  // Check if it's an OpenCode native agent (case-insensitive match)
+  const nativeMatch = OPENCODE_AGENTS.find(
+    native => native === normalized
+  );
+  if (nativeMatch) {
+    return { agent: nativeMatch };
+  }
+
+  // Pass through custom agent names as lowercase (OpenCode API expects lowercase)
+  return { agent: normalized };
+}
+
+/**
+ * Check if an agent is safe for headless (--no-ui) mode
+ *
+ * @param {string} agent - Agent name to check
+ * @returns {boolean|null} true if safe, false if unsafe (chat), null if unknown/custom
+ */
+function isHeadlessSafe(agent) {
+  if (!agent || (typeof agent === 'string' && agent.trim() === '')) {
+    return null;
+  }
+
+  const normalized = agent.toLowerCase();
+
+  if (HEADLESS_SAFE_AGENTS.includes(normalized)) {
+    return true;
+  }
+
+  if (normalized === 'chat') {
+    return false;
+  }
+
+  // Unknown/custom agents — we can't determine safety
+  return null;
+}
+
+/**
+ * Check if an agent name is valid for primary sessions
+ *
+ * @param {string} agent - Agent name to validate
+ * @returns {boolean} True if valid primary agent or custom agent
+ */
+function isValidPrimaryAgent(agent) {
+  if (!isValidAgent(agent)) {
+    return false;
+  }
+
+  // All non-empty strings are valid (custom agents allowed)
+  return true;
+}
+
+/**
+ * Check if an agent name is valid (non-empty string)
+ *
+ * All non-empty agent names are considered valid because:
+ * 1. OpenCode native agents (Build, Plan, General, Explore) are always valid
+ * 2. Custom agents defined in user's agent directory should be allowed
+ *    (OpenCode will validate at runtime)
+ *
+ * @param {string} agent - Agent name to validate
+ * @returns {boolean} True if valid (non-empty string)
+ */
+function isValidAgent(agent) {
+  if (agent === null || agent === undefined) {
+    return false;
+  }
+
+  if (typeof agent !== 'string') {
+    return false;
+  }
+
+  return agent.trim().length > 0;
+}
+
+module.exports = {
+  PRIMARY_AGENTS,
+  OPENCODE_AGENTS,
+  HEADLESS_SAFE_AGENTS,
+  mapAgentToOpenCode,
+  isValidAgent,
+  isHeadlessSafe,
+  isValidPrimaryAgent
+};

package/src/utils/alias-audit.js

@@ -0,0 +1,98 @@
+/**
+ * Alias Audit (F5) — report + suggest, never auto-repair.
+ *
+ * Finds aliases/routes pointing at models absent from the catalog and
+ * suggests current same-vendor replacements. Pure functions over inputs;
+ * collectAliasSources() does the gathering. Consumed by `amicus models
+ * --check` and the npm wrapper scripts.
+ */
+
+'use strict';
+
+/**
+ * @returns {Array<{alias,model,source}>} every alias mapping we ship or the user set
+ * Identical (alias, model) pairs are deduped, first source wins — defaults derive from curated
+ * routes, so every default would otherwise double-report. A user --add-alias override creates a
+ * distinct user-config row; shipped defaults/curated routes stay audited until curated-models.js
+ * itself is updated.
+ */
+function collectAliasSources() {
+  const { getDefaultAliases, loadConfig } = require('./config');
+  const { listCuratedRoutes } = require('./curated-models');
+  const out = [];
+  for (const [alias, model] of Object.entries(getDefaultAliases())) {
+    out.push({ alias, model, source: 'defaults' });
+  }
+  const cfg = loadConfig();
+  for (const [alias, model] of Object.entries((cfg && cfg.aliases) || {})) {
+    if (typeof model === 'string' && model) {
+      out.push({ alias, model, source: 'user-config' });
+    }
+  }
+  for (const r of listCuratedRoutes()) {
+    out.push({ alias: r.alias, model: r.model, source: `curated-route (${r.provider})` });
+  }
+  const seen = new Set();
+  return out.filter(({ alias, model }) => {
+    const key = `${alias} ${model}`;
+    if (seen.has(key)) { return false; }
+    seen.add(key);
+    return true;
+  });
+}
+
+/** Catalog ids grouped by leading provider segment, e.g. 'openrouter', 'google'. */
+function idsByProvider(catalog) {
+  const map = new Map();
+  for (const m of catalog) {
+    if (!(m && typeof m.id === 'string')) { continue; }
+    const provider = m.id.split('/')[0];
+    if (!map.has(provider)) { map.set(provider, new Set()); }
+    map.get(provider).add(m.id);
+  }
+  return map;
+}
+
+/**
+ * Entries whose model is absent from the catalog. A model is only checkable
+ * when its provider has rows in the catalog (unkeyed providers never produce
+ * false stales). Empty catalog → [] (cannot check).
+ * @param {Array<{alias,model,source}>} sources
+ * @param {Array<{id:string}>} catalog
+ */
+function findStaleAliases(sources, catalog) {
+  if (!catalog || catalog.length === 0) { return []; }
+  const byProvider = idsByProvider(catalog);
+  return sources.filter(({ model }) => {
+    const provider = model.split('/')[0];
+    const ids = byProvider.get(provider);
+    if (!ids) { return false; } // provider unverifiable
+    return !ids.has(model);
+  });
+}
+
+/**
+ * Same-vendor replacement candidates for a stale model id, ranked by
+ * shared-prefix length with the stale id (desc), then id descending so
+ * higher version numbers sort first. Deterministic; max n.
+ * @param {string} staleModel - e.g. 'openrouter/x-ai/grok-4.1-fast'
+ * @param {Array<{id:string}>} catalog
+ * @param {number} [n=3]
+ * @returns {string[]} candidate ids
+ */
+function suggestReplacements(staleModel, catalog, n = 3) {
+  const vendorPrefix = staleModel.split('/').slice(0, -1).join('/') + '/';
+  const sharedLen = (a, b) => {
+    let i = 0;
+    while (i < a.length && i < b.length && a[i] === b[i]) { i++; }
+    return i;
+  };
+  return catalog
+    .filter(m => m && typeof m.id === 'string').map(m => m.id)
+    .filter(id => id.startsWith(vendorPrefix) && id !== staleModel)
+    .sort((a, b) =>
+      (sharedLen(b, staleModel) - sharedLen(a, staleModel)) || b.localeCompare(a, 'en', { numeric: true }))
+    .slice(0, n);
+}
+
+module.exports = { collectAliasSources, findStaleAliases, suggestReplacements };

package/src/utils/alias-resolver.js

@@ -0,0 +1,77 @@
+/**
+ * Alias Resolver Utilities
+ *
+ * Handles alias auto-repair and direct API fallback logic,
+ * extracted from config.js to keep it under the 300-line limit.
+ */
+
+const { PROVIDER_ENV_MAP, readApiKeyValues } = require('./api-key-store');
+const { logger } = require('./logger');
+
+/**
+ * Strip openrouter/ prefix when direct provider API key is available
+ * but OPENROUTER_API_KEY is not.
+ * @param {string} model - Full model identifier
+ * @returns {string} Model with or without openrouter/ prefix
+ */
+function applyDirectApiFallback(model) {
+  if (!model.startsWith('openrouter/')) {
+    return model;
+  }
+  const persistedKeys = readApiKeyValues();
+  if (process.env.OPENROUTER_API_KEY || persistedKeys.openrouter) {
+    return model;
+  }
+  const direct = model.slice('openrouter/'.length);
+  const provider = direct.split('/')[0];
+  const envVar = PROVIDER_ENV_MAP[provider];
+  if (envVar && (process.env[envVar] || persistedKeys[provider])) {
+    logger.warn({ msg: 'Using direct provider API (OPENROUTER_API_KEY not set)', original: model, resolved: direct });
+    process.stderr.write(
+      `Notice: Using direct ${provider} API (OPENROUTER_API_KEY not set). ` +
+      'Model availability is validated automatically; pass --no-validate-model to skip.\n'
+    );
+    return direct;
+  }
+  return model;
+}
+
+/**
+ * Auto-repair a null alias by falling back to DEFAULT_ALIASES.
+ * Updates config on disk and warns to stderr.
+ * @param {string} alias - The alias name with null value
+ * @param {object|null} config - Current config object
+ * @param {object} defaultAliases - DEFAULT_ALIASES map
+ * @param {Function} saveConfig - saveConfig function reference
+ * @returns {string} Repaired model string
+ * @throws {Error} If no default exists for this alias
+ */
+function autoRepairAlias(alias, config, defaultAliases, saveConfig) {
+  const defaultModel = defaultAliases[alias];
+  if (defaultModel) {
+    process.stderr.write(
+      `Notice: Auto-repaired null alias '${alias}' -> '${defaultModel}'\n`
+    );
+    if (config && config.aliases) {
+      config.aliases[alias] = defaultModel;
+      try {
+        saveConfig(config);
+      } catch (err) {
+        process.stderr.write(
+          `Notice: Could not persist repaired alias '${alias}' (${err.message}). ` +
+          'Using default for this session only.\n'
+        );
+      }
+    }
+    return applyDirectApiFallback(defaultModel);
+  }
+  throw new Error(
+    `Alias '${alias}' is configured but has no model value. ` +
+    `Fix with: sidecar setup --add-alias ${alias}=provider/model`
+  );
+}
+
+module.exports = {
+  applyDirectApiFallback,
+  autoRepairAlias,
+};