swarm-code 0.1.0

package/dist/memory/episodic.js

@@ -0,0 +1,390 @@
+/**
+ * Episodic memory — persists successful thread strategies to disk.
+ *
+ * Records episodes after successful thread completions:
+ *   - Task pattern (normalized keywords)
+ *   - Agent + model used
+ *   - Result quality (success, duration, cost, files changed)
+ *   - Task slot + complexity classification
+ *
+ * Recall: given a new task, find similar past episodes and return
+ * the strategies that worked. Used to inform agent/model selection
+ * and provide context hints to the orchestrator.
+ *
+ * Storage: JSON files in ~/.swarm/memory/episodes/ indexed by
+ * task similarity hash (trigram-based).
+ */
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+// ── Helpers ────────────────────────────────────────────────────────────────
+/** Stop words to filter from task keywords. */
+const STOP_WORDS = new Set([
+    "the",
+    "a",
+    "an",
+    "is",
+    "are",
+    "was",
+    "were",
+    "be",
+    "been",
+    "being",
+    "have",
+    "has",
+    "had",
+    "do",
+    "does",
+    "did",
+    "will",
+    "would",
+    "could",
+    "should",
+    "may",
+    "might",
+    "shall",
+    "can",
+    "to",
+    "of",
+    "in",
+    "for",
+    "on",
+    "with",
+    "at",
+    "by",
+    "from",
+    "as",
+    "into",
+    "through",
+    "during",
+    "before",
+    "after",
+    "above",
+    "below",
+    "between",
+    "and",
+    "but",
+    "or",
+    "not",
+    "no",
+    "all",
+    "each",
+    "every",
+    "both",
+    "few",
+    "more",
+    "most",
+    "other",
+    "some",
+    "such",
+    "than",
+    "too",
+    "very",
+    "just",
+    "about",
+    "this",
+    "that",
+    "these",
+    "those",
+    "it",
+    "its",
+    "my",
+    "your",
+    "our",
+]);
+/** Extract normalized keywords from a task string. */
+function extractKeywords(task) {
+    return task
+        .toLowerCase()
+        .replace(/[^a-z0-9\s-_./]/g, " ")
+        .split(/\s+/)
+        .filter((w) => w.length > 2 && !STOP_WORDS.has(w))
+        .sort();
+}
+/** Generate trigrams from a string for fuzzy matching. */
+function trigrams(s) {
+    const padded = `  ${s.toLowerCase()}  `;
+    const result = new Set();
+    for (let i = 0; i < padded.length - 2; i++) {
+        result.add(padded.slice(i, i + 3));
+    }
+    return result;
+}
+/** Compute Jaccard similarity between two trigram sets. */
+function trigramSimilarity(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 1;
+    let intersection = 0;
+    for (const t of a) {
+        if (b.has(t))
+            intersection++;
+    }
+    const union = a.size + b.size - intersection;
+    return union === 0 ? 0 : intersection / union;
+}
+/** Generate a deterministic episode ID. */
+function episodeId(task, timestamp) {
+    return createHash("sha256").update(`${task}:${timestamp}`).digest("hex").slice(0, 16);
+}
+// ── Episodic Memory Store ──────────────────────────────────────────────────
+export class EpisodicMemory {
+    memoryDir;
+    episodes = [];
+    loaded = false;
+    maxEpisodes;
+    constructor(memoryDir, maxEpisodes = 500) {
+        this.memoryDir = path.join(memoryDir, "episodes");
+        this.maxEpisodes = maxEpisodes;
+    }
+    /** Initialize — create directory and load existing episodes. */
+    async init() {
+        fs.mkdirSync(this.memoryDir, { recursive: true });
+        await this.loadAll();
+    }
+    /** Record a new episode from a completed thread. */
+    async record(params) {
+        // Only record successful episodes — failures don't teach useful strategies
+        if (!params.success) {
+            return {
+                id: "",
+                taskKeywords: [],
+                filesChangedCount: params.filesChanged.length,
+                timestamp: Date.now(),
+                ...params,
+            };
+        }
+        const timestamp = Date.now();
+        const episode = {
+            id: episodeId(params.task, timestamp),
+            task: params.task,
+            taskKeywords: extractKeywords(params.task),
+            agent: params.agent,
+            model: params.model,
+            slot: params.slot,
+            complexity: params.complexity,
+            success: params.success,
+            durationMs: params.durationMs,
+            estimatedCostUsd: params.estimatedCostUsd,
+            filesChangedCount: params.filesChanged.length,
+            filesChanged: params.filesChanged,
+            summary: params.summary.slice(0, 2000), // Cap stored summary
+            timestamp,
+        };
+        this.episodes.push(episode);
+        // Evict oldest if over capacity
+        if (this.episodes.length > this.maxEpisodes) {
+            const removed = this.episodes.shift();
+            this.deleteFile(removed.id);
+        }
+        // Persist to disk
+        await this.saveEpisode(episode);
+        return episode;
+    }
+    /**
+     * Recall similar past episodes for a given task.
+     * Returns episodes sorted by similarity (highest first).
+     */
+    recall(task, maxResults = 5, minSimilarity = 0.15) {
+        if (this.episodes.length === 0)
+            return [];
+        const taskTrigrams = trigrams(task);
+        const taskKeywords = new Set(extractKeywords(task));
+        const scored = [];
+        for (const episode of this.episodes) {
+            if (!episode.success)
+                continue;
+            // Trigram similarity on full task string
+            const triSim = trigramSimilarity(taskTrigrams, trigrams(episode.task));
+            // Keyword overlap bonus
+            const epKeywords = new Set(episode.taskKeywords);
+            let keywordOverlap = 0;
+            for (const kw of taskKeywords) {
+                if (epKeywords.has(kw))
+                    keywordOverlap++;
+            }
+            const maxKeywords = Math.max(taskKeywords.size, epKeywords.size);
+            const kwSim = maxKeywords > 0 ? keywordOverlap / maxKeywords : 0;
+            // Combined similarity (weighted: trigrams 60%, keywords 40%)
+            const similarity = triSim * 0.6 + kwSim * 0.4;
+            if (similarity >= minSimilarity) {
+                scored.push({ episode, similarity });
+            }
+        }
+        return scored.sort((a, b) => b.similarity - a.similarity).slice(0, maxResults);
+    }
+    /**
+     * Get strategy recommendations based on past episodes.
+     * Returns a formatted string for inclusion in orchestrator context.
+     */
+    getStrategyHints(task) {
+        const recalls = this.recall(task, 3, 0.2);
+        if (recalls.length === 0)
+            return null;
+        const lines = ["Past successful strategies for similar tasks:"];
+        for (const { episode, similarity } of recalls) {
+            const sim = (similarity * 100).toFixed(0);
+            const cost = episode.estimatedCostUsd.toFixed(4);
+            const duration = (episode.durationMs / 1000).toFixed(1);
+            lines.push(`  - [${sim}% match] "${episode.task.slice(0, 80)}" → ` +
+                `${episode.agent}/${episode.model} (${episode.slot}, ${duration}s, $${cost}, ` +
+                `${episode.filesChangedCount} files)`);
+        }
+        return lines.join("\n");
+    }
+    /**
+     * Get the best agent/model recommendation for a task based on past episodes.
+     * Returns null if no relevant episodes found.
+     */
+    recommendStrategy(task) {
+        const recalls = this.recall(task, 5, 0.25);
+        if (recalls.length === 0)
+            return null;
+        // Score agent+model pairs as composite keys to avoid mismatched combos
+        const pairScores = new Map();
+        for (const { episode, similarity } of recalls) {
+            const quality = 1 / (1 + episode.estimatedCostUsd * 10 + episode.durationMs / 60000);
+            const score = similarity * quality;
+            const pairKey = `${episode.agent}::${episode.model}`;
+            const existing = pairScores.get(pairKey);
+            if (existing) {
+                existing.score += score;
+            }
+            else {
+                pairScores.set(pairKey, { agent: episode.agent, model: episode.model, score });
+            }
+        }
+        // Pick highest-scoring agent+model pair
+        let bestPair = null;
+        for (const pair of pairScores.values()) {
+            if (!bestPair || pair.score > bestPair.score) {
+                bestPair = pair;
+            }
+        }
+        if (!bestPair)
+            return null;
+        return {
+            agent: bestPair.agent,
+            model: bestPair.model,
+            confidence: Math.min(1, recalls[0].similarity),
+        };
+    }
+    /**
+     * Get aggregate statistics across all episodes, grouped by agent.
+     *
+     * Returns per-agent success rates, average costs/durations, slot distributions,
+     * and a file-extension-to-agent mapping. Used by the model router as a fallback
+     * when no high-confidence episodic match exists.
+     *
+     * Returns null if no episodes are loaded (graceful degradation).
+     */
+    getAggregateStats() {
+        if (this.episodes.length === 0)
+            return null;
+        const perAgent = new Map();
+        const fileExtensions = new Map();
+        for (const episode of this.episodes) {
+            if (!episode.success)
+                continue;
+            // Initialize agent stats if needed
+            let stats = perAgent.get(episode.agent);
+            if (!stats) {
+                stats = {
+                    totalEpisodes: 0,
+                    avgDurationMs: 0,
+                    avgCostUsd: 0,
+                    slotCounts: new Map(),
+                    fileExtensions: new Set(),
+                };
+                perAgent.set(episode.agent, stats);
+            }
+            // Running average: update incrementally
+            const n = stats.totalEpisodes;
+            stats.avgDurationMs = (stats.avgDurationMs * n + episode.durationMs) / (n + 1);
+            stats.avgCostUsd = (stats.avgCostUsd * n + episode.estimatedCostUsd) / (n + 1);
+            stats.totalEpisodes++;
+            // Slot counts
+            if (episode.slot) {
+                stats.slotCounts.set(episode.slot, (stats.slotCounts.get(episode.slot) || 0) + 1);
+            }
+            // Extract file extensions from changed files
+            for (const filePath of episode.filesChanged) {
+                const dotIdx = filePath.lastIndexOf(".");
+                if (dotIdx !== -1 && dotIdx < filePath.length - 1) {
+                    const ext = filePath.slice(dotIdx).toLowerCase();
+                    stats.fileExtensions.add(ext);
+                    // Update global file extension → agent mapping
+                    let agentMap = fileExtensions.get(ext);
+                    if (!agentMap) {
+                        agentMap = new Map();
+                        fileExtensions.set(ext, agentMap);
+                    }
+                    agentMap.set(episode.agent, (agentMap.get(episode.agent) || 0) + 1);
+                }
+            }
+        }
+        return { perAgent, fileExtensions };
+    }
+    /** Get total episode count. */
+    get size() {
+        return this.episodes.length;
+    }
+    /** Get all episodes (for viewer). */
+    getAll() {
+        return [...this.episodes];
+    }
+    // ── Persistence ──────────────────────────────────────────────────────────
+    async loadAll() {
+        if (this.loaded)
+            return;
+        this.loaded = true;
+        if (!fs.existsSync(this.memoryDir))
+            return;
+        let files;
+        try {
+            files = fs.readdirSync(this.memoryDir).filter((f) => f.endsWith(".json"));
+        }
+        catch {
+            return;
+        }
+        for (const file of files) {
+            try {
+                const raw = fs.readFileSync(path.join(this.memoryDir, file), "utf-8");
+                const episode = JSON.parse(raw);
+                if (episode.id && episode.task) {
+                    this.episodes.push(episode);
+                }
+            }
+            catch {
+                // Skip corrupt files
+            }
+        }
+        // Sort by timestamp (oldest first for consistent eviction)
+        this.episodes.sort((a, b) => a.timestamp - b.timestamp);
+        // Trim to max
+        while (this.episodes.length > this.maxEpisodes) {
+            const removed = this.episodes.shift();
+            this.deleteFile(removed.id);
+        }
+    }
+    async saveEpisode(episode) {
+        try {
+            const filePath = path.join(this.memoryDir, `${episode.id}.json`);
+            fs.writeFileSync(filePath, JSON.stringify(episode, null, 2), "utf-8");
+        }
+        catch {
+            // Non-fatal — memory is best-effort
+        }
+    }
+    deleteFile(id) {
+        try {
+            const filePath = path.join(this.memoryDir, `${id}.json`);
+            if (fs.existsSync(filePath)) {
+                fs.unlinkSync(filePath);
+            }
+        }
+        catch {
+            // Non-fatal
+        }
+    }
+}
+//# sourceMappingURL=episodic.js.map

