bootstrap/docs/DEVELOPER-GUIDE/orchestrator-matrix/macp-phase2a.md

MACP Phase 2A

MACP Phase 2A adds the repo-local event bridge that makes orchestrator lifecycle events consumable by external systems.

What Changed

1. tools/orchestrator-matrix/events/event_watcher.py polls .mosaic/orchestrator/events.ndjson, parses appended NDJSON events, dispatches callbacks, and persists a byte-offset cursor in .mosaic/orchestrator/event_cursor.json.
2. tools/orchestrator-matrix/events/webhook_adapter.py forwards selected MACP events to a configured webhook endpoint with bounded retries and optional bearer auth.
3. tools/orchestrator-matrix/events/discord_formatter.py renders task lifecycle events into concise Discord-friendly status lines.
4. bin/mosaic-macp adds watch mode for one-shot or continuous event processing.

Watcher Behavior

1. File watching is polling-based and stdlib-only for portability.
2. The watcher resets its cursor if the events file is truncated.
3. Corrupt JSON lines are logged to stderr and skipped.
4. A trailing partial line is left unread until the newline arrives, preventing half-written events from being consumed.

Webhook Configuration

Configure .mosaic/orchestrator/config.json under macp.webhook:

{
  "macp": {
    "webhook": {
      "enabled": false,
      "url": "http://localhost:8080/macp/events",
      "auth_token": "",
      "timeout_seconds": 10,
      "retry_count": 2,
      "event_filter": ["task.completed", "task.failed", "task.escalated"]
    }
  }
}

CLI

mosaic macp watch --once
mosaic macp watch --webhook

--once performs a single poll and exits. --webhook enables delivery via the configured macp.webhook block while still printing Discord-formatted event lines to stdout.