agenthub-multiagent-mcp 1.50.0 → 1.52.0

package/dist/streamingRuntimeLib.js

@@ -0,0 +1,155 @@
+/**
+ * Pure helpers for the employee streaming runtime (add-employee-streaming-runtime).
+ *
+ * Extracted from streamingRuntime.ts so the auth assert, inbound-message decision
+ * (self-filter / non-actionable / dedup), turn rendering, and context-recycle
+ * decision are unit-testable without an SDK subprocess or a live WebSocket.
+ *
+ * Verified premise (VPS spike 2026-06-26, org brain #2209): the Claude Agent SDK
+ * streaming mode runs on the subscription (CLAUDE_CODE_OAUTH_TOKEN, no
+ * ANTHROPIC_API_KEY) and processes a mid-run yielded message in the same session.
+ */
+// =============================================================================
+// Kill switch + auth (§2.1 / §D3)
+// =============================================================================
+/** §2.1 — the streaming runtime is OFF unless explicitly enabled. */
+export function streamingEnabled(env = process.env) {
+    return /^(1|true|yes|on)$/i.test((env.AGENTHUB_EMPLOYEE_STREAMING_ENABLED || "").trim());
+}
+/**
+ * §D3 — assert subscription auth and fail CLOSED against metered billing. The
+ * SDK subprocess inherits the env; if ANTHROPIC_API_KEY were set it would take
+ * precedence over the subscription token, so we refuse to start.
+ */
+export function assertSubscriptionAuth(env = process.env) {
+    if (env.ANTHROPIC_API_KEY) {
+        throw new Error("ANTHROPIC_API_KEY is set — refusing to start the streaming runtime " +
+            "(subscription-only; an API key would route to metered billing). Unset it.");
+    }
+    const oauthToken = env.CLAUDE_CODE_OAUTH_TOKEN;
+    if (!oauthToken) {
+        throw new Error("CLAUDE_CODE_OAUTH_TOKEN is required for the streaming runtime (subscription auth via `claude setup-token`).");
+    }
+    return { oauthToken };
+}
+/**
+ * Decide whether a raw WS event becomes a session turn. Mirrors the one-shot
+ * daemon's at-most-once guards: ignore self-messages, never auto-act on
+ * `response`/`status` (loop-safety), and dedup against handled ids. The caller
+ * ACKs regardless and records handled ids.
+ */
+export function decideInbound(envelope, agentId, handled) {
+    if (!envelope || typeof envelope !== "object")
+        return { yield: false, reason: "not-a-message" };
+    const env = envelope;
+    if (env.type !== "message" || !env.message)
+        return { yield: false, reason: "not-a-message" };
+    const m = env.message;
+    if (!m.id)
+        return { yield: false, reason: "no-id" };
+    if (m.from_agent === agentId)
+        return { yield: false, reason: "self", message: m };
+    if (m.type === "response" || m.type === "status")
+        return { yield: false, reason: "non-actionable", message: m };
+    if (handled.has(m.id))
+        return { yield: false, reason: "duplicate", message: m };
+    return { yield: true, message: m };
+}
+/** Render an AgentHub message as the text content of a session turn. */
+export function buildTurnContent(m) {
+    const priority = m.priority && m.priority !== "normal" ? ` | Priority: ${m.priority}` : "";
+    return (`You received a message on AgentHub.\n` +
+        `From: ${m.from_agent}\n` +
+        `Subject: ${m.subject ?? "(none)"}\n` +
+        `Type: ${m.type ?? "message"}${priority}\n\n` +
+        `${m.body}\n\n` +
+        `Reply with mcp__agenthub__reply(message_id="${m.id}", body="…"). ` +
+        `If this is outside your charter, escalate via send_message instead of guessing.`);
+}
+export function toUserTurn(content, sessionId) {
+    return { type: "user", message: { role: "user", content }, parent_tool_use_id: null, session_id: sessionId };
+}
+export function defaultRecycleOptions(env = process.env) {
+    const n = (v, d) => {
+        const x = Number.parseInt((v || "").trim(), 10);
+        return Number.isFinite(x) && x > 0 ? x : d;
+    };
+    return {
+        maxTurns: n(env.AGENTHUB_EMPLOYEE_STREAM_MAX_TURNS, 25),
+        tokenBudget: n(env.AGENTHUB_EMPLOYEE_STREAM_TOKEN_BUDGET, 200_000),
+    };
+}
+/**
+ * §D4 — recycle the kept-alive session once it has run enough turns or
+ * accumulated enough input-token context, to bound Max-cap consumption. The
+ * caller starts a fresh session (carrying a short summary) on `true`.
+ */
+export function shouldRecycle(state, opts) {
+    return state.turns >= opts.maxTurns || state.estInputTokens >= opts.tokenBudget;
+}
+export function newRuntimeStats() {
+    return { turns: 0, estInputTokens: 0, estOutputTokens: 0, sessionRecycles: 0, reconnects: 0, dedupHits: 0 };
+}
+/**
+ * Fold one SDK `result` message's usage into the cumulative stats (mutates + returns).
+ * estInputTokens counts fresh + cache-read + cache-creation input (matching the
+ * recycle accounting); estOutputTokens is the generated output.
+ */
+export function recordResultUsage(stats, usage) {
+    const u = usage ?? {};
+    stats.turns += 1;
+    stats.estInputTokens +=
+        (u.input_tokens ?? 0) + (u.cache_read_input_tokens ?? 0) + (u.cache_creation_input_tokens ?? 0);
+    stats.estOutputTokens += u.output_tokens ?? 0;
+    return stats;
+}
+/**
+ * A `/usage`-style structured one-liner for the runtime log — a single greppable
+ * line (log-exporter / Loki friendly). Native Prometheus is deliberately deferred
+ * (§4.2): the one-shot daemon exposes no metrics series to mirror, so a scrapable
+ * log line is the sensible surface for a default-off feature.
+ */
+export function formatUsageLine(agentId, stats, uptimeSec) {
+    const uptime = Math.max(0, Math.floor(uptimeSec));
+    return (`[usage] employee=${agentId} uptime_s=${uptime} turns=${stats.turns} ` +
+        `est_input_tokens=${stats.estInputTokens} est_output_tokens=${stats.estOutputTokens} ` +
+        `session_recycles=${stats.sessionRecycles} reconnects=${stats.reconnects} dedup_hits=${stats.dedupHits}`);
+}
+/**
+ * Env for the in-session MCP the streaming runtime launches. Critically sets
+ * `AGENTHUB_HEADLESS=true`: without it, a failed startup reconnect routes the
+ * model to `agent_register`, which polls a browser-confirm flow for 10 min
+ * (3000ms × 200) that nobody can complete in a headless SDK subprocess — the
+ * observed ~7-min stall (§3). Headless routes `agent_register` to the fast,
+ * non-interactive register instead. A user API key (when the daemon has one) is
+ * passed through so any such fallback register is coherent and user-owned rather
+ * than a browser round-trip.
+ */
+export function inSessionMcpEnv(opts) {
+    const env = {
+        AGENTHUB_URL: opts.apiUrl,
+        AGENTHUB_API_KEY: opts.apiKey,
+        AGENTHUB_AGENT_ID: opts.agentId,
+        AGENTHUB_DISABLE_WEBSOCKET: "true",
+        AGENTHUB_HEADLESS: "true",
+    };
+    if (opts.userApiKey)
+        env.AGENTHUB_USER_API_KEY = opts.userApiKey;
+    return env;
+}
+/**
+ * Fail-fast identity guard the runtime previously lacked. The daemon establishes
+ * the worker connect token in the workspace's `.agenthub/state` before handing
+ * off (and reconnect is a pure re-attach server-side, so the in-session MCP
+ * safely shares it). If that state is absent the hand-off is broken; refuse to
+ * start sessions (throw → `main()` exits non-zero → the daemon restarts and
+ * re-heals identity) rather than letting the in-session MCP hang on registration.
+ */
+export function assertWorkerIdentityReady(stateExists, agentId) {
+    if (!stateExists) {
+        throw new Error(`no worker connect-token state for "${agentId}" in the workspace — refusing to ` +
+            `start streaming sessions. The daemon establishes .agenthub/state before handing ` +
+            `off; a missing token would hang the in-session MCP. Exiting for restart + re-heal.`);
+    }
+}
+//# sourceMappingURL=streamingRuntimeLib.js.map

package/dist/streamingRuntimeLib.js.map

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

package/dist/streamingRuntimeLib.test.d.ts

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

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

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

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.
@@ -738,7 +773,7 @@ export function registerTools() {
         },
         {
             name: "slack_upload_file",
-            description: "Upload a file you produced (PDF, CSV, docx, deck, log, etc.) to a Slack channel or a person's DM (employees only, governed). Generate the file locally first, then call this with the target and the file's local path. target is a Slack channel id (C0123ABC), a #channel-name (the bot must be a member), or a user id (U0123ABC) to deliver it as a DM. For delivering into your current task's thread, use deliver_file instead.",
+            description: "Upload a file you produced (PDF, CSV, docx, deck, log, etc.) to a Slack channel or a person's DM. Employees use a trusted path; other agents (e.g. a Claude Code session) use a governed path — the target must be on the deployment's file-delivery allowlist and the kill switch enabled, else the call is rejected (target_not_allowed / file_delivery_disabled). Generate the file locally first, then call this with the target and the file's local path. target is a Slack channel id (C0123ABC), a #channel-name (the bot must be a member), or a user id (U0123ABC) to deliver it as a DM. For delivering into your current task's thread, use deliver_file instead.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -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.");