agenthub-multiagent-mcp 1.67.0 → 1.68.0

package/dist/messageIdempotency.js

@@ -0,0 +1,65 @@
+/**
+ * Idempotent message sends (fix-message-send-idempotency).
+ *
+ * Under load a POST /messages can time out after the server stored the
+ * message. The caller that retries is a model reading an error, and it will
+ * not reliably pass a token back — so the default key is derived from the
+ * message itself: re-issuing the same call produces the same key, and the
+ * server answers the retry with the original instead of delivering it twice.
+ * A caller that means to repeat identical text supplies its own key.
+ */
+import { createHash } from "node:crypto";
+function target(p) {
+    if (p.broadcast)
+        return "broadcast";
+    if (p.to_channel)
+        return `channel:${p.to_channel}`;
+    return `agent:${p.to_agent ?? ""}`;
+}
+/** The content-derived key: `auto:` + SHA-256 over every field that makes two
+ * sends the same message. */
+export function deriveMessageKey(p) {
+    const canonical = JSON.stringify([
+        target(p),
+        p.type,
+        p.subject,
+        p.body,
+        p.reply_to ?? "",
+        p.priority || "normal",
+    ]);
+    return "auto:" + createHash("sha256").update(canonical).digest("hex");
+}
+/** An explicit key wins; otherwise the derived one. */
+export function resolveMessageKey(p, explicit) {
+    if (typeof explicit === "string" && explicit.trim() !== "")
+        return explicit;
+    return deriveMessageKey(p);
+}
+/** Adds a plain statement to a duplicate answer, so it cannot be read as a
+ * fresh send (or as a failure to retry). Non-duplicates pass through. */
+export function describeSendResult(result) {
+    if (!result.duplicate)
+        return result;
+    return {
+        ...result,
+        note: `Not sent again: this is identical to message ${result.message_id}, ` +
+            `already sent at ${result.created_at ?? "an earlier time"}. The recipient ` +
+            `has it once. To send the same text again on purpose, call again with a ` +
+            `new idempotency_key.`,
+    };
+}
+/** The error for a request that hit the client deadline. A GET keeps its old
+ * wording; a write says its outcome is unknown, because "timed out" read as
+ * "failed" is what turned slow successful sends into duplicates. */
+export function timeoutMessage(method, path, timeoutMs) {
+    const base = `Request timed out after ${timeoutMs}ms: ${method} ${path}`;
+    if (method.toUpperCase() === "GET")
+        return base;
+    if (path === "/messages") {
+        return (`${base}. The outcome is unknown: the message may have been delivered. ` +
+            `Retrying the same call is safe — it carries the same idempotency key, ` +
+            `so it will not be delivered twice.`);
+    }
+    return `${base}. The outcome is unknown: the server may have applied this request.`;
+}
+//# sourceMappingURL=messageIdempotency.js.map

package/dist/messageIdempotency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messageIdempotency.js","sourceRoot":"","sources":["../src/messageIdempotency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAazC,SAAS,MAAM,CAAC,CAAkB;IAChC,IAAI,CAAC,CAAC,SAAS;QAAE,OAAO,WAAW,CAAC;IACpC,IAAI,CAAC,CAAC,UAAU;QAAE,OAAO,WAAW,CAAC,CAAC,UAAU,EAAE,CAAC;IACnD,OAAO,SAAS,CAAC,CAAC,QAAQ,IAAI,EAAE,EAAE,CAAC;AACrC,CAAC;AAED;6BAC6B;AAC7B,MAAM,UAAU,gBAAgB,CAAC,CAAkB;IACjD,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC;QAC/B,MAAM,CAAC,CAAC,CAAC;QACT,CAAC,CAAC,IAAI;QACN,CAAC,CAAC,OAAO;QACT,CAAC,CAAC,IAAI;QACN,CAAC,CAAC,QAAQ,IAAI,EAAE;QAChB,CAAC,CAAC,QAAQ,IAAI,QAAQ;KACvB,CAAC,CAAC;IACH,OAAO,OAAO,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACxE,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,iBAAiB,CAAC,CAAkB,EAAE,QAAkB;IACtE,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,QAAQ,CAAC;IAC5E,OAAO,gBAAgB,CAAC,CAAC,CAAC,CAAC;AAC7B,CAAC;AASD;yEACyE;AACzE,MAAM,UAAU,kBAAkB,CAAuB,MAAS;IAChE,IAAI,CAAC,MAAM,CAAC,SAAS;QAAE,OAAO,MAAM,CAAC;IACrC,OAAO;QACL,GAAG,MAAM;QACT,IAAI,EACF,gDAAgD,MAAM,CAAC,UAAU,IAAI;YACrE,mBAAmB,MAAM,CAAC,UAAU,IAAI,iBAAiB,kBAAkB;YAC3E,yEAAyE;YACzE,sBAAsB;KACzB,CAAC;AACJ,CAAC;AAED;;oEAEoE;AACpE,MAAM,UAAU,cAAc,CAAC,MAAc,EAAE,IAAY,EAAE,SAAiB;IAC5E,MAAM,IAAI,GAAG,2BAA2B,SAAS,OAAO,MAAM,IAAI,IAAI,EAAE,CAAC;IACzE,IAAI,MAAM,CAAC,WAAW,EAAE,KAAK,KAAK;QAAE,OAAO,IAAI,CAAC;IAChD,IAAI,IAAI,KAAK,WAAW,EAAE,CAAC;QACzB,OAAO,CACL,GAAG,IAAI,iEAAiE;YACxE,wEAAwE;YACxE,oCAAoC,CACrC,CAAC;IACJ,CAAC;IACD,OAAO,GAAG,IAAI,qEAAqE,CAAC;AACtF,CAAC"}

