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>
106 lines
6.1 KiB
Markdown
106 lines
6.1 KiB
Markdown
# v2 Setup Wiring — Status & Remaining Work
|
|
|
|
Last updated: 2026-04-09, branch `v2`, commit `1dc5750`
|
|
|
|
## What's Done
|
|
|
|
### Two-DB Split (session DB write isolation)
|
|
- Session DB split into `inbound.db` (host-owned) and `outbound.db` (container-owned)
|
|
- Each file has exactly one writer — eliminates SQLite write contention across host-container mount
|
|
- Host uses even seq numbers, container uses odd (collision-free)
|
|
- Container heartbeat via file touch (`/workspace/.heartbeat`) instead of DB UPDATE
|
|
- Scheduling MCP tools emit system actions via messages_out; host applies them to inbound.db in `delivery.ts:handleSystemAction()`
|
|
- Host sweep reads `processing_ack` table + heartbeat file mtime for stale detection
|
|
- Container clears stale `processing_ack` entries on startup (crash recovery)
|
|
- Files: `src/db/schema.ts` (INBOUND_SCHEMA + OUTBOUND_SCHEMA), `src/session-manager.ts`, `src/delivery.ts`, `src/host-sweep.ts`, `container/agent-runner/src/db/connection.ts`, `messages-in.ts`, `messages-out.ts`, `poll-loop.ts`, `mcp-tools/scheduling.ts`, `mcp-tools/interactive.ts`
|
|
- Container image rebuilt with tsconfig excluding v1 (`container/agent-runner/tsconfig.json`)
|
|
- E2E verified: host → Docker container → Claude responds → "E2E works!" ✓
|
|
|
|
### OneCLI Integration
|
|
- `ensureAgent()` call added before `applyContainerConfig()` in `src/container-runner.ts`
|
|
- Without `ensureAgent`, OneCLI rejects unknown agent identifiers and returns false, leaving container with no credentials
|
|
- E2E verified with OneCLI credential injection ✓
|
|
|
|
### Channel Barrel
|
|
- `src/index.ts` imports `./channels/index.js` (the barrel)
|
|
- Channel skills uncomment lines in the barrel to enable channels
|
|
- Discord is uncommented by default (it was previously a direct import in index.ts)
|
|
|
|
### Setup Registration (partially)
|
|
- `setup/register.ts` rewritten to create v2 entities (`agent_groups`, `messaging_groups`, `messaging_group_agents`) in `data/v2.db`
|
|
- Accepts `--platform-id` (v2) and `--jid` (v1 compat) flags
|
|
- Added `getMessagingGroupAgentByPair()` to prevent duplicate wiring
|
|
- `setup/verify.ts` updated to check v2 central DB (counts agent groups with wiring)
|
|
|
|
### Router Logging
|
|
- `src/router.ts` logs `MESSAGE DROPPED` at WARN level when no agents wired, with actionable guidance
|
|
|
|
---
|
|
|
|
## Previously Open — Now Resolved
|
|
|
|
### 1. ~~v2 Channel Skills Don't Register Groups~~ ✅
|
|
|
|
Channel skills now point to `/manage-channels` in their "Next Steps" section. Registration is handled by the `/manage-channels` skill, which reads each channel's `## Channel Info` section for platform-specific guidance. Channel skills stay lean (credentials only).
|
|
|
|
### 2. ~~v1 add-discord Skill is Incompatible~~ ✅
|
|
|
|
Created `/add-discord-v2` skill matching the v2 pattern. Setup SKILL.md updated to reference `/add-discord-v2`.
|
|
|
|
### 3. ~~Setup SKILL.md Missing Group Registration Step~~ ✅
|
|
|
|
Added step 5a "Wire Channels to Agent Groups" between channel installation (step 5) and mount allowlist (step 6). This step invokes `/manage-channels` which handles agent group creation, isolation level decisions, and wiring.
|
|
|
|
### 4. ~~Channel Skills Should Know Channel Type~~ ✅
|
|
|
|
Each v2 channel skill now has a `## Channel Info` structured section with: type, terminology, how-to-find-id, supports-threads, typical-use, default-isolation. The `/manage-channels` skill reads this for contextual recommendations.
|
|
|
|
### 5. ~~Verify Step Channel Auth Check~~ ✅
|
|
|
|
`setup/verify.ts` now checks all v2 channel tokens: DISCORD_BOT_TOKEN, TELEGRAM_BOT_TOKEN, SLACK_BOT_TOKEN+SLACK_APP_TOKEN, GITHUB_TOKEN, LINEAR_API_KEY, GCHAT_CREDENTIALS, TEAMS_APP_ID+TEAMS_APP_PASSWORD, WEBEX_BOT_TOKEN, MATRIX_ACCESS_TOKEN, RESEND_API_KEY, WHATSAPP_ACCESS_TOKEN, IMESSAGE_ENABLED, plus WhatsApp Baileys auth dir.
|
|
|
|
### 6. Agent-Shared Session Mode ✅
|
|
|
|
Added `session_mode: 'agent-shared'` for cross-channel shared sessions (e.g. GitHub + Slack in one conversation). Session resolution looks up by agent_group_id instead of messaging_group_id when this mode is set.
|
|
|
|
---
|
|
|
|
## Architecture Reference
|
|
|
|
### v2 Entity Model
|
|
```
|
|
agent_groups (id, name, folder, agent_provider, container_config)
|
|
↕ many-to-many
|
|
messaging_groups (id, channel_type, platform_id, name, is_group, unknown_sender_policy)
|
|
via
|
|
messaging_group_agents (messaging_group_id, agent_group_id, trigger_rules, session_mode, priority)
|
|
|
|
users (id, kind, display_name) -- namespaced as "<channel>:<handle>"
|
|
user_roles (user_id, role, agent_group_id) -- owner / admin (global or scoped)
|
|
agent_group_members (user_id, agent_group_id) -- unprivileged access gate
|
|
user_dms (user_id, channel_type, messaging_group_id) -- cold-DM cache
|
|
```
|
|
|
|
Privilege is a user-level concept — there is no "main" agent group or "admin" messaging group. `user_roles` carries `owner` (global only, first pairing sets it) and `admin` (global or scoped to an `agent_group_id`). Unknown-sender gating is per-messaging-group via `messaging_groups.unknown_sender_policy` (`strict | request_approval | public`).
|
|
|
|
### Message Flow
|
|
```
|
|
Channel adapter → routeInbound() → resolve messaging_group → resolve agent via messaging_group_agents
|
|
→ resolve/create session → write to inbound.db → wake container → agent-runner polls inbound.db
|
|
→ agent responds → writes to outbound.db → host delivery poll reads outbound.db → deliver via adapter
|
|
```
|
|
|
|
### Key Files
|
|
| File | Purpose |
|
|
|------|---------|
|
|
| `src/index.ts` | v2 entry point, imports channel barrel |
|
|
| `src/channels/index.ts` | Channel barrel — uncomment to enable |
|
|
| `src/router.ts` | Inbound routing, auto-creates messaging groups |
|
|
| `src/session-manager.ts` | Creates inbound.db + outbound.db per session |
|
|
| `src/delivery.ts` | Polls outbound.db, delivers, handles system actions |
|
|
| `src/host-sweep.ts` | Syncs processing_ack, stale detection, recurrence |
|
|
| `src/container-runner.ts` | Spawns containers, OneCLI ensureAgent + applyContainerConfig |
|
|
| `setup/register.ts` | Creates v2 entities (agent_group, messaging_group, wiring) |
|
|
| `setup/verify.ts` | Checks v2 central DB for registered groups |
|
|
| `container/agent-runner/src/db/connection.ts` | Two-DB connection layer (inbound read-only, outbound read-write) |
|