@ziggs-ai/ziggs-mcp 0.1.9 → 0.1.11

package/README.md

@@ -154,9 +154,9 @@ Startup validates the key shape, expiry (JWT `exp`), and agent resolution — er
 
 ### 4. CLI smoke scripts
 
-```bash
-cd agentplus
+From the **repository root** ([github.com/ZiggsAI/agentplus](https://github.com/ZiggsAI/agentplus)):
 
+```bash
 # ZIG-222
 ZIGGS_OPERATOR_KEY=... ZIGGS_AGENT_ID=cursor-delegate \
   node scripts/smoke-ziggs-mcp.mjs
@@ -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)
 ```
 
 ---
@@ -187,7 +193,7 @@ ZIGGS_SMOKE_CHAT_ID=... \
 
 | Tool | Maps to |
 |------|---------|
-| `ziggs_inbox` | `GET /agent-api/v1/inbox` + `POST .../ack` (ZIG-434) |
+| `ziggs_inbox` | `GET /inbox` + `POST /inbox/ack` (ZIG-434, ZIG-491) |
 | `ziggs_discover_context` | `GET /context/discovery` |
 | `ziggs_read_context` | `GET /context/read/:type` |
 | `ziggs_record_artifact` | `POST /artifacts` |
@@ -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,14 +215,13 @@ 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) |
 
 ---
 
 ## Develop
 
 ```bash
-cd agentplus
 npm install
 npm run build -w @ziggs-ai/ziggs-mcp
 npm test -w @ziggs-ai/ziggs-mcp

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/examples/claude-ai-oauth.md

@@ -15,7 +15,7 @@ Manual smoke runbook for the **real claude.ai connector UI**. Automated coverage
 Automated probe (same guarantee, no claude.ai UI):
 
 ```bash
-cd agentplus
+# from github.com/ZiggsAI/agentplus clone root
 node scripts/smoke-ziggs-mcp-oauth-z474-consent-probe.mjs --auto
 ```
 
@@ -94,7 +94,7 @@ If you are already logged in, you still see this screen (ZIG-474). You are **not
 Full API path smoke (no claude.ai UI):
 
 ```bash
-cd agentplus
+# from github.com/ZiggsAI/agentplus clone root
 node scripts/smoke-ziggs-mcp-oauth-z468-e2e.mjs --auto
 node scripts/smoke-ziggs-mcp-oauth-z474-consent-probe.mjs --auto
 ```

package/examples/claude-code-remote-mcp.json

