macro-agent 0.1.0 → 0.1.2

package/references/openteams/src/services/template-service.test.ts

@@ -0,0 +1,306 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import type Database from "better-sqlite3";
+import { createInMemoryDatabase } from "../db/database";
+import { TemplateService } from "./template-service";
+import { CommunicationService } from "./communication-service";
+import { TeamService } from "./team-service";
+import type { TeamManifest } from "../template/types";
+
+describe("TemplateService", () => {
+  let db: Database.Database;
+  let templateService: TemplateService;
+  let commService: CommunicationService;
+  let teamService: TeamService;
+
+  const selfDrivingManifest: TeamManifest = {
+    name: "self-driving",
+    description: "Autonomous codebase development",
+    version: 1,
+    roles: ["planner", "grinder", "judge"],
+    topology: {
+      root: { role: "planner", config: { model: "sonnet" } },
+      companions: [{ role: "judge", config: { model: "haiku" } }],
+      spawn_rules: {
+        planner: ["grinder", "planner"],
+        judge: [],
+        grinder: [],
+      },
+    },
+    communication: {
+      channels: {
+        task_updates: {
+          description: "Task events",
+          signals: ["TASK_CREATED", "TASK_COMPLETED", "TASK_FAILED"],
+        },
+        work_coordination: {
+          signals: ["WORK_ASSIGNED", "WORKER_DONE"],
+        },
+      },
+      subscriptions: {
+        planner: [
+          { channel: "task_updates" },
+          { channel: "work_coordination", signals: ["WORKER_DONE"] },
+        ],
+        judge: [{ channel: "task_updates", signals: ["TASK_FAILED"] }],
+        grinder: [
+          { channel: "work_coordination", signals: ["WORK_ASSIGNED"] },
+        ],
+      },
+      emissions: {
+        planner: ["TASK_CREATED", "WORK_ASSIGNED"],
+        grinder: ["WORKER_DONE"],
+      },
+      routing: {
+        peers: [
+          {
+            from: "judge",
+            to: "planner",
+            via: "direct",
+            signals: ["FIXUP_CREATED"],
+          },
+        ],
+      },
+    },
+  };
+
+  beforeEach(() => {
+    db = createInMemoryDatabase();
+    templateService = new TemplateService(db);
+    commService = new CommunicationService(db);
+    teamService = new TeamService(db);
+  });
+
+  afterEach(() => {
+    db.close();
+  });
+
+  describe("bootstrapFromManifest", () => {
+    it("creates a team with template metadata", () => {
+      const result = templateService.bootstrapFromManifest(
+        selfDrivingManifest
+      );
+
+      expect(result.team.name).toBe("self-driving");
+      expect(result.team.description).toBe(
+        "Autonomous codebase development"
+      );
+      expect(result.team.template_name).toBe("self-driving");
+      expect(result.roles).toEqual(["planner", "grinder", "judge"]);
+    });
+
+    it("auto-registers root and companion roles as members", () => {
+      const result = templateService.bootstrapFromManifest(
+        selfDrivingManifest
+      );
+
+      expect(result.members).toContain("planner");
+      expect(result.members).toContain("judge");
+      expect(result.members).toHaveLength(2); // root + 1 companion
+
+      const plannerMember = teamService.getMember("self-driving", "planner");
+      expect(plannerMember).not.toBeNull();
+      expect(plannerMember!.role).toBe("planner");
+      expect(plannerMember!.model).toBe("sonnet");
+
+      const judgeMember = teamService.getMember("self-driving", "judge");
+      expect(judgeMember).not.toBeNull();
+      expect(judgeMember!.role).toBe("judge");
+      expect(judgeMember!.model).toBe("haiku");
+    });
+
+    it("allows overriding the team name", () => {
+      const result = templateService.bootstrapFromManifest(
+        selfDrivingManifest,
+        "my-project"
+      );
+
+      expect(result.team.name).toBe("my-project");
+      expect(result.team.template_name).toBe("self-driving");
+    });
+
+    it("sets up channels", () => {
+      templateService.bootstrapFromManifest(selfDrivingManifest);
+
+      const channels = commService.listChannels("self-driving");
+      expect(channels).toHaveLength(2);
+      expect(channels.map((c) => c.name).sort()).toEqual([
+        "task_updates",
+        "work_coordination",
+      ]);
+    });
+
+    it("sets up subscriptions", () => {
+      templateService.bootstrapFromManifest(selfDrivingManifest);
+
+      const subs = commService.listSubscriptions("self-driving");
+      expect(subs.length).toBeGreaterThan(0);
+
+      const plannerSubs = commService.getSubscriptionsForRole(
+        "self-driving",
+        "planner"
+      );
+      expect(plannerSubs).toHaveLength(2);
+    });
+
+    it("sets up spawn rules", () => {
+      const result = templateService.bootstrapFromManifest(
+        selfDrivingManifest
+      );
+
+      expect(result.spawnRules).toHaveLength(3);
+
+      const plannerRule = result.spawnRules.find(
+        (r) => r.from === "planner"
+      )!;
+      expect(plannerRule.canSpawn).toEqual(["grinder", "planner"]);
+
+      // Judge and grinder can't spawn
+      expect(
+        result.spawnRules.find((r) => r.from === "judge")!.canSpawn
+      ).toEqual([]);
+    });
+
+    it("sets up peer routes", () => {
+      templateService.bootstrapFromManifest(selfDrivingManifest);
+
+      const routes = commService.listPeerRoutes("self-driving");
+      expect(routes).toHaveLength(1);
+      expect(routes[0].from_role).toBe("judge");
+      expect(routes[0].to_role).toBe("planner");
+    });
+  });
+
+  describe("canSpawn", () => {
+    it("respects spawn rules", () => {
+      templateService.bootstrapFromManifest(selfDrivingManifest);
+
+      expect(
+        templateService.canSpawn("self-driving", "planner", "grinder")
+      ).toBe(true);
+      expect(
+        templateService.canSpawn("self-driving", "planner", "planner")
+      ).toBe(true);
+      expect(
+        templateService.canSpawn("self-driving", "judge", "grinder")
+      ).toBe(false);
+      expect(
+        templateService.canSpawn("self-driving", "grinder", "grinder")
+      ).toBe(false);
+    });
+
+    it("allows all when no spawn rules exist", () => {
+      teamService.create({ name: "no-rules" });
+
+      expect(
+        templateService.canSpawn("no-rules", "anyone", "anything")
+      ).toBe(true);
+    });
+  });
+
+  describe("getSpawnRules", () => {
+    it("returns roles that a role can spawn", () => {
+      templateService.bootstrapFromManifest(selfDrivingManifest);
+
+      expect(
+        templateService.getSpawnRules("self-driving", "planner")
+      ).toEqual(["grinder", "planner"]);
+      expect(
+        templateService.getSpawnRules("self-driving", "judge")
+      ).toEqual([]);
+    });
+  });
+
+  describe("listSpawnRules", () => {
+    it("returns all spawn rules for a team", () => {
+      templateService.bootstrapFromManifest(selfDrivingManifest);
+
+      const rules = templateService.listSpawnRules("self-driving");
+      // Only planner has non-empty spawn targets stored in the DB
+      expect(rules).toHaveLength(1);
+      expect(rules[0].from).toBe("planner");
+      expect(rules[0].canSpawn).toEqual(["grinder", "planner"]);
+    });
+  });
+
+  describe("getTemplateInfo", () => {
+    it("returns template info for a templated team", () => {
+      templateService.bootstrapFromManifest(selfDrivingManifest);
+
+      const info = templateService.getTemplateInfo("self-driving");
+      expect(info!.templateName).toBe("self-driving");
+    });
+
+    it("returns null template info for non-templated team", () => {
+      teamService.create({ name: "manual" });
+
+      const info = templateService.getTemplateInfo("manual");
+      expect(info!.templateName).toBeNull();
+    });
+
+    it("returns null for nonexistent team", () => {
+      expect(templateService.getTemplateInfo("nope")).toBeNull();
+    });
+  });
+
+  describe("structured team template (backward compat)", () => {
+    it("bootstraps a traditional coordinator/worker structure", () => {
+      const structured: TeamManifest = {
+        name: "structured",
+        description: "Traditional structured development",
+        version: 1,
+        roles: ["coordinator", "integrator", "worker", "monitor"],
+        topology: {
+          root: { role: "coordinator" },
+          spawn_rules: {
+            coordinator: ["worker", "integrator", "monitor"],
+            integrator: ["worker"],
+            worker: [],
+            monitor: [],
+          },
+        },
+        communication: {
+          channels: {
+            work: {
+              signals: [
+                "WORK_ASSIGNED",
+                "WORKER_DONE",
+                "MERGE_REQUEST",
+                "MERGE_COMPLETE",
+              ],
+            },
+          },
+          subscriptions: {
+            coordinator: [{ channel: "work" }],
+            integrator: [
+              {
+                channel: "work",
+                signals: ["MERGE_REQUEST", "WORKER_DONE"],
+              },
+            ],
+            worker: [
+              { channel: "work", signals: ["WORK_ASSIGNED"] },
+            ],
+          },
+        },
+      };
+
+      const result = templateService.bootstrapFromManifest(structured);
+      expect(result.team.name).toBe("structured");
+      expect(result.roles).toHaveLength(4);
+
+      expect(
+        templateService.canSpawn("structured", "coordinator", "worker")
+      ).toBe(true);
+      expect(
+        templateService.canSpawn("structured", "worker", "worker")
+      ).toBe(false);
+
+      const coordinatorSubs = commService.getSubscriptionsForRole(
+        "structured",
+        "coordinator"
+      );
+      expect(coordinatorSubs).toHaveLength(1);
+      expect(coordinatorSubs[0].signal).toBeNull(); // all signals
+    });
+  });
+});

