agenthub-multiagent-mcp 1.51.0 → 1.52.0

package/dist/streamingRuntimeLib.test.js

@@ -0,0 +1,147 @@
+import { describe, it, expect } from "vitest";
+import { streamingEnabled, assertSubscriptionAuth, decideInbound, buildTurnContent, toUserTurn, shouldRecycle, defaultRecycleOptions, newRuntimeStats, recordResultUsage, formatUsageLine, inSessionMcpEnv, assertWorkerIdentityReady, } from "./streamingRuntimeLib.js";
+// add-employee-streaming-runtime §2 — pure-helper tests.
+describe("streamingEnabled (kill switch §2.1)", () => {
+    it("off by default / falsey", () => {
+        for (const v of [undefined, "", "false", "0", "no", "off"]) {
+            expect(streamingEnabled(v === undefined ? {} : { AGENTHUB_EMPLOYEE_STREAMING_ENABLED: v })).toBe(false);
+        }
+    });
+    it("on for explicit truthy", () => {
+        for (const v of ["true", "1", "yes", "on", " TRUE "]) {
+            expect(streamingEnabled({ AGENTHUB_EMPLOYEE_STREAMING_ENABLED: v })).toBe(true);
+        }
+    });
+});
+describe("assertSubscriptionAuth (§D3 fail-closed)", () => {
+    it("throws when ANTHROPIC_API_KEY is set (refuse metered billing)", () => {
+        expect(() => assertSubscriptionAuth({ ANTHROPIC_API_KEY: "sk-x", CLAUDE_CODE_OAUTH_TOKEN: "t" })).toThrow(/ANTHROPIC_API_KEY/);
+    });
+    it("throws when no oauth token", () => {
+        expect(() => assertSubscriptionAuth({})).toThrow(/CLAUDE_CODE_OAUTH_TOKEN/);
+    });
+    it("returns the token on subscription-only env", () => {
+        expect(assertSubscriptionAuth({ CLAUDE_CODE_OAUTH_TOKEN: "tok" })).toEqual({ oauthToken: "tok" });
+    });
+});
+describe("decideInbound (§2.5 loop-safety)", () => {
+    const handled = (ids = []) => ({ has: (id) => ids.includes(id) });
+    const msg = (over) => ({ type: "message", message: { id: "m1", from_agent: "alice", type: "task", body: "do it", ...over } });
+    it("yields an actionable inbound from another agent", () => {
+        const d = decideInbound(msg({}), "me", handled());
+        expect(d.yield).toBe(true);
+        expect(d.message?.id).toBe("m1");
+    });
+    it("skips self messages", () => {
+        expect(decideInbound(msg({ from_agent: "me" }), "me", handled()).yield).toBe(false);
+    });
+    it("skips response/status (non-actionable)", () => {
+        expect(decideInbound(msg({ type: "response" }), "me", handled()).reason).toBe("non-actionable");
+        expect(decideInbound(msg({ type: "status" }), "me", handled()).reason).toBe("non-actionable");
+    });
+    it("skips duplicates", () => {
+        expect(decideInbound(msg({}), "me", handled(["m1"])).reason).toBe("duplicate");
+    });
+    it("skips non-message envelopes", () => {
+        expect(decideInbound({ type: "ping" }, "me", handled()).yield).toBe(false);
+        expect(decideInbound(null, "me", handled()).yield).toBe(false);
+    });
+});
+describe("buildTurnContent + toUserTurn", () => {
+    it("renders sender, body, and reply hint", () => {
+        const c = buildTurnContent({ id: "m1", from_agent: "alice", type: "task", subject: "Hi", body: "ping" });
+        expect(c).toContain("From: alice");
+        expect(c).toContain("ping");
+        expect(c).toContain('mcp__agenthub__reply(message_id="m1"');
+    });
+    it("wraps in the proven SDK user-turn shape", () => {
+        const t = toUserTurn("hello", "sess");
+        expect(t).toEqual({ type: "user", message: { role: "user", content: "hello" }, parent_tool_use_id: null, session_id: "sess" });
+    });
+});
+describe("shouldRecycle (§D4 context bounding)", () => {
+    const opts = { maxTurns: 10, tokenBudget: 100 };
+    it("recycles at the turn bound", () => {
+        expect(shouldRecycle({ turns: 10, estInputTokens: 0 }, opts)).toBe(true);
+        expect(shouldRecycle({ turns: 9, estInputTokens: 0 }, opts)).toBe(false);
+    });
+    it("recycles at the token bound", () => {
+        expect(shouldRecycle({ turns: 0, estInputTokens: 100 }, opts)).toBe(true);
+    });
+    it("default options read env with sane fallbacks", () => {
+        expect(defaultRecycleOptions({})).toEqual({ maxTurns: 25, tokenBudget: 200_000 });
+        expect(defaultRecycleOptions({ AGENTHUB_EMPLOYEE_STREAM_MAX_TURNS: "5" }).maxTurns).toBe(5);
+    });
+});
+describe("RuntimeStats (§4.1 per-employee observability)", () => {
+    it("newRuntimeStats starts every counter at zero", () => {
+        expect(newRuntimeStats()).toEqual({
+            turns: 0,
+            estInputTokens: 0,
+            estOutputTokens: 0,
+            sessionRecycles: 0,
+            reconnects: 0,
+            dedupHits: 0,
+        });
+    });
+    it("recordResultUsage folds fresh + cache-read + cache-creation input and output across turns", () => {
+        const s = newRuntimeStats();
+        recordResultUsage(s, {
+            input_tokens: 100,
+            cache_read_input_tokens: 50,
+            cache_creation_input_tokens: 10,
+            output_tokens: 20,
+        });
+        recordResultUsage(s, { input_tokens: 5, output_tokens: 3 });
+        expect(s.turns).toBe(2);
+        expect(s.estInputTokens).toBe(165); // 160 + 5
+        expect(s.estOutputTokens).toBe(23); // 20 + 3
+    });
+    it("recordResultUsage tolerates missing/undefined usage (still counts the turn)", () => {
+        const s = newRuntimeStats();
+        recordResultUsage(s, undefined);
+        recordResultUsage(s, {});
+        expect(s.turns).toBe(2);
+        expect(s.estInputTokens).toBe(0);
+        expect(s.estOutputTokens).toBe(0);
+    });
+    it("formatUsageLine renders one greppable line with every counter", () => {
+        const s = { turns: 4, estInputTokens: 1000, estOutputTokens: 200, sessionRecycles: 1, reconnects: 2, dedupHits: 3 };
+        const line = formatUsageLine("eng-ic-test", s, 65.9);
+        expect(line).toBe("[usage] employee=eng-ic-test uptime_s=65 turns=4 est_input_tokens=1000 est_output_tokens=200 " +
+            "session_recycles=1 reconnects=2 dedup_hits=3");
+        expect(line).not.toContain("\n");
+    });
+    it("formatUsageLine floors negative/fractional uptime to a non-negative integer", () => {
+        expect(formatUsageLine("x", newRuntimeStats(), -5)).toContain("uptime_s=0");
+    });
+});
+describe("inSessionMcpEnv (§3 connect-token — no browser-poll stall)", () => {
+    const base = { apiUrl: "https://h", apiKey: "ah_x", agentId: "eng-ic-test" };
+    it("always sets AGENTHUB_HEADLESS=true so agent_register can't enter the 10-min browser poll", () => {
+        expect(inSessionMcpEnv(base).AGENTHUB_HEADLESS).toBe("true");
+    });
+    it("carries the core connect-token env (url/key/agent) and disables the in-session WS", () => {
+        const env = inSessionMcpEnv(base);
+        expect(env.AGENTHUB_URL).toBe("https://h");
+        expect(env.AGENTHUB_API_KEY).toBe("ah_x");
+        expect(env.AGENTHUB_AGENT_ID).toBe("eng-ic-test");
+        expect(env.AGENTHUB_DISABLE_WEBSOCKET).toBe("true");
+    });
+    it("passes a user API key through only when present (coherent fallback register)", () => {
+        expect(inSessionMcpEnv(base).AGENTHUB_USER_API_KEY).toBeUndefined();
+        expect(inSessionMcpEnv({ ...base, userApiKey: "ah_user" }).AGENTHUB_USER_API_KEY).toBe("ah_user");
+    });
+    it("does not pass an empty user API key", () => {
+        expect(inSessionMcpEnv({ ...base, userApiKey: "" }).AGENTHUB_USER_API_KEY).toBeUndefined();
+    });
+});
+describe("assertWorkerIdentityReady (§3 fail-fast identity guard)", () => {
+    it("throws when the workspace connect-token state is missing", () => {
+        expect(() => assertWorkerIdentityReady(false, "eng-ic-test")).toThrow(/eng-ic-test/);
+    });
+    it("passes silently when the state file exists", () => {
+        expect(() => assertWorkerIdentityReady(true, "eng-ic-test")).not.toThrow();
+    });
+});
+//# sourceMappingURL=streamingRuntimeLib.test.js.map

