macro-agent 0.0.10 → 0.0.12

package/CLAUDE.md

@@ -5,11 +5,16 @@ A multi-agent orchestration system for spawning and managing hierarchical Claude
 ## Project Overview
 
 macro-agent enables coordinated work across multiple AI agents with:
-- **Role-based agents** (Worker, Integrator, Coordinator, Monitor)
+- **Role-based agents** (Worker, Integrator, Coordinator, Monitor + custom team roles)
+- **Team templates** for declarative multi-agent topologies (YAML config)
+- **Pluggable integration strategies** (queue, trunk, optimistic)
 - **Workspace isolation** via git worktrees
 - **Merge queue** for serialized integration
-- **Task backend** abstraction (memory or sudocode)
+- **Task backend** abstraction (memory or sudocode) with push and pull modes
 - **In-flight steering** via context injection
+- **Signal filtering and emission enforcement** for communication topology
+- **Session continuations** for long-running daemon agents
+- **Observability** via throughput, utilization, and error metrics
 
 ## Architecture
 
@@ -20,10 +25,18 @@ macro-agent enables coordinated work across multiple AI agents with:
 └───────────────────────────┬─────────────────────────────────┘
                             │
 ┌───────────────────────────▼─────────────────────────────────┐
+│                     Team Runtime (optional)                   │
+│  - Loads team YAML config (topology, communication)         │
+│  - Bootstraps root + companion agents                       │
+│  - Installs spawn interceptor, signal filters, validators   │
+│  - Manages integration strategy and session continuations   │
+└───────────────────────────┬─────────────────────────────────┘
+                            │
+┌───────────────────────────▼─────────────────────────────────┐
 │                     Agent Manager                            │
 │  - Spawns agents via acp-factory                            │
-│  - Manages lifecycle (spawn, prompt, stop)                  │
-│  - Exposes sessions for context injection                   │
+│  - Manages lifecycle (spawn, prompt, stop, continue)        │
+│  - Spawn interception for team role/topic injection         │
 └───────────────────────────┬─────────────────────────────────┘
                             │
         ┌───────────────────┼───────────────────┐
@@ -31,10 +44,11 @@ macro-agent enables coordinated work across multiple AI agents with:
         ▼                   ▼                   ▼
 ┌──────────────┐   ┌──────────────┐   ┌──────────────┐
 │    Roles     │   │   Workspace  │   │    Tasks     │
-│  Worker      │   │  Bare Repo   │   │  Backend     │
-│  Integrator  │   │  Worktrees   │   │  (memory/    │
-│  Coordinator │   │  Pool        │   │   sudocode)  │
-│  Monitor     │   │              │   │              │
+│  Built-in +  │   │  Bare Repo   │   │  Backend     │
+│  Team-defined│   │  Worktrees   │   │  (memory/    │
+│  (via YAML)  │   │  Strategies  │   │   sudocode)  │
+│              │   │  (queue/     │   │  Push/Pull   │
+│              │   │   trunk/opt) │   │   modes      │
 └──────────────┘   └──────────────┘   └──────────────┘
         │                   │                   │
         └───────────────────┼───────────────────┘
@@ -43,7 +57,8 @@ macro-agent enables coordinated work across multiple AI agents with:
 │                     Message Router                           │
 │  - MAP addressing (agent, role, scope, parent/child)        │
 │  - sendToAddress() for all message routing                  │
-│  - Priority ordering (urgent > high > normal > low)         │
+│  - Topic-based status routing with signal filtering         │
+│  - Emission validation (strict/permissive/audit)            │
 │  - Activity waking for sleeping agents                      │
 └───────────────────────────┬─────────────────────────────────┘
                             │
@@ -51,7 +66,7 @@ macro-agent enables coordinated work across multiple AI agents with:
 │                      Event Store                             │
 │  - Append-only event log (SQLite)                           │
 │  - Materialized views for queries                           │
