mirror of
https://github.com/qwibitai/nanoclaw.git
synced 2026-06-04 10:14:47 +08:00
v2: channel isolation model, manage-channels skill, refactored channel skills
- Add three-level isolation model (shared session, same agent, separate agent) with agent-shared session mode for cross-channel shared sessions - Create /manage-channels skill for wiring channels to agent groups - Refactor all 12 v2 channel skills: lean SKILL.md + VERIFY.md + REMOVE.md with structured Channel Info section for platform-specific metadata - Create /add-discord-v2 skill (was missing) - Add step 5a to setup SKILL.md invoking /manage-channels after channel install - Update setup/verify.ts to check all 12 channel token types - Add docs/v2-isolation-model.md explaining the isolation model - Update v2-checklist.md and v2-setup-wiring.md to reflect completed work Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
gavrielc
@@ -55,8 +55,10 @@ Status: [x] done, [~] partial, [ ] not started
|
||||
- [~] iMessage via Chat SDK (adapter + skill written, not tested)
|
||||
- [x] Backward compatibility with native channels (old adapters still work)
|
||||
- [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
|
||||
- [x] Setup flow wired to v2 channels (channel skills + /manage-channels for registration + verify.ts checks all tokens)
|
||||
- [x] Channel Info metadata in each channel skill (type, terminology, how-to-find-id, isolation defaults)
|
||||
- [x] /manage-channels skill (wire channels to agent groups with three isolation levels)
|
||||
- [x] Agent-shared session mode (cross-channel shared sessions, e.g. GitHub + Slack)
|
||||
- [ ] Setup vs production channel separation
|
||||
- [ ] Generate visual diagram of customized instance at end of setup
|
||||
|
||||
|
||||
@@ -0,0 +1,88 @@
|
||||
# Channel Isolation Model
|
||||
|
||||
NanoClaw v2 decouples messaging channels from agent groups. When you connect a channel (Discord, Telegram, Slack, GitHub, etc.), you decide how it relates to your existing agents. There are three isolation levels.
|
||||
|
||||
## The Three Levels
|
||||
|
||||
### 1. Shared Session
|
||||
|
||||
Multiple channels feed into the same conversation. The agent sees all messages from all channels in one thread.
|
||||
|
||||
**What's shared:** Everything — workspace, memory, CLAUDE.md, and the conversation itself. A GitHub PR comment and a Slack message appear side by side in the agent's context.
|
||||
|
||||
**Example:** A Slack channel paired with GitHub webhooks. The agent receives PR review requests via GitHub and discusses them in Slack — all in one session. When someone comments on a PR, the agent can reference the earlier Slack discussion about that feature.
|
||||
|
||||
**When to use:** When one channel feeds context into another. Webhook/notification channels (GitHub, Linear) paired with a chat channel (Slack, Discord) are the classic case.
|
||||
|
||||
**Technical:** Both messaging groups are wired to the same agent group with `session_mode: 'agent-shared'`. Session resolution looks up by agent group ID only, ignoring the messaging group — so all channels converge on one session.
|
||||
|
||||
---
|
||||
|
||||
### 2. Same Agent, Separate Sessions
|
||||
|
||||
Multiple channels share the same agent (same workspace, memory, personality) but have independent conversations.
|
||||
|
||||
**What's shared:** Workspace, memory, CLAUDE.md, and all persistent state. If you tell the agent something in one session, it can save that to memory and recall it in another. The agent's personality, knowledge, and tools are identical across sessions.
|
||||
|
||||
**What's separate:** The conversation thread. Messages from one channel don't appear in the other channel's session. Each channel has its own context window and conversation history.
|
||||
|
||||
**Example:** You have three Telegram chats with your agent — one for a side project, one for personal tasks, one for work. All three share the same agent workspace. If you ask it to remember your API key naming convention in the project chat, it may recall that convention in the work chat too. But the conversations themselves are independent.
|
||||
|
||||
**When to use:** When you're the primary (or sole) participant across channels and you want a unified agent identity. This is the most common setup for personal use across multiple platforms or multiple groups within one platform.
|
||||
|
||||
**Technical:** Multiple messaging groups are wired to the same agent group with `session_mode: 'shared'` (or `'per-thread'`). Each messaging group gets its own session, but they all run in the same agent group folder.
|
||||
|
||||
---
|
||||
|
||||
### 3. Separate Agent Groups
|
||||
|
||||
Each channel gets its own agent with its own workspace, memory, and personality. Nothing is shared.
|
||||
|
||||
**What's shared:** Nothing. The agents don't know about each other. Different CLAUDE.md, different memory, different workspace, different conversation history.
|
||||
|
||||
**Example:** You have a Telegram group with a friend and a Discord server for a team project. The friend shouldn't know what you discuss with your team, and vice versa. Each gets its own agent with its own memory and personality.
|
||||
|
||||
**When to use:** When different people are involved, or when the information in one channel should never leak to another. This is the right choice whenever there's a privacy or confidentiality boundary between channels.
|
||||
|
||||
**Technical:** Each channel is wired to a different agent group, each with its own folder under `groups/`. Separate containers, separate session databases, separate everything.
|
||||
|
||||
---
|
||||
|
||||
## How to Decide
|
||||
|
||||
The key question: **Are you okay with any and every piece of information from one channel being available in the other?**
|
||||
|
||||
- **No** → Separate agent groups (level 3)
|
||||
- **Yes, and the channels should see each other's messages** → Shared session (level 1)
|
||||
- **Yes, but the conversations should be independent** → Same agent, separate sessions (level 2)
|
||||
|
||||
### Rules of Thumb
|
||||
|
||||
| Scenario | Recommended Level |
|
||||
|----------|------------------|
|
||||
| Just you, multiple platforms (Telegram + Discord + Slack) | Same agent, separate sessions |
|
||||
| Just you, multiple groups on one platform (3 Telegram chats) | Same agent, separate sessions |
|
||||
| Webhook channel + chat channel (GitHub + Slack) | Shared session |
|
||||
| Channel with friend A and channel with friend B | Separate agent groups |
|
||||
| Personal channel and work channel | Separate agent groups |
|
||||
| Team channel with different access levels | Separate agent groups |
|
||||
|
||||
### When in Doubt
|
||||
|
||||
If the participants are the same across channels → same agent group is usually fine.
|
||||
|
||||
If different people are involved → separate agent groups. Information will cross-pollinate through agent memory if you don't.
|
||||
|
||||
## Entity Model
|
||||
|
||||
```
|
||||
agent_groups (workspace, memory, CLAUDE.md, personality)
|
||||
↕ many-to-many
|
||||
messaging_groups (a specific channel/chat/group on a platform)
|
||||
via
|
||||
messaging_group_agents (session_mode, trigger_rules, priority)
|
||||
```
|
||||
|
||||
- **Shared session:** multiple messaging_groups → same agent_group, `session_mode = 'agent-shared'`
|
||||
- **Same agent, separate sessions:** multiple messaging_groups → same agent_group, `session_mode = 'shared'`
|
||||
- **Separate agents:** each messaging_group → different agent_group
|
||||
+13
-58
@@ -37,76 +37,31 @@ Last updated: 2026-04-09, branch `v2`, commit `1dc5750`
|
||||
|
||||
---
|
||||
|
||||
## What's NOT Done — Remaining Work for Fresh Install
|
||||
## Previously Open — Now Resolved
|
||||
|
||||
### 1. v2 Channel Skills Don't Register Groups
|
||||
### 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
|
||||
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).
|
||||
|
||||
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).
|
||||
### 2. ~~v1 add-discord Skill is Incompatible~~ ✅
|
||||
|
||||
**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)
|
||||
```
|
||||
Created `/add-discord-v2` skill matching the v2 pattern. Setup SKILL.md updated to reference `/add-discord-v2`.
|
||||
|
||||
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
|
||||
### 3. ~~Setup SKILL.md Missing Group Registration Step~~ ✅
|
||||
|
||||
### 2. v1 add-discord Skill is Incompatible
|
||||
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.
|
||||
|
||||
**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)
|
||||
### 4. ~~Channel Skills Should Know Channel Type~~ ✅
|
||||
|
||||
**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
|
||||
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.
|
||||
|
||||
### 3. Setup SKILL.md Missing Group Registration Step
|
||||
### 5. ~~Verify Step Channel Auth Check~~ ✅
|
||||
|
||||
**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.
|
||||
`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.
|
||||
|
||||
**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
|
||||
### 6. Agent-Shared Session Mode ✅
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user