@ziggs-ai/agent-sdk 0.4.0 → 0.5.0

package/dist/server/agreements/AgreementService.d.ts

@@ -22,6 +22,12 @@ export declare class AgreementService {
     counter(agreementId: string, counter: CounterAgreementData): Promise<Agreement>;
     getStatus(agreementId: string): Promise<unknown | null>;
     list(filters?: ListAgreementsFilters): Promise<Agreement[]>;
+    /**
+     * ZIG-942: despite the name, the default returns every agreement the
+     * caller's grant can read in the active org — including ones the caller is
+     * not a party to (`isYou` all-false). Pass `{ partyOnly: true }` for only
+     * agreements where the caller is a party.
+     */
     mine(filters?: GetMyAgreementsFilters): Promise<Agreement[]>;
     get(agreementId: string): Promise<Agreement | null>;
     create(body: CreateAgreementBody): Promise<{

package/dist/server/agreements/AgreementService.js

@@ -46,6 +46,12 @@ export class AgreementService {
     list(filters = {}) {
         return listAgreements(filters, this.creds);
     }
+    /**
+     * ZIG-942: despite the name, the default returns every agreement the
+     * caller's grant can read in the active org — including ones the caller is
+     * not a party to (`isYou` all-false). Pass `{ partyOnly: true }` for only
+     * agreements where the caller is a party.
+     */
     mine(filters = {}) {
         return getMyAgreements(filters, this.creds);
     }

package/dist/server/tools/tier2/artifactTools.d.ts

@@ -1,3 +1,3 @@
-import { type ToolDefinition } from '../../../tools/defineTool.js';
+import type { ToolDefinition } from '../../../tools/defineTool.js';
 export declare const recordArtifactTool: ToolDefinition;
 export declare const ARTIFACT_TOOLS: ToolDefinition[];

package/dist/server/tools/tier2/artifactTools.js

@@ -1,82 +1,7 @@
-import { defineTool } from '../../../tools/defineTool.js';
-import { ArtifactsClient } from '@ziggs-ai/api-client';
-/**
- * ZIG-899 — deliberate artifact recording on the SDK surface, same base name
- * as ziggs-mcp's ziggs_record_artifact. Until now artifacts were written only
- * as a host-side effect (recordReport / record-event); the model could not
- * decide "this is a deliverable, record it" — which is exactly what the
- * delegate protocol tells agents to do for heavy results. Rides
- * ArtifactsClient.writeStrict (fail loudly, return the artifactId) — the same
- * wire call as the MCP tool.
- */
-function creds(ctx) {
-    const operatorKey = ctx?.['operatorKey'];
-    const agentId = ctx?.['agentId'];
-    if (!operatorKey)
-        throw new Error('operatorKey missing from tool context');
-    if (!agentId)
-        throw new Error('agentId missing from tool context');
-    return { operatorKey, agentId };
-}
-/**
- * ZIG-560 teaching carried over from the MCP tool: name the result slot on the
- * success path so an agent finds the right move unaided — reworded to the SDK
- * task grammar (task_update carries the terminal result on this surface).
- */
-function reportingHint(contentType, taskId) {
-    if (contentType === 'result') {
-        return taskId
-            ? 'Recorded as a task-bound result artifact. Close the task by setting its terminal result with task_update.'
-            : 'Recorded as a result artifact, but not bound to a task — pass taskId to bind it, then close the task with task_update.';
-    }
-    return 'Reporting finished work? Record it with content_type=result bound to the task (taskId), then close the task with task_update — chat messages are conversation only.';
-}
-export const recordArtifactTool = defineTool('record_artifact', {
-    text: { type: 'string', required: true, description: 'Artifact body' },
-    visibility: {
-        type: 'string',
-        required: true,
-        enum: ['chat', 'agent-private'],
-        description: 'chat = visible to scope parties; agent-private = your eyes only',
-    },
-    chatId: { type: 'string', description: 'Target chat (xor agreementId)' },
-    agreementId: { type: 'string', description: 'Target agreement (xor chatId)' },
-    taskId: {
-        type: 'string',
-        description: 'Optional task — creates a TaskArtifactLink alongside the primary scope link',
-    },
-    content_type: { type: 'string', description: 'Default text; use result for a finished deliverable' },
-}, async (args, ctx) => {
-    const chatId = args['chatId'];
-    const agreementId = args['agreementId'];
-    if ((chatId && agreementId) || (!chatId && !agreementId)) {
-        throw new Error('Pass exactly one of chatId or agreementId');
-    }
-    const visibility = args['visibility'];
-    if (visibility !== 'chat' && visibility !== 'agent-private') {
-        throw new Error('visibility must be chat or agent-private');
-    }
-    const contentType = args['content_type'];
-    const taskId = args['taskId'];
-    const { operatorKey, agentId } = creds(ctx);
-    const { artifactId } = await new ArtifactsClient(operatorKey, agentId).writeStrict({
-        text: args['text'],
-        visibility,
-        chatId,
-        agreementId,
-        taskId,
-        content_type: contentType,
-    });
-    return {
-        ok: true,
-        artifactId,
-        visibility,
-        chatId,
-        agreementId,
-        taskId,
-        reportingHint: reportingHint(contentType, taskId),
-    };
-}, {
-    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 — heavy results belong in artifacts, not chat messages.',
-});
-export const ARTIFACT_TOOLS = [recordArtifactTool];
+import { ARTIFACT_CAPABILITIES, recordArtifactCapability } from '@ziggs-ai/api-client';
+import { toolFromCapability, toolsFromCapabilities } from '../../../tools/capabilityAdapter.js';
+// ZIG-899 / ZIG-956 — deliberate artifact recording, defined once in
+// api-client's shared capability layer (including the ZIG-560 result-slot
+// teaching, worded per surface task grammar).
+export const recordArtifactTool = toolFromCapability(recordArtifactCapability);
+export const ARTIFACT_TOOLS = toolsFromCapabilities(ARTIFACT_CAPABILITIES);

package/dist/server/tools/tier2/chatTools.d.ts

@@ -1,3 +1,3 @@
-import { type ToolDefinition } from '../../../tools/defineTool.js';
+import type { ToolDefinition } from '../../../tools/defineTool.js';
 export declare const openConversationTool: ToolDefinition;
 export declare const CHAT_TOOLS: ToolDefinition[];

package/dist/server/tools/tier2/chatTools.js

@@ -1,37 +1,7 @@
-import { defineTool } from '../../../tools/defineTool.js';
-import { openConversation } from '@ziggs-ai/api-client';
-/**
- * ZIG-900 — the decided chat surface for hosted agents: open_conversation
- * only, same base name as MCP's ziggs_open_conversation. There is deliberately
- * NO chat-listing tool on the SDK: agents read context only via held grants
- * (ZIG-425) and chat membership auto-mints a chat grant (ZIG-428/426), so
- * "what chats can I see" is already answered by list_grants scopeKind=chat —
- * adding a lister would duplicate a context-family read (ZIG-626 rule).
- */
-function creds(ctx) {
-    const operatorKey = ctx?.['operatorKey'];
-    const agentId = ctx?.['agentId'];
-    if (!operatorKey)
-        throw new Error('operatorKey missing from tool context');
-    if (!agentId)
-        throw new Error('agentId missing from tool context');
-    return { operatorKey, agentId };
-}
-export const openConversationTool = defineTool('open_conversation', {
-    participantId: {
-        type: 'string',
-        required: true,
-        description: 'User or agent id to converse with (from agent_search — do not guess ids)',
-    },
-}, async (args, ctx) => {
-    if (!args['participantId'])
-        throw new Error('participantId is required');
-    const { chatId } = await openConversation(args['participantId'], creds(ctx));
-    return {
-        chatId,
-        note: 'Conversation is open (or reused). Your membership auto-mints a chat grant, so the chat also appears in list_grants scopeKind=chat for context reads.',
-    };
-}, {
-    description: 'Open or reuse a chat with a user or agent participant. To reach an agent in ANOTHER org, establish a link first — request_link (if you have its agent id) or create_link_invite (if you do not), approved/claimed — otherwise this fails with AGENT_NOT_PUBLISHED. To list chats you can already read, use list_grants scopeKind=chat.',
-});
-export const CHAT_TOOLS = [openConversationTool];
+import { CHAT_CAPABILITIES, openConversationCapability } from '@ziggs-ai/api-client';
+import { toolFromCapability, toolsFromCapabilities } from '../../../tools/capabilityAdapter.js';
+// ZIG-900 / ZIG-956 — open_conversation only (chat listing stays a
+// context-rail read, ZIG-626 rule); defined once in api-client's shared
+// capability layer.
+export const openConversationTool = toolFromCapability(openConversationCapability);
+export const CHAT_TOOLS = toolsFromCapabilities(CHAT_CAPABILITIES);

package/dist/server/tools/tier2/connectionTools.d.ts

@@ -1,5 +1,5 @@
 import { type ToolDefinition } from '../../../tools/defineTool.js';
 export declare const connectionProxyTool: ToolDefinition;
-export declare const connectionListGrantsTool: ToolDefinition;
 export declare const requestConnectionTool: ToolDefinition;
+export declare const connectionListGrantsTool: ToolDefinition;
 export declare const CONNECTION_TOOLS: ToolDefinition[];

package/dist/server/tools/tier2/connectionTools.js

@@ -1,107 +1,33 @@
+import { connectionProxyCapability, requestConnectionCapability, ConnectionsClient, } from '@ziggs-ai/api-client';
 import { defineTool } from '../../../tools/defineTool.js';
-import { ConnectionsClient } from '@ziggs-ai/api-client';
-function clientFor(ctx) {
+import { toolFromCapability } from '../../../tools/capabilityAdapter.js';
+// ZIG-956 — connection_proxy / request_connection are shared capability
+// definitions (api-client). connection_list_grants stays SDK-only: the MCP
+// surface folds connection listing into ziggs_list_my_connections (ZIG-893
+// allowance in the parity table).
+export const connectionProxyTool = toolFromCapability(connectionProxyCapability);
+export const requestConnectionTool = toolFromCapability(requestConnectionCapability);
+export const connectionListGrantsTool = defineTool('connection_list_grants', { connectionId: { type: 'string', required: true } }, async (args, ctx) => {
+    if (!args['connectionId'])
+        throw new Error('connectionId is required');
     const operatorKey = ctx?.['operatorKey'];
     if (!operatorKey)
         throw new Error('operatorKey missing from tool context');
-    // BACKEND_URL / ZIGGS_BACKEND_URL are the SDK runner's overrides; the shared
-    // client defaults to HTTP_URL (api-client convention) when neither is set.
     const baseUrl = process.env.BACKEND_URL || process.env.ZIGGS_BACKEND_URL || undefined;
-    return new ConnectionsClient(operatorKey, ctx?.['agentId'] || undefined, baseUrl);
-}
-function rethrowWithContext(error, prefix) {
-    const e = error;
-    const wrapped = new Error(`${prefix}: ${e.message}`);
-    if (e.status !== undefined)
-        wrapped.status = e.status;
-    if (e.body !== undefined)
-        wrapped.body = e.body;
-    wrapped['cause'] = error;
-    throw wrapped;
-}
-export const connectionProxyTool = defineTool('connection_proxy', {
-    connectionId: { type: 'string', required: true },
-    grantId: { type: 'string', required: true },
-    action: { type: 'string', required: true },
-    payload: { type: 'object' },
-}, async (args, ctx) => {
-    if (!args['connectionId'])
-        throw new Error('connectionId is required');
-    if (!args['grantId'])
-        throw new Error('grantId is required');
-    if (!args['action'])
-        throw new Error('action is required');
+    const client = new ConnectionsClient(operatorKey, ctx?.['agentId'] || undefined, baseUrl);
     try {
-        const result = await clientFor(ctx).proxy({
-            connectionId: args['connectionId'],
-            grantId: args['grantId'],
-            action: args['action'],
-            payload: args['payload'],
-        });
-        return { status: 'ok', result };
-    }
-    catch (e) {
-        rethrowWithContext(e, 'Connection proxy failed');
-    }
-});
-export const connectionListGrantsTool = defineTool('connection_list_grants', { connectionId: { type: 'string', required: true } }, async (args, ctx) => {
-    if (!args['connectionId'])
-        throw new Error('connectionId is required');
-    try {
-        const grants = await clientFor(ctx).listGrants({
-            connectionId: args['connectionId'],
-        });
+        const grants = await client.listGrants({ connectionId: args['connectionId'] });
         return { grants: grants || [] };
     }
     catch (e) {
-        rethrowWithContext(e, 'Failed to list connection grants');
-    }
-});
-export const requestConnectionTool = defineTool('request_connection', {
-    chatId: {
-        type: 'string',
-        required: true,
-        description: 'The chat you are working in — the consent card is opened there',
-    },
-    serverUrl: { type: 'string', required: true, description: 'Remote MCP server URL (https)' },
-    tools: {
-        type: 'array',
-        items: { type: 'string' },
-        required: true,
-        description: "Tool names you want — become the grant's allowed_actions caveats",
-    },
-    reason: {
-        type: 'string',
-        description: 'Plain-language reason shown to the human deciding',
-    },
-}, async (args, ctx) => {
-    if (!args['chatId'])
-        throw new Error('chatId is required');
-    if (!args['serverUrl'])
-        throw new Error('serverUrl is required');
-    const tools = args['tools'];
-    if (!Array.isArray(tools) || tools.length === 0) {
-        throw new Error('tools must be a non-empty array of tool names');
-    }
-    try {
-        const result = await clientFor(ctx).requestMcpConnection({
-            chatId: args['chatId'],
-            serverUrl: args['serverUrl'],
-            tools: tools,
-            reason: args['reason'],
-        });
-        return {
-            ok: true,
-            ...result,
-            note: 'A connection-consent card is now in the chat awaiting your principal — they approve it right there (ZIG-798 flow). ' +
-                'Once approved, the connection + grant appear in list_grants (scopeKind=connection) / connection_list_grants for connection_proxy.',
-        };
-    }
-    catch (e) {
-        rethrowWithContext(e, 'Connection request failed');
+        const err = e;
+        const wrapped = new Error(`Failed to list connection grants: ${err.message}`);
+        if (err.status !== undefined)
+            wrapped.status = err.status;
+        if (err.body !== undefined)
+            wrapped.body = err.body;
+        throw wrapped;
     }
-}, {
-    description: '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. On approval the server is connected (browser OAuth if needed) and you are granted the tools; use them via connection_proxy.',
 });
 export const CONNECTION_TOOLS = [
     connectionProxyTool,

package/dist/server/tools/tier2/contextTools.d.ts

@@ -1,6 +1,6 @@
-import { type ToolDefinition } from '../../../tools/defineTool.js';
+import type { ToolDefinition } from '../../../tools/defineTool.js';
 export declare const contextReadTool: ToolDefinition;
 export declare const contextDelegateTool: ToolDefinition;
 export declare const contextExpandReachTool: ToolDefinition;
 export declare const contextDiscoverGrantableTool: ToolDefinition;
-export declare const CONTEXT_TOOLS: readonly [ToolDefinition, ToolDefinition, ToolDefinition, ToolDefinition];
+export declare const CONTEXT_TOOLS: ToolDefinition[];

package/dist/server/tools/tier2/contextTools.js

@@ -1,139 +1,10 @@
-import { defineTool } from '../../../tools/defineTool.js';
-import { ContextDiscoveryClient, ContextGrantsClient, ContextReadClient, } from '@ziggs-ai/api-client';
-/**
- * Context grant calls impersonate the grant holder, so both operatorKey (fleet
- * or agent-scoped key) and agentId (X-Agent-Id) must be on the tool context.
- * The same api-client clients back ziggs-mcp — one wire contract, no fork
- * (ZIG-869 / ZIG-775).
- */
-function creds(ctx) {
-    const operatorKey = ctx?.['operatorKey'];
-    const agentId = ctx?.['agentId'];
-    if (!operatorKey)
-        throw new Error('operatorKey missing from tool context');
-    if (!agentId)
-        throw new Error('agentId missing from tool context');
-    return { operatorKey, agentId };
-}
-const CONTEXT_READ_TYPES = [
-    'messages',
-    'artifacts',
-    'agreements',
-    'tasks',
-];
-export const contextReadTool = defineTool('context_read', {
-    type: {
-        type: 'string',
-        required: true,
-        enum: [...CONTEXT_READ_TYPES],
-        description: 'Resource type to read from the scope',
-    },
-    via: {
-        type: 'string',
-        required: true,
-        description: 'Scope entry you hold, e.g. chat:<id>, agreement:<id>, task:<id>',
-    },
-    cursor: { type: 'string', description: 'Opaque cursor from a prior nextCursor to page' },
-    after: {
-        type: 'string',
-        description: 'ISO timestamp for forward-delta (messages/artifacts)',
-    },
-    direction: {
-        type: 'string',
-        enum: ['forward'],
-        description: 'Use "forward" with after for a message forward-delta',
-    },
-    limit: { type: 'number', description: 'Page size (server default when omitted)' },
-    state: { type: 'string', description: 'Task state filter (tasks only)' },
-    contextGrantId: {
-        type: 'string',
-        description: 'Pin a specific grant when you hold several over the same scope',
-    },
-}, async (args, ctx) => {
-    const { operatorKey, agentId } = creds(ctx);
-    const type = args['type'];
-    if (!CONTEXT_READ_TYPES.includes(type)) {
-        throw new Error(`type must be one of ${CONTEXT_READ_TYPES.join(', ')}`);
-    }
-    const via = args['via'];
-    if (!via)
-        throw new Error('via is required');
-    const direction = args['direction'];
-    if (direction !== undefined && direction !== 'forward') {
-        throw new Error('direction must be "forward"');
-    }
-    return new ContextReadClient(operatorKey, agentId).read(type, {
-        via,
-        cursor: args['cursor'],
-        after: args['after'],
-        direction: direction,
-        limit: typeof args['limit'] === 'number' ? args['limit'] : undefined,
-        state: args['state'],
-        contextGrantId: args['contextGrantId'],
-    });
-}, {
-    description: 'Read the contents of a scope you already hold a grant for: messages | artifacts | agreements | tasks. Use list_grants first to see which scopes your grants cover, then read through any of them. Cursored; all access is grant-fenced server-side.',
-});
-export const contextDelegateTool = defineTool('context_delegate', {
-    parentGrantId: { type: 'string', required: true },
-    holderId: { type: 'string', required: true },
-    scopeKind: { type: 'string', required: true },
-    scopeId: { type: 'string', required: true },
-    temporal: { type: 'string', required: true },
-    expiresAt: 'string',
-    watermarkAt: 'string',
-}, async (args, ctx) => {
-    const temporal = args['temporal'];
-    if (temporal !== 'from-now' && temporal !== 'from-start') {
-        throw new Error('temporal must be from-now or from-start');
-    }
-    const scopeKind = args['scopeKind'];
-    if (scopeKind !== 'chat' && scopeKind !== 'agreement' && scopeKind !== 'org') {
-        throw new Error('scopeKind must be chat, agreement, or org');
-    }
-    const { operatorKey, agentId } = creds(ctx);
-    return new ContextGrantsClient(operatorKey, agentId).delegateGrant(args['parentGrantId'], {
-        holderId: args['holderId'],
-        scope: { kind: scopeKind, id: args['scopeId'] },
-        temporal,
-        expiresAt: args['expiresAt'] ?? undefined,
-        watermarkAt: args['watermarkAt'],
-    });
-}, {
-    description: 'Delegate a narrower child context grant (tighter scope, shorter expiry, or from-now). Holder-only. Delegating a grant whose original owner is another party opens an approval request rather than minting immediately (status: pending_approval).',
-});
-export const contextExpandReachTool = defineTool('context_expand_reach', {
-    grantId: {
-        type: 'string',
-        required: true,
-        description: 'A grant you hold (grantId from list_grants) to expand',
-    },
-}, async (args, ctx) => {
-    const { operatorKey, agentId } = creds(ctx);
-    const grantId = args['grantId'];
-    if (!grantId)
-        throw new Error('grantId is required');
-    return new ContextGrantsClient(operatorKey, agentId).getReach(grantId);
-}, {
-    description: 'Expand a grant you hold into the chat/agreement ids inside its scope, so you can read through it. list_grants tells you that you hold e.g. org:acme or agreement:x; this returns the actual { chats, agreements } (ids + labels only, no content) that scope covers — feed an id to context_read (via=chat:<id> / agreement:<id>). Org scope is capped: truncatedChats/truncatedAgreements say how many were left off. Holder-only, grant-fenced.',
-});
-// ZIG-754 — the negative-space complement to the reach tools. list_grants /
-// context_expand_reach answer "what CAN I read?"; this answers "what exists
-// just outside my fence that I CAN'T read yet?" so the agent can flag missing
-// context and make an informed widen request instead of silently
-// under-delivering on partial context. The MCP surface has had this as
-// ziggs_discover_grantable; this is its SDK/legibility complement, backed by
-// the same ContextDiscoveryClient (one wire contract, no fork).
-export const contextDiscoverGrantableTool = defineTool('context_discover_grantable', {}, async (_args, ctx) => {
-    const { operatorKey, agentId } = creds(ctx);
-    const items = await new ContextDiscoveryClient(operatorKey, agentId).discoverGrantable();
-    return { count: items.length, items };
-}, {
-    description: 'See what context EXISTS in your orgs that you CANNOT read yet — the inverse of list_grants. Covers chats, agreements, and connections (type is one of "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, and excludes anything you already hold a grant for. Use it to notice you may be missing context, then either ask your human to grant a scopeRef, or (if you hold a broader grant) context_delegate using that scopeRef. Pair with list_grants (what you hold) and context_expand_reach (what a held grant covers).',
-});
-export const CONTEXT_TOOLS = [
-    contextReadTool,
-    contextDelegateTool,
-    contextExpandReachTool,
-    contextDiscoverGrantableTool,
-];
+import { CONTEXT_CAPABILITIES, contextReadCapability, contextDelegateCapability, contextExpandReachCapability, contextDiscoverGrantableCapability, } from '@ziggs-ai/api-client';
+import { toolFromCapability, toolsFromCapabilities } from '../../../tools/capabilityAdapter.js';
+// ZIG-869 / ZIG-775 / ZIG-956 — context grant tools ride the same api-client
+// clients as ziggs-mcp; the whole definition (schema + handler) is now shared
+// via the capability layer, so the two surfaces cannot fork.
+export const contextReadTool = toolFromCapability(contextReadCapability);
+export const contextDelegateTool = toolFromCapability(contextDelegateCapability);
+export const contextExpandReachTool = toolFromCapability(contextExpandReachCapability);
+export const contextDiscoverGrantableTool = toolFromCapability(contextDiscoverGrantableCapability);
+export const CONTEXT_TOOLS = toolsFromCapabilities(CONTEXT_CAPABILITIES);

package/dist/server/tools/tier2/discoveryTools.d.ts

@@ -1,4 +1,4 @@
-import { type ToolDefinition } from '../../../tools/defineTool.js';
+import type { ToolDefinition } from '../../../tools/defineTool.js';
 export declare const agentSearchTool: ToolDefinition;
 export declare const agentGetTool: ToolDefinition;
 export declare const DISCOVERY_TOOLS: ToolDefinition[];

package/dist/server/tools/tier2/discoveryTools.js

@@ -1,25 +1,8 @@
-import { defineTool } from '../../../tools/defineTool.js';
-import { AgentSearchClient } from '@ziggs-ai/api-client';
-function clientFor(ctx) {
-    const operatorKey = ctx?.['operatorKey'];
-    const agentId = ctx?.['agentId'];
-    if (!operatorKey)
-        throw new Error('operatorKey missing from tool context');
-    if (!agentId)
-        throw new Error('agentId missing from tool context');
-    return new AgentSearchClient(operatorKey, agentId);
-}
-export const agentSearchTool = defineTool('agent_search', { query: { type: 'string', required: true }, limit: 'number' }, async (args, ctx) => {
-    if (!args['query'])
-        throw new Error('query is required');
-    const options = {};
-    if (typeof args['limit'] === 'number')
-        options.limit = args['limit'];
-    return clientFor(ctx).searchAgents(args['query'], options);
-}, { description: 'Search for agents by capability, name, or description. Returns ranked results with relevance scores. Use before agreement_propose or agreement_subcontract to discover the right agent for a job.', isGenericFallback: true });
-export const agentGetTool = defineTool('agent_get', { agentId: { type: 'string', required: true } }, async (args, ctx) => {
-    if (!args['agentId'])
-        throw new Error('agentId is required');
-    return clientFor(ctx).getAgentById(args['agentId']);
-}, { description: 'Fetch the full profile of a specific agent by ID. Use to confirm capabilities and terms before proposing an agreement.' });
+import { agentSearchCapability, agentGetCapability } from '@ziggs-ai/api-client';
+import { toolFromCapability } from '../../../tools/capabilityAdapter.js';
+// ZIG-956 — agent discovery is a shared capability definition (api-client),
+// so search shaping (ZIG-664 zero-hit hint, reachability rows) is identical
+// on both surfaces.
+export const agentSearchTool = toolFromCapability(agentSearchCapability);
+export const agentGetTool = toolFromCapability(agentGetCapability);
 export const DISCOVERY_TOOLS = [agentSearchTool, agentGetTool];

package/dist/server/tools/tier2/grantsTools.d.ts

@@ -1,3 +1,3 @@
-import { type ToolDefinition } from '../../../tools/defineTool.js';
+import type { ToolDefinition } from '../../../tools/defineTool.js';
 export declare const listGrantsTool: ToolDefinition;
 export declare const GRANTS_TOOLS: ToolDefinition[];

package/dist/server/tools/tier2/grantsTools.js

@@ -1,81 +1,6 @@
-import { defineTool } from '../../../tools/defineTool.js';
-import { GrantsClient, unreadableGrantRails, } from '@ziggs-ai/api-client';
-/**
- * ZIG-893 — the single "what authority do I hold?" tool. One name, every rail
- * (context chat/agreement/org, connection, wallet), holder-scoped, cross-session.
- * Wraps the unified `GET /grants` (GrantsClient) that already replaced the three
- * per-rail listers server-side; this lifts that unification up to the tool layer
- * so an agent no longer has to know three tool names — or, as in the 2026-07-20
- * incident, tell its principal grant lookup doesn't exist because its config
- * happened to omit the one rail's lister.
- */
-function creds(ctx) {
-    const operatorKey = ctx?.['operatorKey'];
-    const agentId = ctx?.['agentId'];
-    if (!operatorKey)
-        throw new Error('operatorKey missing from tool context');
-    if (!agentId)
-        throw new Error('agentId missing from tool context');
-    return { operatorKey, agentId };
-}
-const SCOPE_KINDS = [
-    'chat',
-    'agreement',
-    'org',
-    'connection',
-    'wallet',
-];
-const HEALTHS = ['active', 'expired', 'revoked'];
-function parseScopeKinds(raw) {
-    if (raw == null)
-        return undefined;
-    const list = Array.isArray(raw) ? raw : [raw];
-    const out = [];
-    for (const r of list) {
-        if (!SCOPE_KINDS.includes(r)) {
-            throw new Error(`scopeKind must be one of ${SCOPE_KINDS.join(', ')}`);
-        }
-        if (!out.includes(r))
-            out.push(r);
-    }
-    return out.length ? out : undefined;
-}
-export const listGrantsTool = defineTool('list_grants', {
-    scopeKind: {
-        type: 'array',
-        items: { type: 'string', enum: [...SCOPE_KINDS] },
-        description: 'Rail filter (repeatable): chat | agreement | org (context) | connection | wallet. Omit for every rail you can read.',
-    },
-    health: {
-        type: 'string',
-        enum: [...HEALTHS],
-        description: 'Grant health filter. Defaults to active (live grants only).',
-    },
-    cursor: { type: 'string', description: 'Opaque cursor from a prior nextCursor to page' },
-    limit: { type: 'number', description: 'Page size (server default when omitted)' },
-}, async (args, ctx) => {
-    const { operatorKey, agentId } = creds(ctx);
-    const scopeKind = parseScopeKinds(args['scopeKind']);
-    const healthArg = args['health'];
-    if (healthArg !== undefined && !HEALTHS.includes(healthArg)) {
-        throw new Error(`health must be one of ${HEALTHS.join(', ')}`);
-    }
-    const { items, nextCursor } = await new GrantsClient(operatorKey, agentId).listGrants({
-        scopeKind,
-        // Reach = live grants only by default; pass health to see expired/revoked.
-        health: healthArg ?? 'active',
-        cursor: args['cursor'],
-        limit: typeof args['limit'] === 'number' ? args['limit'] : undefined,
-    });
-    const unreadable = unreadableGrantRails(operatorKey, scopeKind);
-    return {
-        count: items.length,
-        grants: items,
-        nextCursor,
-        ...(unreadable && unreadable.length ? { unreadableRails: unreadable } : {}),
-    };
-}, {
-    description: 'List every grant this agent holds across all rails in one call — context (chat/agreement/org), connection, and wallet — as canonical grants (grantId, scope, caveats, expiresAt, health; no message/artifact 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. Pair with context_read to read through a context grant, or context_expand_reach to enumerate a scope.',
-    isGenericFallback: true,
-});
-export const GRANTS_TOOLS = [listGrantsTool];
+import { GRANTS_CAPABILITIES, listGrantsCapability } from '@ziggs-ai/api-client';
+import { toolFromCapability, toolsFromCapabilities } from '../../../tools/capabilityAdapter.js';
+// ZIG-893 / ZIG-956 — the single "what authority do I hold?" tool, defined
+// once in api-client's shared capability layer.
+export const listGrantsTool = toolFromCapability(listGrantsCapability);
+export const GRANTS_TOOLS = toolsFromCapabilities(GRANTS_CAPABILITIES);

package/dist/server/tools/tier2/linkTools.d.ts

@@ -1,4 +1,4 @@
-import { type ToolDefinition } from '../../../tools/defineTool.js';
+import type { ToolDefinition } from '../../../tools/defineTool.js';
 export declare const requestLinkTool: ToolDefinition;
 export declare const createLinkInviteTool: ToolDefinition;
 export declare const claimLinkInviteTool: ToolDefinition;

package/dist/server/tools/tier2/linkTools.js

@@ -1,156 +1,12 @@
-import { defineTool } from '../../../tools/defineTool.js';
-import { createAgreement, claimAgreement, listAgreements, revokeAgreement, } from '@ziggs-ai/api-client';
-/**
- * ZIG-898 — link tools on the SDK surface, same base names as ziggs-mcp's
- * trustTools (ziggs_request_link → request_link, …). Links are agreements with
- * engagementKind 'link' — bilateral agent-to-agent trust that gives unpublished
- * delegates cross-org reach. No new endpoints: everything rides the agreements
- * rail exactly as the MCP tools do.
- *
- * A link is reach-only: it lets the peers find and message each other, never
- * read context — grants stay separate (context_delegate / the owner's grant
- * tools).
- */
-function creds(ctx) {
-    const operatorKey = ctx?.['operatorKey'];
-    const agentId = ctx?.['agentId'];
-    if (!operatorKey)
-        throw new Error('operatorKey missing from tool context');
-    if (!agentId)
-        throw new Error('agentId missing from tool context');
-    return { operatorKey, agentId };
-}
-function webAppOrigin() {
-    return (process.env.ZIGGS_WEB_URL?.trim() || 'https://ziggsai.com').replace(/\/$/, '');
-}
-/**
- * ZIG-670 rule carried over from the MCP tools: link-shaped summaries, not raw
- * agreement documents — the money block, approvals array, and Mongo internals
- * are noise on a trust relationship.
- */
-function linkSummary(a) {
-    return {
-        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 LINK_IS_REACH_ONLY = 'A link is reach-only: it does not grant context. Share a slice of a grant you hold with context_delegate, or ask the peer owner to issue one, before reading.';
-export const requestLinkTool = defineTool('request_link', {
-    providerId: {
-        type: 'string',
-        required: true,
-        description: 'Bare agent id to link with (the target delegate). Use agent_search or a known delegate id — do not guess.',
-    },
-    message: {
-        type: 'string',
-        description: 'Optional note shown to the counterparty human on approval (agreement description)',
-    },
-}, async (args, ctx) => {
-    const { agreement } = await createAgreement({
-        engagementKind: 'link',
-        providerId: args['providerId'],
-        description: args['message'],
-    }, creds(ctx));
-    return {
-        status: 'pending',
-        message: 'Link agreement created — the counterparty owner must approve (agreement_respond on their side) before cross-org reach. Surface pending state to your principal.',
-        agreement: linkSummary(agreement),
-    };
-}, {
-    description: 'Request a bilateral trust link with another agent before cross-org reach (party-to-party, NOT a third-party service connection — that is the connection rail). A link is just an agreement (engagementKind "link"). The target OWNER must approve it before unpublished delegates can message each other.',
-    isAgreementCreation: true,
-});
-export const createLinkInviteTool = defineTool('create_link_invite', {
-    message: {
-        type: 'string',
-        description: 'Optional note shown to whoever opens the invite (agreement description)',
-    },
-}, async (args, ctx) => {
-    const { agreement } = await createAgreement({ engagementKind: 'link', description: args['message'] }, creds(ctx));
-    return {
-        status: 'open',
-        inviteId: agreement.agreementId,
-        claimUrl: `${webAppOrigin()}/app/link-invites/${agreement.agreementId}`,
-        message: 'Open link invite created. Share claimUrl (or the inviteId) with the counterparty — they claim it in the Ziggs web app or via their claim_link_invite tool. No agent id needed on either side. Revoke with revoke_link to disable.',
-        agreement: linkSummary(agreement),
-    };
-}, {
-    description: "Create a shareable OPEN link invite (bilateral agent-to-agent trust) when you do NOT have the counterparty's agent id (e.g. connecting across orgs). Creates an open link agreement proposed to everyone; the recipient forms the link by claiming the returned inviteId.",
-    isAgreementCreation: true,
-});
-export const claimLinkInviteTool = defineTool('claim_link_invite', {
-    agreementId: {
-        type: 'string',
-        required: true,
-        description: 'The invite id (agreementId) shared by the issuer',
-    },
-}, async (args, ctx) => {
-    const { agreement } = await claimAgreement(args['agreementId'], creds(ctx));
-    return {
-        status: 'linked',
-        message: `Link invite claimed — you are now linked. ${LINK_IS_REACH_ONLY}`,
-        agreement: linkSummary(agreement),
-    };
-}, {
-    description: 'Claim an open link invite by its id to form a bilateral link. You become the counterparty and the link activates immediately (cross-org reach). You cannot claim your own invite.',
-});
-export const listLinksTool = defineTool('list_links', {
-    status: {
-        type: 'string',
-        enum: ['active', 'open', 'cancelled', 'all'],
-        description: 'active (default) = established links; open = pending proposals/invites awaiting approval or claim; cancelled = revoked; all = every link regardless of status',
-    },
-}, async (args, ctx) => {
-    const status = args['status'] ?? 'active';
-    if (!['active', 'open', 'cancelled', 'all'].includes(status)) {
-        throw new Error('status must be one of active, open, cancelled, all');
-    }
-    const links = await listAgreements({
-        engagementKind: 'link',
-        ...(status === 'all' ? {} : { status }),
-    }, creds(ctx));
-    const summaries = links.map(linkSummary);
-    const hasActive = links.some((a) => a.status === 'active');
-    return {
-        count: summaries.length,
-        status,
-        links: summaries,
-        ...(hasActive ? { nextSteps: LINK_IS_REACH_ONLY } : {}),
-    };
-}, {
-    description: 'List link agreements for this agent — bilateral agent-to-agent trust relationships (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.',
-    isGenericFallback: true,
-});
-export const revokeLinkTool = defineTool('revoke_link', {
-    agreementId: {
-        type: 'string',
-        required: true,
-        description: 'agreementId of the link agreement (from list_links)',
-    },
-}, async (args, ctx) => {
-    const result = await revokeAgreement(args['agreementId'], creds(ctx));
-    return {
-        status: 'revoked',
-        message: 'Link revoked — unpublished cross-org reach to this peer is blocked again.',
-        agreementId: args['agreementId'],
-        agreement: result.agreement ? linkSummary(result.agreement) : null,
-    };
-}, {
-    description: 'Revoke a bilateral link agreement (DELETE /agreements/:agreementId). Either party may revoke; cross-org reach ends immediately. For non-link agreements (hire/service/quest), use agreement_revoke — same endpoint, different messaging.',
-});
-export const LINK_TOOLS = [
-    requestLinkTool,
-    createLinkInviteTool,
-    claimLinkInviteTool,
-    listLinksTool,
-    revokeLinkTool,
-];
+import { LINK_CAPABILITIES, requestLinkCapability, createLinkInviteCapability, claimLinkInviteCapability, listLinksCapability, revokeLinkCapability, } from '@ziggs-ai/api-client';
+import { toolFromCapability, toolsFromCapabilities } from '../../../tools/capabilityAdapter.js';
+// ZIG-898 / ZIG-956 — links are agreements with engagementKind 'link':
+// bilateral agent-to-agent trust that gives unpublished delegates cross-org
+// reach. Defined once in api-client's shared capability layer (including the
+// ZIG-670 linkSummary shaping); this file only adapts them onto the SDK.
+export const requestLinkTool = toolFromCapability(requestLinkCapability);
+export const createLinkInviteTool = toolFromCapability(createLinkInviteCapability);
+export const claimLinkInviteTool = toolFromCapability(claimLinkInviteCapability);
+export const listLinksTool = toolFromCapability(listLinksCapability);
+export const revokeLinkTool = toolFromCapability(revokeLinkCapability);
+export const LINK_TOOLS = toolsFromCapabilities(LINK_CAPABILITIES);

package/dist/server/tools/tier2/paymentTools.d.ts

@@ -1,10 +1,10 @@
-import { type ToolDefinition } from '../../../tools/defineTool.js';
+import type { ToolDefinition } from '../../../tools/defineTool.js';
 export declare const paymentBalanceTool: ToolDefinition;
 export declare const paymentTransferTool: ToolDefinition;
 export declare const paymentWaitForApprovalTool: ToolDefinition;
-export declare const paymentResolveWalletTool: ToolDefinition;
 export declare const paymentHoldTool: ToolDefinition;
 export declare const paymentReleaseTool: ToolDefinition;
+export declare const paymentResolveWalletTool: ToolDefinition;
 export declare const paymentIssueGrantTool: ToolDefinition;
 export declare const paymentAttenuateGrantTool: ToolDefinition;
 export declare const paymentRevokeGrantTool: ToolDefinition;

package/dist/server/tools/tier2/paymentTools.js

@@ -1,161 +1,16 @@
-import { defineTool } from '../../../tools/defineTool.js';
-import { PaymentsClient } from '@ziggs-ai/api-client';
-function clientFor(ctx) {
-    const operatorKey = ctx?.['operatorKey'];
-    if (!operatorKey)
-        throw new Error('operatorKey missing from tool context');
-    // BACKEND_URL / ZIGGS_BACKEND_URL are the SDK runner's overrides; the shared
-    // client defaults to HTTP_URL (api-client convention) when neither is set.
-    const baseUrl = process.env.BACKEND_URL || process.env.ZIGGS_BACKEND_URL || undefined;
-    return new PaymentsClient(operatorKey, ctx?.['agentId'] || undefined, baseUrl);
-}
-function rethrowWithContext(error, prefix) {
-    const e = error;
-    const wrapped = new Error(`${prefix}: ${e.message}`);
-    if (e.status !== undefined)
-        wrapped.status = e.status;
-    if (e.body !== undefined)
-        wrapped.body = e.body;
-    wrapped['cause'] = error;
-    throw wrapped;
-}
-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;
-}
-export const paymentBalanceTool = defineTool('payment_balance', {}, async (_args, ctx) => {
-    try {
-        return await clientFor(ctx).balance();
-    }
-    catch (e) {
-        rethrowWithContext(e, 'Failed to get balance');
-    }
-}, { description: "Check the caller's current wallet balance and available balance (total minus active holds). Use before a transfer to confirm sufficient funds." });
-export const paymentTransferTool = defineTool('payment_transfer', { toWalletId: { type: 'string', required: true }, amount: { type: 'number', required: true }, description: 'string', idempotencyKey: 'string', paymentGrantId: 'string' }, async (args, ctx) => {
-    if (!args['toWalletId'])
-        throw new Error('toWalletId is required');
-    if (!args['amount'] || args['amount'] <= 0)
-        throw new Error('amount must be positive');
-    const client = clientFor(ctx);
-    let result;
-    try {
-        result = await client.transfer({ to: args['toWalletId'], amount: Math.round(args['amount']), description: args['description'] || 'Agent-initiated transfer', idempotencyKey: args['idempotencyKey'], paymentGrantId: args['paymentGrantId'] });
-    }
-    catch (e) {
-        rethrowWithContext(e, 'Transfer failed');
-    }
-    if (result['status'] === 'approval_required') {
-        return { status: 'approval_required', approvalId: result['approvalId'] || null, expiresAt: result['expiresAt'] || null, reason: result['reason'] || null, amount: args['amount'], toWalletId: result['toWalletId'],
-            message: 'Transfer paused: the wallet owner must approve this amount.',
-            next_actions: [{ tool: 'payment_wait_for_approval', when: 'You expect a quick decision (≤2 min) and can wait inline.', args: { approvalId: result['approvalId'], timeoutMs: 120000 } }, { tool: 'task_update_plan_step', when: 'You want to abandon the transfer and route around it.' }] };
-    }
-    return { status: 'transferred', transactionId: result['transactionId'] || null, amount: args['amount'], toWalletId: result['toWalletId'] };
-});
-export const paymentWaitForApprovalTool = defineTool('payment_wait_for_approval', { approvalId: { type: 'string', required: true }, timeoutMs: 'number', pollMs: 'number' }, async (args, ctx) => {
-    if (!args['approvalId'])
-        throw new Error('approvalId is required');
-    try {
-        const result = await clientFor(ctx).waitForApproval(args['approvalId'], { timeoutMs: args['timeoutMs'], pollMs: args['pollMs'] });
-        return { status: result['status'], approvalId: args['approvalId'], transactionId: result['transactionId'] || null, approval: result['approval'] || null };
-    }
-    catch (e) {
-        rethrowWithContext(e, 'wait_for_approval failed');
-    }
-});
-export const paymentResolveWalletTool = defineTool('payment_resolve_wallet', { userId: 'string', agentId: 'string' }, async (args, ctx) => {
-    if (!args['userId'] && !args['agentId'])
-        throw new Error('Provide userId or agentId to resolve a wallet');
-    try {
-        const wallet = await clientFor(ctx).resolve({ userId: args['userId'], agentId: args['agentId'] });
-        return { walletId: wallet?.['walletId'] || null, ownerId: wallet?.['ownerId'] || null, currency: wallet?.['currency'] || 'pez', status: wallet?.['status'] || null };
-    }
-    catch (e) {
-        rethrowWithContext(e, 'Failed to resolve wallet');
-    }
-}, { description: 'Look up a walletId by userId or agentId. Use before a transfer when you only know the recipient by their platform ID.' });
-export const paymentHoldTool = defineTool('payment_hold', { amount: { type: 'number', required: true }, description: 'string', idempotencyKey: 'string' }, async (args, ctx) => {
-    if (!args['amount'] || args['amount'] <= 0)
-        throw new Error('amount must be positive');
-    try {
-        const result = await clientFor(ctx).hold({ amount: Math.round(args['amount']), description: args['description'] || 'Agent escrow hold', idempotencyKey: args['idempotencyKey'] });
-        return { status: 'held', transactionId: result['transaction']?.['transactionId'] || null, amount: args['amount'] };
-    }
-    catch (e) {
-        rethrowWithContext(e, 'Hold failed');
-    }
-}, { description: 'Pre-authorize (escrow) funds without moving them. Use to reserve payment at agreement formation; release with payment_release once work is complete or to refund if work is cancelled.' });
-export const paymentReleaseTool = defineTool('payment_release', { holdId: { type: 'string', required: true }, action: { type: 'string', required: true }, toWalletId: 'string', idempotencyKey: 'string' }, async (args, ctx) => {
-    if (!args['holdId'])
-        throw new Error('holdId is required');
-    if (args['action'] !== 'complete' && args['action'] !== 'refund')
-        throw new Error("action must be 'complete' or 'refund'");
-    if (args['action'] === 'complete' && !args['toWalletId'])
-        throw new Error('toWalletId is required when action=complete');
-    try {
-        const result = await clientFor(ctx).release({ holdId: args['holdId'], action: args['action'], toWalletId: args['toWalletId'], idempotencyKey: args['idempotencyKey'] });
-        return { status: args['action'] === 'complete' ? 'settled' : 'refunded', transactionId: result['transaction']?.['transactionId'] || null, holdId: args['holdId'], action: args['action'] };
-    }
-    catch (e) {
-        rethrowWithContext(e, 'Release failed');
-    }
-}, { description: "Settle or refund an escrow hold. Use action='complete' to transfer held funds to toWalletId (work done), or action='refund' to return funds to the sender (work cancelled)." });
-const issueGrantHandler = async (args, ctx) => {
-    if (!args['holderId'])
-        throw new Error('holderId is required');
-    try {
-        const caveats = buildCaveats(args);
-        const result = await clientFor(ctx).issueGrant({ holderId: args['holderId'], caveats });
-        const grant = result['grant'];
-        return { grantId: grant?.['grantId'] || null, holderId: grant?.['holderId'] || args['holderId'], caveats: grant?.['caveats'] || caveats, expiresAt: grant?.['expiresAt'] || null };
-    }
-    catch (e) {
-        rethrowWithContext(e, 'Failed to issue payment grant');
-    }
-};
-export const paymentIssueGrantTool = defineTool('payment_issue_grant', { holderId: { type: 'string', required: true }, maxAmount: 'number', dailyBudget: 'number', allowedRecipients: ['string'], expiresInSeconds: 'number' }, issueGrantHandler);
-const attenuateGrantHandler = async (args, ctx) => {
-    const grantId = args['grantId'];
-    if (!grantId)
-        throw new Error('grantId is required');
-    if (!args['holderId'])
-        throw new Error('holderId is required');
-    try {
-        const caveats = buildCaveats(args);
-        const result = await clientFor(ctx).attenuateGrant({ grantId, holderId: args['holderId'], caveats });
-        const grant = result['grant'];
-        return { grantId: grant?.['grantId'] || null, parentGrantId: grant?.['parentGrantId'] || grantId, holderId: grant?.['holderId'] || args['holderId'], caveats: grant?.['caveats'] || caveats, expiresAt: grant?.['expiresAt'] || null };
-    }
-    catch (e) {
-        rethrowWithContext(e, 'Failed to attenuate payment grant');
-    }
-};
-export const paymentAttenuateGrantTool = defineTool('payment_attenuate_grant', { grantId: { type: 'string', required: true }, holderId: { type: 'string', required: true }, maxAmount: 'number', dailyBudget: 'number', allowedRecipients: ['string'], expiresInSeconds: 'number' }, attenuateGrantHandler);
-const revokeGrantHandler = async (args, ctx) => {
-    const grantId = args['grantId'];
-    if (!grantId)
-        throw new Error('grantId is required');
-    try {
-        const result = await clientFor(ctx).revokeGrant(grantId);
-        return { status: 'revoked', grantId, revoked: result['revoked'] ?? null };
-    }
-    catch (e) {
-        rethrowWithContext(e, 'Failed to revoke payment grant');
-    }
-};
-export const paymentRevokeGrantTool = defineTool('payment_revoke_grant', { grantId: { type: 'string', required: true } }, revokeGrantHandler);
-// ZIG-893 — payment_list_grants retired; the wallet rail is now part of the
-// unified list_grants tool (scopeKind: 'wallet'). Grant *mutations* stay on the
-// payment rail (issue/attenuate/revoke below).
-export const PAYMENT_TOOLS = [
-    paymentBalanceTool, paymentTransferTool, paymentWaitForApprovalTool,
-    paymentHoldTool, paymentReleaseTool, paymentResolveWalletTool,
-    paymentIssueGrantTool, paymentAttenuateGrantTool, paymentRevokeGrantTool,
-];
+import { PAYMENT_CAPABILITIES, paymentBalanceCapability, paymentTransferCapability, paymentWaitForApprovalCapability, paymentHoldCapability, paymentReleaseCapability, paymentResolveWalletCapability, paymentIssueGrantCapability, paymentAttenuateGrantCapability, paymentRevokeGrantCapability, } from '@ziggs-ai/api-client';
+import { toolFromCapability, toolsFromCapabilities } from '../../../tools/capabilityAdapter.js';
+// ZIG-956 — the wallet toolset is defined once in api-client's shared
+// capability layer; this file only adapts it onto the SDK surface. Safety is
+// unchanged: money-moving calls stay policy-gated server-side, and there is
+// deliberately NO approve/decide tool on the agent surface.
+export const paymentBalanceTool = toolFromCapability(paymentBalanceCapability);
+export const paymentTransferTool = toolFromCapability(paymentTransferCapability);
+export const paymentWaitForApprovalTool = toolFromCapability(paymentWaitForApprovalCapability);
+export const paymentHoldTool = toolFromCapability(paymentHoldCapability);
+export const paymentReleaseTool = toolFromCapability(paymentReleaseCapability);
+export const paymentResolveWalletTool = toolFromCapability(paymentResolveWalletCapability);
+export const paymentIssueGrantTool = toolFromCapability(paymentIssueGrantCapability);
+export const paymentAttenuateGrantTool = toolFromCapability(paymentAttenuateGrantCapability);
+export const paymentRevokeGrantTool = toolFromCapability(paymentRevokeGrantCapability);
+export const PAYMENT_TOOLS = toolsFromCapabilities(PAYMENT_CAPABILITIES);

package/dist/tools/capabilityAdapter.d.ts

@@ -0,0 +1,11 @@
+import { type ToolDefinition } from './defineTool.js';
+import type { CapabilityDefinition } from '@ziggs-ai/api-client';
+/**
+ * ZIG-956 — the SDK surface adapter for shared capability definitions
+ * (api-client `capabilities/`). One capability (schema + handler + guidance)
+ * becomes a defineTool ToolDefinition: the neutral param DSL feeds defineTool's
+ * JSON-schema converter unchanged, and the handler runs with creds pulled from
+ * tool context plus the SDK runner's base-URL overrides.
+ */
+export declare function toolFromCapability(cap: CapabilityDefinition): ToolDefinition;
+export declare function toolsFromCapabilities(caps: CapabilityDefinition[]): ToolDefinition[];

package/dist/tools/capabilityAdapter.js

@@ -0,0 +1,30 @@
+import { defineTool } from './defineTool.js';
+/**
+ * ZIG-956 — the SDK surface adapter for shared capability definitions
+ * (api-client `capabilities/`). One capability (schema + handler + guidance)
+ * becomes a defineTool ToolDefinition: the neutral param DSL feeds defineTool's
+ * JSON-schema converter unchanged, and the handler runs with creds pulled from
+ * tool context plus the SDK runner's base-URL overrides.
+ */
+export function toolFromCapability(cap) {
+    return defineTool(cap.names.sdk, cap.params, async (args, ctx) => {
+        const operatorKey = ctx?.['operatorKey'];
+        const agentId = ctx?.['agentId'];
+        if (!operatorKey)
+            throw new Error('operatorKey missing from tool context');
+        if (cap.needsAgentId && !agentId)
+            throw new Error('agentId missing from tool context');
+        const env = {
+            creds: { operatorKey, ...(agentId ? { agentId } : {}) },
+            // BACKEND_URL / ZIGGS_BACKEND_URL are the SDK runner's overrides; the
+            // shared clients default to HTTP_URL (api-client convention) otherwise.
+            baseUrl: process.env.BACKEND_URL || process.env.ZIGGS_BACKEND_URL || undefined,
+            webUrl: process.env.ZIGGS_WEB_URL,
+            surface: 'sdk',
+        };
+        return cap.handler(args, env);
+    }, { description: cap.descriptions.sdk, ...(cap.sdkOptions ?? {}) });
+}
+export function toolsFromCapabilities(caps) {
+    return caps.map(toolFromCapability);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/agent-sdk",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Agent framework SDK for building autonomous agents on the Ziggs platform",
   "type": "module",
   "main": "dist/index.js",
@@ -26,7 +26,7 @@
     "@anthropic-ai/claude-agent-sdk": "^0.3.204",
     "@anthropic-ai/sdk": "^0.110.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@ziggs-ai/api-client": "^0.3.0",
+    "@ziggs-ai/api-client": "^0.4.0",
     "ajv": "^8.17.1",
     "dotenv": "^17.2.3",
     "openai": "^4.0.0",