package/dist/prompts/orchestrator.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Orchestrator system prompt — teaches the LLM how to use swarm primitives.
+ */
+import type { SwarmConfig } from "../core/types.js";
+export declare function buildSwarmSystemPrompt(config: SwarmConfig, agentDescriptions?: string): string;

package/dist/prompts/orchestrator.js

@@ -0,0 +1,191 @@
+/**
+ * Orchestrator system prompt — teaches the LLM how to use swarm primitives.
+ */
+export function buildSwarmSystemPrompt(config, agentDescriptions) {
+    return `You are a Swarm Orchestrator — a Recursive Language Model (RLM) agent enhanced with the ability to spawn coding agent threads in isolated git worktrees.
+
+## Available Primitives
+
+### 1. \`context\` variable
+The full input text or codebase listing (may be very large). Check \`len(context)\` first.
+
+### 2. \`llm_query(sub_context, instruction)\` — Lightweight analysis
+Send text to an LLM for summarization, extraction, classification. No file changes.
+For parallel queries: \`async_llm_query()\` with \`asyncio.gather()\`.
+
+### 3. \`thread(task, context="", agent="${config.default_agent}", model="${config.default_model}", files=None)\` — Coding agent thread
+Spawns a coding agent in an isolated git worktree. The agent can read/write files, run commands, etc.
+Returns a compressed result string (status, files changed, diff, output summary).
+
+Parameters:
+  - \`task\`: What the agent should do (be specific and self-contained)
+  - \`context\`: Additional context to include (extracted code, requirements, etc.)
+  - \`agent\`: Agent backend — choose based on task (see Available Agents below)
+  - \`model\`: Model in provider/model-id format (e.g., "anthropic/claude-sonnet-4-6", "openai/gpt-4o", "google/gemini-2.5-flash")
+  - \`files\`: List of relevant file paths (hint for the agent)
+
+### 4. \`async_thread(task, context="", agent="${config.default_agent}", model="${config.default_model}", files=None)\` — Parallel threads
+Same as thread() but async. Use with \`asyncio.gather()\` for parallel execution.
+
+### 5. \`merge_threads()\` — Merge all completed thread branches
+Merges thread branches back into the main branch sequentially. Returns merge status.
+
+### 6. \`FINAL(answer)\` / \`FINAL_VAR(variable)\` — Return answer
+Call when you have a complete answer or summary of work done.
+
+${agentDescriptions
+        ? `## Available Agents
+
+${agentDescriptions}
+
+**Agent selection by task slot:**
+- **Execution** (coding, fixing, building): Use \`opencode\` or \`codex\` — fast, tool-capable
+- **Search** (finding files, researching docs): Use \`direct-llm\` — lightweight, no agent overhead
+- **Reasoning** (analysis, debugging, review): Use \`claude-code\` or \`direct-llm\` — deep analysis
+- **Planning** (design, architecture, strategy): Use \`direct-llm\` or \`claude-code\` — structured thinking
+
+**Model tier by complexity:**
+- **Simple** (rename, lint, format): Use cheap models (haiku, gpt-4o-mini)
+- **Standard** (bug fixes, features, tests): Use default models (sonnet, o3-mini)
+- **Complex** (refactoring, migrations): Use premium models (opus, o3)
+- **OpenAI-specific**: Use \`codex\` for best o3/gpt-4o compatibility
+- When in doubt, use \`${config.default_agent}\` with the default model
+
+`
+        : ""}## Strategy
+
+1. **Analyze first**: Use \`llm_query()\` or direct Python to understand the codebase/task
+2. **Decompose**: Break the task into independent, parallelizable units
+3. **Extract context**: For each thread, extract ONLY the relevant code/context — don't send everything
+4. **Spawn threads**: Use \`async_thread()\` + \`asyncio.gather()\` for parallel work
+5. **Inspect results**: Check each thread's result for success/failure
+6. **Merge**: Call \`merge_threads()\` to integrate changes
+7. **Verify**: Optionally spawn a test thread to verify the merged result
+8. **Report**: Call \`FINAL()\` with a summary
+
+## Episode Quality & Caching
+
+- **Thread results are episodes**: Each thread returns a compressed summary of only the successful operations and conclusions — failed attempts, stack traces, and retries are filtered out automatically.
+- **Subthread caching**: Identical threads (same task + files + agent + model) are cached. If you spawn the same thread twice, the second call returns instantly from cache. Design your tasks to be deterministic and reusable where possible.
+- **Cost optimization**: Prefer spawning many small, focused threads over few large ones. Small threads cache better and fail more gracefully.
+
+## Rules
+
+1. Write valid Python 3 code in \`\`\`python blocks
+2. Be specific in thread tasks — each thread should be self-contained
+3. Pass relevant context to threads — they run in clean worktrees and don't see other threads' changes
+4. Use \`print()\` for intermediate output visible in the next iteration
+5. Max ${config.max_threads} concurrent threads, ${config.max_total_threads} total per session
+6. Thread timeout: ${config.thread_timeout_ms / 1000}s per thread
+7. Don't call FINAL prematurely — verify thread results first
+8. The REPL persists state — variables survive across iterations
+
+## Examples
+
+**Single thread:**
+\`\`\`python
+result = thread("Fix the authentication bug in src/auth.ts — the JWT token validation is not checking expiry",
+                context="The auth module uses jsonwebtoken library...",
+                files=["src/auth.ts", "src/middleware/auth.ts"])
+print(result)
+\`\`\`
+
+**Parallel threads:**
+\`\`\`python
+import asyncio
+
+results = await asyncio.gather(
+    async_thread("Add input validation to the POST /users endpoint", files=["src/routes/users.ts"]),
+    async_thread("Add input validation to the POST /orders endpoint", files=["src/routes/orders.ts"]),
+    async_thread("Add input validation to the POST /products endpoint", files=["src/routes/products.ts"]),
+)
+
+for i, r in enumerate(results):
+    print(f"Thread {i+1}: {r[:200]}")
+\`\`\`
+
+**Analyze then act:**
+\`\`\`python
+# First, understand the codebase
+analysis = llm_query(context[:5000], "List all API route files and their endpoints")
+print(analysis)
+\`\`\`
+
+Then in the next iteration:
+\`\`\`python
+# Now spawn threads based on analysis
+import asyncio
+tasks = []
+for route_file in route_files:
+    tasks.append(async_thread(f"Add error handling to {route_file}", files=[route_file]))
+results = await asyncio.gather(*tasks)
+\`\`\`
+
+**Merge and verify:**
+\`\`\`python
+merge_result = merge_threads()
+print(merge_result)
+
+# Verify
+test_result = thread("Run the test suite and fix any failures", files=["package.json"])
+print(test_result)
+
+FINAL(f"Completed: added error handling to {len(route_files)} route files. All threads merged successfully.")
+\`\`\`
+
+**Thread DAG composition (T1+T2 → T3):**
+\`\`\`python
+import asyncio
+
+# Stage 1: Research in parallel (variables persist across iterations)
+analysis, test_gaps = await asyncio.gather(
+    async_thread("Analyze the auth module and list all endpoints without rate limiting",
+                 files=["src/auth/"], agent="direct-llm"),
+    async_thread("Run the test suite and identify files with <50% coverage",
+                 files=["package.json"]),
+)
+print("Analysis:", analysis[:300])
+print("Test gaps:", test_gaps[:300])
+\`\`\`
+
+Then compose results into downstream threads:
+\`\`\`python
+import asyncio
+
+# Stage 2: Act on Stage 1 results (compose thread outputs as input context)
+impl_results = await asyncio.gather(
+    async_thread("Add rate limiting to these endpoints", context=analysis,
+                 files=["src/auth/middleware.ts"]),
+    async_thread("Add tests for the files with low coverage", context=test_gaps,
+                 files=["src/__tests__/"]),
+)
+
+# Stage 3: Merge and validate
+merge_threads()
+final_check = thread("Run full test suite, verify rate limiting works, fix failures",
+                      context=f"Rate limiting: {impl_results[0][:200]}\\nNew tests: {impl_results[1][:200]}")
+print(final_check)
+\`\`\`
+
+**Multi-stage pipeline with re-routing on failure:**
+\`\`\`python
+# Attempt with cheap model first
+result = thread("Fix the flaky test in test_auth.py", agent="aider",
+                model="anthropic/claude-haiku-4-5", files=["tests/test_auth.py"])
+if "FAILED" in result:
+    # Escalate to premium model with the failure context
+    result = thread("Fix this test — previous attempt failed", context=result,
+                    agent="claude-code", model="claude-opus-4-6",
+                    files=["tests/test_auth.py", "src/auth.py"])
+print(result)
+\`\`\`
+
+## Output format
+
+Respond with ONLY a Python code block. No explanation before or after.
+
+\`\`\`python
+# Your code here
+\`\`\``;
+}
+//# sourceMappingURL=orchestrator.js.map