@@ -1,6 +1,7 @@
 {
   "mcpServers": {
     "ziggs": {
+      "type": "http",
       "url": "https://mcp.ziggsai.com/mcp"
     }
   }

package/examples/claude-code-remote-oauth.md

@@ -5,9 +5,12 @@ Verify the **fresh Claude Code** journey: empty repo, `.mcp.json` only (no opera
 Automated prerequisites + Path A parity (no UI):
 
 ```bash
-cd agentplus
+# from github.com/ZiggsAI/agentplus clone root
 node scripts/smoke-zig-500-v4-path.mjs --discovery-only
 node scripts/smoke-zig-500-v4-path.mjs --auto
+node scripts/smoke-zig-500-v4-claude-code.mjs   # Claude Code CLI parity
+# or:
+./scripts/run-zig-500-v4-claude-code.sh
 ```
 
 ---
@@ -19,11 +22,12 @@ node scripts/smoke-zig-500-v4-path.mjs --auto
 | ZIG-496 discovery (well-known, 401 docs) | `--discovery-only` | Client uses same URLs |
 | OAuth → Bearer → full tool surface | `--auto` or smoke creds | Connect in IDE |
 | No stub-only tools | fails if only `authenticate` / `complete_authentication` | Tool picker shows `ziggs_*` |
+| Runtime tools work | `ziggs_connection_status` + `ziggs_inbox` | Same smoke in IDE |
 | Restart not required | N/A | Tools visible right after OAuth |
 
-**Path A (pass):** Native MCP OAuth — client discovers metadata, gets Bearer, `tools/list` returns ≥12 `ziggs_*` tools.
+**Pass:** Native MCP OAuth — client discovers metadata, gets Bearer, `tools/list` returns ≥12 `ziggs_*` tools, and inbox/connection_status succeed.
 
-**Path B (fail → epic children 501–502):** OAuth succeeds but only stub auth tools appear — needs unauth MCP + `tools/list_changed` design in backend.
+**Fail:** OAuth OK but tools empty, stub-only list, or inbox 404 → comment on [ZIG-500](https://linear.app/ziggsai/issue/ZIG-500) with tool list + smoke output.
 
 ---
 
@@ -37,6 +41,7 @@ Copy [`claude-code-remote-mcp.json`](claude-code-remote-mcp.json):
 {
   "mcpServers": {
     "ziggs": {
+      "type": "http",
       "url": "https://mcp.ziggsai.com/mcp"
     }
   }
@@ -52,19 +57,18 @@ Use a **throwaway directory** (no existing Ziggs plugin or stdio MCP).
 ### 3. Connect / authorize
 
 1. Claude Code should prompt for MCP OAuth (or open MCP settings).
-2. Browser → Ziggs consent (`/app/oauth/mcp-consent`) → **Allow**.
+2. Browser → Ziggs consent (`/app/oauth/mcp-consent`) — pick **org** if you have teams → **Allow**.
 3. Return to Claude Code — check tool list.
 
 ### 4. Smoke tools (no restart)
 
 Ask Claude to call in order:
 
-1. `ziggs_list_chats` or `ziggs_inbox`
-2. `ziggs_send_message` (chat you belong to)
+1. `ziggs_connection_status` — confirm agent + org binding
+2. `ziggs_inbox` or `ziggs_list_chats`
+3. `ziggs_send_message` (chat you belong to)
 
-**Pass:** both succeed; tool picker shows many `ziggs_*` tools (not just 2 auth stubs).
-
-**Fail:** only `authenticate` / `complete_authentication`; or OAuth OK but tools empty until restart → comment on [ZIG-500](https://linear.app/ziggsai/issue/ZIG-500) with Path B.
+**Pass:** all succeed; tool picker shows many `ziggs_*` tools (not just 2 auth stubs).
 
 ---
 
@@ -92,9 +96,9 @@ For dev or when OAuth is blocked, use [claude-code.md](claude-code.md) Option B
 | Symptom | Check |
 |---------|--------|
 | OAuth loop / 401 on tools | Re-run `smoke-zig-500-v4-path.mjs --auto`; revoke MCP in Agents dashboard → reconnect |
-| Only 2 stub tools | Path B — epic needs 501/502; paste tool list in Linear |
-| `app.ziggsai.com` in 401 `error` text | ZIG-496 fixed `docs` field; `error` string comes from pinned `@ziggs-ai/ziggs-mcp` npm — bump backend dep after publish |
-| Tools after restart only | ZIG-502 `tools/list_changed` candidate |
+| Only 2 stub tools | Should not happen on current prod (Bearer-only `/mcp`); paste tool list in ZIG-500 |
+| `ziggs_inbox` 404 | Backend must pin `@ziggs-ai/ziggs-mcp@0.1.9+` (ZIG-491 `/inbox` path); npm 0.1.10+ fixes Claude Code `.mcp.json` example (`type: http`) |
+| Wrong org | Reconnect; pick org on consent screen (ZIG-504) |
 
 ---
 
@@ -106,9 +110,10 @@ Date:
 Claude Code version:
 Repo: empty + .mcp.json only (Y/N)
 Automated: smoke-zig-500-v4-path.mjs --discovery-only → pass/fail
-Automated: smoke-zig-500-v4-path.mjs --auto → Path A/B, N tools
+Automated: smoke-zig-500-v4-path.mjs --auto → Path A, N tools, inbox pass/fail
 Manual OAuth connect: pass/fail
 Tool count after OAuth (no restart): __
-ziggs_inbox or ziggs_list_chats: pass/fail
+ziggs_connection_status: pass/fail
+ziggs_inbox: pass/fail
 Notes:
 ```

package/examples/claude-code.md

@@ -58,7 +58,7 @@ Ask Claude to call tools in order:
 Paste the session transcript in the PR when verifying ZIG-430, or run:
 
 ```bash
-cd agentplus
+# from github.com/ZiggsAI/agentplus clone root
 ZIGGS_OPERATOR_KEY=<agent-scoped> node scripts/smoke-ziggs-mcp-z430-e2e.mjs
 ```
 

package/examples/cursor-remote-oauth.md

@@ -80,7 +80,7 @@ Points `authorization_servers` → `https://api.ziggsai.com` and lists MCP scope
 Automated parity probe:
 
 ```bash
-cd agentplus
+# from github.com/ZiggsAI/agentplus clone root
 node scripts/probe-cursor-oauth-parity.mjs
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/ziggs-mcp",
-  "version": "0.1.9",
+  "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.