@framers/agentos-ext-wallet 0.2.0

package/src/tools/IssueCardTool.ts

@@ -0,0 +1,76 @@
+// @ts-nocheck
+/**
+ * @fileoverview Agent-callable tool for issuing a virtual card.
+ * @module wallet/tools/IssueCardTool
+ */
+
+import type { ITool, ToolExecutionContext, ToolExecutionResult } from '@framers/agentos/core/tools/ITool';
+import type { CardManager } from '../cards/CardManager.js';
+
+interface IssueCardInput {
+  /** Optional label for the card. */
+  memo?: string;
+  /** Monthly spending limit in USD. Uses default if omitted. */
+  spendLimitUsd?: number;
+}
+
+interface IssueCardOutput {
+  cardId: string;
+  last4: string;
+  state: string;
+  spendLimitUsd: number;
+  network: string;
+}
+
+export function createIssueCardTool(cardManager: CardManager): ITool<IssueCardInput, IssueCardOutput> {
+  return {
+    id: 'wallet-issue-card-v1',
+    name: 'issue_virtual_card',
+    displayName: 'Issue Virtual Card',
+    description:
+      'Issue a new virtual debit card for the agent. The card can be used for online purchases, '
+      + 'subscriptions, and API payments. Spending limits and category restrictions from the wallet '
+      + 'spending policy are automatically enforced at the card network level.',
+    category: 'wallet',
+    version: '1.0.0',
+    hasSideEffects: true,
+    requiredCapabilities: ['capability:wallet', 'capability:wallet_card'],
+
+    inputSchema: {
+      type: 'object',
+      properties: {
+        memo: {
+          type: 'string',
+          description: 'Optional label for the card (e.g. "API subscriptions").',
+        },
+        spendLimitUsd: {
+          type: 'number',
+          description: 'Monthly spending limit in USD. Uses the default from config if omitted.',
+        },
+      },
+    },
+
+    async execute(args: IssueCardInput, context: ToolExecutionContext): Promise<ToolExecutionResult<IssueCardOutput>> {
+      try {
+        const agentId = context.gmiId;
+        const card = await cardManager.issueCard(agentId, {
+          memo: args.memo,
+          spendLimitUsd: args.spendLimitUsd,
+        });
+
+        return {
+          success: true,
+          output: {
+            cardId: card.id,
+            last4: card.last4,
+            state: card.state,
+            spendLimitUsd: card.spendLimitUsd,
+            network: card.network,
+          },
+        };
+      } catch (err: any) {
+        return { success: false, error: err.message || String(err) };
+      }
+    },
+  };
+}

package/src/tools/PayWithCardTool.ts

@@ -0,0 +1,109 @@
+// @ts-nocheck
+/**
+ * @fileoverview Agent-callable tool for retrieving card details for online payments.
+ *
+ * Returns sensitive card details (PAN, CVV, expiry) so the agent can fill
+ * online checkout forms. Enforces spending policy before revealing details.
+ *
+ * @module wallet/tools/PayWithCardTool
+ */
+
+import type { ITool, ToolExecutionContext, ToolExecutionResult } from '@framers/agentos/core/tools/ITool';
+import type { CardManager } from '../cards/CardManager.js';
+import type { SpendCategory } from '../types.js';
+
+interface PayWithCardInput {
+  /** Estimated transaction amount in USD. Used for spending policy pre-check. */
+  estimatedAmountUsd?: number;
+  /** Spending category for budget tracking. Defaults to 'shopping'. */
+  category?: SpendCategory;
+  /** Description of what the payment is for. */
+  description?: string;
+}
+
+interface PayWithCardOutput {
+  last4: string;
+  pan: string;
+  cvv: string;
+  expMonth: string;
+  expYear: string;
+}
+
+export function createPayWithCardTool(cardManager: CardManager): ITool<PayWithCardInput, PayWithCardOutput> {
+  return {
+    id: 'wallet-pay-with-card-v1',
+    name: 'pay_with_card',
+    displayName: 'Pay With Card',
+    description:
+      'Retrieve the agent\'s virtual card details (card number, CVV, expiry) to make an online payment. '
+      + 'If an estimated amount is provided, spending policy is checked before revealing card details. '
+      + 'Use this when filling checkout forms on websites or paying for API services.',
+    category: 'wallet',
+    version: '1.0.0',
+    hasSideEffects: true,
+    requiredCapabilities: ['capability:wallet', 'capability:wallet_card', 'capability:wallet_card_pay'],
+
+    inputSchema: {
+      type: 'object',
+      properties: {
+        estimatedAmountUsd: {
+          type: 'number',
+          description: 'Estimated transaction amount in USD for spending policy pre-check.',
+        },
+        category: {
+          type: 'string',
+          enum: [
+            'api_costs', 'web_services', 'shopping', 'subscriptions',
+            'transfers', 'defi', 'dining', 'travel', 'entertainment',
+            'utilities', 'other',
+          ],
+          description: 'Spending category for budget tracking. Defaults to "shopping".',
+        },
+        description: {
+          type: 'string',
+          description: 'What the payment is for (logged for audit trail).',
+        },
+      },
+    },
+
+    async execute(args: PayWithCardInput, context: ToolExecutionContext): Promise<ToolExecutionResult<PayWithCardOutput>> {
+      try {
+        const agentId = context.gmiId;
+        const category: SpendCategory = args.category || 'shopping';
+
+        const details = await cardManager.getCardDetails(
+          agentId,
+          args.estimatedAmountUsd,
+          category,
+        );
+
+        if (!details.pan) {
+          return {
+            success: false,
+            error: 'Card details not available. The card provider may not support PAN retrieval in this environment.',
+          };
+        }
+
+        return {
+          success: true,
+          output: {
+            last4: details.last4,
+            pan: details.pan,
+            cvv: details.cvv,
+            expMonth: details.expMonth,
+            expYear: details.expYear,
+          },
+        };
+      } catch (err: any) {
+        if (err.name === 'CardSpendingBlockedError') {
+          return {
+            success: false,
+            error: err.message,
+            details: { policyViolation: true },
+          };
+        }
+        return { success: false, error: err.message || String(err) };
+      }
+    },
+  };
+}

