@ziggs-ai/ziggs-mcp 0.3.2 → 0.5.0

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
@@ -574,7 +453,7 @@ export function registerZiggsTools(server, creds, cfg) {
             return toolError(e.message);
         }
     });
-    server.tool('ziggs_propose_agreement', 'Propose a direct agreement to one counterparty (proposedTo) in a chat. The payer is always derived server-side as the non-providing side — there is no payer input. Omit providerId (or set it to proposedTo) to commission the recipient (they work, your side pays). Set providerId to your own agent id to offer (you work, proposedTo pays). Set providerId to a third-party agent id to broker (they work, proposedTo pays) — that provider must have an active published offer whose terms match this proposal (price, lifecycle, engagementKind, etc.) or the call fails naming the mismatched field. engagementKind "service" (default) = one deliverable; "hire" = ongoing engagement. price is recorded on the agreement but does not itself trigger a transfer.', {
+    server.tool('ziggs_propose_agreement', 'Propose a direct agreement to one counterparty (proposedTo) in a chat. The payer is always derived server-side as the non-providing side — there is no payer input. Omit providerId (or set it to proposedTo) to commission the recipient (they work, your side pays). Set providerId to your own agent id to offer (you work, proposedTo pays). Set providerId to a third-party agent id to broker (they work, proposedTo pays) — that provider must have an active published offer whose terms match this proposal (price, lifecycle, engagementKind, etc.) or the call fails naming the mismatched field. engagementKind "service" (default) = one deliverable; "hire" = ongoing engagement. Agreements are STANDING by default (lifecycle "open": no expiry, unlimited tasks) — hire once, then keep spawning tasks under the same agreement; set expiresAt (time-bound) or maxExecutions (count-bound) only when the engagement should end on its own. price is recorded on the agreement but does not itself trigger a transfer.', {
         proposedTo: z.string(),
         chatId: z.string(),
         description: z.string(),
@@ -587,7 +466,25 @@ export function registerZiggsTools(server, creds, cfg) {
             .enum(['hire', 'service'])
             .optional()
             .describe("'service' (default) = one-off deliverable; 'hire' = ongoing engagement"),
-    }, WRITE, async ({ proposedTo, chatId, description, providerId, price, engagementKind }) => {
+        expiresAt: z
+            .string()
+            .optional()
+            .describe('ISO date: the agreement ends (is cancelled, tasks and all) at this time. Omit for a standing agreement.'),
+        maxExecutions: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe('The agreement auto-fulfills after this many completed tasks. Omit for unlimited tasks.'),
+        lifecycle: z
+            .enum(['open', 'time-bound', 'count-bound'])
+            .optional()
+            .describe("Usually inferred: expiresAt → 'time-bound', maxExecutions → 'count-bound', neither → 'open' (standing)."),
+        billing: z
+            .enum(['total', 'per_task'])
+            .optional()
+            .describe("How price reads. 'total' (default) = one price for the whole engagement, escrowed now and paid at the end. 'per_task' = a RATE charged for each completed task, paid as work lands — requires a standing (open) agreement, and is the default for a hire. Never send 'per_task' for a one-off price or the payer is charged it once per task."),
+    }, WRITE, async ({ proposedTo, chatId, description, providerId, price, engagementKind, expiresAt, maxExecutions, lifecycle, billing, }) => {
         try {
             const agreement = await proposeDirectTo({
                 proposedTo,
@@ -596,6 +493,10 @@ export function registerZiggsTools(server, creds, cfg) {
                 providerId: providerId?.trim() || proposedTo,
                 price,
                 engagementKind: engagementKind ?? 'service',
+                expiresAt,
+                maxExecutions,
+                lifecycle,
+                billing,
             }, creds);
             return textResult({ agreement });
         }
@@ -665,7 +566,7 @@ export function registerZiggsTools(server, creds, cfg) {
             return toolError(e.message);
         }
     });
-    server.tool('ziggs_fulfill_agreement', 'Mark an agreement you PROVIDE as fulfilled/complete once its work is delivered (POST /agreements/:id/fulfill) — closes the engagement so it no longer reads as in-progress. Party-gated server-side: only the providing side can fulfill. Use on your hire after the final deliverable is done and delivered.', {
+    server.tool('ziggs_fulfill_agreement', 'END an agreement you PROVIDE — permanently (POST /agreements/:id/fulfill). Fulfilling terminates the whole relationship, not one deliverable: every grant the agreement conferred (context, connection, payment) is revoked, its shared space is torn down, and it cannot be reopened — the counterparty would have to re-hire you from scratch. Finished WORK is reported with ziggs_set_task_result, which closes the task and leaves the agreement standing for the next one. Only fulfill a count/time-bound engagement whose full scope is delivered and where nothing more is expected — never a standing hire that just finished a task. Party-gated server-side: only the providing side can fulfill.', {
         agreementId: z.string().describe('The agreement you provide, to mark fulfilled'),
     }, WRITE, async ({ agreementId }) => {
         try {
@@ -678,13 +579,9 @@ export function registerZiggsTools(server, creds, cfg) {
     });
     server.tool('ziggs_inbox', ZIGGS_INBOX_DESCRIPTION, {
         ack: z
-            .array(z.object({
-            kind: z.enum(['chat', 'agreement', 'org']),
-            id: z.string(),
-            upTo: z.string().describe('ISO timestamp handled up to (inclusive)'),
-        }))
+            .string()
             .optional()
-            .describe('Scopes you finished handling — acked before fetching, monotonic'),
+            .describe("The envelope's `ackTo` from a previous call, once you have handled everything it carried — acked before fetching, monotonic (an older value is a no-op)."),
         waitSeconds: z
             .number()
             .optional()
@@ -692,7 +589,7 @@ export function registerZiggsTools(server, creds, cfg) {
     }, READ_ONLY, async ({ ack, waitSeconds }) => {
         try {
             const client = new InboxClient(creds.operatorKey, creds.agentId);
-            const acked = ack?.length ? await client.ack(ack) : null;
+            const acked = ack ? await client.ack(ack) : null;
             const inbox = await client.getInbox(waitSeconds != null ? { waitSeconds } : {});
             let activeTasks = [];
             let activeTasksError;
@@ -724,145 +621,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;