-│  - Agents, tasks, messages, events                          │
+│  - Agents, tasks, messages, events, team config             │
 └─────────────────────────────────────────────────────────────┘
 ```
 
@@ -65,34 +80,43 @@ src/
 │   └── session-mapper.ts   # Session → Agent ID mapping
 │
 ├── agent/               # Agent lifecycle
-│   ├── agent-manager.ts    # Spawn, prompt, stop agents
+│   ├── agent-manager.ts    # Spawn, prompt, stop, continue agents
 │   ├── wake.ts             # Wake sleeping agents
 │   └── system-prompt.ts    # Agent system prompts
 │
 ├── api/                 # REST API
-│   ├── server.ts           # Express routes
+│   ├── server.ts           # Express routes (agents, tasks, team, metrics)
 │   └── types.ts            # Request/response types
 │
 ├── cli/                 # Command-line interface
-│   └── index.ts            # CLI commands (start, chat, status)
+│   └── index.ts            # CLI commands (start, chat, status, --team)
+│
+├── config/              # Project configuration
+│   └── project-config.ts   # .macro-agent/config.json loader
 │
 ├── lifecycle/           # Agent lifecycle management
 │   ├── handlers/           # Role-specific done() handlers
-│   │   ├── worker.ts       # Worker completion (commit, merge request)
+│   │   ├── worker.ts       # Worker completion (strategy dispatch)
 │   │   ├── integrator.ts   # Integrator completion (merge queue)
 │   │   └── monitor.ts      # Monitor completion (health reporting)
 │   ├── cascade.ts          # Cascade termination
 │   └── cleanup.ts          # Workspace cleanup helpers
 │
 ├── mcp/                 # Model Context Protocol
-│   ├── mcp-server.ts       # Per-agent MCP server
+│   ├── mcp-server.ts       # Per-agent MCP server (role-based tool filtering)
 │   └── tools/              # MCP tool implementations
 │       ├── done.ts         # Generalized done() tool
-│       └── inject_context.ts # Context injection tool
+│       ├── inject_context.ts # Context injection tool
+│       ├── claim_task.ts   # Claim task from pool (pull mode)
+│       ├── unclaim_task.ts # Release claimed task (pull mode)
+│       └── list_claimable_tasks.ts # List available tasks (pull mode)
+│
+├── metrics/             # Observability
+│   └── metrics.ts          # Throughput, utilization, error metrics
 │
 ├── roles/               # Role system
 │   ├── types.ts            # RoleDefinition, Capability types
-│   ├── capabilities.ts     # Capability constants
+│   ├── capabilities.ts     # Capability constants (incl. task.claim)
 │   ├── registry.ts         # Role registry with resolution
 │   └── builtin/            # Built-in role definitions
 │       ├── worker.ts
@@ -101,10 +125,10 @@ src/
 │       └── monitor.ts
 │
 ├── router/              # Message routing
-│   ├── message-router.ts   # Core router with priority
+│   ├── message-router.ts   # Core router with signal filtering + emission validation
 │   ├── broadcast.ts        # Broadcast channel (fan-out)
 │   ├── role-resolver.ts    # Role → Agent resolution
-│   ├── wake.ts             # Activity waking
+│   ├── wake.ts             # Activity waking (status + message)
 │   └── types.ts            # Message, Channel types
 │
 ├── steering/            # In-flight steering
@@ -126,22 +150,42 @@ src/
 ├── task/                # Task management
 │   ├── task-manager.ts     # Legacy task manager
 │   └── backend/            # Pluggable task backends
-│       ├── types.ts        # TaskBackend interface
-│       ├── memory.ts       # InMemoryTaskBackend
+│       ├── types.ts        # TaskBackend interface (+ claim/unclaim/listClaimable)
+│       ├── memory.ts       # InMemoryTaskBackend (push + pull)
 │       ├── tool-provider.ts # Task MCP tools
 │       └── sudocode/       # Sudocode integration
 │
+├── teams/               # Team template system
+│   ├── types.ts            # TeamManifest, TeamTopology, TeamCommunication
+│   ├── team-loader.ts      # YAML loading, role resolution, validation
+│   ├── team-runtime.ts     # Initialize, bootstrap, peer routing, signal filtering
+│   └── index.ts            # Public exports
+│
 └── workspace/           # Workspace isolation
     ├── workspace-manager.ts # Worktree management
     ├── config.ts           # Workspace configuration
-    └── merge-queue/        # Merge queue
-        ├── merge-queue.ts  # SQLite-backed queue
-        ├── types.ts        # Queue types
-        └── schema.ts       # Database schema
+    ├── merge-queue/        # Merge queue
+    │   ├── merge-queue.ts  # SQLite-backed queue
+    │   ├── types.ts        # Queue types
+    │   └── schema.ts       # Database schema
+    └── strategies/         # Integration strategies
+        ├── types.ts        # IntegrationStrategy interface
+        ├── registry.ts     # Strategy factory registry
+        ├── queue.ts        # Queue strategy (wraps merge queue)
+        ├── trunk.ts        # Trunk strategy (direct push + rebase)
+        └── optimistic.ts   # Optimistic strategy (push + validation event)
 ```
 
 ## Key Concepts
 