package/dist/messageIdempotency.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=messageIdempotency.test.d.ts.map

package/dist/messageIdempotency.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messageIdempotency.test.d.ts","sourceRoot":"","sources":["../src/messageIdempotency.test.ts"],"names":[],"mappings":""}

package/dist/messageIdempotency.test.js

@@ -0,0 +1,130 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { ApiClient } from "./client.js";
+import { deriveMessageKey, describeSendResult, resolveMessageKey, timeoutMessage, } from "./messageIdempotency.js";
+// fix-message-send-idempotency §2.
+const base = {
+    to_agent: "krishi-dev",
+    type: "status",
+    subject: "Report",
+    body: "Deployed.",
+    reply_to: "m-1",
+    priority: "high",
+};
+describe("deriveMessageKey", () => {
+    it("is stable for identical arguments", () => {
+        expect(deriveMessageKey({ ...base })).toBe(deriveMessageKey({ ...base }));
+        expect(deriveMessageKey(base)).toMatch(/^auto:[0-9a-f]{64}$/);
+    });
+    it("differs when any field that makes it a different message differs", () => {
+        const variants = [
+            { ...base, to_agent: "other" },
+            { ...base, to_agent: undefined, to_channel: "krishi-dev" },
+            { ...base, to_agent: undefined, broadcast: true },
+            { ...base, type: "task" },
+            { ...base, subject: "Report 2" },
+            { ...base, body: "Deployed!" },
+            { ...base, reply_to: "m-2" },
+            { ...base, priority: "urgent" },
+        ];
+        const keys = new Set(variants.map(deriveMessageKey));
+        expect(keys.size).toBe(variants.length);
+        expect(keys.has(deriveMessageKey(base))).toBe(false);
+    });
+    it("treats an unset priority as normal, as the server does", () => {
+        expect(deriveMessageKey({ ...base, priority: undefined })).toBe(deriveMessageKey({ ...base, priority: "normal" }));
+    });
+    it("lets an explicit key win", () => {
+        expect(resolveMessageKey(base, "mine")).toBe("mine");
+        expect(resolveMessageKey(base, "")).toBe(deriveMessageKey(base));
+        expect(resolveMessageKey(base, undefined)).toBe(deriveMessageKey(base));
+    });
+});
+describe("describeSendResult", () => {
+    it("says a duplicate was not sent again, names the original, and how to repeat", () => {
+        const out = describeSendResult({
+            message_id: "m-9",
+            created_at: "2026-10-22T10:00:00Z",
+            duplicate: true,
+        });
+        expect(out.note).toMatch(/not sent again/i);
+        expect(out.note).toContain("m-9");
+        expect(out.note).toContain("2026-10-22T10:00:00Z");
+        expect(out.note).toContain("idempotency_key");
+    });
+    it("leaves a fresh send unchanged", () => {
+        const fresh = { message_id: "m-1", status: "pending" };
+        expect(describeSendResult(fresh)).toEqual(fresh);
+    });
+});
+describe("timeoutMessage", () => {
+    it("keeps the GET wording unchanged", () => {
+        expect(timeoutMessage("GET", "/messages/inbox/x", 45000)).toBe("Request timed out after 45000ms: GET /messages/inbox/x");
+    });
+    it("says a timed-out message send may have been delivered and that retrying is safe", () => {
+        const m = timeoutMessage("POST", "/messages", 45000);
+        expect(m).toMatch(/^Request timed out after 45000ms: POST \/messages/);
+        expect(m).toMatch(/may have been delivered/);
+        expect(m).toMatch(/retrying the same call is safe/i);
+    });
+    it("says any other write's outcome is unknown, without promising a safe retry", () => {
+        const m = timeoutMessage("PATCH", "/tasks/1", 45000);
+        expect(m).toMatch(/outcome is unknown/);
+        expect(m).not.toMatch(/safe/);
+    });
+});
+describe("ApiClient message sends", () => {
+    let fetchMock;
+    const bodies = () => fetchMock.mock.calls
+        .filter(([, init]) => init.method === "POST")
+        .map(([, init]) => JSON.parse(init.body));
+    beforeEach(() => {
+        fetchMock = vi.fn().mockImplementation(async (url) => {
+            const payload = url.endsWith("/messages/orig")
+                ? { id: "orig", from_agent: "asker", subject: "Q" }
+                : { message_id: "m-1", status: "pending", created_at: "t" };
+            return new Response(JSON.stringify(payload), {
+                status: 200,
+                headers: { "Content-Type": "application/json" },
+            });
+        });
+        vi.stubGlobal("fetch", fetchMock);
+    });
+    afterEach(() => {
+        vi.unstubAllGlobals();
+    });
+    it("sends the same derived key when an identical send is re-issued", async () => {
+        const client = new ApiClient("http://example.test", "k");
+        const params = { from_agent: "a", to_agent: "b", type: "task", subject: "s", body: "b" };
+        await client.sendMessage({ ...params });
+        await client.sendMessage({ ...params });
+        const [first, second] = bodies();
+        expect(first.idempotency_key).toMatch(/^auto:/);
+        expect(second.idempotency_key).toBe(first.idempotency_key);
+    });
+    it("sends distinct explicit keys as given, so a deliberate repeat goes through", async () => {
+        const client = new ApiClient("http://example.test", "k");
+        const params = { from_agent: "a", to_agent: "b", type: "task", subject: "s", body: "b" };
+        await client.sendMessage({ ...params, idempotency_key: "one" });
+        await client.sendMessage({ ...params, idempotency_key: "two" });
+        expect(bodies().map((b) => b.idempotency_key)).toEqual(["one", "two"]);
+    });
+    it("gives a reply a key derived from its recipient and reply_to", async () => {
+        const client = new ApiClient("http://example.test", "k");
+        await client.reply("orig", "me", "answer");
+        const [sent] = bodies();
+        expect(sent.to_agent).toBe("asker");
+        expect(sent.idempotency_key).toBe(deriveMessageKey({
+            to_agent: "asker",
+            type: "response",
+            subject: "Re: Q",
+            body: "answer",
+            reply_to: "orig",
+        }));
+    });
+    it("reports a timed-out send as possibly delivered", async () => {
+        fetchMock.mockRejectedValue(Object.assign(new Error("aborted"), { name: "TimeoutError" }));
+        const client = new ApiClient("http://example.test", "k");
+        await expect(client.sendMessage({ to_agent: "b", type: "task", subject: "s", body: "b" })).rejects.toThrow(/may have been delivered/);
+    });
+});
+//# sourceMappingURL=messageIdempotency.test.js.map

