@ziggs-ai/ziggs-mcp 0.18.0 → 0.19.0

package/dist/inboxToolResult.d.ts

@@ -18,6 +18,26 @@ export interface ReadPlanCall {
 export interface ReadPlanResult {
     plan: ReadPlanCall[];
     truncated: number;
+    /**
+     * Rows the server said this reader cannot open. Listed so the agent can tell
+     * its person what arrived and what it would take to read it, instead of
+     * running a pre-filled read that refuses.
+     */
+    unreadable: Array<{
+        resourceId: string;
+    } & OutOfReachNote>;
+}
+/**
+ * The server's note on a row whose container this reader holds nothing to open.
+ *
+ * Read off the delivery rather than taken from the contract type: this client
+ * is installed independently of the server it talks to, so it has to work
+ * against a backend that predates the field as well as one that sends it.
+ */
+interface OutOfReachNote {
+    scopeKind: string;
+    scopeId: string;
+    remedy: string;
 }
 /**
  * replace the free-text `nextActions` hints with typed `readPlan`
@@ -83,3 +103,4 @@ export declare function formatInboxToolResult(inbox: InboxEnvelope, ack?: InboxA
  * `decisions`, and they must be marked correctly.
  */
 self?: DecisionSelfIds): Record<string, unknown>;
+export {};

package/dist/inboxToolResult.js

@@ -1,7 +1,18 @@
-import { grantCaveat, resolvePendingApprovalPartyId } from '@ziggs-ai/api-client';
+import { grantCaveat, planInboxAck, planPartialInboxAck, resolvePendingApprovalPartyId, } from '@ziggs-ai/api-client';
 import { formatPendingDecisionsPayload, resolveWebAppOrigin, } from './pendingDecisions.js';
 /** Keep the plan bounded; the full deliveries array still carries everything. */
 const MAX_READ_PLAN = 12;
+function outOfReachOf(d) {
+    const note = d.outOfReach;
+    if (!note || typeof note !== 'object')
+        return null;
+    const { scopeKind, scopeId, remedy } = note;
+    return typeof scopeKind === 'string' &&
+        typeof scopeId === 'string' &&
+        typeof remedy === 'string'
+        ? { scopeKind, scopeId, remedy }
+        : null;
+}
 /**
  * Where to read an artifact delivery from — a total function, so there is no
  * "none of the above" that silently drops the row. Container first (the parties
@@ -48,13 +59,38 @@ export function buildReadPlan(inbox, grantsByScope, self = { agentId: '' }) {
     // twice when several deliveries land in one chat. Collect candidates
     // uncapped; the cap is applied once, after the ack is reserved, so the ack
     // step always survives.
+    //
+    // Two lists, because only one of them can cost the ack.
+    // `mine` is what was addressed to this caller (decisions, and rows stamped
+    // for it); `ambient` is context nobody asked it to handle. A mailbox full of
+    // ambient mail — a person's, read by their assistant — overflowed the one
+    // list, the overflow dropped the ack step, and with no ack the window never
+    // moved, so the next read overflowed identically. Measured on one account:
+    // 200 rows, 23 reads dropped, ten days behind, and no way forward.
     const candidates = [];
+    const ambient = [];
     const seen = new Set();
-    const add = (key, call) => {
+    // Which assigned rows each candidate step settles, so a checkpoint ack can
+    // name what is finished once that step is done. Keyed by the step's own
+    // dedup key, because one read covers every row that landed in its chat.
+    const settledBy = new Map();
+    const candidateKeys = [];
+    const add = (key, call, mine = true, settles) => {
+        // Recorded before the dedup return: the second row landing in a chat adds
+        // no step, but the one step there already covers it.
+        if (settles) {
+            const rows = settledBy.get(key);
+            if (rows)
+                rows.push(settles);
+            else
+                settledBy.set(key, [settles]);
+        }
         if (seen.has(key))
             return;
         seen.add(key);
-        candidates.push(call);
+        if (mine)
+            candidateKeys.push(key);
+        (mine ? candidates : ambient).push(call);
     };
     // Decisions first — these also drive humanAttention (pull-only: no push).
     // The decision (approve/reject) is the human's; we only pre-fill the target.
@@ -100,7 +136,13 @@ export function buildReadPlan(inbox, grantsByScope, self = { agentId: '' }) {
     // holds one, so the read presents the right X-Context-Grant-Id without a
     // separate discover round-trip. Untagged reads still work by id.
     const grantFor = (kind, id) => grantsByScope?.get(`${kind}:${id}`)?.grantId;
-    const read = (type, viaKind, viaId) => add(`read:${type}:${viaKind}:${viaId}`, readContextCall(type, viaKind, viaId, grantFor(viaKind, viaId)));
+    const read = (type, viaKind, viaId, mine = true, settles) => add(`read:${type}:${viaKind}:${viaId}`, readContextCall(type, viaKind, viaId, grantFor(viaKind, viaId)), mine, settles);
+    /**
+     * Is this row the caller's own? With no self id configured every row counts
+     * as its own, which is the old behaviour: the plan then holds one list and
+     * the ack rides on all of it fitting, exactly as before.
+     */
+    const isMine = (d) => self.agentId === '' || d.assigneeId === self.agentId;
     // Reads — one call per place mail actually landed. The delivery names the
     // chat, agreement or task directly, so nothing has to be inferred from a scope.
     //