+### Teams
+
+Teams are declarative YAML configurations that define multi-agent topologies:
+- **TeamLoader** (`team-loader.ts`): Parses `team.yaml`, resolves role inheritance, validates topology
+- **TeamRuntime** (`team-runtime.ts`): Wires team config into running services (roles, spawn interceptor, peer routing, signal filtering, emission validation, continuation monitoring)
+- Teams compose on top of existing primitives — no team loaded = identical behavior to pre-team codebase
+- Team config is shared across processes via EventStore `team_config` event
+
 ### Roles
 
 Agents are assigned roles that determine their capabilities:
@@ -153,18 +197,40 @@ Agents are assigned roles that determine their capabilities:
 | **Coordinator** | Orchestrate workers and manage tasks | Spawn agents, assign tasks, broadcast |
 | **Monitor** | Health monitoring and alerts | Read-only access, activity watching |
 
+Teams can define custom roles (e.g., planner, grinder, judge) that extend built-in roles via `extends` in `roles/<name>.yaml`. Custom roles can add/remove capabilities and provide custom prompts.
+
+### Integration Strategies
+
+Pluggable strategies for landing worker changes:
+- **Queue** (`queue.ts`): Wraps merge queue with serialized integration
+- **Trunk** (`trunk.ts`): Direct push with rebase-retry loop, configurable `conflictAction`
+- **Optimistic** (`optimistic.ts`): Same as trunk + emits `validation:requested` event
+
+Strategy is set per-team in `team.yaml` under `macro_agent.integration.strategy`.
+
 ### Workspace Isolation
 
 Each worker gets an isolated git worktree:
 - Workers operate on feature branches
-- Changes merge through the queue
+- Changes merge through the queue or strategy
 - Conflicts detected and resolved by integrator
 
 ### Task Backend
 
 Two backends available:
-- **memory**: In-memory tasks with EventStore persistence
-- **sudocode**: External issue tracking with dependency management
+- **memory**: In-memory tasks with EventStore persistence (supports push + pull modes)
+- **sudocode**: External issue tracking with dependency management (push mode only)
+
+Pull mode adds `claim_task`, `unclaim_task`, `list_claimable_tasks` MCP tools (gated by `task.claim` capability).
+
+### Communication Topology
+
+Teams configure non-hierarchical communication via:
+- **Channels**: Named topics (e.g., `work_coordination`, `task_updates`) with defined signals
+- **Subscriptions**: Per-role channel subscriptions with optional signal filters
+- **Peer routing**: Directional connections between roles (`via: direct|topic|scope`) with per-peer signal filters
+- **Emissions**: Per-role allowed signal lists, enforced by emission validator
+- **Enforcement**: `strict` (reject violations), `permissive` (warn), `audit` (record to EventStore)
 
 ### Context Injection
 
@@ -188,6 +254,17 @@ Inject context into running agents:
 - **kebab-case** for file names
 - **SCREAMING_SNAKE** for constants
 
+#### ID Field Naming Convention
+
+Different layers use different naming for ID fields by design:
+
+| Layer | Convention | Example | Rationale |
+|-------|------------|---------|-----------|
+| **Internal** (store, router, activity) | `agent_id`, `task_id` | `source.agent_id` | Database/event conventions, explicit |
+| **MAP Protocol** (map/types) | `agent`, `task` | `address.agent` | Protocol spec, cleaner syntax |
+
+The `store/types/events.ts` module bridges these conventions when converting between internal events and MAP addresses.
+
 ### Testing
 
 - **Unit tests**: `*.test.ts` - Fast, mocked dependencies
@@ -215,13 +292,20 @@ npm run test:e2e            # E2E tests (requires RUN_E2E_TESTS=true)
 3. Export tool info and handler
 4. Register in `src/mcp/mcp-server.ts`
 
-### Adding a New Role
+### Adding a New Built-in Role
 
 1. Create `src/roles/builtin/your_role.ts`
 2. Define `RoleDefinition` with capabilities
 3. Add enforcement implementations
 4. Register in `src/roles/builtin/index.ts`
 
