@ziggs-ai/ziggs-mcp 0.1.23 → 0.1.25

package/README.md

@@ -1,13 +1,13 @@
 # @ziggs-ai/ziggs-mcp
 
-MCP (stdio) server for **Claude Code**, **Cursor**, and other MCP hosts ([ZIG-222](https://linear.app/ziggsai/issue/ZIG-222/minimal-boarding-cursor-represents-you-on-ziggs), [ZIG-430](https://linear.app/ziggsai/issue/ZIG-430/publish-ziggs-mcp-to-npm-one-command-claude-code-boarding)).
+MCP (stdio) server for **Claude Code**, **Cursor**, and other MCP hosts.
 
 **In scope:** chat, agreements, scope, context discovery/reads, artifacts.  
 **Out of scope (by design):** agent `transfer`, hire agreements, capability tokens / bounded spend.
 
 ---
 
-## Claude Code (recommended — ZIG-430)
+## Claude Code (recommended)
 
 ### Quick start
 
@@ -17,11 +17,11 @@ claude mcp add ziggs \
   -- npx -y @ziggs-ai/ziggs-mcp
 ```
 
-Use an **agent-scoped** operator key from the Ziggs Developer Portal — no `registerAgent`, no separate `ZIGGS_AGENT_ID` ([ZIG-279](https://linear.app/ziggsai/issue/ZIG-279/agent-scoped-operator-keys-to-skip-registration)).
+Use an **agent-scoped** operator key from the Ziggs Developer Portal — no `registerAgent`, no separate `ZIGGS_AGENT_ID`.
 
 Full walkthrough: [`examples/claude-code.md`](examples/claude-code.md)
 
-### Plugin + skill (ZIG-437)
+### Plugin + skill
 
 One install bundles the MCP server config and the **ziggs** workflow skill (inbox → read → act → ack; no credentials in skill files):
 
@@ -37,7 +37,7 @@ claude plugin install ./ziggs-mcp
 
 Skill only (no plugin): `skills/ziggs/SKILL.md` ships in the package for org provisioning or [skills.sh](https://skills.sh) discovery.
 
-### Smoke (Linear ZIG-430)
+### Smoke
 
 | Step | Tool |
 |------|------|
@@ -53,13 +53,13 @@ ZIGGS_OPERATOR_KEY=<agent-scoped> node scripts/smoke-ziggs-mcp-z430-e2e.mjs
 
 ---
 
-## claude.ai / remote MCP (OAuth — ZIG-435 / ZIG-468)
+## claude.ai / remote MCP (OAuth)
 
 Hosted Streamable HTTP: `https://mcp.ziggsai.com/mcp` (Bearer from OAuth, no key paste).
 
 OAuth metadata: `https://api.ziggsai.com/.well-known/oauth-authorization-server`
 
-**Consent (ZIG-474):** `GET /oauth/authorize` always redirects to `/app/oauth/mcp-consent` — even if you already have an API session. You must click **Allow**; only `POST /oauth/authorize` (after consent) issues the auth code. E2E smoke uses POST directly (same as the consent page).
+**Consent:** `GET /oauth/authorize` always redirects to `/app/oauth/mcp-consent` — even if you already have an API session. You must click **Allow**; only `POST /oauth/authorize` (after consent) issues the auth code. E2E smoke uses POST directly (same as the consent page).
 
 Automated E2E (DCR → consent → token → remote MCP → list chats + send message):
 
@@ -72,19 +72,19 @@ ZIGGS_SMOKE_EMAIL=you@example.com ZIGGS_SMOKE_PASSWORD=... \
   node scripts/smoke-ziggs-mcp-oauth-z468-e2e.mjs
 ```
 
-**ZIG-474 consent probe** (GET must redirect to consent, not issue code):
+**Consent probe** (GET must redirect to consent, not issue code):
 
 ```bash
 node scripts/smoke-ziggs-mcp-oauth-z474-consent-probe.mjs --auto
 ```
 
-**Manual claude.ai connector (ZIG-475):** step-by-step checklist — [`examples/claude-ai-oauth.md`](examples/claude-ai-oauth.md).
+**Manual claude.ai connector:** step-by-step checklist — [`examples/claude-ai-oauth.md`](examples/claude-ai-oauth.md).
 
 ---
 
 ## Cursor
 
-### Remote OAuth (ZIG-476 — same path as claude.ai)
+### Remote OAuth (same path as claude.ai)
 
 Add to `.cursor/mcp.json` or `~/.cursor/mcp.json`:
 
@@ -157,34 +157,34 @@ Startup validates the key shape, expiry (JWT `exp`), and agent resolution — er
 From the **repository root** ([github.com/ZiggsAI/agentplus](https://github.com/ZiggsAI/agentplus)):
 
 ```bash
-# ZIG-222
+# basic boarding smoke
 ZIGGS_OPERATOR_KEY=... ZIGGS_AGENT_ID=cursor-delegate \
   node scripts/smoke-ziggs-mcp.mjs
 
-# ZIG-432 (two delegates + negative 403)
+# two delegates + negative 403
 ZIGGS_OPERATOR_KEY_A=... ZIGGS_AGENT_ID_A=... \
 ZIGGS_OPERATOR_KEY_B=... ZIGGS_AGENT_ID_B=... \
 ZIGGS_SMOKE_CHAT_ID=... \
   node scripts/smoke-ziggs-mcp-context.mjs
 
-# ZIG-433 tools-only (npx trust tools after publish)
+# tools-only (npx trust tools after publish)
 ZIGGS_OPERATOR_KEY=<agent-scoped> node scripts/smoke-ziggs-mcp-z433-e2e.mjs --tools-only
 
-# ZIG-433 auto two-org (provisions users/agents/chat, then full flow)
+# auto two-org (provisions users/agents/chat, then full flow)
 HTTP_URL=https://api.ziggsai.com node scripts/smoke-ziggs-mcp-z433-e2e.mjs --auto
 
-# ZIG-433 full two-org (manual env)
+# full two-org (manual env)
 ZIGGS_OPERATOR_KEY_A=... ZIGGS_AGENT_ID_A=... \
 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)
+# 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)
+# Runbook: docs/evals/party-connection-two-claude.md
 ```
 
 ---
@@ -193,19 +193,18 @@ OP_KEY_A=... AGENT_A=... USER_B=... OP_KEY_B=... AGENT_B=... \
 
 | Tool | Maps to |
 |------|---------|
-| `ziggs_inbox` | `GET /inbox` + `POST /inbox/ack` (ZIG-434, ZIG-491) |
+| `ziggs_inbox` | `GET /inbox` + `POST /inbox/ack` |
 | `ziggs_discover_context` | `GET /context/discovery` |
 | `ziggs_read_context` | `GET /context/read/:type` |
 | `ziggs_record_artifact` | `POST /artifacts` |
-| `ziggs_search_agents` | Agent search (ZIG-433) |
-| `ziggs_list_my_grants` | `GET /context/grants` |
+| `ziggs_search_agents` | Agent search |
 | `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_request_link` | `POST /agreements` `{engagementKind:"link"}` (a link is just an agreement) |
 | `ziggs_list_links` | `GET /agreements?engagementKind=link` |
 | `ziggs_revoke_link` | `DELETE /agreements/:agreementId` (see also `ziggs_revoke_agreement`) |
-| `ziggs_revoke_agreement` | `DELETE /agreements/:id` — any agreement (hire/service/quest/link), ZIG-207 |
+| `ziggs_revoke_agreement` | `DELETE /agreements/:id` — any agreement (hire/service/quest/link) |
 | `ziggs_smoke_impersonation` | [Internal/debug] connectivity check — not part of normal delegate workflow |
 | `ziggs_get_scope` | `GET /scope?via=` |
 | `ziggs_list_my_agreements` | `GET /agreements?scope=mine` |

package/dist/inboxToolResult.d.ts

@@ -9,6 +9,15 @@ export interface ReadPlanCall {
     args: Record<string, unknown>;
     why: string;
 }
+/**
+ * ZIG-660: buildReadPlan returns the (bounded, deduped) plan plus how many
+ * candidate entries the cap dropped, so the caller can surface truncation
+ * explicitly instead of the plan silently ending short.
+ */
+export interface ReadPlanResult {
+    plan: ReadPlanCall[];
+    truncated: number;
+}
 /**
  * ZIG-634: replace the free-text `nextActions` hints with typed `readPlan`
  * call objects — tool name + pre-filled args — so the most common loop
@@ -23,7 +32,7 @@ export interface ReadPlanCall {
  * 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[];
+export declare function buildReadPlan(inbox: InboxEnvelope, grantsByScope?: Map<string, ScopeGrantTag>): ReadPlanResult;
 /**
  * ZIG-634: forward-continuation for a read_context page. Built only from fields
  * already on the page (via, hasMore/nextCursor, latestSequence) plus the grant

package/dist/inboxToolResult.js

@@ -1,10 +1,13 @@
 import { formatPendingDecisionsPayload, resolveWebAppOrigin, } from './pendingDecisions.js';
 /** Keep the plan bounded; the full scopes array still carries everything. */
 const MAX_READ_PLAN = 12;
-function readContextCall(type, kind, id) {
+function readContextCall(type, kind, id, grantId) {
+    // ZIG-660: pin the covering grant so the read presents the right
+    // X-Context-Grant-Id without a separate discover_context round-trip.
+    const grant = grantId ? { contextGrantId: grantId } : {};
     return {
         tool: 'ziggs_read_context',
-        args: { type, via: `${kind}:${id}` },
+        args: { type, via: `${kind}:${id}`, ...grant },
         why: `open the ${type} behind the count on ${kind}:${id}`,
     };
 }
@@ -22,59 +25,69 @@ function readContextCall(type, kind, id) {
  * 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 buildReadPlan(inbox) {
-    const plan = [];
+export function buildReadPlan(inbox, grantsByScope) {
     const proposals = inbox.proposalsAwaitingMe ?? [];
     const connectionRequests = inbox.connectionRequestsAwaitingMe ?? [];
     const scopes = inbox.scopes ?? [];
+    // 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.
+    const candidates = [];
+    const seen = new Set();
+    const add = (key, call) => {
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        candidates.push(call);
+    };
     // Decisions first — these also drive humanAttention (pull-only: no push).
     // 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({
+        add(`respond:${p.agreementId}`, {
             tool: 'ziggs_respond_to_agreement',
             args: { agreementId: p.agreementId },
             why: 'agreement proposal awaiting your response — wait for the human to approve/reject',
         });
     }
     for (const c of connectionRequests) {
-        if (plan.length >= MAX_READ_PLAN)
-            break;
-        plan.push({
+        add(`respond:${c.requestId}`, {
             tool: 'ziggs_respond_to_agreement',
             args: { agreementId: c.requestId },
             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) {
-        if (plan.length >= MAX_READ_PLAN)
-            break;
         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)
-                plan.push(readContextCall('messages', 'chat', id));
+                read('messages', 'chat', id);
             if (s.newArtifacts)
-                plan.push(readContextCall('artifacts', 'chat', id));
+                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)
-                    plan.push(readContextCall('messages', 'chat', c.chatId));
+                    read('messages', 'chat', c.chatId);
             }
             // Artifacts (incl. task-result artifacts) read directly via the agreement.
             if (s.newArtifacts)
-                plan.push(readContextCall('artifacts', 'agreement', id));
+                read('artifacts', 'agreement', id);
         }
         else {
             // org: both messages and artifacts resolve per chat only.
             for (const c of s.chats ?? []) {
                 if (c.newMessages)
-                    plan.push(readContextCall('messages', 'chat', c.chatId));
+                    read('messages', 'chat', c.chatId);
                 if (c.newArtifacts)
-                    plan.push(readContextCall('artifacts', 'chat', c.chatId));
+                    read('artifacts', 'chat', c.chatId);
             }
         }
     }
@@ -83,14 +96,21 @@ export function buildReadPlan(inbox) {
     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) {
+    // 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 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) {
         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 plan.slice(0, MAX_READ_PLAN);
+    return { plan, truncated };
 }
 /**
  * ZIG-634: forward-continuation for a read_context page. Built only from fields
@@ -169,10 +189,9 @@ export function indexReachByScope(reach) {
  * 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)
+function tagScopesWithGrants(scopes, byScope) {
+    if (!byScope?.size)
         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;
@@ -187,8 +206,12 @@ function tagScopesWithGrants(scopes, reach) {
  * with its covering grant (ZIG-635) so the agent can pin X-Context-Grant-Id.
  */
 export function formatInboxToolResult(inbox, ack, webOrigin, activeTasks, reach) {
-    const readPlan = buildReadPlan(inbox);
-    const scopes = tagScopesWithGrants(inbox.scopes ?? [], reach);
+    // 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);
     const pending = formatPendingDecisionsPayload(inbox, origin, { activeTasks });
     const pendingTail = pending.hasActionable === true
@@ -201,7 +224,11 @@ export function formatInboxToolResult(inbox, ack, webOrigin, activeTasks, reach)
             ...(pending.workChatCard ? { workChatCard: pending.workChatCard } : {}),
         }
         : {};
-    const tail = { ...pendingTail, ...(readPlan.length ? { readPlan } : {}) };
+    const tail = {
+        ...pendingTail,
+        ...(readPlan.length ? { readPlan } : {}),
+        ...(readPlanTruncated ? { readPlanTruncated } : {}),
+    };
     const { humanAttention, ...rest } = inbox;
     const payload = ack
         ? { acked: ack.acked, ...rest, scopes, ...tail }

package/dist/operatorKey.d.ts

@@ -4,7 +4,6 @@ export interface OperatorKeyClaims {
     keyId?: string;
     ownerId?: string;
     boundAgentId?: string | null;
-    boundOrgId?: string | null;
     exp?: number;
 }
 declare const MINT_KEY_HELP: string;

package/dist/operatorKey.js

@@ -15,7 +15,6 @@ export function decodeOperatorKeyClaims(token) {
             keyId: payload.keyId,
             ownerId: payload.ownerId,
             boundAgentId: payload.boundAgentId ?? null,
-            boundOrgId: payload.boundOrgId ?? null,
             exp: payload.exp,
         };
     }

package/dist/pendingDecisions.d.ts

@@ -1,17 +1,22 @@
 import type { InboxEnvelope, Task } from '@ziggs-ai/api-client';
-export type PendingDecisionKind = 'proposal' | 'link_request';
+export type PendingDecisionKind = 'proposal' | 'link_request' | 'mcp_server_request';
 export interface PendingDecisionItem {
     kind: PendingDecisionKind;
+    /** Agreement id for proposals; requestId for link / MCP server requests. */
     agreementId: string;
     title: string;
     subtitle: string | null;
     proposedAt: string | null;
     proposedAtLabel: string | null;
     appUrl: string;
-    respondApprove: string;
-    respondReject: string;
-    sayApprove: string;
-    sayReject: string;
+    /**
+     * Null for mcp_server_request — connecting a server (OAuth) happens in the
+     * browser at /app/settings/connections; there is no MCP respond tool.
+     */
+    respondApprove: string | null;
+    respondReject: string | null;
+    sayApprove: string | null;
+    sayReject: string | null;
 }
 export interface ActiveWorkItem {
     taskId: string;
@@ -20,18 +25,20 @@ export interface ActiveWorkItem {
     state: string;
     planDone: number;
     planTotal: number;
-    processing: boolean;
     appUrl: string | null;
     sayWork: string;
 }
 export declare function resolveWebAppOrigin(webUrl?: string | null): string;
 export declare function agreementAppUrl(origin: string, agreementId: string): string;
 export declare function agreementsListAppUrl(origin: string): string;
+/** Where the human connects MCP servers and grants tools (ZIG-686). */
+export declare function connectionsSettingsAppUrl(origin: string): string;
 export declare function buildPendingDecisionItems(inbox: InboxEnvelope, webOrigin: string): PendingDecisionItem[];
 export declare function buildActiveWorkItems(tasks: Task[], webOrigin: string): ActiveWorkItem[];
 export declare function buildDecisionChatCard(items: PendingDecisionItem[], opts: {
     truncatedProposals?: number;
     truncatedConnectionRequests?: number;
+    truncatedMcpServerRequests?: number;
     agreementsListAppUrl?: string;
 }): string;
 export declare function buildWorkChatCard(work: ActiveWorkItem[], listUrl?: string): string;
@@ -39,6 +46,7 @@ export declare function buildWorkChatCard(work: ActiveWorkItem[], listUrl?: stri
 export declare function buildSessionChatCard(decisions: PendingDecisionItem[], work: ActiveWorkItem[], opts: {
     truncatedProposals?: number;
     truncatedConnectionRequests?: number;
+    truncatedMcpServerRequests?: number;
     agreementsListAppUrl?: string;
 }): string;
 /** Structured session payload for MCP tools (ZIG-625 + active work). */