@ziggs-ai/api-client 0.3.0 → 0.4.0

package/dist/capabilities/payments.js

@@ -0,0 +1,404 @@
+import { PaymentsClient } from '../http/PaymentsClient.js';
+import { rethrowWithContext, } from './types.js';
+function client(env) {
+    const { operatorKey, agentId } = env.creds;
+    if (!operatorKey)
+        throw new Error('operatorKey missing from tool context');
+    return new PaymentsClient(operatorKey, agentId, env.baseUrl);
+}
+/** Lower the optional caveat args to the wire's caveat list (was written twice). */
+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;
+}
+const grantCaveatParams = {
+    maxAmount: { type: 'number', description: 'Per-transfer ceiling in cents' },
+    dailyBudget: { type: 'number', description: 'Rolling daily budget in cents' },
+    allowedRecipients: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Wallet ids the holder may pay',
+    },
+    expiresInSeconds: { type: 'number', description: 'Grant lifetime from now' },
+};
+export const paymentBalanceCapability = {
+    key: 'payment_balance',
+    names: { sdk: 'payment_balance', mcp: 'ziggs_payment_balance' },
+    descriptions: {
+        sdk: "Check the caller's current wallet balance and available balance (total minus active holds). Use before a transfer to confirm sufficient funds.",
+        mcp: "Check the caller's current wallet balance and available balance (total minus active holds). Use before a transfer to confirm sufficient funds.",
+    },
+    annotation: 'read-only',
+    params: {},
+    handler: async (_args, env) => {
+        try {
+            return await client(env).balance();
+        }
+        catch (e) {
+            rethrowWithContext(e, 'Failed to get balance');
+        }
+    },
+};
+export const paymentResolveWalletCapability = {
+    key: 'payment_resolve_wallet',
+    names: { sdk: 'payment_resolve_wallet', mcp: 'ziggs_payment_resolve_wallet' },
+    descriptions: {
+        sdk: 'Look up a walletId by userId or agentId. Use before a transfer when you only know the recipient by their platform ID.',
+        mcp: 'Look up a walletId by userId or agentId. Use before a transfer when you only know the recipient by their platform ID.',
+    },
+    annotation: 'read-only',
+    params: {
+        userId: { type: 'string', description: 'User to resolve' },
+        agentId: { type: 'string', description: 'Agent to resolve' },
+    },
+    handler: async (args, env) => {
+        if (!args['userId'] && !args['agentId'])
+            throw new Error('Provide userId or agentId to resolve a wallet');
+        try {
+            const wallet = await client(env).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');
+        }
+    },
+};
+export const paymentTransferCapability = {
+    key: 'payment_transfer',
+    names: { sdk: 'payment_transfer', mcp: 'ziggs_payment_transfer' },
+    descriptions: {
+        sdk: 'Transfer funds to another wallet. Amounts are integer cents. Transfers above the wallet owner\'s policy pause with status "approval_required" — wait inline with payment_wait_for_approval when you expect a quick decision.',
+        mcp: 'Transfer funds to another wallet. Amounts are integer cents. As a delegate you spend under a payment grant the wallet owner issued (paymentGrantId — find yours via ziggs_list_grants scopeKind=wallet). Transfers above the owner\'s policy pause with status "approval_required": the human approves on the wallet page (it also shows in ziggs_pending_decisions) — you can wait inline with ziggs_payment_wait_for_approval, and you must NEVER approve your own transfer.',
+    },
+    annotation: 'write',
+    params: {
+        toWalletId: {
+            type: 'string',
+            required: true,
+            description: 'Destination wal_... id — or a userId/agentId to auto-resolve',
+        },
+        amount: { type: 'number', required: true, description: 'Amount in integer cents, > 0' },
+        description: { type: 'string', description: 'Human-readable transfer memo' },
+        idempotencyKey: {
+            type: 'string',
+            description: 'Client-supplied key to make retries safe (auto-generated when omitted)',
+        },
+        paymentGrantId: {
+            type: 'string',
+            description: 'Payment grant to spend under (required for agent-impersonated transfers)',
+        },
+    },
+    handler: async (args, env) => {
+        if (!args['toWalletId'])
+            throw new Error('toWalletId is required');
+        const amount = args['amount'];
+        if (!amount || amount <= 0)
+            throw new Error('amount must be positive');
+        let result;
+        try {
+            result = await client(env).transfer({
+                to: args['toWalletId'],
+                amount: Math.round(amount),
+                description: args['description'] || 'Agent-initiated transfer',
+                idempotencyKey: args['idempotencyKey'],
+                paymentGrantId: args['paymentGrantId'],
+            });
+        }
+        catch (e) {
+            rethrowWithContext(e, 'Transfer failed');
+        }
+        if (result.status === 'approval_required') {
+            const base = {
+                status: 'approval_required',
+                approvalId: result.approvalId,
+                expiresAt: result.expiresAt,
+                reason: result.reason,
+                amount,
+                toWalletId: result.toWalletId,
+            };
+            // Same pause, surface-local guidance: the MCP delegate must surface the
+            // pending approval to the human (pull-only MCP has no push); the SDK
+            // runtime routes via structured next_actions.
+            if (env.surface === 'mcp') {
+                return {
+                    ...base,
+                    note: 'Transfer paused: the wallet owner must approve this amount on the wallet page (also listed by ziggs_pending_decisions). Tell the human now (pull-only MCP has no push). ' +
+                        'Wait inline with ziggs_payment_wait_for_approval when you expect a quick decision (≤2 min).',
+                };
+            }
+            return {
+                ...base,
+                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,
+            amount,
+            toWalletId: result.toWalletId,
+        };
+    },
+};
+export const paymentWaitForApprovalCapability = {
+    key: 'payment_wait_for_approval',
+    names: { sdk: 'payment_wait_for_approval', mcp: 'ziggs_payment_wait_for_approval' },
+    descriptions: {
+        sdk: 'Poll a paused transfer (status "approval_required") until the human decides or the timeout passes. Returns executed | rejected | expired | timeout | gone.',
+        mcp: 'Poll a paused transfer (status "approval_required") until the human decides or the timeout passes. Returns executed | rejected | expired | timeout | gone. Use for quick decisions (≤2 min); for longer waits, stop and check again next session.',
+    },
+    annotation: 'read-only',
+    params: {
+        approvalId: {
+            type: 'string',
+            required: true,
+            description: 'Approval to wait on (from the paused transfer)',
+        },
+        timeoutMs: { type: 'number', description: 'Max wait, default 120000' },
+        pollMs: { type: 'number', description: 'Poll interval, default 3000 (min 500)' },
+    },
+    handler: async (args, env) => {
+        if (!args['approvalId'])
+            throw new Error('approvalId is required');
+        try {
+            const result = await client(env).waitForApproval(args['approvalId'], {
+                timeoutMs: args['timeoutMs'],
+                pollMs: args['pollMs'],
+            });
+            const loose = result;
+            return {
+                status: result.status,
+                approvalId: args['approvalId'],
+                transactionId: loose['transactionId'] || null,
+                approval: loose['approval'] || null,
+            };
+        }
+        catch (e) {
+            rethrowWithContext(e, 'wait_for_approval failed');
+        }
+    },
+};
+export const paymentHoldCapability = {
+    key: 'payment_hold',
+    names: { sdk: 'payment_hold', mcp: 'ziggs_payment_hold' },
+    descriptions: {
+        sdk: '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.',
+        mcp: "Pre-authorize (escrow) funds without moving them. Use to reserve payment at agreement formation; release with ziggs_payment_release once work is complete, or refund if it's cancelled.",
+    },
+    annotation: 'write',
+    params: {
+        amount: { type: 'number', required: true, description: 'Amount in integer cents, > 0' },
+        description: { type: 'string', description: 'Human-readable hold memo' },
+        idempotencyKey: { type: 'string', description: 'Client-supplied retry-safety key' },
+    },
+    handler: async (args, env) => {
+        const amount = args['amount'];
+        if (!amount || amount <= 0)
+            throw new Error('amount must be positive');
+        try {
+            const result = await client(env).hold({
+                amount: Math.round(amount),
+                description: args['description'] || 'Agent escrow hold',
+                idempotencyKey: args['idempotencyKey'],
+            });
+            return {
+                status: 'held',
+                transactionId: result.transaction?.transactionId || null,
+                amount,
+            };
+        }
+        catch (e) {
+            rethrowWithContext(e, 'Hold failed');
+        }
+    },
+};
+export const paymentReleaseCapability = {
+    key: 'payment_release',
+    names: { sdk: 'payment_release', mcp: 'ziggs_payment_release' },
+    descriptions: {
+        sdk: "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).",
+        mcp: "Settle or refund an escrow hold. action='complete' transfers held funds to toWalletId (work done); action='refund' returns funds to the sender (work cancelled).",
+    },
+    annotation: 'write',
+    params: {
+        holdId: {
+            type: 'string',
+            required: true,
+            description: 'Hold to settle (transactionId from the hold)',
+        },
+        action: {
+            type: 'string',
+            required: true,
+            enum: ['complete', 'refund'],
+            description: 'complete = pay out, refund = return',
+        },
+        toWalletId: { type: 'string', description: 'Destination wallet — required when action=complete' },
+        idempotencyKey: { type: 'string', description: 'Client-supplied retry-safety key' },
+    },
+    handler: async (args, env) => {
+        if (!args['holdId'])
+            throw new Error('holdId is required');
+        const action = args['action'];
+        if (action !== 'complete' && action !== 'refund')
+            throw new Error("action must be 'complete' or 'refund'");
+        if (action === 'complete' && !args['toWalletId'])
+            throw new Error('toWalletId is required when action=complete');
+        try {
+            const result = await client(env).release({
+                holdId: args['holdId'],
+                action,
+                toWalletId: args['toWalletId'],
+                idempotencyKey: args['idempotencyKey'],
+            });
+            return {
+                status: action === 'complete' ? 'settled' : 'refunded',
+                transactionId: result.transaction?.transactionId || null,
+                holdId: args['holdId'],
+                action,
+            };
+        }
+        catch (e) {
+            rethrowWithContext(e, 'Release failed');
+        }
+    },
+};
+export const paymentIssueGrantCapability = {
+    key: 'payment_issue_grant',
+    names: { sdk: 'payment_issue_grant', mcp: 'ziggs_payment_issue_grant' },
+    descriptions: {
+        sdk: "Issue a payment grant delegating bounded spend from the operator's wallet to an agent holder. Caveats bound what the holder can do (max_amount, daily_budget, allowed_recipients, expiry). The holder spends by passing the grantId as paymentGrantId on transfers.",
+        mcp: "Issue a payment grant delegating bounded spend from the operator's wallet to an agent holder. Caveats bound what the holder can do (max_amount, daily_budget, allowed_recipients, expiry). The holder spends by passing the grantId as paymentGrantId on transfers.",
+    },
+    annotation: 'write',
+    params: {
+        holderId: { type: 'string', required: true, description: 'Agent that will hold the grant' },
+        ...grantCaveatParams,
+    },
+    handler: async (args, env) => {
+        if (!args['holderId'])
+            throw new Error('holderId is required');
+        try {
+            const caveats = buildCaveats(args);
+            const { grant } = await client(env).issueGrant({
+                holderId: args['holderId'],
+                caveats,
+            });
+            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 paymentAttenuateGrantCapability = {
+    key: 'payment_attenuate_grant',
+    names: { sdk: 'payment_attenuate_grant', mcp: 'ziggs_payment_attenuate_grant' },
+    descriptions: {
+        sdk: 'Re-delegate a payment grant you hold to another agent with TIGHTER caveats (narrowing only — the child can never exceed the parent). Use to pass a bounded spend slice to a sub-agent.',
+        mcp: 'Re-delegate a payment grant you hold to another agent with TIGHTER caveats (narrowing only — the child can never exceed the parent). Use to pass a bounded spend slice to a sub-agent.',
+    },
+    annotation: 'write',
+    params: {
+        grantId: { type: 'string', required: true, description: 'Parent grant to attenuate' },
+        holderId: {
+            type: 'string',
+            required: true,
+            description: 'Agent that will hold the narrowed grant',
+        },
+        ...grantCaveatParams,
+    },
+    handler: async (args, env) => {
+        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 { grant } = await client(env).attenuateGrant({
+                grantId,
+                holderId: args['holderId'],
+                caveats,
+            });
+            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 paymentRevokeGrantCapability = {
+    key: 'payment_revoke_grant',
+    names: { sdk: 'payment_revoke_grant', mcp: 'ziggs_payment_revoke_grant' },
+    descriptions: {
+        sdk: 'Revoke a payment grant (and its attenuated children). The holder can no longer spend under it.',
+        mcp: 'Revoke a payment grant (and its attenuated children). The holder can no longer spend under it.',
+    },
+    annotation: 'destructive',
+    params: {
+        grantId: { type: 'string', required: true, description: 'Grant to revoke' },
+    },
+    handler: async (args, env) => {
+        const grantId = args['grantId'];
+        if (!grantId)
+            throw new Error('grantId is required');
+        try {
+            const result = await client(env).revokeGrant(grantId);
+            return { status: 'revoked', grantId, revoked: result?.revoked ?? null };
+        }
+        catch (e) {
+            rethrowWithContext(e, 'Failed to revoke payment grant');
+        }
+    },
+};
+// ZIG-893 — payment_list_grants stays retired; the wallet rail is part of the
+// unified list_grants capability (scopeKind: 'wallet'). Grant *mutations* stay
+// on the payment rail above.
+export const PAYMENT_CAPABILITIES = [
+    paymentBalanceCapability,
+    paymentTransferCapability,
+    paymentWaitForApprovalCapability,
+    paymentHoldCapability,
+    paymentReleaseCapability,
+    paymentResolveWalletCapability,
+    paymentIssueGrantCapability,
+    paymentAttenuateGrantCapability,
+    paymentRevokeGrantCapability,
+];

package/dist/capabilities/types.d.ts

@@ -0,0 +1,88 @@
+/**
+ * ZIG-956 — one shared definition per SDK/MCP tool capability.
+ *
+ * The tool-surface-parity epic (ZIG-893→903) unified the HTTP layer here in
+ * api-client but left ~25 shared capabilities hand-written twice: once in the
+ * agent-sdk's defineTool DSL, once in ziggs-mcp zod. Each capability below is
+ * the single source for the tool's schema, validation, response shaping, and
+ * guidance; the two surfaces register it through thin adapters
+ * (agent-sdk `toolFromCapability`, ziggs-mcp `registerCapability`).
+ *
+ * Params are a neutral JSON-schema-flavoured DSL rather than zod because the
+ * two surfaces cannot share one zod: agent-sdk is on zod v4, ziggs-mcp on
+ * zod v3 (pinned by the MCP SDK's ZodRawShape), and api-client deliberately
+ * has no zod dependency. The SDK adapter feeds params straight into
+ * defineTool's converter; the MCP adapter lowers them to zod v3.
+ */
+import type { Creds } from '../types.js';
+export type CapabilitySurface = 'sdk' | 'mcp';
+/** read-only / write / destructive — lowered to MCP tool annotations. */
+export type CapabilityAnnotation = 'read-only' | 'write' | 'destructive';
+export interface CapabilityParam {
+    type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    required?: boolean;
+    description?: string;
+    /** Only for type 'string'. */
+    enum?: readonly string[];
+    /** Only for type 'array'. */
+    items?: {
+        type: 'string';
+        enum?: readonly string[];
+    } | {
+        type: 'object';
+        properties?: Record<string, unknown>;
+        required?: string[];
+    };
+}
+/**
+ * Runtime context a surface adapter hands the shared handler. `creds.agentId`
+ * may be absent for agent-scoped operator keys (payments rail); capabilities
+ * that impersonate set `needsAgentId` so the adapter fails early instead.
+ */
+export interface CapabilityEnv {
+    creds: {
+        operatorKey: string;
+        agentId?: string;
+    };
+    /** SDK runner base-URL override (BACKEND_URL / ZIGGS_BACKEND_URL). */
+    baseUrl?: string;
+    /** Web-app origin for human-facing URLs (claim links etc.). */
+    webUrl?: string;
+    surface: CapabilitySurface;
+}
+export interface CapabilityDefinition {
+    /** Stable capability key (the parity-table base name), e.g. 'payment_transfer'. */
+    key: string;
+    /** Registered tool name per surface — the ZIG-903 parity table is the authority. */
+    names: {
+        sdk: string;
+        mcp: string;
+    };
+    /**
+     * Tool description per surface. Kept side by side deliberately: wording may
+     * reference surface-local tool names and MCP delegate-protocol guidance, but
+     * schema + handler can no longer drift.
+     */
+    descriptions: {
+        sdk: string;
+        mcp: string;
+    };
+    annotation: CapabilityAnnotation;
+    params: Record<string, CapabilityParam>;
+    /** True when the handler impersonates an agent (X-Agent-Id required). */
+    needsAgentId?: boolean;
+    handler: (args: Record<string, unknown>, env: CapabilityEnv) => Promise<unknown>;
+    /** Pass-through flags for the SDK's defineTool options. */
+    sdkOptions?: {
+        isAgreementCreation?: boolean;
+        isGenericFallback?: boolean;
+    };
+}
+/** Creds for impersonated calls; adapters guarantee agentId when needsAgentId. */
+export declare function fullCreds(env: CapabilityEnv): Creds;
+/**
+ * Re-throw a client error with a capability-level prefix, preserving the HTTP
+ * status/body the clients attach (the SDK runtime and toolError classification
+ * both read them).
+ */
+export declare function rethrowWithContext(error: unknown, prefix: string): never;

package/dist/capabilities/types.js

@@ -0,0 +1,24 @@
+/** Creds for impersonated calls; adapters guarantee agentId when needsAgentId. */
+export function fullCreds(env) {
+    const { operatorKey, agentId } = env.creds;
+    if (!operatorKey)
+        throw new Error('operatorKey missing from tool context');
+    if (!agentId)
+        throw new Error('agentId missing from tool context');
+    return { operatorKey, agentId };
+}
+/**
+ * Re-throw a client error with a capability-level prefix, preserving the HTTP
+ * status/body the clients attach (the SDK runtime and toolError classification
+ * both read them).
+ */
+export 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;
+}

package/dist/http/AgreementClient.d.ts

@@ -128,6 +128,13 @@ export interface GetMyAgreementsFilters {
     engagementKind?: EngagementKind;
     proposalStatus?: string;
     hasTask?: boolean;
+    /**
+     * ZIG-942: `scope=mine` alone 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 a true "mine": only
+     * agreements where the caller (key owner or impersonated agent) is a party.
+     */
+    partyOnly?: boolean;
 }
 export declare function getMyAgreements(filters: GetMyAgreementsFilters | undefined, creds: Creds): Promise<Agreement[]>;
 export declare function getAgreement(agreementId: string, creds: Creds): Promise<Agreement | null>;

package/dist/http/AgreementClient.js

@@ -284,6 +284,8 @@ export async function getMyAgreements(filters = {}, creds) {
         url.searchParams.set('proposalStatus', filters.proposalStatus);
     if (filters.hasTask != null)
         url.searchParams.set('hasTask', String(filters.hasTask));
+    if (filters.partyOnly)
+        url.searchParams.set('partyOnly', 'true');
     let res;
     try {
         res = await fetch(url.toString(), { method: 'GET', headers: buildHeaders(creds) });

package/dist/http/ConnectionsClient.d.ts

@@ -1,4 +1,5 @@
 import 'dotenv/config';
+import type { GrantView } from './grants.js';
 export declare function assertNoLeakedConnectionSecret(serialized: string): void;
 /** Thrown by ConnectionsClient with the HTTP status and raw body attached. */
 export interface ConnectionsError extends Error {
@@ -11,6 +12,23 @@ export interface ConnectionProxyParams {
     action: string;
     payload?: unknown;
 }
+/** A grant row from the per-connection lister (GET /connections/:id/grants). */
+export interface ConnectionGrant {
+    grantId?: string;
+    holderId?: string;
+    caveats?: unknown[];
+    [key: string]: unknown;
+}
+/**
+ * ZIG-641 / ZIG-648 — every connection grant the acting agent holds, grouped by
+ * connection, via the unified GET /grants. `provider` comes from the grant's
+ * resolved scope label.
+ */
+export interface ConnectionWithGrants {
+    connectionId: string;
+    provider: string | null;
+    grants: GrantView[];
+}
 export interface McpConnectionRequestParams {
     serverUrl: string;
     tools: string[];
@@ -53,7 +71,15 @@ export declare class ConnectionsClient {
      */
     listGrants({ connectionId }: {
         connectionId: string;
-    }): Promise<unknown[]>;
+    }): Promise<ConnectionGrant[]>;
+    /**
+     * ZIG-641 / ZIG-956 — cross-connection discovery over the unified GET /grants:
+     * every live connection grant this agent holds, grouped by connection, so a
+     * proxy caller's connectionId/grantId no longer has to arrive out of band.
+     * Moved here from ziggs-mcp's inline helper. The response is scanned
+     * defensively for leaked secrets, as `proxy` does.
+     */
+    listForHolder(): Promise<ConnectionWithGrants[]>;
     /** Issue a connection grant to an agent holder (connection owner side). */
     issueGrant({ connectionId, holderId, caveats, }: {
         connectionId: string;

package/dist/http/ConnectionsClient.js

@@ -1,6 +1,7 @@
 import 'dotenv/config';
 import { getBackendUrl } from '../utils/urlUtils.js';
 import { buildOperatorHeaders } from './operatorHeaders.js';
+import { GrantsClient } from './GrantsClient.js';
 // ZIG-569 — defense-in-depth mirror of the backend leak-guard
 // (assertProxyResponseDoesNotLeakTokens). The backend strips the *specific*
 // vault token from the response; clients never see that token, so this layer
@@ -82,6 +83,34 @@ export class ConnectionsClient {
         const grants = res['grants'] || [];
         return grants.filter((g) => g['holderId'] === this.agentId);
     }
+    /**
+     * ZIG-641 / ZIG-956 — cross-connection discovery over the unified GET /grants:
+     * every live connection grant this agent holds, grouped by connection, so a
+     * proxy caller's connectionId/grantId no longer has to arrive out of band.
+     * Moved here from ziggs-mcp's inline helper. The response is scanned
+     * defensively for leaked secrets, as `proxy` does.
+     */
+    async listForHolder() {
+        const grantsClient = new GrantsClient(this.operatorKey, this.agentId, this.baseUrl);
+        // All pages of the agent's live connection grants (not just the first page).
+        const items = await grantsClient.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;
+    }
     /** Issue a connection grant to an agent holder (connection owner side). */
     async issueGrant({ connectionId, holderId, caveats, }) {
         if (!connectionId)

package/dist/http/GrantsClient.d.ts

@@ -16,10 +16,26 @@ export interface ListGrantsQuery {
     cursor?: string;
     limit?: number;
 }
+/**
+ * ZIG-893 / ZIG-956 — a grant rail the caller's operator key cannot read, named
+ * by the backend on `GET /grants` (it silently drops those rails from `items`,
+ * so the unified list tool names what it isn't entitled to instead of
+ * presenting a short list as if it were complete). Replaces the client-side
+ * mirror of the backend scope table + JWT decode (the retired grantRails.ts).
+ */
+export interface UnreadableRail {
+    rail: 'context' | 'connection' | 'wallet';
+    requiredScope: string;
+}
 export interface ListGrantsResult {
     items: GrantView[];
     nextCursor: string | null;
     hasMore: boolean;
+    /**
+     * Rails the caller can't read, per the backend. Absent when the backend
+     * predates ZIG-956 or every requested rail was readable.
+     */
+    unreadableRails?: UnreadableRail[];
 }
 /**
  * ZIG-648 — unified grant listing across every rail. `GET /grants` returns the

package/dist/http/GrantsClient.js

@@ -48,6 +48,9 @@ export class GrantsClient {
             items: parsed.items ?? [],
             nextCursor: parsed.nextCursor ?? null,
             hasMore: parsed.hasMore ?? false,
+            ...(parsed.unreadableRails?.length
+                ? { unreadableRails: parsed.unreadableRails }
+                : {}),
         };
     }
     /**