macro-agent 0.1.1 → 0.1.3

package/docs/lifecycle-events-design.md

@@ -0,0 +1,111 @@
+# Lifecycle Events Design
+
+## Problem
+
+macro-agent V2 has internal lifecycle events (`AgentManager.onLifecycleEvent`) but these don't propagate to:
+1. **OpenHive hub** — needs to see agent spawn/stop for swarm monitoring
+2. **OpenSwarm TUI** — needs events for dashboard updates (agent list, status indicators)
+3. **TUI store** — expects `macro.status.emitted` events for milestone tracking (currently dormant)
+
+## Current State
+
+### What exists
+
+- `AgentManager.onLifecycleEvent()` — callback for `spawned | started | stopped` events
+- MAP sidecar lifecycle bridge — translates lifecycle → MAP `spawn()`/`unregister()` for hub
+- MAP server lifecycle sync — registers/unregisters agents in MAPServer's agent registry
+- MAPServer eventBus — emits `agent.registered`/`agent.unregistered` events (now working with SubscriptionManager patch)
+
+### What's missing
+
+1. **Rich status events** — `spawned`/`stopped` are lifecycle state changes. cc-swarm also emits milestone events like `checkpoint`, `blocked`, `discovery`. V2 doesn't have these.
+
+2. **Session update events for observers** — when agent A prompts a child agent B, the ACP session updates from B are only visible to A's ACP stream. Other MAP clients (TUI observers) don't see B's activity unless they create their own ACP stream to B.
+
+3. **Task state events via MAP** — when tasks transition in opentasks, no MAP events are emitted. The task bridge emits events via the sidecar (outbound to hub) but not via the MAP server (inbound for TUI).
+
+## Design
+
+### Layer 1: Enhanced lifecycle events
+
+Extend `AgentLifecycleEvent` with richer event types:
+
+```typescript
+type AgentLifecycleEvent =
+  | { type: "spawned"; agent: Agent }
+  | { type: "started"; agent: Agent }
+  | { type: "stopped"; agent: Agent; reason: StopReason }
+  // New events:
+  | { type: "state_changed"; agent: Agent; previousState: AgentState; newState: AgentState }
+  | { type: "task_assigned"; agent: Agent; taskId: string }
+  | { type: "prompt_started"; agent: Agent; promptLength: number }
+  | { type: "prompt_completed"; agent: Agent; stopReason: string; tokenUsage?: TokenUsage }
+```
+
+Source: emit from `AgentManagerV2.spawn()`, `terminate()`, `prompt()`.
+
+### Layer 2: MAP event emission
+
+When lifecycle events fire, emit corresponding MAP events on the MAPServer's eventBus AND via the MAP sidecar:
+
+| Lifecycle event | MAP server event (for TUI) | MAP sidecar event (for hub) |
+|---|---|---|
+| `spawned` | `agent.registered` (already works) | `agents/spawn` (already works) |
+| `stopped` | `agent.unregistered` (already works) | `agents/unregister` (already works) |
+| `state_changed` | `agent.state.changed` | `connection.updateState()` |
+| `task_assigned` | Custom `macro.task.assigned` | `task.assigned` broadcast |
+| `prompt_started` | Custom `macro.agent.busy` | State update to "busy" |
+| `prompt_completed` | Custom `macro.agent.idle` + trajectory checkpoint | State update to "idle" + checkpoint |
+
+### Layer 3: Session observation events
+
+When any ACP session produces updates, broadcast them as MAP events so other clients can observe:
+
+```
+Agent B produces session update
+  → ACP bridge sends to requesting client (A)
+  → ACP bridge ALSO emits on MAPServer eventBus
+  → Other clients subscribed to B's events see the update
+  → TUI renders observed stream in real-time
+```
+
+This is partially implemented — the bridge emits `message_delivered` events on the eventBus (added this session). Needs verification that the TUI's "observed" stream handling picks these up correctly.
+
+### Layer 4: StatusEvent bridge (for TUI backward compat)
+
+The TUI store has handlers for `macro.status.emitted` events. To emit these:
+
+```typescript
+// In the MAP server lifecycle callback:
+agentManager.onLifecycleEvent((event) => {
+  if (event.type === "spawned") {
+    mapServer.eventBus.emit({
+      type: "macro.status.emitted",  // Custom event type
+      data: {
+        id: `status-${Date.now()}`,
+        agentId: event.agent.id,
+        statusType: "started",
+        summary: `Agent ${event.agent.name} spawned`,
+        timestamp: Date.now(),
+      },
+      source: { agentId: event.agent.id },
+    });
+  }
+  // Similar for stopped, prompt_completed, etc.
+});
+```
+
+The TUI's `macroAgentStore.eventHandlers["macro.status.emitted"]` would then update the status events in the store.
+
+## Implementation Order
+
+1. **Session observation** — verify the eventBus emission in acp-bridge.ts works for TUI observed streams
+2. **StatusEvent bridge** — emit `macro.status.emitted` events from lifecycle callbacks in the MAP server
+3. **Enhanced lifecycle events** — add `state_changed`, `prompt_started`, `prompt_completed` to AgentManagerV2
+4. **Task state events** — emit `macro.task.*` events via MAP server when tasks transition
+
+## Dependencies
+
+- SubscriptionManager patch (done — `server.ts` step 2b)
+- ACP bridge eventBus emission (done — `acp-bridge.ts`)
+- MAP server lifecycle sync (done — `server.ts` step 6)

