agenthub-multiagent-mcp 1.60.0 → 1.64.0

package/dist/tools/inboxBounds.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Bounds for the check_inbox payload (fix-inbox-delivery-and-tool-wrapping §1).
+ *
+ * check_inbox used to pass no `limit`, so the server applied its own default of
+ * 50 messages with full bodies and nothing truncated anywhere in the path. One
+ * such call measured 115,769 characters across 787 lines, exceeded the
+ * tool-result token budget, and never reached the model — the harness spilled it
+ * to a file. From the model's seat an unusable result is indistinguishable from
+ * a hang, which is how it was first reported.
+ *
+ * The cap alone would not be a fix. A caller that silently receives 10 of 40
+ * messages has no way to know, and the loss happened precisely because a
+ * slash-command bulk-marked read a result nobody had actually seen. So every
+ * bound here is paired with a signal: `truncated`, `omitted_count`, and a
+ * `_truncated` marker naming the original byte length on any clipped body.
+ *
+ * The rule that follows — never bulk-ack a truncated result — belongs to the
+ * caller, and is why the bundled `inbox` skill is part of this change.
+ */
+import type { Message } from "../client.js";
+/** Messages returned when the caller names no limit. */
+export declare const CHECK_INBOX_DEFAULT_LIMIT = 10;
+/**
+ * Hard ceiling on messages per call, whatever the caller asks for. The server
+ * clamps too; this stops a client from making the request in the first place.
+ */
+export declare const CHECK_INBOX_MAX_LIMIT = 50;
+/**
+ * Per-message body cap. Generous enough for a normal A2A message to arrive
+ * whole — the bodies that blew the budget were multi-kilobyte bug reports — and
+ * small enough that a full page of them cannot.
+ */
+export declare const CHECK_INBOX_BODY_CAP_BYTES = 4000;
+/** A message body clipped by the cap, carrying its true length. */
+export interface TruncationMarker {
+    original_bytes: number;
+}
+export interface BoundedInbox {
+    messages: (Message & {
+        _truncated?: TruncationMarker;
+    })[];
+    /** Total matching the query server-side, not the number returned. */
+    total: number;
+    returned: number;
+    omitted_count: number;
+    /** True when any message was withheld OR any body was clipped. */
+    truncated: boolean;
+}
+/**
+ * Resolve the limit to send to the server.
+ *
+ * A missing, non-numeric, zero or negative limit takes the default rather than
+ * meaning "unbounded" — "no limit" is the bug this exists to remove, and it must
+ * not be reachable by typo or by a caller passing 0. This mirrors
+ * `requestTimeoutMs`, where a malformed override also falls back rather than
+ * disabling the deadline.
+ */
+export declare function resolveInboxLimit(requested?: unknown): number;
+/**
+ * Bound an inbox response and declare what was withheld.
+ *
+ * `total` is the server's count for the query, which may exceed the rows
+ * returned; `omitted_count` is the difference. A clipped body also sets
+ * `truncated`, because a caller deciding whether it is safe to acknowledge
+ * these messages needs one flag that means "you did not get everything",
+ * not two it might check only one of.
+ */
+export declare function boundInbox(raw: {
+    messages?: Message[];
+    total?: number;
+    /**
+     * How many matched the query server-side, independent of the page size. The
+     * server's `total` has always meant "how many are in this response", so it
+     * cannot answer "what was withheld" — `matching_total` was added for that.
+     * Absent against an older server, in which case the omitted count collapses
+     * to 0 and only body clipping can set `truncated`.
+     */
+    matching_total?: number;
+}): BoundedInbox;
+//# sourceMappingURL=inboxBounds.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"inboxBounds.d.ts","sourceRoot":"","sources":["../../src/tools/inboxBounds.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C,wDAAwD;AACxD,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C;;;GAGG;AACH,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAExC;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,OAAO,CAAC;AAE/C,mEAAmE;AACnE,MAAM,WAAW,gBAAgB;IAC/B,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,CAAC,OAAO,GAAG;QAAE,UAAU,CAAC,EAAE,gBAAgB,CAAA;KAAE,CAAC,EAAE,CAAC;IAC1D,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,kEAAkE;IAClE,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,CAO7D;AAyBD;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE;IAC9B,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,GAAG,YAAY,CAyBf"}

