@albalink/agent 1.0.0

package/dist/runner/ModelClient.js

@@ -0,0 +1,350 @@
+/**
+ * ModelClient — sends messages to any OpenAI-compatible model API.
+ *
+ * Provider priority (auto-detected from env):
+ *   OpenRouter > Anthropic compat > OpenAI > local (ollama/lm-studio)
+ *
+ * Model rotation: resolveModelChain() returns up to 5 configs — the AgentRunner
+ * walks the chain on 429 (rate limit) or 5xx errors, with exponential backoff
+ * (up to 2 retries per model) before falling through.
+ *
+ * When a ModelRegistry is available, chains are dynamically built from the
+ * tiered pool, with per-model performance tracking and cost estimation.
+ *
+ * All outbound, all local — no inbound ports, no server.
+ */
+// ── Model rotation chain ──────────────────────────────────────────────────────
+/**
+ * Build the ordered model fallback chain.
+ *
+ * If a ModelRegistry is provided, builds from the tiered pool dynamically.
+ * Falls back to static env-var parsing otherwise.
+ *
+ * User-configurable pool: ALBA_MODEL_1 … ALBA_MODEL_5
+ * If any ALBA_MODEL_N vars are set they take priority; up to 5 are used in
+ * order. Unset slots are filled with provider-appropriate defaults.
+ *
+ * ALBA_MODEL_N format: just the model ID string, e.g.
+ *   ALBA_MODEL_1=anthropic/claude-opus-4-5
+ *   ALBA_MODEL_2=openai/gpt-4o
+ *   ALBA_MODEL_3=google/gemini-2.5-pro
+ */
+export function resolveModelChain(modelReg) {
+    const env = process.env;
+    const tokens = parseInt(env.MAX_TOKENS ?? "8192");
+    const temp = parseFloat(env.TEMPERATURE ?? "0.7");
+    // ── Collect user-configured model IDs (ALBA_MODEL_1..5) ────────────────
+    const userModels = [];
+    for (let i = 1; i <= 5; i++) {
+        const m = env[`ALBA_MODEL_${i}`];
+        if (m?.trim())
+            userModels.push(m.trim());
+    }
+    // ── Use ModelRegistry dynamic pool if available ──────────────────────────
+    if (modelReg) {
+        return modelReg.buildModelChain(userModels);
+    }
+    // ── Static fallback (used when ModelRegistry cannot be initialised) ───────
+    // ── OpenRouter — supports all providers via a single key ─────────────────
+    if (env.OPENROUTER_API_KEY) {
+        const base = "https://openrouter.ai/api/v1";
+        const key = env.OPENROUTER_API_KEY;
+        const siteUrl = env.OPENROUTER_SITE_URL ?? "https://alba.fun";
+        const siteName = env.OPENROUTER_SITE_NAME ?? "ALBA";
+        const mk = (model) => ({
+            baseUrl: base, apiKey: key, model, maxTokens: tokens, temperature: temp,
+            siteUrl, siteName,
+        });
+        const defaults = [
+            env.DEFAULT_MODEL ?? "anthropic/claude-sonnet-4-5",
+            "anthropic/claude-3-haiku",
+            "openai/gpt-4o-mini",
+            "google/gemini-flash-1.5",
+            "meta-llama/llama-3-8b-instruct:free",
+        ];
+        // Merge: user-configured models first, then fill remaining slots with defaults
+        const merged = [...userModels, ...defaults.filter(d => !userModels.includes(d))].slice(0, 5);
+        return merged.map(mk);
+    }
+    // ── Anthropic direct (OpenAI-compat endpoint) ────────────────────────────
+    if (env.ANTHROPIC_API_KEY) {
+        const base = "https://api.anthropic.com/v1";
+        const key = env.ANTHROPIC_API_KEY;
+        const mk = (model) => ({
+            baseUrl: base, apiKey: key, model, maxTokens: tokens, temperature: temp,
+        });
+        const defaults = [
+            env.DEFAULT_MODEL ?? "claude-sonnet-4-5-20251101",
+            "claude-3-haiku-20240307",
+            "claude-3-5-haiku-20241022",
+        ];
+        const merged = [...userModels, ...defaults.filter(d => !userModels.includes(d))].slice(0, 5);
+        return merged.map(mk);
+    }
+    // ── OpenAI direct ────────────────────────────────────────────────────────
+    if (env.OPENAI_API_KEY) {
+        const base = env.OPENAI_BASE_URL ?? "https://api.openai.com/v1";
+        const key = env.OPENAI_API_KEY;
+        const mk = (model) => ({
+            baseUrl: base, apiKey: key, model, maxTokens: tokens, temperature: temp,
+        });
+        const defaults = [
+            env.DEFAULT_MODEL ?? "gpt-4o",
+            "gpt-4o-mini",
+            "gpt-3.5-turbo",
+        ];
+        const merged = [...userModels, ...defaults.filter(d => !userModels.includes(d))].slice(0, 5);
+        return merged.map(mk);
+    }
+    // ── Local model (ollama, lm-studio, etc.) — single entry, no rotation ───
+    if (env.OPENAI_BASE_URL) {
+        return [{
+                baseUrl: env.OPENAI_BASE_URL,
+                apiKey: env.OPENAI_API_KEY ?? "local",
+                model: userModels[0] ?? env.DEFAULT_MODEL ?? "llama3",
+                maxTokens: tokens,
+                temperature: temp,
+            }];
+    }
+    // No API key configured — return a placeholder so the TUI can show setup
+    return [{
+            baseUrl: "https://openrouter.ai/api/v1",
+            apiKey: "",
+            model: "anthropic/claude-sonnet-4-5",
+            maxTokens: 8192,
+            temperature: 0.7,
+        }];
+}
+/** Convenience: returns just the primary (first) model config */
+export function resolveModelConfig(modelReg) {
+    return resolveModelChain(modelReg)[0];
+}
+// ── ModelClient ───────────────────────────────────────────────────────────────
+export class ModelClient {
+    cfg;
+    modelRegistry;
+    constructor(cfg, modelReg) {
+        this.cfg = cfg;
+        this.modelRegistry = modelReg;
+    }
+    /**
+     * Stream a chat completion. Yields ChatChunk objects.
+     * Retries up to 2 times on 429 / 5xx with exponential backoff (1s, 2s).
+     * On persistent HTTP error the generator yields a single { type: "error", status, error }
+     * chunk and returns — the caller (AgentRunner) decides whether to rotate.
+     * Also reports success/failure to the ModelRegistry for tiering and cooldown.
+     */
+    async *stream(messages, tools, abortSignal) {
+        const t0 = Date.now();
+        let hadError = false;
+        const headers = {
+            "Content-Type": "application/json",
+            "Authorization": `Bearer ${this.cfg.apiKey}`,
+            "User-Agent": "ALBA/1.0",
+        };
+        if (this.cfg.siteUrl)
+            headers["HTTP-Referer"] = this.cfg.siteUrl;
+        if (this.cfg.siteName)
+            headers["X-Title"] = this.cfg.siteName;
+        // #13: Detect thinking-capable models
+        const THINKING_MODELS = new Set([
+            "anthropic/claude-opus-4.7", "anthropic/claude-opus-4.7-fast",
+            "anthropic/claude-opus-4.6", "anthropic/claude-opus-4.6-fast",
+            "anthropic/claude-opus-4.5", "anthropic/claude-opus-4",
+            "openai/o3", "openai/o3-pro", "openai/o3-mini",
+            "openai/o4", "openai/o4-mini",
+        ]);
+        const isThinkingModel = THINKING_MODELS.has(this.cfg.model) || /thinking/i.test(this.cfg.model);
+        const useThinking = this.cfg.thinkingEnabled && isThinkingModel;
+        const isOSeries = /openai\/o[34]/i.test(this.cfg.model);
+        const isAnthropicModel = this.cfg.model.startsWith("anthropic/") ||
+            this.cfg.baseUrl.includes("anthropic.com");
+        // Build request body
+        const body = {
+            model: this.cfg.model,
+            max_tokens: this.cfg.maxTokens,
+            stream: true,
+        };
+        // #13: Temperature handling — o-series does not support temperature
+        if (!isOSeries) {
+            body.temperature = useThinking ? 1.0 : this.cfg.temperature; // thinking requires 1.0
+        }
+        // #15: Prompt caching for Anthropic — extract system message, add cache_control
+        if (isAnthropicModel) {
+            const sysMsg = messages.find(m => m.role === "system");
+            const rest = messages.filter(m => m.role !== "system");
+            if (sysMsg && typeof sysMsg.content === "string" && sysMsg.content.length > 512) {
+                // Cache the system prompt (saves up to 90% on repeated calls)
+                body.system = [{
+                        type: "text",
+                        text: sysMsg.content,
+                        cache_control: { type: "ephemeral" },
+                    }];
+                body.messages = rest;
+            }
+            else {
+                body.messages = messages;
+            }
+            // #13: Extended thinking for Claude Opus 4.x
+            if (useThinking) {
+                body.thinking = { type: "enabled", budget_tokens: this.cfg.thinkingBudget ?? 8000 };
+                headers["anthropic-beta"] = "thinking-v1";
+            }
+        }
+        else {
+            body.messages = messages;
+        }
+        // #13: o-series reasoning effort
+        if (isOSeries && useThinking) {
+            body.reasoning_effort = "high";
+        }
+        if (tools && tools.length > 0) {
+            // strict: true enforces valid JSON on GPT-4o+ and GPT-5.x
+            // Skip strict mode for o-series (not supported) and thinking models
+            body.tools = tools.map(t => ({
+                ...t,
+                function: isOSeries ? t.function : { ...t.function, strict: true },
+            }));
+            body.tool_choice = "auto";
+            // Disable parallel tool calls — prevents race conditions in tool_call_id map
+            body.parallel_tool_calls = false;
+        }
+        const MAX_RETRIES = 2;
+        const RETRY_STATUSES = new Set([429, 500, 502, 503, 504]);
+        let res;
+        let lastError = "";
+        for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+            try {
+                // #25: Combine user abort signal with 120s timeout
+                const timeoutSignal = AbortSignal.timeout(120_000);
+                const combinedSignal = abortSignal
+                    ? AbortSignal.any([abortSignal, timeoutSignal])
+                    : timeoutSignal;
+                res = await fetch(`${this.cfg.baseUrl}/chat/completions`, {
+                    method: "POST",
+                    headers,
+                    body: JSON.stringify(body),
+                    signal: combinedSignal,
+                });
+            }
+            catch (e) {
+                if (e?.name === "AbortError") {
+                    yield { type: "done", finish_reason: "aborted" };
+                    return;
+                }
+                hadError = true;
+                lastError = `Network error: ${e.message}`;
+                if (attempt < MAX_RETRIES) {
+                    await new Promise(r => setTimeout(r, 1000 * (attempt + 1)));
+                    continue;
+                }
+                this.modelRegistry?.recordFailure(this.cfg.model);
+                yield { type: "error", error: lastError, status: 0 };
+                return;
+            }
+            if (!res.ok && RETRY_STATUSES.has(res.status) && attempt < MAX_RETRIES) {
+                hadError = true;
+                lastError = await res.text().catch(() => res.statusText);
+                await new Promise(r => setTimeout(r, 1000 * (attempt + 1)));
+                continue;
+            }
+            if (!res.ok) {
+                hadError = true;
+                const err = await res.text().catch(() => res.statusText);
+                // 404 → model removed, mark permanently deprecated
+                if (res.status === 404)
+                    this.modelRegistry?.markDeprecated(this.cfg.model);
+                else
+                    this.modelRegistry?.recordFailure(this.cfg.model);
+                yield { type: "error", error: `Model API ${res.status}: ${err}`, status: res.status };
+                return;
+            }
+            break; // success — got an ok response
+        }
+        // Accumulate tool calls across chunks (they arrive fragmented)
+        const toolCallMap = new Map();
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buf = "";
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buf += decoder.decode(value, { stream: true });
+            const lines = buf.split("\n");
+            buf = lines.pop() ?? "";
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (!trimmed || trimmed === "data: [DONE]")
+                    continue;
+                if (!trimmed.startsWith("data: "))
+                    continue;
+                let chunk;
+                try {
+                    chunk = JSON.parse(trimmed.slice(6));
+                }
+                catch {
+                    continue;
+                }
+                const delta = chunk.choices?.[0]?.delta;
+                if (!delta)
+                    continue;
+                if (delta.content) {
+                    yield { type: "delta", text: delta.content };
+                }
+                if (delta.tool_calls) {
+                    for (const tc of delta.tool_calls) {
+                        const idx = tc.index ?? 0;
+                        const existing = toolCallMap.get(idx) ?? { id: "", name: "", args: "" };
+                        if (tc.id)
+                            existing.id += tc.id;
+                        if (tc.function?.name)
+                            existing.name += tc.function.name;
+                        if (tc.function?.arguments)
+                            existing.args += tc.function.arguments;
+                        toolCallMap.set(idx, existing);
+                    }
+                }
+                const finish = chunk.choices?.[0]?.finish_reason;
+                // Capture usage from final chunk (OpenAI/OpenRouter send this on finish)
+                if (chunk.usage) {
+                    yield {
+                        type: "done",
+                        finish_reason: finish ?? "usage",
+                        usage: {
+                            prompt_tokens: chunk.usage.prompt_tokens ?? 0,
+                            completion_tokens: chunk.usage.completion_tokens ?? 0,
+                        },
+                    };
+                }
+                if (finish === "tool_calls" || finish === "stop") {
+                    if (toolCallMap.size > 0) {
+                        const tool_calls = [...toolCallMap.values()].map(tc => ({
+                            id: tc.id || `call_${Date.now()}`,
+                            type: "function",
+                            function: { name: tc.name, arguments: tc.args },
+                        }));
+                        yield { type: "tool_call", tool_calls };
+                        toolCallMap.clear();
+                    }
+                    if (!chunk.usage)
+                        yield { type: "done", finish_reason: finish };
+                }
+            }
+        }
+        // Flush any remaining tool calls if stream ended without finish_reason
+        if (toolCallMap.size > 0) {
+            const tool_calls = [...toolCallMap.values()].map(tc => ({
+                id: tc.id || `call_${Date.now()}`,
+                type: "function",
+                function: { name: tc.name, arguments: tc.args },
+            }));
+            yield { type: "tool_call", tool_calls };
+        }
+        yield { type: "done", finish_reason: "end" };
+        // Report success to model registry
+        if (!hadError)
+            this.modelRegistry?.recordSuccess(this.cfg.model, Date.now() - t0);
+    }
+}
+//# sourceMappingURL=ModelClient.js.map

