@ziggs-ai/api-client 0.3.1 → 0.5.0

package/dist/capabilities/links.js

@@ -0,0 +1,219 @@
+import { createAgreement, claimAgreement, listAgreements, revokeAgreement, } from '../http/AgreementClient.js';
+import { fullCreds } from './types.js';
+const DEFAULT_WEB_URL = 'https://ziggsai.com';
+/** Public Streamable-HTTP MCP endpoint; OAuth is discovered from it (RFC 9728). */
+const ZIGGS_MCP_URL = 'https://mcp.ziggsai.com/mcp';
+function webAppOrigin(env) {
+    return (env.webUrl?.trim() || DEFAULT_WEB_URL).replace(/\/$/, '');
+}
+/**
+ * The second form an invite travels in: text the recipient pastes into their
+ * own assistant, which then connects itself and claims the invite. The claim
+ * URL alone only helps someone who already has Ziggs and an assistant wired
+ * up, so hand the caller both and let it pick per recipient.
+ */
+function invitePasteText(agreementId, claimUrl) {
+    return [
+        'Connect me to Ziggs and accept this agent link invite.',
+        '',
+        `1. Add this MCP server: ${ZIGGS_MCP_URL}`,
+        '   It speaks Streamable HTTP and uses OAuth — pasting the URL is enough,',
+        '   but I may need to approve a consent screen in my browser.',
+        `2. Once connected, call the tool ziggs_claim_link_invite with agreementId "${agreementId}".`,
+        '3. Then tell me who I am linked with, and what they can and cannot see.',
+        '',
+        'If you cannot add MCP servers yourself, tell me exactly where to paste that',
+        "URL in my assistant's settings, then continue from step 2.",
+        '',
+        `Invite link (if you need it in a browser instead): ${claimUrl}`,
+    ].join('\n');
+}
+/**
+ * ZIG-670 — link-shaped summaries, not raw agreement documents: the money
+ * block, approvals array, and Mongo internals are noise on a trust
+ * relationship. ZIG-956 moved this into the shared layer so the MCP mutations
+ * return it too (they used to leak the raw agreement doc).
+ */
+export 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,
+    };
+}
+/** A link is reach-only — the follow-up move differs by surface tool names. */
+export function linkIsReachOnly(env) {
+    return env.surface === 'mcp'
+        ? 'A link is reach-only. Open a chat with the peer (ziggs_open_conversation, participantId = peer agent id) and grant it chat access with ziggs_issue_grant, or share a slice of a grant you hold with ziggs_delegate_grant, before reading context.'
+        : '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.';
+}
+const LINK_STATUSES = ['active', 'open', 'cancelled', 'all'];
+export const requestLinkCapability = {
+    key: 'request_link',
+    names: { sdk: 'request_link', mcp: 'ziggs_request_link' },
+    descriptions: {
+        sdk: '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.',
+        mcp: 'Request a bilateral trust link with another agent before cross-org reach (party-to-party, NOT a third-party service connection — see ziggs_list_my_connections for that). A link is just an agreement (POST /agreements {engagementKind:"link"}). The target OWNER must approve it (via ziggs_respond_to_agreement) before unpublished delegates can message each other.',
+    },
+    annotation: 'write',
+    params: {
+        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)',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const { agreement } = await createAgreement({
+            engagementKind: 'link',
+            providerId: args['providerId'],
+            description: args['message'],
+        }, fullCreds(env));
+        return {
+            status: 'pending',
+            message: env.surface === 'mcp'
+                ? 'Link agreement created — the counterparty owner must approve (ziggs_respond_to_agreement) before cross-org reach. Surface pending state to the human.'
+                : '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),
+        };
+    },
+    sdkOptions: { isAgreementCreation: true },
+};
+export const createLinkInviteCapability = {
+    key: 'create_link_invite',
+    names: { sdk: 'create_link_invite', mcp: 'ziggs_create_link_invite' },
+    descriptions: {
+        sdk: "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.",
+        mcp: 'Create a shareable OPEN link invite (bilateral agent-to-agent trust, NOT a third-party service connection — see ziggs_list_my_connections for that) when you do NOT have the counterparty\'s agent id (e.g. connecting across orgs). Creates an open link agreement (POST /agreements {engagementKind:"link"}, proposedTo:"everyone"). Share the returned inviteId (agreementId) out-of-band; the recipient forms the link by calling ziggs_claim_link_invite — neither side pastes an agent id. Revoke via ziggs_revoke_link to disable.',
+    },
+    annotation: 'write',
+    params: {
+        message: {
+            type: 'string',
+            description: 'Optional note shown to whoever opens the invite (agreement description)',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const { agreement } = await createAgreement({ engagementKind: 'link', description: args['message'] }, fullCreds(env));
+        const claimUrl = `${webAppOrigin(env)}/app/link-invites/${agreement.agreementId}`;
+        return {
+            status: 'open',
+            inviteId: agreement.agreementId,
+            claimUrl,
+            pasteText: invitePasteText(agreement.agreementId, claimUrl),
+            message: env.surface === 'mcp'
+                ? 'Open link invite created, single-use and valid 7 days. Give the human BOTH forms and say which is which: claimUrl for a recipient who already uses Ziggs, pasteText for one who has an AI assistant but no Ziggs account — pasting it makes their assistant connect and claim the invite itself. No agent id needed on either side.'
+                : 'Open link invite created, single-use and valid 7 days. Share claimUrl with a counterparty who already uses Ziggs, or pasteText with one who has an assistant but no Ziggs account yet — their assistant connects and claims it. No agent id needed on either side. Revoke with revoke_link to disable.',
+            agreement: linkSummary(agreement),
+        };
+    },
+    sdkOptions: { isAgreementCreation: true },
+};
+export const claimLinkInviteCapability = {
+    key: 'claim_link_invite',
+    names: { sdk: 'claim_link_invite', mcp: 'ziggs_claim_link_invite' },
+    descriptions: {
+        sdk: '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.',
+        mcp: 'Claim an open link invite by its id to form a bilateral link (agent-to-agent trust, NOT a third-party service connection — see ziggs_list_my_connections for that) (POST /agreements/:id/claim). You become the counterparty and the link activates immediately (cross-org reach + bilateral context grants). You cannot claim your own invite.',
+    },
+    annotation: 'write',
+    params: {
+        agreementId: {
+            type: 'string',
+            required: true,
+            description: 'The invite id (agreementId) shared by the issuer',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const { agreement } = await claimAgreement(args['agreementId'], fullCreds(env));
+        return {
+            status: 'linked',
+            message: `Link invite claimed — you are now linked. ${linkIsReachOnly(env)}`,
+            agreement: linkSummary(agreement),
+        };
+    },
+};
+export const listLinksCapability = {
+    key: 'list_links',
+    names: { sdk: 'list_links', mcp: 'ziggs_list_links' },
+    descriptions: {
+        sdk: '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.',
+        mcp: 'List link agreements for this delegate — bilateral agent-to-agent trust relationships, NOT third-party service connections (see ziggs_list_my_connections for those) (GET /agreements?engagementKind=link). Defaults to ACTIVE links only; pass status to see pending proposals ("open") or revoked ones ("cancelled"). Each item is a link summary: agreementId, status, proposalStatus, parties.creatorAgent (requester), parties.providerAgent (target), parties.proposedTo (target owner). Approve pending links via ziggs_respond_to_agreement.',
+    },
+    annotation: 'read-only',
+    params: {
+        status: {
+            type: 'string',
+            enum: LINK_STATUSES,
+            description: 'active (default) = established links; open = pending proposals/invites awaiting approval or claim; cancelled = revoked; all = every link regardless of status',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const status = args['status'] ?? 'active';
+        if (!LINK_STATUSES.includes(status)) {
+            throw new Error('status must be one of active, open, cancelled, all');
+        }
+        const links = await listAgreements({
+            engagementKind: 'link',
+            ...(status === 'all' ? {} : { status }),
+        }, fullCreds(env));
+        const summaries = links.map(linkSummary);
+        const hasActive = links.some((a) => a.status === 'active');
+        return {
+            count: summaries.length,
+            status,
+            links: summaries,
+            ...(hasActive ? { nextSteps: linkIsReachOnly(env) } : {}),
+        };
+    },
+    sdkOptions: { isGenericFallback: true },
+};
+export const revokeLinkCapability = {
+    key: 'revoke_link',
+    names: { sdk: 'revoke_link', mcp: 'ziggs_revoke_link' },
+    descriptions: {
+        sdk: '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.',
+        mcp: 'Revoke a bilateral link agreement — agent-to-agent trust, NOT a third-party service connection (DELETE /agreements/:agreementId). Either party may revoke; cross-org reach ends immediately. For non-link agreements (hire/service/quest), use ziggs_revoke_agreement — same endpoint, different messaging.',
+    },
+    annotation: 'destructive',
+    params: {
+        agreementId: {
+            type: 'string',
+            required: true,
+            description: 'agreementId of the link agreement (from the link lister)',
+        },
+    },
+    needsAgentId: true,
+    handler: async (args, env) => {
+        const result = await revokeAgreement(args['agreementId'], fullCreds(env));
+        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,
+        };
+    },
+};
+export const LINK_CAPABILITIES = [
+    requestLinkCapability,
+    createLinkInviteCapability,
+    claimLinkInviteCapability,
+    listLinksCapability,
+    revokeLinkCapability,
+];

package/dist/capabilities/payments.d.ts

@@ -0,0 +1,11 @@
+import { type CapabilityDefinition } from './types.js';
+export declare const paymentBalanceCapability: CapabilityDefinition;
+export declare const paymentResolveWalletCapability: CapabilityDefinition;
+export declare const paymentTransferCapability: CapabilityDefinition;
+export declare const paymentWaitForApprovalCapability: CapabilityDefinition;
+export declare const paymentHoldCapability: CapabilityDefinition;
+export declare const paymentReleaseCapability: CapabilityDefinition;
+export declare const paymentIssueGrantCapability: CapabilityDefinition;
+export declare const paymentAttenuateGrantCapability: CapabilityDefinition;
+export declare const paymentRevokeGrantCapability: CapabilityDefinition;
+export declare const PAYMENT_CAPABILITIES: CapabilityDefinition[];

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,
+];