package/dist/streamingRuntimeLib.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streamingRuntimeLib.test.js","sourceRoot":"","sources":["../src/streamingRuntimeLib.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;AACrG,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AA+B/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,cAAc,EAAE,MAAM,WAAW,CAAC;CACnC;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;AAwJD,wBAAgB,aAAa,IAAI,IAAI,EAAE,CAwwFtC;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,CA0lFlB"}
+{"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;AACrG,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAC;AA4E/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,cAAc,EAAE,MAAM,WAAW,CAAC;CACnC;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;AAwJD,wBAAgB,aAAa,IAAI,IAAI,EAAE,CA20FtC;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,CAqoFlB"}

package/dist/tools/index.js

@@ -11,6 +11,41 @@ import { registerOpenSpecVizTools, handleOpenSpecVizToolCall } from "./openspec-
 import { installPackFromArchive } from "../skillPackInstaller.js";
 import { getServerTime, useTimeInjection } from "../lib/server-time.js";
 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";
+// 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.
+const INLINE_ATTACHMENT_MAX_BYTES = 1024 * 1024;
+/** Root for downloaded attachments. Overridable for tests and for operators. */
+function attachmentDownloadRoot() {
+    return (process.env.AGENTHUB_ATTACHMENT_DIR ||
+        path.join(os.homedir(), ".agenthub", "zoho-attachments"));
+}
+/**
+ * Sanitize an untrusted path segment into a single safe directory/file name.
+ * Upstream supplies both the message id and the filename, so neither may be
+ * allowed to traverse out of the download root.
+ */
+function safeSegment(raw, fallback) {
+    const base = path.basename((raw || "").replace(/\\/g, "/")).replace(/[\x00-\x1f]/g, "");
+    const cleaned = base.replace(/^\.+$/, "").trim();
+    return cleaned || fallback;
+}
+/**
+ * Write attachment bytes under <root>/<message-id>/<filename> and return the
+ * absolute path. Grouping by message keeps a thread's documents together and
+ * avoids collisions between identically named files on different messages.
+ */
+async function writeAttachmentToDisk(messageId, filename, bytes) {
+    const root = attachmentDownloadRoot();
+    const dir = path.join(root, safeSegment(messageId, "message"));
+    await fsp.mkdir(dir, { recursive: true });
+    const filePath = path.join(dir, safeSegment(filename, "attachment"));
+    await fsp.writeFile(filePath, bytes);
+    return filePath;
+}
 /**
  * Background sync: pushes local context to server after every save.
  * Non-blocking — logs errors but never throws.
@@ -130,12 +165,12 @@ function isUrgentMessage(msg) {
  * Build instruction text for urgent messages
  */
 function buildUrgentInstruction(msg) {
-    return `URGENT: Agent [${msg.from_agent}] needs immediate assistance.
-
-Query: ${msg.subject}
-
-Details: ${msg.body}
-
+    return `URGENT: Agent [${msg.from_agent}] needs immediate assistance.
+
+Query: ${msg.subject}
+
+Details: ${msg.body}
+
 Spawn a subagent with Task tool to research and respond to this query. Use send_message to reply when done.`;
 }
 /**
@@ -143,10 +178,10 @@ Spawn a subagent with Task tool to research and respond to this query. Use send_
  */
 function buildTaskInstruction(task) {
     const assignerName = task.assigned_by_name || task.assigned_by;
-    return `ACTION REQUIRED: You have a task assigned by ${assignerName}.
-
-Task: ${task.task}
-
+    return `ACTION REQUIRED: You have a task assigned by ${assignerName}.
+
+Task: ${task.task}
+
 Use accept_task with task_id="${task.id}" to accept and start working, or decline_task to decline with a reason.`;
 }
 export function registerTools() {
@@ -2824,17 +2859,78 @@ export function registerTools() {
         },
         {
             name: "zoho_search",
-            description: "Search messages in one of your registered mailboxes by a Zoho search key. (requires agent_register first)",
+            description: "Search messages in one of your registered mailboxes. `query` accepts a plain term " +
+                "(normalized to Zoho's `entire:` form for you) OR Zoho's typed search syntax, which is " +
+                "passed through unchanged. Typed forms: `entire:<term>` (anywhere in the mail), " +
+                "`content:<term>` (body only), `sender:<addr-or-word>`, `to:<addr>`, `cc:<addr>`, " +
+                "`subject:<term>`. Combine conditions with `::` (e.g. `entire:payroll::has:attachment`) " +
+                "and alternate with `:or:` (e.g. `sender:a@x.com::or:to:a@x.com`). " +
+                "Searches the last 30 days unless you pass `since`. (requires agent_register first)",
             inputSchema: {
                 type: "object",
                 properties: {
                     mailbox: { type: "string", description: "Your mailbox address" },
-                    query: { type: "string", description: "Zoho search key" },
+                    query: {
+                        type: "string",
+                        description: "A plain term (e.g. 'Baccara') or a typed Zoho search key (e.g. 'sender:eknath.a@baccara-geva.com')",
+                    },
                     limit: { type: "number", description: "Max results (default 20)" },
+                    since: {
+                        type: "string",
+                        description: "Oldest message to search, as RFC3339 (e.g. '2026-01-01T00:00:00Z') or unix millis. " +
+                            "Defaults to 30 days ago — widen this to search further back.",
+                    },
                 },
                 required: ["mailbox", "query"],
             },
         },
+        {
+            name: "zoho_list_attachments",
+            description: "List the attachments on a message in one of your registered mailboxes, without downloading " +
+                "them. Returns attachment_id, filename, mime_type (inferred from the extension — Zoho sends " +
+                "no content type) and size_bytes. Inline parts (signatures, logos) are excluded unless you " +
+                "pass include_inline. Use this to see WHAT is attached, then zoho_download_attachment to " +
+                "fetch one. (requires agent_register first)",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    mailbox: { type: "string", description: "Your mailbox address (must be registered by you)" },
+                    message_id: { type: "string", description: "Zoho message id" },
+                    folder: { type: "string", description: "Zoho folder id the message is in" },
+                    include_inline: {
+                        type: "boolean",
+                        description: "Also return inline content-id parts (signatures, logos). Default false.",
+                    },
+                },
+                required: ["mailbox", "message_id"],
+            },
+        },
+        {
+            name: "zoho_download_attachment",
+            description: "Download one attachment to a local file and return its PATH — hand that path to a PDF/doc " +
+                "reader rather than reading the bytes into context. Returns { file_path, filename, mime_type, " +
+                "size_bytes }. Content is NOT returned inline unless you pass inline:true, which is capped at " +
+                "1 MB and intended only for small text files. Attachments over the server's size cap fail with " +
+                "an error naming the actual size and the cap — never a truncated file. " +
+                "(requires agent_register first)",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    mailbox: { type: "string", description: "Your mailbox address (must be registered by you)" },
+                    message_id: { type: "string", description: "Zoho message id" },
+                    attachment_id: {
+                        type: "string",
+                        description: "Attachment id from zoho_list_attachments or zoho_read_message",
+                    },
+                    folder: { type: "string", description: "Zoho folder id the message is in" },
+                    inline: {
+                        type: "boolean",
+                        description: "Also return the content as text in the response (max 1 MB). Default false — prefer file_path.",
+                    },
+                },
+                required: ["mailbox", "message_id", "attachment_id"],
+            },
+        },
         {
             name: "zoho_read_message",
             description: "Read one message (headers + body) from one of your registered mailboxes. (requires agent_register first)",
@@ -5246,9 +5342,41 @@ export async function handleToolCall(name, args, client, context) {
         case "zoho_search": {
             if (!agentId)
                 throw new Error("Not registered. Call agent_register first.");
-            const res = await client.zohoSearchMessages(args.mailbox, args.query, args.limit);
+            const res = await client.zohoSearchMessages(args.mailbox, args.query, args.limit, args.since);
             return { content: [{ type: "text", text: JSON.stringify(res, null, 2) }] };
         }
+        case "zoho_list_attachments": {
+            if (!agentId)
+                throw new Error("Not registered. Call agent_register first.");
+            const res = await client.zohoListAttachments(args.mailbox, args.message_id, args.folder, args.include_inline === true);
+            return { content: [{ type: "text", text: JSON.stringify(res, null, 2) }] };
+        }
+        case "zoho_download_attachment": {
+            if (!agentId)
+                throw new Error("Not registered. Call agent_register first.");
+            const messageId = args.message_id;
+            const { filename, mimeType, bytes } = await client.zohoDownloadAttachment(args.mailbox, messageId, args.attachment_id, args.folder);
+            const filePath = await writeAttachmentToDisk(messageId, filename, bytes);
+            const out = {
+                file_path: filePath,
+                filename: path.basename(filePath),
+                mime_type: mimeType,
+                size_bytes: bytes.length,
+            };
+            // Inline content is opt-in and capped: a multi-MB document as text blows
+            // out the context window for no benefit when a path will do.
+            if (args.inline === true) {
+                if (bytes.length <= INLINE_ATTACHMENT_MAX_BYTES) {
+                    out.content = bytes.toString("utf8");
+                }
+                else {
+                    out.inline_omitted =
+                        `Attachment is ${bytes.length} bytes, over the ${INLINE_ATTACHMENT_MAX_BYTES} byte ` +
+                            `inline limit. It was written to file_path — read that instead.`;
+                }
+            }
+            return { content: [{ type: "text", text: JSON.stringify(out, null, 2) }] };
+        }
         case "zoho_read_message": {
             if (!agentId)
                 throw new Error("Not registered. Call agent_register first.");