macro-agent 0.1.0 → 0.1.2

package/references/openteams/src/cli/template.ts

@@ -0,0 +1,207 @@
+import { Command } from "commander";
+import { TemplateService } from "../services/template-service";
+import { CommunicationService } from "../services/communication-service";
+import { TemplateLoader } from "../template/loader";
+import type Database from "better-sqlite3";
+
+export function createTemplateCommands(db: Database.Database): Command {
+  const templateService = new TemplateService(db);
+  const commService = new CommunicationService(db);
+  const template = new Command("template").description(
+    "Load and manage team templates"
+  );
+
+  template
+    .command("load <dir>")
+    .description("Load a team template from a directory and create a team")
+    .option("-n, --name <name>", "Override the team name from the manifest")
+    .action((dir: string, opts) => {
+      try {
+        const result = templateService.bootstrap(dir, opts.name);
+        console.log(`Team "${result.team.name}" created from template.`);
+        console.log(`  Roles: ${result.roles.join(", ")}`);
+        if (result.channels.length > 0) {
+          console.log(`  Channels: ${result.channels.join(", ")}`);
+        }
+        if (result.spawnRules.length > 0) {
+          console.log("  Spawn rules:");
+          for (const rule of result.spawnRules) {
+            console.log(
+              `    ${rule.from} -> [${rule.canSpawn.join(", ")}]`
+            );
+          }
+        }
+      } catch (err: any) {
+        console.error(`Error: ${err.message}`);
+        process.exitCode = 1;
+      }
+    });
+
+  template
+    .command("validate <dir>")
+    .description("Validate a team template directory without creating a team")
+    .action((dir: string) => {
+      try {
+        const resolved = TemplateLoader.load(dir);
+        console.log(`Template "${resolved.manifest.name}" is valid.`);
+        console.log(`  Version: ${resolved.manifest.version}`);
+        console.log(`  Roles: ${resolved.manifest.roles.join(", ")}`);
+        console.log(`  Root: ${resolved.manifest.topology.root.role}`);
+        if (resolved.manifest.topology.companions) {
+          const companions = resolved.manifest.topology.companions.map(
+            (c) => c.role
+          );
+          console.log(`  Companions: ${companions.join(", ")}`);
+        }
+        if (resolved.prompts.size > 0) {
+          console.log(
+            `  Prompts loaded: ${Array.from(resolved.prompts.keys()).join(", ")}`
+          );
+        }
+        if (resolved.manifest.communication?.channels) {
+          console.log(
+            `  Channels: ${Object.keys(resolved.manifest.communication.channels).join(", ")}`
+          );
+        }
+      } catch (err: any) {
+        console.error(`Invalid template: ${err.message}`);
+        process.exitCode = 1;
+      }
+    });
+
+  template
+    .command("info <team>")
+    .description("Show template information for a team")
+    .action((teamName: string) => {
+      const info = templateService.getTemplateInfo(teamName);
+      if (!info) {
+        console.error(`Error: Team "${teamName}" not found.`);
+        process.exitCode = 1;
+        return;
+      }
+      if (!info.templateName) {
+        console.log(`Team "${teamName}" was not created from a template.`);
+        return;
+      }
+      console.log(`Template: ${info.templateName}`);
+      if (info.templatePath) {
+        console.log(`Source: ${info.templatePath}`);
+      }
+
+      // Show communication topology
+      const channels = commService.listChannels(teamName);
+      if (channels.length > 0) {
+        console.log("\nChannels:");
+        for (const ch of channels) {
+          const desc = ch.description ? ` - ${ch.description}` : "";
+          console.log(`  ${ch.name}${desc}`);
+          console.log(`    Signals: ${ch.signals.join(", ")}`);
+        }
+      }
+
+      const subs = commService.listSubscriptions(teamName);
+      if (subs.length > 0) {
+        console.log("\nSubscriptions:");
+        // Group by role
+        const grouped: Record<string, string[]> = {};
+        for (const sub of subs) {
+          if (!grouped[sub.role]) grouped[sub.role] = [];
+          const label = sub.signal
+            ? `${sub.channel}:${sub.signal}`
+            : `${sub.channel}:*`;
+          grouped[sub.role].push(label);
+        }
+        for (const [role, channels] of Object.entries(grouped)) {
+          console.log(`  ${role}: ${channels.join(", ")}`);
+        }
+      }
+
+      const routes = commService.listPeerRoutes(teamName);
+      if (routes.length > 0) {
+        console.log("\nPeer Routes:");
+        for (const route of routes) {
+          const signals =
+            route.signals.length > 0
+              ? ` [${route.signals.join(", ")}]`
+              : "";
+          console.log(
+            `  ${route.from_role} -> ${route.to_role} via ${route.via}${signals}`
+          );
+        }
+      }
+
+      const spawnRules = templateService.listSpawnRules(teamName);
+      if (spawnRules.length > 0) {
+        console.log("\nSpawn Rules:");
+        for (const rule of spawnRules) {
+          console.log(
+            `  ${rule.from} -> [${rule.canSpawn.join(", ")}]`
+          );
+        }
+      }
+    });
+
+  template
+    .command("emit <team>")
+    .description("Emit a signal on a channel")
+    .requiredOption("-c, --channel <channel>", "Channel name")
+    .requiredOption("-s, --signal <signal>", "Signal name")
+    .requiredOption("--sender <sender>", "Sender agent/role name")
+    .option("-p, --payload <json>", "JSON payload")
+    .action((teamName: string, opts) => {
+      try {
+        const { event, permitted, enforcement } = commService.emit({
+          teamName,
+          channel: opts.channel,
+          signal: opts.signal,
+          sender: opts.sender,
+          payload: opts.payload ? JSON.parse(opts.payload) : undefined,
+        });
+        let msg = `Signal ${event.signal} emitted on ${event.channel} by ${event.sender} (event #${event.id}).`;
+        if (!permitted && enforcement === "audit") {
+          msg += ` [AUDIT: "${opts.sender}" is not permitted to emit "${opts.signal}"]`;
+        }
+        console.log(msg);
+      } catch (err: any) {
+        console.error(`Error: ${err.message}`);
+        process.exitCode = 1;
+      }
+    });
+
+  template
+    .command("events <team>")
+    .description("List signal events for a team")
+    .option("-c, --channel <channel>", "Filter by channel")
+    .option("-s, --signal <signal>", "Filter by signal")
+    .option("--sender <sender>", "Filter by sender")
+    .option("--role <role>", "Show events visible to a specific role")
+    .action((teamName: string, opts) => {
+      let events;
+      if (opts.role) {
+        events = commService.getEventsForRole(teamName, opts.role);
+      } else {
+        events = commService.listEvents(teamName, {
+          channel: opts.channel,
+          signal: opts.signal,
+          sender: opts.sender,
+        });
+      }
+
+      if (events.length === 0) {
+        console.log("No signal events found.");
+        return;
+      }
+
+      for (const e of events) {
+        const payload =
+          e.payload && Object.keys(e.payload).length > 0
+            ? ` ${JSON.stringify(e.payload)}`
+            : "";
+        console.log(
+          `  #${e.id} [${e.channel}] ${e.signal} from ${e.sender}${payload}`
+        );
+      }
+    });
+
+  return template;
+}

