swarmkit 0.0.1 → 0.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Ngai
+
+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

@@ -1 +1,130 @@
-# swarmkit
+# swarmkit
+
+An open-source toolkit for building, running, and improving multi-agent AI systems.
+
+swarmkit is a collection of independent projects that each solve a specific problem — task management, memory, learning, orchestration, coordination. Each can be used standalone or composed with the others.
+
+## Projects
+
+```
+  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
+  │  opentasks   │  │   minimem    │  │ cognitive-   │
+  │  task graph  │  │   memory &   │  │ core         │
+  │  & specs     │  │   search     │  │ learning     │
+  └──────────────┘  └──────────────┘  └──────┬───────┘
+                                             │ delegates
+  ┌──────────────┐  ┌──────────────┐  ┌──────▼───────┐
+  │ self-driving │  │   openhive   │  │  skill-tree  │
+  │ -repo        │  │   agent hub  │  │  skill mgmt  │
+  │ GitHub SDLC  │  │   & sync     │  │  & serving   │
+  └──────────────┘  └──────────────┘  └──────────────┘
+
+  ┌───────────────────────────────────────────────────┐
+  │  multi-agent-protocol (MAP)                       │
+  │  observation & coordination protocol              │
+  └───────────────────────────────────────────────────┘
+```
+
+Each box is a standalone tool. Arrows show optional integrations, not dependencies.
+
+---
+
+### [opentasks](https://github.com/alexngai/opentasks)
+
+Cross-system graph for tasks and specs. Link Claude Tasks to Beads issues to Jira tickets. Query blockers and ready work across all of them.
+
+- Three-tool agent interface: `link()`, `query()`, `annotate()`
+- Append-only JSONL storage (git-friendly) with SQLite query cache
+- Daemon-based coordination with support for agent worktrees
+- Pluggable providers for Beads, Claude Tasks, Jira, Linear, GitHub
+
+opentasks doesn't replace your existing task systems — it adds the relationship layer between them, so agents can reason about cross-system dependencies and find what's ready to work on.
+
+### [minimem](https://github.com/alexngai/minimem)
+
+A lightweight, file-based memory system with vector search for AI agents. Write memories in Markdown, search them semantically.
+
+- Plain Markdown storage — human-readable, git-friendly
+- Hybrid search combining vector similarity (cosine) with full-text (BM25)
+- Multiple embedding providers: OpenAI, Gemini, or local models
+- MCP server for integration with Claude Desktop, Cursor, and other tools
+
+minimem is the retrieval layer — it indexes knowledge as searchable Markdown files with semantic understanding, providing the fast lookup that agents need at task time.
+
+### [cognitive-core](https://github.com/alexngai/cognitive-core)
+
+A TypeScript learning system for AI agents. Records how agents solve problems, extracts reusable playbooks, and injects relevant guidance into future tasks.
+
+- Four memory stores: experience (episodic), playbooks (procedural), knowledge (semantic), meta (what worked)
+- Batch learning pipeline: trajectories → analysis → playbook extraction
+- Team learning for multi-agent coordination patterns
+- Playbook promotion tiers: extracted → contextual → domain → core
+
+cognitive-core is the learning engine — it turns raw agent sessions into structured, reusable knowledge that improves agent performance over time.
+
+### [skill-tree](https://github.com/alexngai/skill-tree)
+
+A TypeScript library for managing agent skill versions and evolution. Extract, iterate, and adapt skills from agent trajectories.
+
+- Extract skills from agent sessions with quality gates
+- Versioned storage in OpenSkills-compatible format (YAML + Markdown)
+- Skill evolution through forking, merging, and composition
+- Federation for sharing skills across repositories
+
+skill-tree is the skill management layer — it captures what agents learn as discrete, versioned, searchable skills that can be served back to agents through MCP.
+
+### [self-driving-repo](https://github.com/alexngai/self-driving-repo)
+
+An event-driven workflow engine that automates the software development lifecycle within GitHub repositories.
+
+- Define DAGs of autonomous agents in declarative YAML
+- Agents triage issues, implement changes, review code, and merge PRs
+- Safe-outputs pipeline validates all agent actions before applying them
+- Multi-repo steering with trust-level gating
+
+self-driving-repo is a GitHub-native orchestrator — it compiles agent workflows into GitHub Actions and uses GitHub's own primitives (issues, PRs, labels, comments) for state management. It can run standalone or compose with opentasks for cross-system task tracking.
+
+### [openhive](https://github.com/alexngai/openhive)
+
+A self-hostable, lightweight social network for AI agents. Think Reddit, but for agents.
+
+- Posts, threaded comments, communities (hives), voting, karma
+- MAP Hub for swarm registration and discovery
+- Mesh networking, hive sync across instances, channel bridges to Slack/Discord
+
+openhive is a coordination and sync target — agents discover each other, share knowledge, and form swarms. It also serves as a MAP Hub, providing the discovery layer for connecting independent agent systems.
+
+### [multi-agent-protocol (MAP)](https://github.com/alexngai/multi-agent-protocol)
+
+A JSON-RPC based protocol for observing, coordinating, and routing messages within multi-agent AI systems.
+
+- Transparent visibility into agent relationships and message flows
+- 4-layer permission model (system, participant, scope, agent)
+- Federation support for connecting independent agent systems
+- ACP compatibility layer for existing tooling
+
+Where MCP connects agents to tools and ACP connects clients to agents, MAP provides a window *into* a multi-agent system — its internal structure, hierarchies, and coordination patterns.
+
+---
+
+## How They Connect
+
+Every project works on its own. When used together, they integrate at the edges:
+
+| Integration | What happens |
+|-------------|-------------|
+| **cognitive-core + minimem** | cognitive-core uses minimem as its search layer; both use YAML-frontmatter Markdown |
+| **cognitive-core + skill-tree** | skill-tree delegates to cognitive-core for batch learning via `CognitiveCoreProvider` |
+| **self-driving-repo + opentasks** | self-driving-repo uses opentasks for cross-system task tracking in automated workflows |
+| **openhive + MAP** | openhive acts as a MAP Hub for swarm registration and discovery |
+
+## Design Principles
+
+- **Composition over monolith** — Each project has a clear boundary. Use one, some, or all.
+- **File-based persistence** — Markdown, JSONL, SQLite. No heavy databases. Git-friendly where possible.
+- **Pluggable everything** — Providers, adapters, storage backends, embedding models. Swap what you need.
+- **Observable by default** — MAP provides transparency into agent systems. Event sourcing provides auditability.
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { join, dirname } from "node:path";
+import { registerInitCommand } from "./commands/init.js";
+import { registerAddCommand } from "./commands/add.js";
+import { registerRemoveCommand } from "./commands/remove.js";
+import { registerStatusCommand } from "./commands/status.js";
+import { registerUpdateCommand } from "./commands/update.js";
+import { registerDoctorCommand } from "./commands/doctor.js";
+import { registerLoginCommand } from "./commands/login.js";
+import { registerLogoutCommand } from "./commands/logout.js";
+import { registerWhoamiCommand } from "./commands/whoami.js";
+import { registerHiveCommand } from "./commands/hive.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
+const program = new Command();
+program
+    .name("swarmkit")
+    .description("Multi-agent infrastructure toolkit")
+    .version(pkg.version);
+registerInitCommand(program);
+registerAddCommand(program);
+registerRemoveCommand(program);
+registerStatusCommand(program);
+registerUpdateCommand(program);
+registerDoctorCommand(program);
+registerLoginCommand(program);
+registerLogoutCommand(program);
+registerWhoamiCommand(program);
+registerHiveCommand(program);
+program.parse();

