@ziggs-ai/agent-sdk 0.4.1 → 0.6.0

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/dist/types.d.ts

@@ -313,8 +313,9 @@ export interface ContextSnapshot {
      * The session's chat no longer resolves on the backend (messages read
      * 404'd) — deleted or never visible to this agent. Message-triggered wakes
      * check this and skip the LLM instead of reasoning over a fabricated empty
-     * history. Agreement-keyed lanes also set it (their sessionId is not a
-     * chat), so it only gates message wakes, never task lanes.
+     * history. Only gates message wakes. A bare agreementId as sessionId also
+     * trips it (ZIG-975) — that is a mis-keyed lane, not a legitimate task lane;
+     * task wakes should key on the agreement's origin/notification chat.
      */
     chatMissing?: boolean;
     /** Index signature so PromptBuilder's `ServerContext` can accept it directly. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ziggs-ai/agent-sdk",
-  "version": "0.4.1",
+  "version": "0.6.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.1",
+    "@ziggs-ai/api-client": "^0.5.0",
     "ajv": "^8.17.1",
     "dotenv": "^17.2.3",
     "openai": "^4.0.0",