CALC: Cross-Agent Live Collaboration

# CALC: Cross-Agent Live Collaboration
## Architecture Document v1.0
> Date: 2026-03-09 | Author: Mohamed Diomande | Status: Production

---

1. System Overview

CALC connects three AI coding agents from three different companies into a unified collaboration system. The agents share context, route tasks by model strength, and communicate through five transport layers.

The problem it solves is simple: when multiple AI agents run on the same machine, they're blind to each other. Each one starts fresh, unaware of what others have done, are doing, or need. The old approach (the Cortex Orchestrator auto-injector) solved half of this by detecting idle panes and pasting tasks into them. But it was unidirectional, one-shot, and model-agnostic. CALC replaces that with bidirectional, persistent, model-aware collaboration.

The discovery that triggered CALC: Codex answered a question about the pane orchestrator without being told anything about it. It synthesized the answer from shared state files that its bootstrap digest reads at session start. Gemini, lacking a bootstrap digest, could not answer the same question. The gap between "connected" and "disconnected" was visible in a single prompt.

---

2. Component Diagram

+-----------------------------------------------------------------------------------+
|  Mac1 (M2 MacBook Pro)                                                            |
|                                                                                    |
|  +------------------+    +------------------+    +------------------+              |
|  |  Claude Code     |    |  Codex CLI       |    |  Gemini CLI      |              |
|  |  Opus 4.6        |    |  GPT-5.4         |    |  Gemini 3 Pro    |              |
|  |  /dev/ttys003-12 |    |  /dev/ttys001    |    |  /dev/ttys009    |              |
|  |  COMMANDER        |    |  ANALYST          |    |  REVIEWER         |              |
|  +--------+---------+    +--------+---------+    +--------+---------+              |
|           |                       |                       |                        |
|  +--------+-----------------------+-----------------------+--------+               |
|  |                    Shared Infrastructure                         |               |
|  |                                                                 |               |
|  |  [L5] Graph Kernel -------> RAG++ :8000 + GK :8001 (semantic)   |               |
|  |  [L4] Pane Awareness -----> pane_registry.json (read-only)      |               |
|  |  [L3] Bridge File --------> orchestrator_bridge.json (R/W)      |               |
|  |  [L2] NUMU Bus ------------> ws://localhost:7890 (pub/sub)       |               |
|  |  [L1] Mesh Event Bus -----> POST cloud-vm:8600 (fire+forget)    |               |
|  +-----------------------------------------------------------------+               |
|                                                                                    |
|  +----------------------------+    +----------------------------+                  |
|  |  Cortex Orchestrator       |    |  Bootstrap Digests         |                  |
|  |  AppleScript pane sensing  |    |  .codex/bootstrap-digest.ts|                  |
|  |  Idle detection + inject   |    |  .gemini/bootstrap-digest.sh                  |
|  +----------------------------+    +----------------------------+                  |
+-----------------------------------------------------------------------------------+
           |
           | HTTP POST / WebSocket
           v
+-----------------------------------------------------------------------------------+
|  cloud-vm ([ip])                                                          |
|                                                                                    |
|  +------------------+  +------------------+  +------------------+                  |
|  | Mesh Event Bus   |  | Supabase         |  | Prometheus       |                  |
|  | :8600            |  | mesh_events tbl  |  | :9090            |                  |
|  +------------------+  +------------------+  +------------------+                  |
|                                                                                    |
|  +------------------+  +------------------+  +------------------+                  |
|  | Dashboard API    |  | Nexus Portal     |  | Grafana          |                  |
|  | :8421            |  | :3001            |  | :3000            |                  |
|  +------------------+  +------------------+  +------------------+                  |
+-----------------------------------------------------------------------------------+

---

3. Agent Specifications

3.1 Claude Code (COMMANDER)

Responsibilities: orchestration, architecture decisions, iOS builds and Xcode operations, infrastructure management, Docker and VM operations, task dispatch to other agents.

Context injection: SessionStart hooks read pane_registry.json, cortex event log, memory files, and bridge state. Runs automatically on every session start.

3.2 Codex CLI (ANALYST)

Responsibilities: structured output and data analysis, CRM and pipeline work, mathematical reasoning, bootstrap operations for other agents.

Context injection: openclaw-agent.md rules trigger reading 15 context files in order, then bootstrap-digest.ts generates grounding-context.md from pane registry, cortex, NUMU state, active tasks, bridge file, Nexus pages, and mesh events.

