swarm-code 0.1.0

package/dist/config.js

@@ -0,0 +1,170 @@
+/**
+ * Configuration loader for swarm-code.
+ *
+ * Reads swarm_config.yaml (or rlm_config.yaml fallback) from project root or cwd.
+ * Extends RLM config with swarm-specific fields.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+const DEFAULTS = {
+    // RLM defaults
+    max_iterations: 20,
+    max_depth: 3,
+    max_sub_queries: 50,
+    truncate_len: 5000,
+    metadata_preview_lines: 20,
+    // Swarm defaults
+    max_threads: 5,
+    max_total_threads: 20,
+    thread_timeout_ms: 300000,
+    max_thread_budget_usd: 1.0,
+    max_session_budget_usd: 10.0,
+    default_agent: "opencode",
+    default_model: "anthropic/claude-sonnet-4-6",
+    auto_model_selection: false,
+    compression_strategy: "structured",
+    compression_max_tokens: 1000,
+    worktree_base_dir: ".swarm-worktrees",
+    auto_cleanup_worktrees: true,
+    episodic_memory_enabled: false,
+    memory_dir: path.join(os.homedir(), ".swarm", "memory"),
+    thread_retries: 1,
+    model_slots: {
+        execution: "", // empty = use agent's default based on complexity
+        search: "",
+        reasoning: "",
+        planning: "",
+    },
+    thread_cache_persist: false,
+    thread_cache_dir: path.join(os.homedir(), ".swarm", "cache"),
+    thread_cache_ttl_hours: 24,
+    opencode_server_mode: true,
+};
+function parseYaml(text) {
+    // Minimal YAML parser for flat key:value files (no nested objects, no arrays)
+    const result = {};
+    for (const line of text.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const colonIdx = trimmed.indexOf(":");
+        if (colonIdx === -1)
+            continue;
+        const key = trimmed.slice(0, colonIdx).trim();
+        const rawVal = trimmed.slice(colonIdx + 1).trim();
+        // Strip inline comments (but not inside quoted strings)
+        let val;
+        if ((rawVal.startsWith('"') && rawVal.includes('"', 1)) || (rawVal.startsWith("'") && rawVal.includes("'", 1))) {
+            // Quoted value — don't strip inline comments
+            val = rawVal;
+        }
+        else {
+            val = rawVal.replace(/\s+#.*$/, "");
+        }
+        // Parse number
+        const num = Number(val);
+        if (!Number.isNaN(num) && val !== "") {
+            result[key] = num;
+        }
+        else if (val === "true") {
+            result[key] = true;
+        }
+        else if (val === "false") {
+            result[key] = false;
+        }
+        else {
+            // Strip quotes
+            result[key] = val.replace(/^["']|["']$/g, "");
+        }
+    }
+    return result;
+}
+export function loadConfig(cwd) {
+    // Search order: cwd swarm_config, cwd rlm_config, package root swarm_config, package root rlm_config
+    // User prefs (~/.swarm/config.yaml) are overlaid on top of the first found project config
+    const projectDir = cwd || process.cwd();
+    const pkgRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+    const userConfigPath = path.join(os.homedir(), ".swarm", "config.yaml");
+    const candidates = [
+        path.resolve(projectDir, "swarm_config.yaml"),
+        path.resolve(projectDir, "rlm_config.yaml"),
+        path.resolve(pkgRoot, "swarm_config.yaml"),
+        path.resolve(pkgRoot, "rlm_config.yaml"),
+    ];
+    for (const configPath of candidates) {
+        if (fs.existsSync(configPath)) {
+            try {
+                const raw = fs.readFileSync(configPath, "utf-8");
+                let parsed = parseYaml(raw);
+                // Overlay user preferences from ~/.swarm/config.yaml
+                if (fs.existsSync(userConfigPath)) {
+                    try {
+                        const userRaw = fs.readFileSync(userConfigPath, "utf-8");
+                        const userParsed = parseYaml(userRaw);
+                        parsed = { ...parsed, ...userParsed };
+                    }
+                    catch {
+                        /* ignore malformed user config */
+                    }
+                }
+                const clamp = (v, min, max, def) => typeof v === "number" && Number.isFinite(v) ? Math.max(min, Math.min(max, Math.round(v))) : def;
+                const str = (v, def) => (typeof v === "string" && v.length > 0 ? v : def);
+                const bool = (v, def) => (typeof v === "boolean" ? v : def);
+                const validStrategies = ["structured", "llm-summary", "diff-only", "truncate"];
+                const strategyVal = str(parsed.compression_strategy, DEFAULTS.compression_strategy);
+                const strategy = validStrategies.includes(strategyVal)
+                    ? strategyVal
+                    : DEFAULTS.compression_strategy;
+                return {
+                    // RLM fields
+                    max_iterations: clamp(parsed.max_iterations, 1, 100, DEFAULTS.max_iterations),
+                    max_depth: clamp(parsed.max_depth, 1, 10, DEFAULTS.max_depth),
+                    max_sub_queries: clamp(parsed.max_sub_queries, 1, 500, DEFAULTS.max_sub_queries),
+                    truncate_len: clamp(parsed.truncate_len, 500, 50000, DEFAULTS.truncate_len),
+                    metadata_preview_lines: clamp(parsed.metadata_preview_lines, 5, 100, DEFAULTS.metadata_preview_lines),
+                    // Swarm fields
+                    max_threads: clamp(parsed.max_threads, 1, 20, DEFAULTS.max_threads),
+                    max_total_threads: clamp(parsed.max_total_threads, 1, 100, DEFAULTS.max_total_threads),
+                    thread_timeout_ms: clamp(parsed.thread_timeout_ms, 10000, 3600000, DEFAULTS.thread_timeout_ms),
+                    max_thread_budget_usd: typeof parsed.max_thread_budget_usd === "number" &&
+                        Number.isFinite(parsed.max_thread_budget_usd) &&
+                        parsed.max_thread_budget_usd > 0
+                        ? parsed.max_thread_budget_usd
+                        : DEFAULTS.max_thread_budget_usd,
+                    max_session_budget_usd: typeof parsed.max_session_budget_usd === "number" &&
+                        Number.isFinite(parsed.max_session_budget_usd) &&
+                        parsed.max_session_budget_usd > 0
+                        ? parsed.max_session_budget_usd
+                        : DEFAULTS.max_session_budget_usd,
+                    default_agent: str(parsed.default_agent, DEFAULTS.default_agent),
+                    default_model: str(parsed.default_model, DEFAULTS.default_model),
+                    auto_model_selection: bool(parsed.auto_model_selection, DEFAULTS.auto_model_selection),
+                    compression_strategy: strategy,
+                    compression_max_tokens: clamp(parsed.compression_max_tokens, 100, 10000, DEFAULTS.compression_max_tokens),
+                    worktree_base_dir: str(parsed.worktree_base_dir, DEFAULTS.worktree_base_dir),
+                    auto_cleanup_worktrees: bool(parsed.auto_cleanup_worktrees, DEFAULTS.auto_cleanup_worktrees),
+                    episodic_memory_enabled: bool(parsed.episodic_memory_enabled, DEFAULTS.episodic_memory_enabled),
+                    memory_dir: str(parsed.memory_dir, DEFAULTS.memory_dir),
+                    thread_retries: clamp(parsed.thread_retries, 0, 3, DEFAULTS.thread_retries),
+                    model_slots: {
+                        execution: str(parsed.model_slot_execution, DEFAULTS.model_slots.execution),
+                        search: str(parsed.model_slot_search, DEFAULTS.model_slots.search),
+                        reasoning: str(parsed.model_slot_reasoning, DEFAULTS.model_slots.reasoning),
+                        planning: str(parsed.model_slot_planning, DEFAULTS.model_slots.planning),
+                    },
+                    thread_cache_persist: bool(parsed.thread_cache_persist, DEFAULTS.thread_cache_persist),
+                    thread_cache_dir: str(parsed.thread_cache_dir, DEFAULTS.thread_cache_dir),
+                    thread_cache_ttl_hours: clamp(parsed.thread_cache_ttl_hours, 1, 720, DEFAULTS.thread_cache_ttl_hours),
+                    opencode_server_mode: bool(parsed.opencode_server_mode, DEFAULTS.opencode_server_mode),
+                };
+            }
+            catch {
+                // Fall through to defaults
+            }
+        }
+    }
+    return { ...DEFAULTS };
+}
+//# sourceMappingURL=config.js.map