package/references/openteams/src/services/template-service.ts

@@ -0,0 +1,182 @@
+import type Database from "better-sqlite3";
+import type { Team } from "../types";
+import type { ResolvedTemplate, TeamManifest } from "../template/types";
+import { TemplateLoader } from "../template/loader";
+import { TeamService } from "./team-service";
+import { CommunicationService } from "./communication-service";
+
+export interface BootstrapResult {
+  team: Team;
+  roles: string[];
+  members: string[];
+  channels: string[];
+  spawnRules: Array<{ from: string; canSpawn: string[] }>;
+}
+
+export class TemplateService {
+  private teamService: TeamService;
+  private commService: CommunicationService;
+
+  constructor(private db: Database.Database) {
+    this.teamService = new TeamService(db);
+    this.commService = new CommunicationService(db);
+  }
+
+  /**
+   * Load a template from a directory and create a team from it.
+   * This is the primary entry point: load template → create team → wire communication → store spawn rules.
+   */
+  bootstrap(templateDir: string, teamNameOverride?: string): BootstrapResult {
+    const template = TemplateLoader.load(templateDir);
+    return this.bootstrapFromTemplate(template, teamNameOverride);
+  }
+
+  /**
+   * Bootstrap from an already-resolved template (for programmatic/test use).
+   */
+  bootstrapFromTemplate(
+    template: ResolvedTemplate,
+    teamNameOverride?: string
+  ): BootstrapResult {
+    const teamName = teamNameOverride ?? template.manifest.name;
+
+    // Create the team
+    const team = this.teamService.create({
+      name: teamName,
+      description: template.manifest.description,
+      templateName: template.manifest.name,
+      templatePath: template.sourcePath || undefined,
+    });
+
+    // Apply communication topology
+    if (template.manifest.communication) {
+      this.commService.applyConfig(teamName, template.manifest.communication);
+    }
+
+    // Register topology roles as initial members
+    const rootRole = template.manifest.topology.root.role;
+    const rootConfig = template.manifest.topology.root.config;
+    this.teamService.addMember(teamName, rootRole, {
+      role: rootRole,
+      agentType: "general-purpose",
+      model: rootConfig?.model as string | undefined,
+    });
+
+    if (template.manifest.topology.companions) {
+      for (const comp of template.manifest.topology.companions) {
+        this.teamService.addMember(teamName, comp.role, {
+          role: comp.role,
+          agentType: "general-purpose",
+          model: comp.config?.model as string | undefined,
+        });
+      }
+    }
+
+    // Store spawn rules
+    const spawnRules: Array<{ from: string; canSpawn: string[] }> = [];
+    if (template.manifest.topology.spawn_rules) {
+      const insertRule = this.db.prepare(
+        "INSERT OR IGNORE INTO spawn_rules (team_name, from_role, to_role) VALUES (?, ?, ?)"
+      );
+      for (const [from, targets] of Object.entries(
+        template.manifest.topology.spawn_rules
+      )) {
+        for (const to of targets) {
+          insertRule.run(teamName, from, to);
+        }
+        spawnRules.push({ from, canSpawn: targets });
+      }
+    }
+
+    const channels = template.manifest.communication?.channels
+      ? Object.keys(template.manifest.communication.channels)
+      : [];
+
+    const members = this.teamService.listMembers(teamName).map((m) => m.agent_name);
+
+    return {
+      team,
+      roles: template.manifest.roles,
+      members,
+      channels,
+      spawnRules,
+    };
+  }
+
+  /**
+   * Bootstrap from a raw manifest object (no filesystem needed).
+   */
+  bootstrapFromManifest(
+    manifest: TeamManifest,
+    teamNameOverride?: string
+  ): BootstrapResult {
+    const template = TemplateLoader.loadFromManifest(manifest);
+    return this.bootstrapFromTemplate(template, teamNameOverride);
+  }
+
+  /**
+   * Get the template info for a team.
+   */
+  getTemplateInfo(
+    teamName: string
+  ): { templateName: string | null; templatePath: string | null } | null {
+    const team = this.teamService.get(teamName);
+    if (!team) return null;
+    return {
+      templateName: team.template_name,
+      templatePath: team.template_path,
+    };
+  }
+
+  /**
+   * Check if a role can spawn another role within a team.
+   */
+  canSpawn(teamName: string, fromRole: string, toRole: string): boolean {
+    // If no spawn rules exist for this team, allow all (permissive)
+    const anyRules = this.db
+      .prepare(
+        "SELECT COUNT(*) as count FROM spawn_rules WHERE team_name = ?"
+      )
+      .get(teamName) as { count: number };
+
+    if (anyRules.count === 0) return true;
+
+    const row = this.db
+      .prepare(
+        "SELECT COUNT(*) as count FROM spawn_rules WHERE team_name = ? AND from_role = ? AND to_role = ?"
+      )
+      .get(teamName, fromRole, toRole) as { count: number };
+
+    return row.count > 0;
+  }
+
+  /**
+   * Get spawn rules for a role.
+   */
+  getSpawnRules(teamName: string, fromRole: string): string[] {
+    const rows = this.db
+      .prepare(
+        "SELECT to_role FROM spawn_rules WHERE team_name = ? AND from_role = ?"
+      )
+      .all(teamName, fromRole) as Array<{ to_role: string }>;
+    return rows.map((r) => r.to_role);
+  }
+
+  /**
+   * List all spawn rules for a team.
+   */
+  listSpawnRules(
+    teamName: string
+  ): Array<{ from: string; canSpawn: string[] }> {
+    const rows = this.db
+      .prepare(
+        "SELECT DISTINCT from_role FROM spawn_rules WHERE team_name = ? ORDER BY from_role"
+      )
+      .all(teamName) as Array<{ from_role: string }>;
+
+    return rows.map((r) => ({
+      from: r.from_role,
+      canSpawn: this.getSpawnRules(teamName, r.from_role),
+    }));
+  }
+}