3.3 Gemini CLI (REVIEWER)

Responsibilities: large-context code review (>100K tokens), Evo3 Stage 2 compound synthesis (holding all 6 Stage 1 paths), cross-project dependency analysis, creative content.

Context injection: GEMINI.md instructs running bootstrap-digest.sh at session start, which reads pane registry, active tasks, bridge file, cortex log, and Codex's digest, outputting to [home-path]

---

4. Transport Layer Specifications

Layer 1: Mesh Event Bus

Event schema:

{
  "type": "string (e.g. agent.task_complete, agent.discovery)",
  "event": "string (alias of type)",
  "source": "claude-code | codex | gemini-cli",
  "machine": "mac1 | mac2 | mac3 | mac4 | mac5 | cloud-vm",
  "timestamp": "ISO-8601",
  "ts": "number (unix epoch seconds)",
  "session_id": "string (agent-specific identifier)",
  "pane_id": "string (/dev/ttysNNN) or null",
  "cwd": "string (working directory)",
  "payload": "object (arbitrary)"
}

Codex publisher: `[home-path]` (includes 5-second per-agent throttle window, dry-run mode, CLI interface).

Gemini publisher: `[home-path]` (shell script, validates JSON payload via jq, same schema).

Layer 2: NUMU Bus

Topic patterns:
| Pattern | Purpose |
|---------|---------|
| `evo3.*` | Evolution World events |
| `pane.*` | Pane lifecycle events |
| `hef.*` | HEF orchestrator events |
| `mesh.*` | Multi-machine mesh events |
| `gsd.*` | Get Stuff Done workflow events |
| `calc.context_share` | Agent shares context with others |
| `calc.task_handoff` | Agent routes task to better-suited agent |
| `calc.discovery` | Cross-cutting insight broadcast |
| `calc.request` | Direct request to specific agent |
| `calc.ack` | Receipt acknowledgment |

Codex client: `[home-path]` (WebSocket with auto-reconnect, topic pattern matching, state file output, pending action queue).

Layer 3: Orchestrator Bridge

Schema:

{
  "version": "2.0.0",
  "last_updated": "ISO-8601",
  "last_writer": "claude-code | codex | gemini-cli",
  "active_evolution": "string | null",
  "task_queue": [
    {
      "id": "uuid",
      "assigned_to": "codex | gemini-cli | claude-code",
      "status": "pending | in_progress | complete",
      "priority": 1,
      "prompt": "Full task description",
      "output_file": "/path/to/write/results",
      "created_by": "source agent identifier",
      "created_at": "ISO-8601",
      "completed_at": "ISO-8601 | null"
    }
  ],
  "account_state": {
    "mac1_account": { "email": "...", "status": "active | available" },
    "mac5_account": { "email": "...", "status": "active | available" },
    "vm_account": { "email": "...", "status": "active | available" }
  },
  "discoveries": [
    {
      "content": "Description of finding",
      "source": "claude-code | codex | gemini-cli",
      "timestamp": "ISO-8601"
    }
  ],
  "messages": [
    {
      "from": "source agent",
      "to": "target agent",
      "content": "Message text",
      "timestamp": "ISO-8601"
    }
  ]
}

Layer 4: Pane Awareness

Data per pane:

{
  "tty": "/dev/ttysNNN",
  "pid": 12345,
  "session_id": "uuid",
  "project": "project-name",
  "cwd": "/path/to/project",
  "last_prompt": "truncated prompt text",
  "status": "active | inactive",
  "activity_state": "SESSION_ENDED | CONTEXT_EXHAUSTED | STUCK_ON_ERROR | TASK_COMPLETE | TRULY_IDLE | WORKING",
  "quadrant": "top-left | top-right | bottom-left | bottom-right",
  "last_active": "ISO-8601",
  "agent": "claude | codex | gemini",
  "runtime": "claude-code | codex-cli | gemini-cli"
}

Layer 5: Graph Kernel (Semantic Context)

Query schema:

{
  "query": "natural language context query",
  "k_rag": 5,
  "max_tokens": 300,
  "include_graph": true
}

Response schema:

{
  "related_turns": [
    {
      "score": 0.73,
      "preview": "truncated turn content",
      "source": "session or pane identifier"
    }
  ],
  "sources": ["rag++", "pgvector", "gk"]
}