package/dist/runner/SwarmRouter.d.ts

@@ -0,0 +1,64 @@
+/**
+ * SwarmRouter — complexity scoring and task decomposition.
+ *
+ * For complex prompts (score >= threshold) the runner decomposes the request
+ * into 2–5 sub-tasks, executes them with a capped worker pool, then feeds all
+ * results to a reviewer model that synthesises a final answer.
+ *
+ * Sub-task execution is sequential inside each worker slot to avoid hammering
+ * the provider; concurrency is capped at Math.min(maxAgents, os.cpus().length).
+ */
+import type { ModelRegistry } from "../models/ModelRegistry.js";
+import type { ContextStore } from "../session/ContextStore.js";
+export interface SwarmConfig {
+    /** Maximum parallel workers (hard cap: 5). Default: min(cpuCount, 3). */
+    maxAgents?: number;
+    /** Complexity score threshold above which swarm activates. Default: 40. */
+    complexityThreshold?: number;
+    /** Use LLM planner for task decomposition (false = heuristic only for eco/normal). */
+    useLLM?: boolean;
+}
+export interface SubTaskResult {
+    task: string;
+    result: string;
+    model: string;
+    ms: number;
+    error?: string;
+}
+/**
+ * Returns a score 0–100 reflecting prompt complexity.
+ * Tuned so "check ETH price" ≈ 10, "analyze ETH and BTC then predict" ≈ 55.
+ */
+export declare function scoreComplexity(prompt: string): number;
+/** Original heuristic decomposer — used as fallback when LLM planner fails */
+export declare function decomposeHeuristic(prompt: string, maxTasks: number): string[];
+/** Exported for tests — heuristic only, no model call */
+export declare const decompose: typeof decomposeHeuristic;
+export declare class SwarmRouter {
+    private maxAgents;
+    private complexityThreshold;
+    private useLLM;
+    private modelRegistry?;
+    constructor(cfg?: SwarmConfig, modelReg?: ModelRegistry);
+    /** True when the prompt is complex enough to warrant swarm execution. */
+    shouldSwarm(prompt: string): boolean;
+    /**
+     * Decompose prompt into sub-tasks, execute them in groups of 3 (up to 5
+     * agents total), then synthesise with a reviewer model.
+     *
+     * Groups-of-3 planner:
+     *   tasks = decompose(prompt, maxAgents)     → 2–5 sub-tasks
+     *   batches = chunk(tasks, 3)                → [[t1,t2,t3],[t4,t5]] for 5 tasks
+     *   each batch runs in parallel; batches run sequentially
+     *   reviewer model synthesises all results into a unified answer
+     *
+     * @param prompt        - Original user message
+     * @param systemPrompt  - Current system prompt (passed to each sub-agent + reviewer)
+     * @param onProgress    - Called as each sub-task completes
+     */
+    run(prompt: string, systemPrompt: string, onProgress: (result: SubTaskResult, remaining: number) => void, contextStore?: ContextStore): Promise<{
+        synthesis: string;
+        subResults: SubTaskResult[];
+    }>;
+}
+//# sourceMappingURL=SwarmRouter.d.ts.map