package/docs/openhive-capability-summary.md

@@ -0,0 +1,415 @@
+# macro-agent: OpenHive Ecosystem Capability Summary
+
+## 1. Architecture Overview
+
+```
+                          OpenHive Hub
+                     (Fastify + SQLite/PG)
+                    /ws/map  /api/v1  /ws
+                            |
+              MAP (JSON-RPC 2.0 over WebSocket)
+                            |
+           +----------------+----------------+
+           |                                 |
+   macro-agent Sidecar              cc-swarm Sidecar
+   (AgentConnection outbound)       (AgentConnection outbound)
+           |                                 |
+   +-------+--------+              +---------+---------+
+   | macro-agent     |              | Claude Code       |
+   | (boot-v2.ts)    |              | (native teams)    |
+   |                 |              |                   |
+   | AgentManagerV2  |              | /swarm skill      |
+   | InboxAdapter    |              | map-hook.mjs      |
+   | TasksAdapter    |              | sidecar-server    |
+   | ControlServer   |              | bootstrap.mjs     |
+   | TriggerSystem   |              +-------------------+
+   | MAP Server      |
+   | ACP Server      |
+   | REST API        |
+   +-------+---------+
+           |
+     OpenSwarm TUI
+     (MAP client, ACP-over-MAP)
+```
+
+### Key architectural difference
+
+- **macro-agent** is a standalone orchestration process that spawns Claude Code (or other) agents as subprocesses. It owns agent lifecycle, messaging (agent-inbox), task management (opentasks), workspace isolation (git worktrees), and exposes both a MAP server (inbound) and MAP sidecar (outbound).
+
+- **cc-swarm** is a Claude Code plugin that hooks into an existing Claude Code session. It uses Claude Code's native team features (`TeamCreate`, `SendMessage`, `TaskCreate`) for coordination and provides external observability via a MAP sidecar process.
+
+---
+
+## 2. Core Capabilities
+
+macro-agent is a multi-agent orchestration system that provides:
+
+| Capability | Implementation | Key File |
+|---|---|---|
+| **Hierarchical agent spawning** | `AgentManagerV2` — spawns Claude Code agents via `acp-factory`, manages parent-child relationships | `src/agent/agent-manager-v2.ts` |
+| **Role-based agents** | Worker, Integrator, Coordinator, Monitor + custom YAML roles with capability inheritance | `src/roles/builtin/`, `src/roles/registry.ts` |
+| **Team templates** | Declarative YAML topologies with per-team scoped messaging, signal filtering, emission validation | `src/teams/team-runtime-v2.ts`, `src/teams/team-manager-v2.ts` |
+| **Messaging** | Embedded agent-inbox with IPC for MCP subprocesses, threading, federation, composite signal filters | `src/adapters/inbox-adapter.ts` |
+| **Task management** | opentasks daemon IPC — task graph, dependencies, providers, claiming, pull-mode work | `src/adapters/tasks-adapter.ts` |
+| **Workspace isolation** | Git worktrees via git-cascade, merge queue, pluggable integration strategies (queue/trunk/optimistic) | `src/workspace/` |
+| **Control socket** | NDJSON-over-UNIX-socket RPC between MCP subprocesses and main process | `src/control/control-server.ts` |
+| **Trigger system** | Pluggable routing strategies, WakeManager, SystemEventQueue, CronService, WebhookHandler | `src/trigger/trigger-system-v2.ts` |
+| **ACP protocol** | Full Agent Client Protocol implementation with session management, streaming, permissions, extensions | `src/acp/macro-agent.ts` |
+| **Health monitoring** | MCP subprocess heartbeat tracking, stale agent detection, parent notification | `src/boot-v2.ts` (lines 277-314) |
+
+### MCP Tool Surface (per agent)
+
+| Source | Tools |
+|---|---|
+| macro-agent core | `done`, `spawn_agent`, `stop_agent`, `get_hierarchy`, `inject_context` |
+| macro-agent pull mode | `claim_task`, `unclaim_task`, `list_claimable_tasks` |
+| agent-inbox | `send_message`, `check_inbox`, `read_thread`, `list_agents` |
+| opentasks | `task`, `link`, `annotate`, `query` |
+
+### ACP Extension Methods
+
+```
+_macro/spawnAgent, _macro/getHierarchy, _macro/getTask,
+_macro/mountAgent, _macro/forkAgent, _macro/resume,
+_macro/getHistory, _macro/getModels,
+_macro/respondToPermission, _macro/cancelPermission, _macro/setPermissionMode
+```
+
+Plus stubbed peer extensions: `_macro/listPeers`, `_macro/getPeer`, `_macro/sendToPeer`, etc.
+
+---
+
+## 3. MAP Integration
+
+macro-agent has two MAP components, both optional:
+
+### 3a. MAP Server (inbound connections)
+
+**File**: `src/map/server.ts`
+**Config**: `mapServer: { enabled: true, port: 3002, host: "127.0.0.1", path: "/map" }`
+
+Accepts inbound MAP connections from TUI clients and other MAP participants. Built on `MAPServer` from `@multi-agent-protocol/sdk/server`.
+
+| Feature | Implementation |
+|---|---|
+| Agent discovery | `listAgents` / `subscribe` — synced from AgentManager lifecycle events |
+| ACP-over-MAP | Full bridge (`src/map/acp-bridge.ts`) — MAP clients send ACP envelopes, routed to `createMacroAgent()` |
+| Extension methods | `_macro/spawnAgent`, `_macro/getHierarchy`, `_macro/forkAgent`, `_macro/resume`, `_macro/task/list`, `_macro/getTask`, `_macro/getHistory`, `ping` |
+| Trajectory forwarding | `trajectory/checkpoint` handler receives from child cc-swarm agents, forwards upstream to sidecar |
+| ID mapping | Bidirectional `mapIdToLocalId` / `localIdToMapId` for routing between MAP ULIDs and local agent IDs |
+
+### 3b. MAP Sidecar (outbound hub connection)
+
+**File**: `src/map/sidecar.ts`
+**Config**: `map: { enabled: true, server: "ws://hub:3000", token: "...", scope: "swarm:macro-agent" }`
+
+Connects outbound to an OpenHive MAP hub via `AgentConnection` from `@multi-agent-protocol/sdk`.
+
+| Sub-module | File | Purpose |
+|---|---|---|
+| **Lifecycle Bridge** | `src/map/lifecycle-bridge.ts` | Agent spawn → `connection.spawn()`, agent stop → `callExtension("map/agents/unregister")` |
+| **Trajectory Reporter** | `src/map/trajectory-reporter.ts` | Sends checkpoints via `callExtension("trajectory/checkpoint")`, handles inbound `trajectory/content.request` |
+| **Task Bridge** | `src/map/task-bridge.ts` | Emits `task.created`, `task.status`, `task.assigned`, `task.completed` to MAP scope |
+| **Coordination Handler** | `src/map/coordination-handler.ts` | Handles inbound `x-openhive/task.assign`, `x-openhive/task.status`, `x-openhive/context.share`, `x-openhive/message.send`, `x-openhive/learning.workspace.execute` |
+
+**Connection features**:
+- Open mode (single call connect+register) and verified mode (connectOnly + authenticate + register)
+- SDK-level reconnection (configurable maxRetries, baseDelay, maxDelay)
+- Slow reconnection loop after SDK retries exhausted (default 60s interval)
+- State change monitoring
+- Declared capabilities: `trajectory.canReport: true`, `trajectory.canServeContent: false`, `tasks.canCreate/canAssign/canUpdate/canList: true`
+
+---
+
+## 4. OpenHive Integration
+
+### What macro-agent provides to OpenHive
+
+| Feature | Wire Format | OpenHive Handler |
+|---|---|---|
+| **Agent registration** | `connection.spawn({ agentId, name, role, scopes, metadata })` | MAP hub agent registry |
+| **Agent unregistration** | `callExtension("map/agents/unregister", { agentId, reason })` | MAP hub agent registry |
+| **Trajectory checkpoints** | `callExtension("trajectory/checkpoint", { checkpoint, resource_id })` | `src/map/trajectory-handler.ts` — auto-creates session resource, stores checkpoint |
+| **Task events** | `connection.send({ scope }, { type: "task.created", task: {...} })` | Scoped MAP message delivery |
+| **Content serving response** | `sendNotification("trajectory/content.response", { request_id, transcript })` | `src/map/trajectory-content.ts` |
+
+### What OpenHive sends to macro-agent
+
+| Feature | Wire Format | macro-agent Handler |
+|---|---|---|
+| **Task assignment** | `x-openhive/task.assign` notification | Creates task in opentasks, notifies assigned agent via inbox |
+| **Task status update** | `x-openhive/task.status` notification | Transitions task state in opentasks |
+| **Context sharing** | `x-openhive/context.share` notification | Delivers to all running agents via inbox |
+| **Cross-swarm messaging** | `x-openhive/message.send` notification | Routes to coordinator or specific agent via inbox |
+| **Workspace execution** | `x-openhive/learning.workspace.execute` notification | Delegates to cognitive module workspace handler |
+| **Content request** | `trajectory/content.request` notification | Responds with minimal metadata (full transcript serving not yet implemented) |
+
+### Trajectory Wire Format (cc-swarm compatible)
+
+```typescript
+interface TrajectoryCheckpointPayload {
+  id: string;                    // "<sessionId>-step<N>"
+  session_id: string;
+  agent: string;
+  branch: string | null;
+  files_touched: string[];
+  checkpoints_count: number;
+  token_usage?: {
+    input_tokens?: number;
+    output_tokens?: number;
+    cache_creation_tokens?: number;
+    cache_read_tokens?: number;
+    api_call_count?: number;
+  };
+  metadata?: {
+    project?: string;
+    projectPath?: string;
+    firstPrompt?: string;        // Used as session description in OpenHive UI
+    phase?: string;
+    template?: string;
+    [key: string]: unknown;
+  };
+}
+```
+
+---
+
+## 5. OpenSwarm Integration
+
+**Adapter**: `references/openswarm/src/hosting/adapters/macro-agent.ts` (`MacroAgentAdapter`)
+
+OpenSwarm can host macro-agent as a managed swarm. The adapter:
+
+1. Calls `bootV2()` with config derived from `AdapterConfig`
+2. Enables ACP WebSocket server on `config.port`
+3. Enables MAP server on `config.port + 2`
+4. Optionally enables REST API on `config.options.apiPort`
+5. Forwards MAP sidecar config from `options.map`
+6. Exposes `getConnectionUrl()` returning the MAP server URL (for TUI connections)
+7. Provides `getSystem()` for plugin-level access to `MacroAgentSystemV2`
+
+### Bootstrap Token Auto-Wiring
+
+**File**: `references/openswarm/src/hosting/config.ts` (lines 222-239)
+
+When OpenHive spawns a swarm, it provides a base64-encoded `OPENSWARM_BOOTSTRAP_TOKEN`. The config loader automatically populates MAP sidecar config:
+
+```typescript
+// From the token:
+token.adapter_config.map = {
+  enabled: true,
+  server: token.openhive_url.replace(/^http/, "ws") + "/ws/map",
+  token: token.preauth_key,
+  scope: `swarm:${token.swarm_name}`,
+  agentName: `${token.swarm_name}-sidecar`,
+  trajectorySyncLevel: "metrics",
+};
+```
+
+This means: when OpenHive spawns a macro-agent swarm, the swarm automatically connects back to the hub with zero manual configuration.
+
+### Default adapter
+
+OpenSwarm's `DEFAULT_CONFIG.adapter.id` is `"macro-agent"` — it is the default hosting adapter.
+
+---
+
+## 6. Parity with cc-swarm (Feature Comparison)
+
+| Feature | cc-swarm | macro-agent | Notes |
+|---|---|---|---|
+| **Agent spawning** | Claude Code native (`Agent` tool with `team_name`) | `AgentManagerV2.spawn()` via acp-factory | Both spawn Claude Code processes |
+| **Team templates** | openteams YAML → `openteams generate all` → AGENT.md | openteams YAML → TeamRuntimeV2 → runtime topology | cc-swarm generates static files; macro-agent uses runtime wiring |
+| **Messaging** | Claude Code native `SendMessage` | agent-inbox (embedded, IPC, threading, federation) | macro-agent has richer messaging primitives |
+| **Task management** | Claude Code native `TaskCreate`/`TaskUpdate` + optional OpenTasks | opentasks (IPC daemon) + native `claim_task`/`unclaim_task` | Both support OpenTasks; macro-agent adds pull-mode claiming |
+| **MAP sidecar** | Persistent Node.js process (`map-sidecar.mjs`) | Embedded in bootV2 (`src/map/sidecar.ts`) | cc-swarm runs a separate process; macro-agent runs in-process |
+| **MAP server** | No (client-only) | Yes (`src/map/server.ts`) — accepts inbound MAP connections | Unique to macro-agent |
+| **Agent lifecycle → MAP** | `conn.spawn()` / `conn.callExtension("map/agents/unregister")` | Same wire format via lifecycle-bridge | Compatible |
+| **Trajectory reporting** | `trajectory/checkpoint` via `callExtension` (with `trajectory.checkpoint` broadcast fallback) | Same wire format via trajectory-reporter | Compatible; macro-agent also reports from ACP prompt handler |
+| **Task → MAP bridge** | `bridge-task-created`, `bridge-task-status`, etc. via `conn.send()` | `task.created`, `task.status`, etc. via `conn.send()` | Event type names differ (`bridge-task-*` vs `task.*`); payload structure compatible |
+| **Content serving** | Sessionlog transcripts via `trajectory/content.response` | Stub response ("not yet implemented") | Gap — macro-agent cannot serve full transcripts |
+| **sessionlog integration** | Full — detects sessions, builds checkpoints from sessionlog state | Via cc-swarm-hooks integration (spawns cc-swarm sidecar per agent) | macro-agent can piggyback on cc-swarm's sessionlog |
+| **Workspace isolation** | None (agents share the project directory) | Git worktrees with merge queue and integration strategies | Unique to macro-agent |
+| **MeshPeer transport** | Supported (`mesh.enabled`) via agentic-mesh | Not supported | Gap |
+| **minimem (memory)** | Supported — MCP server with semantic search | Not supported | Gap |
+| **skill-tree (per-role skills)** | Supported — compiled into AGENT.md at generation time | Not supported | Gap |
+| **Permission handling** | Not applicable (runs inside Claude Code) | Full ACP permission request/response flow | Unique to macro-agent |
+| **ACP protocol** | Not applicable | Full ACP agent implementation with extensions | Unique to macro-agent |
+| **Inbound coordination** | Not supported | `x-openhive/*` handlers for task assign, status, context share, messaging | Unique to macro-agent |
+| **Federation** | Not supported | agent-inbox federation with peer routing | Unique to macro-agent |
+| **OpenHive auto-wiring** | Via `SWARM_MAP_SERVER` env var + config | Via bootstrap token → `BootV2Config.map` | Both work; macro-agent's is more automatic |
+
+---
+
+## 7. Parity with Swarmkit Technologies
+
+Swarmkit is a package manager for the swarm ecosystem. cc-swarm uses it to install global packages. Here is macro-agent's support for each:
+
+| Swarmkit Package | cc-swarm Status | macro-agent Status | Notes |
+|---|---|---|---|
+| **openteams** | Core dependency — generates AGENT.md artifacts | Core dependency — `TeamRuntimeV2` loads team YAML directly | Both use openteams templates |
+| **@multi-agent-protocol/sdk** | MAP connection + hooks | MAP sidecar + server (embedded) | macro-agent uses both client and server SDK |
+| **agent-inbox** | Optional — messaging over MAP/mesh | Core dependency — embedded in-process, IPC for subprocesses | macro-agent uses agent-inbox more deeply |
+| **opentasks** | Optional — MCP server + daemon IPC | Core dependency — `TasksAdapter` wraps opentasks client | macro-agent uses opentasks more deeply |
+| **sessionlog** | Optional — session capture + trajectory sync | Not directly used (piggybacks via cc-swarm-hooks) | Gap — no native sessionlog integration |
+| **minimem** | Optional — semantic memory MCP server | Not supported | Gap |
+| **skill-tree** | Optional — per-role skill loadouts | Not supported | Gap |
+| **agentic-mesh** | Optional — P2P encrypted transport | Not supported | Gap |
+| **git-cascade** | Not used | Core dependency — workspace isolation, merge queue | Unique to macro-agent |
+| **acp-factory** | Not used | Core dependency — spawns Claude Code via ACP | Unique to macro-agent |
+
+---
+
+## 8. What's Unique to macro-agent
+
+Features that cc-swarm does not have:
+
+1. **MAP Server (inbound connections)** — Accepts MAP client connections, enabling TUI interaction via ACP-over-MAP bridge. cc-swarm is client-only.
+
+2. **ACP-over-MAP Bridge** (`src/map/acp-bridge.ts`) — MAP clients can send ACP envelopes to local agents. In-memory stream pairs wire to `createMacroAgent()`. Enables remote agent interaction through MAP protocol.
+
+3. **Workspace Isolation** — Each worker agent gets an isolated git worktree. Changes are merged via a configurable integration strategy (queue, trunk, optimistic). Prevents agent conflicts.
+
+4. **Merge Queue** — SQLite-backed queue for serialized integration of worker changes.
+
+5. **Control Socket** — NDJSON-over-UNIX-socket RPC for lifecycle operations from MCP subprocesses. Separates control plane from data plane.
+
+6. **Trigger System** — Pluggable routing strategies (direct, role, head, custom), WakeManager with inject/interrupt/prompt fallback chain, CronService, WebhookHandler. Enables event-driven agent activation.
+
+7. **Full ACP Agent** (`src/acp/macro-agent.ts`) — Complete Agent Client Protocol implementation with session management, streaming updates, permission request/response, and 11+ extension methods.
+
+8. **Inbound Coordination** (`src/map/coordination-handler.ts`) — Handles 5 `x-openhive/*` notification types: task assignment, task status, context sharing, messaging, workspace execution. Enables hub-directed orchestration.
+
+9. **Pull-Mode Task Claiming** — Agents can claim tasks from a shared pool via `claim_task`/`unclaim_task`/`list_claimable_tasks` MCP tools (gated by `task.claim` capability).
+
+10. **Agent Detection** — Discovers installed CLI coding agents (Claude Code, Codex, Goose) by scanning PATH, extracting version info, building headless invocation commands.
+
+11. **Federation** — agent-inbox supports cross-instance communication via federation config with peer routing and trust policies.
+
+12. **cc-swarm Hooks Integration** (`src/map/cc-swarm-hooks.ts`) — Can inject cc-swarm's shell hooks (SessionStart, Stop, SubagentStart, SubagentStop, PostToolUse, UserPromptSubmit) into spawned agents via acp-factory's programmatic hooks API. Also supports direct sidecar spawning via `startCCSwarmSidecar()`.
+
+13. **Health Check Escalation** — 30-second health check loop detects stale MCP subprocesses (60s threshold) and notifies parent agents via inbox with `STALE_AGENT` event.
+
+---
+
+## 9. Known Gaps
+
+| Gap | Severity | Details |
+|---|---|---|
+| **Transcript content serving** | Medium | `trajectory/content.request` handler returns stub response: "Full transcript serving not yet implemented". OpenHive's 5-tier resolution will fall through to tier 3/4/5. |
+| **sessionlog native integration** | Low | No direct sessionlog integration. Relies on cc-swarm-hooks to inject sessionlog hooks into spawned agents. If cc-swarm is not installed, no session-level trajectory data beyond what the ACP prompt handler emits. |
+| **MeshPeer transport** | Low | No agentic-mesh support. All MAP communication is direct WebSocket. |
+| **minimem (agent memory)** | Low | No semantic memory integration. Agents have no persistent memory across sessions. |
+| **skill-tree** | Low | No per-role skill loadout compilation. |
+| **Task event type names** | Cosmetic | macro-agent emits `task.created`/`task.status`; cc-swarm emits `bridge-task-created`/`bridge-task-status`. Payload structures are compatible but type discriminants differ. OpenHive may need to handle both. |
+| **Peer extensions** | Low | `_macro/listPeers`, `_macro/getPeer`, `_macro/sendToPeer`, etc. are declared but stubbed — return `NO_PEER_MANAGER` error. |
+| **MAP agent state updates** | Low | The ACP prompt handler updates local MAP server agent state (idle/busy) but upstream sidecar state is not directly updated (commented code in `src/acp/macro-agent.ts` lines 510-517). |
+
+---
+
+## 10. Configuration
+
+### boot-v2 Config (`BootV2Config`)
+
+```typescript
+const system = await bootV2({
+  // Core
+  cwd: "/path/to/project",
+  baseDir: "~/.macro-agent",
+  defaultPermissionMode: "auto-approve",
+  defaultAgentType: "claude-code",
+
+  // Messaging
+  inbox: { socketPath: "/path/to/inbox.sock", sqlitePath: "/path/to/inbox.db" },
+
+  // Tasks
+  tasks: { /* opentasks client config */ },
+
+  // Trigger system
+  trigger: { enableHeartbeat: true, heartbeatIntervalMs: 5000 },
+
+  // Federation
+  federation: {
+    systemId: "my-system",
+    peers: [{ systemId: "peer-1", url: "ws://peer:3000" }],
+    trust: { allowedSystems: ["peer-1"] },
+  },
+
+  // REST API (optional)
+  api: { enabled: true, port: 3001, host: "127.0.0.1" },
+
+  // ACP WebSocket server (optional)
+  acp: { enabled: true, port: 3000, host: "127.0.0.1", path: "/acp" },
+
+  // MAP server — inbound connections (optional)
+  mapServer: { enabled: true, port: 3002, host: "127.0.0.1", path: "/map", name: "macro-agent" },
+
+  // MAP sidecar — outbound hub connection (optional)
+  map: {
+    enabled: true,
+    server: "ws://openhive-hub:3000",
+    token: "api-key-or-preauth-key",
+    scope: "swarm:my-project",
+    systemId: "macro-agent",
+    credential: "opaque-credential-for-verified-auth",
+    agentName: "my-project-sidecar",
+    trajectorySyncLevel: "metrics",  // "off" | "lifecycle" | "metrics" | "full"
+    reconnectIntervalMs: 60000,
+    reconnection: {
+      enabled: true,
+      maxRetries: 10,
+      baseDelayMs: 1000,
+      maxDelayMs: 30000,
+    },
+  },
+});
+```
+
+### OpenSwarm Adapter Config
+
+```json
+{
+  "adapter": { "id": "macro-agent" },
+  "port": 3000,
+  "host": "localhost"
+}
+```
+
+Adapter-specific options (via `AdapterConfig.options`):
+- `baseDir` — macro-agent data directory
+- `defaultPermissionMode` — "auto-approve" (default)
+- `apiPort` — Enable REST API on separate port
+- `inbox`, `tasks`, `trigger` — Pass through to bootV2
+- `federation` — Cross-instance config
+- `map` — MAP sidecar config (auto-populated from bootstrap token)
+
+### Bootstrap Token (auto-wiring)
+
+Set `OPENSWARM_BOOTSTRAP_TOKEN` (base64 JSON):
+```json
+{
+  "version": 1,
+  "swarm_name": "my-swarm",
+  "openhive_url": "http://hub:3000",
+  "preauth_key": "preauthkey_abc123",
+  "adapter": "macro-agent",
+  "adapter_config": {},
+  "expires_at": "2026-05-01T00:00:00Z"
+}
+```
+
+The config loader auto-populates `adapter_config.map` from `openhive_url` + `preauth_key`, so the spawned swarm connects back to the hub automatically.
+
+### cc-swarm Hooks Integration
+
+To enable cc-swarm hooks on spawned agents (for sessionlog + trajectory):
+
+1. Ensure cc-swarm is installed (plugin cache, marketplace, or references directory)
+2. Enable the MAP server: `mapServer: { enabled: true }`
+3. The `AgentManagerV2` calls `buildCCSwarmHooks(mapServerUrl, agentScope)` and passes hooks to acp-factory
+4. Alternatively, call `startCCSwarmSidecar(mapServerUrl, scope, sessionId, cwd)` for direct sidecar spawning
+
+cc-swarm is discovered at:
+- `~/.claude/plugins/cache/claude-code-swarm/claude-code-swarm/<version>/`
+- `~/.claude/plugins/marketplaces/claude-code-swarm/`
+- `../../references/claude-code-swarm/` (development)