@robzilla1738/agentswarm 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robert Courson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,142 @@
+# agentswarm
+
+A local agent-swarm orchestrator with a terminal dashboard and a localhost web UI. Works with DeepSeek, OpenAI, Anthropic, xAI, MiniMax, OpenRouter, Ollama, LM Studio, or any OpenAI-compatible endpoint.
+
+You give it a mission. A conductor model breaks the mission into tasks and hands them to worker agents that run in parallel, share findings on a blackboard, and get checked by an adversarial verifier. The run ends with a synthesized report plus whatever files the agents produced. Everything runs on your machine with your own API key, or fully offline against a local model.
+
+```
+            ┌─────────────┐
+            │  Conductor  │  decomposes the mission, schedules waves,
+            └──────┬──────┘  reacts to results, steers toward the goal
+       ┌───────────┼───────────┐
+   ┌───▼───┐   ┌───▼───┐   ┌───▼───┐    parallel worker agents
+   │  T1   │   │  T2   │   │  T3   │    (shell · files · web · notes)
+   └───┬───┘   └───┬───┘   └───┬───┘
+       └─────┬─────┘           │         dependencies + shared blackboard
+        ┌────▼─────┐      ┌────▼────┐
+        │  T4 dep  │◀─────│ verify  │   adversarial verification
+        └────┬─────┘      └─────────┘
+        ┌────▼─────┐
+        │Synthesize│  → final-report.md + artifacts
+        └──────────┘
+```
+
+## What it does
+
+- Independent tasks run at the same time, up to a parallelism cap you set. Dependent tasks start the moment their inputs are ready.
+- Runs are built to go long. Each agent compacts its own context when it grows too big, and the conductor's history is bounded the same way. A run-wide token budget is enforced mid-task; when it's hit, agents wrap up and report instead of dying mid-thought. Failed verifications retry with feedback. Every event lands in an append-only journal that survives crashes.
+- Interrupted runs resume. `swarm resume <id>`, or a button in the UI, keeps completed work, re-runs whatever was in flight, and carries the token spend over.
+- Runs execute in an isolated per-run workspace on your machine by default. Nothing extra to install, no daemon to start. Want stronger isolation? Run in a Docker container or an E2B/Modal/Vercel cloud sandbox, per run (`--sandbox docker`) or as your default (`swarm config set sandboxRuntime auto` picks the strongest one you've configured). `swarm sandbox test` boots whichever is active and tells you whether it works.
+- Tasks flagged `verify` get a second agent whose whole job is to prove the first one wrong. Failures bounce back for a retry with the verifier's feedback attached.
+- You can steer a live run. `swarm note <id> "skip the pricing section"` and the conductor re-plans on its next tick.
+- Workers get real tools: shell, file read/write/patch, web search and fetch, the blackboard, and an artifacts folder that lands on your disk. Search uses [SearchKit](https://github.com/robzilla1738/script-search) if it's installed (local, returns quotable passages; agents can pass `deep=true` when they need grounded sources), TinyFish if you have a key, DuckDuckGo otherwise.
+- The web UI streams every tool call live and renders the final report. Each task gets a deterministic name and pixel avatar so you can tell agents apart at a glance.
+- Provider keys are stored per provider, so switching between DeepSeek, OpenAI, Anthropic, Grok, MiniMax, OpenRouter, Ollama, and LM Studio never loses a key. Reasoning effort maps to whatever each API actually supports.
+
+## Install
+
+Requires Node 20 or newer.
+
+```bash
+npm install -g @robzilla1738/agentswarm
+```
+
+That gives you the `swarm` command with the web UI prebuilt, nothing else to do. The E2B/Modal/Vercel SDKs install as optional dependencies; add `--omit=optional` if you'll never use a cloud sandbox.
+
+Or from source:
+
+```bash
+git clone https://github.com/robzilla1738/agentswarm.git && cd agentswarm
+npm run setup        # installs deps + builds the engine and the web UI
+npm link             # optional: puts `swarm` on your PATH
+```
+
+Without `npm link`, replace `swarm` below with `node bin/swarm.js`.
+
+## First run
+
+```bash
+swarm config set apiKey sk-...            # key for the active provider (default: DeepSeek)
+swarm config set provider ollama          # or: openai | anthropic | xai | minimax | openrouter | lmstudio | custom
+pip install searchkit                     # optional: local, citable web search for agents
+swarm serve --open                        # opens the web UI (http://localhost:7777)
+```
+
+Type a mission, hit Launch swarm, and watch it work. Or stay in the terminal:
+
+```bash
+swarm run "Research the best open-source vector DBs in 2026 and write a recommendation"
+```
+
+## CLI
+
+| Command | What it does |
+|---|---|
+| `swarm run "<mission>"` | Decompose and execute a mission (live terminal dashboard). Ctrl-C detaches; the run keeps going. |
+| `swarm serve [--port 7777] [--open]` | Start the web UI + REST API. |
+| `swarm watch <id>` | Re-attach a live dashboard to any run. |
+| `swarm resume <id>` | Resume an interrupted run. Done tasks keep their results, in-flight tasks re-run. |
+| `swarm sandbox [test\|<runtime>]` | Show the resolved shell runtime, or boot and smoke-test one (host, docker, e2b, modal, vercel). |
+| `swarm ls` | List runs (status, tasks, tokens, cost). |
+| `swarm report <id> [--open]` | Print or open a run's final report. |
+| `swarm note <id> "<text>"` | Steer a live run. The conductor reads it. |
+| `swarm cancel <id>` | Stop a run. It still synthesizes a report from completed work. |
+| `swarm config [list\|get\|set …]` | Manage `~/.agentswarm/config.json`. |
+| `swarm models` | List models from the active provider. |
+| `swarm demo` | Run a self-contained demo mission in an isolated workspace. |
+
+Run options (also on the UI launch form under Options): `--workers N` (parallelism), `--tasks N`, `--steps N` (tool steps per task), `--budget N` (token cap), `--model`, `--conductor`, `--verify off|normal|strict`, `--effort low|medium|high|max`, `--no-thinking`, `--sandbox host|docker|e2b|modal|vercel|auto` (shell runtime for this run), `--cwd <path>` (run against a real directory instead of an isolated workspace), `--fg` (foreground in this process).
+
+## How it works
+
+The conductor is a model with three tools: `spawn_tasks`, `wait`, and `finish`. It reads the mission, spawns self-contained tasks (each with an objective, success criteria, a role, optional dependencies, and an optional `verify` flag), then reacts as reports come back.
+
+Each task becomes an autonomous agent with a tool budget. It works in small steps, posts durable findings to the blackboard, saves artifacts, and ends by reporting back. The report is the only thing the conductor sees, which keeps reports specific.
+
+The scheduler starts a task as soon as its dependencies are done, up to the parallelism cap. Tasks whose dependencies failed are blocked and surfaced to the conductor for re-planning.
+
+When the conductor finishes (or the budget forces it), a synthesizer composes `final-report.md` from every task report.
+
+The journal is the source of truth. Every run is an append-only `events.jsonl`; the terminal dashboard, the web UI, and `swarm ls` all reduce the same file. That's why runs survive crashes and can be resumed or replayed. Runs live under `~/.agentswarm/runs/<id>/`.
+
+If the engine process dies without writing a terminal status (kill -9, reboot), the hub notices the missing process and shows the run as interrupted instead of leaving it "running" forever.
+
+## Architecture
+
+```
+src/                         TypeScript engine (zero runtime deps)
+  deepseek.ts   streaming chat client (OpenAI-compatible; thinking mode, tool calls, retries)
+  providers.ts  provider registry (DeepSeek/OpenAI/Anthropic/xAI/MiniMax/OpenRouter/Ollama/LM Studio)
+  sandbox.ts    sandbox runtimes: host, docker, E2B, Modal, Vercel
+  agent.ts      the agent loop: stream → tool calls → results → repeat, with compaction
+  executor.ts   the orchestrator: conductor loop, parallel scheduler, verify, synth, budget
+  tools.ts      worker toolbelt (shell, files, web, blackboard, artifacts) + safety
+  webtools.ts   web search/fetch: SearchKit → TinyFish → DuckDuckGo fallback chain
+  journal.ts    append-only crash-safe event log (single source of truth)
+  state.ts      pure reducer: events → live run state
+  hub.ts        localhost HTTP API + SSE + static UI server
+  terminal.ts   live TTY dashboard
+  cli.ts        command-line interface
+ui/             Next.js 15 + Tailwind 4 web app (static-exported, served by the hub)
+test/           end-to-end test with a scripted mock model (no API key needed)
+```
+
+## Testing
+
+```bash
+node test/e2e.js
+```
+
+Boots a mock model server and drives real missions through the engine, offline, no API key needed. The happy path covers parallel execution, dependency order, tool calls, verification, and synthesis. The rest covers what goes wrong: bad keys fail loudly instead of producing a phantom run, interrupted runs resume without losing work, a tiny token budget still ends with a report, a failed verification retries with feedback and then passes, a live run can be steered with a note and cancelled, and agents compact their context when it grows too big. There's also a hub API phase and, when a docker daemon is reachable, a full run inside a container.
+
+## Safety notes
+
+- Safe mode is on by default. It blocks obviously destructive shell commands and confines writes to the working directory. `--no-safe` turns it off for a run; only do that when you trust the mission.
+- Runs default to an isolated per-run workspace on this machine. That's a private directory, not a container. Agents still execute with your user's permissions; the engine strips API keys and sandbox credentials from their environment, and safe mode constrains commands and writes. For untrusted or risky missions, use `--sandbox docker` or a cloud runtime.
+- Use `--cwd <path>` (or Workspace → "A directory on disk" in the UI) to let agents touch a real project. Those runs always execute on the host, since touching your real files is the point.
+- Costs are estimates based on list prices and the token counts the API reports. Models without pricing data show $0. Set a `--budget` either way.
+- Keys are stored in `~/.agentswarm/config.json` (chmod 600) and are only sent to the APIs you configured.
+
+## License
+
+MIT

package/bin/swarm.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+try {
+  require("../dist/cli.js").main();
+} catch (e) {
+  if (e && e.code === "MODULE_NOT_FOUND" && /dist[\/\\]cli/.test(String(e.message))) {
+    console.error("agentswarm isn't built yet. From the repo root run:\n\n  npm run setup\n\nthen try again.");
+    process.exit(1);
+  }
+  throw e;
+}

package/dist/agent.js

@@ -0,0 +1,211 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runAgent = runAgent;
+exports.estimateMessages = estimateMessages;
+const deepseek_1 = require("./deepseek");
+const prompts_1 = require("./prompts");
+const types_1 = require("./types");
+const util_1 = require("./util");
+/**
+ * The agent loop: stream a completion, execute tool calls, feed results back,
+ * until a terminal tool is called or the step budget runs out. Context is
+ * compacted in place when it grows past the configured limit.
+ */
+async function runAgent(p) {
+    const { cfg, hooks } = p;
+    let messages = [
+        { role: "system", content: p.system },
+        { role: "user", content: p.kickoff },
+    ];
+    const terminalNames = new Set(p.terminal.map((t) => t.name));
+    const allSchemas = [
+        ...Object.values(p.tools).map((t) => t.schema),
+        ...p.terminal,
+    ];
+    let usage = { ...types_1.ZERO_USAGE };
+    let lastText = "";
+    let steps = 0;
+    hooks.onTranscript?.(messages);
+    const callModel = (opts) => (0, deepseek_1.chat)(cfg, {
+        model: p.model,
+        messages,
+        tools: opts?.only
+            ? allSchemas.filter((s) => s.name === opts.only)
+            : allSchemas,
+        toolChoice: opts?.only,
+        thinking: p.thinking,
+        reasoningEffort: p.thinking ? p.reasoningEffort : undefined,
+        maxTokens: p.maxTokensOut,
+        signal: p.signal,
+        onDelta: (d) => {
+            if (d.think)
+                hooks.onDelta?.("think", d.think);
+            if (d.text)
+                hooks.onDelta?.("text", d.text);
+        },
+    });
+    let stopReason = null;
+    while (steps < p.maxSteps) {
+        stopReason = p.stop?.() ?? null;
+        if (stopReason)
+            break;
+        steps++;
+        const res = await callModel();
+        hooks.onUsage?.(p.model, res.usage);
+        usage = (0, types_1.addUsage)(usage, res.usage);
+        if (res.toolCalls.length === 0) {
+            // The model replied with prose. Record it and nudge it back to tools.
+            messages.push({ role: "assistant", content: res.content, reasoning_content: res.reasoning });
+            if (res.content) {
+                lastText = res.content;
+                hooks.onMessage?.(res.content);
+            }
+            messages.push({ role: "user", content: prompts_1.NUDGE_USE_TOOLS });
+            hooks.onTranscript?.(messages);
+            continue;
+        }
+        messages.push({
+            role: "assistant",
+            content: res.content || null,
+            reasoning_content: res.reasoning,
+            tool_calls: res.toolCalls,
+        });
+        if (res.content) {
+            lastText = res.content;
+            hooks.onMessage?.(res.content);
+        }
+        for (const call of res.toolCalls) {
+            const name = call.function.name;
+            const parsed = (0, util_1.safeJson)(call.function.arguments);
+            const args = parsed ?? {};
+            if (terminalNames.has(name)) {
+                if (parsed === undefined && call.function.arguments.trim()) {
+                    // Unparseable terminal args — tell the model and let it retry.
+                    messages.push({
+                        role: "tool",
+                        tool_call_id: call.id,
+                        content: "ERROR: arguments were not valid JSON. Call the tool again with valid JSON.",
+                    });
+                    hooks.onTranscript?.(messages);
+                    continue;
+                }
+                hooks.onToolCall?.(call.id, name, redact(args));
+                hooks.onTranscript?.(messages);
+                return { terminal: { name, args }, finalText: lastText, steps, usage };
+            }
+            const tool = p.tools[name];
+            hooks.onToolCall?.(call.id, name, redact(args));
+            let result;
+            let ok = true;
+            if (!tool) {
+                ok = false;
+                result = `ERROR: unknown tool "${name}". Available: ${allSchemas.map((s) => s.name).join(", ")}`;
+            }
+            else if (parsed === undefined && call.function.arguments.trim()) {
+                ok = false;
+                result = "ERROR: arguments were not valid JSON.";
+            }
+            else {
+                try {
+                    result = await tool.run(args, p.ctx);
+                }
+                catch (e) {
+                    ok = false;
+                    result = `ERROR: ${(0, util_1.errMsg)(e)}`;
+                }
+            }
+            if (p.signal.aborted)
+                throw new Error("cancelled");
+            result = (0, util_1.truncateMiddle)(result, cfg.maxToolResultChars, "chars");
+            hooks.onToolResult?.(call.id, name, ok, (0, util_1.clip)(result.replace(/\s+/g, " "), 200));
+            messages.push({ role: "tool", tool_call_id: call.id, content: result });
+        }
+        hooks.onTranscript?.(messages);
+        if (estimateMessages(messages) > cfg.contextTokenLimit) {
+            messages = await compact(p, messages);
+            hooks.onTranscript?.(messages);
+            hooks.onLog?.("info", `${p.agentId}: context compacted`);
+        }
+    }
+    // Step budget exhausted (or stopped early) — force one final terminal call.
+    messages.push({ role: "user", content: stopReason ? (0, prompts_1.forcedFinal)(stopReason) : prompts_1.STEP_LIMIT_FINAL });
+    try {
+        const res = await callModel({ only: p.terminal[0].name });
+        hooks.onUsage?.(p.model, res.usage);
+        usage = (0, types_1.addUsage)(usage, res.usage);
+        const call = res.toolCalls.find((c) => terminalNames.has(c.function.name));
+        if (call) {
+            const args = (0, util_1.safeJson)(call.function.arguments) ?? {};
+            return { terminal: { name: call.function.name, args }, finalText: lastText, steps, usage };
+        }
+        if (res.content)
+            lastText = res.content;
+    }
+    catch (e) {
+        hooks.onLog?.("warn", `${p.agentId}: forced final call failed: ${(0, util_1.errMsg)(e)}`);
+    }
+    return { terminal: null, finalText: lastText, steps, usage };
+}
+function redact(args) {
+    const out = {};
+    for (const [k, v] of Object.entries(args)) {
+        out[k] = typeof v === "string" && v.length > 600 ? (0, util_1.clip)(v, 600) : v;
+    }
+    return out;
+}
+function estimateMessages(messages) {
+    let chars = 0;
+    for (const m of messages) {
+        chars += m.content?.length ?? 0;
+        chars += m.reasoning_content?.length ?? 0;
+        if (m.tool_calls) {
+            for (const c of m.tool_calls)
+                chars += c.function.arguments.length + 40;
+        }
+    }
+    return Math.ceil(chars / 3.5) + messages.length * 6;
+}
+async function compact(p, messages) {
+    const KEEP_TAIL = 8;
+    if (messages.length <= 2 + KEEP_TAIL + 2)
+        return messages;
+    let cut = messages.length - KEEP_TAIL;
+    // Never start the tail on a tool result whose assistant turn was dropped.
+    while (cut > 2 && messages[cut].role === "tool")
+        cut--;
+    if (cut <= 2)
+        return messages;
+    const middle = messages.slice(2, cut);
+    const serialized = middle
+        .map((m) => {
+        const tools = m.tool_calls?.map((c) => ` [${c.function.name}(${(0, util_1.clip)(c.function.arguments, 300)})]`).join("") ?? "";
+        const body = (0, util_1.clip)(m.content ?? "", m.role === "tool" ? 900 : 1500);
+        return `${m.role.toUpperCase()}:${tools} ${body}`;
+    })
+        .join("\n");
+    let summary;
+    try {
+        const res = await (0, deepseek_1.chat)(p.cfg, {
+            model: p.model,
+            messages: [{ role: "user", content: (0, prompts_1.compactorPrompt)((0, util_1.truncateMiddle)(serialized, 300_000, "chars")) }],
+            thinking: false,
+            maxTokens: 2048,
+            signal: p.signal,
+        });
+        p.hooks.onUsage?.(p.model, res.usage);
+        summary = res.content || "(compaction produced no summary)";
+    }
+    catch (e) {
+        // Compaction is best-effort; fall back to hard truncation.
+        summary = "(compaction failed: " + (0, util_1.errMsg)(e) + ") Earlier steps were dropped.";
+    }
+    return [
+        messages[0],
+        messages[1],
+        {
+            role: "user",
+            content: `[Context was compacted to save space. Faithful summary of your earlier work:]\n${summary}\n[Continue from here. The most recent steps follow.]`,
+        },
+        ...messages.slice(cut),
+    ];
+}