package/dist/tools/inboxBounds.js

@@ -0,0 +1,105 @@
+/**
+ * Bounds for the check_inbox payload (fix-inbox-delivery-and-tool-wrapping §1).
+ *
+ * check_inbox used to pass no `limit`, so the server applied its own default of
+ * 50 messages with full bodies and nothing truncated anywhere in the path. One
+ * such call measured 115,769 characters across 787 lines, exceeded the
+ * tool-result token budget, and never reached the model — the harness spilled it
+ * to a file. From the model's seat an unusable result is indistinguishable from
+ * a hang, which is how it was first reported.
+ *
+ * The cap alone would not be a fix. A caller that silently receives 10 of 40
+ * messages has no way to know, and the loss happened precisely because a
+ * slash-command bulk-marked read a result nobody had actually seen. So every
+ * bound here is paired with a signal: `truncated`, `omitted_count`, and a
+ * `_truncated` marker naming the original byte length on any clipped body.
+ *
+ * The rule that follows — never bulk-ack a truncated result — belongs to the
+ * caller, and is why the bundled `inbox` skill is part of this change.
+ */
+/** Messages returned when the caller names no limit. */
+export const CHECK_INBOX_DEFAULT_LIMIT = 10;
+/**
+ * Hard ceiling on messages per call, whatever the caller asks for. The server
+ * clamps too; this stops a client from making the request in the first place.
+ */
+export const CHECK_INBOX_MAX_LIMIT = 50;
+/**
+ * Per-message body cap. Generous enough for a normal A2A message to arrive
+ * whole — the bodies that blew the budget were multi-kilobyte bug reports — and
+ * small enough that a full page of them cannot.
+ */
+export const CHECK_INBOX_BODY_CAP_BYTES = 4000;
+/**
+ * Resolve the limit to send to the server.
+ *
+ * A missing, non-numeric, zero or negative limit takes the default rather than
+ * meaning "unbounded" — "no limit" is the bug this exists to remove, and it must
+ * not be reachable by typo or by a caller passing 0. This mirrors
+ * `requestTimeoutMs`, where a malformed override also falls back rather than
+ * disabling the deadline.
+ */
+export function resolveInboxLimit(requested) {
+    const n = typeof requested === "number"
+        ? requested
+        : Number.parseInt(String(requested ?? ""), 10);
+    if (!Number.isFinite(n) || n <= 0)
+        return CHECK_INBOX_DEFAULT_LIMIT;
+    return Math.min(Math.trunc(n), CHECK_INBOX_MAX_LIMIT);
+}
+/**
+ * Apply the body cap to one message, attaching a marker when it bites.
+ *
+ * Measured in UTF-16 code units (`String.length`), matching how the payload is
+ * counted downstream. `original_bytes` keeps the field name the session-event
+ * truncation marker already uses, so there is one truncation idiom in the
+ * codebase rather than two.
+ */
+function capBody(msg) {
+    const body = typeof msg.body === "string" ? msg.body : "";
+    if (body.length <= CHECK_INBOX_BODY_CAP_BYTES)
+        return { msg, clipped: false };
+    return {
+        msg: {
+            ...msg,
+            body: body.slice(0, CHECK_INBOX_BODY_CAP_BYTES),
+            _truncated: { original_bytes: body.length },
+        },
+        clipped: true,
+    };
+}
+/**
+ * Bound an inbox response and declare what was withheld.
+ *
+ * `total` is the server's count for the query, which may exceed the rows
+ * returned; `omitted_count` is the difference. A clipped body also sets
+ * `truncated`, because a caller deciding whether it is safe to acknowledge
+ * these messages needs one flag that means "you did not get everything",
+ * not two it might check only one of.
+ */
+export function boundInbox(raw) {
+    const messages = raw.messages ?? [];
+    let anyClipped = false;
+    const capped = messages.map((m) => {
+        const { msg, clipped } = capBody(m);
+        if (clipped)
+            anyClipped = true;
+        return msg;
+    });
+    const returned = capped.length;
+    // Prefer matching_total; fall back to total for an older server. Trust the
+    // larger of the two either way: a count below the rows actually sent is
+    // wrong, and a negative omitted count would read as "nothing withheld" — the
+    // one answer that must never be wrong in this direction.
+    const reported = raw.matching_total ?? raw.total ?? returned;
+    const total = Math.max(reported, returned);
+    const omitted = total - returned;
+    return {
+        messages: capped,
+        total,
+        returned,
+        omitted_count: omitted,
+        truncated: omitted > 0 || anyClipped,
+    };
+}
+//# sourceMappingURL=inboxBounds.js.map