+### Adding a Team Role (via YAML)
+
+1. Create `.macro-agent/teams/<team>/roles/<role>.yaml` with `extends` base role
+2. Add `capabilities_add`/`capabilities_remove` as needed
+3. Create `.macro-agent/teams/<team>/prompts/<role>.md` for custom prompt
+4. Reference the role in `team.yaml` topology and communication sections
+
 ### Modifying Task Backend
 
 1. Update interface in `src/task/backend/types.ts`
@@ -236,10 +320,17 @@ npm run test:e2e            # E2E tests (requires RUN_E2E_TESTS=true)
 | `SUDOCODE_PROJECT_PATH` | Path to sudocode project | `cwd` |
 | `MACRO_WORKSPACE_POOL_SIZE` | Max concurrent workspaces | `10` |
 | `MACRO_MERGE_QUEUE_DB` | Merge queue SQLite path | `:memory:` |
+| `MACRO_TEAM_NAME` | Team name (injected into agent env by team runtime) | — |
+| `MACRO_TASK_MODE` | Task mode: `push` or `pull` (injected by team runtime) | — |
+| `MACRO_INTEGRATION_STRATEGY` | Integration strategy name (injected by team runtime) | — |
+| `MACRO_INSTANCE_ID` | EventStore instance ID (for MCP subprocess access) | — |
+| `MACRO_BASE_DIR` | EventStore base directory (for MCP subprocess access) | — |
 
 ## References
 
 - [README.md](README.md) - User-facing documentation
-- [docs/sudocode-integration.md](docs/sudocode-integration.md) - Sudocode backend details
 - [docs/architecture.md](docs/architecture.md) - Full architecture documentation
 - [docs/configuration.md](docs/configuration.md) - Configuration reference
+- [docs/teams.md](docs/teams.md) - Team template schema reference
+- [docs/team-templates.md](docs/team-templates.md) - Team template format and examples
+- [docs/sudocode-integration.md](docs/sudocode-integration.md) - Sudocode backend details

package/README.md

@@ -6,14 +6,19 @@ A multi-agent orchestration system for spawning and managing hierarchical Claude
 
 - **Hierarchical Agent Management** - Head manager spawns and coordinates child agents
 - **Role-Based Agents** - Worker, Integrator, Coordinator, and Monitor roles with distinct capabilities
+- **Team Templates** - Declarative YAML-based team configurations for multi-agent topologies
+- **Pluggable Integration Strategies** - Queue, trunk, or optimistic merge strategies
 - **Workspace Isolation** - Each worker gets isolated git worktrees to prevent conflicts
 - **Merge Queue** - Serialized integration of worker changes with conflict resolution
 - **Event-Sourced State** - All state changes persisted via append-only event log
 - **Real-time Communication** - WebSocket subscriptions for live updates
 - **MCP Tool Integration** - Agents communicate via Model Context Protocol tools
-- **Task Lifecycle** - Create, assign, and track tasks across agents
-- **Message Routing** - Direct, broadcast, and role-based message delivery with priority
+- **Task Lifecycle** - Create, assign, and track tasks with push or pull models
+- **Message Routing** - Direct, broadcast, role-based, and topic-based message delivery with priority
+- **Signal Filtering** - Per-role and per-peer signal filtering for status notifications
 - **Context Injection** - Push context into running agents without waiting for message checks
+- **Session Continuations** - Auto-resume long-running agents across process restarts
+- **Observability** - Throughput, utilization, and error metrics via REST API
 - **Sudocode Integration** - Optional issue tracking with dependency management
 
 ## Sudocode Integration
@@ -37,6 +42,44 @@ With sudocode enabled:
 
 See [docs/sudocode-integration.md](docs/sudocode-integration.md) for full documentation.
 
