--- name: multi-user-support description: 'Planning skill — multi-user architecture for LINE Hive. Covers per-user message routing, user identity in tools, outbound targeting, and migration path from single-user.' --- # Multi-User Support (Planning) > **Status**: Planning — not yet implemented. This skill documents the target architecture and migration path. ## Current Status Snapshot (2026-02-12) This section reflects the current LINE Hive behavior/codebase baseline that the multi-user plan must evolve from. ### Tool Surface (today) Agents interact with LINE via these MCP tools: - `line_ask` — sends messages (reply-token pool preferred, push fallback) and waits for replies - `line_set_status` — status + agentName - `line_check_messages` — fetches unclaimed inbound messages (currently returns `{ text, timestamp }` only) - `line_list_agents`, `line_read_file`, `line_render_markdown`, `line_git_review` > Note: `line_send_message` was removed; all outbound messaging goes through `line_ask`. ### Storage Schema (relevant tables) - `messages`: has `user_id`, `target_agent_id`, `line_message_id`, `media_json` (but most tool responses do **not** expose `user_id` yet) - `sessions`: has `agent_id` (no `user_id` scoping) - `reply_tokens`: global pool (no `user_id` scoping) - `outgoing`: stores `user_id` recipient + `line_message_id` for quote routing ### Routing + Token Behavior (today) - **Targeting is global**: `targeted_agent_id` is a single config value (shared for all users). - **Sessions are per-agent, not per-user**: a waiting session can be fulfilled by any allowed user's message. - **Reply token pool is shared**: any fresh token can be consumed to reply to the default user; not safe for multi-user. - **Quote replies**: quoting a previously-stored message ID best-effort attaches the *full* quoted text to the routed message using a `[Quote]...[/Quote]` block. ## Known Gaps / Risks (to address) These are additional gaps beyond the core “assignments + per-user sessions + per-user reply tokens + `line_ask(userId)`” work. **Decisions (2026-02-12):** - Targeting state: per-user context target (not global), enforced by assignment (don’t allow unassigned agents; don’t show them in UI) - Allowed-but-unassigned users: reject with “ask admin to assign you” (no queue) - Assignments: a user can be assigned to up to 3 agents (configurable); the user only sees/selects from their assigned agents - Admin commands (`users/assign/unassign/revoke`): admin is `default_user_id` only; non-admin attempts are silently dropped - Reply token pool: tokens must be scoped/consumed strictly per recipient `userId`; `line_ask` can still fall back to push when no token exists - Status/queue UI: `?` shows only that user’s assigned agents; `q` shows only that user’s queued items - Per-user locale: store/use user-level language (not global `user_language`) - Context resolution for target agent: quoted message agent (or quoted-reply target) takes precedence; otherwise use last agent that messaged that user - Schema migration strategy: startup blocking migration + full backfill before serving - Migration failure policy: fail fast (do not start in degraded mode) - Logging PII: log prefix-masked user IDs by default; full raw IDs only in debug mode behind explicit env flag - `line_ask` recipient: `userId` is required in multi-user mode; no fallback/backward-compat recipient lookup | Gap | Why it matters | Proposed direction | |-----|----------------|-------------------| | Per-user targeting state | `targeted_agent_id` is global today → users can steal each other’s target | Store/resolve `targeted_agent_id:` per user. Set from quote context first, otherwise from last agent that messaged that user; always constrain to assigned agents | | Tool payload lacks `userId` | Agents can’t tell who said what; multi-user support becomes unusable | Always include `userId` and `displayName` (cached; may be null) in `line_check_messages` and `line_ask` reply results | | Unassigned-but-allowed UX | Users feel “bot is broken” with silent drops or misroutes | Reject (no queue): “ask admin to assign you”. Welcome message + optionally notify admin on first contact | | Admin command gating | Without gating, any allowed user can re-route themselves/others | Only admin (`default_user_id`) can run `users/assign/unassign/revoke` | | Token pool correctness | Reply tokens are user-scoped on LINE; global pool can reply to wrong user | Add `user_id` to `reply_tokens` and filter by recipient in `sendWithTokenPool` | | Queue/status scoping | Queue previews can leak other users’ messages | Scope queue and status to userId (and assigned agent) | | Locale/profile caching | Today `user_language` is global; doesn’t work for teams | Add per-user profile cache table (language, displayName, fetchedAt) | | Schema migrations & backfill | Shared SQLite across workspaces must be safely migrated | Add additive migrations, default/null columns, and tests for legacy DBs | | Logging/PII | Full LINE userIds shouldn’t leak into logs/reports | Log prefix-masked IDs by default; allow raw IDs only in debug mode behind explicit env flag; keep raw IDs in DB/tool payloads | ### Behavior Contracts (Refined) #### A. Target Resolution Order (per user) For inbound routing, resolve target agent in this order: 1. Agent resolved from quoted message (or quoted-reply target metadata) 2. Last agent that sent an outbound message to that user At each step, validate the candidate agent is in the user’s assigned-agent set. If no valid candidate exists, reject as unassigned/no-target (no queue). #### B. Command Authorization Matrix | Command | Admin (`default_user_id`) | Non-admin allowed user | |---------|---------------------------|-------------------------| | `users` | Allowed | Silent drop | | `assign` | Allowed | Silent drop | | `unassign` | Allowed | Silent drop | | `revoke` | Allowed | Silent drop | | `?` / status | Allowed (scoped to admin’s assigned agents) | Allowed (scoped to caller’s assigned agents) | | `q` / queue | Allowed (caller-scoped queue only) | Allowed (caller-scoped queue only) | #### C. Tool/Error Contract (planning) | Case | Expected behavior | |------|-------------------| | `line_ask` called without `userId` in multi-user mode | Return tool error `missing_user_id` | | `line_ask` called with non-allowed or unassigned `userId` | Return tool error `user_not_assignable` | | No valid reply token for user | Use push fallback (if enabled) | | Migration not complete / schema invalid | Fail startup (no degraded mode) | ## Problem LINE Hive currently assumes a single primary user (`default_user_id`). While access control allows multiple users to send messages, the agent-facing tools have single-user limitations: ### Current Single-User Constraints | Area | Limitation | |------|-----------| | Outbound targeting | `line_ask` always targets `default_user_id` | | User identity | Agent tools don't expose which user sent a message | | Session isolation | Sessions are per-agent, not per-user — messages from different users mix | | Agent ownership | Agents don't know which user they serve | | Reply tokens | Token pool is shared — any agent can use any user's reply token | | Target selection | `targeted_agent_id` is global (not per user) | ### What Already Works | Area | Status | |------|--------| | Access control | ✅ `allowed_users` list filters at webhook level | | Message storage | ✅ `messages.user_id` column already tracks sender | | Outgoing audit | ✅ `outgoing.user_id` column tracks recipient | | Multi-agent | ✅ Agent targeting via `@agentName` works | | Quote routing | ✅ Quote-reply auto-targeting works; stored quoted text can be attached best-effort | ## Design: Admin-Managed Assignment Multi-user mode uses **admin-managed assignment only**. The admin (first registered user) assigns team members to agents via LINE commands. No config files, no web UI. ### Architecture Overview ```mermaid %%{init: {"theme": "default"}}%% flowchart LR subgraph Users["LINE Users"] direction TB Admin["Admin 👑"] DevA["Dev A"] DevB["Dev B"] end subgraph Server["LINE Hive Server"] direction TB WH["Webhook"] --> AC["Access Control"] AC --> Router["Assignment Router"] Router --> StoreMsg["messages table
user_id + target_agent_id"] end subgraph Workspaces["Developer Workspaces"] direction TB AgentX["Agent X
assigned → Dev A"] AgentY["Agent Y
assigned → Dev B"] end Users --> WH StoreMsg --> AgentX StoreMsg --> AgentY AgentX --> DevA AgentY --> DevB style Users fill:#e8f5e9,stroke:#2e7d32 style Server fill:#e3f2fd,stroke:#1565c0 style Workspaces fill:#f3e5f5,stroke:#7b1fa2 ``` ### Admin Commands (LINE Trigger Words) | Command | Action | Quick Reply? | |---------|--------|-------------| | `users` | List all users with assignments | No — returns text list | | `assign` | Start assignment flow | Yes — user picker → agent picker → confirm | | `unassign` | Remove user ↔ agent assignment | Yes — user picker → confirm | | `revoke ` | Remove user from allowed list entirely | No — direct action | ### Webhook Command Flow Spec (Refined) #### Global Guards (all command flows) 1. Access control check passes (`isUserAllowed`) 2. Admin check for admin commands (`users`, `assign`, `unassign`, `revoke`) 3. Non-admin admin-command attempts are silently dropped (no reply) 4. All stateful postbacks must validate the caller is the same admin who started the flow #### Postback Payload Contract (planning) - `assign_pick_user`: `action=assign_pick_user&flowId=&userId=` - `assign_pick_agent`: `action=assign_pick_agent&flowId=&userId=&agentId=` - `assign_confirm`: `action=assign_confirm&flowId=&userId=&agentId=` - `unassign_pick_user`: `action=unassign_pick_user&flowId=&userId=` - `unassign_pick_agent`: `action=unassign_pick_agent&flowId=&userId=&agentId=` - `unassign_confirm`: `action=unassign_confirm&flowId=&userId=&agentId=` `flowId` prevents stale button replays from affecting newer flows. #### `users` Command Flow - Input: admin sends `users` - Output: list allowed users with assigned agent set, current target agent (if any), and assignment count/max - Failure: non-admin → silent drop #### `assign` Command Flow 1. Admin sends `assign` 2. Bot shows candidate users (allowed users not yet at max assignment count) 3. Admin picks user (`assign_pick_user`) 4. Bot shows candidate agents (alive agents not already assigned to that user) 5. Admin picks agent (`assign_pick_agent`) 6. Bot shows confirmation (`assign_confirm`) 7. On confirm: write assignment row idempotently, refresh user’s visible agent set Validation rules: - Reject if user already has max assigned agents - Reject if selected agent is dead or already assigned - Ignore stale/foreign `flowId` #### `unassign` Command Flow 1. Admin sends `unassign` 2. Bot shows users with at least one assignment 3. Admin picks user (`unassign_pick_user`) 4. Bot shows that user’s assigned agents 5. Admin picks agent and confirms (`unassign_confirm`) 6. On confirm: remove only the selected user↔agent row Validation rules: - If removed agent equals user’s current context target, clear context target - If user has no assignments remaining, future inbound messages are rejected (no queue) #### `revoke ` Command Flow 1. Admin issues `revoke ` 2. Remove user from allowed list 3. Remove all user↔agent assignments 4. Clear user-scoped targeting/session artifacts 5. Future inbound from that user is blocked by access control Safety rule: require exact user identity resolution (no ambiguous partial matches). ### Command UX Copy Plan (Admin + User) #### Copy Style Rules - Keep each message to 1–3 short lines - Start with intent emoji (`👥`, `➕`, `➖`, `⛔`) for command context - Include explicit next action in imperative form (e.g., “Select a user”) - Show current limits when relevant (e.g., `2/3 assigned`) #### `users` Output Template ```text 👥 User Assignments 1) Tanaka (U1234…) Agents: Kinako, Nova (2/3) Current target: Kinako 2) Sato (U5678…) Agents: (none) Current target: (none) ``` #### `assign` Flow Templates | State | Bot text template | Quick reply buttons | |------|--------------------|---------------------| | Start | `➕ Assign: Select a user` | `1️⃣ Tanaka (2/3)`, `2️⃣ Sato (0/3)`, `❌ Cancel` | | User selected | `➕ Assign: Select an agent for ` | ``, ``, `⬅️ Back`, `❌ Cancel` | | Confirm | `➕ Confirm assignment: → ?` | `✅ Confirm`, `❌ Cancel` | | Success | `✅ Assigned: → ` | `➕ Assign more`, `👥 Users` | | Validation fail | `⚠️ Cannot assign: ` | `⬅️ Back`, `👥 Users` | Validation reasons to surface: - `max_assignments_reached` - `agent_already_assigned` - `agent_unavailable` #### `unassign` Flow Templates | State | Bot text template | Quick reply buttons | |------|--------------------|---------------------| | Start | `➖ Unassign: Select a user` | user list with assignment counts + `❌ Cancel` | | User selected | `➖ Unassign: Select an agent to remove from ` | assigned agent list + `⬅️ Back`, `❌ Cancel` | | Confirm | `➖ Confirm removal: × ?` | `✅ Confirm`, `❌ Cancel` | | Success | `✅ Removed: × ` | `➖ Continue`, `👥 Users` | | Validation fail | `⚠️ Cannot unassign: ` | `⬅️ Back`, `👥 Users` | #### `revoke` Flow Template | State | Bot text template | Quick reply buttons | |------|--------------------|---------------------| | Confirm | `⛔ Revoke user ? This removes access and all assignments.` | `✅ Confirm revoke`, `❌ Cancel` | | Success | `✅ Revoked: ` | `👥 Users` | | Validation fail | `⚠️ Cannot revoke: ` | `👥 Users` | #### Non-Admin Behavior Templates - Admin commands from non-admin users are silently dropped (no visible message) - Normal user `?` shows only assigned agents - Normal user `q` shows only their own queue #### Quick Reply Transition Rules 1. Every stateful admin step includes `❌ Cancel` 2. Intermediate selection steps include `⬅️ Back` 3. Confirmation steps include only `✅ Confirm` and `❌ Cancel` 4. Success steps provide one continue action + one navigation action (`👥 Users`) 5. Any stale `flowId` tap returns no-op (or a compact “expired flow” message if desired) ### Assignment Flow (Quick Reply UX) ```mermaid %%{init: {"theme": "default"}}%% flowchart LR subgraph AssignFlow["Admin sends 'assign'"] direction TB A["Bot shows unassigned users
(Quick Reply buttons)"] --> B["Admin taps user"] B --> C["Bot shows available agents
(Quick Reply buttons)"] C --> D["Admin taps agent"] D --> E["Bot confirms:
'✅ Dev A → Agent X'"] end subgraph DataFlow["Behind the scenes"] direction TB F["assignments table
user_id ↔ agent_id"] --> G["Router filters messages
by assignment"] G --> H["Agent only sees
assigned user's messages"] end AssignFlow --> DataFlow style AssignFlow fill:#fff3e0,stroke:#e65100 style DataFlow fill:#e3f2fd,stroke:#1565c0 ``` ### New Team Member Onboarding ```mermaid %%{init: {"theme": "default"}}%% flowchart LR subgraph JoinFlow["New User Joins"] direction TB J1["Dev adds bot
as LINE friend"] --> J2["Bot: 👋 Welcome!
Ask admin to assign you."] J2 --> J3["Admin gets notification:
'New user: Dev C'"] J3 --> J4["Admin sends 'assign'
→ picks Dev C → Agent Z"] J4 --> J5["Dev C gets:
'✅ Connected to Agent Z!'"] end style JoinFlow fill:#e8f5e9,stroke:#2e7d32 ``` ### Multi-Account Scenario Same person using 2 LINE accounts (personal + work): each account gets a different `userId` from LINE's API. From LINE Hive's perspective, they are 2 separate users. **Handling**: Admin assigns both accounts to the same agent. The agent sees messages from both accounts but can't tell they're the same person unless told. A future "user alias" feature could link multiple LINE IDs to one logical user — but that's out of scope for initial implementation. ### Key Design Decisions #### 0. Waiting Requires a User (Chosen) **Decision:** Use option **A** — do **not** allow `line_ask` to create a waiting session unless a concrete recipient user is known. **Rule:** `line_ask` must have either: - explicit `userId` in tool args, **or** - an assigned user for that `{agent_id}` (from the planned `assignments` table). If neither exists, `line_ask` should return a tool error like `no_user_assigned` and the agent should only call: ```ts line_set_status({ description: "Waiting for admin to assign a user", agentName: "..." }) ``` **Why:** prevents cross-user leakage via sessions and reply tokens before per-user scoping is implemented. #### 1. User Identity in Tool Results Always include `userId` and `displayName` in `line_check_messages` and `line_ask` results so agents know who sent each message. ```typescript // Current: no user identity { text: "Hello", timestamp: 1234567890 } // Target: include userId + display name (cached; may be null when unknown) { text: "Hello", timestamp: 1234567890, userId: "U1234...", displayName: "Tanaka" } ``` Full LINE userId for unambiguous routing. Display name cached from LINE Profile API for human readability. #### 2. Outbound Targeting Agents specify which user receives a message. ```typescript // Current: always targets default_user_id line_ask({ text: "Hello", agentName: "Nova" }) // Target: required userId parameter in multi-user mode line_ask({ text: "Hello", agentName: "Nova", userId: "U1234..." }) ``` If `userId` is omitted in multi-user mode, return a tool error (no implicit fallback). **LINE API constraint**: Push messages require the recipient's userId. Reply tokens are tied to the user who triggered the event. Token pool must be per-user. #### 3. Session Isolation Sessions track which user they belong to. ```sql -- Target: add user_id column ALTER TABLE sessions ADD COLUMN user_id TEXT; ``` Sessions with `user_id` are only fulfilled by messages from that specific user. #### 4. Reply Token Pool Per-User Reply tokens from webhook events are scoped to the user who triggered them. ```sql -- Target: add user_id to reply_tokens ALTER TABLE reply_tokens ADD COLUMN user_id TEXT; ``` `sendWithTokenPool` filters tokens by the target user. #### 5. Assignments Table (New) ```sql CREATE TABLE assignments ( user_id TEXT NOT NULL, agent_id TEXT NOT NULL, assigned_by TEXT NOT NULL, -- admin userId assigned_at INTEGER NOT NULL, PRIMARY KEY (user_id, agent_id) ); ``` Enforce “max agents per user” at the application layer (default 3; configurable). #### 6. User Profiles Cache (New) ```sql CREATE TABLE user_profiles ( user_id TEXT PRIMARY KEY, display_name TEXT, picture_url TEXT, fetched_at INTEGER NOT NULL ); ``` Populated via LINE Profile API on first contact. Cached for 24h. Rate limit: 2000 req/min — cache aggressively. ## Migration Path ### Phase 1: User Identity + Profiles (Non-Breaking) 1. Add `userId` and `displayName` fields to `line_check_messages` results 2. Add `userId` and `displayName` fields to `line_ask` reply results 3. Create `user_profiles` table — cache display names from LINE Profile API 4. Fetch profile on first webhook event from each userId 5. No schema changes to existing tables — `messages.user_id` already exists ### Phase 2: Assignment System + Admin Commands 1. Create `assignments` table (user_id ↔ agent_id set; enforce max agents per user) 2. Add admin commands to webhook: `users`, `assign`, `unassign`, `revoke` 3. Add Quick Reply picker flows for `assign` and `unassign` 4. New user onboarding: welcome message + admin notification 5. Update message routing to filter by assignment ### Phase 3: Outbound User Targeting 1. Add required `userId` param to `line_ask` in multi-user mode 2. Remove implicit recipient lookup/fallback paths in multi-user mode (no default-user fallback) 3. Add `user_id` column to `reply_tokens` table 4. Update `sendWithTokenPool` to filter tokens by target user 5. Add `user_id` column to `sessions` table 6. Session fulfillment matches by user ### Phase 4: Cleanup + Polish 1. Remove deprecated `consumeReplyToken` and `consumeMessageByCorrelationId` 2. User alias support (link multiple LINE IDs to one logical user) 3. Rate limiting per user (for LINE push API quota management) ### Phase 5 (Optional): Informal Decision Collaboration Layer 1. Add lightweight relay context anchored by `origin_agent_id` (no strict project table required) 2. Default target policy: agent-to-agent first (notification-safe), direct-to-user only when explicit or required 3. Add informal intent handling (natural language relay requests) 4. Add optional one-tap escalation: `Formalize this decision` 5. Enforce notification-safety policy (throttling, duplicate suppression, minimal direct user pings) ## Execution Checklist (Planning Gate) ### Phase 1 Gate — Identity + Profiles - **Acceptance criteria** - `line_check_messages` and `line_ask` reply payloads always include `userId` and `displayName` (nullable) - `user_profiles` cache exists and is used for display name lookup - Per-user language is stored/used for webhook-facing text - **Rollback checkpoint** - Feature flag to disable profile lookup and fall back to existing single-user language behavior - Schema rollback not required (additive table only) ### Phase 2 Gate — Assignments + Access UX - **Acceptance criteria** - `assignments` supports user↔agent sets with max-per-user enforcement (default 3, configurable) - Only assigned agents are shown in user status UI; unassigned users are rejected (no queue) - Admin commands are accepted only from `default_user_id`; non-admin attempts are silently dropped - **Rollback checkpoint** - Command handler switch to disable assignment enforcement and return to current routing - Preserve assignment rows; ignore them until re-enabled ### Phase 3 Gate — Per-User Session/Token Correctness - **Acceptance criteria** - `line_ask` requires `userId` in multi-user mode (no implicit fallback) - Reply token consumption is strict per target `userId` - Sessions are user-scoped and cannot be fulfilled by other users’ messages - Target-agent resolution follows context policy (quote context > last agent), constrained to assigned agents - **Rollback checkpoint** - Runtime switch to force push-only sends while preserving per-user session checks - Migration guard to stop startup if session/token schema is inconsistent ### Phase 4 Gate — Observability + Hardening - **Acceptance criteria** - Logs use prefix-masked IDs by default - Raw userId logging is only enabled under explicit debug env flag - Startup-blocking migrations complete with full backfill before serving - **Rollback checkpoint** - Disable debug raw-ID logging flag - Keep fail-fast migration policy; restore from DB backup on migration regressions ### Phase 5 Gate — Informal Decision Layer (Optional) - **Acceptance criteria** - Informal relay works end-to-end with agent context anchoring - D-01 policy enforced: agent-to-agent first, direct-to-user only when explicit/required - D-02 policy enforced: formalization auto-suggest shown only to origin user - Notification-safety rules active (throttling + duplicate suppression) - **Rollback checkpoint** - Disable informal relay intent handling and keep core multi-user flow unchanged - Preserve relay records as inert historical data ## Files to Modify | Phase | File | Changes | |-------|------|---------| | 1 | `src/tools/checkMessages.ts` | Add `userId`, `displayName` to message results | | 1 | `src/tools/waitForReplyInternal.ts` | Add `userId`, `displayName` to reply results | | 1 | `src/store/messageStore.ts` | Query `user_id` in message retrieval; new `user_profiles` table + methods | | 1 | `src/line/webhook.ts` | Fetch profile on first contact, cache in `user_profiles` | | 1 | `src/line/client.ts` | Add `getProfile(userId)` method to LineClient | | 2 | `src/store/messageStore.ts` | New `assignments` table + CRUD methods | | 2 | `src/line/webhook.ts` | Admin commands (`users`, `assign`, `unassign`, `revoke`), Quick Reply flows, onboarding message | | 2 | `src/line/messages.ts` | Quick Reply builders for assignment picker | | 3 | `src/tools/ask.ts` | Require `userId` param in multi-user mode, remove implicit fallback | | 3 | `src/util/sendWithTokenPool.ts` | Filter reply tokens by userId (per-user token pool) | | 3 | `src/store/messageStore.ts` | Add `user_id` to `reply_tokens` and `sessions`, update queries | | 3 | `src/server.ts` | Update tool schemas with userId param | | 4 | `src/store/messageStore.ts` | Remove deprecated methods | | 5 (opt) | `src/line/webhook.ts` | Add informal relay intents, origin-user-only formalization suggestions | | 5 (opt) | `src/store/messageStore.ts` | Add lightweight relay context + expiry tracking | ## Notes (2026-02) - `line_send_message` was removed from LINE Hive. All outbound messaging must go through `line_ask`. - For multi-user, this means `line_ask` requires `userId` so agents always target the correct recipient. - Session + reply-token scoping must be updated to be per-user, otherwise reply tokens and replies can cross users. - Informal decision tie-up details are documented in `INFORMAL-DECISION-TIE-UP.md` and treated as an optional phase-5 add-on. ## Key Constraints - **LINE push API** requires `to: userId` — cannot broadcast to all users in a single call - **Reply tokens** are scoped to the user's message event — can only reply to that user - **LINE Profile API** rate limits: 2000 req/min — cache aggressively in `user_profiles` - **Backward compatibility**: Single-user mode must keep working without any config changes or assignment setup - **Agent context window**: Adding userId to every message increases token usage — keep compact - **Admin-only**: All assignment operations require admin (first registered user) — no self-service - **Max agents per user**: A user can be assigned to up to 3 agents (configurable) - **Unassigned users**: Allowed-but-unassigned users should be rejected with “ask admin to assign you” (no queue) - **Recipient explicitness**: In multi-user mode, `line_ask` must include `userId` (no implicit fallback) - **Notification safety first**: Minimize direct user pings (agent-to-agent first by default, with throttling and suppression)

multi-user-support

Scan your own AI components