swarmdo 1.4.8 → 1.5.0

package/v3/@swarmdo/cli/dist/src/integrations/integrations.js

@@ -0,0 +1,162 @@
+/**
+ * integrations.ts — wire swarmdo into agent CLIs beyond Claude Code.
+ *
+ * Targets: OpenAI Codex CLI, GitHub Copilot CLI, pi. Two standards do the
+ * heavy lifting: AGENTS.md (the cross-agent instructions file all three
+ * read) and MCP (swarmdo already ships a stdio server — `swarmdo mcp
+ * start`). Each merge below is PURE (string/JSON in → out), additive, and
+ * idempotent, so the whole surface is unit-testable and re-running install
+ * never duplicates or clobbers.
+ *
+ * INVARIANT (do-not-break-Claude): nothing in this module produces content
+ * for `.claude/**`, `.mcp.json`, or `CLAUDE.md` — the Claude Code surfaces
+ * are owned by init/mcp-generator and are only ever READ for status here.
+ */
+export const MCP_COMMAND = 'npx';
+export const MCP_ARGS = ['-y', 'swarmdo@latest', 'mcp', 'start'];
+const TOML_BEGIN = '# >>> swarmdo mcp (managed by `swarmdo integrations`) >>>';
+const TOML_END = '# <<< swarmdo mcp <<<';
+/** Codex CLI (~/.codex/config.toml): add the marked [mcp_servers.swarmdo]
+ * block when absent. Existing content — including a user's own hand-written
+ * swarmdo server — is left untouched. */
+export function mergeCodexToml(existing) {
+    const base = existing ?? '';
+    if (base.includes(TOML_BEGIN) || /\[mcp_servers\.swarmdo\]/.test(base)) {
+        return { content: base, changed: false };
+    }
+    const block = [
+        TOML_BEGIN,
+        '[mcp_servers.swarmdo]',
+        `command = "${MCP_COMMAND}"`,
+        `args = [${MCP_ARGS.map((a) => `"${a}"`).join(', ')}]`,
+        TOML_END,
+        '',
+    ].join('\n');
+    const sep = base.length > 0 && !base.endsWith('\n\n') ? (base.endsWith('\n') ? '\n' : '\n\n') : '';
+    return { content: base + sep + block, changed: true };
+}
+/** Copilot CLI (~/.copilot/mcp-config.json): same mcpServers schema Claude
+ * uses. Adds the swarmdo entry when absent; other servers preserved. */
+export function mergeCopilotMcpJson(existing) {
+    let cfg;
+    try {
+        cfg = existing ? JSON.parse(existing) : {};
+    }
+    catch {
+        // never clobber an unparseable user file
+        return { content: existing ?? '', changed: false };
+    }
+    if (cfg.mcpServers && Object.prototype.hasOwnProperty.call(cfg.mcpServers, 'swarmdo')) {
+        return { content: JSON.stringify(cfg, null, 2) + '\n', changed: false };
+    }
+    cfg.mcpServers = { ...(cfg.mcpServers ?? {}), swarmdo: { type: 'local', command: MCP_COMMAND, args: MCP_ARGS, tools: ['*'] } };
+    return { content: JSON.stringify(cfg, null, 2) + '\n', changed: true };
+}
+/** Cross-agent AGENTS.md for projects that don't have one. Existing files
+ * are never rewritten (report-only) — teams own their AGENTS.md. */
+export function crossAgentAgentsMd() {
+    return `# AGENTS.md — swarmdo project
+
+> Read by Codex CLI, GitHub Copilot CLI, pi, and other AGENTS.md-aware
+> agents. Claude Code uses CLAUDE.md instead — both coexist in this repo.
+
+## What swarmdo gives you
+
+This project is wired to **swarmdo** — agent orchestration with persistent
+vector memory, swarm coordination, and 300+ MCP tools.
+
+- **MCP server**: \`swarmdo mcp start\` (stdio). If your CLI supports MCP,
+  \`swarmdo integrations install <your-cli>\` wires it; key tools:
+  \`memory_search\`, \`memory_store\`, \`swarm_init\`, \`agent_spawn\`.
+- **CLI**: \`npx swarmdo@latest <command>\` — \`memory search -q "topic"\`,
+  \`usage\`, \`task\`, \`hud\`, \`security scan\`, \`config lint\`.
+
+## Working agreement (any agent)
+
+1. **Search memory BEFORE starting**: \`memory_search(query="task keywords")\`
+   — patterns with score > 0.7 are load-bearing precedent.
+2. **You are the executor** — swarmdo coordinates and remembers; it never
+   writes your code for you.
+3. **Store what worked AFTER success**:
+   \`memory_store(key="pattern-…", value="what worked", namespace="patterns")\`.
+4. Claude Code users: the same surfaces are namespaced under \`/sDo:\`
+   commands and \`/sdo-\` skills.
+
+## Do not
+
+- Do not commit secrets or .env files.
+- Do not edit \`.claude/\`, \`.mcp.json\`, or \`CLAUDE.md\` — those belong to
+  the Claude Code integration and are managed by \`swarmdo init\`.
+`;
+}
+/** .github/copilot-instructions.md — Copilot reads this per-repo. Kept as a
+ * thin pointer so AGENTS.md stays the single source of truth. */
+export function copilotInstructionsMd() {
+    return `# Copilot instructions
+
+This repository uses **swarmdo** for agent orchestration and persistent
+memory. Follow \`AGENTS.md\` at the repo root — it is the canonical
+cross-agent working agreement (memory-first workflow, executor role, MCP
+tools). The swarmdo MCP server (\`swarmdo mcp start\`) provides
+memory_search / memory_store / swarm_init; wire it with
+\`swarmdo integrations install copilot\`.
+`;
+}
+export const INSTALLABLE = ['codex', 'copilot', 'pi'];
+/** Pure status evaluation over pre-read file contents (null = absent). */
+export function evaluateStatus(files) {
+    const agentsOk = files.agentsMd !== null;
+    const codexMcp = !!files.codexToml && /\[mcp_servers\.swarmdo\]/.test(files.codexToml);
+    const copilotMcp = (() => {
+        try {
+            return !!files.copilotJson && 'swarmdo' in (JSON.parse(files.copilotJson).mcpServers ?? {});
+        }
+        catch {
+            return false;
+        }
+    })();
+    const hasSwarmdoServer = (raw) => {
+        try {
+            return !!raw && 'swarmdo' in (JSON.parse(raw).mcpServers ?? {});
+        }
+        catch {
+            return false;
+        }
+    };
+    const claudeProject = hasSwarmdoServer(files.claudeMcpJson);
+    const claudeUser = hasSwarmdoServer(files.claudeUserJson);
+    const claudeMcp = claudeProject || claudeUser;
+    return [
+        {
+            target: 'claude', ok: files.claudeDirExists && claudeMcp,
+            details: [
+                `.claude/ ${files.claudeDirExists ? 'present' : 'MISSING'}`,
+                `swarmdo MCP server ${claudeMcp ? `wired (${claudeProject ? '.mcp.json' : '~/.claude.json'})` : 'missing from .mcp.json and ~/.claude.json'}`,
+                '(read-only here — managed by `swarmdo init`)',
+            ],
+        },
+        {
+            target: 'codex', ok: agentsOk && codexMcp,
+            details: [
+                `AGENTS.md ${agentsOk ? 'present' : 'missing'}`,
+                `~/.codex/config.toml [mcp_servers.swarmdo] ${codexMcp ? 'wired' : 'missing'}`,
+            ],
+        },
+        {
+            target: 'copilot', ok: agentsOk && copilotMcp && files.copilotInstructions !== null,
+            details: [
+                `AGENTS.md ${agentsOk ? 'present' : 'missing'}`,
+                `.github/copilot-instructions.md ${files.copilotInstructions !== null ? 'present' : 'missing'}`,
+                `~/.copilot/mcp-config.json swarmdo server ${copilotMcp ? 'wired' : 'missing'}`,
+            ],
+        },
+        {
+            target: 'pi', ok: agentsOk,
+            details: [
+                `AGENTS.md ${agentsOk ? 'present (pi reads it natively)' : 'missing'}`,
+                'MCP: point pi at `npx -y swarmdo@latest mcp start` if your pi build supports MCP servers',
+            ],
+        },
+    ];
+}
+//# sourceMappingURL=integrations.js.map