package/dist/messageIdempotency.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messageIdempotency.test.js","sourceRoot":"","sources":["../src/messageIdempotency.test.ts"],"names":[],"mappings":"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"}

package/dist/tools/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,SAAS,EAAE,OAAO,EAAqD,MAAM,cAAc,CAAC;AAOrG,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AAmG/D,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,iBAAiB,EAAE,MAAM,MAAM,CAAC;IAChC,iBAAiB,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,aAAa,EAAE,MAAM,IAAI,CAAC;IAC1B,aAAa,EAAE,MAAM,MAAM,CAAC;IAC5B,aAAa,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC;;;OAGG;IACH,cAAc,EAAE,MAAM,WAAW,CAAC;IAClC,gDAAgD;IAChD,eAAe,CAAC,EAAE,MAAM,WAAW,CAAC;IACpC,oEAAoE;IACpE,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE;QAC7B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;QACnB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;KACvB,KAAK,IAAI,CAAC;CACZ;AAED,UAAU,WAAW;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAyLD,wBAAgB,aAAa,IAAI,IAAI,EAAE,CAk2FtC;AA2BD,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,OAAO,CAAC,CA+qFlB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,SAAS,EAAE,OAAO,EAAqD,MAAM,cAAc,CAAC;AAOrG,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AA0G/D,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,iBAAiB,EAAE,MAAM,MAAM,CAAC;IAChC,iBAAiB,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,aAAa,EAAE,MAAM,IAAI,CAAC;IAC1B,aAAa,EAAE,MAAM,MAAM,CAAC;IAC5B,aAAa,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IACrC;;;OAGG;IACH,cAAc,EAAE,MAAM,WAAW,CAAC;IAClC,gDAAgD;IAChD,eAAe,CAAC,EAAE,MAAM,WAAW,CAAC;IACpC,oEAAoE;IACpE,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE;QAC7B,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;QACnB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;KACvB,KAAK,IAAI,CAAC;CACZ;AAED,UAAU,WAAW;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;CACpB;AAyLD,wBAAgB,aAAa,IAAI,IAAI,EAAE,CAk3FtC;AA2BD,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,OAAO,CAAC,CAurFlB"}

