wangjunxiao/nanoclaw
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(v2): cross-mount invariants + diagrams; inline a2a routing

Browse Source 
- 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
2026-04-12 00:21:12 +03:00
parent c9fa5cdbed
commit 9dda75bb21
13 changed files with 788 additions and 86 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
container/agent-runner/src/db/connection.ts
View File

@@ -8,6 +8,14 @@
* outbound.db — container writes responses + acks here; host opens read-only * outbound.db — container writes responses + acks here; host opens read-only
* *
* Each file has exactly one writer, so no cross-process lock contention. * Each file has exactly one writer, so no cross-process lock contention.
*
* ⚠ Cross-mount visibility: inbound.db MUST be journal_mode=DELETE (set by
* the host when the file is created). WAL's `-shm` is memory-mapped and
* VirtioFS does not propagate mmap coherency from host to guest, so a
* WAL-mode inbound.db would leave this reader frozen on an early snapshot
* and it would silently never see new host messages. See
* src/session-manager.ts for the full set of cross-mount invariants and
* scripts/sanity-live-poll.ts for the empirical validation.
*/ */
import Database from 'better-sqlite3'; import Database from 'better-sqlite3';
import fs from 'fs'; import fs from 'fs';

9
container/agent-runner/src/db/messages-out.ts
View File