How each agent uses L5:
- Claude Code: `session_start_hook.py` queries RAG++ gateway at :8000 with `include_graph: true` during session bootstrap. Results injected as "RECENT RELEVANT CONTEXT (via RAG++)" in session context recovery.
- Codex: `bootstrap-digest.ts` calls `queryGraphKernel()` which checks GK health at :8001, then queries RAG++ at :8000. Results rendered in "Graph Kernel (Semantic Context)" section of digest.
- Gemini: `bootstrap-digest.sh` curls RAG++ at :8000. Results rendered in "Graph Kernel (Semantic Context)" section with scores and previews.
- Evolution World: `daemon.py` _sense() phase queries RAG++ for "cross-project connections and recent mutations". Semantic hits feed into L2 selection and mutation planning.

The key insight: GK at :8001 is a provenance engine (slicing, policy, token verification). RAG++ at :8000 is the query gateway that integrates pgvector semantic search with GK's graph context. All agents query :8000, not :8001 directly.

---

5. Bootstrap Pipeline

5.1 Claude Code

Session Start
  -> [Hook] session_start_hook.py
       reads: pane_registry.json, cortex event_log.jsonl, memory/*.md
  -> [Hook] session_sync.py
       posts: mesh event (type: session.start) to :8600
  -> [Hook] compact_bridge.py
       reads: orchestrator_bridge.json
  -> [Hook] discord-session (HTTP)
       posts: session start notification to Discord
  = Claude has full mesh awareness

5.2 Codex

Session Start
  -> [Rules] openclaw-agent.md (reads 15 files in order)
       1. PARITY.md           9. MEMORY.md (today + yesterday)
       2. CLAUDE.md           10. cloud.md
       3. AGENTS.md           11. MEMORY.md (main)
       4. SOUL.md             12. SESSION_STATE.md
       5. USER.md             13. grounding-context.md
       6. ARCHITECTURE.md     14. hook-output-digest.md
       7. CODEX.md            15. nexus-awareness.md
       8. Auto-memory MEMORY.md
  -> [Script] bun bootstrap-digest.ts --quiet
       reads: pane_registry, cortex log, NUMU state, active-tasks.md,
              bridge file, Nexus pages, dashboard probes, mesh events,
              evo3 outputs, memory files, failure museum
       writes: [home-path]
       writes: [home-path]
  -> [Script] bun event-publisher.ts session.start
       posts: mesh event to :8600
  = Codex has full mesh awareness

5.3 Gemini CLI

Session Start
  -> [Instructions] GEMINI.md
       role: REVIEWER, bridge protocol, available context paths
  -> [Script] bash [home-path]
       reads: pane_registry.json, active-tasks.md, bridge file,
              cortex event_log.jsonl (tail 20), Codex grounding-context.md
       writes: [home-path]
  -> [Heartbeat] gemini_heartbeat.sh (already running as background process)
       posts: Graph Kernel heartbeat every 30s
  = Gemini has full mesh awareness (1M context advantage)

---

6. Communication Patterns

Pattern 1: Passive Context Share

One agent finishes work, publishes an event. Others pick it up on their next bootstrap refresh. No coordination required.

Agent A completes task
  -> POST mesh event bus (type: agent.task_complete, payload: summary)
  -> Event persists in Supabase mesh_events
  -> Agent B runs bootstrap-digest on next session
  -> Agent B sees the event in its grounding context

Use when: task results might be useful to others but nobody is waiting for them.

Pattern 2: Direct Request

One agent needs specific work from another agent. Writes a task to the bridge file.

Agent A needs large-context review
  -> Writes to bridge task_queue: { assigned_to: "gemini-cli", prompt: "...", output_file: "/tmp/review.md" }
  -> Agent B (Gemini) polls bridge, finds pending task
  -> Agent B processes task, writes output to specified path
  -> Agent B updates bridge: status = "complete"
  -> Agent A reads output file

Use when: a task requires a specific agent's strengths (context window, structured output, etc.).

Pattern 3: Live Injection

Urgent, synchronous communication. One agent pastes a prompt directly into another agent's terminal.

Agent A has urgent context
  -> echo "prompt" | pbcopy
  -> AppleScript: find window with target TTY
  -> AppleScript: keystroke "v" using command down
  -> AppleScript: key code 36 (Enter)
  -> Target agent receives as user input
  -> Target agent processes immediately

AppleScript template:

tell application "Terminal"
    repeat with w in windows
        try
            if tty of (selected tab of w) is "/dev/ttys001" then
                set frontmost of w to true
                delay 0.3
                tell application "System Events"
                    keystroke "v" using command down
                end tell
                delay 0.3
                tell application "System Events"
                    key code 36
                end tell
            end if
        end try
    end repeat
end tell

Use when: time-sensitive, agent needs to act immediately, bridge polling is too slow.

Pattern 4: Discovery Broadcast

Cross-cutting insight that affects multiple projects or agents. Published to both NUMU and bridge.

Agent A finds dependency conflict
  -> NUMU publish: topic "calc.discovery", payload with finding
  -> Bridge: discoveries.push({ content, source, timestamp })
  -> All agents see on next NUMU receive or bridge read

Use when: security finding, architectural conflict, shared dependency issue, or any insight that spans project boundaries.

---

7. Agent Routing Matrix

---

8. Security Model

Network Boundaries

Access Controls

All three agents run with maximum filesystem permissions. This is intentional for a single-user development machine. The trust boundary is the machine itself.

Sensitive data isolation: API keys and credentials stay in each agent's own config files ([home-path] [home-path] [home-path] settings). These are never transmitted via any transport layer.

The bridge file contains no secrets. Event payloads contain no secrets. NUMU messages contain no secrets.

Threat Model

The primary risk is not external attack (Tailscale handles that) but agent misbehavior: one agent overwriting another's work, conflicting edits to the same file, or runaway task dispatch. CALC mitigates this through:

1. Pane awareness is read-only. No agent can modify the registry.
2. Bridge file uses last-writer-wins with timestamps for conflict detection.
3. Mesh event bus is append-only. Events cannot be modified or deleted.
4. The Cortex Orchestrator's bounded divergence invariant caps injection rate.

---

9. Failure Modes and Recovery

Agent Crash

If any agent process dies, the others continue unaffected. The crashed agent's last state remains in the bridge file and pane registry. On restart, the agent's bootstrap digest reads current state and resumes.

Recovery: restart the agent. No special procedure needed.

Mesh Event Bus Down

Events from all agents fail to POST. Each agent handles this gracefully (Codex's event-publisher.ts catches fetch errors, Gemini's event-publisher.sh checks curl exit code). Agents continue working locally.

Recovery: `ssh cloud-vm 'sudo systemctl restart mesh-event-bus'`. Events during downtime are lost (not queued).

NUMU Bus Down

Real-time pub/sub stops. Codex's numu-client.ts has auto-reconnect with attempt counting. No data loss since NUMU is ephemeral.

Recovery: `launchctl kickstart gui/$(id -u)/com.openclaw.numu-daemon`

Bridge File Corruption

If orchestrator_bridge.json becomes invalid JSON, all agents fall back to defaults. Codex's readJsonFile helper returns a typed fallback on parse error.

Recovery: overwrite with a valid empty bridge: `echo '{"version":"2.0.0","task_queue":[],"discoveries":[],"messages":[]}' > [home-path]`

Bootstrap Digest Failure

If bootstrap-digest.ts or bootstrap-digest.sh fails, the agent starts without mesh awareness but otherwise functions normally. The digest scripts have try/catch on every file read.

Recovery: run manually to see error output. Common cause: missing pane_registry.json (orchestrator not running).

Pane Awareness Stale

If the Cortex Orchestrator stops running, pane_registry.json becomes stale. Agents still read it but data reflects old state.

Recovery: `launchctl kickstart gui/$(id -u)/com.openclaw.pane-orchestrator`

---

10. Comparison: CALC vs Auto-Injector

The auto-injector remains useful as Pattern 3 (Live Injection) within CALC. It's the synchronous, urgent communication channel. But it's no longer the only channel.

---

11. Integration Parity Checklist

---

12. Future Enhancements

Phase 2: Conflict Resolution. When two agents modify the same file, detect the conflict via PostToolUse hooks and route resolution to the agent with more context about the file.

Phase 3: NUMU Client for Gemini. Build a Node.js WebSocket client that Gemini can invoke for real-time NUMU subscription. Close the last pub/sub gap.

Phase 4: Cognitive Routing. Analyze prompt content to automatically determine which agent should handle it. Use the domain classification regex from mesh_coordinator.py as a starting point.

Phase 5: Cross-Machine CALC. Extend to Mac2, Mac3, Mac4, Mac5 via Supabase Realtime subscriptions on the bridge file. Each machine runs its own agents with the same bootstrap pattern.