macro-agent 0.0.11 → 0.0.12

package/docs/teams.md

@@ -0,0 +1,233 @@
+# Team Templates
+
+Team templates define reusable multi-agent configurations that can be loaded and bootstrapped by the TeamRuntime. Templates live in `.macro-agent/teams/<name>/` directories.
+
+## Directory Structure
+
+```
+.macro-agent/teams/<name>/
+├── team.yaml              # Main manifest (required)
+├── roles/
+│   ├── <role>.yaml        # Custom role definitions
+│   └── ...
+└── prompts/
+    ├── <role>.md          # System prompts for each role
+    └── ...
+```
+
+## Schema Reference
+
+### team.yaml
+
+```yaml
+name: string              # Team identifier (matches directory name)
+description: string       # Human-readable description
+version: 1                # Schema version (currently 1)
+
+roles:                    # List of role names used by this team
+  - <role_name>
+
+topology:                 # Agent spawn structure
+  root:                   # Initial agent (always spawned first)
+    role: string          # Role name from roles list
+    prompt: string        # Relative path to prompt file
+    config:
+      model: string       # Model to use (sonnet, haiku, opus)
+
+  companions:             # Peer agents (spawned alongside root, not as children)
+    - role: string
+      prompt: string
+      config:
+        model: string
+
+  spawn_rules:            # Which roles can spawn which other roles
+    <role>: [<role>, ...]
+
+communication:            # Signal routing configuration
+  channels:               # Named signal groups
+    <channel_name>:
+      description: string
+      signals: [string, ...]
+
+  subscriptions:          # Which signals each role receives
+    <role>:
+      - channel: string
+        signals: [string, ...]  # Optional; omit for all signals
+
+  emissions:              # Which signals each role can emit
+    <role>: [string, ...]
+
+  routing:
+    status: upstream      # Status events flow to parent
+    peers:                # Direct peer-to-peer routes
+      - from: string
+        to: string
+        via: direct
+        signals: [string, ...]
+
+  enforcement: permissive | strict | audit
+
+macro_agent:              # Runtime behavior configuration
+  task_assignment:
+    mode: push | pull
+    pull:                 # Only for pull mode
+      idle_timeout_s: number
+      claim_retry_delay_ms: number
+      max_concurrent_per_agent: number
+
+  integration:
+    strategy: queue | trunk | optimistic
+    config:               # Strategy-specific options
+      max_retries: number       # trunk/optimistic: retry count
+      conflict_action: string   # trunk: abandon|rebase
+      require_review: boolean   # queue: gate on review
+
+  lifecycle:
+    continuations:
+      enabled: boolean
+      max_history_messages: number
+      checkpoint_interval: round_trip | none
+    scaling:
+      min_workers: number
+      max_workers: number
+      scale_on: task_queue_depth | manual
+      idle_drain: boolean
+
+  observability:
+    metrics_window_s: number
+    snapshot_interval_s: number
+```
+
+### Role Definitions (roles/*.yaml)
+
+```yaml
+name: string              # Role identifier
+extends: string           # Base role: worker, coordinator, monitor, integrator
+display_name: string      # Human-readable name
+description: string
+
+# Capability modification (pick one approach)
+capabilities: [string]          # Full replacement of base capabilities
+capabilities_add: [string]      # Add to base capabilities
+capabilities_remove: [string]   # Remove from base capabilities
+
+prompt: string            # Relative path to prompt file
+
+macro_agent:
+  workspace:
+    type: own | shared | none
+    branch_pattern: string        # Pattern with {agent-id} placeholder
+    cleanup_on_terminate: boolean
+  lifecycle:
+    type: ephemeral | persistent | daemon | event-driven
+    cascade_terminate: boolean
+    self_cleanup: boolean
+    task_bound: boolean
+    parent_bound: boolean
+    max_duration_ms: number
+```
+
+## Task Assignment Modes
+
+### Push Mode
+
+The coordinator creates tasks and explicitly assigns them to spawned agents. This is the traditional hierarchical model.
+
+- Coordinator spawns workers and assigns tasks via `assign_task`
+- Workers execute their assigned task and call `done()`
+- Workers terminate after task completion
+
+### Pull Mode
+
+Agents autonomously claim tasks from a shared pool. Best for large, parallelizable workloads.
+
+- A planner role creates and prioritizes tasks
+- Worker agents call `claim_task` to pick up work
+- After completing a task, workers claim the next available one
+- Workers that find no tasks wait with configurable idle timeout
+
+## Integration Strategies
+
+### Queue (default)
+
+Changes flow through a merge queue managed by an integrator agent. Provides the highest safety with review gates.
+
+### Trunk
+
+Workers push directly to the main branch with automatic rebase-and-retry. Fast but requires good test coverage.
+
+Configuration:
+- `max_retries`: Number of rebase attempts (default: 3)
+- `conflict_action`: What to do on persistent conflict (`abandon` or `rebase`)
+
+### Optimistic
+
+Like trunk, but emits a validation event after push for async verification. Useful when builds are slow.
+
+## Reference Templates
+
+### self-driving
+
+Autonomous development with continuous planning. Uses pull-mode task assignment and trunk integration.
+
+| Role | Base | Purpose |
+|------|------|---------|
+| planner | coordinator | Explores codebase, creates and prioritizes tasks |
+| grinder | worker | Claims and executes tasks autonomously |
+| judge | monitor | Monitors codebase health, creates fixup tasks |
+
+### structured
+
+Hierarchical development with explicit assignment. Uses push-mode task assignment and merge queue.
+
+| Role | Base | Purpose |
+|------|------|---------|
+| lead | coordinator | Decomposes work and assigns tasks to developers |
+| developer | worker | Executes assigned tasks in isolated workspaces |
+| reviewer | monitor | Reviews merge requests before they land |
+
+## Creating a Custom Team
+
+1. Create directory: `.macro-agent/teams/my-team/`
+2. Write `team.yaml` with your manifest
+3. Define custom roles in `roles/`
+4. Write system prompts in `prompts/`
+5. Load with: `TeamLoader.load("my-team")`
+
+### Example: Minimal Custom Team
+
+```yaml
+name: my-team
+description: "Simple worker team"
+version: 1
+roles: [lead, dev]
+
+topology:
+  root:
+    role: lead
+    prompt: prompts/lead.md
+  spawn_rules:
+    lead: [dev]
+    dev: []
+
+communication:
+  channels:
+    work:
+      signals: [TASK_ASSIGNED, TASK_COMPLETED]
+  subscriptions:
+    lead:
+      - channel: work
+    dev:
+      - channel: work
+        signals: [TASK_ASSIGNED]
+  emissions:
+    lead: [TASK_ASSIGNED]
+    dev: [TASK_COMPLETED]
+  enforcement: permissive
+
+macro_agent:
+  task_assignment:
+    mode: push
+  integration:
+    strategy: queue
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "macro-agent",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "description": "Interact with multiple agents as if they were a single agent.",
   "type": "module",
   "main": "dist/index.js",
@@ -39,6 +39,7 @@
     "@sudocode-ai/types": "^0.1.19",
     "@types/better-sqlite3": "^7.6.13",
     "@types/express": "^5.0.6",
+    "@types/js-yaml": "^4.0.9",
     "@types/node": "^20.10.0",
     "@types/supertest": "^6.0.3",
     "@types/ws": "^8.18.1",
@@ -54,8 +55,9 @@
     "better-sqlite3": "^12.5.0",
     "chalk": "^5.6.2",
     "commander": "^14.0.2",
-    "dataplane": "^0.1.3",
+    "git-cascade": "0.0.1",
     "express": "^5.2.1",
+    "js-yaml": "^4.1.1",
     "nanoid": "^5.0.0",
     "tinybase": "^5.0.0",
     "ulid": "^3.0.2",

package/src/acp/__tests__/integration.test.ts

@@ -290,6 +290,43 @@ describe("ACP Mode Integration", () => {
       expect(loadResponse).toEqual({});
     });
 
+    it("should load session by agentId via _meta", async () => {
+      // Create a session first
+      const newResponse = await macroAgent.newSession({
+        cwd: "/test/project",
+      });
+
+      const originalSessionId = newResponse.sessionId;
+      const originalAgentId = macroAgent.getMappedAgentId(originalSessionId);
+
+      // Create a new MacroAgent instance (simulating reconnect)
+      const newMacroAgent = new MacroAgent(mockConnection, {
+        agentManager: mockAgentManager,
+        eventStore: mockEventStore,
+        taskManager: mockTaskManager,
+        defaultCwd: "/test/integration",
+      });
+
+      // Load using _meta.agentId — the server resolves agentId to session_id
+      const loadResponse = await newMacroAgent.loadSession({
+        sessionId: "_resume_",
+        cwd: "/test/project",
+        _meta: { agentId: originalAgentId },
+      } as any);
+
+      expect(loadResponse).toEqual({});
+    });
+
+    it("should throw when _meta.agentId references non-existent agent", async () => {
+      await expect(
+        macroAgent.loadSession({
+          sessionId: "_resume_",
+          cwd: "/test/project",
+          _meta: { agentId: "non-existent-agent" },
+        } as any)
+      ).rejects.toThrow("Agent not found: non-existent-agent");
+    });
+
     it("should handle authenticate (no-op)", async () => {
       const response = await macroAgent.authenticate({
         methodId: "none",
@@ -334,7 +371,8 @@ describe("ACP Mode Integration", () => {
       expect(extensions).toContain("_macro/checkCapability");
       expect(extensions).toContain("_macro/respondToPermission");
       expect(extensions).toContain("_macro/cancelPermission");
-      expect(extensions?.length).toBe(15);
+      expect(extensions).toContain("_macro/resume");
+      expect(extensions?.length).toBe(16);
 
       expect(initResponse.agentCapabilities?._meta?.agentType).toBe(
         "macro-agent"
@@ -860,4 +898,126 @@ describe("ACP Protocol Compliance", () => {
     const extensions = initResponse.agentCapabilities?._meta?.extensions;
     expect(extensions?.every((e: string) => e.startsWith("_"))).toBe(true);
   });
+
+  // ─────────────────────────────────────────────────────────────────
+  // Agent Resume Flow Integration Tests
+  // ─────────────────────────────────────────────────────────────────
+
+  describe("Extension: _macro/resume", () => {
+    it("should resume a stopped sub-agent via head manager", async () => {
+      // 1. Create session (head manager)
+      await macroAgent.newSession({ cwd: "/test/project" });
+
+      // 2. Spawn a sub-agent
+      const spawnResponse = await macroAgent.extMethod("macro/spawnAgent", {
+        task_description: "Worker agent to be resumed",
+      });
+      const childAgentId = spawnResponse.agentId as string;
+
+      // 3. Simulate agent being stopped (update store state)
+      const childAgent = agentStore.get(childAgentId)!;
+      childAgent.state = "stopped";
+      agentStore.set(childAgentId, childAgent);
+
+      // 4. Resume via _macro/resume extension
+      const resumeResponse = await macroAgent.extMethod("_macro/resume", {
+        agentId: childAgentId,
+      });
+
+      expect(resumeResponse.success).toBe(true);
+      expect(resumeResponse.agentId).toBe(childAgentId);
+      expect(resumeResponse.sessionId).toBeDefined();
+
+      // 5. Verify agentManager.resume was called with correct ID
+      expect(mockAgentManager.resume).toHaveBeenCalledWith(childAgentId);
+    });
+
+    it("should resume a failed sub-agent", async () => {
+      await macroAgent.newSession({ cwd: "/test/project" });
+
+      const spawnResponse = await macroAgent.extMethod("macro/spawnAgent", {
+        task_description: "Agent that failed",
+      });
+      const childAgentId = spawnResponse.agentId as string;
+
+      // Simulate failed state
+      const childAgent = agentStore.get(childAgentId)!;
+      childAgent.state = "failed";
+      agentStore.set(childAgentId, childAgent);
+
+      const resumeResponse = await macroAgent.extMethod("_macro/resume", {
+        agentId: childAgentId,
+      });
+
+      expect(resumeResponse.success).toBe(true);
+      expect(mockAgentManager.resume).toHaveBeenCalledWith(childAgentId);
+    });
+
+    it("should reject resuming a running agent", async () => {
+      await macroAgent.newSession({ cwd: "/test/project" });
+
+      // Spawn returns a running agent
+      const spawnResponse = await macroAgent.extMethod("macro/spawnAgent", {
+        task_description: "Running agent",
+      });
+      const childAgentId = spawnResponse.agentId as string;
+
+      // Agent is running — resume should fail
+      await expect(
+        macroAgent.extMethod("_macro/resume", {
+          agentId: childAgentId,
+        })
+      ).rejects.toThrow("only stopped or failed");
+    });
+
+    it("should reject resuming a non-existent agent", async () => {
+      await expect(
+        macroAgent.extMethod("_macro/resume", {
+          agentId: "non-existent-agent",
+        })
+      ).rejects.toThrow("Agent not found");
+    });
+
+    it("should reject resume without agentId", async () => {
+      await expect(
+        macroAgent.extMethod("_macro/resume", {})
+      ).rejects.toThrow("agentId is required");
+    });
+
+    it("full lifecycle: spawn → stop → resume", async () => {
+      // Initialize and create session
+      await macroAgent.initialize({
+        protocolVersion: 1,
+        clientCapabilities: {},
+      });
+      await macroAgent.newSession({ cwd: "/test/project" });
+
+      // Spawn sub-agent
+      const spawnResponse = await macroAgent.extMethod("macro/spawnAgent", {
+        task_description: "Full lifecycle test agent",
+        options: { cwd: "/test/spawn" },
+      });
+      const agentId = spawnResponse.agentId as string;
+      const sessionId = spawnResponse.sessionId as string;
+
+      // Verify agent is running
+      const runningAgent = agentStore.get(agentId)!;
+      expect(runningAgent.state).toBe("running");
+      expect(runningAgent.session_id).toBe(sessionId);
+
+      // Simulate stop
+      runningAgent.state = "stopped";
+      agentStore.set(agentId, runningAgent);
+
+      // Resume
+      const resumeResponse = await macroAgent.extMethod("_macro/resume", {
+        agentId,
+      });
+
+      expect(resumeResponse.success).toBe(true);
+      expect(resumeResponse.agentId).toBe(agentId);
+      // Session ID is preserved from the mock's resume implementation
+      expect(resumeResponse.sessionId).toBe(sessionId);
+    });
+  });
 });

package/src/acp/__tests__/macro-agent.test.ts

@@ -154,6 +154,9 @@ describe("MacroAgent", () => {
       expect(response.agentCapabilities?._meta?.extensions).toContain(
         "_macro/spawnAgent"
       );
+      expect(response.agentCapabilities?._meta?.extensions).toContain(
+        "_macro/resume"
+      );
       expect(response.agentCapabilities?._meta?.agentType).toBe("macro-agent");
     });
 
@@ -870,6 +873,98 @@ describe("MacroAgent", () => {
     });
   });
 
+  // ─────────────────────────────────────────────────────────────────
+  // _macro/resume Tests
+  // ─────────────────────────────────────────────────────────────────
+
+  describe("_macro/resume", () => {
+    it("should resume a stopped agent", async () => {
+      const stoppedAgent = createMockAgent({
+        id: "agent-stopped",
+        state: "stopped",
+        session_id: "session-stopped",
+      });
+      vi.mocked(mockEventStore.getAgent).mockReturnValue(stoppedAgent);
+      vi.mocked(mockAgentManager.resume).mockResolvedValue({
+        id: "agent-stopped",
+        session_id: "session-stopped",
+        agent: stoppedAgent,
+        session: {},
+      } as any);
+
+      const result = await macroAgent.extMethod("_macro/resume", {
+        agentId: "agent-stopped",
+      });
+
+      expect(mockAgentManager.resume).toHaveBeenCalledWith("agent-stopped");
+      expect(result).toEqual({
+        success: true,
+        agentId: "agent-stopped",
+        sessionId: "session-stopped",
+      });
+    });
+
+    it("should resume a failed agent", async () => {
+      const failedAgent = createMockAgent({
+        id: "agent-failed",
+        state: "failed",
+        session_id: "session-failed",
+      });
+      vi.mocked(mockEventStore.getAgent).mockReturnValue(failedAgent);
+      vi.mocked(mockAgentManager.resume).mockResolvedValue({
+        id: "agent-failed",
+        session_id: "session-failed",
+        agent: failedAgent,
+        session: {},
+      } as any);
+
+      const result = await macroAgent.extMethod("_macro/resume", {
+        agentId: "agent-failed",
+      });
+
+      expect(mockAgentManager.resume).toHaveBeenCalledWith("agent-failed");
+      expect(result).toHaveProperty("success", true);
+    });
+
+    it("should throw for missing agentId", async () => {
+      await expect(
+        macroAgent.extMethod("_macro/resume", {})
+      ).rejects.toThrow("agentId is required");
+    });
+
+    it("should throw for non-existent agent", async () => {
+      vi.mocked(mockEventStore.getAgent).mockReturnValue(undefined as any);
+
+      await expect(
+        macroAgent.extMethod("_macro/resume", { agentId: "missing" })
+      ).rejects.toThrow("Agent not found");
+    });
+
+    it("should throw for running agent", async () => {
+      const runningAgent = createMockAgent({
+        id: "agent-running",
+        state: "running",
+      });
+      vi.mocked(mockEventStore.getAgent).mockReturnValue(runningAgent);
+
+      await expect(
+        macroAgent.extMethod("_macro/resume", { agentId: "agent-running" })
+      ).rejects.toThrow("only stopped or failed");
+    });
+
+    it("should throw for sleeping agent", async () => {
+      const sleepingAgent = createMockAgent({
+        id: "agent-sleeping",
+        state: "sleeping",
+      });
+      vi.mocked(mockEventStore.getAgent).mockReturnValue(sleepingAgent);
+
+      await expect(
+        macroAgent.extMethod("_macro/resume", { agentId: "agent-sleeping" })
+      ).rejects.toThrow("only stopped or failed");
+    });
+  });
+
   // ─────────────────────────────────────────────────────────────────
   // Cancel Tests
   // ─────────────────────────────────────────────────────────────────