@@ -34,8 +34,13 @@ export interface WriteMessageOut {
/** /**
* Write a new outbound message, auto-assigning an odd seq number. * Write a new outbound message, auto-assigning an odd seq number.
* Container uses odd seq (1, 3, 5...), host uses even (2, 4, 6...) — * Container uses odd seq (1, 3, 5...), host uses even (2, 4, 6...).
* this prevents seq collisions without cross-DB coordination. *
* The disjoint namespace is load-bearing, not just collision avoidance:
* seq is the agent-facing message ID returned by send_message and accepted
* by edit_message / add_reaction, and getMessageIdBySeq() below looks up
* by seq across BOTH tables. If inbound and outbound could share a seq,
* the agent's "edit message #5" could resolve to the wrong row.
*/ */
export function writeMessageOut(msg: WriteMessageOut): number { export function writeMessageOut(msg: WriteMessageOut): number {
const outbound = getOutboundDb(); const outbound = getOutboundDb();

406
docs/v2-architecture-diagram.html Normal file
View File

@@ -0,0 +1,406 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width,initial-scale=1" />
<title>NanoClaw v2 Architecture</title>
<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
<style>
:root {
--bg: #0b0d12;
--panel: #141821;
--ink: #e7ecf3;
--muted: #8a94a6;
--accent: #7aa2ff;
--border: #232a38;
}
* { box-sizing: border-box; }
html, body {
margin: 0;
padding: 0;
background: var(--bg);
color: var(--ink);
font-family: -apple-system, BlinkMacSystemFont, "SF Pro Text", "Segoe UI", Helvetica, Arial, sans-serif;
font-size: 15px;
line-height: 1.55;
}
header {
padding: 32px 40px 16px;
border-bottom: 1px solid var(--border);
position: sticky;
top: 0;
background: rgba(11, 13, 18, 0.92);
backdrop-filter: saturate(180%) blur(10px);
z-index: 10;
}
header h1 {
margin: 0 0 4px;
font-size: 22px;
font-weight: 600;
letter-spacing: -0.01em;
}
header .sub {
color: var(--muted);
font-size: 13px;
}
nav {
display: flex;
flex-wrap: wrap;
gap: 8px;
margin-top: 14px;
}
nav a {
color: var(--accent);
text-decoration: none;
font-size: 12px;
padding: 4px 10px;
border: 1px solid var(--border);
border-radius: 999px;
background: var(--panel);
}
nav a:hover { border-color: var(--accent); }
main {
max-width: 1280px;
margin: 0 auto;
padding: 28px 40px 80px;
}
section {
margin-bottom: 48px;
}
section h2 {
font-size: 18px;
font-weight: 600;
margin: 0 0 6px;
letter-spacing: -0.005em;
}
section h2 .num {
color: var(--muted);
font-weight: 500;
margin-right: 8px;
}
section p.desc {
color: var(--muted);
margin: 0 0 16px;
max-width: 900px;
}
.diagram {
background: var(--panel);
border: 1px solid var(--border);
border-radius: 14px;
padding: 24px;
overflow-x: auto;
}
.diagram svg { max-width: 100%; height: auto; display: block; margin: 0 auto; }
table {
width: 100%;
border-collapse: collapse;
margin-top: 14px;
font-size: 13px;
}
th, td {
text-align: left;
padding: 10px 12px;
border-bottom: 1px solid var(--border);
}
th {
color: var(--muted);
font-weight: 500;
text-transform: uppercase;
font-size: 11px;
letter-spacing: 0.04em;
}
code {
font-family: "SF Mono", Menlo, Consolas, monospace;
font-size: 12px;
background: #1c2230;
padding: 1px 6px;
border-radius: 4px;
color: #c8d4ee;
}
footer {
color: var(--muted);
font-size: 12px;
text-align: center;
padding: 20px 0 0;
border-top: 1px solid var(--border);
}
</style>
</head>
<body>
<header>
<h1>NanoClaw v2 Architecture</h1>
<div class="sub">Session-DB messaging model · Chat SDK bridge · OneCLI credential gateway · per-session containers</div>
<nav>
<a href="#overview">1 · Overview</a>
<a href="#flow">2 · Message Flow</a>
<a href="#destinations">3 · Destinations &amp; A2A</a>
<a href="#entities">4 · Entity Model</a>
<a href="#twodb">5 · Two-DB Split</a>
</nav>
</header>
<main>
<section id="overview">
<h2><span class="num">1</span>System Overview</h2>
<p class="desc">
Inbound messages land at the Chat SDK bridge, which hands off to the
router. The router resolves the messaging group → agent group → session
and writes to the session's <code>inbound.db</code>. The container runner
spawns a per-session container (auth via OneCLI), and the agent-runner
polls its DB, calls Claude, and writes responses to <code>outbound.db</code>.
Delivery polls the outbound DB, re-validates destinations, and ships
messages back through the same bridge.
</p>
<div class="diagram">
<pre class="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 → session"]
SessMgr["Session Manager<br/>src/session-manager.ts"]
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"]
Central[("Central DB · data/v2.db<br/>agent_groups · messaging_groups<br/>messaging_group_agents · sessions<br/>pending_approvals")]
end
subgraph OneCLI["OneCLI Gateway (0.3.1)"]
Vault["Agent Vault<br/>secrets + OAuth"]
Approvals["configureManualApproval"]
SecretsFacade["onecli-secrets.ts<br/>credential collection"]
end
subgraph Session["Per-Session Container"]
direction TB
PollLoop["Poll Loop<br/>container/agent-runner"]
Provider["Claude Agent SDK<br/>(codex / opencode planned)"]
MCP["MCP Tools<br/>send_message · send_file · edit_message<br/>send_card · ask_user_question · schedule_task<br/>create_agent · install_packages · add_mcp_server<br/>request_rebuild · trigger_credential_collection"]
InDB[("inbound.db<br/>host writes · even seq")]
OutDB[("outbound.db<br/>container writes · odd seq")]
end
Folder["Agent Group FS<br/>groups/*<br/>CLAUDE.md · memory · skills"]
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
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
</pre>
</div>
</section>
<section id="flow">
<h2><span class="num">2</span>Message Flow</h2>
<p class="desc">
End-to-end path of a single message. The host and container never write
to the same SQLite file — the split between inbound and outbound DBs is
what makes this lock-free under concurrent activity.
</p>
<div class="diagram">
<pre class="mermaid">
sequenceDiagram
participant P as Platform (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 (spawn or signal)
C->>IDB: poll messages_in
C->>C: format xml → Claude SDK stream
C->>ODB: INSERT messages_out (odd seq)<br/>parse &lt;message to='name'&gt; blocks
D->>ODB: 1s active poll / 60s sweep
D->>D: hasDestination() re-validate
D->>B: deliver via adapter
B->>P: send · edit · react · file · card
</pre>
</div>
</section>
<section id="destinations">
<h2><span class="num">3</span>Named Destinations &amp; Agent-to-Agent</h2>
<p class="desc">
Agents address outputs by local name. The host looks up each name against
the agent's destinations table at delivery time — dropping anything
unauthorized. The same table routes agent-to-agent messages to a sibling
agent's <code>inbound.db</code> with bidirectional permission rows.
</p>
<div class="diagram">
<pre class="mermaid">
flowchart LR
subgraph AgentA["Agent Group A (main)"]
A_out["&lt;message to='slack'&gt;...&lt;/message&gt;<br/>&lt;message to='browser-agent'&gt;...&lt;/message&gt;<br/>&lt;internal&gt;scratchpad&lt;/internal&gt;"]
end
subgraph Dests["inbound.db.destinations (per agent)"]
D1["slack → messaging_group 42"]
D2["browser-agent → agent_group 7<br/>(bidirectional)"]
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]
GitHub[GitHub PR]
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
</pre>
</div>
</section>
<section id="entities">
<h2><span class="num">4</span>Entity Model</h2>
<p class="desc">
Messaging groups and agent groups are many-to-many, joined via
<code>messaging_group_agents</code>. The <code>session_mode</code>
column selects one of three isolation levels.
</p>
<div class="diagram">
<pre class="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
json trigger_rules
int priority
}
sessions {
int id
int agent_group_id
int messaging_group_id
string sdk_session_id
string status
}
</pre>
</div>
<table>
<thead>
<tr><th>Level</th><th>session_mode</th><th>Shared</th><th>Example</th></tr>
</thead>
<tbody>
<tr><td>1 · Shared session</td><td><code>agent-shared</code></td><td>Workspace + memory + conversation</td><td>Slack + GitHub webhooks in one thread</td></tr>
<tr><td>2 · Same agent, separate sessions</td><td><code>shared</code> / <code>per-thread</code></td><td>Workspace + memory only</td><td>One agent across 3 Telegram chats</td></tr>
<tr><td>3 · Separate agent groups</td><td>— (different agent_group_id)</td><td>Nothing</td><td>Personal vs work channels</td></tr>
</tbody>
</table>
</section>
<section id="twodb">
<h2><span class="num">5</span>Two-DB Split</h2>
<p class="desc">
Each SQLite file has exactly one writer. The container touches a
heartbeat file instead of <code>UPDATE</code>-ing a liveness row, so host
sweep can detect staleness via <code>stat(mtime)</code> without opening the
DB. Host uses even seq numbers, container uses odd — collision-free.
</p>
<div class="diagram">
<pre class="mermaid">
flowchart LR
subgraph Mount["/workspace (volume mount)"]
In[("inbound.db")]
Out[("outbound.db")]
HB["/.heartbeat (file touch)"]
end
Host[Host process] -->|writes · even seq| In
Host -->|reads| Out
Container[agent-runner] -->|reads| In
Container -->|writes · odd seq| Out
Container -->|touch every poll| HB
HostSweep[Host sweep] -->|stat mtime| HB
HostSweep -->|reads processing_ack| In
</pre>
</div>
</section>
<footer>NanoClaw v2 · branch <code>v2</code> · generated from docs/v2-checklist.md, v2-architecture-draft.md, v2-isolation-model.md, v2-setup-wiring.md</footer>
</main>
<script>
mermaid.initialize({
startOnLoad: true,
theme: "dark",
securityLevel: "loose",
flowchart: { curve: "basis", padding: 18 },
themeVariables: {
background: "#141821",
primaryColor: "#1c2230",
primaryTextColor: "#e7ecf3",
primaryBorderColor: "#3a465e",
lineColor: "#6b7893",
secondaryColor: "#222a3a",
tertiaryColor: "#1a2030",
fontSize: "14px",
},
});
</script>
</body>
</html>

200
docs/v2-architecture-diagram.md Normal file
View 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/>&lt;message to='slack'&gt;...&lt;/message&gt;<br/>&lt;message to='browser-agent'&gt;...&lt;/message&gt;<br/>&lt;internal&gt;scratchpad&lt;/internal&gt;"]
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."]
```

3
docs/v2-checklist.md
View File

@@ -8,6 +8,8 @@ Status: [x] done, [~] partial, [ ] not started
- [x] Session DB replaces IPC (messages_in / messages_out as sole IO) - [x] Session DB replaces IPC (messages_in / messages_out as sole IO)
- [x] Two-DB split: inbound.db (host-owned) + outbound.db (container-owned) — zero cross-process write contention - [x] Two-DB split: inbound.db (host-owned) + outbound.db (container-owned) — zero cross-process write contention
- **Cross-mount invariants (empirically validated, see `scripts/sanity-live-poll.ts`):** (1) `journal_mode=DELETE` on every session DB — WAL's `-shm` is memory-mapped and VirtioFS does not propagate mmap coherency host→guest, so WAL leaves the container's poll loop frozen on an early snapshot with no error; (2) host opens-writes-closes per operation — the close is what invalidates the container's VirtioFS page cache; (3) one writer per file — DELETE-mode with two writers corrupts because journal-unlink doesn't propagate atomically. Each invariant was individually confirmed by flipping it and observing silent message loss or corruption. Do not "simplify" by unifying the DBs, switching to WAL, or keeping a long-lived host connection.
- **Seq parity is load-bearing, not cleanup:** host writes even seqs, container writes odd seqs. The seq is the agent-facing message ID returned by `send_message` and consumed by `edit_message` / `add_reaction`, and `getMessageIdBySeq()` looks up by seq across both tables. Removing parity would let a single ID resolve to the wrong row.
- [x] Central DB (agent groups, messaging groups, sessions, routing) - [x] Central DB (agent groups, messaging groups, sessions, routing)
- [x] Host sweep (stale detection via heartbeat file, retry with backoff, recurrence scheduling) - [x] Host sweep (stale detection via heartbeat file, retry with backoff, recurrence scheduling)
- [x] Active delivery polling (1s for running sessions) - [x] Active delivery polling (1s for running sessions)
@@ -166,6 +168,7 @@ Status: [x] done, [~] partial, [ ] not started
- [~] Credential collection from chat — `trigger_credential_collection` MCP tool; agent researches API config, card → modal → `onecli secrets create` via internal facade (`src/onecli-secrets.ts`); credential value never enters agent context - [~] Credential collection from chat — `trigger_credential_collection` MCP tool; agent researches API config, card → modal → `onecli secrets create` via internal facade (`src/onecli-secrets.ts`); credential value never enters agent context
- [ ] Replace `src/onecli-secrets.ts` shell facade with SDK-native secret management when `@onecli-sh/sdk` adds it - [ ] Replace `src/onecli-secrets.ts` shell facade with SDK-native secret management when `@onecli-sh/sdk` adds it
- [ ] Per-agent-group secret scoping via OneCLI `agentId` (facade passes it today; CLI ignores it until upstream supports) - [ ] Per-agent-group secret scoping via OneCLI `agentId` (facade passes it today; CLI ignores it until upstream supports)
- [ ] **Attach newly created secrets to the calling agent** — `trigger_credential_collection` today runs `onecli secrets create` but leaves the secret unassigned, so the agent that requested the credential still gets zero injections. Fix options: (a) follow-up `onecli agents set-secrets` call in `src/onecli-secrets.ts` after create, (b) set the agent to `mode=all`, or (c) upstream ask — `onecli secrets create --assign-to-agent-ids <id,...>` so it's a one-shot and orphaned secrets are impossible. Prefer (c); use (a) as the interim.
- [ ] **Chat SDK input support beyond Slack (upstream ask)** — today only Slack's Modal surface works for secure input. The platforms themselves support it, but Chat SDK doesn't expose it: - [ ] **Chat SDK input support beyond Slack (upstream ask)** — today only Slack's Modal surface works for secure input. The platforms themselves support it, but Chat SDK doesn't expose it:
- [ ] **Discord** — native modal (`InteractionResponseType.Modal` with `ActionRow([TextInput])`). Map `event.openModal(Modal(...))` to the Discord REST callback. - [ ] **Discord** — native modal (`InteractionResponseType.Modal` with `ActionRow([TextInput])`). Map `event.openModal(Modal(...))` to the Discord REST callback.
- [ ] **Microsoft Teams** — Adaptive Card with `Input.Text`, delivered as a regular message (inline, no modal-trigger needed). - [ ] **Microsoft Teams** — Adaptive Card with `Input.Text`, delivered as a regular message (inline, no modal-trigger needed).

93
scripts/sanity-live-poll.ts Normal file
View File

@@ -0,0 +1,93 @@
/**
* Cross-mount visibility regression test for the two-DB session architecture.
*
* What this catches: any change that breaks host→container write propagation
* across the Docker bind mount. The v2 session DB design relies on three
* invariants working together:
*
* 1. journal_mode = DELETE on every session DB (not WAL)
* 2. Host opens-writes-closes the DB file on every write
* 3. One writer per file (inbound = host, outbound = container)
*
* This script exercises a long-lived container-side reader polling a DB
* while the host writes. If visibility is working, the reader sees each
* write within one poll period. If any of the invariants regresses, the
* reader either sees nothing, sees only the first write, or sees updates
* only after the host closes its connection for good.
*
* Expected passing output (DELETE mode, close-per-write):
* reader sees each seq within ~1s of it being written.
* Anything else is a regression — investigate BEFORE assuming it's flaky.
*
* Keep this around. It ran for ~20 minutes once to map the failure modes
* and it takes about 60s to run — cheap insurance.
*
* Requires: Docker Desktop running, nanoclaw-agent:latest image built.
*/
import { spawn, spawnSync } from "node:child_process";
import { join } from "node:path";
import { mkdirSync, rmSync } from "node:fs";
import Database from "better-sqlite3";
const dbDir = join("/tmp", `nanoclaw-live-${Date.now()}`);
mkdirSync(dbDir, { recursive: true });
spawnSync("chmod", ["777", dbDir]);
const dbPath = join(dbDir, "live.db");
for (const journalMode of ["DELETE", "WAL"]) {
console.log(`\n=== ${journalMode} ===`);
rmSync(dbPath, { force: true });
rmSync(dbPath + "-wal", { force: true });
rmSync(dbPath + "-shm", { force: true });
rmSync(dbPath + "-journal", { force: true });
const db = new Database(dbPath);
db.pragma(`journal_mode = ${journalMode}`);
db.pragma("synchronous = FULL");
db.exec("CREATE TABLE msgs (seq INTEGER PRIMARY KEY, content TEXT)");
db.close();
// Start container poller in background
const contProc = spawn("docker", [
"run", "--rm", "-w", "/app",
"-v", `${dbDir}:/workspace`,
"--entrypoint", "node",
"nanoclaw-agent:latest",
"-e",
`const Database = require('better-sqlite3');
const db = new Database('/workspace/live.db', { readonly: true });
db.pragma('busy_timeout = 2000');
const stmt = db.prepare('SELECT COUNT(*) as n, MAX(seq) as hi FROM msgs');
let count = 0;
const timer = setInterval(() => {
const r = stmt.get();
console.log('poll t=' + (Date.now() % 100000) + ' count=' + r.n + ' max=' + r.hi);
if (++count >= 10) { clearInterval(timer); db.close(); }
}, 1000);`,
], { stdio: ["ignore", "pipe", "pipe"] });
contProc.stdout.on("data", (d) => process.stdout.write(` [cont] ${d}`));
contProc.stderr.on("data", (d) => process.stderr.write(` [cont-err] ${d}`));
// Give container a moment to start
const waitUntil = Date.now() + 2000;
while (Date.now() < waitUntil) {}
// Host opens, writes, CLOSES each time (matches production session-manager pattern)
for (let i = 1; i <= 8; i++) {
const h = new Database(dbPath);
h.pragma(`journal_mode = ${journalMode}`);
h.pragma("synchronous = FULL");
h.prepare("INSERT INTO msgs (seq, content) VALUES (?, ?)").run(i, `msg-${i}`);
h.close();
console.log(` [host] wrote+closed seq=${i} t=${Date.now() % 100000}`);
const sleepUntil = Date.now() + 1000;
while (Date.now() < sleepUntil) {}
}
// Wait for container to finish
await new Promise<void>((res) => contProc.once("exit", () => res()));
}
rmSync(dbDir, { recursive: true, force: true });

4
src/channels/adapter.ts
View File

@@ -29,7 +29,9 @@ export interface ChannelSetup {
onAction(questionId: string, selectedOption: string, userId: string): void; onAction(questionId: string, selectedOption: string, userId: string): void;
/** Credential collection hooks — used by chat-sdk-bridge to route the modal flow. */ /** Credential collection hooks — used by chat-sdk-bridge to route the modal flow. */
getCredentialForModal?(credentialId: string): { name: string; description: string | null; hostPattern: string } | null; getCredentialForModal?(
credentialId: string,
): { name: string; description: string | null; hostPattern: string } | null;
onCredentialReject?(credentialId: string): void; onCredentialReject?(credentialId: string): void;
onCredentialSubmit?(credentialId: string, value: string): void; onCredentialSubmit?(credentialId: string, value: string): void;
onCredentialChannelUnsupported?(credentialId: string): void; onCredentialChannelUnsupported?(credentialId: string): void;

5
src/channels/chat-sdk-bridge.ts
View File

@@ -188,10 +188,7 @@ export function createChatSdkBridge(config: ChatSdkBridgeConfig): ChannelAdapter
} }
try { try {
const modalChildren = [ const modalChildren = [
CardText( CardText(pending.description ?? `Enter the value for ${pending.name} (host: ${pending.hostPattern}).`),
pending.description ??
`Enter the value for ${pending.name} (host: ${pending.hostPattern}).`,
),
TextInput({ TextInput({
id: 'value', id: 'value',
label: pending.name, label: pending.name,

18
src/credentials.ts
View File

@@ -34,10 +34,7 @@ export function setCredentialDeliveryAdapter(adapter: ChannelDeliveryAdapter): v
} }
/** Handle a `request_credential` system action from a container. */ /** Handle a `request_credential` system action from a container. */
export async function handleCredentialRequest( export async function handleCredentialRequest(content: Record<string, unknown>, session: Session): Promise<void> {
content: Record<string, unknown>,
session: Session,
): Promise<void> {
if (!adapterRef) { if (!adapterRef) {
notifyAgentCredentialResult(session, content.credentialId as string, 'failed', 'delivery adapter not ready'); notifyAgentCredentialResult(session, content.credentialId as string, 'failed', 'delivery adapter not ready');
return; return;
@@ -53,12 +50,7 @@ export async function handleCredentialRequest(
const description = (content.description as string) || null; const description = (content.description as string) || null;
if (!credentialId || !name || !hostPattern) { if (!credentialId || !name || !hostPattern) {
notifyAgentCredentialResult( notifyAgentCredentialResult(session, credentialId, 'failed', 'name and hostPattern are required');
session,
credentialId,
'failed',
'name and hostPattern are required',
);
return; return;
} }
@@ -299,11 +291,7 @@ function buildCardText(opts: {
valueFormat: string | null; valueFormat: string | null;
description: string | null; description: string | null;
}): string { }): string {
const lines = [ const lines = [`🔑 Credential request: ${opts.name}`, '', `Host: \`${opts.hostPattern}\``];
`🔑 Credential request: ${opts.name}`,
'',
`Host: \`${opts.hostPattern}\``,
];
if (opts.headerName) lines.push(`Header: \`${opts.headerName}\``); if (opts.headerName) lines.push(`Header: \`${opts.headerName}\``);
if (opts.valueFormat) lines.push(`Format: \`${opts.valueFormat}\``); if (opts.valueFormat) lines.push(`Format: \`${opts.valueFormat}\``);
if (opts.description) lines.push('', opts.description); if (opts.description) lines.push('', opts.description);