package/references/openteams/src/cli.ts

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+
+import { Command } from "commander";
+import { createDatabase } from "./db/database";
+import { createTeamCommands } from "./cli/team";
+import { createTaskCommands } from "./cli/task";
+import { createMessageCommands } from "./cli/message";
+import { createAgentCommands } from "./cli/agent";
+import { createTemplateCommands } from "./cli/template";
+import { createGenerateCommands } from "./cli/generate";
+import { MockSpawner } from "./spawner/mock";
+import type { AgentSpawner } from "./types";
+
+function loadSpawner(): AgentSpawner {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { ACPFactorySpawner } = require("./spawner/acp-factory");
+    return new ACPFactorySpawner();
+  } catch {
+    // Fall back to mock spawner if acp-factory is not available
+    return new MockSpawner();
+  }
+}
+
+const db = createDatabase();
+const spawner = loadSpawner();
+
+const program = new Command();
+
+program
+  .name("openteams")
+  .description("Multi-agent team coordination CLI")
+  .version("0.1.0");
+
+program.addCommand(createTeamCommands(db));
+program.addCommand(createTaskCommands(db));
+program.addCommand(createMessageCommands(db));
+program.addCommand(createAgentCommands(db, spawner));
+program.addCommand(createTemplateCommands(db));
+program.addCommand(createGenerateCommands());
+
+program.parseAsync(process.argv).catch((err) => {
+  console.error(err.message);
+  process.exit(1);
+});