@@ -116,15 +158,33 @@ export function buildReadPlan(inbox, grantsByScope, self = { agentId: '' }) {
     // nothing else, and an agent following the plan acked work it never read. The
     // second is that hole closed ahead of an emitter — nothing writes an
     // anchor-less delivery today, and when something does it is planned.
-    for (const d of deliveries) {
+    //
+    // A row the server marked out of reach is not planned at all. The
+    // read behind it refuses, and handing the agent a call that always fails is
+    // what left it with no honest move: it could not open the row, could not
+    // report it, and could not ack past it.
+    const unreadable = [];
+    // Assigned first, ambient second, so a chat that carries both is planned as
+    // the caller's own work rather than as droppable context.
+    const inPlanOrder = [
+        ...deliveries.filter((d) => isMine(d)),
+        ...deliveries.filter((d) => !isMine(d)),
+    ];
+    for (const d of inPlanOrder) {
+        const note = outOfReachOf(d);
+        if (note) {
+            unreadable.push({ resourceId: d.resourceId, ...note });
+            continue;
+        }
+        const mine = isMine(d);
         switch (d.kind) {
             case 'message':
                 // A message always lands in a chat; there is nowhere else to read it.
                 if (d.chatId)
-                    read('messages', 'chat', d.chatId);
+                    read('messages', 'chat', d.chatId, mine, mine ? d.resourceId : undefined);
                 break;
             case 'artifact':
-                read('artifacts', ...artifactEntry(d));
+                read('artifacts', ...artifactEntry(d), mine, mine ? d.resourceId : undefined);
                 break;
             case 'task-state':
             case 'agreement':
@@ -148,32 +208,67 @@ export function buildReadPlan(inbox, grantsByScope, self = { agentId: '' }) {
     // never gets squeezed out exactly when there's the most news. Report how many
     // read/decision candidates the cap dropped as an explicit count.
     //
-    // Only pre-fill ack when this plan covers the whole envelope.
-    // A truncated plan (or a capped delivery list) must not hand back an ack
-    // that would clear deliveries the plan never asked the agent to handle.
-    // Reserve the ack slot only when every candidate still fits beside it;
-    // otherwise spend the full budget on reads and omit ack.
-    // A capped list is the oldest head. Acking it (with the listed ids) is
-    // safe — the newer tail is past ackTo. A truncated *plan* still omits
-    // ack, because those steps never asked the agent to handle the rest.
-    const canAckFully = !!inbox.ackTo && (inbox.truncatedRequests ?? 0) === 0;
-    const leaveRoomForAck = canAckFully && candidates.length <= MAX_READ_PLAN - 1;
-    const budget = leaveRoomForAck ? MAX_READ_PLAN - 1 : MAX_READ_PLAN;
-    const truncated = Math.max(0, candidates.length - budget);
-    const plan = candidates.slice(0, budget);
-    if (leaveRoomForAck && truncated === 0) {
-        // Assigned rows only: the server's bury-guard checks what was MINE to
-        // handle. Rows without my stamp are readable context, never mine to ack.
-        // With no self id configured, fall back to listing everything — a
-        // superset is always accepted; the guard only refuses missing ids.
-        const handledResourceIds = [
-            ...new Set([
-                ...(inbox.deliveries ?? [])
-                    .filter((d) => self.agentId === '' || d.assigneeId === self.agentId)
-                    .map((d) => d.resourceId),
-                ...(inbox.openRequestsAwaitingMe ?? []).map((q) => q.agreementId),
-            ]),
-        ].filter((id) => typeof id === 'string' && id.length > 0);
+    // The ack rides on MY steps all fitting, not on the whole plan fitting. The
+    // server's bury-guard is the thing this protects, and it asks one question:
+    // was every row assigned to me in this window handled? Ambient reads dropped
+    // by the cap are not part of that answer — they were never mine to handle,
+    // and the owner's own seen mark tracks them. Letting them veto the ack is
+    // what pinned a busy mailbox in place for good.
+    //
+    // A capped delivery list is the oldest head; acking it with the listed ids
+    // is safe, because the newer tail is past ackTo.
+    const ack = planInboxAck(inbox, {
+        ownAgentId: self.agentId || undefined,
+    });
+    // One checkpoint ack, after the FIRST assigned step.
+    //
+    // A single ack at the end freezes the watermark for the caller's whole turn,
+    // and the server hands an unanswered row to the person's stand-in after 90
+    // seconds. A delegate's turn is a model turn, so that is the long one.
+    //
+    // One checkpoint, not one per step. The plan is capped at MAX_READ_PLAN, and
+    // acking after every read would roughly halve the reads that fit — the exact
+    // pressure the two-list split above exists to relieve, and overflow here is
+    // what put an account ten days behind with no way forward.
+    //
+    // The first step is the valuable one anyway. The takeover only reaches rows
+    // already past the window, which are the oldest, and assigned reads are
+    // planned oldest-first (deliveries arrive oldest-first and `inPlanOrder`
+    // keeps assigned rows ahead of ambient). So this releases exactly the rows
+    // that are in danger, at step one instead of step eleven.
+    const firstKey = candidateKeys[0];
+    const settledFirst = firstKey ? (settledBy.get(firstKey) ?? []) : [];
+    const checkpoint = settledFirst.length > 0
+        ? planPartialInboxAck(inbox, new Set(settledFirst), {
+            ownAgentId: self.agentId || undefined,
+        })
+        : null;
+    // Never the same mark as the final ack — that is a wasted call and a second
+    // chance for the model to ack work it has not done.
+    const useCheckpoint = !!checkpoint && checkpoint.ackTo !== inbox.ackTo;
+    const reserved = (ack.allowed ? 1 : 0) + (useCheckpoint ? 1 : 0);
+    const leaveRoomForAck = ack.allowed && candidates.length <= MAX_READ_PLAN - reserved;
+    const budget = leaveRoomForAck
+        ? MAX_READ_PLAN - reserved
+        : MAX_READ_PLAN;
+    const ordered = [...candidates, ...ambient];
+    const truncated = Math.max(0, ordered.length - budget);
+    const plan = ordered.slice(0, budget);
+    if (leaveRoomForAck && useCheckpoint && plan.length > 1) {
+        plan.splice(1, 0, {
+            tool: 'ziggs_inbox',
+            args: {
+                ack: checkpoint.ackTo,
+                handledResourceIds: checkpoint.handledResourceIds,
+            },
+            why: 'checkpoint — run this as soon as the ONE step above it is done, not later: ' +
+                'it hands back the oldest mail so nobody answers it on top of you while you ' +
+                'work through the rest. Pass ack back VERBATIM (it is opaque). If the step ' +
+                'above is not done, skip this one and let the final ack cover it',
+        });
+    }
+    if (leaveRoomForAck) {
+        const handledResourceIds = ack.handledResourceIds;
         plan.push({
             tool: 'ziggs_inbox',
             args: {
@@ -185,7 +280,7 @@ export function buildReadPlan(inbox, grantsByScope, self = { agentId: '' }) {
                 'delivery assigned to you in this envelope',
         });
     }
-    return { plan, truncated };
+    return { plan, truncated, unreadable };
 }
 /**
  * forward-continuation for a read_context page. Built only from fields
@@ -279,7 +374,7 @@ export function formatInboxToolResult(inbox, ack, webOrigin, activeTasks, reach,
  */
 self = { agentId: '' }) {
     const byScope = reach?.length ? indexReachByScope(reach) : undefined;
-    const { plan: readPlan, truncated: readPlanTruncated } = buildReadPlan(inbox, byScope, self);
+    const { plan: readPlan, truncated: readPlanTruncated, unreadable, } = buildReadPlan(inbox, byScope, self);
     const origin = resolveWebAppOrigin(webOrigin);
     // This is the news half of the inbox result: counts, not cards. The cold-read
     // session block (decisions, activeWork, sessionChatCard) is layered on top of
@@ -312,6 +407,10 @@ self = { agentId: '' }) {
             : {}),
         ...(readPlan.length ? { readPlan } : {}),
         ...(readPlanTruncated ? { readPlanTruncated } : {}),
+        // Named `outOfReach` on the result too, so the one word covers the whole
+        // path: the row carries it, the plan skips it, and this is where the agent
+        // reads what to say about it.
+        ...(unreadable.length ? { outOfReach: unreadable } : {}),
     };
     const { humanAttention, ...rest } = inbox;
     const payload = ack

package/dist/pendingDecisions.js

@@ -430,11 +430,22 @@ export function formatPendingDecisionsPayload(inbox, webOrigin, self, opts) {
     const humanOnlyNote = humanOnly.length
         ? ` ${humanOnly.length} of them ${humanOnly.length === 1 ? 'is' : 'are'} the human's own to answer (respondableBy "human") — for those, hand over the link and do not call ziggs_agreement_respond; it is refused for a delegate.`
         : '';
+    // "nothing pending" is only true about mail the read actually
+    // reached. A window that stops short of the present says how far short, and
+    // that has to reach the line the model reads, not just a field beside it:
+    // an assistant answered "nothing pending" for its person from a window ten
+    // days old, while that morning's unanswered question sat outside it.
+    const backlog = inbox.backlog;
+    const behindNote = backlog
+        ? ` You are looking at a PARTIAL window: ${backlog.beyondWindow} more ${backlog.beyondWindow === 1 ? 'delivery is' : 'deliveries are'} unread past ${backlog.windowEndsAt}${backlog.newestAt ? `, the newest from ${backlog.newestAt}` : ''}. Say so rather than reporting an empty inbox, and ack this window to reach the rest.`
+        : '';
     const instruction = actionCount === 0
-        ? 'No pending decisions or active tasks — continue with ziggs_inbox for scope news.'
+        ? backlog
+            ? `No pending decisions or active tasks IN THIS WINDOW.${behindNote}`
+            : 'No pending decisions or active tasks — continue with ziggs_inbox for scope news.'
         : withSessionCard
-            ? `Paste sessionChatCard at the top of your reply. Decisions: wait for explicit approve/reject before ziggs_agreement_respond.${humanOnlyNote} Tasks: when the human says work on <taskId>, read context and implement.`
-            : `Counts only here — ${SESSION_CARD_POINTER} Decisions: wait for explicit approve/reject before ziggs_agreement_respond.${humanOnlyNote}`;
+            ? `Paste sessionChatCard at the top of your reply. Decisions: wait for explicit approve/reject before ziggs_agreement_respond.${humanOnlyNote} Tasks: when the human says work on <taskId>, read context and implement.${behindNote}`
+            : `Counts only here — ${SESSION_CARD_POINTER} Decisions: wait for explicit approve/reject before ziggs_agreement_respond.${humanOnlyNote}${behindNote}`;
     return {
         pendingCount,
         hasPending: pendingCount > 0,

package/dist/tools.js

@@ -13,12 +13,14 @@ import { toolError } from './toolError.js';
 import { registerCapability, registerCapabilities, textResult, } from './capabilityAdapter.js';
 // Shared protocol paragraphs live on connect `instructions` only.
 // This description is the tool's own fields and next calls — not PROTOCOL.*.
-const ZIGGS_INBOX_DESCRIPTION = "Where you stand, in one call. What's addressed to you since your last ack — references only, never content: `deliveries` (newest first) with a per-chat `chats` fold, plus assigned open tasks and agreement proposals awaiting your response. " +
+const ZIGGS_INBOX_DESCRIPTION = "Where you stand, in one call. What's addressed to you since your last ack — references only, never content: `deliveries` (OLDEST first — this is a drain window, not a view of the newest mail; see `backlog` for how far it is from the present) with a per-chat `chats` fold, plus assigned open tasks and agreement proposals awaiting your response. " +
     'Open the conversations behind the references with ziggs_context_read (type=messages, via=chat:<chatId>). ' +
     'A cold call (no waitSeconds) is the session-start read: it also carries `session` (who you are acting as, in which org, against which backend), the structured `decisions` and `activeWork` awaiting an answer, and the `sessionChatCard` to paste for the human. Do NOT call ziggs_agreement_respond until they explicitly approve or reject. ' +
     'A long-poll call (waitSeconds) is the working loop and returns news only — the session block is a session-start cost, not a per-poll one. ' +
-    'A `readPlan` array gives the exact next calls (tool + pre-filled args) for the news in this response — run them verbatim to read each chat and ack; when the plan overflows or deliveries are capped, `readPlanTruncated` counts dropped reads and the ack step is omitted so a partial plan cannot bury other mail. ' +
-    'readPlan reads come pre-pinned with the covering contextGrantId when you hold one, so no separate ziggs_grant_list call is needed.';
+    'A `readPlan` array gives the exact next calls (tool + pre-filled args) for the news in this response — run them verbatim to read each chat and ack. Your own rows are planned first; `readPlanTruncated` counts reads the plan could not fit, and the ack step is omitted only when one of YOUR OWN reads was dropped, since that is the one case where acking would bury your work. ' +
+    'readPlan reads come pre-pinned with the covering contextGrantId when you hold one, so no separate ziggs_grant_list call is needed. ' +
+    '`outOfReach` lists rows you hold nothing to open: they are not yours to handle and not planned as reads, and each carries the one line saying what would put it in reach — tell your human rather than retrying the read. ' +
+    '`backlog` is present when this window stops short of the present: it says how many deliveries are unread past it and when the newest arrived. Never answer "nothing pending" while it is there — say how far back you are looking, and ack to reach the rest.';
 // The requirement is one grant, and saying so is the whole point: this used to
 // promise a cross-org reach test on every send (propose a link, or fail with
 // AGENT_NOT_PUBLISHED), which no longer exists. Reach is decided once, when

package/package.json

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