@ziggs-ai/ziggs-mcp 0.1.19 → 0.1.22

package/dist/inboxToolResult.d.ts

@@ -1,18 +1,67 @@
-import type { InboxAckResult, InboxEnvelope, Task } from '@ziggs-ai/api-client';
+import type { ContextReachDescriptor, ContextReadType, InboxAckResult, InboxEnvelope, Task } from '@ziggs-ai/api-client';
 /**
- * ZIG-558 (A3): each inbox call points at the next call. Synthesized purely
- * from fields already on the envelope — no new endpoint, no new tool — so the
- * agent doesn't have to remember the inbox → read → act → ack loop from the
- * upfront prompt. Thin protocol up front, heavy guidance in the response.
+ * ZIG-634 (Step 1): a pre-filled next call. The agent can run it verbatim
+ * instead of assembling args from the ids scattered through the response.
+ * `tool` + `args` mirror the MCP tool signature; `why` is a one-line reason.
+ */
+export interface ReadPlanCall {
+    tool: string;
+    args: Record<string, unknown>;
+    why: string;
+}
+/**
+ * ZIG-634: replace the free-text `nextActions` hints with typed `readPlan`
+ * call objects — tool name + pre-filled args — so the most common loop
+ * (inbox → read each chat with news → ack) needs no guesswork.
+ *
+ * Safe by construction: every entry is synthesized purely from fields already
+ * on the envelope (scope kinds, ids, per-chat counts, latestAt). No new data
+ * is read and no new permission check runs — this is the same information the
+ * caller already received, restated as runnable calls.
+ *
+ * Mapping honours how reads resolve server-side: messages read only via chat,
+ * artifacts via chat or agreement. For multi-chat scopes (org / agreement) we
+ * use the per-chat breakdown (ZIG-543) to name the chatIds.
+ */
+export declare function buildReadPlan(inbox: InboxEnvelope): ReadPlanCall[];
+/**
+ * ZIG-634: forward-continuation for a read_context page. Built only from fields
+ * already on the page (via, hasMore/nextCursor, latestSequence) plus the grant
+ * id the caller presented — echoed back, never discovered. Nothing new is read.
  *
- * Mapping honours how reads actually resolve server-side: messages read only
- * via chat, artifacts via chat or agreement. For multi-chat scopes (org /
- * agreement) we use the per-chat breakdown (ZIG-543) to name the chatIds.
+ * - When the page has more rows in this window: a cursor call for the next page.
+ * - When the page reports a high-water sequence: a forward-delta call that
+ *   returns only items created after this page (after = latestSequence).
  */
-export declare function buildNextActions(inbox: InboxEnvelope): string[];
+export declare function buildReadContextReadPlan(page: {
+    hasMore?: boolean;
+    nextCursor?: string | null;
+    latestSequence?: string | null;
+}, type: ContextReadType, via: string, presentedGrantId?: string): ReadPlanCall[];
+/**
+ * ZIG-635 (Step 2): the covering grant attached to a scope so the agent can
+ * pin the right X-Context-Grant-Id without a separate discover_context call.
+ * Grant metadata only — never a resource-derived field.
+ */
+export interface ScopeGrantTag {
+    grantId: string;
+    temporal: 'from-now' | 'from-start';
+    watermarkAt: string;
+    expiresAt: string | null;
+    parentGrantId: string | null;
+}
+/**
+ * ZIG-635: index the caller's own live reach descriptors by scope. The reach
+ * list is already the caller's non-expired grants (holderId == principalId),
+ * so this is grant metadata the caller already holds — no protected content.
+ */
+export declare function indexReachByScope(reach: ContextReachDescriptor[]): Map<string, ScopeGrantTag>;
 /**
  * Put humanAttention first so MCP hosts surface it before counts (ZIG-482),
- * and append nextActions last so each inbox call self-narrates the follow-up
- * call (ZIG-558) without disturbing the leading humanAttention key.
+ * and append readPlan last so each inbox call self-narrates the follow-up
+ * calls (ZIG-634) without disturbing the leading humanAttention key.
+ *
+ * When `reach` (the caller's own live grants) is passed, each scope is tagged
+ * with its covering grant (ZIG-635) so the agent can pin X-Context-Grant-Id.
  */