package/dist/runner/SwarmRouter.js

@@ -0,0 +1,216 @@
+/**
+ * SwarmRouter — complexity scoring and task decomposition.
+ *
+ * For complex prompts (score >= threshold) the runner decomposes the request
+ * into 2–5 sub-tasks, executes them with a capped worker pool, then feeds all
+ * results to a reviewer model that synthesises a final answer.
+ *
+ * Sub-task execution is sequential inside each worker slot to avoid hammering
+ * the provider; concurrency is capped at Math.min(maxAgents, os.cpus().length).
+ */
+import os from "os";
+import { ModelClient, resolveModelChain } from "./ModelClient.js";
+// ── Complexity scoring ───────────────────────────────────────────────────────
+const CONJUNCTION_RE = /\b(and|also|then|additionally|plus|as well as|furthermore)\b/gi;
+const MULTI_CHAIN_RE = /\b(eth|btc|sol|bnb|avax|matic|cosmos|atom|arb|op)\b/gi;
+const ACTION_VERB_RE = /\b(analyze|compare|predict|scan|check|simulate|estimate|backtest|evaluate|assess)\b/gi;
+const QUESTION_RE = /\?/g;
+/**
+ * Returns a score 0–100 reflecting prompt complexity.
+ * Tuned so "check ETH price" ≈ 10, "analyze ETH and BTC then predict" ≈ 55.
+ */
+export function scoreComplexity(prompt) {
+    const conjunctions = (prompt.match(CONJUNCTION_RE) ?? []).length;
+    const chains = new Set((prompt.match(MULTI_CHAIN_RE) ?? []).map(s => s.toLowerCase())).size;
+    const actions = (prompt.match(ACTION_VERB_RE) ?? []).length;
+    const questions = (prompt.match(QUESTION_RE) ?? []).length;
+    const wordCount = prompt.trim().split(/\s+/).length;
+    return Math.min(100, conjunctions * 12 +
+        chains * 8 +
+        actions * 10 +
+        questions * 5 +
+        Math.floor(wordCount / 8));
+}
+// ── Task decomposition (# 29: LLM planner with heuristic fallback) ───────────
+/**
+ * LLM-based task planner. Uses a cheap worker model to decompose the prompt
+ * into focused sub-tasks as a JSON array. Falls back to heuristics on failure.
+ */
+async function planSubtasks(prompt, maxTasks, modelReg, useLLM = true) {
+    const cap = Math.max(2, Math.min(maxTasks, 5));
+    // Heuristic-only path when useLLM is false (eco/normal modes — saves model calls)
+    if (!useLLM) {
+        return decomposeHeuristic(prompt, cap);
+    }
+    // Attempt LLM decomposition with a cheap/fast model
+    try {
+        const chain = resolveModelChain(modelReg);
+        // Prefer a worker-tier model for planning (fast + cheap)
+        const plannerCfg = chain.find(c => modelReg?.getTier(c.model) === "worker") ?? chain[chain.length - 1] ?? chain[0];
+        const client = new ModelClient({ ...plannerCfg, temperature: 0.2 }, modelReg);
+        const plannerPrompt = `Split the following request into exactly ${cap} focused, non-overlapping sub-tasks.\n` +
+            `Each sub-task must be independently answerable using data tools.\n` +
+            `Output ONLY a valid JSON array of strings. No explanation, no markdown.\n\n` +
+            `Request: ${prompt}`;
+        let output = "";
+        for await (const chunk of client.stream([
+            { role: "system", content: "You output only valid JSON arrays of strings. No markdown, no explanation." },
+            { role: "user", content: plannerPrompt },
+        ], [])) {
+            if (chunk.type === "delta" && chunk.text)
+                output += chunk.text;
+            if (chunk.type === "error")
+                throw new Error(chunk.error);
+        }
+        // Extract JSON array from output (model might wrap in markdown)
+        const jsonMatch = output.match(/\[\s*"[\s\S]*?"\s*(?:,\s*"[\s\S]*?"\s*)*\]/);
+        if (jsonMatch) {
+            const tasks = JSON.parse(jsonMatch[0]);
+            if (Array.isArray(tasks) && tasks.every((t) => typeof t === "string") && tasks.length >= 2) {
+                return tasks.slice(0, cap);
+            }
+        }
+    }
+    catch {
+        // Fall through to heuristic decomposition
+    }
+    return decomposeHeuristic(prompt, cap);
+}
+/** Original heuristic decomposer — used as fallback when LLM planner fails */
+export function decomposeHeuristic(prompt, maxTasks) {
+    const cap = Math.max(2, Math.min(maxTasks, 5));
+    const parts = prompt
+        .split(/,\s*| and | also | then | additionally | plus /i)
+        .map(s => s.trim())
+        .filter(s => s.length > 4);
+    if (parts.length >= 2)
+        return parts.slice(0, cap);
+    const verbMatches = [...prompt.matchAll(/\b(analyze|compare|predict|scan|check|estimate|evaluate)\b[^,.?]*/gi)];
+    if (verbMatches.length >= 2)
+        return verbMatches.slice(0, cap).map(m => m[0].trim());
+    return [prompt];
+}
+/** Exported for tests — heuristic only, no model call */
+export const decompose = decomposeHeuristic;
+// ── Reviewer synthesis (#39: compact refs via ContextStore) ─────────────────
+async function reviewerSynthesize(originalPrompt, allResults, systemPrompt, modelReg, contextRef) {
+    const chain = resolveModelChain(modelReg);
+    const cfg = chain[0];
+    const client = new ModelClient(cfg, modelReg);
+    const results = allResults.filter(r => !r.error);
+    // #39: If ContextStore holds the full results, send compact summaries + reference
+    const context = contextRef
+        ? results.map((r, i) => `Sub-task ${i + 1} (${r.task.slice(0, 50)}): ${r.result.slice(0, 300)}...`).join("\n") + `\n\n${contextRef}`
+        : results
+            .map((r, i) => `### Sub-task ${i + 1}: ${r.task}\n${r.result}`)
+            .join("\n\n");
+    const messages = [
+        { role: "system", content: systemPrompt },
+        {
+            role: "user",
+            content: `You are a synthesis reviewer. Sub-tasks were executed for the following request.\n\n` +
+                `**Original request:** ${originalPrompt}\n\n` +
+                `**Sub-task results:**\n${context}\n\n` +
+                `Write a concise, unified answer that directly addresses the original request.`,
+        },
+    ];
+    let out = "";
+    for await (const chunk of client.stream(messages, [])) {
+        if (chunk.type === "delta" && chunk.text)
+            out += chunk.text;
+    }
+    return out || results.map(r => r.result).join("\n\n---\n\n");
+}
+// ── SwarmRouter class ────────────────────────────────────────────────────────
+export class SwarmRouter {
+    maxAgents;
+    complexityThreshold;
+    useLLM;
+    modelRegistry;
+    constructor(cfg = {}, modelReg) {
+        const cpus = os.cpus().length;
+        this.maxAgents = Math.min(cfg.maxAgents ?? Math.min(cpus, 3), 5);
+        this.complexityThreshold = cfg.complexityThreshold ?? 40;
+        this.useLLM = cfg.useLLM ?? true;
+        this.modelRegistry = modelReg;
+    }
+    /** True when the prompt is complex enough to warrant swarm execution. */
+    shouldSwarm(prompt) {
+        return scoreComplexity(prompt) >= this.complexityThreshold;
+    }
+    /**
+     * Decompose prompt into sub-tasks, execute them in groups of 3 (up to 5
+     * agents total), then synthesise with a reviewer model.
+     *
+     * Groups-of-3 planner:
+     *   tasks = decompose(prompt, maxAgents)     → 2–5 sub-tasks
+     *   batches = chunk(tasks, 3)                → [[t1,t2,t3],[t4,t5]] for 5 tasks
+     *   each batch runs in parallel; batches run sequentially
+     *   reviewer model synthesises all results into a unified answer
+     *
+     * @param prompt        - Original user message
+     * @param systemPrompt  - Current system prompt (passed to each sub-agent + reviewer)
+     * @param onProgress    - Called as each sub-task completes
+     */
+    async run(prompt, systemPrompt, onProgress, contextStore) {
+        // #29: Use LLM planner for task decomposition (falls back to heuristic)
+        const tasks = await planSubtasks(prompt, this.maxAgents, this.modelRegistry, this.useLLM);
+        const chain = resolveModelChain(this.modelRegistry);
+        const subResults = [];
+        // #39: Open a task context folder to offload sub-results (saves context window)
+        const taskCtx = contextStore?.openTask(`Swarm: ${prompt.slice(0, 60)}`);
+        // Split tasks into groups of 3 (the required "groups-of-3" planner)
+        const GROUP_SIZE = 3;
+        const batches = [];
+        for (let i = 0; i < tasks.length; i += GROUP_SIZE) {
+            batches.push(tasks.slice(i, i + GROUP_SIZE));
+        }
+        let modelIdx = 1; // reserve chain[0] for reviewer
+        const runOne = async (task, mIdx, remaining) => {
+            const cfg = chain[mIdx % chain.length] ?? chain[0];
+            const client = new ModelClient(cfg, this.modelRegistry);
+            const msgs = [
+                { role: "system", content: systemPrompt },
+                { role: "user", content: task },
+            ];
+            const t0 = Date.now();
+            let out = "";
+            let error;
+            for await (const chunk of client.stream(msgs, [])) {
+                if (chunk.type === "delta" && chunk.text)
+                    out += chunk.text;
+                if (chunk.type === "error")
+                    error = chunk.error ?? "Sub-task model error";
+            }
+            const r = {
+                task,
+                result: out || (error ? `(error: ${error})` : "(no output)"),
+                model: cfg.model,
+                ms: Date.now() - t0,
+                error,
+            };
+            subResults.push(r);
+            // #39: Write sub-result to context file instead of keeping raw in memory
+            if (taskCtx && contextStore) {
+                contextStore.appendFinding(taskCtx.taskId, `Sub-task: ${task.slice(0, 50)}`, r.result);
+            }
+            onProgress(r, remaining);
+        };
+        // Execute batches sequentially; within each batch run up to 3 in parallel
+        let remaining = tasks.length;
+        for (const batch of batches) {
+            await Promise.all(batch.map(task => {
+                remaining--;
+                return runOne(task, modelIdx++, remaining);
+            }));
+        }
+        // #39: Pass context reference to reviewer (compact path vs raw dump)
+        const contextRef = taskCtx ? contextStore?.getReference(taskCtx.taskId) : undefined;
+        const synthesis = await reviewerSynthesize(prompt, subResults, systemPrompt, this.modelRegistry, contextRef);
+        // Close the context folder (auto-deletes in 5s)
+        if (taskCtx)
+            contextStore?.closeTask(taskCtx.taskId);
+        return { synthesis, subResults };
+    }
+}
+//# sourceMappingURL=SwarmRouter.js.map

package/dist/runner/ToolDispatcher.d.ts

@@ -0,0 +1,29 @@
+/**
+ * ToolDispatcher — executes tool calls from the model response.
+ * Looks up tool by name in the Registry, validates params, runs execute().
+ */
+import type { Registry } from "../api/Registry.js";
+import type { ToolCall } from "./ModelClient.js";
+export interface ToolResult {
+    tool_call_id: string;
+    name: string;
+    content: string;
+    isError: boolean;
+}
+/** #40: Estimate chars that will be added to context by dispatching these calls */
+export declare function forecastContextGrowth(calls: {
+    function: {
+        name: string;
+    };
+}[]): number;
+export declare class ToolDispatcher {
+    private registry;
+    private failureCounts;
+    private openCircuits;
+    constructor(registry: Registry);
+    dispatch(calls: ToolCall[]): Promise<ToolResult[]>;
+    private execute;
+    private executeWithTimeout;
+    private executeInner;
+}
+//# sourceMappingURL=ToolDispatcher.d.ts.map