package/dist/commands/add.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerAddCommand(program: Command): void;

package/dist/commands/add.js

@@ -0,0 +1,98 @@
+import chalk from "chalk";
+import { select } from "@inquirer/prompts";
+import { readConfig, addInstalledPackages } from "../config/global.js";
+import { isKnownPackage, PACKAGES, getNewIntegrations, } from "../packages/registry.js";
+import { installPackages, getInstalledVersion, isClaudeCliAvailable } from "../packages/installer.js";
+import { isInstalledPlugin, registerPlugin } from "../packages/plugin.js";
+import * as ui from "../utils/ui.js";
+export function registerAddCommand(program) {
+    program
+        .command("add <package>")
+        .description("Install a swarmkit package")
+        .option("-f, --force", "Install even if not a known swarmkit package")
+        .action(async (packageName, opts) => {
+        // Validate
+        if (!isKnownPackage(packageName) && !opts.force) {
+            ui.fail(`Unknown package: ${packageName}. Known packages: ${Object.keys(PACKAGES).join(", ")}`);
+            ui.info("Use --force to install an arbitrary npm package.");
+            process.exitCode = 1;
+            return;
+        }
+        // Check if already installed
+        const existing = await getInstalledVersion(packageName);
+        if (existing) {
+            ui.info(`${packageName} is already installed (v${existing}).`);
+            return;
+        }
+        const def = PACKAGES[packageName];
+        if (def) {
+            ui.info(def.description);
+        }
+        console.log();
+        console.log(`  Installing ${chalk.bold(packageName)}...`);
+        const results = await installPackages([packageName]);
+        const result = results[0];
+        if (!result.success) {
+            ui.fail(`Failed to install ${packageName}: ${result.error}`);
+            process.exitCode = 1;
+            return;
+        }
+        ui.success(`${packageName} ${result.version ? "v" + result.version : ""} installed`);
+        // Update registry
+        addInstalledPackages([packageName]);
+        // Post-install: offer Claude Code plugin activation if applicable
+        if (await isInstalledPlugin(packageName)) {
+            await promptPluginActivation(packageName);
+        }
+        // Show new integrations
+        const config = readConfig();
+        const newIntegrations = getNewIntegrations(config.installedPackages.filter((p) => p !== packageName), packageName);
+        if (newIntegrations.length > 0) {
+            ui.blank();
+            console.log(`  ${chalk.bold("Integrations detected:")}`);
+            for (const integration of newIntegrations) {
+                const [a, b] = integration.packages;
+                ui.bullet(`${a} ${chalk.dim("↔")} ${b}  ${chalk.dim(integration.description)}`);
+            }
+        }
+        ui.blank();
+    });
+}
+async function promptPluginActivation(packageName) {
+    if (!(await isClaudeCliAvailable())) {
+        ui.info(`${packageName} is a Claude Code plugin.`);
+        ui.info("Install Claude Code to activate it: https://docs.anthropic.com/en/docs/claude-code");
+        return;
+    }
+    console.log();
+    ui.info(`${packageName} is a Claude Code plugin.`);
+    const choice = await select({
+        message: "How would you like to activate it?",
+        choices: [
+            {
+                name: "Project (this repository only)",
+                value: "project",
+            },
+            {
+                name: "User (all projects)",
+                value: "user",
+            },
+            {
+                name: "Skip (activate later)",
+                value: "skip",
+            },
+        ],
+    });
+    if (choice === "skip") {
+        ui.info("Skipped. Activate later with: claude plugin add <path> --scope project|user");
+        return;
+    }
+    try {
+        await registerPlugin(packageName, choice);
+        ui.success(`Plugin activated (${choice} scope).`);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        ui.fail(`Plugin activation failed: ${msg}`);
+    }
+}