-export declare function formatInboxToolResult(inbox: InboxEnvelope, ack?: InboxAckResult | null, webOrigin?: string, activeTasks?: Task[]): Record<string, unknown>;
+export declare function formatInboxToolResult(inbox: InboxEnvelope, ack?: InboxAckResult | null, webOrigin?: string, activeTasks?: Task[], reach?: ContextReachDescriptor[]): Record<string, unknown>;

package/dist/inboxToolResult.js

@@ -1,77 +1,194 @@
 import { formatPendingDecisionsPayload, resolveWebAppOrigin, } from './pendingDecisions.js';
-/** Keep the hint list bounded; the full scopes array still carries everything. */
-const MAX_NEXT_ACTIONS = 12;
-function readHint(type, kind, id) {
-    return `ziggs_read_context type=${type} via=${kind}:${id}`;
+/** Keep the plan bounded; the full scopes array still carries everything. */
+const MAX_READ_PLAN = 12;
+function readContextCall(type, kind, id) {
+    return {
+        tool: 'ziggs_read_context',
+        args: { type, via: `${kind}:${id}` },
+        why: `open the ${type} behind the count on ${kind}:${id}`,
+    };
 }
 /**
- * ZIG-558 (A3): each inbox call points at the next call. Synthesized purely
- * from fields already on the envelope — no new endpoint, no new tool — so the
- * agent doesn't have to remember the inbox → read → act → ack loop from the
- * upfront prompt. Thin protocol up front, heavy guidance in the response.
+ * ZIG-634: replace the free-text `nextActions` hints with typed `readPlan`
+ * call objects — tool name + pre-filled args — so the most common loop
+ * (inbox → read each chat with news → ack) needs no guesswork.
  *
- * Mapping honours how reads actually resolve server-side: messages read only
- * via chat, artifacts via chat or agreement. For multi-chat scopes (org /
- * agreement) we use the per-chat breakdown (ZIG-543) to name the chatIds.
+ * Safe by construction: every entry is synthesized purely from fields already
+ * on the envelope (scope kinds, ids, per-chat counts, latestAt). No new data
+ * is read and no new permission check runs — this is the same information the
+ * caller already received, restated as runnable calls.
+ *
+ * Mapping honours how reads resolve server-side: messages read only via chat,
+ * artifacts via chat or agreement. For multi-chat scopes (org / agreement) we
+ * use the per-chat breakdown (ZIG-543) to name the chatIds.
  */
-export function buildNextActions(inbox) {
-    const actions = [];
+export function buildReadPlan(inbox) {
+    const plan = [];
     const proposals = inbox.proposalsAwaitingMe ?? [];
     const connectionRequests = inbox.connectionRequestsAwaitingMe ?? [];
     const scopes = inbox.scopes ?? [];
     // Decisions first — these also drive humanAttention (pull-only: no push).
-    if (proposals.length) {
-        const ids = proposals.map((p) => p.agreementId).join(', ');
-        actions.push(`Respond to ${proposals.length} agreement proposal(s) with ziggs_respond_to_agreement (${ids})`);
+    // The decision (approve/reject) is the human's; we only pre-fill the target.
+    for (const p of proposals) {
+        if (plan.length >= MAX_READ_PLAN)
+            break;
+        plan.push({
+            tool: 'ziggs_respond_to_agreement',
+            args: { agreementId: p.agreementId },
+            why: 'agreement proposal awaiting your response — wait for the human to approve/reject',
+        });
     }
-    if (connectionRequests.length) {
-        const ids = connectionRequests.map((c) => c.requestId).join(', ');
-        actions.push(`Respond to ${connectionRequests.length} connection request(s) with ziggs_respond_to_agreement (${ids})`);
+    for (const c of connectionRequests) {
+        if (plan.length >= MAX_READ_PLAN)
+            break;
+        plan.push({
+            tool: 'ziggs_respond_to_agreement',
+            args: { agreementId: c.requestId },
+            why: 'connection request awaiting your response — wait for the human to approve/reject',
+        });
     }
     // Reads — point each scope's news at the call that opens it.
     for (const s of scopes) {
-        if (actions.length >= MAX_NEXT_ACTIONS)
+        if (plan.length >= MAX_READ_PLAN)
             break;
         const { kind, id } = s.scope;
         if (kind === 'chat') {
             if (s.newMessages)
-                actions.push(readHint('messages', 'chat', id));
+                plan.push(readContextCall('messages', 'chat', id));
             if (s.newArtifacts)
-                actions.push(readHint('artifacts', 'chat', id));
+                plan.push(readContextCall('artifacts', 'chat', id));
         }
         else if (kind === 'agreement') {
             // Messages resolve only via chat — name the chats from the breakdown.
             for (const c of s.chats ?? []) {
                 if (c.newMessages)
-                    actions.push(readHint('messages', 'chat', c.chatId));
+                    plan.push(readContextCall('messages', 'chat', c.chatId));
             }
             // Artifacts (incl. task-result artifacts) read directly via the agreement.
             if (s.newArtifacts)
-                actions.push(readHint('artifacts', 'agreement', id));
+                plan.push(readContextCall('artifacts', 'agreement', id));
         }
         else {
             // org: both messages and artifacts resolve per chat only.
             for (const c of s.chats ?? []) {
                 if (c.newMessages)
-                    actions.push(readHint('messages', 'chat', c.chatId));
+                    plan.push(readContextCall('messages', 'chat', c.chatId));
                 if (c.newArtifacts)
-                    actions.push(readHint('artifacts', 'chat', c.chatId));
+                    plan.push(readContextCall('artifacts', 'chat', c.chatId));
             }
         }
     }
-    // Close the loop: reading never clears the inbox — ack what you handled.
-    if (scopes.length) {
-        actions.push('After handling a scope, ack it: ziggs_inbox ack=[{ kind, id, upTo: latestAt }]');
+    // Close the loop: reading never clears the inbox — pre-fill the ack call with
+    // each scope's own latestAt (only scopes that actually have a high-water mark).
+    const ackTargets = scopes
+        .filter((s) => s.latestAt)
+        .map((s) => ({ kind: s.scope.kind, id: s.scope.id, upTo: s.latestAt }));
+    if (ackTargets.length && plan.length < MAX_READ_PLAN) {
+        plan.push({
+            tool: 'ziggs_inbox',
+            args: { ack: ackTargets },
+            why: 'reading does not clear the inbox — ack the scopes you handled (drop any you did not)',
+        });
     }
-    return actions.slice(0, MAX_NEXT_ACTIONS);
+    return plan.slice(0, MAX_READ_PLAN);
+}
+/**
+ * ZIG-634: forward-continuation for a read_context page. Built only from fields
+ * already on the page (via, hasMore/nextCursor, latestSequence) plus the grant
+ * id the caller presented — echoed back, never discovered. Nothing new is read.
+ *
+ * - When the page has more rows in this window: a cursor call for the next page.
+ * - When the page reports a high-water sequence: a forward-delta call that
+ *   returns only items created after this page (after = latestSequence).
+ */
+export function buildReadContextReadPlan(page, type, via, presentedGrantId) {
+    const plan = [];
+    // Only echo a grant the caller already presented — never one we discovered.
+    const grant = presentedGrantId ? { contextGrantId: presentedGrantId } : {};
+    if (page.hasMore && page.nextCursor) {
+        plan.push({
+            tool: 'ziggs_read_context',
+            args: { type, via, cursor: page.nextCursor, ...grant },
+            why: 'more rows in this window — next page',
+        });
+    }
+    if (page.latestSequence) {
+        plan.push({
+            tool: 'ziggs_read_context',
+            args: {
+                type,
+                via,
+                direction: 'forward',
+                after: page.latestSequence,
+                ...grant,
+            },
+            why: 'forward-delta — only items created after this page',
+        });
+    }
+    return plan;
+}
+function toScopeGrantTag(d) {
+    return {
+        grantId: d.grantId,
+        temporal: d.temporal,
+        watermarkAt: d.watermarkAt,
+        expiresAt: d.expiresAt,
+        parentGrantId: d.parentGrantId,
+    };
+}
+/**
+ * When several live grants cover the same scope, pick the one the agent should
+ * pin: the broadest history first (from-start over from-now, then the earliest
+ * watermark), so a read against it returns the most the caller is entitled to.
+ */
+function isBroaderGrant(a, b) {
+    if (a.temporal !== b.temporal)
+        return a.temporal === 'from-start';
+    return a.watermarkAt < b.watermarkAt;
+}
+/**
+ * ZIG-635: index the caller's own live reach descriptors by scope. The reach
+ * list is already the caller's non-expired grants (holderId == principalId),
+ * so this is grant metadata the caller already holds — no protected content.
+ */
+export function indexReachByScope(reach) {
+    const byScope = new Map();
+    for (const d of reach) {
+        if (!d?.scope)
+            continue;
+        const key = `${d.scope.kind}:${d.scope.id}`;
+        const tag = toScopeGrantTag(d);
+        const existing = byScope.get(key);
+        if (!existing || isBroaderGrant(tag, existing))
+            byScope.set(key, tag);
+    }
+    return byScope;
+}
+/**
+ * ZIG-635: tag each inbox scope with its covering grant. Scopes with no
+ * matching live grant (e.g. reachable via membership, not a grant) are left
+ * untagged — the agent keeps navigating by id, never a fabricated grant.
+ */
+function tagScopesWithGrants(scopes, reach) {
+    if (!reach?.length)
+        return scopes;
+    const byScope = indexReachByScope(reach);
+    return scopes.map((s) => {
+        const tag = byScope.get(`${s.scope.kind}:${s.scope.id}`);
+        return tag ? { ...s, grant: tag } : s;
+    });
 }
 /**
  * Put humanAttention first so MCP hosts surface it before counts (ZIG-482),
- * and append nextActions last so each inbox call self-narrates the follow-up
- * call (ZIG-558) without disturbing the leading humanAttention key.
+ * and append readPlan last so each inbox call self-narrates the follow-up
+ * calls (ZIG-634) without disturbing the leading humanAttention key.
+ *
+ * When `reach` (the caller's own live grants) is passed, each scope is tagged
+ * with its covering grant (ZIG-635) so the agent can pin X-Context-Grant-Id.
  */
-export function formatInboxToolResult(inbox, ack, webOrigin, activeTasks) {
-    const nextActions = buildNextActions(inbox);
+export function formatInboxToolResult(inbox, ack, webOrigin, activeTasks, reach) {
+    const readPlan = buildReadPlan(inbox);
+    const scopes = tagScopesWithGrants(inbox.scopes ?? [], reach);
     const origin = resolveWebAppOrigin(webOrigin);
     const pending = formatPendingDecisionsPayload(inbox, origin, { activeTasks });
     const pendingTail = pending.hasActionable === true
@@ -84,14 +201,14 @@ export function formatInboxToolResult(inbox, ack, webOrigin, activeTasks) {
             ...(pending.workChatCard ? { workChatCard: pending.workChatCard } : {}),
         }
         : {};
-    const tail = { ...pendingTail, ...(nextActions.length ? { nextActions } : {}) };
+    const tail = { ...pendingTail, ...(readPlan.length ? { readPlan } : {}) };
     const { humanAttention, ...rest } = inbox;
     const payload = ack
-        ? { acked: ack.acked, ...rest, ...tail }
-        : { ...rest, ...tail };
+        ? { acked: ack.acked, ...rest, scopes, ...tail }
+        : { ...rest, scopes, ...tail };
     return humanAttention
         ? { humanAttention, ...payload }
         : ack
             ? payload
-            : { ...inbox, ...tail };
+            : { ...inbox, scopes, ...tail };
 }

package/dist/tools.js

@@ -3,7 +3,7 @@ import { z } from 'zod';
 import { getAgreement, getMyAgreements, listMyChats, openConversation, proposeDirectTo, proposeBroadcast, publishOffer, respondToAgreement, ScopeClient, sendChatMessage, ContextDiscoveryClient, ContextReadClient, InboxClient, createTask, updateTaskState, replaceTaskPlan, listTasks, getBackendUrl, } from '@ziggs-ai/api-client';
 import { decodeOperatorKeyClaims } from './operatorKey.js';
 import { registerTrustTools } from './trustTools.js';
-import { formatInboxToolResult } from './inboxToolResult.js';
+import { formatInboxToolResult, buildReadContextReadPlan, } from './inboxToolResult.js';
 import { formatPendingDecisionsPayload, resolveWebAppOrigin, buildPendingNextActions, } from './pendingDecisions.js';
 import { PROTOCOL } from './protocol/delegateProtocol.js';
 import { READ_ONLY, WRITE } from './toolAnnotations.js';
@@ -13,7 +13,9 @@ import { READ_ONLY, WRITE } from './toolAnnotations.js';
 const ZIGGS_INBOX_DESCRIPTION = "What's new since your last ack — references only, never content: scopes with new-message/artifact counts, plus agreement proposals awaiting your response. " +
     'For org/agreement scopes each entry includes a `chats` breakdown (chatId + per-chat counts) so you can open the conversations behind the count — read them with ziggs_read_context (type=messages, via=chat:<chatId>). ' +
     `${PROTOCOL.humanAttention} ${PROTOCOL.pendingDecisions} ` +
-    'When hasActionable the response includes sessionChatCard (decisions + active tasks), decisionChatCard, workChatCard, and nextActions. ' +
+    'When hasActionable the response includes sessionChatCard (decisions + active tasks), decisionChatCard, and workChatCard. ' +
+    'A `readPlan` array gives the exact next calls (tool + pre-filled args) for the news in this response — run them verbatim to read each scope and ack (ZIG-634). ' +
+    'Each scope also carries the covering `grant` (grantId, temporal, watermarkAt, expiresAt) so you can pin the right contextGrantId on the read without a separate discover_context call (ZIG-635). ' +
     `${PROTOCOL.loop} ${PROTOCOL.ack}`;
 const ZIGGS_PENDING_DECISIONS_DESCRIPTION = 'Session start summary: approve/reject decisions AND active tasks assigned to your delegate (ZIG-625). ' +
     'Call at session start in Cursor/Claude — pull-only MCP has no notification tray. ' +
@@ -441,7 +443,16 @@ export function registerZiggsTools(server, creds, cfg) {
             catch {
                 // omit work card when tasks fail
             }
-            return textResult(formatInboxToolResult(inbox, acked, cfg.ZIGGS_WEB_URL, activeTasks));
+            // ZIG-635: tag each scope with the covering grant from the caller's own
+            // live reach descriptors. Best-effort — the inbox still works untagged.
+            let reach = [];
+            try {
+                reach = await new ContextDiscoveryClient(creds.operatorKey, creds.agentId).discover();
+            }
+            catch {
+                // omit grant tags when discovery fails
+            }
+            return textResult(formatInboxToolResult(inbox, acked, cfg.ZIGGS_WEB_URL, activeTasks, reach));
         }
         catch (e) {
             return toolError(e.message);
@@ -457,7 +468,7 @@ export function registerZiggsTools(server, creds, cfg) {
             return toolError(e.message);
         }
     });
-    server.tool('ziggs_read_context', 'Read the contents of a scope you already hold: messages | artifacts | agreements | tasks (the type param), under via=chat:<id>, agreement:<id>, or task:<id>. Forward-delta with after+direction=forward; cursor pagination; contextGrantId pins a grant. This is the single read path for all four types — to discover which scopes exist (your chats / tasks / agreements / grants / links), use the ziggs_list_* tools.', {
+    server.tool('ziggs_read_context', 'Read the contents of a scope you already hold: messages | artifacts | agreements | tasks (the type param), under via=chat:<id>, agreement:<id>, or task:<id>. Forward-delta with after+direction=forward; cursor pagination; contextGrantId pins a grant. The response carries a `readPlan` with the next page and/or forward-delta call pre-filled (after=this page\'s latestSequence), so you can keep reading without rebuilding args (ZIG-634). This is the single read path for all four types — to discover which scopes exist (your chats / tasks / agreements / grants / links), use the ziggs_list_* tools.', {
         type: contextReadTypeSchema.describe('Resource type to read'),
         via: z
             .string()
@@ -489,7 +500,8 @@ export function registerZiggsTools(server, creds, cfg) {
                 state,
                 contextGrantId,
             });
-            return textResult(result);
+            const readPlan = buildReadContextReadPlan(result, type, via, contextGrantId);
+            return textResult(readPlan.length ? { ...result, readPlan } : result);
         }
         catch (e) {
             return toolError(e.message);

package/dist/trustTools.js

@@ -18,8 +18,8 @@ const DEFAULT_WEB_URL = 'https://ziggsai.com';
 /** ZIG-433 — agent search + context grant management through MCP. */
 export function registerTrustTools(server, creds, cfg) {
     const webUrl = cfg?.ZIGGS_WEB_URL?.replace(/\/$/, '') ?? DEFAULT_WEB_URL;
-    server.tool('ziggs_search_agents', 'Find agents (AgentSearchClient). A keyword/natural-language query searches published store agents AND, scoped to authority, your own org-mates and any delegate you have an active link with — so you can find a teammate or another user\'s delegate by name and ziggs_open_conversation with it directly, even if it is unpublished/offline and has never been in a chat with you (ZIG-578). Passing an EXACT agent id resolves that one agent even if unpublished/private — use this for a delegate someone shared an id for, then ziggs_request_link if not yet linked (ZIG-480). Use returned agentId in grant/issue tools — do not guess ids.', {
-        query: z.string().describe('Keyword/natural-language search (published store agents + your org-mates + your linked delegates) OR an exact agent id (resolves that agent even if unpublished)'),
+    server.tool('ziggs_search_agents', 'Find agents (AgentSearchClient). A keyword/natural-language query searches the published store AND, scoped to your authority, your own org-mates and any delegate you have an active link with — so you can find a teammate or another user\'s delegate by name and ziggs_open_conversation with it directly, even if it is unpublished/offline and has never been in a chat with you (ZIG-578). Passing an EXACT agent id resolves that one agent even if unpublished/private — use this for a delegate someone shared an id for, then ziggs_request_link if not yet linked (ZIG-480). Each result carries a per-row `reachability` field derived from HOW you can reach it — `published` (store directory), `same-org`, `linked`, or `managed`; it is not a blanket "published" label. If an exact-id lookup matches an unpublished agent you cannot reach, the row is `reachability: "restricted"` and returns the id only with no name/profile (ZIG-638). Use returned agentId in grant/issue tools — do not guess ids.', {
+        query: z.string().describe('Keyword/natural-language search (published store + your org-mates + your linked delegates) OR an exact agent id (resolves that agent even if unpublished, when you can reach it)'),
         limit: z.number().optional().describe('Max results (default server-side)'),
         minScore: z.number().optional().describe('Minimum match score filter'),
     }, READ_ONLY, async ({ query, limit, minScore }) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/ziggs-mcp",
-  "version": "0.1.19",
+  "version": "0.1.22",
   "description": "MCP server for Claude Code, Cursor, and other MCP hosts — act as your Ziggs delegate agent",
   "type": "module",
   "bin": {