@ziggs-ai/ziggs-mcp 0.3.1 → 0.4.0

package/dist/tools.js

@@ -1,6 +1,6 @@
 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 { registerTrustTools } from './trustTools.js';
 import { registerPaymentTools } from './paymentTools.js';
@@ -18,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.
@@ -46,118 +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-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.
- */
-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.
- */
-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' };
-}
-/**
- * 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
@@ -205,6 +100,140 @@ async function loadSessionActionsPayload(creds, cfg, opts) {
         withSessionCard: opts?.withSessionCard,
     });
 }
+// ZIG-941 #7 — heavy tool groups pulled out of registerZiggsTools so the
+// lean session-start tier (ZIGGS_MCP_CORE_ONLY) can skip registering them.
+// Registration is otherwise identical to the previous inline definitions.
+function registerMarketplaceTools(server, creds) {
+    server.tool('ziggs_publish_quest', 'Publish an open quest any agent can claim (buyer-broadcast): you are the buyer, and whoever claims it does the work. audience="everyone" (default) is fully public across all orgs; audience="org" scopes it to your active org — only agents in your org see it in marketplace feeds and may claim it. The payer is derived server-side as your side (the publisher); there is no payer input.', {
+        description: z.string(),
+        chatId: z.string().optional(),
+        price: z.number().optional(),
+        audience: z
+            .enum(['everyone', 'org'])
+            .optional()
+            .describe("'everyone' (default, public) or 'org' (visible/claimable only within your org)"),
+    }, WRITE, async ({ description, chatId, price, audience }) => {
+        try {
+            // Buyer-broadcast: the payer is derived server-side as the creating
+            // principal (your side), and providerId is forbidden on broadcasts —
+            // the claiming agent fills the open provider side. So we send neither.
+            // audience flows straight through; the api-client + backend map it to
+            // the proposedTo sentinel and scope on the publisher's org.
+            const agreement = await proposeBroadcast({
+                description,
+                chatId: chatId ?? '',
+                price,
+                engagementKind: 'service',
+                audience: audience ?? 'everyone',
+            }, creds);
+            return textResult({ agreement });
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+    server.tool('ziggs_publish_offer', 'Publish a standing offer buyers can claim (seller-broadcast). audience="everyone" (default) is public; audience="org" scopes it to your active org. Requires an active org when audience="org".', {
+        description: z.string(),
+        price: z.number().optional(),
+        engagementKind: z.enum(['hire', 'service']).optional(),
+        audience: z
+            .enum(['everyone', 'org'])
+            .optional()
+            .describe("'everyone' (default, public) or 'org' (visible/claimable only within your org)"),
+    }, WRITE, async ({ description, price, engagementKind, audience }) => {
+        try {
+            const agreement = await publishOffer({
+                description,
+                price,
+                engagementKind,
+                audience: audience ?? 'everyone',
+            }, creds);
+            return textResult({ offer: agreement });
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+    server.tool('ziggs_claim_offer', 'Claim a published standing offer (POST /marketplace/offers/claim). Use for relay worker provisioning when the worker has a marketplace offer — no worker-side approval needed.', {
+        agreementId: z.string().describe('Open offer agreementId to claim'),
+    }, WRITE, async ({ agreementId }) => {
+        try {
+            const offer = await claimOffer(agreementId, creds);
+            return textResult({ offer });
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+    server.tool('ziggs_provision_relay_workers', 'Initiator path: provision per-step worker agreements before relay kickoff. Reuses active delegations under the hire, claims standing offers when available, otherwise proposes delegations (worker must approve — never impersonated). Returns relay:v1 payload and POST /tasks body when all steps are active.', {
+        hireAgreementId: z.string(),
+        chatId: z
+            .string()
+            .optional()
+            .describe('Required when a step has no standing offer and needs delegation under the hire'),
+        inputArtifactIds: z.array(z.string()).optional(),
+        steps: z.array(z.object({
+            stepId: z.string(),
+            order: z.number(),
+            assigneeId: z.string(),
+            description: z.string(),
+            offerAgreementId: z
+                .string()
+                .optional()
+                .describe('Explicit open offer to claim for this worker'),
+        })),
+        kickoff: z
+            .boolean()
+            .optional()
+            .describe('When true and readyForKickoff, also POST /tasks on the hire for relay-coordinator'),
+    }, WRITE, async ({ hireAgreementId, chatId, inputArtifactIds, steps, kickoff }) => {
+        try {
+            const result = await provisionRelayWorkers({
+                creds,
+                hireAgreementId,
+                chatId,
+                inputArtifactIds,
+                steps,
+            });
+            const relayTaskBody = buildRelayCoordinatorTaskBody({
+                hireAgreementId,
+                payload: result.payload,
+            });
+            let task;
+            if (kickoff && result.readyForKickoff) {
+                task = await createTask(relayTaskBody, creds);
+            }
+            return textResult({
+                ...result,
+                relayTaskBody,
+                task,
+                nextSteps: result.readyForKickoff
+                    ? kickoff && task
+                        ? 'Relay coordinator task created — watch Execution for step progress.'
+                        : 'All worker agreements active — POST relayTaskBody via createTask or set kickoff=true.'
+                    : `Worker approval pending on: ${result.pendingApprovals.join(', ')}. Call ziggs_respond_to_agreement after workers approve, then re-run with kickoff=true.`,
+            });
+        }
+        catch (e) {
+            return toolError(e.message);
+        }
+    });
+}
+function registerConnectionTools(server, creds) {
+    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 new ConnectionsClient(creds.operatorKey, creds.agentId).listForHolder();
+            return textResult({ connections });
+        }
+        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 () => {
         const claims = decodeOperatorKeyClaims(creds.operatorKey);
@@ -346,15 +375,22 @@ export function registerZiggsTools(server, creds, cfg) {
             return toolError(e.message);
         }
     });
-    server.tool('ziggs_list_my_agreements', 'List agreements visible to the impersonated delegate agent (scope=mine).', {
+    server.tool('ziggs_list_my_agreements', 'List agreements you are a party to — your hires, proposals, and work (default scope "mine"). Pass scope "reachable" to list every agreement your grant can read in the org, including ones you are not a party to; the isYou flags on each row mark which party (if any) is you.', {
+        scope: z
+            .enum(['mine', 'reachable'])
+            .optional()
+            .describe('mine (default): only agreements where you are a party. reachable: all agreements your grant can read in the org.'),
         proposalStatus: z
             .string()
             .optional()
             .describe('Optional filter: pending, approved, rejected, …'),
-    }, READ_ONLY, async ({ proposalStatus }) => {
+    }, READ_ONLY, async ({ scope, proposalStatus }) => {
         try {
-            const agreements = await getMyAgreements(proposalStatus ? { proposalStatus } : {}, creds);
-            return textResult({ count: agreements.length, agreements });
+            const agreements = await getMyAgreements({
+                ...(proposalStatus ? { proposalStatus } : {}),
+                partyOnly: scope !== 'reachable',
+            }, creds);
+            return textResult({ count: agreements.length, scope: scope ?? 'mine', agreements });
         }
         catch (e) {
             return toolError(e.message);
@@ -380,23 +416,13 @@ 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
             .string()
             .optional()
-            .describe('User or agent id receiving the message. Optional when the chat has exactly one other member (the recipient is inferred server-side); required when multiple members could receive it.'),
+            .describe("User or agent id receiving the message. Optional: with exactly one other member the recipient is inferred server-side; in a room with several members an omitted receiver becomes a broadcast to the room's HUMAN members (agents are not woken by it). Pass 'human' to broadcast explicitly, or a specific agent id to address (and wake) that agent."),
         text: z.string(),
         entryType: z
             .string()
@@ -456,120 +482,9 @@ export function registerZiggsTools(server, creds, cfg) {
             return toolError(e.message);
         }
     });
-    server.tool('ziggs_publish_quest', 'Publish an open quest any agent can claim (buyer-broadcast): you are the buyer, and whoever claims it does the work. audience="everyone" (default) is fully public across all orgs; audience="org" scopes it to your active org — only agents in your org see it in marketplace feeds and may claim it. The payer is derived server-side as your side (the publisher); there is no payer input.', {
-        description: z.string(),
-        chatId: z.string().optional(),
-        price: z.number().optional(),
-        audience: z
-            .enum(['everyone', 'org'])
-            .optional()
-            .describe("'everyone' (default, public) or 'org' (visible/claimable only within your org)"),
-    }, WRITE, async ({ description, chatId, price, audience }) => {
-        try {
-            // Buyer-broadcast: the payer is derived server-side as the creating
-            // principal (your side), and providerId is forbidden on broadcasts —
-            // the claiming agent fills the open provider side. So we send neither.
-            // audience flows straight through; the api-client + backend map it to
-            // the proposedTo sentinel and scope on the publisher's org.
-            const agreement = await proposeBroadcast({
-                description,
-                chatId: chatId ?? '',
-                price,
-                engagementKind: 'service',
-                audience: audience ?? 'everyone',
-            }, creds);
-            return textResult({ agreement });
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
-    server.tool('ziggs_publish_offer', 'Publish a standing offer buyers can claim (seller-broadcast). audience="everyone" (default) is public; audience="org" scopes it to your active org. Requires an active org when audience="org".', {
-        description: z.string(),
-        price: z.number().optional(),
-        engagementKind: z.enum(['hire', 'service']).optional(),
-        audience: z
-            .enum(['everyone', 'org'])
-            .optional()
-            .describe("'everyone' (default, public) or 'org' (visible/claimable only within your org)"),
-    }, WRITE, async ({ description, price, engagementKind, audience }) => {
-        try {
-            const agreement = await publishOffer({
-                description,
-                price,
-                engagementKind,
-                audience: audience ?? 'everyone',
-            }, creds);
-            return textResult({ offer: agreement });
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
-    server.tool('ziggs_claim_offer', 'Claim a published standing offer (POST /marketplace/offers/claim). Use for relay worker provisioning when the worker has a marketplace offer — no worker-side approval needed.', {
-        agreementId: z.string().describe('Open offer agreementId to claim'),
-    }, WRITE, async ({ agreementId }) => {
-        try {
-            const offer = await claimOffer(agreementId, creds);
-            return textResult({ offer });
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
-    server.tool('ziggs_provision_relay_workers', 'Initiator path: provision per-step worker agreements before relay kickoff. Reuses active delegations under the hire, claims standing offers when available, otherwise proposes delegations (worker must approve — never impersonated). Returns relay:v1 payload and POST /tasks body when all steps are active.', {
-        hireAgreementId: z.string(),
-        chatId: z
-            .string()
-            .optional()
-            .describe('Required when a step has no standing offer and needs delegation under the hire'),
-        inputArtifactIds: z.array(z.string()).optional(),
-        steps: z.array(z.object({
-            stepId: z.string(),
-            order: z.number(),
-            assigneeId: z.string(),
-            description: z.string(),
-            offerAgreementId: z
-                .string()
-                .optional()
-                .describe('Explicit open offer to claim for this worker'),
-        })),
-        kickoff: z
-            .boolean()
-            .optional()
-            .describe('When true and readyForKickoff, also POST /tasks on the hire for relay-coordinator'),
-    }, WRITE, async ({ hireAgreementId, chatId, inputArtifactIds, steps, kickoff }) => {
-        try {
-            const result = await provisionRelayWorkers({
-                creds,
-                hireAgreementId,
-                chatId,
-                inputArtifactIds,
-                steps,
-            });
-            const relayTaskBody = buildRelayCoordinatorTaskBody({
-                hireAgreementId,
-                payload: result.payload,
-            });
-            let task;
-            if (kickoff && result.readyForKickoff) {
-                task = await createTask(relayTaskBody, creds);
-            }
-            return textResult({
-                ...result,
-                relayTaskBody,
-                task,
-                nextSteps: result.readyForKickoff
-                    ? kickoff && task
-                        ? 'Relay coordinator task created — watch Execution for step progress.'
-                        : 'All worker agreements active — POST relayTaskBody via createTask or set kickoff=true.'
-                    : `Worker approval pending on: ${result.pendingApprovals.join(', ')}. Call ziggs_respond_to_agreement after workers approve, then re-run with kickoff=true.`,
-            });
-        }
-        catch (e) {
-            return toolError(e.message);
-        }
-    });
+    if (!cfg.coreOnly) {
+        registerMarketplaceTools(server, creds);
+    }
     server.tool('ziggs_respond_to_agreement', 'Approve or reject a pending agreement. Uses PUT /approvals/:partyId or POST /claim for an open broadcast (public or org-scoped; org-scoped quests are claimable only by members of the agreement\'s org).', {
         agreementId: z.string(),
         action: z.enum(['approve', 'reject']),
@@ -688,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);
-        }
+    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_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);
-        }
-    });
-    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)
@@ -935,67 +728,11 @@ export function registerZiggsTools(server, creds, cfg) {
     // ---------------------------------------------------------------------------
     // Connection proxy (ZIG-569)
     // ---------------------------------------------------------------------------
-    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);
-        }
-    });
-    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);
-            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);
-        }
-    });
+    if (!cfg.coreOnly) {
+        registerConnectionTools(server, creds);
+    }
     registerTrustTools(server, creds, cfg);
-    registerPaymentTools(server, creds);
+    if (!cfg.coreOnly) {
+        registerPaymentTools(server, creds);
+    }
 }