macro-agent 0.1.0 → 0.1.2

package/references/openteams/src/generators/skill-generator.ts

@@ -0,0 +1,374 @@
+import type { ResolvedTemplate, ResolvedRole } from "../template/types";
+
+export interface SkillGeneratorOptions {
+  /** Team name override (defaults to manifest name) */
+  teamName?: string;
+  /** Whether to include CLI usage examples */
+  includeCliExamples?: boolean;
+  /** Whether to include YAML frontmatter */
+  includeFrontmatter?: boolean;
+}
+
+export interface CatalogOptions {
+  /** Team name override (defaults to manifest name) */
+  teamName?: string;
+}
+
+/**
+ * Generates a SKILL.md from a ResolvedTemplate.
+ *
+ * The generated file encodes the team's topology, communication patterns,
+ * and role relationships as human-readable instructions. In the naive loader,
+ * this leaves all interaction enforcement to agent discretion — agents read
+ * the SKILL.md and coordinate by convention, not by runtime enforcement.
+ */
+/**
+ * Generates a lightweight catalog document for a team template.
+ *
+ * The catalog provides progressive disclosure — agents see role names
+ * and one-line descriptions without loading full role context. This
+ * keeps context budgets tight while enabling role discovery.
+ */
+export function generateCatalog(
+  template: ResolvedTemplate,
+  options: CatalogOptions = {}
+): string {
+  const teamName = options.teamName ?? template.manifest.name;
+  const m = template.manifest;
+
+  const lines: string[] = [];
+
+  lines.push(`# Team: ${teamName}`);
+  if (m.description) {
+    lines.push("");
+    lines.push(`> ${m.description}`);
+  }
+
+  lines.push("");
+  lines.push("## Roles");
+  lines.push("");
+  lines.push("| Role | Description | Position |");
+  lines.push("|------|-------------|----------|");
+
+  for (const roleName of m.roles) {
+    const role = template.roles.get(roleName);
+    const desc =
+      role?.description && role.description !== `Role: ${roleName}`
+        ? role.description
+        : "";
+
+    let position: string;
+    if (m.topology.root.role === roleName) {
+      position = "root";
+    } else if (m.topology.companions?.some((c) => c.role === roleName)) {
+      position = "companion";
+    } else {
+      position = "spawned";
+    }
+
+    lines.push(`| ${roleName} | ${desc} | ${position} |`);
+  }
+
+  lines.push("");
+  lines.push("## Loading a role");
+  lines.push("");
+  lines.push("To get full context for a role, read the role's SKILL.md:");
+  for (const roleName of m.roles) {
+    lines.push(`- \`roles/${roleName}/SKILL.md\``);
+  }
+  lines.push("");
+  lines.push(
+    `Or via CLI: \`openteams generate role-package <template-dir> --role <role-name>\``
+  );
+
+  return lines.join("\n") + "\n";
+}
+
+export function generateSkillMd(
+  template: ResolvedTemplate,
+  options: SkillGeneratorOptions = {}
+): string {
+  const teamName = options.teamName ?? template.manifest.name;
+  const includeCliExamples = options.includeCliExamples ?? true;
+  const includeFrontmatter = options.includeFrontmatter ?? false;
+  const m = template.manifest;
+
+  const sections: string[] = [];
+
+  // YAML frontmatter
+  if (includeFrontmatter) {
+    sections.push(generateFrontmatter(template, teamName));
+  }
+
+  // Header
+  sections.push(`# Team: ${teamName}`);
+  if (m.description) {
+    sections.push(`\n> ${m.description}`);
+  }
+
+  // Team structure
+  sections.push(generateStructureSection(template));
+
+  // Roles
+  sections.push(generateRolesSection(template));
+
+  // Communication
+  if (m.communication) {
+    sections.push(generateCommunicationSection(template));
+  }
+
+  // Spawn rules
+  if (m.topology.spawn_rules) {
+    sections.push(generateSpawnRulesSection(template));
+  }
+
+  // Interaction guidelines
+  sections.push(generateGuidelinesSection(teamName, template, includeCliExamples));
+
+  return sections.join("\n\n") + "\n";
+}
+
+function generateStructureSection(template: ResolvedTemplate): string {
+  const m = template.manifest;
+  const lines: string[] = ["## Team Structure"];
+
+  const rootRole = m.topology.root.role;
+  const rootConfig = m.topology.root.config;
+  const modelTag = rootConfig?.model ? ` (model: ${rootConfig.model})` : "";
+  lines.push(`- **Root**: ${rootRole}${modelTag}`);
+
+  if (m.topology.companions && m.topology.companions.length > 0) {
+    const companions = m.topology.companions.map((c) => {
+      const tag = c.config?.model ? ` (model: ${c.config.model})` : "";
+      return `${c.role}${tag}`;
+    });
+    lines.push(`- **Companions**: ${companions.join(", ")}`);
+  }
+
+  lines.push(`- **Roles**: ${m.roles.join(", ")}`);
+
+  return lines.join("\n");
+}
+
+function generateRolesSection(template: ResolvedTemplate): string {
+  const lines: string[] = ["## Roles"];
+
+  for (const roleName of template.manifest.roles) {
+    const role = template.roles.get(roleName);
+    lines.push("");
+    lines.push(`### ${roleName}`);
+
+    if (role) {
+      if (role.description && role.description !== `Role: ${roleName}`) {
+        lines.push(`${role.description}`);
+      }
+      if (role.extends) {
+        lines.push(`- **Extends**: ${role.extends}`);
+      }
+      if (role.capabilities.length > 0) {
+        lines.push(`- **Capabilities**: ${role.capabilities.join(", ")}`);
+      }
+    }
+
+    // Prompt summary
+    const rolePrompts = template.prompts.get(roleName);
+    if (rolePrompts) {
+      // Include a truncated first line as a hint
+      const firstLine = rolePrompts.primary.split("\n").find((l) => l.trim().length > 0);
+      if (firstLine) {
+        const preview =
+          firstLine.length > 100
+            ? firstLine.slice(0, 100) + "..."
+            : firstLine;
+        lines.push(`- **Prompt**: ${preview}`);
+      }
+      if (rolePrompts.additional.length > 0) {
+        const names = rolePrompts.additional.map((s) => s.name);
+        lines.push(`- **Additional**: ${names.join(", ")}`);
+      }
+    }
+  }
+
+  return lines.join("\n");
+}
+
+function generateCommunicationSection(template: ResolvedTemplate): string {
+  const comm = template.manifest.communication!;
+  const lines: string[] = ["## Communication"];
+
+  if (comm.enforcement) {
+    lines.push(`\nEnforcement: **${comm.enforcement}**`);
+  }
+
+  // Channels
+  if (comm.channels && Object.keys(comm.channels).length > 0) {
+    lines.push("");
+    lines.push("### Channels");
+    lines.push("");
+    lines.push("| Channel | Signals | Description |");
+    lines.push("|---------|---------|-------------|");
+    for (const [name, def] of Object.entries(comm.channels)) {
+      const desc = def.description ?? "";
+      lines.push(`| ${name} | ${def.signals.join(", ")} | ${desc} |`);
+    }
+  }
+
+  // Subscriptions
+  if (comm.subscriptions && Object.keys(comm.subscriptions).length > 0) {
+    lines.push("");
+    lines.push("### Subscriptions");
+    lines.push("");
+    lines.push("| Role | Channel | Signals |");
+    lines.push("|------|---------|---------|");
+    for (const [role, entries] of Object.entries(comm.subscriptions)) {
+      for (const entry of entries) {
+        const signals = entry.signals ? entry.signals.join(", ") : "all";
+        lines.push(`| ${role} | ${entry.channel} | ${signals} |`);
+      }
+    }
+  }
+
+  // Emissions
+  if (comm.emissions && Object.keys(comm.emissions).length > 0) {
+    lines.push("");
+    lines.push("### Emission Permissions");
+    lines.push("");
+    lines.push("| Role | Can Emit |");
+    lines.push("|------|----------|");
+    for (const [role, signals] of Object.entries(comm.emissions)) {
+      lines.push(`| ${role} | ${signals.join(", ")} |`);
+    }
+  }
+
+  // Routing / Peer routes
+  if (comm.routing) {
+    if (comm.routing.status) {
+      lines.push("");
+      lines.push(`### Status Routing: **${comm.routing.status}**`);
+    }
+
+    if (comm.routing.peers && comm.routing.peers.length > 0) {
+      lines.push("");
+      lines.push("### Peer Routes");
+      lines.push("");
+      lines.push("| From | To | Via | Signals |");
+      lines.push("|------|----|-----|---------|");
+      for (const peer of comm.routing.peers) {
+        const signals = peer.signals ? peer.signals.join(", ") : "all";
+        lines.push(`| ${peer.from} | ${peer.to} | ${peer.via} | ${signals} |`);
+      }
+    }
+  }
+
+  return lines.join("\n");
+}
+
+function generateSpawnRulesSection(template: ResolvedTemplate): string {
+  const rules = template.manifest.topology.spawn_rules!;
+  const lines: string[] = ["## Spawn Rules"];
+  lines.push("");
+  lines.push("| Role | Can Spawn |");
+  lines.push("|------|-----------|");
+  for (const [from, targets] of Object.entries(rules)) {
+    const targetStr = targets.length > 0 ? targets.join(", ") : "(none)";
+    lines.push(`| ${from} | ${targetStr} |`);
+  }
+  return lines.join("\n");
+}
+
+function generateGuidelinesSection(
+  teamName: string,
+  template: ResolvedTemplate,
+  includeCliExamples: boolean
+): string {
+  const m = template.manifest;
+  const lines: string[] = ["## Agent Interaction Guidelines"];
+  lines.push("");
+  lines.push(
+    `You are a member of the **${teamName}** team. Your behavior should follow the communication patterns described above.`
+  );
+
+  lines.push("");
+  lines.push("### General Principles");
+  lines.push("- Check the task board regularly for new or updated tasks");
+  lines.push("- Communicate status changes through the appropriate channels");
+  lines.push("- Respect spawn rules — only spawn roles you are permitted to");
+  lines.push(
+    "- When emitting signals, use the correct channel for the signal type"
+  );
+  lines.push("- Read messages addressed to you and respond promptly");
+
+  if (m.communication?.enforcement === "strict") {
+    lines.push("");
+    lines.push(
+      "**Enforcement: strict** — Only emit signals you are explicitly permitted to. Unauthorized emissions will be rejected."
+    );
+  } else if (m.communication?.enforcement === "audit") {
+    lines.push("");
+    lines.push(
+      "**Enforcement: audit** — Communication violations are logged but not blocked. Follow the declared patterns."
+    );
+  }
+
+  if (includeCliExamples) {
+    lines.push("");
+    lines.push("### CLI Commands");
+    lines.push("");
+    lines.push("```bash");
+    lines.push("# Check tasks");
+    lines.push(`openteams task list ${teamName}`);
+    lines.push("");
+    lines.push("# Claim a task");
+    lines.push(
+      `openteams task update ${teamName} <task-id> --owner <your-name> --status in_progress`
+    );
+    lines.push("");
+    lines.push("# Complete a task");
+    lines.push(
+      `openteams task update ${teamName} <task-id> --status completed`
+    );
+    lines.push("");
+    lines.push("# Send a message to a teammate");
+    lines.push(
+      `openteams message send ${teamName} --to <agent> --content "..." --summary "..."`
+    );
+    lines.push("");
+    lines.push("# Broadcast to all teammates");
+    lines.push(
+      `openteams message broadcast ${teamName} --content "..." --summary "..."`
+    );
+
+    if (m.communication?.channels) {
+      lines.push("");
+      lines.push("# Emit a signal on a channel");
+      lines.push(
+        `openteams template emit ${teamName} -c <channel> -s <signal> --sender <your-role>`
+      );
+      lines.push("");
+      lines.push("# Check events visible to your role");
+      lines.push(
+        `openteams template events ${teamName} --role <your-role>`
+      );
+    }
+
+    lines.push("```");
+  }
+
+  return lines.join("\n");
+}
+
+function generateFrontmatter(
+  template: ResolvedTemplate,
+  teamName: string
+): string {
+  const m = template.manifest;
+  const lines: string[] = ["---"];
+  lines.push(`name: ${teamName}`);
+  if (m.description) {
+    lines.push(`description: ${m.description}`);
+  }
+  lines.push(`roles: [${m.roles.join(", ")}]`);
+  lines.push(`root: ${m.topology.root.role}`);
+  lines.push("---");
+  return lines.join("\n");
+}

