@emqo/claudebridge 0.9.1 → 0.10.0

package/README.md

@@ -38,6 +38,14 @@ Instead of hardcoded commands, ClaudeBridge injects a **skill document** into Cl
 - **Parallel Execution**: Multiple `claude` instances running simultaneously (`max_parallel` config)
 - **Observability**: `/status` command shows task queue, chain progress, and execution stats
 
+### v0.10.0: Dispatcher Architecture (Master-Worker Sessions)
+
+- **Dispatcher (Master Session)**: Every user has a single dispatcher that receives all messages and routes them to the correct sub-session. Users never interact with sub-sessions directly
+- **Intelligent Routing**: Fast path ($0) for 0-1 active sessions; Claude-powered classification with user memories + session summaries for 2+ sessions
+- **Session Summaries**: Each sub-session maintains an auto-generated summary, giving the dispatcher context about what each conversation is doing
+- **Memory-Aware Dispatch**: Dispatcher sees user memories + all active session summaries when classifying, enabling accurate routing even for ambiguous messages
+- **Concurrent Sub-Sessions**: Multiple sub-sessions execute in parallel with per-session locks
+
 ## Quick Start
 
 ### Global Install (npm)
@@ -91,6 +99,11 @@ agent:
     max_memories: 50
   skill:
     enabled: true
+  session:
+    enabled: true
+    max_per_user: 3
+    idle_timeout_minutes: 30
+    dispatcher_budget: 0.05
 
 workspace:
   base_dir: "./workspaces"
@@ -231,11 +244,13 @@ src/
   ctl.ts                  claudebridge-ctl: memory/task/reminder/auto ops via SQLite
   webhook.ts              HTTP server + GitHub webhooks + cron scheduler
   core/
-    agent.ts              Claude CLI subprocess spawner (runStream + runParallel)
+    agent.ts              Claude CLI subprocess spawner + session summary sync
     config.ts             YAML config with env fallback
     keys.ts               Endpoint round-robin with cooldown
-    lock.ts               Per-user concurrency mutex (Redis or in-memory)
+    lock.ts               Per-user/per-session concurrency mutex (Redis or in-memory)
     store.ts              SQLite (WAL): sessions, usage, history, memories, tasks
+    router.ts             Dispatcher: message routing with memories + session summaries
+    session.ts            Sub-session lifecycle management
     permissions.ts        Whitelist access control
     markdown.ts           Markdown → Telegram MarkdownV2
     i18n.ts               Internationalization (en/zh)
@@ -250,13 +265,16 @@ src/
 ### Data Flow
 
 ```
-User message → Adapter → Access check → Claude subprocess → Stream response back
-                                              ↓
-                                     Reads skill doc → calls ctl via Bash
-                                              ↓
-                                     SQLite: memories, tasks, reminders
-                                              ↓
-                                     Bridge timers: auto-execute, remind, approve
+User message → Adapter → Access check
+                              ↓
+                    Dispatcher (master session)
+                    ├─ Fast path: 0-1 sessions → direct route ($0)
+                    └─ Classify: 2+ sessions → Claude call (memories + summaries)
+                              ↓
+                    Sub-session execution (per-session lock)
+                    ├─ Inject memories + skill doc → spawn claude CLI
+                    ├─ Stream response back to adapter
+                    └─ Post: save history, sync summary, auto-summarize to shared memory
 ```
 
 ## Prerequisites
@@ -305,6 +323,14 @@ MIT
 - **并行执行**：多个 `claude` 实例同时运行（`max_parallel` 配置）
 - **可观测性**：`/status` 命令显示任务队列、链路进度和执行统计
 
+### v0.10.0：Dispatcher 架构（主从会话）
+
+- **Dispatcher（主会话）**：每个用户有一个 Dispatcher 接收所有消息并路由到正确的子会话，用户无需感知子会话的存在
+- **智能路由**：0-1 个活跃会话走快速路径（$0）；2+ 个会话时 Claude 分类器携带用户记忆 + 会话摘要进行判断
+- **会话摘要**：每个子会话自动生成摘要，让 Dispatcher 了解每个对话在做什么
+- **记忆感知分发**：Dispatcher 分类时可见用户记忆 + 所有活跃会话摘要，即使模糊消息也能准确路由
+- **并发子会话**：多个子会话并行执行，per-session 锁保证安全
+
 ## 快速开始
 
 ### 全局安装（npm）