package/dist/core/repl.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Persistent Python REPL manager for swarm-code.
+ *
+ * Spawns a single Python subprocess running `runtime.py` and keeps it alive
+ * across multiple RLM iterations. Communication uses line-delimited JSON
+ * over stdin/stdout.
+ *
+ * Extended from rlm-cli with thread_request and merge_request handlers.
+ */
+/** Result of executing a code snippet in the REPL. */
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    hasFinal: boolean;
+    finalValue: string | null;
+}
+/** Callback the host provides to handle llm_query() calls from Python. */
+export type LlmQueryHandler = (subContext: string, instruction: string) => Promise<string>;
+/** Callback the host provides to handle thread() calls from Python. */
+export type ThreadHandler = (task: string, context: string, agentBackend: string, model: string, files: string[]) => Promise<{
+    result: string;
+    success: boolean;
+    filesChanged: string[];
+    durationMs: number;
+}>;
+/** Callback the host provides to handle merge_threads() calls from Python. */
+export type MergeHandler = () => Promise<{
+    result: string;
+    success: boolean;
+}>;
+export declare class PythonRepl {
+    private proc;
+    private rl;
+    private llmQueryHandler;
+    private threadHandler;
+    private mergeHandler;
+    /**
+     * Pending resolvers for messages we're waiting on from Python.
+     * Each entry maps a message type to a one-shot resolve/reject pair.
+     */
+    private pending;
+    /** Whether the REPL subprocess is alive. */
+    get isAlive(): boolean;
+    /**
+     * Start the Python subprocess and wait for it to signal readiness.
+     */
+    start(signal?: AbortSignal): Promise<void>;
+    /** Register the callback that handles llm_query() calls from Python. */
+    setLlmQueryHandler(handler: LlmQueryHandler): void;
+    /** Register the callback that handles thread() calls from Python. */
+    setThreadHandler(handler: ThreadHandler): void;
+    /** Register the callback that handles merge_threads() calls from Python. */
+    setMergeHandler(handler: MergeHandler): void;
+    /** Inject the full context string into the Python REPL. */
+    setContext(text: string): Promise<void>;
+    /** Reset the Final sentinel variable. */
+    resetFinal(): Promise<void>;
+    /** Execute a code snippet and return the result. */
+    execute(code: string): Promise<ExecResult>;
+    /** Gracefully shut down the Python subprocess. */
+    shutdown(): void;
+    private send;
+    private handleLine;
+    private handleLlmQueryMessage;
+    private handleThreadRequestMessage;
+    private handleMergeRequestMessage;
+    private waitForMessage;
+    private cleanup;
+}

