@ziggs-ai/ziggs-mcp 0.1.31 → 0.1.33

package/README.md

@@ -206,7 +206,7 @@ OP_KEY_A=... AGENT_A=... USER_B=... OP_KEY_B=... AGENT_B=... \
 | `ziggs_revoke_link` | `DELETE /agreements/:agreementId` (see also `ziggs_revoke_agreement`) |
 | `ziggs_revoke_agreement` | `DELETE /agreements/:id` — any agreement (hire/service/quest/link) |
 | `ziggs_smoke_impersonation` | [Internal/debug] connectivity check — only when `ZIGGS_MCP_DEBUG=1`; not part of normal delegate workflow |
-| `ziggs_get_scope` | `GET /scope?via=` |
+| `ziggs_context_snapshot` | `GET /context/snapshot?via=chat:` — one-shot chat orientation (history + agreements + roster), grant-fenced |
 | `ziggs_list_my_agreements` | `GET /agreements?scope=mine` |
 | `ziggs_get_agreement` | `GET /agreements/:id` |
 | `ziggs_list_chats` | `GET /chats/mine` |

package/dist/toolError.js

@@ -13,7 +13,7 @@ const HTTP_STATUS = /(?:^|\s)([1-5]\d{2})(?=\s|$)/;
 const SCOPE_DENIED_HINT = 'You are not authorized for this scope. To get access: ask the counterparty ' +
     'to issue you a context grant (they run ziggs_issue_grant), or request a ' +
     'bilateral link first (ziggs_request_link). Check what you can already ' +
-    'reach with ziggs_discover_context / ziggs_get_scope.';
+    'reach with ziggs_discover_context / ziggs_context_snapshot.';
 function codeForStatus(status) {
     if (status === 401)
         return 'NOT_AUTHENTICATED';

package/dist/tools.js

@@ -1,11 +1,20 @@
 import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
-import { getAgreement, getMyAgreements, listMyChats, openConversation, proposeDirectTo, proposeBroadcast, publishOffer, respondToAgreement, revokeAgreement, ScopeClient, sendChatMessage, ContextDiscoveryClient, ContextReadClient, InboxClient, createTask, updateTaskState, replaceTaskPlan, listTasks, getBackendUrl, } from '@ziggs-ai/api-client';
+import { getAgreement, getMyAgreements, listMyChats, openConversation, proposeDirectTo, proposeBroadcast, publishOffer, claimOffer, provisionRelayWorkers, respondToAgreement, revokeAgreement, 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, buildReadContextReadPlan, } from './inboxToolResult.js';
 import { filterTasksForDelegate, formatPendingDecisionsPayload, resolveWebAppOrigin, buildPendingNextActions, } from './pendingDecisions.js';
 import { PROTOCOL } from './protocol/delegateProtocol.js';
+const RELAY_COORDINATOR_AGENT_ID = 'relay-coordinator';
+function buildRelayCoordinatorTaskBody(opts) {
+    const title = opts.title?.trim() || 'Relay coordinator job';
+    return {
+        agreementId: opts.hireAgreementId,
+        assigneeId: RELAY_COORDINATOR_AGENT_ID,
+        description: `${title}\nrelay:v1\n${JSON.stringify(opts.payload)}`,
+    };
+}
 import { READ_ONLY, WRITE, DESTRUCTIVE } from './toolAnnotations.js';
 import { toolError } from './toolError.js';
 // ZIG-557: the protocol sentences (loop / ack / humanAttention) are sourced
@@ -50,7 +59,6 @@ function textResult(data) {
         content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
     };
 }
