@ziggs-ai/ziggs-mcp 0.1.10 → 0.1.11

package/README.md

@@ -179,6 +179,12 @@ ZIGGS_OPERATOR_KEY_B=... ZIGGS_AGENT_ID_B=... \
 ZIGGS_APPROVER_OPERATOR_KEY=... ZIGGS_APPROVER_USER_ID=... \
 ZIGGS_SMOKE_CHAT_ID=... \
   node scripts/smoke-ziggs-mcp-z433-e2e.mjs
+
+# ZIG-481 / ZIG-520 party handshake (link agreement, prod)
+HTTP_URL=https://api.ziggsai.com \
+OP_KEY_A=... AGENT_A=... USER_B=... OP_KEY_B=... AGENT_B=... \
+  npm run smoke:zig-481-prod
+# Runbook: docs/evals/party-connection-two-claude.md (ZIG-521)
 ```
 
 ---
@@ -197,6 +203,9 @@ ZIGGS_SMOKE_CHAT_ID=... \
 | `ziggs_issue_grant` | Chat admission or `POST /context/grants` |
 | `ziggs_delegate_grant` | `POST /context/grants/:id/delegate` |
 | `ziggs_revoke_grant` | `DELETE /context/grants/:id` |
+| `ziggs_request_link` | `POST /agreements` `{engagementKind:"link"}` (ZIG-481 — a link is just an agreement) |
+| `ziggs_list_links` | `GET /agreements?engagementKind=link` |
+| `ziggs_revoke_link` | `DELETE /agreements/:agreementId` |
 | `ziggs_smoke_impersonation` | Smoke step 1 |
 | `ziggs_get_scope` | `GET /scope?via=` |
 | `ziggs_list_my_agreements` | `GET /agreements?scope=mine` |
@@ -206,7 +215,7 @@ ZIGGS_SMOKE_CHAT_ID=... \
 | `ziggs_list_messages` | `GET /chats/:id/messages` |
 | `ziggs_send_message` | `POST /chats/:id/messages` |
 | `ziggs_propose_agreement` | `POST /agreements/proposals` |
-| `ziggs_respond_to_agreement` | `POST /agreements/:id/respond` |
+| `ziggs_respond_to_agreement` | `PUT /agreements/:id/approvals/:partyId` (owner principal; approves hire, service, and `link` proposals) |
 
 ---
 

package/dist/tools.js

@@ -133,7 +133,7 @@ export function registerZiggsTools(server, creds, cfg) {
             return toolError(e.message);
         }
     });
-    server.tool('ziggs_open_conversation', 'Open or reuse a chat with a user or agent participant.', {
+    server.tool('ziggs_open_conversation', 'Open or reuse a chat with a user or agent participant. To reach an agent in ANOTHER org, an unpublished delegate must establish a link first — call ziggs_request_link (if you have its agent id) or ziggs_create_link_invite (if you do not) and have it approved/claimed — otherwise this fails with AGENT_NOT_PUBLISHED.', {
         participantId: z.string().describe('User or agent id to converse with'),
     }, async ({ participantId }) => {
         try {
@@ -164,7 +164,7 @@ export function registerZiggsTools(server, creds, cfg) {
             return toolError(e.message);
         }
     });
-    server.tool('ziggs_send_message', 'Send a chat message as the delegate agent (requires chat membership).', {
+    server.tool('ziggs_send_message', 'Send a chat message as the delegate agent (requires chat membership). Cross-org first contact requires an ACTIVE link first (ziggs_request_link / ziggs_create_link_invite, then approve/claim); without it, messaging an agent outside your org fails with AGENT_NOT_PUBLISHED.', {
         chatId: z.string(),
         receiverId: z.string().describe('User or agent id receiving the message'),
         text: z.string(),
@@ -217,13 +217,17 @@ export function registerZiggsTools(server, creds, cfg) {
             return toolError(e.message);
         }
     });
-    server.tool('ziggs_respond_to_agreement', 'Approve or reject a pending proposal as the token owner (payer-side delegate).', {
+    server.tool('ziggs_respond_to_agreement', 'Approve or reject a pending agreement (ZIG-524). Uses PUT /approvals/:partyId or POST /claim for open broadcast.', {
         agreementId: z.string(),
         action: z.enum(['approve', 'reject']),
     }, async ({ agreementId, action }) => {
         try {
-            const agreement = await respondToAgreement(agreementId, action, creds);
-            return textResult({ agreement });
+            const claims = decodeOperatorKeyClaims(creds.operatorKey);
+            const ownerId = claims?.ownerId ?? cfg.ZIGGS_OWNER_USER_ID;
+            const updated = await respondToAgreement(agreementId, action, creds, {
+                ownerUserId: ownerId,
+            });
+            return textResult({ agreement: updated });
         }
         catch (e) {
             return toolError(e.message);

package/dist/trustTools.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { AgentSearchClient, ContextGrantsClient, addChatMember, } from '@ziggs-ai/api-client';
+import { AgentSearchClient, ContextGrantsClient, createAgreement, listAgreements, revokeAgreement, claimLink, addChatMember, } from '@ziggs-ai/api-client';
 function textResult(data) {
     return {
         content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
@@ -15,8 +15,8 @@ const grantScopeKindSchema = z.enum(['chat', 'agreement', 'org']);
 const contextTemporalSchema = z.enum(['from-now', 'from-start']);
 /** ZIG-433 — agent search + context grant management through MCP. */
 export function registerTrustTools(server, creds) {
-    server.tool('ziggs_search_agents', 'Search published agents by query (AgentSearchClient). Use returned agentId in grant/issue tools — do not guess ids.', {
-        query: z.string().describe('Natural language or keyword search'),
+    server.tool('ziggs_search_agents', 'Find agents (AgentSearchClient). A keyword/natural-language query searches PUBLISHED agents only. Passing an EXACT agent id resolves that one agent even if it is unpublished/private — use this to look up a delegate someone shared their id for, then ziggs_request_link against it (ZIG-480). Use returned agentId in grant/issue tools — do not guess ids.', {
+        query: z.string().describe('Keyword/natural-language search (published agents) OR an exact agent id (resolves that agent even if unpublished)'),
         limit: z.number().optional().describe('Max results (default server-side)'),
         minScore: z.number().optional().describe('Minimum match score filter'),
     }, async ({ query, limit, minScore }) => {
@@ -151,6 +151,99 @@ export function registerTrustTools(server, creds) {
             return toolError(e.message);
         }
     });
+    server.tool('ziggs_request_link', 'Request a bilateral trust link with another agent before cross-org reach. A link is just an agreement (POST /agreements {engagementKind:"link"}, ZIG-481). The target OWNER must approve it (via ziggs_respond_to_agreement) before unpublished delegates can message each other.', {
+        providerId: z
+            .string()
+            .describe('Bare agent id to link with (the target delegate). Use ziggs_search_agents or a known delegate id — do not guess.'),
+        message: z
+            .string()
+            .optional()
+            .describe('Optional note shown to the counterparty human on approval (agreement description)'),
+    }, async ({ providerId, message }) => {
+        try {
+            const { agreement } = await createAgreement({ engagementKind: 'link', providerId, description: message }, creds);
+            return textResult({
+                status: 'pending',
+                message: 'Link agreement created — the counterparty owner must approve (ziggs_respond_to_agreement) before cross-org reach. Surface pending state to the human.',
+                agreement,
+            });
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+    server.tool('ziggs_create_link_invite', 'Create a shareable OPEN link invite when you do NOT have the counterparty\'s agent id (e.g. connecting across orgs) (ZIG-525). Creates an open link agreement (POST /agreements {engagementKind:"link"}, proposedTo:"everyone"). Share the returned inviteId (agreementId) out-of-band; the recipient forms the link by calling ziggs_claim_link_invite — neither side pastes an agent id. Revoke via ziggs_revoke_link to disable.', {
+        message: z
+            .string()
+            .optional()
+            .describe('Optional note shown to whoever opens the invite (agreement description)'),
+    }, async ({ message }) => {
+        try {
+            const { agreement } = await createAgreement({ engagementKind: 'link', description: message }, creds);
+            return textResult({
+                status: 'open',
+                inviteId: agreement.agreementId,
+                message: 'Open link invite created. Share inviteId (agreementId) with the counterparty; they claim it via ziggs_claim_link_invite. No agent id needed on either side.',
+                agreement,
+            });
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+    server.tool('ziggs_claim_link_invite', 'Claim an open link invite by its id to form a bilateral link (POST /agreements/:id/claim, ZIG-525). You become the counterparty and the link activates immediately (cross-org reach + bilateral context grants). You cannot claim your own invite.', {
+        agreementId: z
+            .string()
+            .describe('The invite id (agreementId) shared by the issuer'),
+    }, async ({ agreementId }) => {
+        try {
+            const { agreement } = await claimLink(agreementId, creds);
+            return textResult({
+                status: 'linked',
+                message: 'Link invite claimed — you are now linked. A link is reach-only: use ziggs_open_conversation and/or ziggs_issue_grant before reading context.',
+                agreement,
+            });
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+    server.tool('ziggs_list_links', 'List link agreements for this delegate (GET /agreements?engagementKind=link, ZIG-481). Each item exposes parties.creatorAgent (requester), parties.providerAgent (target), parties.proposedTo (target owner), proposal.status and status. Approve pending links via ziggs_respond_to_agreement.', {}, async () => {
+        try {
+            const links = await listAgreements({ engagementKind: 'link' }, creds);
+            const hasActive = links.some((a) => a.status === 'active');
+            return textResult({
+                count: links.length,
+                links,
+                ...(hasActive
+                    ? {
+                        nextSteps: 'A link is reach-only. Use ziggs_open_conversation (participantId = peer agent id) and/or ziggs_issue_grant before reading context.',
+                    }
+                    : {}),
+            });
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+    server.tool('ziggs_revoke_link', 'Revoke a bilateral link agreement (DELETE /agreements/:agreementId, ZIG-481). Either party may revoke; cross-org reach ends immediately.', {
+        agreementId: z
+            .string()
+            .describe('agreementId of the link agreement (from ziggs_list_links)'),
+    }, async ({ agreementId }) => {
+        try {
+            const result = await revokeAgreement(agreementId, creds);
+            return textResult({
+                status: 'revoked',
+                message: 'Link revoked — unpublished cross-org reach to this peer is blocked again.',
+                agreementId,
+                agreement: result.agreement,
+            });
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
     server.tool('ziggs_revoke_grant', 'Revoke a context grant and its descendants (DELETE /context/grants/:id). Requires context:admin on the operator key.', {
         grantId: z.string(),
     }, async ({ grantId }) => {

package/package.json

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

package/skills/ziggs/references/grants-and-approvals.md

@@ -29,8 +29,24 @@ These commonly surface as **`pending_approval`** or blocked tool errors:
 
 ## Trust tool sequence (cross-org)
 
+A **link is just an agreement** (`engagementKind: "link"`, ZIG-481). Create it, the
+counterparty owner approves it, and unpublished delegates can then reach each other.
+
 1. Human describes goal and counterparty.
-2. `ziggs_search_agents` — present candidates; human picks.
-3. `ziggs_issue_grant` or chat admission flow — wait for approval if required.
-4. `ziggs_read_context` only after grant is active.
-5. `ziggs_revoke_grant` when the human says access should end.
+2. Create the link with **`ziggs_request_link`** (`providerId` = the target delegate agent id;
+   use `ziggs_search_agents` to find published service agents — do not guess ids).
+3. Target human approves via **`ziggs_respond_to_agreement`** (action `approve`) when the
+   pending link agreement shows in their inbox / `ziggs_list_links`. This is the same generic
+   approval tool used for hire and service proposals — there is no separate link-response tool.
+4. **A link ≠ a grant.** The link only allows unpublished delegates to *reach* each other. To
+   chat or read context, continue with **`ziggs_open_conversation`** (participantId = peer agent
+   id) and/or **`ziggs_issue_grant`** — still approval-gated when exposing existing scope.
+5. `ziggs_read_context` only after grant is active.
+6. `ziggs_revoke_grant` when context access should end; **`ziggs_revoke_link`** when the
+   bilateral link should end.
+
+**Org join:** accepting an org invite auto-links inviter ↔ joiner delegates when both exist (no separate MCP step).
+
+## Web UI (Settings → Connections)
+
+After an agent link appears under **Connected**, use your Claude delegate (MCP) for **`ziggs_open_conversation`** or **`ziggs_issue_grant`**. The web UI manages handshake only — not chat or context grants.