package/dist/tools/inboxBounds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inboxBounds.js","sourceRoot":"","sources":["../../src/tools/inboxBounds.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,wDAAwD;AACxD,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,CAAC;AAE5C;;;GAGG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,EAAE,CAAC;AAExC;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,IAAI,CAAC;AAiB/C;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,SAAmB;IACnD,MAAM,CAAC,GACL,OAAO,SAAS,KAAK,QAAQ;QAC3B,CAAC,CAAC,SAAS;QACX,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;IACnD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,yBAAyB,CAAC;IACpE,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,qBAAqB,CAAC,CAAC;AACxD,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,OAAO,CACd,GAAY;IAEZ,MAAM,IAAI,GAAG,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1D,IAAI,IAAI,CAAC,MAAM,IAAI,0BAA0B;QAAE,OAAO,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAC9E,OAAO;QACL,GAAG,EAAE;YACH,GAAG,GAAG;YACN,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,0BAA0B,CAAC;YAC/C,UAAU,EAAE,EAAE,cAAc,EAAE,IAAI,CAAC,MAAM,EAAE;SAC5C;QACD,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CAAC,GAW1B;IACC,MAAM,QAAQ,GAAG,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC;IACpC,IAAI,UAAU,GAAG,KAAK,CAAC;IACvB,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;QAChC,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QACpC,IAAI,OAAO;YAAE,UAAU,GAAG,IAAI,CAAC;QAC/B,OAAO,GAAG,CAAC;IACb,CAAC,CAAC,CAAC;IAEH,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC;IAC/B,2EAA2E;IAC3E,wEAAwE;IACxE,6EAA6E;IAC7E,yDAAyD;IACzD,MAAM,QAAQ,GAAG,GAAG,CAAC,cAAc,IAAI,GAAG,CAAC,KAAK,IAAI,QAAQ,CAAC;IAC7D,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC3C,MAAM,OAAO,GAAG,KAAK,GAAG,QAAQ,CAAC;IAEjC,OAAO;QACL,QAAQ,EAAE,MAAM;QAChB,KAAK;QACL,QAAQ;QACR,aAAa,EAAE,OAAO;QACtB,SAAS,EAAE,OAAO,GAAG,CAAC,IAAI,UAAU;KACrC,CAAC;AACJ,CAAC"}

package/dist/tools/inboxBounds.test.d.ts

@@ -0,0 +1,15 @@
+/**
+ * fix-inbox-delivery-and-tool-wrapping §1 — check_inbox bounds its payload and
+ * declares what it withheld.
+ *
+ * Why this file exists: check_inbox passed no `limit`, so the server returned
+ * its default 50 messages with full bodies and nothing truncated anywhere. One
+ * such call measured 115,769 characters, exceeded the tool-result token budget
+ * and never reached the model. A slash-command then bulk-marked those messages
+ * read, and because `unread_only` only returns 'pending'/'delivered' rows they
+ * became invisible for good. Bounding the payload is half the fix; SAYING what
+ * was withheld is the other half, because a silent cap turns loud breakage into
+ * quiet breakage.
+ */
+export {};
+//# sourceMappingURL=inboxBounds.test.d.ts.map

package/dist/tools/inboxBounds.test.d.ts.map

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

package/dist/tools/inboxBounds.test.js