package/references/openteams/src/index.ts

@@ -0,0 +1,104 @@
+export const VERSION = "0.1.0";
+
+// Types
+export type {
+  Team,
+  CreateTeamOptions,
+  Member,
+  MemberStatus,
+  Task,
+  TaskRow,
+  TaskSummary,
+  CreateTaskOptions,
+  UpdateTaskOptions,
+  TaskStatus,
+  Message,
+  MessageRow,
+  MessageType,
+  SendMessageOptions,
+  BroadcastMessageOptions,
+  ShutdownRequestOptions,
+  ShutdownResponseOptions,
+  PlanApprovalResponseOptions,
+  AgentSpawner,
+  AgentInstance,
+  AgentUpdate,
+  SpawnAgentOptions,
+} from "./types";
+
+// Template types
+export type {
+  TeamManifest,
+  TopologyConfig,
+  TopologyNode,
+  TopologyNodeConfig,
+  CommunicationConfig,
+  ChannelDefinition,
+  SubscriptionEntry,
+  RoutingConfig,
+  PeerRoute,
+  RoleDefinition,
+  CapabilityComposition,
+  McpServerEntry,
+  LoadOptions,
+  AsyncLoadOptions,
+  PromptSection,
+  ResolvedPrompts,
+  ResolvedTemplate,
+  ResolvedRole,
+  SignalEvent,
+  EmitSignalOptions,
+} from "./template/types";
+
+// Database
+export { createDatabase, createInMemoryDatabase } from "./db/database";
+
+// Services
+export { TeamService } from "./services/team-service";
+export { TaskService } from "./services/task-service";
+export { MessageService } from "./services/message-service";
+export { AgentService } from "./services/agent-service";
+export { TemplateService } from "./services/template-service";
+export { CommunicationService } from "./services/communication-service";
+
+// Template
+export { TemplateLoader } from "./template/loader";
+
+// Generators
+export { generateSkillMd, generateCatalog } from "./generators/skill-generator";
+export type {
+  SkillGeneratorOptions,
+  CatalogOptions,
+} from "./generators/skill-generator";
+export {
+  generateAgentPrompts,
+  generateAgentPrompt,
+  generateRoleSkillMd,
+  generateAllRoleSkillMds,
+} from "./generators/agent-prompt-generator";
+export type {
+  AgentPrompt,
+  AgentPromptGeneratorOptions,
+  RoleSkillMd,
+  RoleSkillMdOptions,
+} from "./generators/agent-prompt-generator";
+export { generatePackage } from "./generators/package-generator";
+export type {
+  PackageGeneratorOptions,
+  PackageResult,
+} from "./generators/package-generator";
+
+// Spawner
+export { setSpawner, getSpawner, hasSpawner } from "./spawner/interface";
+export { MockSpawner } from "./spawner/mock";
+
+/**
+ * Create an ACPFactorySpawner instance. Requires the optional `acp-factory` package.
+ * @throws If `acp-factory` is not installed.
+ */
+export async function createACPFactorySpawner(): Promise<
+  import("./types").AgentSpawner
+> {
+  const { ACPFactorySpawner } = await import("./spawner/acp-factory");
+  return new ACPFactorySpawner();
+}

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

