diff --git a/docs/v2-checklist.md b/docs/v2-checklist.md index 80f91d9..6487658 100644 --- a/docs/v2-checklist.md +++ b/docs/v2-checklist.md @@ -7,8 +7,9 @@ Status: [x] done, [~] partial, [ ] not started ## Core Architecture - [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] Central DB (agent groups, messaging groups, sessions, routing) -- [x] Host sweep (stale detection, 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] Sweep delivery polling (60s across all sessions) - [x] Container runner with session DB mounting @@ -53,7 +54,8 @@ Status: [x] done, [~] partial, [ ] not started - [~] Webex via Chat SDK (adapter + skill written, not tested) - [~] iMessage via Chat SDK (adapter + skill written, not tested) - [x] Backward compatibility with native channels (old adapters still work) -- [ ] Setup flow wired to v2 channels +- [x] Channel barrel wired (src/index.ts imports barrel, skills uncomment) +- [~] Setup flow wired to v2 channels (register.ts + verify.ts updated, but channel skills don't call register yet — see docs/v2-setup-wiring.md) - [ ] Setup communicates each group is a different agent, distinct names - [ ] Setup vs production channel separation - [ ] Generate visual diagram of customized instance at end of setup diff --git a/docs/v2-setup-wiring.md b/docs/v2-setup-wiring.md new file mode 100644 index 0000000..8b67d30 --- /dev/null +++ b/docs/v2-setup-wiring.md @@ -0,0 +1,143 @@ +# 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 "" \ + --name "" \ + --folder "" \ + --trigger "@BotName" \ + --channel \ + --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:"` 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) |