1
src/db/db-v2.test.ts
View File

@@ -57,7 +57,6 @@ describe('migrations', () => {
// Running again should not throw // Running again should not throw
runMigrations(db); runMigrations(db);
}); });
}); });
// ── Agent Groups ── // ── Agent Groups ──

5
src/db/sessions.ts
View File

@@ -93,7 +93,10 @@ export function deletePendingQuestion(questionId: string): void {
// ── Pending Approvals ── // ── Pending Approvals ──
export function createPendingApproval(pa: Partial<PendingApproval> & Pick<PendingApproval, 'approval_id' | 'request_id' | 'action' | 'payload' | 'created_at'>): void { export function createPendingApproval(
pa: Partial<PendingApproval> &
Pick<PendingApproval, 'approval_id' | 'request_id' | 'action' | 'payload' | 'created_at'>,
): void {
getDb() getDb()
.prepare( .prepare(
`INSERT INTO pending_approvals `INSERT INTO pending_approvals

91
src/delivery.ts
View File

@@ -312,9 +312,44 @@ async function deliverMessage(
return; return;
} }
// Agent-to-agent — route to target session (with permission check) // Agent-to-agent — route to target session (with permission check).
// Permission is enforced via agent_destinations — the source agent must have
// a row for the target. Content is copied verbatim; the target's formatter
// will look up the source agent in its own local map to display a name.
if (msg.channel_type === 'agent') { if (msg.channel_type === 'agent') {
await routeAgentMessage(msg, session); const targetAgentGroupId = msg.platform_id;
if (!targetAgentGroupId) {
log.warn('Agent message missing target agent group ID', { id: msg.id });
return;
}
if (!hasDestination(session.agent_group_id, 'agent', targetAgentGroupId)) {
log.warn('Unauthorized agent-to-agent message — dropping', {
source: session.agent_group_id,
target: targetAgentGroupId,
});
return;
}
if (!getAgentGroup(targetAgentGroupId)) {
log.warn('Target agent group not found', { id: msg.id, targetAgentGroupId });
return;
}
const { session: targetSession } = resolveSession(targetAgentGroupId, null, null, 'agent-shared');
writeSessionMessage(targetAgentGroupId, targetSession.id, {
id: `a2a-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
kind: 'chat',
timestamp: new Date().toISOString(),
platformId: session.agent_group_id,
channelType: 'agent',
threadId: null,
content: msg.content,
});
log.info('Agent message routed', {
from: session.agent_group_id,
to: targetAgentGroupId,
targetSession: targetSession.id,
});
const fresh = getSession(targetSession.id);
if (fresh) await wakeContainer(fresh);
return; return;
} }
@@ -393,58 +428,6 @@ async function deliverMessage(
return platformMsgId; return platformMsgId;
} }
/**
* Route an agent-to-agent message to the target agent's session.
*
* Permission is enforced via agent_destinations — the source agent must have
* a row for the target. Content is copied verbatim; the target's formatter
* will look up the source agent in its own local map to display a name.
*/
async function routeAgentMessage(
msg: { id: string; platform_id: string | null; content: string },
sourceSession: Session,
): Promise<void> {
const targetAgentGroupId = msg.platform_id;
if (!targetAgentGroupId) {
log.warn('Agent message missing target agent group ID', { id: msg.id });
return;
}
if (!hasDestination(sourceSession.agent_group_id, 'agent', targetAgentGroupId)) {
log.warn('Unauthorized agent-to-agent message — dropping', {
source: sourceSession.agent_group_id,
target: targetAgentGroupId,
});
return;
}
if (!getAgentGroup(targetAgentGroupId)) {
log.warn('Target agent group not found', { id: msg.id, targetAgentGroupId });
return;
}
const { session: targetSession } = resolveSession(targetAgentGroupId, null, null, 'agent-shared');
writeSessionMessage(targetAgentGroupId, targetSession.id, {
id: `a2a-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
kind: 'chat',
timestamp: new Date().toISOString(),
platformId: sourceSession.agent_group_id,
channelType: 'agent',
threadId: null,
content: msg.content,
});
log.info('Agent message routed', {
from: sourceSession.agent_group_id,
to: targetAgentGroupId,
targetSession: targetSession.id,
});
const fresh = getSession(targetSession.id);
if (fresh) await wakeContainer(fresh);
}
/** Ensure the delivered table has new columns (migration for existing sessions). */ /** Ensure the delivered table has new columns (migration for existing sessions). */
function migrateDeliveredTable(db: Database.Database): void { function migrateDeliveredTable(db: Database.Database): void {
const cols = new Set( const cols = new Set(

31
src/session-manager.ts
View File

@@ -1,10 +1,14 @@
/** /**
* Session lifecycle management. * Session lifecycle: folders, DBs, messages, container status.
* Creates session folders + DBs, writes messages, manages container status.
* *
* Two-DB architecture: each session has inbound.db (host-owned) and outbound.db * Two-DB split — inbound.db (host writes) + outbound.db (container writes).
* (container-owned). This eliminates SQLite write contention across the * Three cross-mount invariants are load-bearing:
* host-container mount boundary — each file has exactly one writer. * 1. journal_mode=DELETE — WAL's mmapped -shm doesn't refresh host→guest;
* the container would silently miss every new message.
* 2. Host opens-writes-CLOSES per op — close invalidates the container's
* page cache; a long-lived connection freezes its view at first read.
* 3. One writer per file — DELETE-mode journal-unlink isn't atomic across
* the mount; concurrent writers corrupt the DB.
*/ */
import Database from 'better-sqlite3'; import Database from 'better-sqlite3';
import fs from 'fs'; import fs from 'fs';
@@ -260,7 +264,13 @@ export function writeDestinations(agentGroupId: string, sessionId: string): void
log.debug('Destination map written', { sessionId, count: resolved.length }); log.debug('Destination map written', { sessionId, count: resolved.length });
} }
/** Write a message to a session's inbound DB (messages_in). Host-only. */ /**
* Write a message to a session's inbound DB (messages_in). Host-only.
*
* ⚠ Opens and closes the DB on every call. Do not refactor to reuse a
* long-lived connection — see the "Cross-mount visibility invariants" note
* at the top of this file.
*/
export function writeSessionMessage( export function writeSessionMessage(
agentGroupId: string, agentGroupId: string,
sessionId: string, sessionId: string,
@@ -285,8 +295,13 @@ export function writeSessionMessage(
db.pragma('busy_timeout = 5000'); db.pragma('busy_timeout = 5000');
try { try {
// Host uses even seq numbers, container uses odd — prevents collisions // Host uses even seq, container uses odd. This is not just collision
// across the two-DB boundary without cross-DB coordination. // avoidance between the two DB files — the seq is the agent-facing
// message ID returned by send_message and accepted by edit_message /
// add_reaction, and those tools look up by seq across BOTH tables
// (see container/agent-runner/src/db/messages-out.ts:getMessageIdBySeq).
// So the {messages_in.seq, messages_out.seq} namespace MUST be disjoint,
// or the agent's "edit message #5" could resolve to the wrong row.
const maxSeq = (db.prepare('SELECT COALESCE(MAX(seq), 0) AS m FROM messages_in').get() as { m: number }).m; const maxSeq = (db.prepare('SELECT COALESCE(MAX(seq), 0) AS m FROM messages_in').get() as { m: number }).m;
const nextSeq = maxSeq < 2 ? 2 : maxSeq + 2 - (maxSeq % 2); // next even const nextSeq = maxSeq < 2 ? 2 : maxSeq + 2 - (maxSeq % 2); // next even