package/src/tools/SendCryptoTool.ts

@@ -0,0 +1,185 @@
+// @ts-nocheck
+/**
+ * @fileoverview Agent-callable tool for sending crypto with spending policy enforcement.
+ * @module wunderland/wallet/tools/SendCryptoTool
+ */
+
+import type { ITool, ToolExecutionContext, ToolExecutionResult } from '@framers/agentos/core/tools/ITool';
+import type { AgentWalletManager } from '../AgentWalletManager.js';
+import type { ChainId, SpendCategory, TokenSymbol } from '../types.js';
+
+interface SendCryptoInput {
+  /** Destination address. */
+  to: string;
+  /** Amount in human-readable units (e.g. "0.5" SOL, "10" USDC). */
+  amount: string;
+  /** Chain to send on. Defaults to 'solana'. */
+  chain?: ChainId;
+  /** Token to send. Defaults to native (SOL/ETH). */
+  token?: TokenSymbol;
+  /** Spending category for budget tracking. Defaults to 'transfers'. */
+  category?: SpendCategory;
+  /** Optional description for the transaction log. */
+  description?: string;
+}
+
+interface SendCryptoOutput {
+  txHash: string;
+  chain: ChainId;
+  fromAddress: string;
+  toAddress: string;
+  amount: string;
+  token: string;
+  status: string;
+}
+
+const DECIMALS: Record<string, number> = {
+  SOL: 9,
+  ETH: 18,
+  USDC: 6,
+  USDT: 6,
+};
+
+const DEFAULT_REFERENCE_USD_PRICES: Record<TokenSymbol, number> = {
+  SOL: 1,
+  ETH: 1,
+  USDC: 1,
+  USDT: 1,
+};
+
+function getReferenceUsdPrice(token: TokenSymbol): number {
+  const envKey = `WALLET_PRICE_${token}_USD`;
+  const override = Number.parseFloat(process.env[envKey] || '');
+  if (Number.isFinite(override) && override > 0) {
+    return override;
+  }
+  return DEFAULT_REFERENCE_USD_PRICES[token] ?? 1;
+}
+
+function parseAmountToRaw(amount: string, decimals: number): bigint {
+  const parts = amount.split('.');
+  const intPart = parts[0] || '0';
+  const fracPart = (parts[1] || '').padEnd(decimals, '0').slice(0, decimals);
+  return BigInt(intPart) * 10n ** BigInt(decimals) + BigInt(fracPart);
+}
+
+export function createSendCryptoTool(walletManager: AgentWalletManager): ITool<SendCryptoInput, SendCryptoOutput> {
+  return {
+    id: 'wallet-send-crypto-v1',
+    name: 'send_crypto',
+    displayName: 'Send Crypto',
+    description:
+      'Send cryptocurrency from the agent\'s personal wallet to a destination address. '
+      + 'Enforces spending limits, category budgets, and address whitelists configured by the user. '
+      + 'Transactions above the approval threshold require explicit human confirmation. '
+      + 'Supports SOL, ETH (on Ethereum/Base), USDC, and USDT.',
+    category: 'wallet',
+    version: '1.0.0',
+    hasSideEffects: true,
+    requiredCapabilities: ['capability:wallet', 'capability:wallet_send'],
+
+    inputSchema: {
+      type: 'object',
+      properties: {
+        to: {
+          type: 'string',
+          description: 'Destination wallet address.',
+        },
+        amount: {
+          type: 'string',
+          description: 'Amount to send in human-readable units (e.g. "0.5" for 0.5 SOL).',
+        },
+        chain: {
+          type: 'string',
+          enum: ['solana', 'ethereum', 'base', 'polygon'],
+          description: 'Blockchain to use. Defaults to solana.',
+        },
+        token: {
+          type: 'string',
+          enum: ['SOL', 'ETH', 'USDC', 'USDT'],
+          description: 'Token to send. Defaults to native token (SOL/ETH).',
+        },
+        category: {
+          type: 'string',
+          enum: [
+            'api_costs', 'web_services', 'shopping', 'subscriptions',
+            'transfers', 'defi', 'dining', 'travel', 'entertainment',
+            'utilities', 'other',
+          ],
+          description: 'Spending category for budget tracking. Defaults to "transfers".',
+        },
+        description: {
+          type: 'string',
+          description: 'Optional note for the transaction log.',
+        },
+      },
+      required: ['to', 'amount'],
+    },
+
+    async execute(args: SendCryptoInput, context: ToolExecutionContext): Promise<ToolExecutionResult<SendCryptoOutput>> {
+      try {
+        const chain: ChainId = args.chain || 'solana';
+        const nativeToken: TokenSymbol = chain === 'solana' ? 'SOL' : 'ETH';
+        const token: TokenSymbol = args.token || nativeToken;
+        const category: SpendCategory = args.category || 'transfers';
+        const agentId = context.gmiId;
+        const decimals = DECIMALS[token] || 18;
+
+        // Validate amount
+        const amountNum = parseFloat(args.amount);
+        if (isNaN(amountNum) || amountNum <= 0) {
+          return { success: false, error: `Invalid amount: "${args.amount}". Must be a positive number.` };
+        }
+
+        const amountRaw = parseAmountToRaw(args.amount, decimals);
+
+        // Use configurable reference prices until a live oracle/provider is wired.
+        const estimatedUsd = amountNum * getReferenceUsdPrice(token);
+
+        // Only native sends are implemented in Phase 1
+        if (token !== nativeToken) {
+          return {
+            success: false,
+            error: `Token transfers (${token}) are not yet supported. Only native ${nativeToken} sends are available in this version.`,
+          };
+        }
+
+        const txRecord = await walletManager.sendNative(
+          agentId,
+          chain,
+          args.to,
+          amountRaw,
+          estimatedUsd,
+          category,
+          args.description,
+        );
+
+        return {
+          success: true,
+          output: {
+            txHash: txRecord.txHash || '',
+            chain,
+            fromAddress: txRecord.fromAddress || '',
+            toAddress: args.to,
+            amount: args.amount,
+            token,
+            status: txRecord.status,
+          },
+        };
+      } catch (err: any) {
+        // Surface spending policy violations cleanly
+        if (err.name === 'SpendingPolicyViolation' || err.name === 'ApprovalRequiredError') {
+          return {
+            success: false,
+            error: err.message,
+            details: {
+              policyViolation: true,
+              requiresApproval: err.name === 'ApprovalRequiredError',
+            },
+          };
+        }
+        return { success: false, error: err.message || String(err) };
+      }
+    },
+  };
+}