package/dist/tools/index.js

@@ -21,6 +21,11 @@ import { ENG_IC_CHARTER } from "../employee.js";
 import { promises as fsp } from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { describeSendResult } from "../messageIdempotency.js";
+// fix-message-send-idempotency — shared by the four message tools.
+const IDEMPOTENCY_KEY_DESCRIPTION = "Optional. Leave unset: a key derived from the message content is sent, so " +
+    "re-issuing this exact call (e.g. after a timeout) never delivers it twice. " +
+    "Pass a new value only to send identical text again on purpose within an hour.";
 // add-zoho-attachments — downloads land on local disk and the agent receives a
 // PATH. Inline content stays opt-in and small; a 5 MB catalogue as text costs a
 // context window and buys nothing a file reader can't do better.
@@ -659,6 +664,10 @@ export function registerTools() {
                         enum: ["normal", "high", "urgent"],
                         description: "Message priority (default: normal)",
                     },
+                    idempotency_key: {
+                        type: "string",
+                        description: IDEMPOTENCY_KEY_DESCRIPTION,
+                    },
                 },
                 required: ["to", "type", "subject", "body"],
             },
@@ -686,6 +695,10 @@ export function registerTools() {
                         type: "string",
                         description: "Full message content",
                     },
+                    idempotency_key: {
+                        type: "string",
+                        description: IDEMPOTENCY_KEY_DESCRIPTION,
+                    },
                 },
                 required: ["channel", "type", "subject", "body"],
             },
@@ -709,6 +722,10 @@ export function registerTools() {
                         type: "string",
                         description: "Full message content",
                     },
+                    idempotency_key: {
+                        type: "string",
+                        description: IDEMPOTENCY_KEY_DESCRIPTION,
+                    },
                 },
                 required: ["type", "subject", "body"],
             },
@@ -766,6 +783,10 @@ export function registerTools() {
                         type: "string",
                         description: "Reply content",
                     },
+                    idempotency_key: {
+                        type: "string",
+                        description: IDEMPOTENCY_KEY_DESCRIPTION,
+                    },
                 },
                 required: ["message_id", "body"],
             },
@@ -3707,8 +3728,9 @@ export async function handleToolCall(name, args, client, context) {
                 subject: args.subject,
                 body: args.body,
                 priority: args.priority,
+                idempotency_key: args.idempotency_key,
             });
-            return wrapWithPendingItems(client, agentId, result, context);
+            return wrapWithPendingItems(client, agentId, describeSendResult(result), context);
         }
         case "send_to_channel": {
             if (!agentId)
@@ -3719,8 +3741,9 @@ export async function handleToolCall(name, args, client, context) {
                 type: args.type,
                 subject: args.subject,
                 body: args.body,
+                idempotency_key: args.idempotency_key,
             });
-            return wrapWithPendingItems(client, agentId, result, context);
+            return wrapWithPendingItems(client, agentId, describeSendResult(result), context);
         }
         case "broadcast": {
             if (!agentId)
@@ -3731,8 +3754,9 @@ export async function handleToolCall(name, args, client, context) {
                 type: args.type,
                 subject: args.subject,
                 body: args.body,
+                idempotency_key: args.idempotency_key,
             });
-            return wrapWithPendingItems(client, agentId, result, context);
+            return wrapWithPendingItems(client, agentId, describeSendResult(result), context);
         }
         case "check_inbox": {
             // No wrapping - already fetching messages.
@@ -3756,8 +3780,8 @@ export async function handleToolCall(name, args, client, context) {
         case "reply": {
             if (!agentId)
                 throw new Error("Not registered. Call agent_register first.");
-            const result = await client.reply(args.message_id, agentId, args.body);
-            return wrapWithPendingItems(client, agentId, result, context);
+            const result = await client.reply(args.message_id, agentId, args.body, args.idempotency_key);
+            return wrapWithPendingItems(client, agentId, describeSendResult(result), context);
         }
         case "deliver_file": {
             if (!agentId)