package/references/openteams/src/db/database.test.ts

@@ -0,0 +1,185 @@
+import { describe, it, expect } from "vitest";
+import Database from "better-sqlite3";
+import {
+  createInMemoryDatabase,
+  getSchemaVersion,
+  applyMigrations,
+  CURRENT_VERSION,
+} from "./database";
+import type { Migration } from "./database";
+
+describe("database", () => {
+  it("creates an in-memory database with all tables", () => {
+    const db = createInMemoryDatabase();
+
+    const tables = db
+      .prepare(
+        "SELECT name FROM sqlite_master WHERE type='table' ORDER BY name"
+      )
+      .all() as Array<{ name: string }>;
+
+    const tableNames = tables.map((t) => t.name);
+    expect(tableNames).toContain("teams");
+    expect(tableNames).toContain("members");
+    expect(tableNames).toContain("tasks");
+    expect(tableNames).toContain("task_deps");
+    expect(tableNames).toContain("messages");
+    expect(tableNames).toContain("schema_version");
+    expect(tableNames).toContain("channels");
+    expect(tableNames).toContain("channel_signals");
+    expect(tableNames).toContain("subscriptions");
+    expect(tableNames).toContain("emissions");
+    expect(tableNames).toContain("peer_routes");
+    expect(tableNames).toContain("signal_events");
+    expect(tableNames).toContain("spawn_rules");
+
+    db.close();
+  });
+
+  it("stores schema version", () => {
+    const db = createInMemoryDatabase();
+
+    const row = db
+      .prepare("SELECT version FROM schema_version LIMIT 1")
+      .get() as { version: number };
+
+    expect(row.version).toBe(CURRENT_VERSION);
+    db.close();
+  });
+
+  it("enables WAL mode and foreign keys", () => {
+    const db = createInMemoryDatabase();
+
+    const wal = db.pragma("journal_mode") as Array<{ journal_mode: string }>;
+    // In-memory databases may use 'memory' instead of 'wal'
+    expect(["wal", "memory"]).toContain(wal[0].journal_mode);
+
+    const fk = db.pragma("foreign_keys") as Array<{ foreign_keys: number }>;
+    expect(fk[0].foreign_keys).toBe(1);
+
+    db.close();
+  });
+
+  it("is idempotent - can be called multiple times on same db", () => {
+    const db = createInMemoryDatabase();
+
+    // Calling schema creation again should not fail
+    db.exec(
+      "CREATE TABLE IF NOT EXISTS teams (name TEXT PRIMARY KEY, description TEXT, agent_type TEXT, created_at TEXT, status TEXT)"
+    );
+
+    db.close();
+  });
+});
+
+describe("migrations", () => {
+  it("getSchemaVersion returns 0 for empty schema_version table", () => {
+    const db = new Database(":memory:");
+    db.exec("CREATE TABLE schema_version (version INTEGER PRIMARY KEY)");
+
+    expect(getSchemaVersion(db)).toBe(0);
+    db.close();
+  });
+
+  it("getSchemaVersion returns stored version", () => {
+    const db = createInMemoryDatabase();
+    expect(getSchemaVersion(db)).toBe(CURRENT_VERSION);
+    db.close();
+  });
+
+  it("applyMigrations runs pending migrations in order", () => {
+    const db = createInMemoryDatabase();
+
+    // Simulate a v2 database that needs v3 and v4
+    const migrations: Migration[] = [
+      { version: 3, up: "ALTER TABLE teams ADD COLUMN extra1 TEXT;" },
+      { version: 4, up: "ALTER TABLE teams ADD COLUMN extra2 TEXT;" },
+    ];
+
+    const result = applyMigrations(db, 2, migrations);
+    expect(result).toBe(4);
+
+    // Verify version was updated
+    expect(getSchemaVersion(db)).toBe(4);
+
+    // Verify columns were added
+    const info = db.prepare("PRAGMA table_info(teams)").all() as Array<{
+      name: string;
+    }>;
+    const colNames = info.map((c) => c.name);
+    expect(colNames).toContain("extra1");
+    expect(colNames).toContain("extra2");
+
+    db.close();
+  });
+
+  it("applyMigrations skips already-applied versions", () => {
+    const db = createInMemoryDatabase();
+
+    const migrations: Migration[] = [
+      { version: 1, up: "SELECT 1;" }, // already past this
+      { version: 2, up: "SELECT 1;" }, // already at this
+      { version: 3, up: "ALTER TABLE teams ADD COLUMN new_col TEXT;" },
+    ];
+
+    const result = applyMigrations(db, 2, migrations);
+    expect(result).toBe(3);
+
+    // Only the v3 migration should have run
+    const info = db.prepare("PRAGMA table_info(teams)").all() as Array<{
+      name: string;
+    }>;
+    const colNames = info.map((c) => c.name);
+    expect(colNames).toContain("new_col");
+
+    db.close();
+  });
+
+  it("applyMigrations returns current version when nothing to apply", () => {
+    const db = createInMemoryDatabase();
+
+    const result = applyMigrations(db, CURRENT_VERSION, []);
+    expect(result).toBe(CURRENT_VERSION);
+
+    db.close();
+  });
+
+  it("applyMigrations rolls back on failure", () => {
+    const db = createInMemoryDatabase();
+
+    const migrations: Migration[] = [
+      { version: 3, up: "ALTER TABLE teams ADD COLUMN good_col TEXT;" },
+      { version: 4, up: "ALTER TABLE nonexistent_table ADD COLUMN bad TEXT;" },
+    ];
+
+    expect(() => applyMigrations(db, 2, migrations)).toThrow();
+
+    // Version should still be 2 — transaction rolled back
+    expect(getSchemaVersion(db)).toBe(CURRENT_VERSION);
+
+    // The v3 column should NOT exist — entire transaction rolled back
+    const info = db.prepare("PRAGMA table_info(teams)").all() as Array<{
+      name: string;
+    }>;
+    const colNames = info.map((c) => c.name);
+    expect(colNames).not.toContain("good_col");
+
+    db.close();
+  });
+
+  it("applies migrations in version order regardless of array order", () => {
+    const db = createInMemoryDatabase();
+
+    // Provide migrations out of order
+    const migrations: Migration[] = [
+      { version: 4, up: "ALTER TABLE teams ADD COLUMN col_b TEXT;" },
+      { version: 3, up: "ALTER TABLE teams ADD COLUMN col_a TEXT;" },
+    ];
+
+    const result = applyMigrations(db, 2, migrations);
+    expect(result).toBe(4);
+    expect(getSchemaVersion(db)).toBe(4);
+
+    db.close();
+  });
+});