@@ -0,0 +1,158 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import type Database from "better-sqlite3";
+import { createInMemoryDatabase } from "../db/database";
+import { AgentService } from "./agent-service";
+import { TeamService } from "./team-service";
+import { MockSpawner } from "../spawner/mock";
+
+describe("AgentService", () => {
+  let db: Database.Database;
+  let agentService: AgentService;
+  let teamService: TeamService;
+  let spawner: MockSpawner;
+
+  beforeEach(() => {
+    db = createInMemoryDatabase();
+    spawner = new MockSpawner();
+    agentService = new AgentService(db, spawner);
+    teamService = new TeamService(db);
+    teamService.create({ name: "test-team" });
+  });
+
+  afterEach(() => {
+    db.close();
+  });
+
+  describe("spawn", () => {
+    it("spawns an agent and registers it as a member", async () => {
+      const member = await agentService.spawn({
+        name: "researcher",
+        teamName: "test-team",
+        prompt: "Research the codebase",
+        agentType: "explore",
+        model: "sonnet",
+      });
+
+      expect(member.agent_name).toBe("researcher");
+      expect(member.team_name).toBe("test-team");
+      expect(member.status).toBe("running");
+      expect(member.agent_id).toBeTruthy();
+
+      expect(spawner.spawnCalls).toHaveLength(1);
+      expect(spawner.spawnCalls[0].name).toBe("researcher");
+      expect(spawner.spawnCalls[0].prompt).toBe("Research the codebase");
+    });
+
+    it("throws when team does not exist", async () => {
+      await expect(
+        agentService.spawn({
+          name: "agent",
+          teamName: "nope",
+          prompt: "Do stuff",
+        })
+      ).rejects.toThrow('Team "nope" not found');
+    });
+
+    it("throws when agent name already exists and is active", async () => {
+      await agentService.spawn({
+        name: "worker",
+        teamName: "test-team",
+        prompt: "Work",
+      });
+
+      await expect(
+        agentService.spawn({
+          name: "worker",
+          teamName: "test-team",
+          prompt: "More work",
+        })
+      ).rejects.toThrow('Agent "worker" already exists');
+    });
+
+    it("allows re-spawning a shut down agent", async () => {
+      await agentService.spawn({
+        name: "worker",
+        teamName: "test-team",
+        prompt: "Work",
+      });
+      await agentService.shutdown("test-team", "worker");
+
+      const member = await agentService.spawn({
+        name: "worker",
+        teamName: "test-team",
+        prompt: "New work",
+      });
+      expect(member.status).toBe("running");
+    });
+  });
+
+  describe("shutdown", () => {
+    it("shuts down an agent", async () => {
+      await agentService.spawn({
+        name: "worker",
+        teamName: "test-team",
+        prompt: "Work",
+      });
+
+      await agentService.shutdown("test-team", "worker");
+
+      const member = agentService.getMember("test-team", "worker");
+      expect(member!.status).toBe("shutdown");
+    });
+
+    it("throws when agent does not exist", async () => {
+      await expect(
+        agentService.shutdown("test-team", "nope")
+      ).rejects.toThrow('Agent "nope" not found');
+    });
+  });
+
+  describe("listMembers", () => {
+    it("returns all members", async () => {
+      await agentService.spawn({
+        name: "a",
+        teamName: "test-team",
+        prompt: "Work A",
+      });
+      await agentService.spawn({
+        name: "b",
+        teamName: "test-team",
+        prompt: "Work B",
+      });
+
+      const members = agentService.listMembers("test-team");
+      expect(members).toHaveLength(2);
+    });
+  });
+
+  describe("getMember", () => {
+    it("returns a specific member", async () => {
+      await agentService.spawn({
+        name: "finder",
+        teamName: "test-team",
+        prompt: "Find things",
+      });
+
+      const member = agentService.getMember("test-team", "finder");
+      expect(member).not.toBeNull();
+      expect(member!.agent_name).toBe("finder");
+    });
+
+    it("returns null for nonexistent member", () => {
+      expect(agentService.getMember("test-team", "nope")).toBeNull();
+    });
+  });
+
+  describe("getRunningInstances", () => {
+    it("returns spawner's running instances", async () => {
+      await agentService.spawn({
+        name: "a",
+        teamName: "test-team",
+        prompt: "Work",
+      });
+
+      const instances = agentService.getRunningInstances();
+      expect(instances).toHaveLength(1);
+    });
+  });
+});