+## Team Templates
+
+Teams define multi-agent topologies as YAML configuration. A team template specifies which roles to spawn, how they communicate, and what integration strategy to use.
+
+```bash
+# Start with a team template
+npx multiagent --team self-driving
+
+# Or set in project config (.macro-agent/config.json)
+echo '{ "team": "self-driving" }' > .macro-agent/config.json
+npx multiagent
+```
+
+Teams are stored in `.macro-agent/teams/<name>/`:
+
+```
+.macro-agent/teams/self-driving/
+├── team.yaml          # Team manifest (topology, communication, strategy)
+├── roles/
+│   ├── planner.yaml   # Custom role (extends coordinator)
+│   ├── grinder.yaml   # Custom role (extends worker)
+│   └── judge.yaml     # Custom role (extends monitor)
+└── prompts/
+    ├── planner.md     # Role-specific system prompt
+    ├── grinder.md
+    └── judge.md
+```
+
+Key team features:
+- **Topology**: Root + companion agents spawned at bootstrap, with spawn rules for dynamic workers
+- **Communication**: Topic-based channels with per-role signal filtering, peer-to-peer routing
+- **Integration strategies**: `queue` (merge queue), `trunk` (direct push with rebase), `optimistic` (push + validation)
+- **Task modes**: `push` (coordinator assigns) or `pull` (agents claim from pool)
+- **Enforcement**: `strict` (reject violations), `permissive` (warn), or `audit` (record)
+- **Session continuations**: Auto-resume daemon agents on unexpected stops
+
+See [docs/teams.md](docs/teams.md) for the full schema reference and [docs/team-templates.md](docs/team-templates.md) for examples.
+
 ## Installation
 
 ```bash
@@ -51,6 +94,9 @@ npm install macro-agent
 # Start full server with ACP + MAP + REST API
 npx multiagent
 
+# Start with a team template
+npx multiagent --team self-driving
+
 # Custom port and host
 npx multiagent --port 8080 --host 0.0.0.0
 ```
@@ -224,6 +270,10 @@ Fallback chain: `inject()` → `interruptWith()` → high-priority message
 | `/api/events` | GET | List events |
 | `/api/conversation/message` | POST | Send message |
 | `/api/conversation/history` | GET | Get history |
+| `/api/team` | GET | Active team info |
+| `/api/metrics/throughput` | GET | Task completion rates |
+| `/api/metrics/utilization` | GET | Agent counts by role/state |
+| `/api/metrics/errors` | GET | Error tracking |
 
 ### WebSocket Channels
 
@@ -237,7 +287,7 @@ Fallback chain: `inject()` → `interruptWith()` → high-priority message
 | Tool | Description |
 |------|-------------|
 | `spawn_agent` | Spawn a child agent |
-| `emit_status` | Report status to parent |
+| `emit_status` | Report status (with signal filtering and emission validation) |
 | `send_message` | Send message to another agent |
 | `check_messages` | Check message inbox |
 | `get_hierarchy` | View agent tree |
@@ -246,6 +296,9 @@ Fallback chain: `inject()` → `interruptWith()` → high-priority message
 | `create_task` | Create a new task |
 | `get_task` | Get task details |
 | `list_ready_tasks` | List tasks with no blockers |
+| `claim_task` | Claim next available task (pull mode) |
+| `unclaim_task` | Return claimed task to pool (pull mode) |
+| `list_claimable_tasks` | List claimable tasks (pull mode) |
 | `done` | Signal task completion (role-specific) |
 | `inject_context` | Inject context into another agent |
 | `wait_for_activity` | Wait for system events (Monitor) |
@@ -279,6 +332,7 @@ npx multiagent --acp --cwd /path/to/project
 | `--port <port>` | Server port (default: 3001) |
 | `--host <host>` | Server host (default: localhost) |
 | `--cwd <path>` | Working directory for agents |
+| `--team <name>` | Load team template from `.macro-agent/teams/<name>/` |
 | `--acp` | Stdio ACP-only mode (for embedded use with acp-factory) |
 
 ### Multi-Client Architecture
@@ -344,6 +398,7 @@ multiagent [options]          Start the agent server (full mode by default)
   --port <port>               Port (default: 3001)
   --host <host>               Host (default: localhost)
   --cwd <path>                Working directory
