@ziggs-ai/ziggs-mcp 0.37.3 → 0.37.4

package/dist/inboxCompact.d.ts

@@ -4,9 +4,9 @@
  * Every assistant start-up pays for one inbox read, and it was several times
  * the size of the connect text before any content was opened. This changes how
  * the result is written, never what it says: which deliveries are visible,
- * their order, their reach, the acknowledgement tokens, the counters and the
- * lease all come from the server unchanged. What goes is only what can be read
- * back from what stays:
+ * their order within a thread, their reach, the acknowledgement tokens, the
+ * counters and the lease all come from the server unchanged. What goes is only
+ * what can be read back from what stays:
  *
  * - a delivery field that is null, false or empty (absent reads the same);
  * - `partyKind` on a delivery, which `sources` already gives for its `partyId`,
@@ -24,17 +24,61 @@
  *
  * Acknowledgement stays exact: every `ackTo` — the envelope's, each row's and
  * the ack step's — is passed through byte for byte.
+ *
+ * The rows are written grouped rather than as one flat list: by who they are
+ * for, then by who sent them, then by the chat, task or agreement they are
+ * about. A flat list mixed the assistant's own work with mail it
+ * only passes along to its person and mail for the person's other
+ * assistants, and the split lived in one sentence of counts. Every row is
+ * still there, oldest first inside its thread; see {@link groupDeliveries}.
  */
 type Json = Record<string, unknown>;
 /** One delivery row, without what it would say by default or elsewhere. */
 export declare function compactDelivery(row: Json, kindOfParty: Map<string, unknown>, usualPartyId?: unknown): Json;
+/** Who an inbox read belongs to: the connection's assistants and their person. */
+export interface InboxReader {
+    agentIds: readonly string[];
+    /** The person the assistants work for; read off the human source when absent. */
+    personId?: string | null;
+}
+/** The sections of a grouped inbox, in the order they are written. */
+export declare const INBOX_SECTIONS: readonly ["forYou", "forYourPerson", "forOtherAssistants", "context"];
+export type InboxSection = (typeof INBOX_SECTIONS)[number];
+/**
+ * Who a row is for. One rule for the grouping and for the counts in the
+ * notice, so the two cannot disagree: assigned to one of the reader's
+ * assistants is theirs to handle; unassigned and flagged for a human is the
+ * person's, which the assistant passes along; assigned to anyone else is
+ * another assistant's; the rest nobody is asked to act on.
+ */
+export declare function sectionOf(row: Json, agentIds: readonly string[]): InboxSection;
+/**
+ * The window's rows, grouped: section, then sender, then thread.
+ *
+ * Nothing is hidden and nothing is reordered within a thread. Senders and
+ * threads are written in the order their oldest row arrived, which is the
+ * order the server sends (oldest first), except that the reader's own actions
+ * and their person's come last in a section: they are a record of what this
+ * side did, not news from anyone.
+ *
+ * A row drops only what its place in the grouping says: the sender (the
+ * group's `from`), the thread's own id, the assignee in `forYou` when the
+ * connection has one assistant, and `needsHuman` in `forYourPerson`. A thread
+ * names the first agreement its rows sit under; a row under another one keeps
+ * its own, and a row under none says `agreementId: null`, so every row reads
+ * back exactly.
+ */
+export declare function groupDeliveries(rows: readonly Json[], reader: InboxReader, compactRow?: (row: Json) => Json): Partial<Record<InboxSection, Json[]>>;
 /**
  * The compact inbox result. Takes the result exactly as it would otherwise be
  * returned and gives back the same information in fewer characters.
+ *
+ * With a reader, `deliveries` is written grouped ({@link groupDeliveries});
+ * without one there is no telling whose a row is, so it stays one list.
  */
-export declare function compactInboxResult(result: Json): Json;
+export declare function compactInboxResult(result: Json, reader?: InboxReader): Json;
 /** The inbox result as one line of JSON: indentation is most of nothing. */