package/references/openteams/src/spawner/acp-factory.ts

@@ -0,0 +1,96 @@
+import type {
+  AgentSpawner,
+  AgentInstance,
+  AgentUpdate,
+  SpawnAgentOptions,
+} from "../types";
+
+export class ACPFactorySpawner implements AgentSpawner {
+  private agents: Map<string, AgentInstance> = new Map();
+  private AgentFactoryModule: any = null;
+
+  private async loadFactory(): Promise<any> {
+    if (!this.AgentFactoryModule) {
+      try {
+        const mod = await import("acp-factory");
+        this.AgentFactoryModule = mod.AgentFactory ?? mod.default?.AgentFactory ?? mod;
+      } catch {
+        throw new Error(
+          "acp-factory is not installed. Install it with: npm install acp-factory"
+        );
+      }
+    }
+    return this.AgentFactoryModule;
+  }
+
+  async spawn(options: SpawnAgentOptions): Promise<AgentInstance> {
+    const Factory = await this.loadFactory();
+
+    const agentProvider = options.model ?? "claude-code";
+    const handle = await Factory.spawn(agentProvider, {
+      permissionMode: options.permissionMode ?? "auto-approve",
+      agentType: options.agentType,
+      env: options.env,
+    });
+
+    const session = await handle.createSession(options.cwd ?? process.cwd());
+
+    const id = `acp-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    let running = true;
+
+    const instance: AgentInstance = {
+      id,
+      name: options.name,
+
+      isRunning(): boolean {
+        return running;
+      },
+
+      async *sendPrompt(prompt: string): AsyncIterable<AgentUpdate> {
+        try {
+          running = true;
+          for await (const update of session.prompt(prompt)) {
+            if (
+              update.sessionUpdate === "agent_message_chunk" &&
+              update.content?.type === "text"
+            ) {
+              yield { type: "text", content: update.content.text };
+            } else if (update.sessionUpdate === "tool_call") {
+              yield {
+                type: "tool_call",
+                content: update.toolName ?? "unknown tool",
+              };
+            } else if (update.sessionUpdate === "agent_thought_chunk") {
+              yield { type: "thought", content: update.content?.text ?? "" };
+            }
+          }
+          yield { type: "done", content: "" };
+        } catch (err: any) {
+          yield { type: "error", content: err.message ?? String(err) };
+        } finally {
+          running = false;
+        }
+      },
+
+      async shutdown(): Promise<void> {
+        running = false;
+        await handle.close();
+      },
+    };
+
+    this.agents.set(id, instance);
+    return instance;
+  }
+
+  async shutdown(agentId: string): Promise<void> {
+    const agent = this.agents.get(agentId);
+    if (agent) {
+      await agent.shutdown();
+      this.agents.delete(agentId);
+    }
+  }
+
+  list(): AgentInstance[] {
+    return Array.from(this.agents.values());
+  }
+}

package/references/openteams/src/spawner/interface.ts

@@ -0,0 +1,31 @@
+import type { AgentSpawner } from "../types";
+
+let currentSpawner: AgentSpawner | null = null;
+
+/**
+ * @deprecated Use dependency injection instead. Pass spawner instances directly
+ * to services/commands that need them (e.g. `new AgentService(db, spawner)`).
+ */
+export function setSpawner(spawner: AgentSpawner): void {
+  currentSpawner = spawner;
+}
+
+/**
+ * @deprecated Use dependency injection instead. Pass spawner instances directly
+ * to services/commands that need them (e.g. `new AgentService(db, spawner)`).
+ */
+export function getSpawner(): AgentSpawner {
+  if (!currentSpawner) {
+    throw new Error(
+      "No agent spawner configured. Call setSpawner() or use dependency injection instead."
+    );
+  }
+  return currentSpawner;
+}
+
+/**
+ * @deprecated Use dependency injection instead.
+ */
+export function hasSpawner(): boolean {
+  return currentSpawner !== null;
+}

package/references/openteams/src/spawner/mock.test.ts

@@ -0,0 +1,93 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { MockSpawner } from "./mock";
+
+describe("MockSpawner", () => {
+  let spawner: MockSpawner;
+
+  beforeEach(() => {
+    spawner = new MockSpawner();
+  });
+
+  it("spawns a mock agent", async () => {
+    const instance = await spawner.spawn({
+      name: "test-agent",
+      teamName: "test-team",
+      prompt: "Do testing",
+    });
+
+    expect(instance.id).toMatch(/^mock-/);
+    expect(instance.name).toBe("test-agent");
+    expect(instance.isRunning()).toBe(true);
+  });
+
+  it("records spawn calls", async () => {
+    await spawner.spawn({
+      name: "a",
+      teamName: "team",
+      prompt: "Prompt A",
+    });
+    await spawner.spawn({
+      name: "b",
+      teamName: "team",
+      prompt: "Prompt B",
+    });
+
+    expect(spawner.spawnCalls).toHaveLength(2);
+    expect(spawner.spawnCalls[0].name).toBe("a");
+    expect(spawner.spawnCalls[1].name).toBe("b");
+  });
+
+  it("sends mock prompt responses", async () => {
+    const instance = await spawner.spawn({
+      name: "test",
+      teamName: "team",
+      prompt: "Init",
+    });
+
+    const updates = [];
+    for await (const update of instance.sendPrompt("Hello")) {
+      updates.push(update);
+    }
+
+    expect(updates).toHaveLength(2);
+    expect(updates[0].type).toBe("text");
+    expect(updates[0].content).toContain("Hello");
+    expect(updates[1].type).toBe("done");
+  });
+
+  it("shuts down an agent", async () => {
+    const instance = await spawner.spawn({
+      name: "test",
+      teamName: "team",
+      prompt: "Init",
+    });
+
+    await spawner.shutdown(instance.id);
+    expect(instance.isRunning()).toBe(false);
+    expect(spawner.shutdownCalls).toEqual([instance.id]);
+  });
+
+  it("lists active agents", async () => {
+    await spawner.spawn({ name: "a", teamName: "t", prompt: "P" });
+    await spawner.spawn({ name: "b", teamName: "t", prompt: "P" });
+
+    expect(spawner.list()).toHaveLength(2);
+  });
+
+  it("removes agent from list on shutdown", async () => {
+    const a = await spawner.spawn({ name: "a", teamName: "t", prompt: "P" });
+    await spawner.spawn({ name: "b", teamName: "t", prompt: "P" });
+
+    await spawner.shutdown(a.id);
+    expect(spawner.list()).toHaveLength(1);
+  });
+
+  it("resets all state", async () => {
+    await spawner.spawn({ name: "a", teamName: "t", prompt: "P" });
+    spawner.reset();
+
+    expect(spawner.list()).toHaveLength(0);
+    expect(spawner.spawnCalls).toHaveLength(0);
+    expect(spawner.shutdownCalls).toHaveLength(0);
+  });
+});