amicus 1.3.0 → 1.5.0

package/src/mcp-tools.js

@@ -255,8 +255,11 @@ function getTools() {
       'document (per-leg summaries inside). Each leg is also an ordinary ' +
       'session readable by taskId.',
     inputSchema: {
-      models: z.array(safeModel).min(1).max(10).describe(
-        `1-10 models (2+ for genuine fan-out). Short aliases (${aliasNames}) or full provider/model IDs. Duplicates allowed.`
+      models: z.array(safeModel).min(1).max(10).optional().describe(
+        `1-10 models (2+ for genuine fan-out). Short aliases (${aliasNames}) or full provider/model IDs. Duplicates allowed. Omit when using 'council'.`
+      ),
+      council: z.string().optional().describe(
+        "Run a saved council by name (e.g. 'free') instead of 'models'. Expands to the council's members. Mutually exclusive with 'models'."
       ),
       prompt: z.string().describe(
         'The briefing sent to every model. Self-contained briefings work best (set includeContext false).'

package/src/sidecar/setup.js

@@ -40,19 +40,23 @@ function addAlias(name, modelString) {
 }
 
 /**
- * Create a new config with all default aliases and the chosen default model
+ * Ensure a config exists with the chosen default model. Read-modify-write:
+ * preserves every pre-existing top-level key (aliases, councils, …) and only
+ * fills in the default + any missing default aliases. Never clobbers.
  * @param {string} defaultModel - Default model alias or full model string
- * @returns {object} The created config object
+ * @returns {object} The resulting config object
  */
 function createDefaultConfig(defaultModel) {
+  const existing = loadConfig() || {};
   const cfg = {
-    default: defaultModel,
-    aliases: getDefaultAliases()
+    ...existing,
+    default: existing.default || defaultModel,
+    aliases: { ...getDefaultAliases(), ...(existing.aliases || {}) },
   };
   saveConfig(cfg);
-  logger.info('Default config created', {
-    default: defaultModel,
-    aliasCount: Object.keys(cfg.aliases).length
+  logger.info('Default config ensured', {
+    default: cfg.default,
+    aliasCount: Object.keys(cfg.aliases).length,
   });
   return cfg;
 }
@@ -152,13 +156,70 @@ async function seedCatalog(print) {
   log('Model catalog unavailable (offline?) — it will refresh on first start.');
 }
 
+/**
+ * Free OpenRouter council branch of the readline wizard. Requires
+ * OPENROUTER_API_KEY; lists free catalog models, lets the user multi-pick
+ * (Enter = the vendor-diverse default), seeds aliases + councils.free, and
+ * never touches config.default.
+ * @param {readline.Interface} rl
+ */
+async function runFreeCouncilBranch(rl) {
+  const keys = detectApiKeys();
+  if (!keys.openrouter) {
+    console.log('');
+    console.log('A free council needs OPENROUTER_API_KEY (free models route only through OpenRouter).');
+    console.log('Set OPENROUTER_API_KEY and re-run: amicus setup. No changes made.');
+    return;
+  }
+  const { getCatalog } = require('../utils/model-catalog');
+  const { listFreeModels, suggestFreeCouncil, PINNED_FREE_MODELS } = require('../utils/free-models');
+  let catalog = [];
+  try { catalog = await getCatalog(); } catch (_e) { /* offline */ }
+  let free = listFreeModels(catalog);
+  if (free.length === 0) {
+    console.log('Live free-model list unavailable (offline?) — using a small pinned set.');
+    free = PINNED_FREE_MODELS.map(id => ({ id }));
+  }
+  const defaults = new Set(suggestFreeCouncil(free, 3).map(r => r.id));
+  console.log('');
+  console.log('Free OpenRouter models (★ = default council):');
+  free.forEach((r, i) => {
+    const star = defaults.has(r.id) ? '★' : ' ';
+    console.log(`  ${star} ${i + 1}) ${r.id}`);
+  });
+  console.log('');
+  const answer = await askQuestion(rl,
+    'Pick members (comma-separated numbers, or Enter for the ★ default): ');
+  let pickIds;
+  if (!answer) {
+    pickIds = free.filter(r => defaults.has(r.id)).map(r => r.id);
+  } else {
+    pickIds = answer.split(',').map(s => parseInt(s.trim(), 10))
+      .filter(n => n >= 1 && n <= free.length).map(n => free[n - 1].id);
+  }
+  if (pickIds.length < 2) {
+    console.log('A council needs at least 2 models. No changes made.');
+    return;
+  }
+  const { council } = seedFreeCouncil(pickIds);
+  await seedCatalog();
+  console.log('');
+  console.log(`Free council saved: councils.free = [${council.join(', ')}]`);
+  console.log('Run it:   amicus fanout --council free --prompt "..."');
+  console.log('config.default left unchanged.');
+  console.log('');
+  console.log('Heads up (free tier): rate-limited & quality-variable; some models 404');
+  console.log('unless you enable data-sharing at openrouter.ai/settings/privacy.');
+}
+
 /**
  * Run the readline-based setup wizard (headless fallback)
  *
  * Guides the user through:
  * 1. API key detection
- * 2. Default model selection from live quick-picks (read-modify-write, no clobber)
- * 3. Config file save
+ * 2. Mode selection (standard or free council)
+ * 3. Default model selection from live quick-picks (read-modify-write, no clobber)
+ * 4. Config file save
  */
 async function runReadlineSetup() {
   const rl = readline.createInterface({
@@ -185,6 +246,13 @@ async function runReadlineSetup() {
     }
     console.log('');
 
+    const mode = await askQuestion(rl,
+      'Setup mode — 1) Standard (pick a default model)  2) Free OpenRouter council: ');
+    if (mode === '2') {
+      await runFreeCouncilBranch(rl);
+      return;
+    }
+
     const { getCatalog } = require('../utils/model-catalog');
     const { resolveQuickPicks, toLiveSeedAliases } = require('../utils/quick-picks');
     let catalog = [];
@@ -282,12 +350,64 @@ async function runInteractiveSetup() {
 
 /* eslint-enable no-console */
 
+/**
+ * Collision-safe alias name from a free model id. Strips the openrouter/
+ * prefix and trailing :free, sanitizes '/'/':' to '-', prefixes 'free-',
+ * and disambiguates against `taken` with a numeric suffix.
+ * @param {string} id e.g. openrouter/deepseek/deepseek-r1:free
+ * @param {Set<string>} taken alias names already in use
+ * @returns {string} e.g. free-deepseek-deepseek-r1
+ */
+function deriveFreeAlias(id, taken) {
+  const base = 'free-' + id
+    .replace(/^openrouter\//, '')
+    .replace(/:free$/, '')
+    .replace(/[/:]/g, '-')
+    .replace(/-+/g, '-');
+  let name = base;
+  let n = 2;
+  while (taken.has(name)) { name = `${base}-${n++}`; }
+  taken.add(name);
+  return name;
+}
+
+/**
+ * Seed free-model aliases + councils.free from chosen catalog ids.
+ * Single atomic read-modify-write. Reuses an existing alias that already
+ * maps to the same id (idempotent re-runs); never touches config.default.
+ * @param {string[]} pickIds full openrouter/.../...:free ids
+ * @returns {{added: Array<{alias:string, model:string}>, council: string[]}}
+ */
+function seedFreeCouncil(pickIds) {
+  const cfg = loadConfig() || { aliases: {} };
+  if (!cfg.aliases) { cfg.aliases = {}; }
+  const taken = new Set(Object.keys(cfg.aliases));
+  const council = [];
+  const added = [];
+  for (const id of pickIds) {
+    const existing = Object.entries(cfg.aliases).find(([, m]) => m === id);
+    if (existing) { if (!council.includes(existing[0])) { council.push(existing[0]); } continue; }
+    const alias = deriveFreeAlias(id, taken);
+    cfg.aliases[alias] = id;
+    added.push({ alias, model: id });
+    council.push(alias);
+  }
+  if (!cfg.councils) { cfg.councils = {}; }
+  cfg.councils.free = Array.from(new Set(council));
+  saveConfig(cfg);
+  logger.info('Free council seeded', { count: cfg.councils.free.length });
+  return { added, council: cfg.councils.free };
+}
+
 module.exports = {
   addAlias,
   createDefaultConfig,
+  deriveFreeAlias,
   detectApiKeys,
+  runFreeCouncilBranch,
   runInteractiveSetup,
   runReadlineSetup,
   runApiKeySetup,
   seedCatalog,
+  seedFreeCouncil,
 };

package/src/utils/config.js

@@ -39,6 +39,34 @@ function getConfigDir() {
   return amicusDir;
 }
 
+/**
+ * One-time, non-destructive migration of the legacy ~/.config/sidecar config
+ * directory onto the canonical ~/.config/amicus. Copies (does not move), so the
+ * legacy dir is left intact as a backup. This collapses the two-dir split that
+ * let getConfigDir() flip between them and orphan data: once ~/.config/amicus
+ * exists it always wins. No-op when amicus already exists, when there is no
+ * legacy dir, or when a CONFIG_DIR override is set. Best-effort — returns a
+ * result object and never throws. Call once at startup, before any config read.
+ *
+ * @param {{home?: string}} [opts]
+ * @returns {{migrated: boolean, from?: string, to?: string, reason?: string, error?: string}}
+ */
+function migrateLegacyConfigDir(opts = {}) {
+  if (getCompatEnv('CONFIG_DIR')) { return { migrated: false, reason: 'override-set' }; }
+  const home = opts.home || process.env.HOME || process.env.USERPROFILE;
+  if (!home) { return { migrated: false, reason: 'no-home' }; }
+  const amicusDir = path.join(home, '.config', 'amicus');
+  const legacyDir = path.join(home, '.config', 'sidecar');
+  try {
+    if (fs.existsSync(amicusDir)) { return { migrated: false, reason: 'amicus-exists' }; }
+    if (!fs.existsSync(legacyDir)) { return { migrated: false, reason: 'no-legacy' }; }
+    fs.cpSync(legacyDir, amicusDir, { recursive: true });
+    return { migrated: true, from: legacyDir, to: amicusDir };
+  } catch (err) {
+    return { migrated: false, reason: 'error', error: err.message };
+  }
+}
+
 /** @returns {string} Full path to config.json */
 function getConfigPath() {
   return path.join(getConfigDir(), 'config.json');
@@ -273,8 +301,60 @@ function detectFallback(alias, resolvedModel) {
   return !!(val && val.startsWith('openrouter/') && !resolvedModel.startsWith('openrouter/'));
 }
 
+/** @returns {Object<string,string[]>} the councils map (empty if none) */
+function getCouncils() {
+  const config = loadConfig();
+  return (config && config.councils) || {};
+}
+
+/** @param {string} name @returns {string[]|null} council members, or null if absent */
+function getCouncil(name) {
+  return getCouncils()[name] || null;
+}
+
+/**
+ * Expand a saved council into a runnable members list, degrading gracefully.
+ * Each member is resolved to its full model id (alias → id via effective
+ * aliases; a member containing '/' is taken as-is) and that id checked against
+ * the cached catalog. Unresolvable aliases and delisted ids are dropped with a
+ * warning rather than fail-fast-aborting the whole wave. The catalog check is
+ * skipped when the catalog is empty (offline). Returns members RAW (alias or
+ * id) — leg-time validation resolves them again.
+ * @param {string} name
+ * @param {Array<{id:string}>} [catalog]
+ * @returns {{models:string[], dropped:string[]} | {error:string}}
+ */
+function resolveCouncilMembers(name, catalog = []) {
+  const members = getCouncil(name);
+  if (!members) {
+    return { error: `Unknown council '${name}'. Run 'amicus setup' to create one.` };
+  }
+  if (!Array.isArray(members) || members.length === 0) {
+    return { error: `Council '${name}' is empty. Run 'amicus setup' to populate it.` };
+  }
+  const aliases = getEffectiveAliases();
+  const known = new Set((Array.isArray(catalog) ? catalog : []).map(m => m && m.id).filter(Boolean));
+  const models = [];
+  const dropped = [];
+  for (const member of members) {
+    const id = member.includes('/') ? member : aliases[member];
+    if (!id) { dropped.push(member); continue; }                 // alias no longer resolves
+    if (known.size > 0 && !known.has(id)) { dropped.push(member); continue; } // delisted model
+    models.push(member);
+  }
+  if (models.length < 2) {
+    return {
+      error: `Council '${name}' has fewer than 2 usable members` +
+        (dropped.length ? ` (dropped: ${dropped.join(', ')})` : '') +
+        '. Run \'amicus setup\' to refresh it.',
+    };
+  }
+  return { models, dropped };
+}
+
 module.exports = {
   getConfigDir,
+  migrateLegacyConfigDir,
   getConfigPath,
   loadConfig,
   saveConfig,
@@ -288,4 +368,7 @@ module.exports = {
   formatAliasNames,
   tryResolveModel,
   buildProviderModels,
+  getCouncils,
+  getCouncil,
+  resolveCouncilMembers,
 };

package/src/utils/free-models.js

@@ -0,0 +1,50 @@
+/**
+ * Free OpenRouter model detection (Unit A).
+ *
+ * A free model is an openrouter/* catalog id whose slug ends in ':free'.
+ * The ':free' suffix is OpenRouter's authoritative free-tier marker. A
+ * zero prompt/completion price is deliberately NOT used: the catalog
+ * normalizer keeps only {prompt, completion} and discards request/image
+ * pricing, so a per-request-charged model with prompt:'0' would be
+ * mislabeled. Pure + network-free.
+ */
+'use strict';
+
+/** Offline last-resort free ids (used only when the live catalog is empty). */
+const PINNED_FREE_MODELS = [
+  'openrouter/deepseek/deepseek-r1:free',
+  'openrouter/google/gemini-2.0-flash-exp:free',
+  'openrouter/qwen/qwen3-coder:free',
+];
+
+/** @param {{id?:string}} row @returns {boolean} */
+function isFreeModel(row) {
+  const id = row && typeof row.id === 'string' ? row.id : '';
+  return id.startsWith('openrouter/') && id.endsWith(':free');
+}
+
+/** @param {Array} catalog @returns {Array} free rows, sorted by vendor then id */
+function listFreeModels(catalog) {
+  const rows = (Array.isArray(catalog) ? catalog : []).filter(isFreeModel);
+  return rows.sort((a, b) => {
+    const va = a.id.split('/')[1] || '';
+    const vb = b.id.split('/')[1] || '';
+    return va === vb ? a.id.localeCompare(b.id) : va.localeCompare(vb);
+  });
+}
+
+/** @param {Array} catalog @param {number} n @returns {Array} ≤n free rows, one per vendor */
+function suggestFreeCouncil(catalog, n = 3) {
+  const out = [];
+  const seenVendors = new Set();
+  for (const row of listFreeModels(catalog)) {
+    const vendor = row.id.split('/')[1] || '';
+    if (seenVendors.has(vendor)) { continue; }
+    seenVendors.add(vendor);
+    out.push(row);
+    if (out.length >= n) { break; }
+  }
+  return out;
+}
+
+module.exports = { isFreeModel, listFreeModels, suggestFreeCouncil, PINNED_FREE_MODELS };