package/src/tools/UnfreezeCardTool.ts

@@ -0,0 +1,52 @@
+// @ts-nocheck
+/**
+ * @fileoverview Agent-callable tool for unfreezing (resuming) a card.
+ * @module wallet/tools/UnfreezeCardTool
+ */
+
+import type { ITool, ToolExecutionContext, ToolExecutionResult } from '@framers/agentos/core/tools/ITool';
+import type { CardManager } from '../cards/CardManager.js';
+
+interface UnfreezeCardInput {}
+
+interface UnfreezeCardOutput {
+  state: string;
+  message: string;
+}
+
+export function createUnfreezeCardTool(cardManager: CardManager): ITool<UnfreezeCardInput, UnfreezeCardOutput> {
+  return {
+    id: 'wallet-unfreeze-card-v1',
+    name: 'unfreeze_card',
+    displayName: 'Unfreeze Card',
+    description:
+      'Unfreeze the agent\'s virtual card, resuming normal transaction processing. '
+      + 'The card must be in a PAUSED state.',
+    category: 'wallet',
+    version: '1.0.0',
+    hasSideEffects: true,
+    requiredCapabilities: ['capability:wallet', 'capability:wallet_card'],
+
+    inputSchema: {
+      type: 'object',
+      properties: {},
+    },
+
+    async execute(_args: UnfreezeCardInput, context: ToolExecutionContext): Promise<ToolExecutionResult<UnfreezeCardOutput>> {
+      try {
+        const agentId = context.gmiId;
+        await cardManager.unfreezeCard(agentId);
+
+        return {
+          success: true,
+          output: {
+            state: 'OPEN',
+            message: 'Card has been unfrozen. Transactions are now accepted.',
+          },
+        };
+      } catch (err: any) {
+        return { success: false, error: err.message || String(err) };
+      }
+    },
+  };
+}

