multiclaws 0.3.4 → 0.4.0

package/dist/gateway/handlers.js

@@ -8,11 +8,16 @@ const agentAddSchema = zod_1.z.object({
     apiKey: zod_1.z.string().trim().min(1).optional(),
 });
 const agentRemoveSchema = zod_1.z.object({ url: nonEmptyString });
-const taskDelegateSchema = zod_1.z.object({
+const sessionStartSchema = zod_1.z.object({
     agentUrl: nonEmptyString,
-    task: nonEmptyString,
+    message: nonEmptyString,
 });
-const taskStatusSchema = zod_1.z.object({ taskId: nonEmptyString });
+const sessionReplySchema = zod_1.z.object({
+    sessionId: nonEmptyString,
+    message: nonEmptyString,
+});
+const sessionStatusSchema = zod_1.z.object({ sessionId: zod_1.z.string().trim().min(1).optional() });
+const sessionEndSchema = zod_1.z.object({ sessionId: nonEmptyString });
 const profileSetSchema = zod_1.z.object({
     ownerName: zod_1.z.string().trim().optional(),
     bio: zod_1.z.string().optional(),
@@ -57,34 +62,59 @@ function createGatewayHandlers(getService) {
                 safeHandle(respond, "invalid_params", error);
             }
         },
-        /* ── Task handlers ──────────────────────────────────────────── */
-        "multiclaws.task.delegate": async ({ params, respond }) => {
+        /* ── Session handlers ───────────────────────────────────────── */
+        "multiclaws.session.start": async ({ params, respond }) => {
             try {
-                const parsed = taskDelegateSchema.parse(params);
+                const parsed = sessionStartSchema.parse(params);
                 const service = getService();
-                const result = await service.delegateTask(parsed);
+                const result = await service.startSession(parsed);
                 respond(true, result);
             }
             catch (error) {
-                safeHandle(respond, "task_delegate_failed", error);
+                safeHandle(respond, "session_start_failed", error);
             }
         },
-        "multiclaws.task.status": async ({ params, respond }) => {
+        "multiclaws.session.reply": async ({ params, respond }) => {
             try {
-                const parsed = taskStatusSchema.parse(params);
+                const parsed = sessionReplySchema.parse(params);
                 const service = getService();
-                const task = service.getTaskStatus(parsed.taskId);
-                if (!task) {
-                    respond(false, undefined, {
-                        code: "not_found",
-                        message: `task not found: ${parsed.taskId}`,
-                    });
-                    return;
+                const result = await service.sendSessionMessage(parsed);
+                respond(true, result);
+            }
+            catch (error) {
+                safeHandle(respond, "session_reply_failed", error);
+            }
+        },
+        "multiclaws.session.status": async ({ params, respond }) => {
+            try {
+                const parsed = sessionStatusSchema.parse(params);
+                const service = getService();
+                if (parsed.sessionId) {
+                    const session = service.getSession(parsed.sessionId);
+                    if (!session) {
+                        respond(false, undefined, { code: "not_found", message: `session not found: ${parsed.sessionId}` });
+                        return;
+                    }
+                    respond(true, session);
+                }
+                else {
+                    const sessions = service.listSessions();
+                    respond(true, { sessions });
                 }
-                respond(true, { task });
             }
             catch (error) {
-                safeHandle(respond, "task_status_failed", error);
+                safeHandle(respond, "session_status_failed", error);
+            }
+        },
+        "multiclaws.session.end": async ({ params, respond }) => {
+            try {
+                const parsed = sessionEndSchema.parse(params);
+                const service = getService();
+                const ok = service.endSession(parsed.sessionId);
+                respond(true, { ended: ok });
+            }
+            catch (error) {
+                safeHandle(respond, "session_end_failed", error);
             }
         },
         /* ── Team handlers ──────────────────────────────────────────── */

package/dist/index.js

@@ -87,48 +87,92 @@ function createTools(getService) {
             return textResult(removed ? `Agent ${url} removed.` : `Agent ${url} not found.`);
         },
     };
-    const multiclawsDelegate = {
-        name: "multiclaws_delegate",
-        description: "Delegate a task to a remote A2A agent.",
+    /* ── Session tools (multi-turn collaboration) ─────────────────── */
+    const multiclawsSessionStart = {
+        name: "multiclaws_session_start",
+        description: "Start a multi-turn collaboration session with a remote agent. Sends the first message and returns immediately with a sessionId (async). The agent's response will be pushed as a message when ready. Covers both single-turn and multi-turn use cases.",
         parameters: {
             type: "object",
             additionalProperties: false,
             properties: {
                 agentUrl: { type: "string" },
-                task: { type: "string" },
+                message: { type: "string" },
             },
-            required: ["agentUrl", "task"],
+            required: ["agentUrl", "message"],
         },
         execute: async (_toolCallId, args) => {
             const service = requireService(getService());
             const agentUrl = typeof args.agentUrl === "string" ? args.agentUrl.trim() : "";
-            const task = typeof args.task === "string" ? args.task.trim() : "";
-            if (!agentUrl || !task)
-                throw new Error("agentUrl and task are required");
-            const result = await service.delegateTask({ agentUrl, task });
+            const message = typeof args.message === "string" ? args.message.trim() : "";
+            if (!agentUrl || !message)
+                throw new Error("agentUrl and message are required");
+            const result = await service.startSession({ agentUrl, message });
             return textResult(JSON.stringify(result, null, 2), result);
         },
     };
-    const multiclawsTaskStatus = {
-        name: "multiclaws_task_status",
-        description: "Check the status of a delegated task.",
+    const multiclawsSessionReply = {
+        name: "multiclaws_session_reply",
+        description: "Send a follow-up message in an existing collaboration session. Use when the remote agent returns 'input-required' or to continue a multi-turn conversation.",
         parameters: {
             type: "object",
             additionalProperties: false,
             properties: {
-                taskId: { type: "string" },
+                sessionId: { type: "string" },
+                message: { type: "string" },
             },
-            required: ["taskId"],
+            required: ["sessionId", "message"],
         },
         execute: async (_toolCallId, args) => {
             const service = requireService(getService());
-            const taskId = typeof args.taskId === "string" ? args.taskId.trim() : "";
-            if (!taskId)
-                throw new Error("taskId is required");
-            const task = service.getTaskStatus(taskId);
-            if (!task)
-                throw new Error(`task not found: ${taskId}`);
-            return textResult(JSON.stringify(task, null, 2), task);
+            const sessionId = typeof args.sessionId === "string" ? args.sessionId.trim() : "";
+            const message = typeof args.message === "string" ? args.message.trim() : "";
+            if (!sessionId || !message)
+                throw new Error("sessionId and message are required");
+            const result = await service.sendSessionMessage({ sessionId, message });
+            return textResult(JSON.stringify(result, null, 2), result);
+        },
+    };
+    const multiclawsSessionStatus = {
+        name: "multiclaws_session_status",
+        description: "Get the status and message history of a collaboration session. If sessionId is omitted, lists all sessions.",
+        parameters: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                sessionId: { type: "string" },
+            },
+        },
+        execute: async (_toolCallId, args) => {
+            const service = requireService(getService());
+            const sessionId = typeof args.sessionId === "string" ? args.sessionId.trim() : "";
+            if (sessionId) {
+                const session = service.getSession(sessionId);
+                if (!session)
+                    throw new Error(`session not found: ${sessionId}`);
+                return textResult(JSON.stringify(session, null, 2), session);
+            }
+            const sessions = service.listSessions();
+            return textResult(JSON.stringify({ sessions }, null, 2), { sessions });
+        },
+    };
+    const multiclawsSessionEnd = {
+        name: "multiclaws_session_end",
+        description: "Cancel and close a collaboration session.",
+        parameters: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                sessionId: { type: "string" },
+            },
+            required: ["sessionId"],
+        },
+        execute: async (_toolCallId, args) => {
+            const service = requireService(getService());
+            const sessionId = typeof args.sessionId === "string" ? args.sessionId.trim() : "";
+            if (!sessionId)
+                throw new Error("sessionId is required");
+            const ok = service.endSession(sessionId);
+            return textResult(ok ? `Session ${sessionId} ended.` : `Session ${sessionId} not found.`);
         },
     };
     /* ── Team tools ───────────────────────────────────────────────── */
@@ -280,8 +324,10 @@ function createTools(getService) {
         multiclawsAgents,
         multiclawsAddAgent,
         multiclawsRemoveAgent,
-        multiclawsDelegate,
-        multiclawsTaskStatus,
+        multiclawsSessionStart,
+        multiclawsSessionReply,
+        multiclawsSessionStatus,
+        multiclawsSessionEnd,
         multiclawsTeamCreate,
         multiclawsTeamJoin,
         multiclawsTeamLeave,

package/dist/service/multiclaws-service.d.ts

@@ -2,6 +2,7 @@ import { EventEmitter } from "node:events";
 import { type AgentRecord } from "./agent-registry";
 import { type AgentProfile } from "./agent-profile";
 import { type TeamRecord, type TeamMember } from "../team/team-store";
+import { type ConversationSession } from "./session-store";
 import type { GatewayConfig } from "../infra/gateway-client";
 export type MulticlawsServiceOptions = {
     stateDir: string;
@@ -16,10 +17,14 @@ export type MulticlawsServiceOptions = {
         debug?: (message: string) => void;
     };
 };
-export type DelegateTaskResult = {
-    taskId?: string;
-    output?: string;
-    status: string;
+export type SessionStartResult = {
+    sessionId: string;
+    status: "running" | "failed";
+    error?: string;
+};
+export type SessionReplyResult = {
+    sessionId: string;
+    status: "ok" | "failed";
     error?: string;
 };
 export declare class MulticlawsService extends EventEmitter {
@@ -30,6 +35,7 @@ export declare class MulticlawsService extends EventEmitter {
     private readonly teamStore;
     private readonly profileStore;
     private readonly taskTracker;
+    private readonly sessionStore;
     private agentExecutor;
     private a2aRequestHandler;
     private agentCard;
@@ -47,11 +53,20 @@ export declare class MulticlawsService extends EventEmitter {
         apiKey?: string;
     }): Promise<AgentRecord>;
     removeAgent(url: string): Promise<boolean>;
-    delegateTask(params: {
+    startSession(params: {
         agentUrl: string;
-        task: string;
-    }): Promise<DelegateTaskResult>;
-    getTaskStatus(taskId: string): import("../task/tracker").TaskRecord | null;
+        message: string;
+    }): Promise<SessionStartResult>;
+    sendSessionMessage(params: {
+        sessionId: string;
+        message: string;
+    }): Promise<SessionReplyResult>;
+    getSession(sessionId: string): ConversationSession | null;
+    listSessions(): ConversationSession[];
+    endSession(sessionId: string): boolean;
+    private runSession;
+    private handleSessionResult;
+    private notifySessionUpdate;
     getProfile(): Promise<AgentProfile>;
     setProfile(patch: {
         ownerName?: string;
@@ -84,7 +99,6 @@ export declare class MulticlawsService extends EventEmitter {
     private fetchMemberDescriptions;
     private syncTeamToRegistry;
     private createA2AClient;
-    private processTaskResult;
     private extractArtifactText;
     private notifyTailscaleSetup;
     /** Fetch with up to 2 retries and exponential backoff. */

package/dist/service/multiclaws-service.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MulticlawsService = void 0;
 const node_events_1 = require("node:events");
+const node_crypto_1 = require("node:crypto");
 const node_os_1 = __importDefault(require("node:os"));
 const node_http_1 = __importDefault(require("node:http"));
 const node_path_1 = __importDefault(require("node:path"));
@@ -20,6 +21,7 @@ const agent_registry_1 = require("./agent-registry");
 const agent_profile_1 = require("./agent-profile");
 const team_store_1 = require("../team/team-store");
 const tracker_1 = require("../task/tracker");
+const session_store_1 = require("./session-store");
 const zod_1 = require("zod");
 const gateway_client_1 = require("../infra/gateway-client");
 const rate_limiter_1 = require("../infra/rate-limiter");
@@ -34,6 +36,7 @@ class MulticlawsService extends node_events_1.EventEmitter {
     teamStore;
     profileStore;
     taskTracker;
+    sessionStore;
     agentExecutor = null;
     a2aRequestHandler = null;
     agentCard = null;
@@ -51,6 +54,9 @@ class MulticlawsService extends node_events_1.EventEmitter {
         this.taskTracker = new tracker_1.TaskTracker({
             filePath: node_path_1.default.join(multiclawsStateDir, "tasks.json"),
         });
+        this.sessionStore = new session_store_1.SessionStore({
+            filePath: node_path_1.default.join(multiclawsStateDir, "sessions.json"),
+        });
         const port = options.port ?? 3100;
         // selfUrl resolved later in start() after Tailscale detection; use placeholder for now
         this.selfUrl = options.selfUrl ?? `http://${getLocalIp()}:${port}`;
@@ -194,37 +200,208 @@ class MulticlawsService extends node_events_1.EventEmitter {
     /* ---------------------------------------------------------------- */
     /*  Task delegation                                                  */
     /* ---------------------------------------------------------------- */
-    async delegateTask(params) {
+    /* ---------------------------------------------------------------- */
+    /*  Session management (multi-turn collaboration)                  */
+    /* ---------------------------------------------------------------- */
+    async startSession(params) {
         const agentRecord = await this.agentRegistry.get(params.agentUrl);
         if (!agentRecord) {
-            return { status: "failed", error: `unknown agent: ${params.agentUrl}` };
+            return { sessionId: "", status: "failed", error: `unknown agent: ${params.agentUrl}` };
         }
-        const track = this.taskTracker.create({
-            fromPeerId: "local",
-            toPeerId: params.agentUrl,
-            task: params.task,
+        const contextId = (0, node_crypto_1.randomUUID)();
+        const session = this.sessionStore.create({
+            agentUrl: params.agentUrl,
+            agentName: agentRecord.name,
+            contextId,
+        });
+        this.sessionStore.appendMessage(session.sessionId, {
+            role: "user",
+            content: params.message,
+            timestampMs: Date.now(),
         });
-        this.taskTracker.update(track.taskId, { status: "running" });
+        void this.runSession({
+            sessionId: session.sessionId,
+            agentRecord,
+            message: params.message,
+            contextId,
+            taskId: undefined,
+        });
+        return { sessionId: session.sessionId, status: "running" };
+    }
+    async sendSessionMessage(params) {
+        const session = this.sessionStore.get(params.sessionId);
+        if (!session) {
+            return { sessionId: params.sessionId, status: "failed", error: "session not found" };
+        }
+        if (session.status !== "input-required" && session.status !== "active") {
+            return { sessionId: params.sessionId, status: "failed", error: `session is ${session.status}, cannot send message` };
+        }
+        this.sessionStore.appendMessage(params.sessionId, {
+            role: "user",
+            content: params.message,
+            timestampMs: Date.now(),
+        });
+        this.sessionStore.update(params.sessionId, { status: "active" });
+        const agentRecord = await this.agentRegistry.get(session.agentUrl);
+        if (!agentRecord) {
+            this.sessionStore.update(params.sessionId, { status: "failed", error: "agent no longer registered" });
+            return { sessionId: params.sessionId, status: "failed", error: "agent no longer registered" };
+        }
+        void this.runSession({
+            sessionId: params.sessionId,
+            agentRecord,
+            message: params.message,
+            contextId: session.contextId,
+            taskId: session.currentTaskId,
+        });
+        return { sessionId: params.sessionId, status: "ok" };
+    }
+    getSession(sessionId) {
+        return this.sessionStore.get(sessionId);
+    }
+    listSessions() {
+        return this.sessionStore.list();
+    }
+    endSession(sessionId) {
+        const session = this.sessionStore.get(sessionId);
+        if (!session)
+            return false;
+        this.sessionStore.update(sessionId, { status: "canceled" });
+        return true;
+    }
+    async runSession(params) {
+        const timeout = params.timeoutMs ?? 5 * 60 * 1000; // 5 min default
+        const timeoutController = new AbortController();
+        const timer = setTimeout(() => timeoutController.abort(), timeout);
         try {
-            const client = await this.createA2AClient(agentRecord);
-            const result = await client.sendMessage({
-                message: {
-                    kind: "message",
-                    role: "user",
-                    parts: [{ kind: "text", text: params.task }],
-                    messageId: track.taskId,
-                },
-            });
-            return this.processTaskResult(track.taskId, result);
+            const client = await this.createA2AClient(params.agentRecord);
+            const result = await Promise.race([
+                client.sendMessage({
+                    message: {
+                        kind: "message",
+                        role: "user",
+                        parts: [{ kind: "text", text: params.message }],
+                        messageId: (0, node_crypto_1.randomUUID)(),
+                        contextId: params.contextId,
+                        ...(params.taskId ? { taskId: params.taskId } : {}),
+                    },
+                }),
+                new Promise((_, reject) => timeoutController.signal.addEventListener("abort", () => reject(new Error("session timeout")))),
+            ]);
+            await this.handleSessionResult(params.sessionId, result);
         }
         catch (err) {
             const errorMsg = err instanceof Error ? err.message : String(err);
-            this.taskTracker.update(track.taskId, { status: "failed", error: errorMsg });
-            return { taskId: track.taskId, status: "failed", error: errorMsg };
+            this.sessionStore.update(params.sessionId, { status: "failed", error: errorMsg });
+            await this.notifySessionUpdate(params.sessionId, "failed");
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    async handleSessionResult(sessionId, result) {
+        // Extract content
+        let content = "";
+        let state = "completed";
+        let remoteTaskId;
+        if ("status" in result && result.status) {
+            const task = result;
+            state = task.status?.state ?? "completed";
+            remoteTaskId = task.id;
+            content = this.extractArtifactText(task);
+            // Also try to get text from task messages if artifacts empty
+            if (!content && task.history?.length) {
+                const lastAgentMsg = [...task.history].reverse().find((m) => m.role === "agent");
+                if (lastAgentMsg) {
+                    content = lastAgentMsg.parts
+                        ?.filter((p) => p.kind === "text")
+                        .map((p) => p.text)
+                        .join("\n") ?? "";
+                }
+            }
+        }
+        else {
+            const msg = result;
+            remoteTaskId = msg.taskId;
+            content = msg.parts
+                ?.filter((p) => p.kind === "text")
+                .map((p) => p.text)
+                .join("\n") ?? "";
+        }
+        // Append agent message to history
+        if (content) {
+            this.sessionStore.appendMessage(sessionId, {
+                role: "agent",
+                content,
+                timestampMs: Date.now(),
+                taskId: remoteTaskId,
+            });
+        }
+        // Update session state
+        if (state === "input-required" || state === "auth-required") {
+            this.sessionStore.update(sessionId, {
+                status: "input-required",
+                currentTaskId: remoteTaskId,
+            });
+            await this.notifySessionUpdate(sessionId, "input-required");
+        }
+        else if (state === "failed" || state === "rejected") {
+            this.sessionStore.update(sessionId, {
+                status: "failed",
+                currentTaskId: remoteTaskId,
+                error: content || "remote task failed",
+            });
+            await this.notifySessionUpdate(sessionId, "failed");
+        }
+        else if (state === "completed" || state === "canceled") {
+            this.sessionStore.update(sessionId, {
+                status: "completed",
+                currentTaskId: remoteTaskId,
+            });
+            await this.notifySessionUpdate(sessionId, "completed");
+        }
+        else {
+            // working / submitted / unknown — still in progress, no notification
+            this.sessionStore.update(sessionId, { currentTaskId: remoteTaskId });
         }
     }
-    getTaskStatus(taskId) {
-        return this.taskTracker.get(taskId);
+    async notifySessionUpdate(sessionId, event) {
+        if (!this.options.gatewayConfig)
+            return;
+        const session = this.sessionStore.get(sessionId);
+        if (!session)
+            return;
+        const lastAgentMsg = [...session.messages].reverse().find((m) => m.role === "agent");
+        const content = lastAgentMsg?.content ?? "";
+        const agentName = session.agentName;
+        let message;
+        if (event === "completed") {
+            message = [`✅ **${agentName} 任务完成** (session: \`${sessionId}\`)`, "", content].join("\n");
+        }
+        else if (event === "input-required") {
+            message = [
+                `📨 **${agentName} 需要补充信息** (session: \`${sessionId}\`)`,
+                "",
+                content,
+                "",
+                `→ 回复请用 \`multiclaws_session_reply\` 工具，sessionId: \`${sessionId}\``,
+            ].join("\n");
+        }
+        else {
+            const error = session.error ?? content;
+            message = [`❌ **${agentName} 任务失败** (session: \`${sessionId}\`)`, "", error].join("\n");
+        }
+        try {
+            await (0, gateway_client_1.invokeGatewayTool)({
+                gateway: this.options.gatewayConfig,
+                tool: "message",
+                args: { action: "send", message },
+                timeoutMs: 5_000,
+            });
+        }
+        catch {
+            this.log("warn", `[multiclaws] failed to notify session update: ${sessionId}`);
+        }
     }
     /* ---------------------------------------------------------------- */
     /*  Profile                                                          */
@@ -602,27 +779,6 @@ class MulticlawsService extends node_events_1.EventEmitter {
     async createA2AClient(agent) {
         return await this.clientFactory.createFromUrl(agent.url);
     }
-    processTaskResult(trackId, result) {
-        if ("status" in result && result.status) {
-            const task = result;
-            const state = task.status?.state ?? "unknown";
-            const output = this.extractArtifactText(task);
-            if (state === "completed") {
-                this.taskTracker.update(trackId, { status: "completed", result: output });
-            }
-            else if (state === "failed") {
-                this.taskTracker.update(trackId, { status: "failed", error: output || "remote task failed" });
-            }
-            return { taskId: task.id, output, status: state };
-        }
-        const msg = result;
-        const text = msg.parts
-            ?.filter((p) => p.kind === "text")
-            .map((p) => p.text)
-            .join("\n") ?? "";
-        this.taskTracker.update(trackId, { status: "completed", result: text });
-        return { taskId: trackId, output: text, status: "completed" };
-    }
     extractArtifactText(task) {
         if (!task.artifacts?.length)
             return "";

package/dist/service/session-store.d.ts

@@ -0,0 +1,43 @@
+export type SessionStatus = "active" | "input-required" | "completed" | "failed" | "canceled";
+export type SessionMessage = {
+    role: "user" | "agent";
+    content: string;
+    timestampMs: number;
+    taskId?: string;
+};
+export type ConversationSession = {
+    sessionId: string;
+    agentUrl: string;
+    agentName: string;
+    contextId: string;
+    currentTaskId?: string;
+    status: SessionStatus;
+    messages: SessionMessage[];
+    createdAtMs: number;
+    updatedAtMs: number;
+    error?: string;
+};
+export declare class SessionStore {
+    private readonly filePath;
+    private readonly ttlMs;
+    private store;
+    private persistPending;
+    constructor(opts: {
+        filePath: string;
+        ttlMs?: number;
+    });
+    create(params: {
+        agentUrl: string;
+        agentName: string;
+        contextId: string;
+    }): ConversationSession;
+    get(sessionId: string): ConversationSession | null;
+    list(): ConversationSession[];
+    update(sessionId: string, patch: Partial<Omit<ConversationSession, "sessionId" | "createdAtMs">>): ConversationSession | null;
+    appendMessage(sessionId: string, msg: SessionMessage): ConversationSession | null;
+    private loadSync;
+    private schedulePersist;
+    private persistAsync;
+    private prune;
+    private evictOldest;
+}

package/dist/service/session-store.js

@@ -0,0 +1,124 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionStore = void 0;
+const node_crypto_1 = require("node:crypto");
+const node_fs_1 = __importDefault(require("node:fs"));
+const promises_1 = __importDefault(require("node:fs/promises"));
+const node_path_1 = __importDefault(require("node:path"));
+const DEFAULT_TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+const MAX_SESSIONS = 1_000;
+function emptyStore() {
+    return { version: 1, sessions: [] };
+}
+class SessionStore {
+    filePath;
+    ttlMs;
+    store;
+    persistPending = false;
+    constructor(opts) {
+        this.filePath = opts.filePath;
+        this.ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+        this.store = this.loadSync();
+    }
+    create(params) {
+        this.prune();
+        const now = Date.now();
+        const session = {
+            sessionId: (0, node_crypto_1.randomUUID)(),
+            agentUrl: params.agentUrl,
+            agentName: params.agentName,
+            contextId: params.contextId,
+            status: "active",
+            messages: [],
+            createdAtMs: now,
+            updatedAtMs: now,
+        };
+        if (this.store.sessions.length >= MAX_SESSIONS) {
+            this.evictOldest();
+        }
+        this.store.sessions.push(session);
+        this.schedulePersist();
+        return session;
+    }
+    get(sessionId) {
+        return this.store.sessions.find((s) => s.sessionId === sessionId) ?? null;
+    }
+    list() {
+        return [...this.store.sessions].sort((a, b) => b.updatedAtMs - a.updatedAtMs);
+    }
+    update(sessionId, patch) {
+        const idx = this.store.sessions.findIndex((s) => s.sessionId === sessionId);
+        if (idx < 0)
+            return null;
+        const next = {
+            ...this.store.sessions[idx],
+            ...patch,
+            updatedAtMs: Date.now(),
+        };
+        this.store.sessions[idx] = next;
+        this.schedulePersist();
+        return next;
+    }
+    appendMessage(sessionId, msg) {
+        const session = this.get(sessionId);
+        if (!session)
+            return null;
+        return this.update(sessionId, {
+            messages: [...session.messages, msg],
+        });
+    }
+    loadSync() {
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(this.filePath), { recursive: true });
+        try {
+            const raw = JSON.parse(node_fs_1.default.readFileSync(this.filePath, "utf8"));
+            if (raw.version !== 1 || !Array.isArray(raw.sessions))
+                return emptyStore();
+            return raw;
+        }
+        catch {
+            const store = emptyStore();
+            node_fs_1.default.writeFileSync(this.filePath, JSON.stringify(store, null, 2), "utf8");
+            return store;
+        }
+    }
+    schedulePersist() {
+        if (this.persistPending)
+            return;
+        this.persistPending = true;
+        queueMicrotask(() => {
+            this.persistPending = false;
+            void this.persistAsync();
+        });
+    }
+    async persistAsync() {
+        try {
+            await promises_1.default.mkdir(node_path_1.default.dirname(this.filePath), { recursive: true });
+            const tmp = `${this.filePath}.${process.pid}.${Date.now()}.tmp`;
+            await promises_1.default.writeFile(tmp, JSON.stringify(this.store, null, 2), "utf8");
+            await promises_1.default.rename(tmp, this.filePath);
+        }
+        catch {
+            // best-effort
+        }
+    }
+    prune() {
+        const cutoff = Date.now() - this.ttlMs;
+        this.store.sessions = this.store.sessions.filter((s) => {
+            if (s.updatedAtMs >= cutoff)
+                return true;
+            return s.status !== "completed" && s.status !== "failed" && s.status !== "canceled";
+        });
+    }
+    evictOldest() {
+        const removable = [...this.store.sessions]
+            .filter((s) => s.status === "completed" || s.status === "failed" || s.status === "canceled")
+            .sort((a, b) => a.updatedAtMs - b.updatedAtMs)
+            .slice(0, Math.max(1, Math.floor(MAX_SESSIONS / 4)));
+        const ids = new Set(removable.map((s) => s.sessionId));
+        this.store.sessions = this.store.sessions.filter((s) => !ids.has(s.sessionId));
+    }
+}
+exports.SessionStore = SessionStore;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "multiclaws",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "MultiClaws plugin for OpenClaw collaboration via A2A protocol",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/skills/multiclaws/SKILL.md

@@ -1,87 +1,111 @@
 # MultiClaws — 技能行为
 
-以下规则在插件安装后生效，指导 AI 如何使用 MultiClaws 工具。
-
-MultiClaws 让多个 OpenClaw 实例通过 [A2A（Agent-to-Agent）](https://google.github.io/A2A/) 协议组成团队、互相委派任务。
+MultiClaws 让多个 OpenClaw 实例通过 [A2A（Agent-to-Agent）](https://google.github.io/A2A/) 协议组成团队、互相委派和协作任务。
 
 ---
 
 ## 1. 首次安装：档案初始化（由插件 hook 触发）
 
 首次安装后，插件会通过 `before_prompt_build` hook 自动在系统提示中注入初始化任务。
-**无需每次对话手动检查 `multiclaws_profile_pending_review()`**，hook 已处理触发时机。
 
 当 hook 注入了初始化任务时，按以下步骤执行：
 
-1. **扫描当前环境**，自动生成 bio（markdown 格式），包含：
-   - 可用的工具和 skills（推断能力）
-   - 已连接的渠道（Telegram、Discord、Gmail 等）
-   - 工作区内容（git 仓库、关键文件、项目目录）
-   - 已安装的插件
-   - 时区、语言等上下文
+1. **扫描当前环境**，自动生成 bio（markdown 格式）
+2. 向用户展示，逐一确认：
+   - **名字**：询问是否需要修改（需用户明确回答）
+   - **Bio**：询问是否需要修改（需用户明确回答）
+   - **网络情况**：告知「同局域网开箱即用；跨网络需安装 Tailscale」，无需用户回答
+3. 调用 `multiclaws_profile_set(ownerName="...", bio="...")` 保存
+4. 调用 `multiclaws_profile_clear_pending_review()` 完成初始化
 
-2. 向用户展示生成的档案，并逐一确认以下三项：
-   - **名字**：展示推断出的名字，询问是否需要修改（需用户明确回答）
-   - **Bio**：展示生成的 bio，询问是否需要修改（需用户明确回答）
-   - **网络情况**：告知用户「同局域网开箱即用；跨网络需安装 Tailscale（https://tailscale.com/download）并重启 OpenClaw」，无需用户回答
+---
 
-3. 根据用户对名字和 bio 的回答更新内容后，调用 `multiclaws_profile_set(ownerName="...", bio="...")` 保存档案。
+## 2. 协作任务（Session）
 
-4. 调用 `multiclaws_profile_clear_pending_review()` 完成初始化。
+**所有委派任务均通过 session 进行**，支持单轮和多轮场景。
 
-**示例 bio：**
-```markdown
-后端工程师，负责 API 服务开发与维护。
+### 开始协作
+```
+multiclaws_session_start(agentUrl="...", message="任务描述")
+→ 立即返回 sessionId，任务在后台运行
+→ 完成后自动推送消息通知
+```
 
-**可处理：**
-- 代码审查、调试、重构（Node.js / Go / Python）
-- API 文档编写与接口设计
-- 数据库查询与优化（PostgreSQL）
+### 远端需要补充信息（input-required）
+收到 `📨 AgentName 需要补充信息` 通知后：
+```
+multiclaws_session_reply(sessionId="...", message="补充内容")
+→ 继续会话，后台处理，完成后推送通知
+```
 
-**数据访问：**
-- Codebase: `/Users/eric/Project/api-service`（Node.js，~50k LOC）
-- Email: Gmail
-- Calendar: Google Calendar
+### 查看会话状态
+```
+multiclaws_session_status()              → 列出所有会话
+multiclaws_session_status(sessionId="...") → 查看单个会话及消息历史
+```
 
-**时区：** GMT+8
+### 结束会话
+```
+multiclaws_session_end(sessionId="...")  → 取消并关闭会话
 ```
 
----
+### 并发协作
+可同时开启多个 session，各自独立运行：
+```
+multiclaws_session_start(agentUrl=B, message="任务1") → sessionId_1
+multiclaws_session_start(agentUrl=C, message="任务2") → sessionId_2
+```
+
+### 链式协作（A→B→C）
+B 内部可以自己调用 `multiclaws_session_start` 委派给 C，结果自然冒泡回 A。
 
-## 2. 团队操作前检查档案
+---
 
-在 **创建团队** 或 **加入团队** 之前：
+## 3. 智能委派流程
 
 ```
-multiclaws_profile_show()
+1. multiclaws_team_members()          → 列出所有成员，读 bio
+2. 选择 bio 最匹配任务的 agent
+3. multiclaws_session_start(agentUrl, message)
+4. 等待推送通知（或用 session_status 查进度）
+5. 如收到 input-required 通知 → multiclaws_session_reply 回复
 ```
 
-如果 `bio` 为空或 `ownerName` 为空：
-1. 自动生成 bio（同上）
-2. 询问用户确认名字和 bio
-3. 调用 `multiclaws_profile_set(...)` 设置
-4. 然后继续团队操作
+**选择 agent 原则：**
+- 匹配任务领域（「财务报告」→ 有财务技能的 agent）
+- 匹配数据访问（「检查代码」→ bio 中有该代码库的 agent）
+- 多个匹配时选最具体的
 
 ---
 
-## 3. 保持档案更新
+## 4. 团队操作前检查档案
 
-档案是动态的。在以下情况自动更新（调用 `multiclaws_profile_set`）：
-- 用户连接了新渠道或数据源
-- 用户安装了新 skill 或插件
-- 用户的角色或关注点发生变化
+在创建或加入团队之前：
 
-不要等用户说「更新档案」，主动更新并简要提及即可。
+```
+multiclaws_profile_show()
+```
+
+如果 `bio` 为空或 `ownerName` 为空，先完成档案设置再继续。
 
 ---
 
 ## 工具列表
 
+### 协作 Session
+
+| 工具 | 说明 | 参数 |
+|------|------|------|
+| `multiclaws_session_start` | 开始协作会话（替代旧 delegate） | `agentUrl`, `message` |
+| `multiclaws_session_reply` | 在会话中发送后续消息 | `sessionId`, `message` |
+| `multiclaws_session_status` | 查看会话状态和消息历史 | `sessionId`（可选，不传返回全部） |
+| `multiclaws_session_end` | 取消/关闭会话 | `sessionId` |
+
 ### 档案
 
 | 工具 | 说明 | 参数 |
 |------|------|------|
-| `multiclaws_profile_set` | 设置名字和 bio | `ownerName`（可选）, `bio`（可选，markdown） |
+| `multiclaws_profile_set` | 设置名字和 bio | `ownerName`（可选）, `bio`（可选） |
 | `multiclaws_profile_show` | 查看当前档案 | — |
 | `multiclaws_profile_pending_review` | 检查是否有待确认的首次档案 | — |
 | `multiclaws_profile_clear_pending_review` | 清除待确认标记 | — |
@@ -93,75 +117,32 @@ multiclaws_profile_show()
 | `multiclaws_team_create` | 创建团队，返回邀请码 | `name` |
 | `multiclaws_team_join` | 用邀请码加入团队 | `inviteCode` |
 | `multiclaws_team_leave` | 离开团队 | `teamId`（可选） |
-| `multiclaws_team_members` | 列出团队成员 | `teamId`（可选） |
+| `multiclaws_team_members` | 列出所有团队和成员 | `teamId`（可选） |
 
-### 智能体与委派
+### 智能体
 
 | 工具 | 说明 | 参数 |
 |------|------|------|
-| `multiclaws_agents` | 列出所有已知智能体及 bio | — |
-| `multiclaws_add_agent` | 手动添加远端智能体 | `url`, `apiKey`（可选） |
-| `multiclaws_remove_agent` | 移除已知智能体 | `url` |
-| `multiclaws_delegate` | 委派任务给远端智能体 | `agentUrl`, `task` |
-| `multiclaws_task_status` | 查看委派任务状态 | `taskId` |
+| `multiclaws_agents` | 列出已知 agent 及 bio | — |
+| `multiclaws_add_agent` | 手动添加 agent | `url`, `apiKey`（可选） |
+| `multiclaws_remove_agent` | 移除 agent | `url` |
 
 ---
 
 ## 重要规则
 
-- **不要问用户 IP 地址或 selfUrl。** 插件自动处理。
-- **只使用上面列出的工具。** 没有 `multiclaws_status` 工具。
-- **Bio 是自由格式的 markdown。** 写得让另一个 AI 能读懂这个智能体能做什么。
-- **每个智能体就像一个 skill。** 委派时读每个智能体的 bio，选最匹配的。
-- **名字和 bio 必须用户明确确认**；网络情况仅告知，无需用户回答。
-
----
-
-## 工作流
-
-### 创建团队
-
-```
-1. multiclaws_profile_show()              — 检查档案
-2.（如果为空）自动生成并设置 bio，确认名字和 bio
-3. multiclaws_team_create(name="...")     — 返回 inviteCode (mc:xxxx)
-4. 告诉用户把邀请码分享给队友
-```
-
-### 加入团队
-
-```
-1. multiclaws_profile_show()              — 检查档案
-2.（如果为空）自动生成并设置 bio，确认名字和 bio
-3. multiclaws_team_join(inviteCode="mc:xxxx")
-   → 自动同步所有团队成员
-```
-
-### 智能委派
-
-```
-1. multiclaws_agents()                    — 列出智能体，读 bio
-2. 选择 bio 最匹配任务的智能体
-3. multiclaws_delegate(agentUrl="...", task="...")
-4. 把结果返回给用户
-```
-
-选择智能体时：
-- 匹配任务领域和 bio（如「财务报告」→ 有财务技能的智能体）
-- 匹配数据需求（如「检查 API 代码」→ bio 中有该代码库的智能体）
-- 多个匹配时选最具体的
+- **不要问用户 IP 或 selfUrl**，插件自动处理
+- **Bio 是 markdown**，写得让另一个 AI 能读懂这个 agent 能做什么
+- **名字和 bio 必须用户明确确认**；网络情况仅告知
+- **session 超时默认 5 分钟**，超时后 status 变 failed 并推送通知
 
 ---
 
 ## 跨网络
 
-**同局域网：** 开箱即用，无需配置。
-
-**不同网络：** 每人安装 [Tailscale](https://tailscale.com/download) 并登录同一 tailnet，插件自动检测 Tailscale IP。
+**同局域网：** 开箱即用。
 
-当加入或委派因网络错误失败时（ECONNREFUSED、ETIMEDOUT、fetch failed），引导用户：
+**不同网络：** 安装 [Tailscale](https://tailscale.com/download) 并登录同一 tailnet，插件自动检测。
 
-> 你和对方不在同一网络。跨网络协作需要每个成员安装 Tailscale：
-> 1. 下载安装：https://tailscale.com/download
-> 2. 登录同一个 Tailscale 账号（或同一 tailnet）
-> 3. 重启 OpenClaw，插件会自动检测 Tailscale IP
+网络错误时引导用户：
+> 跨网络需要安装 Tailscale：https://tailscale.com/download，登录后重启 OpenClaw。