@ziggs-ai/agent-sdk 0.1.12 → 0.2.0

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

@@ -0,0 +1,165 @@
+import { defineTool } from '../../../tools/defineTool.js';
+import { ZiggsPayClient } from '../../ziggspay/ZiggsPayClient.js';
+function clientFor(ctx) {
+    const operatorKey = ctx?.['operatorKey'];
+    if (!operatorKey)
+        throw new Error('operatorKey missing from tool context');
+    return new ZiggsPayClient({ operatorKey, actAsAgentId: ctx?.['agentId'] || undefined });
+}
+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);
+const listGrantsHandler = async (_args, ctx) => {
+    try {
+        const result = await clientFor(ctx).listGrants();
+        return { grants: result || [] };
+    }
+    catch (e) {
+        rethrowWithContext(e, 'Failed to list payment grants');
+    }
+};
+export const paymentListGrantsTool = defineTool('payment_list_grants', {}, listGrantsHandler);
+export const PAYMENT_TOOLS = [
+    paymentBalanceTool, paymentTransferTool, paymentWaitForApprovalTool,
+    paymentHoldTool, paymentReleaseTool, paymentResolveWalletTool,
+    paymentIssueGrantTool, paymentAttenuateGrantTool, paymentRevokeGrantTool, paymentListGrantsTool,
+];

package/dist/server/ziggsconnect/ZiggsConnectClient.d.ts

@@ -0,0 +1,35 @@
+import 'dotenv/config';
+export interface ZiggsConnectClientOptions {
+    operatorKey: string;
+    actAsAgentId?: string;
+    baseUrl?: string;
+}
+export interface ProxyParams {
+    connectionId: string;
+    grantId: string;
+    action: string;
+    payload?: unknown;
+}
+export declare class ZiggsConnectClient {
+    private operatorKey;
+    private actAsAgentId;
+    private baseUrl;
+    constructor({ operatorKey, actAsAgentId, baseUrl }: ZiggsConnectClientOptions);
+    /**
+     * Present a ConnectionGrant to the broker and perform a provider action.
+     * Returns the provider result — never the raw OAuth token.
+     */
+    proxy({ connectionId, grantId, action, payload }: ProxyParams): Promise<unknown>;
+    /**
+     * List ConnectionGrants held by this agent for a connection.
+     * Requires actAsAgentId; filters server rows to holderId === agent.
+     */
+    listGrants({ connectionId }: {
+        connectionId: string;
+    }): Promise<unknown[]>;
+    private _buildHeaders;
+    private _request;
+    private _get;
+    private _post;
+}
+export declare function createZiggsConnectClient(opts: ZiggsConnectClientOptions): ZiggsConnectClient;

package/dist/server/ziggsconnect/ZiggsConnectClient.js

@@ -0,0 +1,95 @@
+import 'dotenv/config';
+function getDefaultBaseUrl() {
+    return process.env.BACKEND_URL || process.env.ZIGGS_BACKEND_URL || 'http://localhost:3000';
+}
+function parseError(text, fallback) {
+    if (!text)
+        return fallback;
+    try {
+        const parsed = JSON.parse(text);
+        return parsed['message'] || parsed['error'] || text;
+    }
+    catch {
+        return text;
+    }
+}
+export class ZiggsConnectClient {
+    operatorKey;
+    actAsAgentId;
+    baseUrl;
+    constructor({ operatorKey, actAsAgentId, baseUrl }) {
+        if (!operatorKey || typeof operatorKey !== 'string') {
+            throw new Error('ZiggsConnectClient requires an operatorKey');
+        }
+        this.operatorKey = operatorKey;
+        this.actAsAgentId = actAsAgentId || null;
+        this.baseUrl = baseUrl || getDefaultBaseUrl();
+    }
+    /**
+     * Present a ConnectionGrant to the broker and perform a provider action.
+     * Returns the provider result — never the raw OAuth token.
+     */
+    async proxy({ connectionId, grantId, action, payload }) {
+        if (!connectionId)
+            throw new Error('proxy: connectionId is required');
+        if (!grantId)
+            throw new Error('proxy: grantId is required');
+        if (!action)
+            throw new Error('proxy: action is required');
+        if (!this.actAsAgentId) {
+            throw new Error('proxy: actAsAgentId is required — connection broker calls must impersonate the grant holder agent');
+        }
+        const res = (await this._post(`/connections/${encodeURIComponent(connectionId)}/proxy`, {
+            grantId,
+            action,
+            payload: payload ?? {},
+        }));
+        return res['result'] ?? res;
+    }
+    /**
+     * List ConnectionGrants held by this agent for a connection.
+     * Requires actAsAgentId; filters server rows to holderId === agent.
+     */
+    async listGrants({ connectionId }) {
+        if (!connectionId)
+            throw new Error('listGrants: connectionId is required');
+        if (!this.actAsAgentId) {
+            throw new Error('listGrants: actAsAgentId is required — grants are scoped to the impersonated agent');
+        }
+        const res = (await this._get(`/connections/${encodeURIComponent(connectionId)}/grants`));
+        const grants = res['grants'] || [];
+        return grants.filter((g) => g['holderId'] === this.actAsAgentId);
+    }
+    _buildHeaders(extra = {}) {
+        const h = { Authorization: `Bearer ${this.operatorKey}`, ...extra };
+        if (this.actAsAgentId)
+            h['X-Agent-Id'] = this.actAsAgentId;
+        return h;
+    }
+    async _request(method, path, body) {
+        const init = {
+            method,
+            headers: this._buildHeaders(body !== undefined ? { 'content-type': 'application/json' } : {}),
+        };
+        if (body !== undefined)
+            init.body = JSON.stringify(body);
+        const response = await fetch(`${this.baseUrl}${path}`, init);
+        const text = await response.text();
+        if (!response.ok) {
+            const err = new Error(parseError(text, `HTTP ${response.status}`));
+            err.status = response.status;
+            err.body = text;
+            throw err;
+        }
+        return text ? JSON.parse(text) : null;
+    }
+    _get(path) {
+        return this._request('GET', path, undefined);
+    }
+    _post(path, body) {
+        return this._request('POST', path, body ?? {});
+    }
+}
+export function createZiggsConnectClient(opts) {
+    return new ZiggsConnectClient(opts);
+}