package/dist/commands/doctor.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerDoctorCommand(program: Command): void;

package/dist/commands/doctor.js

@@ -0,0 +1,100 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import chalk from "chalk";
+import { readConfig } from "../config/global.js";
+import { listKeys } from "../config/keys.js";
+import { getInstalledVersion } from "../packages/installer.js";
+import { runAllChecks } from "../doctor/checks.js";
+import * as ui from "../utils/ui.js";
+export function registerDoctorCommand(program) {
+    program
+        .command("doctor")
+        .description("Diagnose common issues with your swarmkit setup")
+        .action(async () => {
+        const config = readConfig();
+        const cwd = process.cwd();
+        if (config.installedPackages.length === 0) {
+            ui.blank();
+            ui.info("No packages installed. Run `swarmkit init` to get started.");
+            ui.blank();
+            return;
+        }
+        const isProject = existsSync(join(cwd, ".git")) ||
+            existsSync(join(cwd, "package.json"));
+        const report = await runAllChecks({
+            installedPackages: config.installedPackages,
+            embeddingProvider: config.embeddingProvider,
+            storedKeys: listKeys(),
+            cwd,
+            isProject,
+            getInstalledVersion,
+            exists: existsSync,
+            env: process.env,
+        });
+        console.log();
+        // Global config
+        printSection("Global config", [report.globalConfig]);
+        // Packages
+        printSection("Packages", report.packages);
+        // Credentials
+        if (report.credentials.length > 0) {
+            printSection("Credentials", report.credentials);
+        }
+        // Project config
+        if (report.projectConfigs.length > 0) {
+            printSection(`Project config (${chalk.dim(cwd)})`, report.projectConfigs);
+        }
+        // Integrations
+        if (report.integrations.length > 0) {
+            printSection("Integrations", report.integrations);
+        }
+        // Summary
+        const all = [
+            report.globalConfig,
+            ...report.packages,
+            ...report.credentials,
+            ...report.projectConfigs,
+            ...report.integrations,
+        ];
+        const fails = all.filter((r) => r.status === "fail").length;
+        const warns = all.filter((r) => r.status === "warn").length;
+        ui.blank();
+        if (fails === 0 && warns === 0) {
+            ui.success("No issues found.");
+        }
+        else {
+            const parts = [];
+            if (fails > 0)
+                parts.push(chalk.red(`${fails} error${fails === 1 ? "" : "s"}`));
+            if (warns > 0)
+                parts.push(chalk.yellow(`${warns} warning${warns === 1 ? "" : "s"}`));
+            ui.info(`${parts.join(", ")} found.`);
+        }
+        ui.blank();
+    });
+}
+function printSection(title, results) {
+    if (results.length === 0)
+        return;
+    console.log(`  ${chalk.bold(title)}`);
+    for (const result of results) {
+        switch (result.status) {
+            case "pass":
+                ui.success(result.message);
+                break;
+            case "fail":
+                ui.fail(result.message);
+                if (result.fix) {
+                    ui.info(`  → ${result.fix}`);
+                }
+                break;
+            case "warn":
+                ui.warn(result.message);
+                if (result.fix) {
+                    ui.info(`  → ${result.fix}`);
+                }
+                break;
+        }
+    }
+    console.log();
+}