-const scopeKindSchema = z.enum(['chat', 'agreement', 'task', 'counterparty']);
 const contextReadTypeSchema = z.enum([
     'messages',
     'artifacts',
@@ -444,21 +452,21 @@ export function registerZiggsTools(server, creds, cfg) {
         }
     });
     if (cfg.debugTools) {
-        server.tool('ziggs_smoke_impersonation', '[Internal/debug] Connectivity check for the operator-key impersonation path — lists agreements and resolves scope from the first chat. Not part of normal delegate workflow; use ziggs_list_my_agreements / ziggs_get_scope instead.', {}, READ_ONLY, async () => {
+        server.tool('ziggs_smoke_impersonation', '[Internal/debug] Connectivity check for the operator-key impersonation path — lists agreements and snapshots the first chat. Not part of normal delegate workflow; use ziggs_list_my_agreements / ziggs_context_snapshot instead.', {}, READ_ONLY, async () => {
             try {
                 const agreements = await getMyAgreements({}, creds);
                 const chats = await listMyChats(creds);
-                let scope = null;
+                let snapshot = null;
                 const firstChatId = chats[0]?.chatId;
                 if (firstChatId) {
-                    const client = new ScopeClient(creds.operatorKey, creds.agentId);
-                    scope = await client.get('chat', firstChatId);
+                    const client = new ContextReadClient(creds.operatorKey, creds.agentId);
+                    snapshot = await client.snapshot(firstChatId, { maxMessages: 5 });
                 }
                 return textResult({
                     ok: true,
                     agreementsCount: agreements.length,
                     chatsCount: chats.length,
-                    scope,
+                    snapshot,
                 });
             }
             catch (e) {
@@ -466,13 +474,20 @@ export function registerZiggsTools(server, creds, cfg) {
             }
         });
     }
-    server.tool('ziggs_get_scope', 'Resolve the access graph for the delegate agent from a chat, agreement, task, or counterparty entry point.', {
-        scopeKind: scopeKindSchema.describe('Entry kind'),
-        scopeId: z.string().describe('Entry id'),
-    }, READ_ONLY, async ({ scopeKind, scopeId }) => {
+    server.tool('ziggs_context_snapshot', 'One-shot orientation for a chat: history, agreements (with which party is you), and the roster of agents/users — grant-fenced. Use when entering a chat you have not read yet; follow up with ziggs_read_context forward deltas from the returned latestSequence.', {
+        chatId: z.string().describe('Chat id to snapshot'),
+        maxMessages: z.number().optional().describe('Optional message history cap'),
+        contextGrantId: z
+            .string()
+            .optional()
+            .describe('Optional grant id when reading under a context grant'),
+    }, READ_ONLY, async ({ chatId, maxMessages, contextGrantId }) => {
         try {
-            const client = new ScopeClient(creds.operatorKey, creds.agentId);
-            const result = await client.get(scopeKind, scopeId);
+            const client = new ContextReadClient(creds.operatorKey, creds.agentId);
+            const result = await client.snapshot(chatId, {
+                maxMessages,
+                contextGrantId,
+            });
             return textResult(result);
         }
         catch (e) {
@@ -637,6 +652,70 @@ export function registerZiggsTools(server, creds, cfg) {
             return toolError(e.message);
         }
     });
+    server.tool('ziggs_claim_offer', 'Claim a published standing offer (POST /marketplace/offers/claim). Use for relay worker provisioning when the worker has a marketplace offer — no worker-side approval needed.', {
+        agreementId: z.string().describe('Open offer agreementId to claim'),
+    }, WRITE, async ({ agreementId }) => {
+        try {
+            const offer = await claimOffer(agreementId, creds);
+            return textResult({ offer });
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+    server.tool('ziggs_provision_relay_workers', 'Initiator path: provision per-step worker agreements before relay kickoff. Reuses active delegations under the hire, claims standing offers when available, otherwise proposes delegations (worker must approve — never impersonated). Returns relay:v1 payload and POST /tasks body when all steps are active.', {
+        hireAgreementId: z.string(),
+        chatId: z
+            .string()
+            .optional()
+            .describe('Required when a step has no standing offer and needs delegation under the hire'),
+        inputArtifactIds: z.array(z.string()).optional(),
+        steps: z.array(z.object({
+            stepId: z.string(),
+            order: z.number(),
+            assigneeId: z.string(),
+            description: z.string(),
+            offerAgreementId: z
+                .string()
+                .optional()
+                .describe('Explicit open offer to claim for this worker'),
+        })),
+        kickoff: z
+            .boolean()
+            .optional()
+            .describe('When true and readyForKickoff, also POST /tasks on the hire for relay-coordinator'),
+    }, WRITE, async ({ hireAgreementId, chatId, inputArtifactIds, steps, kickoff }) => {
+        try {
+            const result = await provisionRelayWorkers({
+                creds,
+                hireAgreementId,
+                chatId,
+                inputArtifactIds,
+                steps,
+            });
+            const relayTaskBody = buildRelayCoordinatorTaskBody({
+                hireAgreementId,
+                payload: result.payload,
+            });
+            let task;
+            if (kickoff && result.readyForKickoff) {
+                task = await createTask(relayTaskBody, creds);
+            }
+            return textResult({
+                ...result,
+                relayTaskBody,
+                task,
+                nextSteps: result.readyForKickoff
+                    ? kickoff && task
+                        ? 'Relay coordinator task created — watch Execution for step progress.'
+                        : 'All worker agreements active — POST relayTaskBody via createTask or set kickoff=true.'
+                    : `Worker approval pending on: ${result.pendingApprovals.join(', ')}. Call ziggs_respond_to_agreement after workers approve, then re-run with kickoff=true.`,
+            });
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
     server.tool('ziggs_respond_to_agreement', 'Approve or reject a pending agreement. Uses PUT /approvals/:partyId or POST /claim for an open broadcast (public or org-scoped; org-scoped quests are claimable only by members of the agreement\'s org).', {
         agreementId: z.string(),
         action: z.enum(['approve', 'reject']),

package/package.json

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

package/skills/ziggs/SKILL.md

@@ -100,7 +100,7 @@ When coordinating with another org’s delegate:
 
 ## Boarding checklist (cold session)
 
-1. Confirm MCP tools are available (e.g. `ziggs_list_chats` or `ziggs_get_scope`).
+1. Confirm MCP tools are available (e.g. `ziggs_list_chats` or `ziggs_context_snapshot`).
 2. Run **`ziggs_inbox`** — empty inbox is fine.
 3. Ask the human what they want to do on Ziggs before issuing grants or opening new agreements.