package/config.yaml.example

@@ -37,7 +37,7 @@ agent:
     enabled: true             # Enable multi-session (concurrent conversations per user)
     max_per_user: 3           # Max concurrent sub-sessions per user
     idle_timeout_minutes: 30  # Auto-close idle sub-sessions after this time
-    classifier_budget: 0.05   # Max budget for routing classifier (Tier 3)
+    dispatcher_budget: 0.05   # Max budget for dispatcher classifier
     classifier_model: ""      # Model for classifier (empty = use default)
 
 workspace:

package/dist/core/agent.d.ts

@@ -3,7 +3,7 @@ import { Store } from "./store.js";
 import { AccessControl } from "./permissions.js";
 import { EndpointRotator } from "./keys.js";
 import { SessionManager } from "./session.js";
-import { SessionRouter } from "./router.js";
+import { Dispatcher } from "./router.js";
 export interface AgentResponse {
     text: string;
     sessionId: string;
@@ -19,7 +19,7 @@ export declare class AgentEngine {
     private lock;
     private rotator;
     private sessionMgr;
-    private router;
+    private dispatcher;
     private sessionExpiryTimer?;
     access: AccessControl;
     constructor(config: Config, store: Store);
@@ -32,7 +32,7 @@ export declare class AgentEngine {
     getEndpointCount(): number;
     getMaxParallel(): number;
     getSessionManager(): SessionManager;
-    getRouter(): SessionRouter;
+    getDispatcher(): Dispatcher;
     getWorkDir(userId: string): string;
     /** @deprecated Use isSessionLocked() for multi-session mode */
     isLocked(userId: string): boolean;
@@ -68,5 +68,6 @@ export declare class AgentEngine {
     private _execute;
     /** Parallel execution without session resume. Thin wrapper around _spawnAgent. */
     private _executeNoSession;
+    private _syncSessionSummary;
     private _autoSummarize;
 }

package/dist/core/agent.js

@@ -6,7 +6,7 @@ import { AccessControl } from "./permissions.js";
 import { EndpointRotator } from "./keys.js";
 import { generateSkillDoc } from "../skills/bridge.js";
 import { SessionManager } from "./session.js";
-import { SessionRouter } from "./router.js";
+import { Dispatcher } from "./router.js";
 import { log as rootLog } from "./logger.js";
 import { getProvider } from "../providers/registry.js";
 const log = rootLog.child("agent");
@@ -16,7 +16,7 @@ export class AgentEngine {
     lock;
     rotator;
     sessionMgr;
-    router;
+    dispatcher;
     sessionExpiryTimer;
     access;
     constructor(config, store) {
@@ -26,7 +26,7 @@ export class AgentEngine {
         this.access = new AccessControl(config.access.allowed_users, config.access.allowed_groups);
         this.rotator = new EndpointRotator(config.endpoints);
         this.sessionMgr = new SessionManager(store, config.agent.session);
-        this.router = new SessionRouter(this.sessionMgr, this.rotator, config.agent.session);
+        this.dispatcher = new Dispatcher(this.sessionMgr, this.rotator, config.agent.session, store);
         // Periodic idle session expiry (every 5 min)
         this.sessionExpiryTimer = setInterval(() => {
             this.sessionMgr.expireIdle();
@@ -53,8 +53,8 @@ export class AgentEngine {
     getSessionManager() {
         return this.sessionMgr;
     }
-    getRouter() {
-        return this.router;
+    getDispatcher() {
+        return this.dispatcher;
     }
     getWorkDir(userId) {
         if (!this.config.workspace.isolation) {
@@ -80,8 +80,8 @@ export class AgentEngine {
      * Routes to the correct sub-session and executes concurrently.
      */
     async handleUserMessage(userId, prompt, platform, chatId, replyToMsgId, onChunk, overrideTimeoutMs) {
-        // 1. Route
-        const decision = await this.router.route(userId, platform, chatId, prompt, replyToMsgId);
+        // 1. Dispatch
+        const decision = await this.dispatcher.dispatch(userId, platform, chatId, prompt, replyToMsgId);
         // 2. Create or get sub-session
         let subSession;
         if (decision.action === "create") {
@@ -121,6 +121,8 @@ export class AgentEngine {
         // 6. Auto-summarize
         if (this.config.agent.memory?.auto_summary)
             this._autoSummarize(userId, prompt, res.text);
+        // 7. Sync sub-session summary for dispatcher context
+        this._syncSessionSummary(subSession, prompt, res.text);
         return { ...res, subSessionId: subSession.id, label: subSession.label };
     }
     /**
@@ -336,6 +338,47 @@ export class AgentEngine {
             logLabel: "parallel", verbose: false,
         });
     }
+    _syncSessionSummary(subSession, prompt, response) {
+        const ep = this.rotator.count
+            ? this.rotator.next()
+            : { name: "default", provider: "claude", model: "" };
+        const summaryPrompt = `Summarize this conversation exchange in 1-2 sentences for a dispatcher that routes messages. Focus on the topic/task being discussed.\n\nUser: ${prompt.slice(0, 300)}\nAssistant: ${response.slice(0, 500)}`;
+        const args = ["-p", summaryPrompt, "--output-format", "stream-json", "--max-turns", "1", "--max-budget-usd", "0.02"];
+        if (ep.model)
+            args.push("--model", ep.model);
+        const env = { ...process.env };
+        const child = spawn("claude", args, { env, stdio: ["pipe", "pipe", "pipe"] });
+        child.stdin.end();
+        const killTimer = setTimeout(() => { try {
+            child.kill("SIGTERM");
+        }
+        catch { } }, 30000);
+        let result = "";
+        let buffer = "";
+        child.stdout.on("data", (data) => {
+            buffer += data.toString();
+            const lines = buffer.split("\n");
+            buffer = lines.pop() || "";
+            for (const line of lines) {
+                if (!line.trim())
+                    continue;
+                try {
+                    const msg = JSON.parse(line);
+                    if (msg.type === "result" && msg.result)
+                        result = msg.result;
+                }
+                catch { }
+            }
+        });
+        child.on("close", () => {
+            clearTimeout(killTimer);
+            if (result && result.length > 0) {
+                this.sessionMgr.updateSummary(subSession.id, result.trim().slice(0, 200));
+                log.info("session summary synced", { sessionId: subSession.id.slice(0, 8) });
+            }
+        });
+        child.on("error", (err) => { log.warn("session summary error", { error: err.message }); });
+    }
     _autoSummarize(userId, prompt, response) {
         const ep = this.rotator.count
             ? this.rotator.next()

package/dist/core/router.d.ts

@@ -1,25 +1,29 @@
 import { SessionManager } from "./session.js";
 import { EndpointRotator } from "./keys.js";
 import { SessionConfig } from "./config.js";
+import { Store } from "./store.js";
 export interface RouterDecision {
     action: "route" | "create";
     subSessionId?: string;
     label?: string;
 }
-export declare class SessionRouter {
+export declare class Dispatcher {
     private sessionMgr;
     private rotator;
     private config;
-    constructor(sessionMgr: SessionManager, rotator: EndpointRotator, config: SessionConfig);
+    private store;
+    constructor(sessionMgr: SessionManager, rotator: EndpointRotator, config: SessionConfig, store: Store);
     /**
-     * 3-tier routing:
-     *   Tier 1: reply-to → direct route ($0)
-     *   Tier 2: 0-1 active sessions → bypass ($0)
-     *   Tier 3: 2+ active sessions → Claude classifier (~$0.002)
+     * Dispatch user message:
+     *   Fast path: reply-to → direct route ($0)
+     *   Fast path: 0 active → create ($0)
+     *   Fast path: 1 active → route ($0)
+     *   Classify: 2+ active → Claude classifier with memories + summaries
      */
-    route(userId: string, platform: string, chatId: string, messageText: string, replyToMsgId?: string): Promise<RouterDecision>;
-    /** Single-turn Claude call to classify which session a message belongs to */
+    dispatch(userId: string, platform: string, chatId: string, messageText: string, replyToMsgId?: string): Promise<RouterDecision>;
+    /** Classify with user memories + sub-session summaries for context */
     private _classify;
-    /** Spawn claude CLI for single-turn classification (no tools, no session) */
+    /** Spawn claude CLI for single-turn classification */
     private _callClassifier;
 }
+export { Dispatcher as SessionRouter };

package/dist/core/router.js

@@ -1,23 +1,26 @@
 import { spawn } from "child_process";
 import { log as rootLog } from "./logger.js";
-const log = rootLog.child("router");
-export class SessionRouter {
+const log = rootLog.child("dispatcher");
+export class Dispatcher {
     sessionMgr;
     rotator;
     config;
-    constructor(sessionMgr, rotator, config) {
+    store;
+    constructor(sessionMgr, rotator, config, store) {
         this.sessionMgr = sessionMgr;
         this.rotator = rotator;
         this.config = config;
+        this.store = store;
     }
     /**
-     * 3-tier routing:
-     *   Tier 1: reply-to → direct route ($0)
-     *   Tier 2: 0-1 active sessions → bypass ($0)
-     *   Tier 3: 2+ active sessions → Claude classifier (~$0.002)
+     * Dispatch user message:
+     *   Fast path: reply-to → direct route ($0)
+     *   Fast path: 0 active → create ($0)
+     *   Fast path: 1 active → route ($0)
+     *   Classify: 2+ active → Claude classifier with memories + summaries
      */
-    async route(userId, platform, chatId, messageText, replyToMsgId) {
-        // Tier 1: reply-to routing
+    async dispatch(userId, platform, chatId, messageText, replyToMsgId) {
+        // Fast path: reply-to routing
         if (replyToMsgId) {
             const sessId = this.sessionMgr.getSessionByMessage(replyToMsgId, chatId);
             if (sessId) {
@@ -26,9 +29,8 @@ export class SessionRouter {
                     return { action: "route", subSessionId: sessId };
                 }
             }
-            // reply-to pointed to closed/expired session — fall through to Tier 2/3
         }
-        // Tier 2: 0-1 active sessions → direct
+        // Fast path: 0-1 active sessions
         const active = this.sessionMgr.getActive(userId, platform);
         if (active.length === 0) {
             return { action: "create", label: messageText.slice(0, 50) };
@@ -36,49 +38,67 @@ export class SessionRouter {
         if (active.length === 1) {
             return { action: "route", subSessionId: active[0].id };
         }
-        // Tier 3: 2+ sessions → Claude classifier
+        // 2+ sessions: classify with memories + summaries
         return await this._classify(userId, platform, messageText, active);
     }
-    /** Single-turn Claude call to classify which session a message belongs to */
+    /** Classify with user memories + sub-session summaries for context */
     async _classify(userId, platform, text, sessions) {
         try {
+            // Gather context
+            const memories = this.store.getMemories(userId);
+            const summaries = this.sessionMgr.getSummaries(userId, platform);
             const sessionList = sessions
                 .map(s => {
                 const ago = Math.round((Date.now() - s.lastActiveAt) / 60000);
-                return `[${s.id.slice(0, 8)}] "${s.label || "(no topic)"}" (${ago}min ago)`;
+                const sum = summaries.find(x => x.id === s.id);
+                const summaryText = sum?.summary ? ` | Summary: ${sum.summary}` : "";
+                return `[${s.id.slice(0, 8)}] "${s.label || "(no topic)"}" (${ago}min ago${summaryText})`;
             })
                 .join("\n");
-            const prompt = `You are a message router. Active conversations:\n${sessionList}\n\nUser message: "${text.slice(0, 200)}"\n\nReply with ONLY the 8-char session ID to route to, or "new" for a new conversation. No explanation.`;
+            const memoryBlock = memories.length
+                ? `\nUser context:\n${memories.slice(0, 10).map(m => `- ${m.content}`).join("\n")}\n`
+                : "";
+            const prompt = `You are a message dispatcher. Route the user's message to the correct conversation, or decide to create a new one, or handle a management request.
+${memoryBlock}
+Active conversations:
+${sessionList}
+
+User message: "${text.slice(0, 300)}"
+
+Reply with ONLY one of:
+- An 8-char session ID to route to
+- "new" to create a new conversation
+
+No explanation.`;
             const result = await this._callClassifier(prompt);
-            const cleaned = result.trim().toLowerCase();
-            if (cleaned === "new") {
+            const cleaned = result.trim();
+            if (cleaned.toLowerCase() === "new") {
                 return { action: "create", label: text.slice(0, 50) };
             }
             // Match against active sessions (first 8 chars of ID)
-            const match = sessions.find(s => s.id.slice(0, 8) === cleaned);
+            const match = sessions.find(s => s.id.slice(0, 8) === cleaned.toLowerCase());
             if (match) {
                 return { action: "route", subSessionId: match.id };
             }
-            // Fallback: if classifier returned something unexpected, route to most recently active
+            // Fallback: route to most recently active
             log.warn("classifier returned unexpected, falling back", { result: cleaned });
             return { action: "route", subSessionId: sessions[0].id };
         }
         catch (err) {
-            // Classifier failed — fallback: create new session
             log.warn("classifier error, creating new session", { error: err.message });
             return { action: "create", label: text.slice(0, 50) };
         }
     }
-    /** Spawn claude CLI for single-turn classification (no tools, no session) */
+    /** Spawn claude CLI for single-turn classification */
     _callClassifier(prompt) {
         return new Promise((resolve, reject) => {
+            const budget = this.config.dispatcher_budget ?? this.config.classifier_budget ?? 0.05;
             const args = ["-p", prompt, "--output-format", "stream-json", "--max-turns", "1"];
-            if (this.config.classifier_budget)
-                args.push("--max-budget-usd", String(this.config.classifier_budget));
+            if (budget)
+                args.push("--max-budget-usd", String(budget));
             if (this.config.classifier_model)
                 args.push("--model", this.config.classifier_model);
             const env = { ...process.env };
-            // Use the first available endpoint for the classifier model
             if (this.rotator.count) {
                 const ep = this.rotator.next();
                 if (!this.config.classifier_model && ep.model)
@@ -123,3 +143,5 @@ export class SessionRouter {
         });
     }
 }
+// Backward compatibility alias
+export { Dispatcher as SessionRouter };

package/dist/core/schema.d.ts

@@ -16,7 +16,7 @@ declare const SessionConfigSchema: z.ZodObject<{
     enabled: z.ZodDefault<z.ZodBoolean>;
     max_per_user: z.ZodDefault<z.ZodNumber>;
     idle_timeout_minutes: z.ZodDefault<z.ZodNumber>;
-    classifier_budget: z.ZodDefault<z.ZodNumber>;
+    dispatcher_budget: z.ZodDefault<z.ZodNumber>;
     classifier_model: z.ZodDefault<z.ZodString>;
 }, z.core.$strip>;
 declare const AgentConfigSchema: z.ZodObject<{
@@ -40,7 +40,7 @@ declare const AgentConfigSchema: z.ZodObject<{
         enabled: z.ZodDefault<z.ZodBoolean>;
         max_per_user: z.ZodDefault<z.ZodNumber>;
         idle_timeout_minutes: z.ZodDefault<z.ZodNumber>;
-        classifier_budget: z.ZodDefault<z.ZodNumber>;
+        dispatcher_budget: z.ZodDefault<z.ZodNumber>;
         classifier_model: z.ZodDefault<z.ZodString>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
@@ -108,7 +108,7 @@ export declare const ConfigSchema: z.ZodObject<{
             enabled: z.ZodDefault<z.ZodBoolean>;
             max_per_user: z.ZodDefault<z.ZodNumber>;
             idle_timeout_minutes: z.ZodDefault<z.ZodNumber>;
-            classifier_budget: z.ZodDefault<z.ZodNumber>;
+            dispatcher_budget: z.ZodDefault<z.ZodNumber>;
             classifier_model: z.ZodDefault<z.ZodString>;
         }, z.core.$strip>>;
     }, z.core.$strip>>;

package/dist/core/schema.js

@@ -16,7 +16,7 @@ const SessionConfigSchema = z.object({
     enabled: z.boolean().default(true),
     max_per_user: z.number().int().positive().default(3),
     idle_timeout_minutes: z.number().positive().default(30),
-    classifier_budget: z.number().nonnegative().default(0.05),
+    dispatcher_budget: z.number().nonnegative().default(0.05),
     classifier_model: z.string().default(""),
 });
 const AgentConfigSchema = z.object({

package/dist/core/session.d.ts

@@ -7,6 +7,7 @@ export interface SubSession {
     chatId: string;
     claudeSessionId: string | null;
     label: string;
+    summary: string;
     status: "active" | "idle" | "expired" | "closed";
     createdAt: number;
     lastActiveAt: number;
@@ -47,4 +48,13 @@ export declare class SessionManager {
     isUsable(session: SubSession): boolean;
     /** Get all sub-sessions for a user (all statuses) */
     getAll(userId: string): SubSession[];
+    /** Update the summary of a sub-session */
+    updateSummary(sessionId: string, summary: string): void;
+    /** Get summaries of active sub-sessions for dispatcher context */
+    getSummaries(userId: string, platform: string): {
+        id: string;
+        label: string;
+        summary: string;
+        lastActiveAt: number;
+    }[];
 }

package/dist/core/session.js

@@ -10,6 +10,7 @@ function toSubSession(row) {
         chatId: row.chat_id,
         claudeSessionId: row.claude_session_id ?? null,
         label: row.label,
+        summary: row.summary ?? "",
         status: row.status,
         createdAt: row.created_at,
         lastActiveAt: row.last_active_at,
@@ -97,4 +98,14 @@ export class SessionManager {
     getAll(userId) {
         return this.store.getAllSubSessions(userId).map(toSubSession);
     }
+    /** Update the summary of a sub-session */
+    updateSummary(sessionId, summary) {
+        this.store.updateSubSessionSummary(sessionId, summary);
+    }
+    /** Get summaries of active sub-sessions for dispatcher context */
+    getSummaries(userId, platform) {
+        return this.store.getSubSessionSummaries(userId, platform).map(r => ({
+            id: r.id, label: r.label, summary: r.summary, lastActiveAt: r.last_active_at,
+        }));
+    }
 }

package/dist/core/store.d.ts

@@ -145,4 +145,11 @@ export declare class Store {
         message_count: number;
         total_cost: number;
     }[];
+    updateSubSessionSummary(id: string, summary: string): void;
+    getSubSessionSummaries(userId: string, platform: string): {
+        id: string;
+        label: string;
+        summary: string;
+        last_active_at: number;
+    }[];
 }

package/dist/core/store.js

@@ -81,7 +81,7 @@ export class Store {
         PRIMARY KEY (platform_msg_id, chat_id)
       );
     `);
-        // Schema migration: add parent_id, result, and scheduled_at columns
+        // Schema migration: add parent_id, result, scheduled_at, and sub_session summary columns
         try {
             this.db.exec("ALTER TABLE tasks ADD COLUMN parent_id INTEGER");
         }
@@ -94,6 +94,10 @@ export class Store {
             this.db.exec("ALTER TABLE tasks ADD COLUMN scheduled_at INTEGER");
         }
         catch { }
+        try {
+            this.db.exec("ALTER TABLE sub_sessions ADD COLUMN summary TEXT DEFAULT ''");
+        }
+        catch { }
         this.db.exec("CREATE INDEX IF NOT EXISTS idx_tasks_parent ON tasks(parent_id)");
         // Startup recovery: reset orphaned 'running' tasks back to 'auto' so they get re-executed
         const orphaned = this.db.prepare("SELECT id, description FROM tasks WHERE status = 'running'").all();
@@ -309,4 +313,10 @@ export class Store {
     getAllSubSessions(userId) {
         return this.db.prepare("SELECT * FROM sub_sessions WHERE user_id = ? ORDER BY last_active_at DESC").all(userId);
     }
+    updateSubSessionSummary(id, summary) {
+        this.db.prepare("UPDATE sub_sessions SET summary = ? WHERE id = ?").run(summary, id);
+    }
+    getSubSessionSummaries(userId, platform) {
+        return this.db.prepare("SELECT id, label, summary, last_active_at FROM sub_sessions WHERE user_id = ? AND platform = ? AND status IN ('active','idle') ORDER BY last_active_at DESC").all(userId, platform);
+    }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emqo/claudebridge",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "Bridge claude CLI to chat platforms (Telegram, Discord) with scheduled auto-tasks, autonomous project management, HITL approval, conditional branching, webhook triggers, parallel execution, and observability",
   "main": "dist/index.js",
   "bin": {