+  --team <name>               Load team template
   --acp                       Stdio ACP-only mode (for acp-factory)
 ```
 
@@ -397,6 +452,8 @@ RUN_E2E_TESTS=true ANTHROPIC_API_KEY=xxx npm run test:e2e
 
 - [Architecture Overview](docs/architecture.md) - Full system architecture
 - [Configuration Reference](docs/configuration.md) - Environment variables and config options
+- [Team Templates](docs/team-templates.md) - Team template format and examples
+- [Team Schema Reference](docs/teams.md) - Full YAML schema reference
 - [Sudocode Integration](docs/sudocode-integration.md) - External issue tracking
 - [Troubleshooting Guide](docs/troubleshooting.md) - Common issues and solutions
 

package/dist/acp/macro-agent.d.ts

@@ -169,6 +169,10 @@ export declare class MacroAgent implements Agent {
      * then calls the agent manager to cancel the pending permission.
      */
     private handleCancelPermission;
+    /**
+     * Resume a stopped/failed agent
+     */
+    private handleResumeAgent;
     /**
      * Extract text content from prompt content blocks
      */

package/dist/acp/macro-agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"macro-agent.d.ts","sourceRoot":"","sources":["../../src/acp/macro-agent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"macro-agent.d.ts","sourceRoot":"","sources":["../../src/acp/macro-agent.ts"],"names":[],"mappings":"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"}

package/dist/acp/macro-agent.js

@@ -28,6 +28,7 @@ const SUPPORTED_EXTENSIONS = [
     "_macro/checkCapability",
     "_macro/respondToPermission",
     "_macro/cancelPermission",
+    "_macro/resume",
 ];
 // ─────────────────────────────────────────────────────────────────
 // MacroAgent Implementation
@@ -58,8 +59,13 @@ export class MacroAgent {
         this.peerManager = config.peerManager;
         this.capabilityManager = config.capabilityManager;
         this.roleRegistry = config.roleRegistry ?? new DefaultRoleRegistry();
-        this.sessionMapper = new SessionMapper();
+        this.sessionMapper = new SessionMapper(config.eventStore);
         this.defaultCwd = config.defaultCwd ?? process.cwd();
+        // Recover persisted sessions from the EventStore
+        const recovered = this.sessionMapper.recoverFromStore();
+        if (recovered > 0) {
+            console.log(`[MacroAgent] Recovered ${recovered} session(s) from EventStore`);
+        }
     }
     // ─────────────────────────────────────────────────────────────────
     // Core ACP Methods
@@ -121,8 +127,21 @@ export class MacroAgent {
      * Load an existing session from EventStore
      */
     async loadSession(params) {
-        const acpSessionId = params.sessionId;
+        let acpSessionId = params.sessionId;
         const cwd = params.cwd ?? this.defaultCwd;
+        // Extension: If _meta.agentId provided, look up session from agent record
+        // This allows resuming a stopped head manager by MAP agent ID
+        // when the TUI doesn't know the ACP session ID
+        const metaAgentId = params._meta
+            ?.agentId;
+        if (metaAgentId) {
+            const agent = this.eventStore.getAgent(metaAgentId);
+            if (!agent) {
+                throw new Error(`Agent not found: ${metaAgentId}`);
+            }
+            acpSessionId = agent.session_id;
+            console.log(`[MacroAgent] loadSession: Resolved agentId ${metaAgentId} to session ${acpSessionId}`);
+        }
         // Try to find an existing head manager with this session ID
         const headManagers = this.agentManager.listHeadManagers();
         const existing = headManagers.find((hm) => hm.session_id === acpSessionId);
@@ -203,8 +222,8 @@ export class MacroAgent {
             await this.connection.sessionUpdate({
                 sessionId: acpSessionId,
                 update: {
-                    type: "agent_message_chunk",
-                    textChunk: `Error: ${errorMessage}`,
+                    sessionUpdate: "agent_message_chunk",
+                    content: { type: "text", text: `Error: ${errorMessage}` },
                 },
             });
             return {
@@ -286,6 +305,8 @@ export class MacroAgent {
                 return this.handleRespondToPermission(params);
             case "_macro/cancelPermission":
                 return this.handleCancelPermission(params);
+            case "_macro/resume":
+                return this.handleResumeAgent(params);
             default:
                 throw new ACPError(`Unknown extension method: ${method}`, "INVALID_EXTENSION");
         }
@@ -714,6 +735,31 @@ export class MacroAgent {
             };
         }
     }
+    /**
+     * Resume a stopped/failed agent
+     */
+    async handleResumeAgent(params) {
+        const { agentId } = params;
+        if (!agentId) {
+            throw new ACPError("agentId is required", "INVALID_EXTENSION");
+        }
+        // Verify agent exists
+        const agent = this.eventStore.getAgent(agentId);
+        if (!agent) {
+            throw new ACPError(`Agent not found: ${agentId}`, "AGENT_NOT_FOUND");
+        }
+        // Only resume stopped/failed agents
+        if (agent.state !== "stopped" && agent.state !== "failed") {
+            throw new ACPError(`Agent ${agentId} is ${agent.state} — only stopped or failed agents can be resumed`, "INVALID_EXTENSION");
+        }
+        console.log(`[MacroAgent] Resuming agent ${agentId}`);
+        const spawned = await this.agentManager.resume(agentId);
+        return {
+            success: true,
+            agentId: spawned.id,
+            sessionId: spawned.session_id,
+        };
+    }
     // ─────────────────────────────────────────────────────────────────
     // Helper Methods
     // ─────────────────────────────────────────────────────────────────