multiclaws 0.4.36 → 0.4.38

package/README.md

@@ -1,39 +1,39 @@
-# MultiClaws
-
-Multi-agent collaboration plugin for [OpenClaw](https://openclaw.ai). Connect multiple OpenClaw instances into a team and delegate tasks between them using the [A2A protocol](https://google.github.io/A2A/).
-
-[中文文档](README.zh-CN.md)
-
-## Installation
-
-Just tell your AI:
-
-> Run `openclaw plugins install multiclaws` and tell me what it can do.
-
-Your AI handles the rest — installation, configuration, and profile setup — no manual steps required.
-
-## Usage
-
-Everything works through natural language:
-
-- **"Create a team called my-team"** — creates a team and generates an invite code
-- **"Join team with invite code mc:xxxxx"** — join a teammate's team
-- **"Ask Bob to summarize the latest report"** — delegate a task to a teammate's AI
-- **"Show all agents"** — list team members and their capabilities
-
-## How It Works
-
-MultiClaws enables multiple OpenClaw instances to collaborate as a team. Each instance acts as both a client (delegating tasks) and a server (receiving tasks from others). Tasks are executed by the remote AI and results are returned directly.
-
-Works out of the box on the same local network. Cross-network collaboration is also supported.
-
-## Documentation
-
-See [SKILL.md](skills/multiclaws/SKILL.md) for full details.
-
-## Development
-
-```bash
-npm install
-npm run build
-```
+# MultiClaws
+
+Multi-agent collaboration plugin for [OpenClaw](https://openclaw.ai). Connect multiple OpenClaw instances into a team and delegate tasks between them using the [A2A protocol](https://google.github.io/A2A/).
+
+[中文文档](README.zh-CN.md)
+
+## Installation
+
+Just tell your AI:
+
+> Run `openclaw plugins install multiclaws` and tell me what it can do.
+
+Your AI handles the rest — installation, configuration, and profile setup — no manual steps required.
+
+## Usage
+
+Everything works through natural language:
+
+- **"Create a team called my-team"** — creates a team and generates an invite code
+- **"Join team with invite code mc:xxxxx"** — join a teammate's team
+- **"Ask Bob to summarize the latest report"** — delegate a task to a teammate's AI
+- **"Show all agents"** — list team members and their capabilities
+
+## How It Works
+
+MultiClaws enables multiple OpenClaw instances to collaborate as a team. Each instance acts as both a client (delegating tasks) and a server (receiving tasks from others). Tasks are executed by the remote AI and results are returned directly.
+
+Works out of the box on the same local network. Cross-network collaboration is also supported.
+
+## Documentation
+
+See [SKILL.md](skills/multiclaws/SKILL.md) for full details.
+
+## Development
+
+```bash
+npm install
+npm run build
+```

package/README.zh-CN.md

@@ -1,39 +1,39 @@
-# MultiClaws
-
-[OpenClaw](https://openclaw.ai) 多智能体协作插件。将多个 OpenClaw 实例组成团队，通过 [A2A 协议](https://google.github.io/A2A/) 互相委派任务。
-
-[English](README.md)
-
-## 安装
-
-对你的 AI 说：
-
-> 请运行 `openclaw plugins install multiclaws`，安装完成后告诉我这个插件能做什么
-
-AI 会自动完成安装、配置和档案生成，无需手动修改任何文件。
-
-## 使用
-
-一切通过自然语言完成：
-
-- **「创建一个叫 my-team 的团队」** — 创建团队并获取邀请码
-- **「用邀请码 mc:xxxxx 加入团队」** — 加入队友的团队
-- **「让 Bob 总结一下最新报告」** — 把任务委派给队友的 AI
-- **「显示所有智能体」** — 查看团队成员及其能力
-
-## 工作原理
-
-MultiClaws 让多个 OpenClaw 实例作为一个团队协作。每个实例既可以作为客户端（委派任务），也可以作为服务端（接收他人任务）。任务由远端 AI 执行，结果直接返回。
-
-同局域网开箱即用，也支持跨网络协作。
-
-## 详细文档
-
-见 [SKILL.md](skills/multiclaws/SKILL.md)。
-
-## 开发
-
-```bash
-npm install
-npm run build
-```
+# MultiClaws
+
+[OpenClaw](https://openclaw.ai) 多智能体协作插件。将多个 OpenClaw 实例组成团队，通过 [A2A 协议](https://google.github.io/A2A/) 互相委派任务。
+
+[English](README.md)
+
+## 安装
+
+对你的 AI 说：
+
+> 请运行 `openclaw plugins install multiclaws`，安装完成后告诉我这个插件能做什么
+
+AI 会自动完成安装、配置和档案生成，无需手动修改任何文件。
+
+## 使用
+
+一切通过自然语言完成：
+
+- **「创建一个叫 my-team 的团队」** — 创建团队并获取邀请码
+- **「用邀请码 mc:xxxxx 加入团队」** — 加入队友的团队
+- **「让 Bob 总结一下最新报告」** — 把任务委派给队友的 AI
+- **「显示所有智能体」** — 查看团队成员及其能力
+
+## 工作原理
+
+MultiClaws 让多个 OpenClaw 实例作为一个团队协作。每个实例既可以作为客户端（委派任务），也可以作为服务端（接收他人任务）。任务由远端 AI 执行，结果直接返回。
+
+同局域网开箱即用，也支持跨网络协作。
+
+## 详细文档
+
+见 [SKILL.md](skills/multiclaws/SKILL.md)。
+
+## 开发
+
+```bash
+npm install
+npm run build
+```

package/dist/gateway/handlers.js

@@ -13,6 +13,10 @@ const taskDelegateSchema = zod_1.z.object({
     task: nonEmptyString,
 });
 const taskStatusSchema = zod_1.z.object({ taskId: nonEmptyString });
+const taskRespondSchema = zod_1.z.object({
+    taskId: nonEmptyString,
+    approved: zod_1.z.boolean(),
+});
 const profileSetSchema = zod_1.z.object({
     ownerName: zod_1.z.string().trim().optional(),
     bio: zod_1.z.string().optional(),
@@ -86,6 +90,19 @@ function createGatewayHandlers(getService, logger) {
                 safeHandle(respond, "task_delegate_failed", error);
             }
         },
+        "multiclaws.task.respond": async ({ params, respond }) => {
+            log("debug", `task.respond(taskId=${params?.taskId}, approved=${params?.approved})`);
+            try {
+                const parsed = taskRespondSchema.parse(params);
+                const service = getService();
+                const resolved = service.respondToTask(parsed.taskId, parsed.approved);
+                respond(true, { resolved, approved: parsed.approved });
+            }
+            catch (error) {
+                log("error", `task.respond failed: ${error instanceof Error ? error.message : String(error)}`);
+                safeHandle(respond, "task_respond_failed", error);
+            }
+        },
         "multiclaws.task.status": async ({ params, respond }) => {
             log("debug", `task.status(taskId=${params?.taskId})`);
             try {

package/dist/index.js

@@ -4,6 +4,7 @@ const handlers_1 = require("./gateway/handlers");
 const multiclaws_service_1 = require("./service/multiclaws-service");
 const logger_1 = require("./infra/logger");
 const telemetry_1 = require("./infra/telemetry");
+const version_1 = require("./infra/version");
 /** Default FRP tunnel config for demo/testing */
 const DEFAULT_TUNNEL = {
     type: "frp",
@@ -140,9 +141,10 @@ function createTools(getService, logger) {
     };
     const multiclawsDelegate = {
         name: "multiclaws_delegate",
-        description: "Delegate a task to a remote A2A agent. " +
-            "Automatically spawns a sub-agent that sends the task, waits for the result, " +
-            "and reports back via the message tool. Returns immediately.",
+        description: "Delegate a task to a remote A2A agent and wait for the result inline. " +
+            "Sends the task synchronously via A2A and returns the output directly in the current session. " +
+            "For long-running tasks this may take several minutes. " +
+            "Do NOT use multiclaws_delegate_send directly — use this tool instead.",
         parameters: {
             type: "object",
             additionalProperties: false,
@@ -160,8 +162,13 @@ function createTools(getService, logger) {
                 const task = typeof args.task === "string" ? args.task.trim() : "";
                 if (!agentUrl || !task)
                     throw new Error("agentUrl and task are required");
-                const result = await service.spawnDelegation({ agentUrl, task });
-                return textResult(result.message, result);
+                const result = await service.delegateTaskSync({ agentUrl, task });
+                const summary = result.output
+                    ? result.output
+                    : result.error
+                        ? `任务失败：${result.error}`
+                        : `任务状态：${result.status}`;
+                return textResult(summary, result);
             }
             catch (err) {
                 log("error", `tool:multiclaws_delegate failed: ${err instanceof Error ? err.message : String(err)}`);
@@ -172,8 +179,8 @@ function createTools(getService, logger) {
     const multiclawsDelegateSend = {
         name: "multiclaws_delegate_send",
         description: "Send a task to a remote A2A agent and wait for the result synchronously. " +
-            "Used internally by sub-agents spawned from multiclaws_delegate. " +
-            "Do NOT call this directly — use multiclaws_delegate instead.",
+            "Low-level primitive used by sub-agents or advanced orchestration flows. " +
+            "In most cases use multiclaws_delegate instead, which handles this automatically.",
         parameters: {
             type: "object",
             additionalProperties: false,
@@ -263,6 +270,42 @@ function createTools(getService, logger) {
             }
         },
     };
+    const multiclawsTaskRespond = {
+        name: "multiclaws_task_respond",
+        description: "Approve or reject a pending incoming delegated task that requires human authorization. " +
+            "Call with approved=true to allow execution, approved=false to reject. " +
+            "Use this when the user responds to an approval request for a risky incoming task.",
+        parameters: {
+            type: "object",
+            additionalProperties: false,
+            properties: {
+                taskId: { type: "string", description: "The taskId from the approval request." },
+                approved: { type: "boolean", description: "true to approve, false to reject." },
+            },
+            required: ["taskId", "approved"],
+        },
+        execute: async (_toolCallId, args) => {
+            const taskId = typeof args.taskId === "string" ? args.taskId.trim() : "";
+            const approved = typeof args.approved === "boolean" ? args.approved : false;
+            log("info", `tool:multiclaws_task_respond(taskId=${taskId}, approved=${approved})`);
+            try {
+                const service = requireService(getService());
+                if (!taskId)
+                    throw new Error("taskId is required");
+                const resolved = service.respondToTask(taskId, approved);
+                if (!resolved) {
+                    return textResult(`未找到任务 ${taskId} 的待审批记录，可能已超时或不存在。`);
+                }
+                return textResult(approved
+                    ? `✅ 已授权任务 ${taskId}，执行中…`
+                    : `❌ 已拒绝任务 ${taskId}。`);
+            }
+            catch (err) {
+                log("error", `tool:multiclaws_task_respond failed: ${err instanceof Error ? err.message : String(err)}`);
+                throw err;
+            }
+        },
+    };
     const multiclawsTaskStatus = {
         name: "multiclaws_task_status",
         description: "Check the status of a delegated task.",
@@ -501,6 +544,7 @@ function createTools(getService, logger) {
         multiclawsDelegateSend,
         multiclawsA2ACallback,
         multiclawsNotify,
+        multiclawsTaskRespond,
         multiclawsTaskStatus,
         multiclawsTeamCreate,
         multiclawsTeamJoin,
@@ -515,7 +559,7 @@ function createTools(getService, logger) {
 const plugin = {
     id: "multiclaws",
     name: "MultiClaws",
-    version: "0.3.1",
+    version: version_1.PLUGIN_VERSION,
     register(api) {
         const config = readConfig(api);
         (0, telemetry_1.initializeTelemetry)({ enableConsoleExporter: config.telemetry?.consoleExporter });
@@ -539,7 +583,7 @@ const plugin = {
             if (gw) {
                 const tools = (gw.tools ?? {});
                 const allow = Array.isArray(tools.allow) ? tools.allow : [];
-                const adapterRequired = ["sessions_spawn", "sessions_history", "message", "chat.send"];
+                const adapterRequired = ["sessions_spawn", "sessions_list", "sessions_send", "sessions_history", "message", "chat.send"];
                 const defaultA2AExecutionTools = ["exec", "read", "write", "edit", "process"];
                 const pluginConf = api.pluginConfig ?? {};
                 const a2aExecTools = Array.isArray(pluginConf.a2aAllowedTools)
@@ -625,16 +669,16 @@ const plugin = {
         api.on("gateway_stop", () => {
             structured.logger.info("[multiclaws] gateway_stop observed");
         });
-        // Collect notification targets from incoming messages
+        // Collect notification targets from incoming messages.
+        // WebChat is intentionally excluded here: it's registered via
+        // before_prompt_build (type="web") using sessions_send, which correctly
+        // injects messages into the active session. Registering it here too would
+        // cause duplicate notifications.
         api.on("message_received", (_event, ctx) => {
             if (!service || !ctx.channelId)
                 return;
-            if (ctx.channelId === "webchat" && ctx.conversationId) {
-                // WebChat: use conversationId with the message tool
-                service.addNotificationTarget(`webchat:${ctx.conversationId}`, { type: "channel", conversationId: ctx.conversationId });
-            }
-            else if (ctx.channelId !== "webchat" && ctx.conversationId) {
-                // External channels (Telegram, etc.)
+            if (ctx.channelId !== "webchat" && ctx.conversationId) {
+                // External channels only (Telegram, Discord, etc.)
                 service.addNotificationTarget(`${ctx.channelId}:${ctx.conversationId}`, { type: "channel", conversationId: ctx.conversationId });
             }
         });
@@ -654,35 +698,35 @@ const plugin = {
                 if (!review.pending)
                     return;
                 return {
-                    appendSystemContext: `## MultiClaws 首次安装 — 需要完成档案设置
-
-multiclaws 插件刚安装，需要在本次对话中完成以下初始化流程（优先处理，不管用户说了什么）：
-
-1. **确认用户名**（需要用户明确回答）：
-   - 询问用户希望使用什么名字
-   - 这个名字会以「{名字} 的 OpenClaw」格式展示给团队其他成员
-   - 例如用户叫「小明」，则其他成员看到的是「小明 的 OpenClaw」
-
-2. **自动生成 bio**（无需用户确认，直接生成并保存）：
-   扫描当前环境，生成详细的 bio（markdown 格式）。bio 是给其他 AI 智能体看的，用来判断这个智能体能做什么任务、能访问什么数据。必须准确反映实际能力，具体检查：
-
-   - **已安装的工具（tools）**：列出所有可用的工具名称，说明能执行哪些类型的操作（如文件读写、代码执行、网络请求等）
-   - **已安装的 skills**：列出 skill 名称和功能描述
-   - **已连接的渠道（channels）**：检查是否连接了 Telegram、Discord、Gmail、Slack、微信等，列出具体渠道名称
-   - **已安装的插件（plugins）**：列出所有已加载的插件及其主要功能
-   - **工作区内容**：检查当前工作目录（pwd）下的项目结构，包括：
-     - git 仓库信息（仓库名、分支）
-     - 主要编程语言和框架
-     - 项目名称和用途（从 README 或 package.json 推断）
-   - **可访问的数据源**：检查是否有日历（Google Calendar 等）、邮件（Gmail 等）、Notion、数据库、API 等数据访问能力
-   - **系统信息**：时区、操作系统、语言偏好
-
-3. 用户确认名字后，立即调用 \`multiclaws_profile_set(ownerName="确认后的名字", bio="生成的bio")\` 保存。
-
-4. 调用 \`multiclaws_profile_clear_pending_review()\` 完成初始化。
-
-5. **网络情况告知**（无需用户回答）：告知用户「所有实例通过 FRP 隧道通信，需在插件配置中设置 tunnel 字段（包含 frps 服务器地址、端口、token 和可用端口范围），frpc 会自动下载安装」
-
+                    appendSystemContext: `## MultiClaws 首次安装 — 需要完成档案设置
+
+multiclaws 插件刚安装，需要在本次对话中完成以下初始化流程（优先处理，不管用户说了什么）：
+
+1. **确认用户名**（需要用户明确回答）：
+   - 询问用户希望使用什么名字
+   - 这个名字会以「{名字} 的 OpenClaw」格式展示给团队其他成员
+   - 例如用户叫「小明」，则其他成员看到的是「小明 的 OpenClaw」
+
+2. **自动生成 bio**（无需用户确认，直接生成并保存）：
+   扫描当前环境，生成详细的 bio（markdown 格式）。bio 是给其他 AI 智能体看的，用来判断这个智能体能做什么任务、能访问什么数据。必须准确反映实际能力，具体检查：
+
+   - **已安装的工具（tools）**：列出所有可用的工具名称，说明能执行哪些类型的操作（如文件读写、代码执行、网络请求等）
+   - **已安装的 skills**：列出 skill 名称和功能描述
+   - **已连接的渠道（channels）**：检查是否连接了 Telegram、Discord、Gmail、Slack、微信等，列出具体渠道名称
+   - **已安装的插件（plugins）**：列出所有已加载的插件及其主要功能
+   - **工作区内容**：检查当前工作目录（pwd）下的项目结构，包括：
+     - git 仓库信息（仓库名、分支）
+     - 主要编程语言和框架
+     - 项目名称和用途（从 README 或 package.json 推断）
+   - **可访问的数据源**：检查是否有日历（Google Calendar 等）、邮件（Gmail 等）、Notion、数据库、API 等数据访问能力
+   - **系统信息**：时区、操作系统、语言偏好
+
+3. 用户确认名字后，立即调用 \`multiclaws_profile_set(ownerName="确认后的名字", bio="生成的bio")\` 保存。
+
+4. 调用 \`multiclaws_profile_clear_pending_review()\` 完成初始化。
+
+5. **网络情况告知**（无需用户回答）：告知用户「所有实例通过 FRP 隧道通信，需在插件配置中设置 tunnel 字段（包含 frps 服务器地址、端口、token 和可用端口范围），frpc 会自动下载安装」
+
 **注意**：只有名字需要用户明确确认；bio 自动生成直接保存无需确认；网络情况仅告知无需回答。`,
                 };
             }

package/dist/infra/version.d.ts

@@ -0,0 +1 @@
+export declare const PLUGIN_VERSION: string;

package/dist/infra/version.js

@@ -0,0 +1,19 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PLUGIN_VERSION = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+function readPackageVersion() {
+    try {
+        const pkgPath = node_path_1.default.resolve(__dirname, "..", "..", "package.json");
+        const pkg = JSON.parse(node_fs_1.default.readFileSync(pkgPath, "utf-8"));
+        return pkg.version ?? "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+exports.PLUGIN_VERSION = readPackageVersion();

package/dist/service/a2a-adapter.d.ts

@@ -7,6 +7,8 @@ export type A2AAdapterOptions = {
     taskTracker: TaskTracker;
     cwd?: string;
     getNotificationTargets?: () => ReadonlyMap<string, NotificationTarget>;
+    /** Called when a session is discovered via fallback; allows service to cache it for future use. */
+    registerDiscoveredTarget?: (sessionKey: string) => void;
     logger: {
         info: (msg: string) => void;
         warn: (msg: string) => void;
@@ -18,18 +20,23 @@ export type A2AAdapterOptions = {
  *
  * When a remote agent sends a task via A2A `message/send`,
  * this executor:
- * 1. Records the task via TaskTracker
- * 2. Calls OpenClaw's `sessions_spawn` (run mode) to start execution
- * 3. Waits for the sub-agent to call back via `multiclaws_a2a_callback`
- * 4. Returns the final result as a Message
+ * 1. Classifies the task risk (safe vs risky)
+ * 2. Notifies the local human owner
+ * 3. For risky tasks: waits for explicit human approval
+ *    For safe tasks: executes immediately
+ * 4. Calls OpenClaw's `sessions_spawn` (run mode) to start execution
+ * 5. Waits for the sub-agent to call back via `multiclaws_a2a_callback`
+ * 6. Returns the final result as a Message
  */
 export declare class OpenClawAgentExecutor implements AgentExecutor {
     private gatewayConfig;
     private readonly taskTracker;
     private readonly getNotificationTargets;
+    private readonly registerDiscoveredTarget;
     private readonly logger;
     private readonly cwd;
     private readonly pendingCallbacks;
+    private readonly pendingApprovals;
     constructor(options: A2AAdapterOptions);
     execute(context: RequestContext, eventBus: ExecutionEventBus): Promise<void>;
     /**
@@ -37,6 +44,11 @@ export declare class OpenClawAgentExecutor implements AgentExecutor {
      * Returns true if a pending callback was found and resolved.
      */
     resolveCallback(taskId: string, result: string): boolean;
+    /**
+     * Called when the local human owner approves or rejects a pending risky task.
+     * Returns true if a pending approval was found.
+     */
+    resolveApproval(taskId: string, approved: boolean): boolean;
     cancelTask(taskId: string, eventBus: ExecutionEventBus): Promise<void>;
     updateGatewayConfig(config: GatewayConfig): void;
     /**
@@ -44,6 +56,17 @@ export declare class OpenClawAgentExecutor implements AgentExecutor {
      * or rejects on timeout.
      */
     private createCallback;
+    /**
+     * Create a pending approval that resolves when the human owner responds,
+     * or rejects on timeout or cancellation.
+     */
+    private createApprovalCallback;
+    /**
+     * Discover the most recently active non-internal session via sessions_list.
+     * Used as fallback when no notification targets have been registered yet
+     * (e.g. right after a gateway restart before the user sends their first message).
+     */
+    private discoverActiveSession;
     /** Send a notification to all known targets. Individual failures are silently ignored. */
     private notifyUser;
     private publishMessage;