@ziggs-ai/ziggs-mcp 0.3.2 → 0.4.0

package/dist/capabilityAdapter.d.ts

@@ -0,0 +1,25 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type ZodRawShape } from 'zod';
+import type { CapabilityDefinition, CapabilityParam, Creds } from '@ziggs-ai/api-client';
+/** One JSON text-content result shape for every MCP tool (was copied 3×). */
+export declare function textResult(data: unknown): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export declare function toZodShape(params: Record<string, CapabilityParam>): ZodRawShape;
+export interface RegisterCapabilityOptions {
+    /** Web-app origin for human-facing URLs (claim links etc.). */
+    webUrl?: string;
+    /**
+     * Description override for wording assembled from MCP-local shared consts
+     * (e.g. the delegate-protocol reporting rule, ZIG-557) — schema and handler
+     * still come from the shared definition.
+     */
+    description?: string;
+    /** Surface-local response decoration (e.g. the read-plan on ziggs_read_context). */
+    transformResult?: (result: unknown, args: Record<string, unknown>) => unknown;
+}
+export declare function registerCapability(server: McpServer, cap: CapabilityDefinition, creds: Creds, opts?: RegisterCapabilityOptions): void;
+export declare function registerCapabilities(server: McpServer, caps: CapabilityDefinition[], creds: Creds, opts?: RegisterCapabilityOptions): void;

