0d3326aae5
Replaces the agent-group-centric "main group" concept with user-level
privileges and adds the cold-DM infrastructure needed for proactive
outbound messaging (pairing, approvals, welcome flows).
Privilege model
- New tables: users, user_roles (owner global-only; admin global or
scoped to an agent_group), agent_group_members (explicit non-
privileged access; admin/owner imply membership), user_dms (cold-DM
resolution cache).
- Removed agent_groups.is_admin, messaging_groups.admin_user_id. Replaced
with messaging_groups.unknown_sender_policy (strict | request_approval
| public) for per-chat unknown-sender gating.
- src/access.ts: canAccessAgentGroup, pickApprover, pickApprovalDelivery.
- src/router.ts: access gate on every inbound, honoring
unknown_sender_policy for unknown senders.
- src/channels/telegram.ts: pairing interceptor upserts the paired user
and promotes them to owner if hasAnyOwner() is false (first-pair-wins).
Cold DM infrastructure
- ChannelAdapter.openDM?(handle) — optional method. Chat-SDK-bridge wires
it to chat.openDM() for resolution-required channels (Discord, Slack,
Teams, Webex, gChat); direct-addressable channels (Telegram, WhatsApp,
iMessage, Matrix, Resend) fall through to the handle directly.
- src/user-dm.ts: ensureUserDm(userId) — resolves + caches via user_dms.
Approval routing
- onecli-approvals + delivery use pickApprover + pickApprovalDelivery:
scoped admins → global admins → owners (dedup), first reachable via
ensureUserDm, same-channel-kind tie-break. Approvals land in the
approver's DM, not the origin chat.
Delivery fixes
- delivery.ts ACL rejection now throws instead of returning undefined —
the outer loop previously marked rejected messages as delivered.
- Implicit-origin allow: session.messaging_group_id === target skips the
destination check.
- createMessagingGroupAgent auto-creates the companion agent_destinations
row (normalized local_name from the messaging group's name, collision-
broken within the agent's namespace).
Container
- container-runner.ts: /workspace/global always read-only; drops
NANOCLAW_IS_ADMIN; adds NANOCLAW_ADMIN_USER_IDS (owners + global admins
+ scoped admins for this agent group). Agent-runner poll-loop gates
slash commands against that set.
New skill: /init-first-agent
- Walks the operator through standing up the first agent for a channel:
channel pick → identity lookup (reads each channel SKILL.md's
## Channel Info > how-to-find-id) → DM platform_id resolution (direct-
addressable, cold-DM via "user DMs bot first + sqlite lookup", or
Telegram pair-code fallback) → run scripts/init-first-agent.ts →
verify via tail of nanoclaw.log.
- scripts/init-first-agent.ts: parameterized helper that upserts the
user + grants owner (if none), creates dm-with-<display-name> agent
group + initGroupFilesystem, reuses/creates the DM messaging_group,
wires it (auto-creates destination), resolves the session, and writes
a kind:'chat' / sender:'system' welcome message into inbound.db. Host
sweep wakes the container and the agent DMs the operator via the
normal delivery path.
/manage-channels rewrite
- Drops --is-main / --jid / main-vs-non-main isolation references.
- First-channel flow delegates to /init-first-agent.
- Explains createMessagingGroupAgent auto-creates destinations.
- Adds a privileged-users show section.
setup/
- register.ts: drop --is-main, --jid, --local-name, --trigger
requiresTrigger defaults; call initGroupFilesystem; normalize to
v2 schema (no is_admin, no admin_user_id, sets unknown_sender_policy
'strict'); let createMessagingGroupAgent handle the destination row.
- pair-telegram.ts: emit PAIRED_USER_ID (namespaced "telegram:<id>")
instead of ADMIN_USER_ID; update header comment.
- register.test.ts deleted — was v1-only, tested a registered_groups
table that no longer exists.
Docs
- v2-architecture-diagram.{md,html}: ER diagram updated to drop
is_admin/admin_user_id, add unknown_sender_policy, and include
users/user_roles/agent_group_members/user_dms.
- v2-architecture-draft.md: approval-routing paragraph rewritten for
pickApprover/pickApprovalDelivery/ensureUserDm; SQL schema block
updated; admin-verification paragraph references
NANOCLAW_ADMIN_USER_IDS.
- v2-setup-wiring.md: entity-model sketch rewritten.
- v2-checklist.md: marked privilege refactor / container filtering /
approval routing / unknown-sender gating done; removed obsolete
admin_user_id and main-vs-non-main items.
Scripts
- scripts/init-first-agent.ts (new) replaces scripts/welcome-owner-dm.ts
(removed; welcome-owner was a Discord-specific one-off).
- test-v2-host.ts, test-v2-channel-e2e.ts, seed-discord.ts: drop
is_admin + admin_user_id, use unknown_sender_policy.
Tests
- src/access.test.ts (new): 14 tests for canAccessAgentGroup, role
helpers, pickApprover, ensureUserDm, pickApprovalDelivery.
- src/db/db-v2.test.ts: adds 3 tests for the auto-created
agent_destinations row (normalized name, no duplicates, collision
break within an agent group).
- host-core.test.ts, channel-registry.test.ts: updated fixtures to
use unknown_sender_policy: 'public' where the test exercises routing
rather than the access gate.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
425 lines
13 KiB
HTML
425 lines
13 KiB
HTML
<!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 & 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 <message to='name'> 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 & 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["<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)"]
|
|
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
|
|
string agent_provider
|
|
json container_config
|
|
}
|
|
messaging_groups {
|
|
int id
|
|
string channel_type
|
|
string platform_id
|
|
string name
|
|
bool is_group
|
|
string unknown_sender_policy "strict | request_approval | public"
|
|
}
|
|
users {
|
|
string id PK "namespaced <channel>:<handle>"
|
|
string kind
|
|
string display_name
|
|
}
|
|
user_roles {
|
|
string user_id FK
|
|
string role "owner | admin"
|
|
string agent_group_id FK "null = global"
|
|
}
|
|
agent_group_members {
|
|
string user_id FK
|
|
string agent_group_id FK
|
|
}
|
|
user_dms {
|
|
string user_id FK
|
|
string channel_type
|
|
string messaging_group_id FK
|
|
}
|
|
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>
|