package/dist/server/ziggscontext/ZiggsContextClient.d.ts

@@ -0,0 +1,48 @@
+import 'dotenv/config';
+export interface ZiggsContextClientOptions {
+    operatorKey: string;
+    actAsAgentId?: string;
+    baseUrl?: string;
+}
+export interface ContextReachDescriptor {
+    grantId: string;
+    scope: {
+        kind: 'chat' | 'agreement' | 'org';
+        id: string;
+    };
+    temporal: 'from-now' | 'from-start';
+    watermarkAt: string;
+    expiresAt: string | null;
+    parentGrantId: string | null;
+    createdAt: string;
+}
+export interface DelegateContextGrantParams {
+    parentGrantId: string;
+    holderId: string;
+    scope: {
+        kind: 'chat' | 'agreement' | 'org';
+        id: string;
+    };
+    temporal: 'from-now' | 'from-start';
+    expiresAt?: string | null;
+    watermarkAt?: string;
+}
+/**
+ * HTTP client for context grants (ZIG-413).
+ * Presentation model (signed bytes vs grant id) is intentionally not baked in here.
+ */
+export declare class ZiggsContextClient {
+    private operatorKey;
+    private actAsAgentId;
+    private baseUrl;
+    constructor({ operatorKey, actAsAgentId, baseUrl }: ZiggsContextClientOptions);
+    /** ZIG-412: scope descriptors for what this agent can reach (no content). */
+    discover(): Promise<ContextReachDescriptor[]>;
+    /** Holder delegates a narrower child grant. */
+    delegate(params: DelegateContextGrantParams): Promise<unknown>;
+    private requireActAsAgent;
+    private _buildHeaders;
+    private _request;
+    private _get;
+    private _post;
+}

package/dist/server/ziggscontext/ZiggsContextClient.js