-export declare function compactTextResult(data: Json): {
+export declare function compactTextResult(data: Json, reader?: InboxReader): {
     content: {
         type: "text";
         text: string;

package/dist/inboxCompact.js

@@ -4,9 +4,9 @@
  * Every assistant start-up pays for one inbox read, and it was several times
  * the size of the connect text before any content was opened. This changes how
  * the result is written, never what it says: which deliveries are visible,
- * their order, their reach, the acknowledgement tokens, the counters and the
- * lease all come from the server unchanged. What goes is only what can be read
- * back from what stays:
+ * their order within a thread, their reach, the acknowledgement tokens, the
+ * counters and the lease all come from the server unchanged. What goes is only
+ * what can be read back from what stays:
  *
  * - a delivery field that is null, false or empty (absent reads the same);
  * - `partyKind` on a delivery, which `sources` already gives for its `partyId`,
@@ -24,6 +24,13 @@
  *
  * Acknowledgement stays exact: every `ackTo` — the envelope's, each row's and
  * the ack step's — is passed through byte for byte.
+ *
+ * The rows are written grouped rather than as one flat list: by who they are
+ * for, then by who sent them, then by the chat, task or agreement they are
+ * about. A flat list mixed the assistant's own work with mail it
+ * only passes along to its person and mail for the person's other
+ * assistants, and the split lived in one sentence of counts. Every row is
+ * still there, oldest first inside its thread; see {@link groupDeliveries}.
  */
 const isRecord = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
 /** Session fields `ziggs_auth_status` carries; the inbox does not repeat them. */
@@ -84,11 +91,140 @@ function usualPartyOf(rows) {
             [best, most] = [id, n];
     return best;
 }
+/** The sections of a grouped inbox, in the order they are written. */
+export const INBOX_SECTIONS = ['forYou', 'forYourPerson', 'forOtherAssistants', 'context'];
+/**
+ * Who a row is for. One rule for the grouping and for the counts in the
+ * notice, so the two cannot disagree: assigned to one of the reader's
+ * assistants is theirs to handle; unassigned and flagged for a human is the
+ * person's, which the assistant passes along; assigned to anyone else is
+ * another assistant's; the rest nobody is asked to act on.
+ */
+export function sectionOf(row, agentIds) {
+    const assignee = row.assigneeId ? String(row.assigneeId) : '';
+    if (assignee && agentIds.includes(assignee))
+        return 'forYou';
+    if (!assignee && row.needsHuman === true)
+        return 'forYourPerson';
+    if (assignee)
+        return 'forOtherAssistants';
+    return 'context';
+}
+/** What a row is about: its chat, else its task, else its agreement, else itself. */
+function anchorOf(row) {
+    if (row.chatId)
+        return ['chatId', String(row.chatId)];
+    if (row.taskId)
+        return ['taskId', String(row.taskId)];
+    if (row.agreementId)
+        return ['agreementId', String(row.agreementId)];
+    return [row.kind === 'artifact' ? 'artifactId' : 'resourceId', String(row.resourceId)];
+}
+/**
+ * The window's rows, grouped: section, then sender, then thread.
+ *
+ * Nothing is hidden and nothing is reordered within a thread. Senders and
+ * threads are written in the order their oldest row arrived, which is the
+ * order the server sends (oldest first), except that the reader's own actions
+ * and their person's come last in a section: they are a record of what this
+ * side did, not news from anyone.
+ *
+ * A row drops only what its place in the grouping says: the sender (the
+ * group's `from`), the thread's own id, the assignee in `forYou` when the
+ * connection has one assistant, and `needsHuman` in `forYourPerson`. A thread
+ * names the first agreement its rows sit under; a row under another one keeps
+ * its own, and a row under none says `agreementId: null`, so every row reads
+ * back exactly.
+ */
+export function groupDeliveries(rows, reader, compactRow = (row) => ({ ...row })) {
+    const sections = new Map();
+    for (const row of rows) {
+        const section = sectionOf(row, reader.agentIds);
+        const from = row.actorId ? String(row.actorId) : null;
+        const anchor = anchorOf(row);
+        let senders = sections.get(section);
+        if (!senders)
+            sections.set(section, (senders = new Map()));
+        let group = senders.get(String(from));
+        if (!group)
+            senders.set(String(from), (group = { from, threads: new Map() }));
+        const key = anchor.join(':');
+        let thread = group.threads.get(key);
+        if (!thread)
+            group.threads.set(key, (thread = { anchor, rows: [] }));
+        thread.rows.push(row);
+    }
+    const own = (from) => from !== null && (reader.agentIds.includes(from) || from === reader.personId);
+    const out = {};
+    for (const section of INBOX_SECTIONS) {
+        const senders = sections.get(section);
+        if (!senders)
+            continue;
+        const ordered = [...senders.values()];
+        out[section] = [
+            ...ordered.filter((g) => !own(g.from)),
+            ...ordered.filter((g) => own(g.from)),
+        ].map((g) => {
+            const threads = [...g.threads.values()].map((t) => writeThread(t, section, reader, compactRow));
+            const count = [...g.threads.values()].reduce((n, t) => n + t.rows.length, 0);
+            return {
+                from: g.from,
+                ...(g.from !== null && reader.agentIds.includes(g.from) ? { you: true } : {}),
+                ...(g.from !== null && g.from === reader.personId ? { yourPerson: true } : {}),
+                count,
+                threads,
+            };
+        });
+    }
+    return out;
+}
+function writeThread(thread, section, reader, compactRow) {
+    const [field, id] = thread.anchor;
+    const lifted = field === 'agreementId'
+        ? null
+        : thread.rows.map((r) => r.agreementId).find(Boolean) ?? null;
+    const rows = thread.rows.map((original) => {
+        const row = compactRow(original);
+        delete row.actorId;
+        if (field !== 'resourceId' && field !== 'artifactId')
+            delete row[field];
+        if (lifted) {
+            if (row.agreementId === lifted)
+                delete row.agreementId;
+            else if (!row.agreementId)
+                row.agreementId = null;
+        }
+        if (section === 'forYou') {
+            if (reader.agentIds.length === 1)
+                delete row.assigneeId;
+            if (row.assignedToConnection === true)
+                delete row.assignedToConnection;
+        }
+        if (section === 'forYourPerson')
+            delete row.needsHuman;
+        return row;
+    });
+    return { [field]: id, ...(lifted ? { agreementId: lifted } : {}), rows };
+}
+/** The reader's assistants, without empty ids, and their person. */
+function readerOf(result, reader) {
+    const agentIds = (reader?.agentIds ?? []).filter(Boolean);
+    if (!agentIds.length)
+        return null;
+    const human = Array.isArray(result.sources)
+        ? result.sources.find((s) => isRecord(s) && s.partyKind === 'human')
+        : undefined;
+    const personId = reader?.personId ?? (isRecord(human) ? String(human.partyId) : null);
+    return { agentIds, personId };
+}
 /**
  * The compact inbox result. Takes the result exactly as it would otherwise be
  * returned and gives back the same information in fewer characters.
+ *
+ * With a reader, `deliveries` is written grouped ({@link groupDeliveries});
+ * without one there is no telling whose a row is, so it stays one list.
  */
-export function compactInboxResult(result) {
+export function compactInboxResult(result, reader) {
     const kindOfParty = new Map();
     if (Array.isArray(result.sources))
         for (const s of result.sources)
@@ -101,7 +237,10 @@ export function compactInboxResult(result) {
         const usual = usualPartyOf(result.deliveries);
         if (usual !== undefined)
             out.deliveriesPartyId = usual;
-        out.deliveries = result.deliveries.map((d) => isRecord(d) ? compactDelivery(d, kindOfParty, usual) : d);
+        const whose = readerOf(result, reader);
+        out.deliveries = whose
+            ? groupDeliveries(result.deliveries.filter(isRecord), whose, (d) => compactDelivery(d, kindOfParty, usual))
+            : result.deliveries.map((d) => isRecord(d) ? compactDelivery(d, kindOfParty, usual) : d);
     }
     if (isRecord(result.session))
         out.session = compactSession(result.session, result.connectionNotices);
@@ -135,9 +274,9 @@ export function compactInboxResult(result) {
     return out;
 }
 /** The inbox result as one line of JSON: indentation is most of nothing. */
-export function compactTextResult(data) {
+export function compactTextResult(data, reader) {
     return {
-        content: [{ type: 'text', text: JSON.stringify(compactInboxResult(data)) }],
+        content: [{ type: 'text', text: JSON.stringify(compactInboxResult(data, reader)) }],
     };
 }
 /**
@@ -152,19 +291,17 @@ export function windowNote(deliveries, selfAgentIds, outOfReach) {
     const rows = Array.isArray(deliveries) ? deliveries.filter(isRecord) : [];
     if (!rows.length)
         return '';
-    const mine = rows.filter((d) => selfAgentIds.includes(String(d.assigneeId))).length;
-    const person = rows.filter((d) => !d.assigneeId && d.needsHuman === true).length;
-    const others = rows.filter((d) => d.assigneeId && !selfAgentIds.includes(String(d.assigneeId))).length;
-    // Rows nobody is asked to handle (no assignee, not the person's) are context.
-    const context = rows.length - mine - person - others;
-    const n = (k, one, many) => `${k} ${k === 1 ? one : many}`;
-    const parts = [n(mine, 'is assigned to you', 'are assigned to you')];
-    if (person)
-        parts.push(`${person} ${person === 1 ? 'needs' : 'need'} your person`);
-    if (others)
-        parts.push(`${others} ${others === 1 ? 'is' : 'are'} for other assistants`);
-    if (context)
-        parts.push(`${context} ${context === 1 ? 'is' : 'are'} context`);
+    // The same rule the grouping uses, so each count is its section's size.
+    const count = (s) => rows.filter((d) => sectionOf(d, selfAgentIds) === s).length;
+    const words = {
+        forYou: 'yours to handle',
+        forYourPerson: 'pass these along to your person',
+        forOtherAssistants: 'your person’s other assistants',
+        context: 'nobody is asked to act',
+    };
+    // forYou is always named, so "nothing for you" is said rather than implied.
+    const parts = INBOX_SECTIONS.filter((s) => s === 'forYou' || count(s) > 0).map((s) => `${s} ${count(s)} (${words[s]})`);
     const reach = outOfReach ? ` ${outOfReach} of them ${outOfReach === 1 ? 'is' : 'are'} out of reach.` : '';
-    return `Those counts are decisions and tasks, not messages. This window has ${n(rows.length, 'delivery', 'deliveries')}: ${parts.join(', ')}.${reach}`;
+    const total = `${rows.length} ${rows.length === 1 ? 'delivery' : 'deliveries'}`;
+    return `Those counts are decisions and tasks, not messages. This window has ${total}, grouped by who they are for, then by sender: ${parts.join(', ')}.${reach}`;
 }

package/dist/tools.js

@@ -692,12 +692,14 @@ export function registerZiggsTools(server, creds, cfg) {
                 }
             }
             const news = formatInboxToolResult(inbox, null, cfg.ZIGGS_WEB_URL, undefined, reach, undefined, { agentId: creds.agentId, ownerUserId: ownerPrincipalId(creds, cfg) });
+            // Whose rows are whose, so the deliveries come back grouped.
+            const reader = { agentIds: [creds.agentId], personId: ownerPrincipalId(creds, cfg) };
             // A long-poll is a continuation of a session that already oriented
             // itself, so it returns news only. A cold call is the session start, and
             // carries what the other two orientation tools used to each be called
             // for: the binding, the decisions, and the card.
             if (waitSeconds != null)
-                return compactTextResult(news);
+                return compactTextResult(news, reader);
             const [bindingSettled, readsSettled] = await sessionStart;
             const session = bindingSettled.status === 'fulfilled'
                 ? bindingSettled.value
@@ -712,7 +714,7 @@ export function registerZiggsTools(server, creds, cfg) {
                     ...news,
                     session,
                     sessionActionsFetchError: readsSettled.reason.message,
-                });
+                }, reader);
             }
             const actions = buildSessionActions(inbox, readsSettled.value, creds, cfg);
             // No prose list of next actions rides here: the calls are in
@@ -729,7 +731,7 @@ export function registerZiggsTools(server, creds, cfg) {
                 ...(note && typeof actions.notice === 'string'
                     ? { notice: `${actions.notice} ${note}` }
                     : {}),
-            });
+            }, reader);
         }
         catch (e) {
             return toolError(e);
@@ -754,7 +756,10 @@ export function registerZiggsTools(server, creds, cfg) {
         registerStrictTool(server, 'ziggs_inbox_claim', {}, destructive('Claim the inbox for this worker'), async () => {
             try {
                 const client = inboxFor(creds);
-                return compactTextResult(await client.getInbox());
+                return compactTextResult(await client.getInbox(), {
+                    agentIds: [creds.agentId],
+                    personId: ownerPrincipalId(creds, cfg),
+                });
             }
             catch (e) {
                 return toolError(e);

package/dist/workspaceRouting.js

@@ -235,8 +235,8 @@ export class WorkspaceRouter {
                     ...(name === 'ziggs_inbox' && args.waitSeconds == null ? { rules: sessionRules('directory') } : {}),
                     ...(note && typeof pending.notice === 'string' ? { notice: `${pending.notice} ${note}` } : {}),
                     session: { workspaces },
-                    instruction: `Assigned to any of agentIds is your work. ${ASK_YOUR_HUMAN}`,
-                });
+                    instruction: `deliveries.forYou is your work; deliveries.forYourPerson is for your person to see. ${ASK_YOUR_HUMAN}`,
+                }, { agentIds: self.agentIds ?? [] });
             }
             if (name === 'ziggs_inbox_peek') {
                 return result(await this.client.request(`inbox/peek?wait=${Number(args.waitSeconds ?? 0)}`));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/ziggs-mcp",
-  "version": "0.37.3",
+  "version": "0.37.4",
   "description": "MCP server for Claude Code, Cursor, and other MCP hosts \u2014 act as your Ziggs delegate agent",
   "type": "module",
   "bin": {
@@ -47,7 +47,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ziggs-ai/api-client": "0.37.1",
+    "@ziggs-ai/api-client": "0.37.4",
     "dotenv": "^16.6.1",
     "zod": "^3.24.2",
     "zod-to-json-schema": "^3.25.1"