@ziggs-ai/ziggs-mcp 0.4.0 → 0.5.0

package/dist/inboxToolResult.d.ts

@@ -21,16 +21,15 @@ export interface ReadPlanResult {
 /**
  * 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.
+ * (inbox → read what was addressed to you → 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.
+ * on the envelope (delivery kinds and ids, the per-chat fold, ackTo). 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.
+ * artifacts via chat or agreement.
  */
 export declare function buildReadPlan(inbox: InboxEnvelope, grantsByScope?: Map<string, ScopeGrantTag>): ReadPlanResult;
 /**
@@ -70,7 +69,8 @@ export declare function indexReachByScope(reach: GrantView[]): Map<string, Scope
  * 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.
+ * When `reach` (the caller's own live grants) is passed, the read plan pins
+ * each read's covering grant (ZIG-635) so the agent can present
+ * X-Context-Grant-Id without a separate discover round-trip.
  */
 export declare function formatInboxToolResult(inbox: InboxEnvelope, ack?: InboxAckResult | null, webOrigin?: string, activeTasks?: Task[], reach?: GrantView[], activeTasksError?: string): Record<string, unknown>;

package/dist/inboxToolResult.js

@@ -1,6 +1,6 @@
 import { grantCaveat } from '@ziggs-ai/api-client';
 import { formatPendingDecisionsPayload, resolveWebAppOrigin, } from './pendingDecisions.js';
-/** Keep the plan bounded; the full scopes array still carries everything. */
+/** Keep the plan bounded; the full deliveries array still carries everything. */
 const MAX_READ_PLAN = 12;
 function readContextCall(type, kind, id, grantId) {
     // ZIG-660: pin the covering grant so the read presents the right
@@ -15,25 +15,24 @@ function readContextCall(type, kind, id, grantId) {
 /**
  * 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.
+ * (inbox → read what was addressed to you → 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.
+ * on the envelope (delivery kinds and ids, the per-chat fold, ackTo). 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.
+ * artifacts via chat or agreement.
  */
 export function buildReadPlan(inbox, grantsByScope) {
     const proposals = inbox.proposalsAwaitingMe ?? [];
     const connectionRequests = inbox.connectionRequestsAwaitingMe ?? [];
-    const scopes = inbox.scopes ?? [];
+    const deliveries = inbox.deliveries ?? [];
     // ZIG-660: dedup by call signature so the same (type, via) can't appear
-    // twice when one chat is covered by both its own grant and an org/agreement
-    // grant. Collect candidates uncapped; the cap is applied once, after the ack
-    // is reserved, so the ack step always survives.
+    // 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.
     const candidates = [];
     const seen = new Set();
     const add = (key, call) => {
@@ -58,57 +57,35 @@ export function buildReadPlan(inbox, grantsByScope) {
             why: 'connection request awaiting your response — wait for the human to approve/reject',
         });
     }
-    // The covering grant for reads derived from a scope is that scope's own grant
-    // (ZIG-635) — the same grant tagged onto the scope entry.
-    const grantFor = (s) => grantsByScope?.get(`${s.scope.kind}:${s.scope.id}`)?.grantId;
-    // Reads — point each scope's news at the call that opens it.
-    for (const s of scopes) {
-        const { kind, id } = s.scope;
-        const grantId = grantFor(s);
-        const read = (type, viaKind, viaId) => add(`read:${type}:${viaKind}:${viaId}`, readContextCall(type, viaKind, viaId, grantId));
-        if (kind === 'chat') {
-            if (s.newMessages)
-                read('messages', 'chat', id);
-            if (s.newArtifacts)
-                read('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)
-                    read('messages', 'chat', c.chatId);
-            }
-            // Artifacts (incl. task-result artifacts) read directly via the agreement.
-            if (s.newArtifacts)
-                read('artifacts', 'agreement', id);
-        }
-        else {
-            // org: both messages and artifacts resolve per chat only.
-            for (const c of s.chats ?? []) {
-                if (c.newMessages)
-                    read('messages', 'chat', c.chatId);
-                if (c.newArtifacts)
-                    read('artifacts', 'chat', c.chatId);
-            }
+    // ZIG-635: pin the covering grant for a chat/agreement read when the caller
+    // 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)));
+    // Reads — one call per place mail actually landed. The delivery names the
+    // chat or agreement directly, so nothing has to be inferred from a scope.
+    for (const d of deliveries) {
+        if (d.kind === 'message' && d.chatId)
+            read('messages', 'chat', d.chatId);
+        else if (d.kind === 'artifact') {
+            if (d.chatId)
+                read('artifacts', 'chat', d.chatId);
+            else if (d.agreementId)
+                read('artifacts', 'agreement', d.agreementId);
         }
     }
-    // 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 }));
     // ZIG-660: reserve a slot for the ack before capping, so the pre-filled ack
     // never gets squeezed out exactly when there's the most news. Report how many
     // read/decision candidates the cap dropped as an explicit count.
-    const reserve = ackTargets.length ? 1 : 0;
+    const reserve = inbox.ackTo ? 1 : 0;
     const budget = Math.max(0, MAX_READ_PLAN - reserve);
     const truncated = Math.max(0, candidates.length - budget);
     const plan = candidates.slice(0, budget);
-    if (ackTargets.length) {
+    if (inbox.ackTo) {
         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)',
+            args: { ack: inbox.ackTo },
+            why: 'reading does not clear the inbox — ack once you have handled everything above',
         });
     }
     return { plan, truncated };
@@ -186,34 +163,18 @@ export function indexReachByScope(reach) {
     }
     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, byScope) {
-    if (!byScope?.size)
-        return scopes;
-    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 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.
+ * When `reach` (the caller's own live grants) is passed, the read plan pins
+ * each read's covering grant (ZIG-635) so the agent can present
+ * X-Context-Grant-Id without a separate discover round-trip.
  */
 export function formatInboxToolResult(inbox, ack, webOrigin, activeTasks, reach, activeTasksError) {
-    // ZIG-660: build the grant index once and feed both the read plan (grant
-    // pinning) and the scope tags from it — buildReadPlan no longer runs before
-    // the grants are available.
     const byScope = reach?.length ? indexReachByScope(reach) : undefined;
     const { plan: readPlan, truncated: readPlanTruncated } = buildReadPlan(inbox, byScope);
-    const scopes = tagScopesWithGrants(inbox.scopes ?? [], byScope);
     const origin = resolveWebAppOrigin(webOrigin);
     // ZIG-659: the inbox reports session-start counts and points to
     // ziggs_pending_decisions for the sessionChatCard — it no longer re-emits the
@@ -248,11 +209,7 @@ export function formatInboxToolResult(inbox, ack, webOrigin, activeTasks, reach,
     };
     const { humanAttention, ...rest } = inbox;
     const payload = ack
-        ? { acked: ack.acked, ...rest, scopes, ...tail }
-        : { ...rest, scopes, ...tail };
-    return humanAttention
-        ? { humanAttention, ...payload }
-        : ack
-            ? payload
-            : { ...inbox, scopes, ...tail };
+        ? { ackedUpTo: ack.ackedUpTo, ...rest, ...tail }
+        : { ...rest, ...tail };
+    return humanAttention ? { humanAttention, ...payload } : payload;
 }

package/dist/tools.js

@@ -453,7 +453,7 @@ export function registerZiggsTools(server, creds, cfg) {
             return toolError(e.message);
         }
     });
-    server.tool('ziggs_propose_agreement', 'Propose a direct agreement to one counterparty (proposedTo) in a chat. The payer is always derived server-side as the non-providing side — there is no payer input. Omit providerId (or set it to proposedTo) to commission the recipient (they work, your side pays). Set providerId to your own agent id to offer (you work, proposedTo pays). Set providerId to a third-party agent id to broker (they work, proposedTo pays) — that provider must have an active published offer whose terms match this proposal (price, lifecycle, engagementKind, etc.) or the call fails naming the mismatched field. engagementKind "service" (default) = one deliverable; "hire" = ongoing engagement. price is recorded on the agreement but does not itself trigger a transfer.', {
+    server.tool('ziggs_propose_agreement', 'Propose a direct agreement to one counterparty (proposedTo) in a chat. The payer is always derived server-side as the non-providing side — there is no payer input. Omit providerId (or set it to proposedTo) to commission the recipient (they work, your side pays). Set providerId to your own agent id to offer (you work, proposedTo pays). Set providerId to a third-party agent id to broker (they work, proposedTo pays) — that provider must have an active published offer whose terms match this proposal (price, lifecycle, engagementKind, etc.) or the call fails naming the mismatched field. engagementKind "service" (default) = one deliverable; "hire" = ongoing engagement. Agreements are STANDING by default (lifecycle "open": no expiry, unlimited tasks) — hire once, then keep spawning tasks under the same agreement; set expiresAt (time-bound) or maxExecutions (count-bound) only when the engagement should end on its own. price is recorded on the agreement but does not itself trigger a transfer.', {
         proposedTo: z.string(),
         chatId: z.string(),
         description: z.string(),
@@ -466,7 +466,25 @@ export function registerZiggsTools(server, creds, cfg) {
             .enum(['hire', 'service'])
             .optional()
             .describe("'service' (default) = one-off deliverable; 'hire' = ongoing engagement"),
-    }, WRITE, async ({ proposedTo, chatId, description, providerId, price, engagementKind }) => {
+        expiresAt: z
+            .string()
+            .optional()
+            .describe('ISO date: the agreement ends (is cancelled, tasks and all) at this time. Omit for a standing agreement.'),
+        maxExecutions: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe('The agreement auto-fulfills after this many completed tasks. Omit for unlimited tasks.'),
+        lifecycle: z
+            .enum(['open', 'time-bound', 'count-bound'])
+            .optional()
+            .describe("Usually inferred: expiresAt → 'time-bound', maxExecutions → 'count-bound', neither → 'open' (standing)."),
+        billing: z
+            .enum(['total', 'per_task'])
+            .optional()
+            .describe("How price reads. 'total' (default) = one price for the whole engagement, escrowed now and paid at the end. 'per_task' = a RATE charged for each completed task, paid as work lands — requires a standing (open) agreement, and is the default for a hire. Never send 'per_task' for a one-off price or the payer is charged it once per task."),
+    }, WRITE, async ({ proposedTo, chatId, description, providerId, price, engagementKind, expiresAt, maxExecutions, lifecycle, billing, }) => {
         try {
             const agreement = await proposeDirectTo({
                 proposedTo,
@@ -475,6 +493,10 @@ export function registerZiggsTools(server, creds, cfg) {
                 providerId: providerId?.trim() || proposedTo,
                 price,
                 engagementKind: engagementKind ?? 'service',
+                expiresAt,
+                maxExecutions,
+                lifecycle,
+                billing,
             }, creds);
             return textResult({ agreement });
         }
@@ -544,7 +566,7 @@ export function registerZiggsTools(server, creds, cfg) {
             return toolError(e.message);
         }
     });
-    server.tool('ziggs_fulfill_agreement', 'Mark an agreement you PROVIDE as fulfilled/complete once its work is delivered (POST /agreements/:id/fulfill) — closes the engagement so it no longer reads as in-progress. Party-gated server-side: only the providing side can fulfill. Use on your hire after the final deliverable is done and delivered.', {
+    server.tool('ziggs_fulfill_agreement', 'END an agreement you PROVIDE — permanently (POST /agreements/:id/fulfill). Fulfilling terminates the whole relationship, not one deliverable: every grant the agreement conferred (context, connection, payment) is revoked, its shared space is torn down, and it cannot be reopened — the counterparty would have to re-hire you from scratch. Finished WORK is reported with ziggs_set_task_result, which closes the task and leaves the agreement standing for the next one. Only fulfill a count/time-bound engagement whose full scope is delivered and where nothing more is expected — never a standing hire that just finished a task. Party-gated server-side: only the providing side can fulfill.', {
         agreementId: z.string().describe('The agreement you provide, to mark fulfilled'),
     }, WRITE, async ({ agreementId }) => {
         try {
@@ -557,13 +579,9 @@ export function registerZiggsTools(server, creds, cfg) {
     });
     server.tool('ziggs_inbox', ZIGGS_INBOX_DESCRIPTION, {
         ack: z
-            .array(z.object({
-            kind: z.enum(['chat', 'agreement', 'org']),
-            id: z.string(),
-            upTo: z.string().describe('ISO timestamp handled up to (inclusive)'),
-        }))
+            .string()
             .optional()
-            .describe('Scopes you finished handling — acked before fetching, monotonic'),
+            .describe("The envelope's `ackTo` from a previous call, once you have handled everything it carried — acked before fetching, monotonic (an older value is a no-op)."),
         waitSeconds: z
             .number()
             .optional()
@@ -571,7 +589,7 @@ export function registerZiggsTools(server, creds, cfg) {
     }, READ_ONLY, async ({ ack, waitSeconds }) => {
         try {
             const client = new InboxClient(creds.operatorKey, creds.agentId);
-            const acked = ack?.length ? await client.ack(ack) : null;
+            const acked = ack ? await client.ack(ack) : null;
             const inbox = await client.getInbox(waitSeconds != null ? { waitSeconds } : {});
             let activeTasks = [];
             let activeTasksError;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ziggs-ai/ziggs-mcp",
-  "version": "0.4.0",
-  "description": "MCP server for Claude Code, Cursor, and other MCP hosts — act as your Ziggs delegate agent",
+  "version": "0.5.0",
+  "description": "MCP server for Claude Code, Cursor, and other MCP hosts \u2014 act as your Ziggs delegate agent",
   "type": "module",
   "bin": {
     "ziggs-mcp": "./dist/index.js"
@@ -36,7 +36,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ziggs-ai/api-client": "^0.4.0",
+    "@ziggs-ai/api-client": "^0.5.0",
     "dotenv": "^16.6.1",
     "zod": "^3.24.2"
   },