package/references/openteams/src/db/database.ts

@@ -0,0 +1,240 @@
+import Database from "better-sqlite3";
+import path from "path";
+import os from "os";
+import fs from "fs";
+
+// ---------------------------------------------------------------------------
+// Migration framework
+// ---------------------------------------------------------------------------
+// SCHEMA_SQL is the full current schema for fresh installs.
+// MIGRATIONS handles upgrades for existing databases.
+//
+// When adding a new schema change:
+//   1. Update SCHEMA_SQL to include the change (for fresh installs)
+//   2. Add a Migration entry with the next version number (for existing installs)
+//   3. Bump CURRENT_VERSION to match
+// ---------------------------------------------------------------------------
+
+export interface Migration {
+  version: number;
+  up: string;
+}
+
+export const CURRENT_VERSION = 2;
+
+/**
+ * Migrations applied incrementally to existing databases.
+ * Each migration brings the schema from (version - 1) to version.
+ * For now this is empty because v2 is the baseline — no users have
+ * older databases. Future changes add entries here.
+ */
+export const MIGRATIONS: Migration[] = [
+  // Example for a future change:
+  // {
+  //   version: 3,
+  //   up: `ALTER TABLE teams ADD COLUMN some_new_col TEXT;`
+  // },
+];
+
+const SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS schema_version (
+  version INTEGER PRIMARY KEY
+);
+
+CREATE TABLE IF NOT EXISTS teams (
+  name          TEXT PRIMARY KEY,
+  description   TEXT,
+  agent_type    TEXT,
+  template_name TEXT,
+  template_path TEXT,
+  enforcement   TEXT DEFAULT 'permissive' CHECK (enforcement IN ('strict', 'permissive', 'audit')),
+  created_at    TEXT DEFAULT (datetime('now')),
+  status        TEXT DEFAULT 'active' CHECK (status IN ('active', 'deleted'))
+);
+
+CREATE TABLE IF NOT EXISTS members (
+  id           INTEGER PRIMARY KEY AUTOINCREMENT,
+  team_name    TEXT NOT NULL REFERENCES teams(name),
+  agent_name   TEXT NOT NULL,
+  agent_id     TEXT,
+  agent_type   TEXT DEFAULT 'general-purpose',
+  role         TEXT,
+  status       TEXT DEFAULT 'idle' CHECK (status IN ('idle', 'running', 'shutdown')),
+  spawn_prompt TEXT,
+  model        TEXT,
+  created_at   TEXT DEFAULT (datetime('now')),
+  UNIQUE(team_name, agent_name)
+);
+
+CREATE TABLE IF NOT EXISTS tasks (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  team_name   TEXT NOT NULL REFERENCES teams(name),
+  subject     TEXT NOT NULL,
+  description TEXT NOT NULL,
+  active_form TEXT,
+  status      TEXT DEFAULT 'pending' CHECK (status IN ('pending', 'in_progress', 'completed', 'deleted')),
+  owner       TEXT,
+  metadata    TEXT DEFAULT '{}',
+  created_at  TEXT DEFAULT (datetime('now')),
+  updated_at  TEXT DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS task_deps (
+  task_id     INTEGER NOT NULL REFERENCES tasks(id),
+  blocked_by  INTEGER NOT NULL REFERENCES tasks(id),
+  PRIMARY KEY (task_id, blocked_by)
+);
+
+CREATE TABLE IF NOT EXISTS messages (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  team_name   TEXT NOT NULL REFERENCES teams(name),
+  type        TEXT NOT NULL CHECK (type IN ('message', 'broadcast', 'shutdown_request', 'shutdown_response', 'plan_approval_response')),
+  sender      TEXT NOT NULL,
+  recipient   TEXT,
+  content     TEXT NOT NULL,
+  summary     TEXT,
+  request_id  TEXT,
+  approve     INTEGER,
+  delivered   INTEGER DEFAULT 0,
+  created_at  TEXT DEFAULT (datetime('now'))
+);
+
+-- Communication: channel definitions per team
+CREATE TABLE IF NOT EXISTS channels (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  team_name   TEXT NOT NULL REFERENCES teams(name),
+  name        TEXT NOT NULL,
+  description TEXT,
+  UNIQUE(team_name, name)
+);
+
+-- Signals belonging to a channel
+CREATE TABLE IF NOT EXISTS channel_signals (
+  channel_id  INTEGER NOT NULL REFERENCES channels(id),
+  signal      TEXT NOT NULL,
+  PRIMARY KEY (channel_id, signal)
+);
+
+-- Role subscriptions to channels (with optional signal filter)
+CREATE TABLE IF NOT EXISTS subscriptions (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  team_name   TEXT NOT NULL REFERENCES teams(name),
+  role        TEXT NOT NULL,
+  channel     TEXT NOT NULL,
+  signal      TEXT,
+  UNIQUE(team_name, role, channel, signal)
+);
+
+-- Emission permissions per role
+CREATE TABLE IF NOT EXISTS emissions (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  team_name   TEXT NOT NULL REFERENCES teams(name),
+  role        TEXT NOT NULL,
+  signal      TEXT NOT NULL,
+  UNIQUE(team_name, role, signal)
+);
+
+-- Peer routing rules
+CREATE TABLE IF NOT EXISTS peer_routes (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  team_name   TEXT NOT NULL REFERENCES teams(name),
+  from_role   TEXT NOT NULL,
+  to_role     TEXT NOT NULL,
+  via         TEXT NOT NULL DEFAULT 'direct' CHECK (via IN ('direct', 'topic', 'scope')),
+  signals     TEXT DEFAULT '[]'
+);
+
+-- Signal events log
+CREATE TABLE IF NOT EXISTS signal_events (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  team_name   TEXT NOT NULL REFERENCES teams(name),
+  channel     TEXT NOT NULL,
+  signal      TEXT NOT NULL,
+  sender      TEXT NOT NULL,
+  payload     TEXT DEFAULT '{}',
+  created_at  TEXT DEFAULT (datetime('now'))
+);
+
+-- Spawn rules per team
+CREATE TABLE IF NOT EXISTS spawn_rules (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  team_name   TEXT NOT NULL REFERENCES teams(name),
+  from_role   TEXT NOT NULL,
+  to_role     TEXT NOT NULL,
+  UNIQUE(team_name, from_role, to_role)
+);
+`;
+
+function getDefaultDbPath(): string {
+  const dir = path.join(os.homedir(), ".openteams");
+  fs.mkdirSync(dir, { recursive: true });
+  return path.join(dir, "openteams.db");
+}
+
+/**
+ * Read the current schema version from the database.
+ * Returns 0 if no version row exists (fresh install).
+ */
+export function getSchemaVersion(db: Database.Database): number {
+  const row = db
+    .prepare("SELECT version FROM schema_version LIMIT 1")
+    .get() as { version: number } | undefined;
+  return row?.version ?? 0;
+}
+
+/**
+ * Apply pending migrations to bring the database up to CURRENT_VERSION.
+ * Runs inside a transaction so partial migrations are rolled back.
+ */
+export function applyMigrations(
+  db: Database.Database,
+  fromVersion: number,
+  migrations: Migration[] = MIGRATIONS
+): number {
+  const pending = migrations
+    .filter((m) => m.version > fromVersion)
+    .sort((a, b) => a.version - b.version);
+
+  if (pending.length === 0) return fromVersion;
+
+  const targetVersion = pending[pending.length - 1].version;
+
+  const migrate = db.transaction(() => {
+    for (const migration of pending) {
+      db.exec(migration.up);
+    }
+    db.prepare("UPDATE schema_version SET version = ?").run(targetVersion);
+  });
+
+  migrate();
+  return targetVersion;
+}
+
+export function createDatabase(dbPath?: string): Database.Database {
+  const resolvedPath = dbPath ?? getDefaultDbPath();
+  const db = new Database(resolvedPath);
+
+  db.pragma("journal_mode = WAL");
+  db.pragma("foreign_keys = ON");
+
+  // Create all tables (IF NOT EXISTS is safe for both fresh and existing DBs)
+  db.exec(SCHEMA_SQL);
+
+  const currentVersion = getSchemaVersion(db);
+
+  if (currentVersion === 0) {
+    // Fresh install — stamp with current version
+    db.prepare("INSERT INTO schema_version (version) VALUES (?)").run(
+      CURRENT_VERSION
+    );
+  } else if (currentVersion < CURRENT_VERSION) {
+    // Existing database needs migration
+    applyMigrations(db, currentVersion);
+  }
+
+  return db;
+}
+
+export function createInMemoryDatabase(): Database.Database {
+  return createDatabase(":memory:");
+}