nanoclaw/docs/v2-setup-wiring.md

# 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

---

## What's NOT Done — Remaining Work for Fresh Install

### 1. v2 Channel Skills Don't Register Groups

**Problem:** The v2 channel skills (`.claude/skills/add-telegram-v2/SKILL.md`, `add-slack-v2`, `add-linear-v2`, etc.) only do:
- Install npm package
- Uncomment barrel import
- Collect credentials → write to `.env`
- Build and verify

They do NOT create agent groups, messaging groups, or wiring in the v2 central DB. Without these DB entities, the router auto-creates a `messaging_group` on first message but finds no `messaging_group_agents` → message is silently dropped (now logged as WARN).

**Fix needed:** Each v2 channel skill needs a registration phase that calls:
```bash
npx tsx setup/index.ts --step register -- \
  --platform-id "<channel-id>" \
  --name "<group-name>" \
  --folder "<agent-folder>" \
  --trigger "@BotName" \
  --channel <channel-type> \
  --is-main  # (if this is the primary group)
```

Or alternatively, add a dedicated "register groups" step to `setup/SKILL.md` between step 5 (channels) and step 6 (mounts). This step would:
1. Ask the user how many agent groups they want
2. For each group: name, folder, which channels it handles, trigger pattern, session mode
3. Call `setup/register.ts` for each

### 2. v1 add-discord Skill is Incompatible

**Problem:** Setup SKILL.md line 263 references `/add-discord` (v1 skill). This skill:
- Tries to merge a branch (`feat/discord`)
- Uses `--jid "dc:<id>"` format
- References `store/messages.db` for verification
- Creates a v1 DiscordChannel class (we now use Chat SDK)

**Fix needed:** Either:
- Create a `/add-discord-v2` skill matching the pattern of other v2 skills
- Or update the existing `/add-discord` skill for v2
- Update `setup/SKILL.md` line 263 to reference the correct skill

### 3. Setup SKILL.md Missing Group Registration Step

**Problem:** The setup flow (steps 0-9) has no step for creating agent groups. Channels get configured (step 5) but nobody creates the v2 entities needed for routing.

**Fix needed:** Add a step (probably between current step 5 and 6, or as part of step 5) that:
1. Asks "What do you want to name your assistant?" (already partially handled by `--assistant-name`)
2. Asks which channel+platform-id is the primary/admin channel
3. Creates the agent_group with `is_admin=1`
4. Creates messaging_group + messaging_group_agents wiring
5. Optionally creates additional non-admin agent groups

The v1 flow embedded this in each channel skill's "Register" phase. The v2 flow should either do the same (add register calls to each v2 channel skill) or centralize it.

### 4. Setup Groups Step (`setup/groups.ts`)

Check if `setup/groups.ts` exists and what it does. It may need updating for v2 or may need to be created.

### 5. Channel Skills Should Know Channel Type

Each v2 channel skill knows its channel type (discord, telegram, slack, etc.) but the registration args need the platform-specific channel/group ID which the user must provide. The skill should ask for this during Phase 3 (Setup) and then call register.

### 6. Verify Step Channel Auth Check

`setup/verify.ts` currently checks for a limited set of channel tokens:
- TELEGRAM_BOT_TOKEN, SLACK_BOT_TOKEN, SLACK_APP_TOKEN, DISCORD_BOT_TOKEN
- WhatsApp auth dir

It should also check for v2 channel tokens:
- GITHUB_TOKEN, LINEAR_API_KEY, GCHAT_CREDENTIALS, TEAMS_APP_PASSWORD, etc.

---

## Architecture Reference

### v2 Entity Model
```
agent_groups (id, name, folder, is_admin, agent_provider, container_config)
    ↕ many-to-many
messaging_groups (id, channel_type, platform_id, name, is_group, admin_user_id)
    via
messaging_group_agents (messaging_group_id, agent_group_id, trigger_rules, session_mode, priority)
```

### 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) |