@@ -0,0 +1,135 @@
+/**
+ * fix-inbox-delivery-and-tool-wrapping §1 — check_inbox bounds its payload and
+ * declares what it withheld.
+ *
+ * Why this file exists: check_inbox passed no `limit`, so the server returned
+ * its default 50 messages with full bodies and nothing truncated anywhere. One
+ * such call measured 115,769 characters, exceeded the tool-result token budget
+ * and never reached the model. A slash-command then bulk-marked those messages
+ * read, and because `unread_only` only returns 'pending'/'delivered' rows they
+ * became invisible for good. Bounding the payload is half the fix; SAYING what
+ * was withheld is the other half, because a silent cap turns loud breakage into
+ * quiet breakage.
+ */
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { handleToolCall } from "./index.js";
+import { CHECK_INBOX_DEFAULT_LIMIT, CHECK_INBOX_MAX_LIMIT, CHECK_INBOX_BODY_CAP_BYTES, } from "./inboxBounds.js";
+vi.mock("../state.js", () => ({
+    loadState: vi.fn(() => null),
+    saveState: vi.fn(),
+    deleteState: vi.fn(),
+    stateExists: vi.fn(() => false),
+    getCurrentOwner: vi.fn(() => "test-user"),
+}));
+vi.mock("../hooks/sessionState.js", async (importOriginal) => {
+    const actual = (await importOriginal());
+    return { ...actual, isEnabled: vi.fn(() => false) };
+});
+const mockClient = {
+    getBaseUrl: vi.fn(() => "http://localhost:8787/api"),
+    getInbox: vi.fn(),
+    getPendingTasks: vi.fn(),
+};
+/** n messages, each body `bodyBytes` long, newest first like GetInbox returns. */
+function makeMessages(n, bodyBytes = 10) {
+    return Array.from({ length: n }, (_, i) => ({
+        id: `msg-${i}`,
+        from_agent: "sender",
+        to_agent: "test-agent",
+        broadcast: false,
+        type: "question",
+        subject: `subject ${i}`,
+        body: "x".repeat(bodyBytes),
+        status: "delivered",
+        priority: "normal",
+        created_at: new Date(Date.now() - i * 1000).toISOString(),
+    }));
+}
+describe("check_inbox payload bounds", () => {
+    let context;
+    let agentId;
+    beforeEach(() => {
+        vi.clearAllMocks();
+        agentId = "test-agent";
+        context = {
+            getCurrentAgentId: () => agentId,
+            setCurrentAgentId: (id) => {
+                agentId = id;
+            },
+            stopHeartbeat: () => { },
+            getWorkingDir: () => "/tmp",
+            setWorkingDir: () => { },
+            getPushedItems: () => ({ tasks: [], messages: [] }),
+        };
+    });
+    it("applies a default limit and reports what it withheld", async () => {
+        // The regression: 40 unread messages, no limit given by the caller.
+        vi.mocked(mockClient.getInbox).mockResolvedValue({
+            messages: makeMessages(CHECK_INBOX_DEFAULT_LIMIT),
+            total: 40,
+        });
+        const result = (await handleToolCall("check_inbox", { unread_only: true }, mockClient, context));
+        // The limit must reach the client call — omitting it is the original bug.
+        expect(mockClient.getInbox).toHaveBeenCalledWith("test-agent", true, CHECK_INBOX_DEFAULT_LIMIT);
+        expect(result.total).toBe(40);
+        expect(result.returned).toBe(CHECK_INBOX_DEFAULT_LIMIT);
+        expect(result.omitted_count).toBe(40 - CHECK_INBOX_DEFAULT_LIMIT);
+        expect(result.truncated).toBe(true);
+    });
+    it("clips an oversized body and names its original length", async () => {
+        const original = CHECK_INBOX_BODY_CAP_BYTES + 1000;
+        vi.mocked(mockClient.getInbox).mockResolvedValue({
+            messages: makeMessages(1, original),
+            total: 1,
+        });
+        const result = (await handleToolCall("check_inbox", { unread_only: true }, mockClient, context));
+        const msg = result.messages[0];
+        expect(msg.body.length).toBeLessThanOrEqual(CHECK_INBOX_BODY_CAP_BYTES);
+        expect(msg._truncated).toEqual({ original_bytes: original });
+        // A clipped body is still a withheld thing: the caller must be told.
+        expect(result.truncated).toBe(true);
+    });
+    it("reports nothing withheld when nothing was withheld", async () => {
+        vi.mocked(mockClient.getInbox).mockResolvedValue({
+            messages: makeMessages(3),
+            total: 3,
+        });
+        const result = (await handleToolCall("check_inbox", { unread_only: true }, mockClient, context));
+        expect(result.truncated).toBe(false);
+        expect(result.omitted_count).toBe(0);
+        expect(result.returned).toBe(3);
+        for (const m of result.messages) {
+            expect(m._truncated).toBeUndefined();
+            expect(m.body.length).toBe(10);
+        }
+    });
+    it("clamps a caller-supplied limit above the maximum", async () => {
+        vi.mocked(mockClient.getInbox).mockResolvedValue({
+            messages: makeMessages(CHECK_INBOX_MAX_LIMIT),
+            total: 500,
+        });
+        await handleToolCall("check_inbox", { unread_only: true, limit: 10_000 }, mockClient, context);
+        expect(mockClient.getInbox).toHaveBeenCalledWith("test-agent", true, CHECK_INBOX_MAX_LIMIT);
+    });
+    it("honours a caller-supplied limit below the maximum", async () => {
+        vi.mocked(mockClient.getInbox).mockResolvedValue({
+            messages: makeMessages(2),
+            total: 2,
+        });
+        await handleToolCall("check_inbox", { unread_only: true, limit: 2 }, mockClient, context);
+        expect(mockClient.getInbox).toHaveBeenCalledWith("test-agent", true, 2);
+    });
+    it("keeps the payload well under the budget for an inbox that once blew it", async () => {
+        // 787 rows averaging ~147 bytes of body is what produced the 115,769-char
+        // response observed on 2026-10-17. Same corpus, bounded output.
+        vi.mocked(mockClient.getInbox).mockResolvedValue({
+            messages: makeMessages(CHECK_INBOX_DEFAULT_LIMIT, 8000),
+            total: 787,
+        });
+        const result = (await handleToolCall("check_inbox", { unread_only: true }, mockClient, context));
+        expect(JSON.stringify(result).length).toBeLessThan(60_000);
+        expect(result.truncated).toBe(true);
+        expect(result.omitted_count).toBe(787 - CHECK_INBOX_DEFAULT_LIMIT);
+    });
+});
+//# sourceMappingURL=inboxBounds.test.js.map