package/v3/@swarmdo/cli/dist/src/mcp-tools/agent-execute-core.js

@@ -80,16 +80,34 @@ export async function callAnthropicMessages(input) {
     const useOpenRouter = explicitProvider === 'openrouter' || (!anthropicKey && !!openrouterKey);
     const useOllama = explicitProvider === 'ollama' || (!anthropicKey && !!ollamaKey && !openrouterKey);
     if (useOpenRouter && openrouterKey) {
+        // Configurable model pool: swarmdo.config.json `openrouter` section lets
+        // the swarm draw from user-configured models (explicit slug > tier pick
+        // via Thompson sampling > config defaultModel). Env vars still win for
+        // base URL and as the final default for un-configured projects.
+        let configuredModel;
+        let configuredBaseUrl;
+        try {
+            const { loadOpenRouterConfig, resolveOpenRouterModel } = await import('../providers/openrouter-config.js');
+            const { config } = loadOpenRouterConfig();
+            if (config.enabled) {
+                configuredBaseUrl = config.baseUrl;
+                configuredModel = resolveOpenRouterModel({ requested: input.model, cfg: config })?.model;
+            }
+        }
+        catch { /* config unreadable — env-only behavior */ }
         return callOpenAICompat({
             ...input,
+            // a resolved pool pick replaces tier words / Anthropic ids; explicit
+            // slugs pass through resolveOpenRouterModel unchanged
+            model: configuredModel ?? input.model,
             apiKey: openrouterKey,
-            baseUrl: process.env.OPENROUTER_BASE_URL || 'https://openrouter.ai/api',
+            baseUrl: process.env.OPENROUTER_BASE_URL || configuredBaseUrl || 'https://openrouter.ai/api',
             providerLabel: 'openrouter',
             // #2357 Finding C: anthropic/claude-3.5-sonnet was retired Oct 2025.
             // Default to the same canonical family the rest of the resolver uses
             // (MODEL_MAP). `OPENROUTER_DEFAULT_MODEL` still wins for callers who
             // want to pin a specific OpenRouter slug.
-            defaultModel: process.env.OPENROUTER_DEFAULT_MODEL || 'anthropic/claude-sonnet-4-6',
+            defaultModel: process.env.OPENROUTER_DEFAULT_MODEL || configuredModel || 'anthropic/claude-sonnet-4-6',
         });
     }
     if (useOllama && ollamaKey) {
@@ -445,7 +463,8 @@ export async function executeAgentTask(input) {
     const fallbackBudget = Math.max(0, parseInt(process.env.SWARMDO_ROUTER_FALLBACK_MAX_RETRIES ?? '1', 10) || 1);
     const fallbackHistory = [];
     if (!result.success && agent.modelId && fallbackBudget > 0) {
-        const isRetryable = /\b(429|500|502|503|504|timeout|ECONNRESET|ETIMEDOUT)\b/i.test(result.error ?? '');
+        const { isRetryableError, computeBackoffMs, sleep } = await import('../resilience/backoff.js');
+        const isRetryable = isRetryableError(result.error);
         if (isRetryable) {
             try {
                 const { nextCostOptimalAlternative } = await import('../swarmvector/neural-router.js');
@@ -459,6 +478,9 @@ export async function executeAgentTask(input) {
                     const excludeIds = [agent.modelId];
                     for (let attempt = 0; attempt < fallbackBudget && !result.success; attempt++) {
                         fallbackHistory.push({ modelId: excludeIds[excludeIds.length - 1], error: result.error ?? '' });
+                        // full-jitter exponential backoff — a 429 is usually account-wide,
+                        // so an instant re-call against the same provider burns the attempt
+                        await sleep(computeBackoffMs(attempt));
                         const alt = await nextCostOptimalAlternative(embedding, excludeIds);
                         if (!alt || !alt.modelId)
                             break;

package/v3/@swarmdo/cli/dist/src/mcp-tools/agentdb-tools.js

@@ -996,11 +996,11 @@ export const agentdbGraphQuery = {
                 catch { /* fall through to sql.js */ }
                 // SQL CTE fallback for k-hop up to depth 3
                 try {
-                    const { getBridgeDb } = await import('../memory/graph-edge-writer.js');
+                    const { getBridgeDb, execRows } = await import('../memory/graph-edge-writer.js');
                     const db = await getBridgeDb();
                     if (db) {
                         const cteSql = buildKHopCTE(nodeId, Math.min(depth, 3), relation, budget.maxNodesVisited);
-                        const result = db.exec(cteSql);
+                        const result = execRows(db, cteSql);
                         const rows = result?.[0]?.values ?? [];
                         return {
                             success: true, mode, nodeId, depth,
@@ -1021,14 +1021,14 @@ export const agentdbGraphQuery = {
                     const queryEmb = await generateEmbedding(nodeId);
                     if (!queryEmb)
                         throw new Error('embedding failed');
-                    const { getBridgeDb } = await import('../memory/graph-edge-writer.js');
+                    const { getBridgeDb, execRows } = await import('../memory/graph-edge-writer.js');
                     // #2246 fix: lazy-create memory.db on first pathfinder call so
                     // fresh environments work without a pre-existing memory init.
                     const db = await getBridgeDb(undefined, { createIfMissing: true });
                     if (!db)
                         return { success: false, error: 'graph_edges DB unavailable (sql.js could not load)', hint: 'Check Node version + try `swarmdo memory init` to initialize manually.', mode, nodeId };
                     // Load all rows with embedding_ref and score by cosine
-                    const rowResult = db.exec(`SELECT id, source_id, target_id, relation, weight, embedding_ref FROM graph_edges WHERE embedding_ref IS NOT NULL LIMIT ?`, [budget.maxNodesVisited]);
+                    const rowResult = execRows(db, `SELECT id, source_id, target_id, relation, weight, embedding_ref FROM graph_edges WHERE embedding_ref IS NOT NULL LIMIT ?`, [budget.maxNodesVisited]);
                     const rows = rowResult?.[0]?.values ?? [];
                     const { decodeEmbedding } = await import('../memory/embedding-quantization.js');
                     const scored = [];
@@ -1061,13 +1061,13 @@ export const agentdbGraphQuery = {
             // ── pagerank mode ────────────────────────────────────────────────────────
             if (mode === 'pagerank') {
                 try {
-                    const { getBridgeDb } = await import('../memory/graph-edge-writer.js');
+                    const { getBridgeDb, execRows } = await import('../memory/graph-edge-writer.js');
                     // #2246 fix: lazy-create memory.db on first pathfinder call so
                     // fresh environments work without a pre-existing memory init.
                     const db = await getBridgeDb(undefined, { createIfMissing: true });
                     if (!db)
                         return { success: false, error: 'graph_edges DB unavailable (sql.js could not load)', hint: 'Check Node version + try `swarmdo memory init` to initialize manually.', mode, nodeId };
-                    const edgeResult = db.exec(`SELECT source_id, target_id, weight FROM graph_edges LIMIT ?`, [budget.maxNodesVisited]);
+                    const edgeResult = execRows(db, `SELECT source_id, target_id, weight FROM graph_edges LIMIT ?`, [budget.maxNodesVisited]);
                     const edges = edgeResult?.[0]?.values ?? [];
                     if (edges.length === 0) {
                         return { success: true, mode, nodeId, results: [], count: 0, message: 'graph_edges is empty', elapsedMs: Date.now() - t0 };
@@ -1248,7 +1248,7 @@ export const agentdbGraphPathfinder = {
                 return { success: false, error: `Unknown algorithm: ${algorithm}. Valid: ${validAlgorithms.join(', ')}` };
             }
             // Load edges from graph_edges
-            const { getBridgeDb } = await import('../memory/graph-edge-writer.js');
+            const { getBridgeDb, execRows } = await import('../memory/graph-edge-writer.js');
             // #2246 fix: lazy-create memory.db on first pathfinder call.
             const db = await getBridgeDb(undefined, { createIfMissing: true });
             if (!db)
@@ -1258,7 +1258,7 @@ export const agentdbGraphPathfinder = {
                 : algorithm === 'temporal-centrality'
                     ? 'source_id, target_id, weight, last_reinforced, confidence'
                     : 'source_id, target_id, weight';
-            const edgeResult = db.exec(`SELECT ${colsSql} FROM graph_edges LIMIT ?`, [budget.maxNodesVisited]);
+            const edgeResult = execRows(db, `SELECT ${colsSql} FROM graph_edges LIMIT ?`, [budget.maxNodesVisited]);
             const rawEdges = edgeResult?.[0]?.values ?? [];
             if (rawEdges.length === 0) {
                 return { success: true, paths: [], count: 0, message: `no edges found from seedNodeId`, seedNodeId, algorithm, elapsedMs: Date.now() - t0 };

package/v3/@swarmdo/cli/dist/src/memory/graph-edge-writer.d.ts

@@ -58,6 +58,18 @@ export interface GraphEdgeInput {
     metadata?: Record<string, unknown>;
     dbPath?: string;
 }
+/**
+ * Engine-compat read: run a SELECT and return rows in sql.js exec() shape
+ * ([{columns, values}] or [] when no rows). getBridgeDb returned sql.js
+ * historically and better-sqlite3 since #2431 — readers written against the
+ * old shape (agentdb graph query/pathfinder) go through this shim so they
+ * work on either engine. better-sqlite3's own exec() neither binds params
+ * nor returns rows, which surfaced as "datatype mismatch" on every LIMIT ?.
+ */
+export declare function execRows(db: any, sql: string, params?: unknown[]): Array<{
+    columns: string[];
+    values: unknown[][];
+}>;
 /**
  * Insert a single edge into graph_edges.
  * Fire-and-forget — errors are suppressed.

package/v3/@swarmdo/cli/dist/src/memory/graph-edge-writer.js

@@ -123,6 +123,26 @@ export async function getBridgeDb(customDbPath, opts) {
         _dbInitializing = false;
     }
 }
+/**
+ * Engine-compat read: run a SELECT and return rows in sql.js exec() shape
+ * ([{columns, values}] or [] when no rows). getBridgeDb returned sql.js
+ * historically and better-sqlite3 since #2431 — readers written against the
+ * old shape (agentdb graph query/pathfinder) go through this shim so they
+ * work on either engine. better-sqlite3's own exec() neither binds params
+ * nor returns rows, which surfaced as "datatype mismatch" on every LIMIT ?.
+ */
+export function execRows(db, sql, params = []) {
+    if (db && typeof db.prepare === 'function') {
+        const stmt = db.prepare(sql);
+        const values = stmt.raw(true).all(...params);
+        if (values.length === 0)
+            return [];
+        const columns = stmt.columns().map((c) => c.name);
+        return [{ columns, values }];
+    }
+    // sql.js fallback (legacy)
+    return db.exec(sql, params);
+}
 /**
  * Insert a single edge into graph_edges.
  * Fire-and-forget — errors are suppressed.
@@ -140,6 +160,17 @@ export async function insertGraphEdge(input) {
             return false;
         const id = `edge-${crypto.randomUUID()}`;
         const createdAt = new Date().toISOString();
+        // ADR-130 §Phase 1 criterion 3: legacy unprefixed node ids (no `kind:`
+        // namespace) are auto-prefixed as `mem:` with a deprecation warning so
+        // old callers keep working while the graph converges on prefixed ids.
+        const normalizeId = (raw) => {
+            if (raw.includes(':'))
+                return raw;
+            console.warn(`[graph-edge-writer] DEPRECATED: unprefixed node id "${raw}" — auto-prefixing as "mem:${raw}" (ADR-130)`);
+            return `mem:${raw}`;
+        };
+        const sourceId = normalizeId(input.sourceId);
+        const targetId = normalizeId(input.targetId);
         let embeddingRef = null;
         if (input.embedding && input.embedding.length > 0) {
             embeddingRef = encodeEmbedding(input.embedding);
@@ -148,7 +179,7 @@ export async function insertGraphEdge(input) {
         db.prepare(`INSERT OR IGNORE INTO graph_edges
         (id, source_id, target_id, relation, weight, confidence, decay_rate,
          last_reinforced, witness_id, embedding_ref, metadata, created_at)
-       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, input.sourceId, input.targetId, input.relation, input.weight ?? 1.0, input.confidence ?? 1.0, input.decayRate ?? 0.0, input.lastReinforced ?? null, input.witnessId ?? null, embeddingRef, metaStr, createdAt);
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, sourceId, targetId, input.relation, input.weight ?? 1.0, input.confidence ?? 1.0, input.decayRate ?? 0.0, input.lastReinforced ?? null, input.witnessId ?? null, embeddingRef, metaStr, createdAt);
         return true;
     }
     catch {

package/v3/@swarmdo/cli/dist/src/memory-vault/watch.d.ts

@@ -0,0 +1,32 @@
+/**
+ * watch.ts — debounced change collection for vault auto-sync (phase 2 of the
+ * dual-plane memory strategy: edit notes in Obsidian, they sync back to the
+ * vector DB as you save).
+ *
+ * Editors fire bursts of fs events per save (write + rename + metadata);
+ * the collector coalesces them into one flush after a quiet window, filters
+ * to real notes (.md, not INDEX.md, not dotfiles), and hands relative paths
+ * to the sync callback. Pure timing via an injectable scheduler so tests run
+ * on fake clocks.
+ */
+export interface Scheduler {
+    set(fn: () => void, ms: number): unknown;
+    clear(handle: unknown): void;
+}
+/** Should this relative path participate in a sync? */
+export declare function isSyncablePath(relPath: string): boolean;
+export declare class ChangeCollector {
+    private readonly flush;
+    private readonly quietMs;
+    private readonly scheduler;
+    private pending;
+    private handle;
+    constructor(flush: (paths: string[]) => void, quietMs?: number, scheduler?: Scheduler);
+    /** Record a change; (re)arms the quiet-window timer. */
+    add(relPath: string): void;
+    /** Flush immediately (shutdown path). No-op when empty. */
+    drain(): void;
+    get size(): number;
+    private fire;
+}
+//# sourceMappingURL=watch.d.ts.map

package/v3/@swarmdo/cli/dist/src/memory-vault/watch.js

@@ -0,0 +1,66 @@
+/**
+ * watch.ts — debounced change collection for vault auto-sync (phase 2 of the
+ * dual-plane memory strategy: edit notes in Obsidian, they sync back to the
+ * vector DB as you save).
+ *
+ * Editors fire bursts of fs events per save (write + rename + metadata);
+ * the collector coalesces them into one flush after a quiet window, filters
+ * to real notes (.md, not INDEX.md, not dotfiles), and hands relative paths
+ * to the sync callback. Pure timing via an injectable scheduler so tests run
+ * on fake clocks.
+ */
+const realScheduler = {
+    set: (fn, ms) => setTimeout(fn, ms),
+    clear: (h) => clearTimeout(h),
+};
+/** Should this relative path participate in a sync? */
+export function isSyncablePath(relPath) {
+    const base = relPath.split('/').pop() ?? relPath;
+    if (!base.endsWith('.md'))
+        return false;
+    if (base === 'INDEX.md')
+        return false;
+    if (relPath.split('/').some((seg) => seg.startsWith('.')))
+        return false;
+    return true;
+}
+export class ChangeCollector {
+    flush;
+    quietMs;
+    scheduler;
+    pending = new Set();
+    handle = null;
+    constructor(flush, quietMs = 1500, scheduler = realScheduler) {
+        this.flush = flush;
+        this.quietMs = quietMs;
+        this.scheduler = scheduler;
+    }
+    /** Record a change; (re)arms the quiet-window timer. */
+    add(relPath) {
+        if (!isSyncablePath(relPath))
+            return;
+        this.pending.add(relPath);
+        if (this.handle !== null)
+            this.scheduler.clear(this.handle);
+        this.handle = this.scheduler.set(() => this.fire(), this.quietMs);
+    }
+    /** Flush immediately (shutdown path). No-op when empty. */
+    drain() {
+        if (this.handle !== null)
+            this.scheduler.clear(this.handle);
+        this.handle = null;
+        this.fire();
+    }
+    get size() {
+        return this.pending.size;
+    }
+    fire() {
+        this.handle = null;
+        if (this.pending.size === 0)
+            return;
+        const batch = [...this.pending].sort();
+        this.pending.clear();
+        this.flush(batch);
+    }
+}
+//# sourceMappingURL=watch.js.map

package/v3/@swarmdo/cli/dist/src/providers/openrouter-config.d.ts

@@ -0,0 +1,91 @@
+/**
+ * openrouter-config.ts — configurable OpenRouter model pool for swarms.
+ *
+ * The execution core has dispatched to OpenRouter since #2042, but only via
+ * env vars and a single default slug. This module makes the integration
+ * CONFIGURABLE: users declare the OpenRouter models they want their agent
+ * swarms to draw from in swarmdo.config.json, each mapped to a routing tier,
+ * and the router selects among same-tier candidates by Thompson sampling —
+ * the concrete consumer for the ADR-149 per-modelId priors.
+ *
+ *   "openrouter": {
+ *     "enabled": true,
+ *     "models": [
+ *       { "id": "meta-llama/llama-3.3-70b-instruct", "tier": "haiku" },
+ *       { "id": "deepseek/deepseek-chat",            "tier": "sonnet" },
+ *       { "id": "anthropic/claude-opus-4-5",         "tier": "opus" }
+ *     ],
+ *     "defaultModel": "anthropic/claude-sonnet-4-6"
+ *   }
+ *
+ * Everything here is pure (validation, filtering, sampling with injectable
+ * randomness) except loadOpenRouterConfig, a thin fs reader.
+ */
+export type RoutingTier = 'haiku' | 'sonnet' | 'opus';
+export interface OpenRouterModelEntry {
+    /** OpenRouter slug, e.g. 'meta-llama/llama-3.3-70b-instruct' */
+    id: string;
+    /** Which routing tier this model can serve. Untiered models are only
+     * reachable as defaultModel or by explicit slug. */
+    tier?: RoutingTier;
+    /** Free-form operator note (why it's in the pool, cost expectations…) */
+    note?: string;
+}
+export interface OpenRouterConfig {
+    enabled: boolean;
+    /** env var holding the key (default OPENROUTER_API_KEY) */
+    apiKeyEnv: string;
+    baseUrl: string;
+    defaultModel?: string;
+    models: OpenRouterModelEntry[];
+}
+export interface ParseResult {
+    config: OpenRouterConfig;
+    /** human-readable reasons for every entry/field that was dropped */
+    warnings: string[];
+}
+/** OpenRouter slugs are provider/model paths ('org/name[:variant]'). */
+export declare function isOpenRouterSlug(model: string | undefined | null): boolean;
+/** Validate the raw `openrouter` config section. Tolerant at the boundary:
+ * bad entries are dropped with a warning, never thrown. */
+export declare function parseOpenRouterConfig(raw: unknown): ParseResult;
+/** Models eligible to serve a tier. */
+export declare function modelsForTier(cfg: OpenRouterConfig, tier: RoutingTier): OpenRouterModelEntry[];
+export interface BetaPrior {
+    alpha: number;
+    beta: number;
+}
+export type BetaSampler = (alpha: number, beta: number) => number;
+/** Default Beta sampler via two Gamma(α,1)/Gamma(β,1) draws (Marsaglia-Tsang
+ * for shape ≥ 1, boost trick below 1). Deterministic tests inject their own. */
+export declare const defaultBetaSampler: BetaSampler;
+export interface PickInput {
+    cfg: OpenRouterConfig;
+    tier: RoutingTier;
+    /** per-modelId Beta priors (ADR-149 shape) — absent models get uniform Beta(1,1) */
+    priors?: Record<string, BetaPrior>;
+    sample?: BetaSampler;
+}
+export interface PickResult {
+    model: string;
+    reason: string;
+    candidates: number;
+}
+/** Thompson-sample a concrete OpenRouter model for a tier from the
+ * user-configured pool. Returns null when disabled or no tier candidates. */
+export declare function pickOpenRouterModel({ cfg, tier, priors, sample }: PickInput): PickResult | null;
+export interface ResolveInput extends Omit<PickInput, 'tier'> {
+    /** caller-supplied model: OpenRouter slug passes through; tier word routes via the pool */
+    requested?: string;
+    tier?: RoutingTier;
+}
+/** Full precedence for the execution path:
+ *  explicit slug > tier pick from the configured pool > config defaultModel > null. */
+export declare function resolveOpenRouterModel({ requested, tier, cfg, priors, sample }: ResolveInput): {
+    model: string;
+    source: string;
+} | null;
+/** Thin reader: swarmdo.config.json's `openrouter` section from cwd (or an
+ * ancestor repo root). Absent/broken files yield the disabled default. */
+export declare function loadOpenRouterConfig(cwd?: string): ParseResult;
+//# sourceMappingURL=openrouter-config.d.ts.map