docs(v2): cross-mount invariants + diagrams; inline a2a routing
- session-manager.ts: shrink the cross-mount invariant header from 31
lines to 12, keeping each invariant's cause and consequence inline.
- agent-runner/db/connection.ts: parallel cross-mount comment for the
container-side reader (inbound.db must be journal_mode=DELETE).
- agent-runner/db/messages-out.ts: document that even/odd seq parity
is load-bearing — seq is the agent-facing message ID returned by
send_message and consumed by edit_message / add_reaction, looked
up across both tables.
- v2-checklist.md: record the cross-mount invariants and seq parity
under Core Architecture so future "simplifications" don't regress
them.
- scripts/sanity-live-poll.ts: empirical validation harness for the
three cross-mount invariants — flips each one and observes silent
message loss / corruption.
- delivery.ts: inline routeAgentMessage at its single callsite (-17
net lines). The wrapper added more boilerplate than it factored.
- docs/v2-architecture-diagram.{md,html}: rendered Mermaid diagrams
of the v2 system, message flow, named destinations, entity model,
and the two-DB split.
- channels/adapter.ts, chat-sdk-bridge.ts, credentials.ts,
db/sessions.ts, db/db-v2.test.ts: prettier format pass.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
gavrielc
200
docs/v2-architecture-diagram.md
Normal file
200
docs/v2-architecture-diagram.md
Normal file
@@ -0,0 +1,200 @@
|
||||
# NanoClaw v2 Architecture Diagram
|
||||
|
||||
## System Overview
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
subgraph Platforms["Messaging Platforms"]
|
||||
P1[Discord]
|
||||
P2[Telegram]
|
||||
P3[Slack]
|
||||
P4[GitHub / Linear]
|
||||
P5[WhatsApp / iMessage / Teams / GChat / Matrix / Webex / Email]
|
||||
end
|
||||
|
||||
subgraph Host["Host Process (Node)"]
|
||||
direction TB
|
||||
Bridge["Chat SDK Bridge<br/>(src/channels/chat-sdk-bridge.ts)"]
|
||||
Router["Router<br/>(src/router.ts)<br/>platformId + threadId -> messaging_group -> agent_group -> session"]
|
||||
SessMgr["Session Manager<br/>(src/session-manager.ts)<br/>creates inbound.db + outbound.db"]
|
||||
Runner["Container Runner<br/>(src/container-runner.ts)<br/>OneCLI ensureAgent + spawn"]
|
||||
Delivery["Delivery Poller<br/>(src/delivery.ts)<br/>1s active / 60s sweep"]
|
||||
Sweep["Host Sweep<br/>(src/host-sweep.ts)<br/>heartbeat, retry, recurrence"]
|
||||
Central[("Central DB<br/>data/v2.db<br/>agent_groups<br/>messaging_groups<br/>messaging_group_agents<br/>sessions<br/>pending_approvals")]
|
||||
end
|
||||
|
||||
subgraph OneCLI["OneCLI Gateway (0.3.1)"]
|
||||
Vault["Agent Vault<br/>secrets + OAuth"]
|
||||
Approvals["configureManualApproval<br/>-> pending_approvals"]
|
||||
SecretsFacade["src/onecli-secrets.ts<br/>credential collection"]
|
||||
end
|
||||
|
||||
subgraph Session["Per-Session Container (Docker / Apple Container)"]
|
||||
direction TB
|
||||
PollLoop["Poll Loop<br/>(container/agent-runner)"]
|
||||
Provider["Claude Agent SDK<br/>(providers: claude, mock, todo: codex/opencode)"]
|
||||
MCP["MCP Tools<br/>send_message, send_file, edit_message,<br/>add_reaction, send_card, ask_user_question,<br/>schedule_task, create_agent,<br/>install_packages, add_mcp_server, request_rebuild,<br/>trigger_credential_collection"]
|
||||
Skills["Container Skills<br/>(container/skills/)"]
|
||||
InDB[("inbound.db<br/>host writes<br/>even seq<br/>messages_in<br/>destinations<br/>processing_ack")]
|
||||
OutDB[("outbound.db<br/>container writes<br/>odd seq<br/>messages_out<br/>heartbeat file")]
|
||||
end
|
||||
|
||||
subgraph Groups["Agent Group Filesystem (groups/*)"]
|
||||
Folder["CLAUDE.md<br/>memory<br/>per-group skills<br/>container_config"]
|
||||
end
|
||||
|
||||
P1 & P2 & P3 & P4 & P5 --> Bridge
|
||||
Bridge --> Router
|
||||
Router --> Central
|
||||
Router --> SessMgr
|
||||
SessMgr --> InDB
|
||||
SessMgr --> Runner
|
||||
Runner --> OneCLI
|
||||
Runner --> PollLoop
|
||||
PollLoop --> InDB
|
||||
PollLoop --> Provider
|
||||
Provider --> MCP
|
||||
Provider --> Skills
|
||||
MCP --> OutDB
|
||||
OutDB --> Delivery
|
||||
Delivery --> Central
|
||||
Delivery --> Bridge
|
||||
Bridge --> P1 & P2 & P3 & P4 & P5
|
||||
Sweep --> InDB
|
||||
Sweep --> OutDB
|
||||
Sweep --> Central
|
||||
Runner -.mounts.-> Folder
|
||||
MCP -.approval.-> Approvals
|
||||
Approvals --> Central
|
||||
MCP -.credential req.-> SecretsFacade
|
||||
SecretsFacade --> Vault
|
||||
Provider -.API calls.-> Vault
|
||||
```
|
||||
|
||||
## Message Flow (inbound -> agent -> outbound)
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant P as Platform (e.g. Telegram)
|
||||
participant B as Chat SDK Bridge
|
||||
participant R as Router
|
||||
participant SM as Session Manager
|
||||
participant IDB as inbound.db
|
||||
participant C as Container (agent-runner)
|
||||
participant ODB as outbound.db
|
||||
participant D as Delivery Poller
|
||||
|
||||
P->>B: new message
|
||||
B->>R: routeInbound(platformId, threadId, msg)
|
||||
R->>R: resolve messaging_group -> agent_group -> session<br/>(agent-shared | shared | per-thread)
|
||||
R->>SM: ensure session + DBs exist
|
||||
R->>IDB: INSERT messages_in (even seq)
|
||||
R->>C: wake container (docker run / already running)
|
||||
C->>IDB: poll messages_in
|
||||
C->>C: format xml, stream to Claude SDK
|
||||
C->>ODB: INSERT messages_out (odd seq)<br/>parse <message to="name"> blocks
|
||||
D->>ODB: 1s poll (active) / 60s (sweep)
|
||||
D->>D: hasDestination() re-validate
|
||||
D->>B: deliver via adapter
|
||||
B->>P: send message / edit / react / file / card
|
||||
```
|
||||
|
||||
## Named Destinations + Agent-to-Agent
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph AgentA["Agent Group A (main)"]
|
||||
A_out["output:<br/><message to='slack'>...</message><br/><message to='browser-agent'>...</message><br/><internal>scratchpad</internal>"]
|
||||
end
|
||||
|
||||
subgraph Dests["inbound.db.destinations (per agent)"]
|
||||
D1["slack -> messaging_group 42"]
|
||||
D2["browser-agent -> agent_group 7<br/>(bidirectional row)"]
|
||||
D3["github -> messaging_group 13"]
|
||||
end
|
||||
|
||||
subgraph AgentB["Agent Group B (browser sub-agent)"]
|
||||
B_session["own inbound.db / outbound.db<br/>inherited destination back to A"]
|
||||
end
|
||||
|
||||
Slack[Slack channel]
|
||||
GitHub[GitHub PR thread]
|
||||
|
||||
A_out -->|parse + lookup| Dests
|
||||
D1 -->|deliver| Slack
|
||||
D2 -->|write to B's inbound.db| B_session
|
||||
D3 -->|deliver| GitHub
|
||||
B_session -.reply via 'parent'.-> Dests
|
||||
```
|
||||
|
||||
## Entity Model + Isolation Levels
|
||||
|
||||
```mermaid
|
||||
erDiagram
|
||||
agent_groups ||--o{ messaging_group_agents : wired
|
||||
messaging_groups ||--o{ messaging_group_agents : wired
|
||||
agent_groups ||--o{ sessions : runs
|
||||
messaging_groups ||--o{ sessions : context
|
||||
agent_groups ||--o{ agent_destinations : owns
|
||||
agent_groups ||--o{ pending_approvals : requests
|
||||
|
||||
agent_groups {
|
||||
int id
|
||||
string name
|
||||
string folder
|
||||
bool is_admin
|
||||
string agent_provider
|
||||
json container_config
|
||||
}
|
||||
messaging_groups {
|
||||
int id
|
||||
string channel_type
|
||||
string platform_id
|
||||
string name
|
||||
bool is_group
|
||||
string admin_user_id
|
||||
}
|
||||
messaging_group_agents {
|
||||
int messaging_group_id
|
||||
int agent_group_id
|
||||
string session_mode "agent-shared | shared | per-thread"
|
||||
json trigger_rules
|
||||
int priority
|
||||
}
|
||||
sessions {
|
||||
int id
|
||||
int agent_group_id
|
||||
int messaging_group_id
|
||||
string sdk_session_id
|
||||
string status
|
||||
}
|
||||
```
|
||||
|
||||
### Isolation Level Cheatsheet
|
||||
|
||||
| Level | `session_mode` | What's shared | Example |
|
||||
|---|---|---|---|
|
||||
| 1. Shared session | `agent-shared` | Workspace + memory + conversation | Slack + GitHub webhooks in one thread |
|
||||
| 2. Same agent, separate sessions | `shared` / `per-thread` | Workspace + memory only | One agent across 3 Telegram chats |
|
||||
| 3. Separate agent groups | (different `agent_group_id`) | Nothing | Personal vs work channels |
|
||||
|
||||
## Two-DB Split (why)
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
subgraph Mount["/workspace (volume mounted into container)"]
|
||||
In[("inbound.db")]
|
||||
Out[("outbound.db")]
|
||||
HB["/.heartbeat (file touch)"]
|
||||
end
|
||||
|
||||
Host[Host process] -->|"writes only<br/>(even seq)"| In
|
||||
Host -->|reads| Out
|
||||
Container[agent-runner] -->|reads| In
|
||||
Container -->|"writes only<br/>(odd seq)"| Out
|
||||
Container -->|touch every poll| HB
|
||||
HostSweep[Host sweep] -->|stat mtime| HB
|
||||
HostSweep -->|reads processing_ack| In
|
||||
|
||||
note1["Each file has exactly ONE writer.<br/>Eliminates SQLite cross-process write contention.<br/>Collision-free seq numbering."]
|
||||
```
|
||||
Reference in New Issue
Block a user