package/dist/tools/inboxBounds.test.js.map

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

package/dist/tools/index.d.ts

@@ -13,7 +13,18 @@ export interface ToolContext {
     stopHeartbeat: () => void;
     getWorkingDir: () => string;
     setWorkingDir: (dir: string) => void;
+    /**
+     * @deprecated Destructive read; see peekPushedItems
+     * (fix-inbox-delivery-and-tool-wrapping §2). Kept so older callers compile.
+     */
     getPushedItems: () => PushedItems;
+    /** Read pushed items without consuming them. */
+    peekPushedItems?: () => PushedItems;
+    /** Consume exactly the items that made it into a built response. */
+    commitPushedItems?: (consumed: {
+        taskIds?: string[];
+        messageIds?: string[];
+    }) => void;
 }
 interface PendingTask {
     id: string;

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;AAiF/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,CA80FtC;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,CA8sFlB"}
+{"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;AAkG/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,CAyuFlB"}

package/dist/tools/index.js

@@ -2,6 +2,7 @@
  * MCP tool definitions and handlers
  */
 import { resolveAgentIdentity, missingStateGuidance, credentialIsDead, } from "../agentIdentity.js";
+import { boundInbox, resolveInboxLimit, CHECK_INBOX_DEFAULT_LIMIT, CHECK_INBOX_MAX_LIMIT, } from "./inboxBounds.js";
 import * as state from "../state.js";
 import * as contextModule from "../context.js";
 import { hookManager } from "../hooks/index.js";
@@ -9,9 +10,12 @@ import * as brainCapture from "../hooks/brainCapture.js";
 import { getBrain } from "../brain/backend.js";
 import open from "open";
 import { registerOpenSpecVizTools, handleOpenSpecVizToolCall } from "./openspec-viz/index.js";
+import { registerIntakeRequestTools, handleIntakeRequestToolCall, isIntakeRequestTool, } from "./intakeRequests.js";
 import { registerSessionControlTools, handleSessionControlToolCall, isSessionControlTool, } from "./sessionControl.js";
+import { registerGoshtiReadTools, handleGoshtiReadToolCall, isGoshtiReadTool, } from "./goshtiRead.js";
 import { installPackFromArchive } from "../skillPackInstaller.js";
 import { getServerTime, useTimeInjection } from "../lib/server-time.js";
+import { getPendingItems } from "../lib/pending-items.js";
 import { ENG_IC_CHARTER } from "../employee.js";
 import { promises as fsp } from "node:fs";
 import * as os from "node:os";
@@ -78,16 +82,23 @@ async function wrapWithPendingItems(client, agentId, result, context) {
     if (!agentId)
         return result;
     try {
-        // Get items pushed via WebSocket (if connected)
-        const pushedItems = context?.getPushedItems() || { tasks: [], messages: [] };
-        // Fetch unread messages and pending tasks in parallel
-        const [inbox, tasksResponse] = await Promise.all([
-            client.getInbox(agentId, true, 10),
-            client.getPendingTasks(agentId),
-        ]);
-        // Merge pushed items with fetched items (deduplicating by ID)
-        const fetchedMessages = inbox.messages || [];
-        const fetchedTasks = (tasksResponse.tasks || []);
+        // Read items pushed via WebSocket WITHOUT consuming them
+        // (fix-inbox-delivery-and-tool-wrapping §2.3). The old code drained the
+        // queue here, before the two fetches below — so a fetch that threw or timed
+        // out sent us to the catch with those messages already gone. They are
+        // consumed at the bottom of this function, once a response exists to carry
+        // them. peekPushedItems is optional on the context so older callers (and
+        // tests constructing a partial context) keep working.
+        const pushedItems = context?.peekPushedItems?.() ??
+            context?.getPushedItems?.() ?? { tasks: [], messages: [] };
+        // Read pending items from cache; never wait on the network
+        // (fix-inbox-delivery-and-tool-wrapping §3.2). This used to await two HTTP
+        // calls on every one of the 58 wrapped tools, each with a 45s deadline, so
+        // an unrelated tool could stall ~90s before doing its own work. A refresh
+        // now runs in the background and a cold cache simply carries nothing.
+        const cachedItems = getPendingItems(client, agentId);
+        const fetchedMessages = cachedItems.messages;
+        const fetchedTasks = cachedItems.tasks;
         // Deduplicate messages
         const messageIds = new Set(fetchedMessages.map((m) => m.id));
         const messages = [
@@ -128,7 +139,7 @@ async function wrapWithPendingItems(client, agentId, result, context) {
                 urgentAction = {
                     required: true,
                     instruction: buildUrgentInstruction(urgentMsg),
-                    message: urgentMsg,
+                    message_id: urgentMsg.id,
                 };
             }
         }
@@ -148,10 +159,20 @@ async function wrapWithPendingItems(client, agentId, result, context) {
                 console.warn("server_time injection failed:", err);
             }
         }
+        // The response now exists and carries these items, so they may be consumed
+        // (§2.3). Only the ids we actually peeked are named: anything pushed since
+        // then stays queued for the next tool call rather than being cleared away
+        // unseen. Reaching the catch above consumes nothing, which is the whole
+        // point of the split.
+        context?.commitPushedItems?.({
+            taskIds: pushedItems.tasks.map((t) => t.id),
+            messageIds: pushedItems.messages.map((m) => m.id),
+        });
         return wrapped;
     }
     catch (error) {
-        // Don't break tool call if fetch fails
+        // Don't break tool call if fetch fails. Pushed items were only peeked, so
+        // they are still queued and will be delivered by the next call.
         console.warn("Failed to fetch pending items for wrapping:", error);
         return result;
     }
@@ -167,13 +188,16 @@ function isUrgentMessage(msg) {
  * Build instruction text for urgent messages
  */
 function buildUrgentInstruction(msg) {
+    // No body here (fix-inbox-delivery-and-tool-wrapping §3.4). Interpolating
+    // ${msg.body} made this the second of three copies of the same text in one
+    // response — the others being pending_messages[] and urgent_action.message.
+    // The instruction's job is to say what to do and which message to do it
+    // about; the body is one lookup away in pending_messages.
     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.`;
+The full message is in this response's pending_messages[], id ${msg.id}. Read it there, then reply with the reply tool (message_id ${msg.id}).`;
 }
 /**
  * Build instruction text for pending tasks
@@ -690,7 +714,12 @@ export function registerTools() {
         },
         {
             name: "check_inbox",
-            description: "Check for incoming messages",
+            description: "Check for incoming messages. The response is bounded: it carries " +
+                "`total`, `returned`, `omitted_count` and `truncated`, and a clipped " +
+                "body carries `_truncated.original_bytes`. When `truncated` is true you " +
+                "did NOT receive everything — do not mark_read anything you did not " +
+                "actually read, or it becomes invisible to everyone (unread_only never " +
+                "returns a read message again). Page with `limit` instead.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -698,6 +727,13 @@ export function registerTools() {
                         type: "boolean",
                         description: "Only return unread messages (default: false)",
                     },
+                    limit: {
+                        type: "number",
+                        description: `Max messages to return (default: ${CHECK_INBOX_DEFAULT_LIMIT}, ` +
+                            `max: ${CHECK_INBOX_MAX_LIMIT}). Values above the max are clamped; ` +
+                            `0, negative and non-numeric values take the default — there is no ` +
+                            `way to request an unbounded inbox.`,
+                    },
                 },
             },
         },
@@ -2116,6 +2152,10 @@ export function registerTools() {
         },
         // Session steering + takeover (add-multiplayer-sessions §4.7, §5.9)
         ...registerSessionControlTools(),
+        // Intake requests: file, triage, scope check (add-intake-requests §6.1)
+        ...registerIntakeRequestTools(),
+        // Reading Goshti as the agent's owner (add-agent-goshti-read §3.1)
+        ...registerGoshtiReadTools(),
         // OpenSpec Visualizer tools
         ...registerOpenSpecVizTools(),
         // Intel layer tools (§2.5 — read-only MCP surface for intel.search + source catalog)
@@ -3006,6 +3046,18 @@ export async function handleToolCall(name, args, client, context) {
     if (isSessionControlTool(name)) {
         return handleSessionControlToolCall(name, args, client);
     }
+    // Intake requests (add-intake-requests §6.1). Same module pattern: the module
+    // owns its tool names and turns refusals into structured results.
+    if (isIntakeRequestTool(name)) {
+        return handleIntakeRequestToolCall(name, args, client, () => state.loadState(context.getWorkingDir())?.project_id);
+    }
+    // Goshti reads (add-agent-goshti-read §3.1). Same module pattern. The owner's
+    // grant, the per-agent switch and the fixed tool list are all the server's
+    // decisions; this only shapes the call and labels the answer as other
+    // people's words.
+    if (isGoshtiReadTool(name)) {
+        return handleGoshtiReadToolCall(name, args, client);
+    }
     switch (name) {
         // Registration
         case "agent_register": {
@@ -3682,10 +3734,19 @@ export async function handleToolCall(name, args, client, context) {
             return wrapWithPendingItems(client, agentId, result, context);
         }
         case "check_inbox": {
-            // No wrapping - already fetching messages
+            // No wrapping - already fetching messages.
+            //
+            // The limit is explicit (fix-inbox-delivery-and-tool-wrapping §1.2).
+            // Omitting it let the server apply its own default of 50 full-bodied
+            // messages; one such response measured 115,769 characters, exceeded the
+            // tool-result token budget and never reached the model at all. boundInbox
+            // then declares anything it withheld, so a caller can never acknowledge
+            // messages it did not actually receive.
             if (!agentId)
                 throw new Error("Not registered. Call agent_register first.");
-            return client.getInbox(agentId, args.unread_only);
+            const inboxLimit = resolveInboxLimit(args.limit);
+            const raw = await client.getInbox(agentId, args.unread_only, inboxLimit);
+            return boundInbox(raw);
         }
         case "mark_read": {
             const result = await client.markRead(args.message_id);