package/dist/capabilityAdapter.js

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+import { READ_ONLY, WRITE, DESTRUCTIVE } from './toolAnnotations.js';
+import { toolError } from './toolError.js';
+/** One JSON text-content result shape for every MCP tool (was copied 3×). */
+export function textResult(data) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
+    };
+}
+/**
+ * ZIG-956 — the MCP surface adapter for shared capability definitions
+ * (api-client `capabilities/`). Lowers the neutral param DSL to zod v3 (the
+ * MCP SDK's ZodRawShape; api-client itself carries no zod, and agent-sdk is on
+ * zod v4, so the schema is defined once and lowered per surface).
+ */
+function zodParam(param) {
+    let t;
+    switch (param.type) {
+        case 'string':
+            t = param.enum ? z.enum(param.enum) : z.string();
+            break;
+        case 'number':
+            t = z.number();
+            break;
+        case 'boolean':
+            t = z.boolean();
+            break;
+        case 'object':
+            t = z.record(z.unknown());
+            break;
+        case 'array': {
+            const items = param.items;
+            const inner = items?.type === 'string'
+                ? items.enum
+                    ? z.enum(items.enum)
+                    : z.string()
+                : z.record(z.unknown());
+            t = z.array(inner);
+            break;
+        }
+    }
+    if (param.description)
+        t = t.describe(param.description);
+    if (!param.required)
+        t = t.optional();
+    return t;
+}
+export function toZodShape(params) {
+    const shape = {};
+    for (const [name, param] of Object.entries(params)) {
+        shape[name] = zodParam(param);
+    }
+    return shape;
+}
+export function registerCapability(server, cap, creds, opts = {}) {
+    const annotations = cap.annotation === 'read-only'
+        ? READ_ONLY
+        : cap.annotation === 'destructive'
+            ? DESTRUCTIVE
+            : WRITE;
+    server.tool(cap.names.mcp, opts.description ?? cap.descriptions.mcp, toZodShape(cap.params), annotations, async (args) => {
+        try {
+            const env = { creds, webUrl: opts.webUrl, surface: 'mcp' };
+            const result = await cap.handler(args, env);
+            return textResult(opts.transformResult ? opts.transformResult(result, args) : result);
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+}
+export function registerCapabilities(server, caps, creds, opts = {}) {
+    for (const cap of caps)
+        registerCapability(server, cap, creds, opts);
+}

package/dist/paymentTools.d.ts

@@ -1,13 +1,14 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { type Creds } from '@ziggs-ai/api-client';
 /**
- * ZIG-896 — the wallet toolset on the MCP surface, same base names as the SDK's
- * PAYMENT_TOOLS (payment_* → ziggs_payment_*), riding the shared PaymentsClient
- * (ZIG-894). Safety is unchanged: money-moving calls are policy-gated
- * server-side (transfers above threshold return `approval_required`; the human
- * decides on the wallet page — surfaced by ziggs_pending_decisions), and rails
- * stay gated by the operator key's payments scopes. There is deliberately NO
- * approve/decide tool on either agent surface — an agent must not approve its
- * own spend.
+ * ZIG-896 / ZIG-956 — the wallet toolset on the MCP surface, same base names
+ * as the SDK's PAYMENT_TOOLS (payment_* → ziggs_payment_*), now registered
+ * from the shared capability definitions in api-client (one schema + handler,
+ * two thin surface adapters). Safety is unchanged: money-moving calls are
+ * policy-gated server-side (transfers above threshold return
+ * `approval_required`; the human decides on the wallet page — surfaced by
+ * ziggs_pending_decisions), and rails stay gated by the operator key's
+ * payments scopes. There is deliberately NO approve/decide tool on either
+ * agent surface — an agent must not approve its own spend.
  */
 export declare function registerPaymentTools(server: McpServer, creds: Creds): void;

package/dist/paymentTools.js

@@ -1,252 +1,16 @@
-import { z } from 'zod';
-import { PaymentsClient } from '@ziggs-ai/api-client';
-import { READ_ONLY, WRITE, DESTRUCTIVE } from './toolAnnotations.js';
-import { toolError } from './toolError.js';
-function textResult(data) {
-    return {
-        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
-    };
-}
-function buildCaveats(args) {
-    const caveats = [];
-    if (args.maxAmount != null)
-        caveats.push({ type: 'max_amount', value: args.maxAmount });
-    if (args.dailyBudget != null)
-        caveats.push({ type: 'daily_budget', value: args.dailyBudget });
-    if (args.allowedRecipients != null)
-        caveats.push({ type: 'allowed_recipients', value: args.allowedRecipients });
-    if (args.expiresInSeconds != null)
-        caveats.push({ type: 'expires_at', value: Date.now() + args.expiresInSeconds * 1000 });
-    return caveats;
-}
+import { PAYMENT_CAPABILITIES } from '@ziggs-ai/api-client';
+import { registerCapabilities } from './capabilityAdapter.js';
 /**
- * ZIG-896 — the wallet toolset on the MCP surface, same base names as the SDK's
- * PAYMENT_TOOLS (payment_* → ziggs_payment_*), riding the shared PaymentsClient
- * (ZIG-894). Safety is unchanged: money-moving calls are policy-gated
- * server-side (transfers above threshold return `approval_required`; the human
- * decides on the wallet page — surfaced by ziggs_pending_decisions), and rails
- * stay gated by the operator key's payments scopes. There is deliberately NO
- * approve/decide tool on either agent surface — an agent must not approve its
- * own spend.
+ * ZIG-896 / ZIG-956 — the wallet toolset on the MCP surface, same base names
+ * as the SDK's PAYMENT_TOOLS (payment_* → ziggs_payment_*), now registered
+ * from the shared capability definitions in api-client (one schema + handler,
+ * two thin surface adapters). Safety is unchanged: money-moving calls are
+ * policy-gated server-side (transfers above threshold return
+ * `approval_required`; the human decides on the wallet page — surfaced by
+ * ziggs_pending_decisions), and rails stay gated by the operator key's
+ * payments scopes. There is deliberately NO approve/decide tool on either
+ * agent surface — an agent must not approve its own spend.
  */
 export function registerPaymentTools(server, creds) {
-    const client = () => new PaymentsClient(creds.operatorKey, creds.agentId);
-    server.tool('ziggs_payment_balance', "Check the caller's current wallet balance and available balance (total minus active holds). Use before a transfer to confirm sufficient funds.", {}, READ_ONLY, async () => {
-        try {
-            return textResult(await client().balance());
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
-    server.tool('ziggs_payment_resolve_wallet', 'Look up a walletId by userId or agentId. Use before a transfer when you only know the recipient by their platform ID.', {
-        userId: z.string().optional().describe('User to resolve'),
-        agentId: z.string().optional().describe('Agent to resolve'),
-    }, READ_ONLY, async ({ userId, agentId }) => {
-        if (!userId && !agentId) {
-            return toolError('Provide userId or agentId to resolve a wallet');
-        }
-        try {
-            const wallet = (await client().resolve({ userId, agentId }));
-            return textResult({
-                walletId: wallet?.['walletId'] || null,
-                ownerId: wallet?.['ownerId'] || null,
-                currency: wallet?.['currency'] || 'pez',
-                status: wallet?.['status'] || null,
-            });
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
-    server.tool('ziggs_payment_transfer', 'Transfer funds to another wallet. Amounts are integer cents. As a delegate you spend under a payment grant the wallet owner issued (paymentGrantId — find yours via ziggs_list_grants scopeKind=wallet). Transfers above the owner\'s policy pause with status "approval_required": the human approves on the wallet page (it also shows in ziggs_pending_decisions) — you can wait inline with ziggs_payment_wait_for_approval, and you must NEVER approve your own transfer.', {
-        toWalletId: z
-            .string()
-            .describe('Destination wal_... id — or a userId/agentId to auto-resolve'),
-        amount: z.number().describe('Amount in integer cents, > 0'),
-        description: z.string().optional().describe('Human-readable transfer memo'),
-        idempotencyKey: z
-            .string()
-            .optional()
-            .describe('Client-supplied key to make retries safe (auto-generated when omitted)'),
-        paymentGrantId: z
-            .string()
-            .optional()
-            .describe('Payment grant to spend under (required for agent-impersonated transfers)'),
-    }, WRITE, async ({ toWalletId, amount, description, idempotencyKey, paymentGrantId }) => {
-        if (!amount || amount <= 0)
-            return toolError('amount must be positive');
-        try {
-            const result = (await client().transfer({
-                to: toWalletId,
-                amount: Math.round(amount),
-                description: description || 'Agent-initiated transfer',
-                idempotencyKey,
-                paymentGrantId,
-            }));
-            if (result['status'] === 'approval_required') {
-                return textResult({
-                    status: 'approval_required',
-                    approvalId: result['approvalId'] || null,
-                    expiresAt: result['expiresAt'] || null,
-                    reason: result['reason'] || null,
-                    amount,
-                    toWalletId: result['toWalletId'],
-                    note: 'Transfer paused: the wallet owner must approve this amount on the wallet page (also listed by ziggs_pending_decisions). Tell the human now (pull-only MCP has no push). ' +
-                        'Wait inline with ziggs_payment_wait_for_approval when you expect a quick decision (≤2 min).',
-                });
-            }
-            return textResult({
-                status: 'transferred',
-                transactionId: result['transactionId'] || null,
-                amount,
-                toWalletId: result['toWalletId'],
-            });
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
-    server.tool('ziggs_payment_wait_for_approval', 'Poll a paused transfer (status "approval_required") until the human decides or the timeout passes. Returns executed | rejected | expired | timeout | gone. Use for quick decisions (≤2 min); for longer waits, stop and check again next session.', {
-        approvalId: z.string().describe('Approval to wait on (from ziggs_payment_transfer)'),
-        timeoutMs: z.number().optional().describe('Max wait, default 120000'),
-        pollMs: z.number().optional().describe('Poll interval, default 3000 (min 500)'),
-    }, READ_ONLY, async ({ approvalId, timeoutMs, pollMs }) => {
-        try {
-            const result = (await client().waitForApproval(approvalId, {
-                timeoutMs,
-                pollMs,
-            }));
-            return textResult({
-                status: result['status'],
-                approvalId,
-                transactionId: result['transactionId'] || null,
-                approval: result['approval'] || null,
-            });
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
-    server.tool('ziggs_payment_hold', "Pre-authorize (escrow) funds without moving them. Use to reserve payment at agreement formation; release with ziggs_payment_release once work is complete, or refund if it's cancelled.", {
-        amount: z.number().describe('Amount in integer cents, > 0'),
-        description: z.string().optional().describe('Human-readable hold memo'),
-        idempotencyKey: z.string().optional().describe('Client-supplied retry-safety key'),
-    }, WRITE, async ({ amount, description, idempotencyKey }) => {
-        if (!amount || amount <= 0)
-            return toolError('amount must be positive');
-        try {
-            const result = (await client().hold({
-                amount: Math.round(amount),
-                description: description || 'Agent escrow hold',
-                idempotencyKey,
-            }));
-            return textResult({
-                status: 'held',
-                transactionId: result['transaction']?.['transactionId'] || null,
-                amount,
-            });
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
-    server.tool('ziggs_payment_release', "Settle or refund an escrow hold. action='complete' transfers held funds to toWalletId (work done); action='refund' returns funds to the sender (work cancelled).", {
-        holdId: z.string().describe('Hold to settle (transactionId from ziggs_payment_hold)'),
-        action: z.enum(['complete', 'refund']).describe('complete = pay out, refund = return'),
-        toWalletId: z
-            .string()
-            .optional()
-            .describe('Destination wallet — required when action=complete'),
-        idempotencyKey: z.string().optional().describe('Client-supplied retry-safety key'),
-    }, WRITE, async ({ holdId, action, toWalletId, idempotencyKey }) => {
-        if (action === 'complete' && !toWalletId) {
-            return toolError('toWalletId is required when action=complete');
-        }
-        try {
-            const result = (await client().release({
-                holdId,
-                action,
-                toWalletId,
-                idempotencyKey,
-            }));
-            return textResult({
-                status: action === 'complete' ? 'settled' : 'refunded',
-                transactionId: result['transaction']?.['transactionId'] || null,
-                holdId,
-                action,
-            });
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
-    const grantCaveatArgs = {
-        maxAmount: z.number().optional().describe('Per-transfer ceiling in cents'),
-        dailyBudget: z.number().optional().describe('Rolling daily budget in cents'),
-        allowedRecipients: z
-            .array(z.string())
-            .optional()
-            .describe('Wallet ids the holder may pay'),
-        expiresInSeconds: z.number().optional().describe('Grant lifetime from now'),
-    };
-    server.tool('ziggs_payment_issue_grant', "Issue a payment grant delegating bounded spend from the operator's wallet to an agent holder. Caveats bound what the holder can do (max_amount, daily_budget, allowed_recipients, expiry). The holder spends by passing the grantId as paymentGrantId on transfers.", {
-        holderId: z.string().describe('Agent that will hold the grant'),
-        ...grantCaveatArgs,
-    }, WRITE, async ({ holderId, ...caveatArgs }) => {
-        try {
-            const caveats = buildCaveats(caveatArgs);
-            const result = (await client().issueGrant({ holderId, caveats }));
-            const grant = result['grant'];
-            return textResult({
-                grantId: grant?.['grantId'] || null,
-                holderId: grant?.['holderId'] || holderId,
-                caveats: grant?.['caveats'] || caveats,
-                expiresAt: grant?.['expiresAt'] || null,
-            });
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
-    server.tool('ziggs_payment_attenuate_grant', 'Re-delegate a payment grant you hold to another agent with TIGHTER caveats (narrowing only — the child can never exceed the parent). Use to pass a bounded spend slice to a sub-agent.', {
-        grantId: z.string().describe('Parent grant to attenuate'),
-        holderId: z.string().describe('Agent that will hold the narrowed grant'),
-        ...grantCaveatArgs,
-    }, WRITE, async ({ grantId, holderId, ...caveatArgs }) => {
-        try {
-            const caveats = buildCaveats(caveatArgs);
-            const result = (await client().attenuateGrant({
-                grantId,
-                holderId,
-                caveats,
-            }));
-            const grant = result['grant'];
-            return textResult({
-                grantId: grant?.['grantId'] || null,
-                parentGrantId: grant?.['parentGrantId'] || grantId,
-                holderId: grant?.['holderId'] || holderId,
-                caveats: grant?.['caveats'] || caveats,
-                expiresAt: grant?.['expiresAt'] || null,
-            });
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
-    server.tool('ziggs_payment_revoke_grant', 'Revoke a payment grant (and its attenuated children). The holder can no longer spend under it.', {
-        grantId: z.string().describe('Grant to revoke'),
-    }, DESTRUCTIVE, async ({ grantId }) => {
-        try {
-            const result = (await client().revokeGrant(grantId));
-            return textResult({
-                status: 'revoked',
-                grantId,
-                revoked: result?.['revoked'] ?? null,
-            });
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
+    registerCapabilities(server, PAYMENT_CAPABILITIES, creds);
 }

package/dist/tools.js

@@ -1,8 +1,7 @@
 import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
-import { getAgreement, getMyAgreements, listMyChats, openConversation, proposeDirectTo, proposeBroadcast, publishOffer, claimOffer, provisionRelayWorkers, respondToAgreement, revokeAgreement, counterAgreement, fulfillAgreement, sendChatMessage, ConnectionsClient, PaymentsClient, assertNoLeakedConnectionSecret, ContextDiscoveryClient, ContextReadClient, ContextGrantsClient, GrantsClient, unreadableGrantRails, InboxClient, createTask, updateTaskState, replaceTaskPlan, listTasks, getTask, getBackendUrl, ArtifactsClient, } from '@ziggs-ai/api-client';
+import { getAgreement, getMyAgreements, listMyChats, proposeDirectTo, proposeBroadcast, publishOffer, claimOffer, provisionRelayWorkers, respondToAgreement, revokeAgreement, counterAgreement, fulfillAgreement, sendChatMessage, ConnectionsClient, PaymentsClient, ContextReadClient, GrantsClient, InboxClient, createTask, updateTaskState, replaceTaskPlan, listTasks, getTask, getBackendUrl, fetchMyOrgs, fetchDelegateAccess, GRANTS_CAPABILITIES, contextReadCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, recordArtifactCapability, openConversationCapability, connectionProxyCapability, requestConnectionCapability, } from '@ziggs-ai/api-client';
 import { decodeOperatorKeyClaims } from './operatorKey.js';
-import { fetchMyOrgs } from './orgs.js';
 import { registerTrustTools } from './trustTools.js';
 import { registerPaymentTools } from './paymentTools.js';
 import { formatInboxToolResult, buildReadContextReadPlan, } from './inboxToolResult.js';
@@ -19,6 +18,7 @@ function buildRelayCoordinatorTaskBody(opts) {
 }
 import { READ_ONLY, WRITE, DESTRUCTIVE } from './toolAnnotations.js';
 import { toolError } from './toolError.js';
+import { registerCapability, registerCapabilities, textResult, } from './capabilityAdapter.js';
 // ZIG-557: the protocol sentences (loop / ack / humanAttention) are sourced
 // from the shared const so this description can't drift from SKILL / server
 // instructions / .cursorrules.
@@ -47,75 +47,12 @@ const ZIGGS_SEND_MESSAGE_DESCRIPTION = 'Send a chat message as the delegate agen
 const ZIGGS_RECORD_ARTIFACT_DESCRIPTION = 'Write an artifact to a chat or agreement scope. Set visibility explicitly. ' +
     'For a finished deliverable, set content_type=result and pass taskId to bind it to the task. ' +
     PROTOCOL.reporting;
-/** Teach the result slot on the record_artifact success path (ZIG-560). */
-function recordArtifactReportingHint(contentType, taskId) {
-    if (contentType === 'result') {
-        return taskId
-            ? 'Recorded as a task-bound result artifact. Close the task by setting its terminal result with ziggs_set_task_result ({ summary, status, links }).'
-            : 'Recorded as a result artifact, but not bound to a task — pass taskId to bind it, then close the task with ziggs_set_task_result ({ summary, status, links }).';
-    }
-    return 'Reporting finished work? Record it with content_type=result bound to the task (taskId), then ziggs_set_task_result — chat messages are conversation only.';
-}
-function textResult(data) {
-    return {
-        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
-    };
-}
-const contextReadTypeSchema = z.enum([
-    'messages',
-    'artifacts',
-    'agreements',
-    'tasks',
-]);
-const artifactVisibilitySchema = z.enum(['chat', 'agent-private']);
 // ZIG-899 — the strict artifact write (fail loudly, return the artifactId)
 // moved into ArtifactsClient.writeStrict, shared with the SDK's record_artifact.
-// ZIG-894 — the leak-guard and the connections proxy/request calls moved into
-// @ziggs-ai/api-client's ConnectionsClient (shared with the agent SDK).
-/** ZIG-640 — runtime acting org from server (self-hire / agent row). */
-async function fetchDelegateAccess(creds) {
-    const url = `${getBackendUrl()}/agents/claude-delegate/access`;
-    const res = await fetch(url, {
-        method: 'GET',
-        headers: {
-            Authorization: `Bearer ${creds.operatorKey}`,
-            'X-Agent-Id': creds.agentId,
-        },
-    });
-    const body = await res.text().catch(() => '');
-    if (!res.ok) {
-        throw new Error(`GET /agents/claude-delegate/access ${res.status} ${body.slice(0, 200)}`);
-    }
-    return body ? JSON.parse(body) : {};
-}
-/**
- * ZIG-641 / ZIG-648 — cross-connection discovery over the unified GET /grants:
- * every connection grant this agent holds, grouped by connection so
- * ziggs_connection_proxy's connectionId/grantId no longer has to arrive out of
- * band. `provider` comes from the grant's resolved scope label. The response is
- * scanned defensively for leaked secrets, as ConnectionsClient.proxy does.
- */
-async function listConnectionsForHolder(creds) {
-    const client = new GrantsClient(creds.operatorKey, creds.agentId);
-    // All pages of the agent's live connection grants (not just the first page).
-    const items = await client.listAllGrants({
-        scopeKind: 'connection',
-        health: 'active',
-    });
-    const byConnection = new Map();
-    for (const g of items) {
-        const connectionId = g.scope.id;
-        let group = byConnection.get(connectionId);
-        if (!group) {
-            group = { connectionId, provider: g.scope.label ?? null, grants: [] };
-            byConnection.set(connectionId, group);
-        }
-        group.grants.push(g);
-    }
-    const result = [...byConnection.values()];
-    assertNoLeakedConnectionSecret(JSON.stringify(result));
-    return result;
-}
+// ZIG-894 / ZIG-956 — the leak-guard, the connections proxy/request calls, the
+// grouped connection lister (ConnectionsClient.listForHolder), the org lookups
+// (fetchMyOrgs / fetchDelegateAccess), and the whole SDK-twin tool definitions
+// all live in @ziggs-ai/api-client now (shared with the agent SDK).
 /**
  * Ids this delegate answers for: its own agent id plus its principal's user
  * id (operator-key ownerId / ZIGGS_OWNER_USER_ID). Used to decide which
@@ -283,67 +220,19 @@ function registerMarketplaceTools(server, creds) {
     });
 }
 function registerConnectionTools(server, creds) {
-    server.tool('ziggs_connection_proxy', "Use a stored connection (a third-party credential, e.g. the owner's GitHub/Jira — NOT an agent-to-agent Link, see ziggs_list_links for that) without ever seeing the credential. " +
-        'Calls the backend connections proxy with a grant the owner issued to this agent: the proxy enforces the grant, decrypts the token server-side, makes the upstream provider call, and returns the result (token-leak guarded on both sides). ' +
-        'Provide connectionId, grantId, the provider action (e.g. repo:read), and an optional action-specific payload. ' +
-        "Don't know connectionId/grantId yet? Call ziggs_list_my_connections first.", {
-        connectionId: z.string().describe('Connection to act on'),
-        grantId: z
-            .string()
-            .describe('Grant the owner issued to this agent for the connection'),
-        action: z.string().describe('Provider action, e.g. repo:read'),
-        payload: z
-            .record(z.unknown())
-            .optional()
-            .describe('Action-specific arguments (provider-defined)'),
-    }, WRITE, async ({ connectionId, grantId, action, payload }) => {
-        try {
-            const result = await new ConnectionsClient(creds.operatorKey, creds.agentId).proxy({ connectionId, grantId, action, payload });
-            return textResult({ ok: true, action, result });
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
+    registerCapability(server, connectionProxyCapability, creds);
     server.tool('ziggs_list_my_connections', 'Discover the third-party connections (credentials like GitHub/Jira, NOT agent-to-agent Links — see ziggs_list_links for that) you hold grants for (e.g. "is GitHub connected?") without the owner sharing connectionId/grantId out of band. ' +
         'Returns, per connection: connectionId, provider, and the grant(s) you hold — each as the canonical grant shape (grantId, scope, caveats, and grant health active/expired/revoked). ' +
         'Read-only — never returns credential material. Feed the connectionId + a grantId with health "active" into ziggs_connection_proxy to actually use it.', {}, READ_ONLY, async () => {
         try {
-            const connections = await listConnectionsForHolder(creds);
+            const connections = await new ConnectionsClient(creds.operatorKey, creds.agentId).listForHolder();
             return textResult({ connections });
         }
         catch (e) {
             return toolError(e.message);
         }
     });
-    server.tool('ziggs_request_connection', 'Ask your principal (the human) to connect a remote MCP server and grant you the listed tools. ' +
-        'Opens a connection-consent agreement as an approvable card in the chat you pass — the human approves it there like any other agreement (there is no MCP tool to approve it, so tell them to approve it in the chat). ' +
-        'On approval the server is connected (browser OAuth if needed) and you are granted the tools; the result shows up in ziggs_list_my_connections for use with ziggs_connection_proxy.', {
-        chatId: z
-            .string()
-            .describe('The chat you are working in — the consent card is opened there'),
-        serverUrl: z.string().describe('Remote MCP server URL (https)'),
-        tools: z
-            .array(z.string())
-            .describe("Tool names you want — become the grant's allowed_actions caveats"),
-        reason: z
-            .string()
-            .optional()
-            .describe('Plain-language reason shown to the human deciding'),
-    }, WRITE, async ({ chatId, serverUrl, tools, reason }) => {
-        try {
-            const result = await new ConnectionsClient(creds.operatorKey, creds.agentId).requestMcpConnection({ chatId, serverUrl, tools, reason });
-            return textResult({
-                ok: true,
-                ...result,
-                note: 'A connection-consent card is now in the chat awaiting your principal. Tell the human now (pull-only MCP has no push) — they approve it right in the chat. ' +
-                    'Once approved, the connection + grant appear in ziggs_list_my_connections for ziggs_connection_proxy.',
-            });
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
+    registerCapability(server, requestConnectionCapability, creds);
 }
 export function registerZiggsTools(server, creds, cfg) {
     server.tool('ziggs_auth_status', 'Verify MCP OAuth binding: delegate agent id, owner user id, and org scope. Call after connect before inbox/chats. Includes pendingDecisions summary when approve/reject is waiting. (Renamed from ziggs_connection_status — "connection" now refers only to third-party credential connections, see ziggs_connection_proxy.)', {}, READ_ONLY, async () => {
@@ -527,17 +416,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. 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'),
-    }, WRITE, async ({ participantId }) => {
-        try {
-            const out = await openConversation(participantId, creds);
-            return textResult(out);
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
+    registerCapability(server, openConversationCapability, creds);
     server.tool('ziggs_send_message', ZIGGS_SEND_MESSAGE_DESCRIPTION, {
         chatId: z.string(),
         receiverId: z
@@ -724,145 +603,23 @@ export function registerZiggsTools(server, creds, cfg) {
             return toolError(e.message);
         }
     });
-    server.tool('ziggs_list_grants', 'List every grant this delegate holds across all rails in one call — context (chat/agreement/org), connection, and wallet — as canonical grants (grantId, scope, caveats, expiresAt, health; no content or credentials). The single answer to "what grants of mine do you hold?", holder-scoped and cross-session. Filter by scopeKind (rail) and health (defaults to active). Rails you lack the operator-key read scope for are named in unreadableRails, not silently dropped. Cursor-paginated: pass cursor from a prior nextCursor to page. Pass a grantId to ziggs_read_context to pin a specific grant, or ziggs_expand_context to enumerate a scope.', {
-        scopeKind: z
-            .array(z.enum(['chat', 'agreement', 'org', 'connection', 'wallet']))
-            .optional()
-            .describe('Rail filter (repeatable). Omit for every rail you can read.'),
-        health: z
-            .enum(['active', 'expired', 'revoked'])
-            .optional()
-            .describe('Grant health filter. Defaults to active (live grants only).'),
-        cursor: z
-            .string()
-            .optional()
-            .describe('Opaque cursor from a prior nextCursor'),
-        limit: z.number().optional().describe('Page size (default server-side)'),
-    }, READ_ONLY, async ({ scopeKind, health, cursor, limit }) => {
-        try {
-            const client = new GrantsClient(creds.operatorKey, creds.agentId);
-            const kinds = scopeKind && scopeKind.length
-                ? scopeKind
-                : undefined;
-            const { items, nextCursor } = await client.listGrants({
-                scopeKind: kinds,
-                // Reach = live grants only by default; pass health for expired/revoked.
-                health: health ?? 'active',
-                cursor,
-                limit,
-            });
-            const unreadable = unreadableGrantRails(creds.operatorKey, kinds);
-            return textResult({
-                count: items.length,
-                grants: items,
-                nextCursor,
-                ...(unreadable && unreadable.length
-                    ? { unreadableRails: unreadable }
-                    : {}),
-            });
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
-    server.tool('ziggs_expand_context', 'Expand a grant you hold into the chat/agreement ids inside its scope, so you can actually read through it. ziggs_list_grants tells you that you hold e.g. org:acme or agreement:x; this returns the { chats, agreements } (ids + labels only, never content) that scope covers — feed an id to ziggs_read_context (via=chat:<id> / agreement:<id>). Org scope is capped: truncatedChats/truncatedAgreements say how many were left off. Holder-only, grant-fenced.', {
-        grantId: z
-            .string()
-            .describe('A grant you hold (grantId from ziggs_list_grants) to expand'),
-    }, READ_ONLY, async ({ grantId }) => {
-        try {
-            const client = new ContextGrantsClient(creds.operatorKey, creds.agentId);
-            return textResult(await client.getReach(grantId));
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
-    server.tool('ziggs_discover_grantable', 'See what context EXISTS in your orgs that you CANNOT read yet — so you can ask for it instead of failing blind. Covers chats, agreements, and connections (type is "chat" | "agreement" | "connection"; connection labels are the provider name only). Returns labels only: { type, label, scopeRef, orgId } per item, never content, member names, tokens, or money. Bounded to orgs you have an active agreement in. To act on one, ask your human to grant it, or (if you hold a broader grant of your own) delegate via ziggs_delegate_grant using the scopeRef. Use ziggs_list_grants for what you already hold; this is what you lack.', {}, READ_ONLY, async () => {
-        try {
-            const client = new ContextDiscoveryClient(creds.operatorKey, creds.agentId);
-            const items = await client.discoverGrantable();
-            return textResult({ count: items.length, items });
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
-    server.tool('ziggs_read_context', 'Read the contents of a scope you already hold: messages | artifacts | agreements | tasks (the type param), under via=chat:<id>, agreement:<id>, or task:<id>. Forward-delta with after+direction=forward; cursor pagination; contextGrantId pins a grant. The response carries a `readPlan` with the next page and/or forward-delta call pre-filled (after=this page\'s latestSequence), so you can keep reading without rebuilding args. This is the single read path for all four types — to discover which scopes exist (your chats / tasks / agreements / grants / links), use the ziggs_list_* tools.', {
-        type: contextReadTypeSchema.describe('Resource type to read'),
-        via: z
-            .string()
-            .describe('Scope entry, e.g. chat:<id>, agreement:<id>, task:<id>'),
-        cursor: z.string().optional().describe('Opaque cursor from prior nextCursor'),
-        after: z
-            .string()
-            .optional()
-            .describe('ISO timestamp for forward-delta (messages/artifacts)'),
-        direction: z
-            .enum(['forward'])
-            .optional()
-            .describe('Use forward with after for message forward-delta'),
-        limit: z.number().optional().describe('Page size (default server-side)'),
-        state: z.string().optional().describe('Task state filter (tasks only)'),
-        contextGrantId: z
-            .string()
-            .optional()
-            .describe('Pin a specific grant when holding several'),
-    }, READ_ONLY, async ({ type, via, cursor, after, direction, limit, state, contextGrantId }) => {
-        try {
-            const client = new ContextReadClient(creds.operatorKey, creds.agentId);
-            const result = await client.read(type, {
-                via,
-                cursor,
-                after,
-                direction,
-                limit,
-                state,
-                contextGrantId,
-            });
-            const readPlan = buildReadContextReadPlan(result, type, via, contextGrantId);
-            return textResult(readPlan.length ? { ...result, readPlan } : result);
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
+    registerCapabilities(server, GRANTS_CAPABILITIES, creds);
+    registerCapability(server, contextExpandReachCapability, creds);
+    registerCapability(server, contextDiscoverGrantableCapability, creds);
+    // The read-plan is MCP-local decoration (its next-call tool names and the
+    // inbox loop it feeds are this surface's); schema + handler stay shared.
+    registerCapability(server, contextReadCapability, creds, {
+        transformResult: (result, args) => {
+            const readPlan = buildReadContextReadPlan(result, args['type'], args['via'], args['contextGrantId']);
+            return readPlan.length
+                ? { ...result, readPlan }
+                : result;
+        },
     });
-    server.tool('ziggs_record_artifact', ZIGGS_RECORD_ARTIFACT_DESCRIPTION, {
-        text: z.string().describe('Artifact body'),
-        visibility: artifactVisibilitySchema.describe('chat = visible to scope parties; agent-private = delegate-only'),
-        chatId: z.string().optional().describe('Target chat (xor agreementId)'),
-        agreementId: z
-            .string()
-            .optional()
-            .describe('Target agreement (xor chatId)'),
-        taskId: z
-            .string()
-            .optional()
-            .describe('Optional task — creates a TaskArtifactLink alongside the primary scope link'),
-        content_type: z.string().optional().describe('Default text'),
-        idempotencyKey: z
-            .string()
-            .optional()
-            .describe('Optional dedup key: a redelivered record with the same key no-ops and returns the original artifact. Derive it deterministically (e.g. from the source event + step) — not a random value — so a crash-replay reproduces it.'),
-    }, WRITE, async ({ text, visibility, chatId, agreementId, taskId, content_type, idempotencyKey }) => {
-        try {
-            if ((chatId && agreementId) || (!chatId && !agreementId)) {
-                return toolError('Pass exactly one of chatId or agreementId');
-            }
-            const { artifactId } = await new ArtifactsClient(creds.operatorKey, creds.agentId).writeStrict({ text, visibility, chatId, agreementId, taskId, content_type, idempotencyKey });
-            return textResult({
-                ok: true,
-                artifactId,
-                visibility,
-                chatId,
-                agreementId,
-                taskId,
-                reportingHint: recordArtifactReportingHint(content_type, taskId),
-            });
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
+    // Description override keeps the reporting rule sourced from the shared
+    // PROTOCOL const (ZIG-557) so it can't drift from SKILL/server instructions.
+    registerCapability(server, recordArtifactCapability, creds, {
+        description: ZIGGS_RECORD_ARTIFACT_DESCRIPTION,
     });
     // ---------------------------------------------------------------------------
     // Task mutation tools (ZIG-555)

package/dist/trustTools.d.ts

@@ -1,5 +1,8 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { type Creds } from '@ziggs-ai/api-client';
 import type { ZiggsMcpConfig } from './config.js';
-/** ZIG-433 — agent search + context grant management through MCP. */
+/** ZIG-433 / ZIG-956 — agent search + context grant management through MCP.
+ * The SDK-twin tools (search/get, links, delegate) come from the shared
+ * capability layer; only the human-authority grant tools (issue/revoke) stay
+ * MCP-local. */
 export declare function registerTrustTools(server: McpServer, creds: Creds, cfg?: ZiggsMcpConfig): void;

package/dist/trustTools.js

@@ -1,227 +1,18 @@
 import { z } from 'zod';
-import { AgentSearchClient, ContextGrantsClient, createAgreement, listAgreements, revokeAgreement, claimAgreement, addChatMember, grantCaveat, } from '@ziggs-ai/api-client';
-import { fetchMyOrgs, resolveOrgSelector } from './orgs.js';
-import { READ_ONLY, WRITE, DESTRUCTIVE } from './toolAnnotations.js';
+import { ContextGrantsClient, addChatMember, contextBounds, resolveOrgScopeId, LINK_CAPABILITIES, DISCOVERY_CAPABILITIES, contextDelegateCapability, } from '@ziggs-ai/api-client';
+import { WRITE, DESTRUCTIVE } from './toolAnnotations.js';
 import { toolError } from './toolError.js';
-function textResult(data) {
-    return {
-        content: [{ type: 'text', text: JSON.stringify(data, null, 2) }],
-    };
-}
-/**
- * Human/LLM-readable bounds for a context grant. ZIG-646 folded a context
- * grant's temporal mode + read watermark into the canonical `caveats` array,
- * so pull them back out here to keep this tool's `bounds` summary stable.
- */
-function contextBounds(grant) {
-    return {
-        temporal: grantCaveat(grant, 'temporal'),
-        watermarkAt: grantCaveat(grant, 'watermark_at'),
-        expiresAt: grant.expiresAt,
-    };
-}
+import { registerCapabilities, registerCapability, textResult } from './capabilityAdapter.js';
 const grantScopeKindSchema = z.enum(['chat', 'agreement', 'org']);
 const contextTemporalSchema = z.enum(['from-now', 'from-start']);
 const DEFAULT_WEB_URL = 'https://ziggsai.com';
-/**
- * ZIG-941 #6 — org-scoped grants may name the org instead of pasting its opaque
- * org_... id. Resolve the selector against the operator's memberships via the
- * (previously unused) resolveOrgSelector: exact id or case-insensitive name.
- * Ambiguous names return the candidate list rather than guessing; a name that
- * matched nothing errors with a pointer to ziggs_list_my_orgs. An org_... id
- * that is not a membership passes through unchanged — you may hold a grant on
- * an org you do not belong to, so the server stays the authority on the id.
- */
-async function resolveOrgScope(creds, scopeId) {
-    const resolution = resolveOrgSelector(await fetchMyOrgs(creds), scopeId);
-    if (resolution.status === 'ok')
-        return { scopeId: resolution.orgId };
-    if (resolution.status === 'ambiguous') {
-        return {
-            error: toolError(`Org name "${scopeId}" matches ${resolution.matches.length} of your orgs — pass the org id: ` +
-                resolution.matches.map((m) => `${m.name} (${m.orgId})`).join(', ')),
-        };
-    }
-    if (scopeId.startsWith('org_'))
-        return { scopeId };
-    return {
-        error: toolError(`No org named "${scopeId}" in your memberships — use ziggs_list_my_orgs to see them, or pass the org id.`),
-    };
-}
-// ZIG-941 #7 — the link tool group, pulled out so the lean session-start
-// tier (ZIGGS_MCP_CORE_ONLY) can skip it. Registration is unchanged.
-function registerLinkTools(server, creds, webUrl) {
-    server.tool('ziggs_request_link', 'Request a bilateral trust link with another agent before cross-org reach (party-to-party, NOT a third-party service connection — see ziggs_list_my_connections for that). A link is just an agreement (POST /agreements {engagementKind:"link"}). 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)'),
-    }, WRITE, 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 (bilateral agent-to-agent trust, NOT a third-party service connection — see ziggs_list_my_connections for that) when you do NOT have the counterparty\'s agent id (e.g. connecting across orgs). 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)'),
-    }, WRITE, async ({ message }) => {
-        try {
-            const { agreement } = await createAgreement({ engagementKind: 'link', description: message }, creds);
-            return textResult({
-                status: 'open',
-                inviteId: agreement.agreementId,
-                claimUrl: `${webUrl}/app/link-invites/${agreement.agreementId}`,
-                message: 'Open link invite created. Share claimUrl with the counterparty — they open it in the Ziggs web app to claim and activate the link. 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 (agent-to-agent trust, NOT a third-party service connection — see ziggs_list_my_connections for that) (POST /agreements/:id/claim). 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'),
-    }, WRITE, async ({ agreementId }) => {
-        try {
-            const { agreement } = await claimAgreement(agreementId, creds);
-            return textResult({
-                status: 'linked',
-                message: 'Link invite claimed — you are now linked. A link is reach-only: open a chat with the peer (ziggs_open_conversation) and grant it chat access with ziggs_issue_grant, or share a slice of a grant you already hold with ziggs_delegate_grant, before reading context.',
-                agreement,
-            });
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
-    server.tool('ziggs_list_links', 'List link agreements for this delegate — bilateral agent-to-agent trust relationships, NOT third-party service connections (see ziggs_list_my_connections for those) (GET /agreements?engagementKind=link). Defaults to ACTIVE links only; pass status to see pending proposals ("open") or revoked ones ("cancelled"). Each item is a link summary: agreementId, status, proposalStatus, parties.creatorAgent (requester), parties.providerAgent (target), parties.proposedTo (target owner). Approve pending links via ziggs_respond_to_agreement.', {
-        status: z
-            .enum(['active', 'open', 'cancelled', 'all'])
-            .optional()
-            .describe('active (default) = established links; open = pending proposals/invites awaiting approval or claim; cancelled = revoked; all = every link regardless of status'),
-    }, READ_ONLY, async ({ status }) => {
-        try {
-            const resolvedStatus = status ?? 'active';
-            const links = await listAgreements({
-                engagementKind: 'link',
-                ...(resolvedStatus === 'all' ? {} : { status: resolvedStatus }),
-            }, creds);
-            // ZIG-670: link-shaped summaries, not raw agreement documents — the
-            // money block, approvals array, and Mongo internals are noise here.
-            const summaries = links.map((a) => ({
-                agreementId: a.agreementId,
-                status: a.status,
-                proposalStatus: a.proposalStatus,
-                parties: {
-                    creatorAgent: a.parties?.creatorAgent ?? null,
-                    providerAgent: a.parties?.providerAgent ?? null,
-                    creator: a.parties?.creator ?? null,
-                    proposedTo: a.parties?.proposedTo ?? null,
-                },
-                ...(a.description ? { description: a.description } : {}),
-                createdAt: a.createdAt,
-            }));
-            const hasActive = links.some((a) => a.status === 'active');
-            return textResult({
-                count: summaries.length,
-                status: resolvedStatus,
-                links: summaries,
-                ...(hasActive
-                    ? {
-                        nextSteps: 'A link is reach-only. Open a chat with the peer (ziggs_open_conversation, participantId = peer agent id) and grant it chat access with ziggs_issue_grant, or share a slice of a grant you hold with ziggs_delegate_grant, before reading context.',
-                    }
-                    : {}),
-            });
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
-    server.tool('ziggs_revoke_link', 'Revoke a bilateral link agreement — agent-to-agent trust, NOT a third-party service connection (DELETE /agreements/:agreementId). Either party may revoke; cross-org reach ends immediately. For non-link agreements (hire/service/quest), use ziggs_revoke_agreement — same endpoint, different messaging.', {
-        agreementId: z
-            .string()
-            .describe('agreementId of the link agreement (from ziggs_list_links)'),
-    }, DESTRUCTIVE, 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);
-        }
-    });
-}
-/** ZIG-433 — agent search + context grant management through MCP. */
+/** ZIG-433 / ZIG-956 — agent search + context grant management through MCP.
+ * The SDK-twin tools (search/get, links, delegate) come from the shared
+ * capability layer; only the human-authority grant tools (issue/revoke) stay
+ * MCP-local. */
 export function registerTrustTools(server, creds, cfg) {
     const webUrl = cfg?.ZIGGS_WEB_URL?.replace(/\/$/, '') ?? DEFAULT_WEB_URL;
-    server.tool('ziggs_search_agents', 'Find agents (AgentSearchClient). A keyword/natural-language query searches the published store AND, scoped to your authority, your own org-mates and any delegate you have an active link with — so you can find a teammate or another user\'s delegate by name and ziggs_open_conversation with it directly, even if it is unpublished/offline and has never been in a chat with you. Passing an EXACT agent id resolves that one agent even if unpublished/private — use this for a delegate someone shared an id for, then ziggs_request_link if not yet linked. Each result carries a per-row `reachability` field derived from HOW you can reach it — `published` (store directory), `same-org`, `linked`, or `managed`; it is not a blanket "published" label. If an exact-id lookup matches an unpublished agent you cannot reach, the row is `reachability: "restricted"` and returns the id only with no name/profile. Use returned agentId in grant/issue tools — do not guess ids.', {
-        query: z.string().describe('Keyword/natural-language search (published store + your org-mates + your linked delegates) OR an exact agent id (resolves that agent even if unpublished, when you can reach it)'),
-        limit: z.number().optional().describe('Max results (default server-side)'),
-        minScore: z.number().optional().describe('Minimum match score filter'),
-    }, READ_ONLY, async ({ query, limit, minScore }) => {
-        try {
-            const client = new AgentSearchClient(creds.operatorKey, creds.agentId);
-            const result = await client.searchAgents(query, { limit, minScore });
-            if (!result.success) {
-                return toolError(result.error ?? result.message ?? 'search failed');
-            }
-            if (!result.agents?.length) {
-                // ZIG-664: a bare {count: 0} reads as "discovery is down" to LLM
-                // callers — say what was searched and how to recover instead.
-                return textResult({
-                    count: 0,
-                    agents: [],
-                    searched: ['published store', 'your org-mates', 'your linked delegates'],
-                    hint: 'Zero hits means no agent profile matched these terms — discovery itself is up. ' +
-                        'Matching is lexical against agent name/description/tags, so try shorter or different keywords. ' +
-                        'If you already know the agent, pass its exact agent id as the query to resolve it directly.',
-                });
-            }
-            return textResult({
-                count: result.agents.length,
-                agents: result.agents,
-            });
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
-    server.tool('ziggs_get_agent', 'Fetch the full profile of ONE agent by its exact id (GET /agents/:id) — name, description, tags, capabilities, reachability, and reliability. Use to confirm a candidate before ziggs_propose_agreement / ziggs_request_link, when you already hold the agent id (from ziggs_search_agents, a grant, or an agreement party). Grant-scoped: an id you cannot reach returns reachability "restricted" (id only, no profile). To find an agent by keyword instead, use ziggs_search_agents.', {
-        agentId: z.string().describe('Exact agent id to fetch — do not guess'),
-    }, READ_ONLY, async ({ agentId }) => {
-        try {
-            const client = new AgentSearchClient(creds.operatorKey, creds.agentId);
-            const result = await client.getAgentById(agentId);
-            if (!result.success) {
-                return toolError(result.error ?? 'agent not found');
-            }
-            const { success: _success, ...agent } = result;
-            return textResult({ agent });
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
+    registerCapabilities(server, DISCOVERY_CAPABILITIES, creds);
     server.tool('ziggs_issue_grant', 'Issue bounded context access. Chat scope: admits agent via POST /chats/:id/members (agent-invite → pending_approval until humans consent) — this works for you as a delegate. Agreement/org scope: issuing a NEW root grant is a human-authority action; if you are acting for a principal you are denied (AGENT_LACKS_HUMAN_AUTHORITY) — instead use ziggs_delegate_grant to hand a peer a narrower slice of a grant you already hold, or ask your human to issue it. Defaults: from-now, narrow scope.', {
         holderId: z.string().describe('Bare agent id receiving the grant'),
         scopeKind: grantScopeKindSchema,
@@ -269,10 +60,7 @@ export function registerTrustTools(server, creds, cfg) {
             // ZIG-941 #6 — an org scope may be named rather than pasted as org_… id.
             let resolvedScopeId = scopeId;
             if (scopeKind === 'org') {
-                const resolved = await resolveOrgScope(creds, scopeId);
-                if ('error' in resolved)
-                    return resolved.error;
-                resolvedScopeId = resolved.scopeId;
+                resolvedScopeId = await resolveOrgScopeId({ creds, surface: 'mcp' }, scopeId);
             }
             const client = new ContextGrantsClient(creds.operatorKey, creds.agentId);
             const grant = await client.issueGrant({
@@ -291,58 +79,12 @@ export function registerTrustTools(server, creds, cfg) {
             return toolError(e.message);
         }
     });
-    server.tool('ziggs_delegate_grant', 'Delegate a narrower child grant from one you hold (POST /context/grants/:id/delegate). Delegation only narrows scope/expiry/temporal — never broadens. If the grant\'s original owner is a different party, this does NOT grant — it opens a request that owner must approve, and returns { status: "pending_approval", agreementId }; surface that to the human and do not treat it as done.', {
-        parentGrantId: z.string(),
-        holderId: z.string().describe('Agent receiving the delegated grant'),
-        scopeKind: grantScopeKindSchema,
-        scopeId: z.string(),
-        temporal: contextTemporalSchema.describe('from-now or from-start (must be same-or-narrower)'),
-        expiresAt: z.string().optional().nullable(),
-        watermarkAt: z
-            .string()
-            .optional()
-            .describe('from-now watermark ISO-8601 (optional; server may default)'),
-    }, WRITE, async ({ parentGrantId, holderId, scopeKind, scopeId, temporal, expiresAt, watermarkAt, }) => {
-        try {
-            // ZIG-941 #6 — an org scope may be named rather than pasted as org_… id.
-            let resolvedScopeId = scopeId;
-            if (scopeKind === 'org') {
-                const resolved = await resolveOrgScope(creds, scopeId);
-                if ('error' in resolved)
-                    return resolved.error;
-                resolvedScopeId = resolved.scopeId;
-            }
-            const client = new ContextGrantsClient(creds.operatorKey, creds.agentId);
-            const result = await client.delegateGrant(parentGrantId, {
-                holderId,
-                scope: { kind: scopeKind, id: resolvedScopeId },
-                temporal,
-                expiresAt,
-                watermarkAt,
-            });
-            if (result.status === 'pending_approval') {
-                return textResult({
-                    status: 'pending_approval',
-                    message: "This grant's original owner must approve sharing it. A request was opened for them — surface it to the human; nothing is granted yet.",
-                    parentGrantId,
-                    agreementId: result.agreementId,
-                    ownerId: result.ownerId,
-                });
-            }
-            const grant = result.grant;
-            return textResult({
-                status: 'delegated',
-                parentGrantId,
-                grant,
-                bounds: contextBounds(grant),
-            });
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
+    registerCapability(server, contextDelegateCapability, creds);
     if (!cfg?.coreOnly) {
-        registerLinkTools(server, creds, webUrl);
+        // ZIG-941 #7 — the link tool group is skipped by the lean session-start
+        // tier (ZIGGS_MCP_CORE_ONLY). Definitions live in the shared capability
+        // layer, including the linkSummary shaping the mutations now share.
+        registerCapabilities(server, LINK_CAPABILITIES, creds, { webUrl });
     }
     server.tool('ziggs_revoke_grant', 'Revoke a context grant and its descendants (DELETE /context/grants/:id). You can revoke (narrow) any grant you hold — this needs no special scope. Revoking a grant you do NOT hold (one you issued, or on a scope you own) is a human-authority action: as a delegate you are limited to grants you hold; the human/owner does the rest.', {
         grantId: z.string(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/ziggs-mcp",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "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.3.1",
+    "@ziggs-ai/api-client": "^0.4.0",
     "dotenv": "^16.6.1",
     "zod": "^3.24.2"
   },

package/dist/orgs.d.ts

@@ -1,28 +0,0 @@
-import { type Creds } from '@ziggs-ai/api-client';
-export interface MyOrg {
-    orgId: string;
-    name: string;
-    kind: string;
-    role?: string;
-}
-/**
- * ZIG-739 — the operator's full org membership (not just granted scopes, which
- * is all ziggs_list_grants sees). Lets the delegate resolve an org name to
- * an id and offer a pick-list instead of demanding a pasted org_... id.
- */
-export declare function fetchMyOrgs(creds: Creds): Promise<MyOrg[]>;
-export type OrgResolution = {
-    status: 'ok';
-    orgId: string;
-} | {
-    status: 'ambiguous';
-    matches: MyOrg[];
-} | {
-    status: 'not-found';
-};
-/**
- * ZIG-739 — resolve an org selector (exact org_... id OR a name/handle) against
- * the operator's memberships. Exact id wins; otherwise case-insensitive name
- * match. Ambiguous names return the candidates rather than guessing.
- */
-export declare function resolveOrgSelector(orgs: MyOrg[], selector: string): OrgResolution;

package/dist/orgs.js

@@ -1,44 +0,0 @@
-import { getBackendUrl } from '@ziggs-ai/api-client';
-/**
- * ZIG-739 — the operator's full org membership (not just granted scopes, which
- * is all ziggs_list_grants sees). Lets the delegate resolve an org name to
- * an id and offer a pick-list instead of demanding a pasted org_... id.
- */
-export async function fetchMyOrgs(creds) {
-    const url = `${getBackendUrl()}/orgs/me`;
-    const res = await fetch(url, {
-        method: 'GET',
-        headers: {
-            Authorization: `Bearer ${creds.operatorKey}`,
-            'X-Agent-Id': creds.agentId,
-        },
-    });
-    const body = await res.text().catch(() => '');
-    if (!res.ok) {
-        throw new Error(`GET /orgs/me ${res.status} ${body.slice(0, 200)}`);
-    }
-    const parsed = body ? JSON.parse(body) : {};
-    return (parsed.orgs ?? []).map((o) => ({
-        orgId: o.orgId,
-        name: o.name,
-        kind: o.kind,
-        role: o.role,
-    }));
-}
-/**
- * ZIG-739 — resolve an org selector (exact org_... id OR a name/handle) against
- * the operator's memberships. Exact id wins; otherwise case-insensitive name
- * match. Ambiguous names return the candidates rather than guessing.
- */
-export function resolveOrgSelector(orgs, selector) {
-    const byId = orgs.find((o) => o.orgId === selector);
-    if (byId)
-        return { status: 'ok', orgId: byId.orgId };
-    const needle = selector.toLowerCase();
-    const byName = orgs.filter((o) => o.name.toLowerCase() === needle);
-    if (byName.length === 1)
-        return { status: 'ok', orgId: byName[0].orgId };
-    if (byName.length > 1)
-        return { status: 'ambiguous', matches: byName };
-    return { status: 'not-found' };
-}