package/dist/core/repl.js

@@ -0,0 +1,336 @@
+/**
+ * Persistent Python REPL manager for swarm-code.
+ *
+ * Spawns a single Python subprocess running `runtime.py` and keeps it alive
+ * across multiple RLM iterations. Communication uses line-delimited JSON
+ * over stdin/stdout.
+ *
+ * Extended from rlm-cli with thread_request and merge_request handlers.
+ */
+import { execFileSync, spawn } from "node:child_process";
+import * as os from "node:os";
+import * as path from "node:path";
+import * as readline from "node:readline";
+import { fileURLToPath } from "node:url";
+/**
+ * Verify Python 3 is available. Throws a clear error if not found.
+ */
+function ensurePython(cmd) {
+    try {
+        const version = execFileSync(cmd, ["--version"], {
+            encoding: "utf-8",
+            timeout: 5000,
+            stdio: ["ignore", "pipe", "pipe"],
+        }).trim();
+        const major = Number.parseInt(version.replace(/^Python\s*/, "").split(".")[0], 10);
+        if (major < 3) {
+            throw new Error(`swarm-code requires Python 3 but found ${version}. Install Python 3.x from https://python.org`);
+        }
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            throw new Error(`swarm-code requires Python 3 but "${cmd}" was not found on PATH. Install Python 3.x from https://python.org`);
+        }
+        throw err;
+    }
+}
+// ── REPL class ──────────────────────────────────────────────────────────────
+export class PythonRepl {
+    proc = null;
+    rl = null;
+    llmQueryHandler = null;
+    threadHandler = null;
+    mergeHandler = null;
+    /**
+     * Pending resolvers for messages we're waiting on from Python.
+     * Each entry maps a message type to a one-shot resolve/reject pair.
+     */
+    pending = new Map();
+    /** Whether the REPL subprocess is alive. */
+    get isAlive() {
+        return this.proc !== null && this.proc.exitCode === null;
+    }
+    /**
+     * Start the Python subprocess and wait for it to signal readiness.
+     */
+    async start(signal) {
+        if (this.isAlive)
+            return;
+        const runtimePath = path.join(path.dirname(fileURLToPath(import.meta.url)), "runtime.py");
+        const pythonCmd = process.platform === "win32" ? "python" : "python3";
+        ensurePython(pythonCmd);
+        const homeDir = os.homedir();
+        this.proc = spawn(pythonCmd, [runtimePath], {
+            stdio: ["pipe", "pipe", "pipe"],
+            env: {
+                // Only pass what Python actually needs — not API keys or secrets
+                PATH: process.env.PATH,
+                HOME: homeDir,
+                USERPROFILE: homeDir, // Windows uses USERPROFILE
+                PYTHONUNBUFFERED: "1",
+                // Windows needs SystemRoot/SYSTEMROOT for Python to find DLLs
+                ...(process.env.SystemRoot ? { SystemRoot: process.env.SystemRoot } : {}),
+                ...(process.env.SYSTEMROOT ? { SYSTEMROOT: process.env.SYSTEMROOT } : {}),
+            },
+        });
+        this.rl = readline.createInterface({ input: this.proc.stdout });
+        this.rl.on("line", (line) => this.handleLine(line));
+        this.proc.stderr.on("data", (chunk) => {
+            const text = chunk.toString();
+            if (text.trim()) {
+                process.stderr.write(`[swarm-repl-python] ${text}`);
+            }
+        });
+        this.proc.on("close", () => {
+            this.cleanup();
+        });
+        if (signal) {
+            signal.addEventListener("abort", () => {
+                this.shutdown();
+            }, { once: true });
+        }
+        await this.waitForMessage("ready");
+    }
+    /** Register the callback that handles llm_query() calls from Python. */
+    setLlmQueryHandler(handler) {
+        this.llmQueryHandler = handler;
+    }
+    /** Register the callback that handles thread() calls from Python. */
+    setThreadHandler(handler) {
+        this.threadHandler = handler;
+    }
+    /** Register the callback that handles merge_threads() calls from Python. */
+    setMergeHandler(handler) {
+        this.mergeHandler = handler;
+    }
+    /** Inject the full context string into the Python REPL. */
+    async setContext(text) {
+        this.send({ type: "set_context", value: text });
+        await this.waitForMessage("context_set");
+    }
+    /** Reset the Final sentinel variable. */
+    async resetFinal() {
+        this.send({ type: "reset_final" });
+        await this.waitForMessage("final_reset");
+    }
+    /** Execute a code snippet and return the result. */
+    async execute(code) {
+        this.send({ type: "exec", code });
+        const msg = (await this.waitForMessage("exec_done"));
+        return {
+            stdout: msg.stdout,
+            stderr: msg.stderr,
+            hasFinal: msg.has_final,
+            finalValue: msg.final_value,
+        };
+    }
+    /** Gracefully shut down the Python subprocess. */
+    shutdown() {
+        if (this.proc && this.proc.exitCode === null) {
+            const proc = this.proc;
+            try {
+                this.send({ type: "shutdown" });
+            }
+            catch {
+                // stdin may already be closed
+            }
+            if (process.platform === "win32") {
+                // Windows: SIGTERM is ignored, kill immediately
+                try {
+                    proc.kill("SIGKILL");
+                }
+                catch {
+                    /* already dead */
+                }
+            }
+            else {
+                // Unix: give Python 500ms to exit gracefully, then force kill
+                const killTimer = setTimeout(() => {
+                    try {
+                        if (proc.exitCode === null)
+                            proc.kill("SIGKILL");
+                    }
+                    catch { }
+                }, 500);
+                proc.on("exit", () => clearTimeout(killTimer));
+                try {
+                    proc.kill("SIGTERM");
+                }
+                catch {
+                    /* already dead */
+                }
+            }
+        }
+        this.cleanup();
+    }
+    // ── Internal ─────────────────────────────────────────────────────────────
+    send(msg) {
+        if (!this.proc || !this.proc.stdin || this.proc.stdin.destroyed) {
+            throw new Error("REPL subprocess is not running");
+        }
+        try {
+            this.proc.stdin.write(`${JSON.stringify(msg)}\n`);
+        }
+        catch {
+            throw new Error("REPL subprocess stdin write failed");
+        }
+    }
+    handleLine(line) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            return;
+        let msg;
+        try {
+            msg = JSON.parse(trimmed);
+        }
+        catch {
+            return;
+        }
+        // Handle async message types (don't go through pending)
+        if (msg.type === "llm_query") {
+            this.handleLlmQueryMessage(msg).catch((err) => {
+                process.stderr.write(`[swarm] llm_query handler error: ${err?.message || err}\n`);
+            });
+            return;
+        }
+        if (msg.type === "thread_request") {
+            this.handleThreadRequestMessage(msg).catch((err) => {
+                process.stderr.write(`[swarm] thread_request handler error: ${err?.message || err}\n`);
+            });
+            return;
+        }
+        if (msg.type === "merge_request") {
+            this.handleMergeRequestMessage(msg).catch((err) => {
+                process.stderr.write(`[swarm] merge_request handler error: ${err?.message || err}\n`);
+            });
+            return;
+        }
+        const entry = this.pending.get(msg.type);
+        if (entry) {
+            this.pending.delete(msg.type);
+            entry.resolve(msg);
+        }
+    }
+    async handleLlmQueryMessage(msg) {
+        if (!this.llmQueryHandler) {
+            this.send({
+                type: "llm_result",
+                id: msg.id,
+                result: "[ERROR] No LLM query handler registered",
+            });
+            return;
+        }
+        try {
+            const result = await this.llmQueryHandler(msg.sub_context, msg.instruction);
+            this.send({ type: "llm_result", id: msg.id, result });
+        }
+        catch (err) {
+            const errorText = err instanceof Error ? err.message : String(err);
+            this.send({
+                type: "llm_result",
+                id: msg.id,
+                result: `[ERROR] LLM query failed: ${errorText}`,
+            });
+        }
+    }
+    async handleThreadRequestMessage(msg) {
+        if (!this.threadHandler) {
+            this.send({
+                type: "thread_result",
+                id: msg.id,
+                result: "[ERROR] No thread handler registered. Run in swarm mode to use thread().",
+                success: false,
+                files_changed: [],
+                duration_ms: 0,
+            });
+            return;
+        }
+        try {
+            const result = await this.threadHandler(msg.task, msg.context, msg.agent_backend, msg.model, msg.files || []);
+            this.send({
+                type: "thread_result",
+                id: msg.id,
+                result: result.result,
+                success: result.success,
+                files_changed: result.filesChanged,
+                duration_ms: result.durationMs,
+            });
+        }
+        catch (err) {
+            const errorText = err instanceof Error ? err.message : String(err);
+            this.send({
+                type: "thread_result",
+                id: msg.id,
+                result: `[ERROR] Thread failed: ${errorText}`,
+                success: false,
+                files_changed: [],
+                duration_ms: 0,
+            });
+        }
+    }
+    async handleMergeRequestMessage(msg) {
+        if (!this.mergeHandler) {
+            this.send({
+                type: "merge_result",
+                id: msg.id,
+                result: "[ERROR] No merge handler registered. Run in swarm mode to use merge_threads().",
+                success: false,
+            });
+            return;
+        }
+        try {
+            const result = await this.mergeHandler();
+            this.send({
+                type: "merge_result",
+                id: msg.id,
+                result: result.result,
+                success: result.success,
+            });
+        }
+        catch (err) {
+            const errorText = err instanceof Error ? err.message : String(err);
+            this.send({
+                type: "merge_result",
+                id: msg.id,
+                result: `[ERROR] Merge failed: ${errorText}`,
+                success: false,
+            });
+        }
+    }
+    waitForMessage(type) {
+        return new Promise((resolve, reject) => {
+            if (!this.isAlive) {
+                reject(new Error(`REPL subprocess is not running (waiting for "${type}")`));
+                return;
+            }
+            const timeout = setTimeout(() => {
+                if (this.pending.has(type)) {
+                    this.pending.delete(type);
+                    reject(new Error(`Timeout waiting for "${type}" from Python REPL`));
+                }
+            }, 300_000);
+            this.pending.set(type, {
+                resolve: (msg) => {
+                    clearTimeout(timeout);
+                    resolve(msg);
+                },
+                reject: (err) => {
+                    clearTimeout(timeout);
+                    reject(err);
+                },
+            });
+        });
+    }
+    cleanup() {
+        this.rl?.close();
+        this.rl = null;
+        this.proc = null;
+        // Reject all pending promises so callers unblock immediately
+        const abortError = new Error("REPL shut down");
+        for (const [, entry] of this.pending) {
+            entry.reject(abortError);
+        }
+        this.pending.clear();
+    }
+}
+//# sourceMappingURL=repl.js.map