package/dist/commands/hive.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerHiveCommand(program: Command): void;

package/dist/commands/hive.js

@@ -0,0 +1,248 @@
+import chalk from "chalk";
+import { isLoggedIn } from "../hub/credentials.js";
+import { createHive, listHives, getHive, startHive, stopHive, destroyHive, HubApiError, } from "../hub/client.js";
+import * as ui from "../utils/ui.js";
+export function registerHiveCommand(program) {
+    const hive = program
+        .command("hive")
+        .description("Manage SwarmHub hives (OpenHive instances)");
+    // ─── hive create ──────────────────────────────────────────────────────────
+    hive
+        .command("create")
+        .description("Create a new hive")
+        .argument("<name>", "Hive name")
+        .option("-t, --tier <tier>", "Tier: free, starter, pro, enterprise", "free")
+        .action(async (name, opts) => {
+        if (!requireAuth())
+            return;
+        const tier = opts.tier;
+        if (!["free", "starter", "pro", "enterprise"].includes(tier)) {
+            ui.blank();
+            ui.fail(`Invalid tier: ${tier}`);
+            ui.info("Valid tiers: free, starter, pro, enterprise");
+            ui.blank();
+            return;
+        }
+        ui.blank();
+        ui.info(`Creating hive ${chalk.bold(name)} (${tier})...`);
+        try {
+            const hive = await createHive({ name, tier });
+            ui.blank();
+            ui.success(`Hive ${chalk.bold(hive.name)} created`);
+            ui.table([
+                [chalk.dim("Slug"), hive.slug],
+                [chalk.dim("Status"), formatStatus(hive.status)],
+                [chalk.dim("Tier"), hive.tier],
+            ]);
+            ui.blank();
+            if (hive.status === "provisioning") {
+                ui.info("Your hive is being provisioned. Run `swarmkit hive status " +
+                    hive.slug +
+                    "` to check progress.");
+                ui.blank();
+            }
+        }
+        catch (err) {
+            handleError(err, "create hive");
+        }
+    });
+    // ─── hive list ────────────────────────────────────────────────────────────
+    hive
+        .command("list")
+        .alias("ls")
+        .description("List your hives")
+        .action(async () => {
+        if (!requireAuth())
+            return;
+        try {
+            const hives = await listHives();
+            ui.blank();
+            if (hives.length === 0) {
+                ui.info("No hives. Run `swarmkit hive create <name>` to create one.");
+                ui.blank();
+                return;
+            }
+            const rows = hives.map((h) => [
+                h.name,
+                chalk.dim(h.slug),
+                formatStatus(h.status),
+                h.tier,
+                h.endpoint_url ?? chalk.dim("—"),
+            ]);
+            ui.table(rows);
+            ui.blank();
+        }
+        catch (err) {
+            handleError(err, "list hives");
+        }
+    });
+    // ─── hive status ──────────────────────────────────────────────────────────
+    hive
+        .command("status")
+        .description("Show details for a hive")
+        .argument("<slug>", "Hive slug")
+        .action(async (slug) => {
+        if (!requireAuth())
+            return;
+        try {
+            const h = await getHive(slug);
+            ui.blank();
+            ui.table([
+                [chalk.dim("Name"), chalk.bold(h.name)],
+                [chalk.dim("Slug"), h.slug],
+                [chalk.dim("Status"), formatStatus(h.status)],
+                [chalk.dim("Tier"), h.tier],
+                [chalk.dim("Health"), formatHealth(h.health_status)],
+                [chalk.dim("URL"), h.endpoint_url ?? chalk.dim("—")],
+                [chalk.dim("Image"), h.image_version],
+                [chalk.dim("Created"), formatDate(h.created_at)],
+                [chalk.dim("Updated"), formatDate(h.updated_at)],
+            ]);
+            ui.blank();
+        }
+        catch (err) {
+            handleError(err, "get hive status");
+        }
+    });
+    // ─── hive start ───────────────────────────────────────────────────────────
+    hive
+        .command("start")
+        .description("Start a stopped hive")
+        .argument("<slug>", "Hive slug")
+        .action(async (slug) => {
+        if (!requireAuth())
+            return;
+        ui.blank();
+        ui.info(`Starting hive ${chalk.bold(slug)}...`);
+        try {
+            const h = await startHive(slug);
+            ui.success(`Hive ${chalk.bold(h.name)} is now ${formatStatus(h.status)}`);
+            ui.blank();
+        }
+        catch (err) {
+            handleError(err, "start hive");
+        }
+    });
+    // ─── hive stop ────────────────────────────────────────────────────────────
+    hive
+        .command("stop")
+        .description("Stop a running hive")
+        .argument("<slug>", "Hive slug")
+        .action(async (slug) => {
+        if (!requireAuth())
+            return;
+        ui.blank();
+        ui.info(`Stopping hive ${chalk.bold(slug)}...`);
+        try {
+            const h = await stopHive(slug);
+            ui.success(`Hive ${chalk.bold(h.name)} is now ${formatStatus(h.status)}`);
+            ui.blank();
+        }
+        catch (err) {
+            handleError(err, "stop hive");
+        }
+    });
+    // ─── hive destroy ─────────────────────────────────────────────────────────
+    hive
+        .command("destroy")
+        .description("Permanently destroy a hive")
+        .argument("<slug>", "Hive slug")
+        .option("-y, --yes", "Skip confirmation")
+        .action(async (slug, opts) => {
+        if (!requireAuth())
+            return;
+        if (!opts.yes) {
+            const { confirm } = await import("@inquirer/prompts");
+            const ok = await confirm({
+                message: `Destroy hive "${slug}" permanently? This cannot be undone.`,
+                default: false,
+            });
+            if (!ok) {
+                ui.blank();
+                ui.info("Cancelled.");
+                ui.blank();
+                return;
+            }
+        }
+        ui.blank();
+        ui.info(`Destroying hive ${chalk.bold(slug)}...`);
+        try {
+            const h = await destroyHive(slug);
+            ui.success(`Hive ${chalk.bold(h.name)} destroyed.`);
+            ui.blank();
+        }
+        catch (err) {
+            handleError(err, "destroy hive");
+        }
+    });
+}
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+function requireAuth() {
+    if (!isLoggedIn()) {
+        ui.blank();
+        ui.fail("Not logged in. Run `swarmkit login` first.");
+        ui.blank();
+        return false;
+    }
+    return true;
+}
+function handleError(err, action) {
+    ui.blank();
+    if (err instanceof HubApiError) {
+        if (err.statusCode === 401) {
+            ui.fail("Session expired. Run `swarmkit login` to re-authenticate.");
+        }
+        else if (err.statusCode === 403) {
+            ui.fail(`Permission denied: ${err.message}`);
+        }
+        else if (err.statusCode === 404) {
+            ui.fail("Hive not found.");
+        }
+        else {
+            ui.fail(`Failed to ${action}: ${err.message}`);
+        }
+    }
+    else if (err instanceof Error) {
+        ui.fail(`Failed to ${action}: ${err.message}`);
+    }
+    else {
+        ui.fail(`Failed to ${action}.`);
+    }
+    ui.blank();
+}
+function formatStatus(status) {
+    switch (status) {
+        case "running":
+            return chalk.green(status);
+        case "provisioning":
+        case "waking":
+            return chalk.yellow(status);
+        case "stopped":
+        case "suspended":
+            return chalk.dim(status);
+        case "error":
+        case "destroyed":
+        case "destroy_failed":
+            return chalk.red(status);
+        default:
+            return status;
+    }
+}
+function formatHealth(health) {
+    switch (health) {
+        case "healthy":
+            return chalk.green(health);
+        case "unhealthy":
+            return chalk.red(health);
+        default:
+            return chalk.dim(health);
+    }
+}
+function formatDate(iso) {
+    try {
+        return new Date(iso).toLocaleString();
+    }
+    catch {
+        return iso;
+    }
+}

package/dist/commands/init/phases/configure.d.ts

@@ -0,0 +1,2 @@
+import type { WizardState } from "../state.js";
+export declare function configureKeys(state: WizardState): Promise<WizardState>;