@@ -0,0 +1,90 @@
+import 'dotenv/config';
+function getDefaultBaseUrl() {
+    return process.env.BACKEND_URL || process.env.ZIGGS_BACKEND_URL || 'http://localhost:3000';
+}
+function parseError(text, fallback) {
+    if (!text)
+        return fallback;
+    try {
+        const parsed = JSON.parse(text);
+        return parsed['message'] || parsed['error'] || text;
+    }
+    catch {
+        return text;
+    }
+}
+/**
+ * HTTP client for context grants (ZIG-413).
+ * Presentation model (signed bytes vs grant id) is intentionally not baked in here.
+ */
+export class ZiggsContextClient {
+    operatorKey;
+    actAsAgentId;
+    baseUrl;
+    constructor({ operatorKey, actAsAgentId, baseUrl }) {
+        if (!operatorKey || typeof operatorKey !== 'string') {
+            throw new Error('ZiggsContextClient requires an operatorKey');
+        }
+        this.operatorKey = operatorKey;
+        this.actAsAgentId = actAsAgentId || null;
+        this.baseUrl = baseUrl || getDefaultBaseUrl();
+    }
+    /** ZIG-412: scope descriptors for what this agent can reach (no content). */
+    async discover() {
+        this.requireActAsAgent('discover');
+        const res = (await this._get('/context/discovery'));
+        return res['reach'] || [];
+    }
+    /** Holder delegates a narrower child grant. */
+    async delegate(params) {
+        this.requireActAsAgent('delegate');
+        if (!params.parentGrantId)
+            throw new Error('delegate: parentGrantId is required');
+        if (!params.holderId)
+            throw new Error('delegate: holderId is required');
+        if (!params.scope?.kind || !params.scope?.id) {
+            throw new Error('delegate: scope { kind, id } is required');
+        }
+        return this._post(`/context/grants/${encodeURIComponent(params.parentGrantId)}/delegate`, {
+            holderId: params.holderId,
+            scope: params.scope,
+            temporal: params.temporal,
+            expiresAt: params.expiresAt,
+            watermarkAt: params.watermarkAt,
+        });
+    }
+    requireActAsAgent(method) {
+        if (!this.actAsAgentId) {
+            throw new Error(`${method}: actAsAgentId is required — context grant calls must impersonate the grant holder agent`);
+        }
+    }
+    _buildHeaders(extra = {}) {
+        const h = { Authorization: `Bearer ${this.operatorKey}`, ...extra };
+        if (this.actAsAgentId)
+            h['X-Agent-Id'] = this.actAsAgentId;
+        return h;
+    }
+    async _request(method, path, body) {
+        const init = {
+            method,
+            headers: this._buildHeaders(body !== undefined ? { 'content-type': 'application/json' } : {}),
+        };
+        if (body !== undefined)
+            init.body = JSON.stringify(body);
+        const res = await fetch(`${this.baseUrl}${path}`, init);
+        const text = await res.text();
+        if (!res.ok) {
+            const err = new Error(parseError(text, `${method} ${path} failed (${res.status})`));
+            err.status = res.status;
+            err.body = text;
+            throw err;
+        }
+        return text ? JSON.parse(text) : {};
+    }
+    _get(path) {
+        return this._request('GET', path, undefined);
+    }
+    _post(path, body) {
+        return this._request('POST', path, body);
+    }
+}

package/dist/server/ziggspay/ZiggsPayClient.d.ts

@@ -0,0 +1,82 @@
+import 'dotenv/config';
+export interface ZiggsPayClientOptions {
+    operatorKey: string;
+    actAsAgentId?: string;
+    baseUrl?: string;
+}
+export declare class ZiggsPayClient {
+    private operatorKey;
+    private actAsAgentId;
+    private baseUrl;
+    constructor({ operatorKey, actAsAgentId, baseUrl }: ZiggsPayClientOptions);
+    balance(): Promise<{
+        walletId: string | null;
+        currency: string;
+        balance: number;
+        availableBalance: number;
+    }>;
+    resolve({ userId, agentId }?: {
+        userId?: string;
+        agentId?: string;
+    }): Promise<unknown>;
+    transfer({ to, amount, idempotencyKey, description, paymentGrantId }: {
+        to: string;
+        amount: number;
+        idempotencyKey?: string;
+        description?: string;
+        paymentGrantId?: string;
+    }): Promise<unknown>;
+    hold({ amount, idempotencyKey, description }: {
+        amount: number;
+        idempotencyKey?: string;
+        description?: string;
+    }): Promise<unknown>;
+    release({ holdId, action, toWalletId, idempotencyKey }: {
+        holdId: string;
+        action?: string;
+        toWalletId?: string;
+        idempotencyKey?: string;
+    }): Promise<unknown>;
+    history(params?: {
+        limit?: number;
+        offset?: number;
+        type?: string;
+    }): Promise<unknown>;
+    issueGrant({ holderId, caveats }: {
+        holderId: string;
+        caveats?: unknown;
+    }): Promise<unknown>;
+    attenuateGrant({ grantId, holderId, caveats }: {
+        grantId: string;
+        holderId: string;
+        caveats?: unknown;
+    }): Promise<unknown>;
+    revokeGrant(grantId: string): Promise<unknown>;
+    listGrants(): Promise<unknown[]>;
+    createTopUpIntent({ amount, description, currency }?: {
+        amount?: number;
+        description?: string;
+        currency?: string;
+    }): Promise<unknown>;
+    confirmMockIntent(intentId: string): Promise<unknown>;
+    faucet({ amount, description, idempotencyKey }?: {
+        amount?: number;
+        description?: string;
+        idempotencyKey?: string;
+    }): Promise<unknown>;
+    approvals({ status }?: {
+        status?: string;
+    }): Promise<unknown[]>;
+    getApproval(approvalId: string): Promise<unknown | null>;
+    decide(approvalId: string, decision: string, note?: string): Promise<unknown>;
+    waitForApproval(approvalId: string, opts?: {
+        pollMs?: number;
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<unknown>;
+    private _buildHeaders;
+    private _request;
+    private _get;
+    private _post;
+}
+export declare function createZiggsPayClient(opts: ZiggsPayClientOptions): ZiggsPayClient;