package/src/tools/WalletHistoryTool.ts

@@ -0,0 +1,113 @@
+// @ts-nocheck
+/**
+ * @fileoverview Agent-callable tool for viewing wallet transaction history.
+ * @module wunderland/wallet/tools/WalletHistoryTool
+ */
+
+import type { ITool, ToolExecutionContext, ToolExecutionResult } from '@framers/agentos/core/tools/ITool';
+import type { AgentWalletManager } from '../AgentWalletManager.js';
+import type { ChainId, WalletTransactionRecord } from '../types.js';
+
+interface WalletHistoryInput {
+  /** Chain to query. Defaults to 'solana'. */
+  chain?: ChainId;
+  /** Max number of transactions to return. Defaults to 10. */
+  limit?: number;
+}
+
+interface TransactionSummary {
+  id: string;
+  txHash?: string;
+  direction: string;
+  to?: string;
+  from?: string;
+  amount: string;
+  token: string;
+  category?: string;
+  status: string;
+  date: string;
+  description?: string;
+}
+
+interface WalletHistoryOutput {
+  chain: ChainId;
+  address: string;
+  transactions: TransactionSummary[];
+  totalCount: number;
+}
+
+export function createWalletHistoryTool(walletManager: AgentWalletManager): ITool<WalletHistoryInput, WalletHistoryOutput> {
+  return {
+    id: 'wallet-transaction-history-v1',
+    name: 'wallet_transaction_history',
+    displayName: 'Wallet Transaction History',
+    description:
+      'View recent transaction history for the agent\'s personal wallet. '
+      + 'Shows inbound and outbound transfers with amounts, status, and categories.',
+    category: 'wallet',
+    version: '1.0.0',
+    hasSideEffects: false,
+    requiredCapabilities: ['capability:wallet'],
+
+    inputSchema: {
+      type: 'object',
+      properties: {
+        chain: {
+          type: 'string',
+          enum: ['solana', 'ethereum', 'base', 'polygon'],
+          description: 'Blockchain to query. Defaults to solana.',
+        },
+        limit: {
+          type: 'integer',
+          minimum: 1,
+          maximum: 50,
+          description: 'Max number of transactions to return. Defaults to 10.',
+        },
+      },
+    },
+
+    async execute(args: WalletHistoryInput, context: ToolExecutionContext): Promise<ToolExecutionResult<WalletHistoryOutput>> {
+      try {
+        const chain: ChainId = args.chain || 'solana';
+        const limit = args.limit || 10;
+        const agentId = context.gmiId;
+
+        const wallet = await walletManager.getWallet(agentId, chain);
+        if (!wallet) {
+          return {
+            success: false,
+            error: `No ${chain} wallet found for this agent.`,
+          };
+        }
+
+        const records = await walletManager.getTransactionHistory(agentId, chain, limit);
+
+        const transactions: TransactionSummary[] = records.map((tx: WalletTransactionRecord) => ({
+          id: tx.id,
+          txHash: tx.txHash,
+          direction: tx.direction,
+          to: tx.toAddress,
+          from: tx.fromAddress,
+          amount: tx.amountUsd != null ? `$${tx.amountUsd.toFixed(2)}` : tx.amountRaw,
+          token: tx.token,
+          category: tx.category,
+          status: tx.status,
+          date: new Date(tx.createdAt).toISOString(),
+          description: tx.description,
+        }));
+
+        return {
+          success: true,
+          output: {
+            chain,
+            address: wallet.address,
+            transactions,
+            totalCount: transactions.length,
+          },
+        };
+      } catch (err: any) {
+        return { success: false, error: err.message || String(err) };
+      }
+    },
+  };
+}