package/dist/core/rlm.d.ts

@@ -0,0 +1,63 @@
+/**
+ * RLM Loop — implements Algorithm 1 from "Recursive Language Models" (arXiv:2512.24601).
+ * Extended for swarm-code with thread handler wiring.
+ *
+ * The loop works as follows:
+ *   1. Inject the full context into a persistent Python REPL as a variable.
+ *   2. Send the LLM metadata about the context plus the user's query.
+ *      The LLM writes Python code that can inspect/slice/query `context`,
+ *      call `llm_query()` recursively, call `thread()` to spawn agents,
+ *      and call FINAL() when done.
+ *   3. Execute the code, capture stdout.
+ *   4. If FINAL is set, return it. Otherwise loop.
+ */
+import { type Api, type Model } from "@mariozechner/pi-ai";
+import type { MergeHandler, PythonRepl, ThreadHandler } from "./repl.js";
+export interface RlmOptions {
+    context: string;
+    query: string;
+    model: Model<Api>;
+    repl: PythonRepl;
+    signal?: AbortSignal;
+    onProgress?: (info: RlmProgress) => void;
+    onSubQueryStart?: (info: SubQueryStartInfo) => void;
+    onSubQuery?: (info: SubQueryInfo) => void;
+    /** Custom system prompt (used for swarm mode) */
+    systemPrompt?: string;
+    /** Thread handler for swarm mode */
+    threadHandler?: ThreadHandler;
+    /** Merge handler for swarm mode */
+    mergeHandler?: MergeHandler;
+}
+export interface RlmProgress {
+    iteration: number;
+    maxIterations: number;
+    subQueries: number;
+    phase: "generating_code" | "executing" | "checking_final";
+    code?: string;
+    stdout?: string;
+    stderr?: string;
+    userMessage?: string;
+    rawResponse?: string;
+    systemPrompt?: string;
+}
+export interface SubQueryStartInfo {
+    index: number;
+    contextLength: number;
+    instruction: string;
+}
+export interface SubQueryInfo {
+    index: number;
+    contextLength: number;
+    instruction: string;
+    resultLength: number;
+    resultPreview: string;
+    elapsedMs: number;
+}
+export interface RlmResult {
+    answer: string;
+    iterations: number;
+    totalSubQueries: number;
+    completed: boolean;
+}
+export declare function runRlmLoop(options: RlmOptions): Promise<RlmResult>;