@framers/agentos-ext-wallet 0.2.0 → 0.2.1

package/src/index.ts

@@ -1,315 +0,0 @@
-// @ts-nocheck
-/**
- * @fileoverview Agent Personal Wallet Extension Pack.
- *
- * Provides autonomous crypto spending tools with configurable guardrails:
- * - check_wallet_balance — query balances across Solana/EVM chains
- * - send_crypto — send with spending policy enforcement
- * - wallet_transaction_history — view recent transactions
- *
- * @module @framers/agentos-ext-wallet
- */
-
-import { AgentWalletManager } from './AgentWalletManager.js';
-import { SpendingPolicyEnforcer } from './SpendingPolicyEnforcer.js';
-import { SolanaWalletAdapter } from './chains/SolanaWalletAdapter.js';
-import { EvmWalletAdapter } from './chains/EvmWalletAdapter.js';
-import { createCheckBalanceTool } from './tools/CheckBalanceTool.js';
-import { createSendCryptoTool } from './tools/SendCryptoTool.js';
-import { createWalletHistoryTool } from './tools/WalletHistoryTool.js';
-import { createIssueCardTool } from './tools/IssueCardTool.js';
-import { createCardStatusTool } from './tools/CardStatusTool.js';
-import { createFreezeCardTool } from './tools/FreezeCardTool.js';
-import { createUnfreezeCardTool } from './tools/UnfreezeCardTool.js';
-import { createCardSpendingSummaryTool } from './tools/CardSpendingSummaryTool.js';
-import { createPayWithCardTool } from './tools/PayWithCardTool.js';
-import { CardManager } from './cards/CardManager.js';
-import { LithicCardAdapter } from './cards/LithicCardAdapter.js';
-import { MccCategoryMap } from './cards/MccCategoryMap.js';
-import { DEFAULT_SPENDING_POLICY } from './types.js';
-import type { ChainId, WalletConfig } from './types.js';
-import type { CardConfig, ICardStore, AgentCardRecord, CardTransactionRecord, CardState, CardTxStatus } from './cards/types.js';
-
-/* ------------------------------------------------------------------ */
-/*  Extension pack types                                               */
-/* ------------------------------------------------------------------ */
-
-export interface ExtensionContext {
-  options?: Record<string, unknown>;
-  secrets?: Record<string, string>;
-  getSecret?: (key: string) => string | undefined;
-  logger?: { info: (msg: string) => void; warn?: (msg: string) => void };
-}
-
-export interface ExtensionPack {
-  name: string;
-  version: string;
-  descriptors: Array<{
-    id: string;
-    kind: string;
-    priority?: number;
-    payload: unknown;
-  }>;
-  onActivate?: () => Promise<void>;
-  onDeactivate?: () => Promise<void>;
-}
-
-/* ------------------------------------------------------------------ */
-/*  In-memory stores (CLI/ephemeral — production would use DB)         */
-/* ------------------------------------------------------------------ */
-
-function createMemoryLedgerStore() {
-  const data: Array<{ agentId: string; category: string; amountUsd: number; periodKey: string }> = [];
-  return {
-    async sumByPeriod(agentId: string, periodKey: string) {
-      return data.filter(e => e.agentId === agentId && e.periodKey === periodKey)
-        .reduce((sum, e) => sum + e.amountUsd, 0);
-    },
-    async sumByCategoryAndPeriod(agentId: string, category: string, periodKey: string) {
-      return data.filter(e => e.agentId === agentId && e.category === category && e.periodKey === periodKey)
-        .reduce((sum, e) => sum + e.amountUsd, 0);
-    },
-    async insert(entry: any) { data.push(entry); },
-  };
-}
-
-function createMemoryWalletStore() {
-  const walletRecords = new Map<string, any>();
-  const txRecords = new Map<string, any[]>();
-  return {
-    async getWallet(agentId: string, chain: string) {
-      return walletRecords.get(`${agentId}:${chain}`) || null;
-    },
-    async getAllWallets(agentId: string) {
-      return [...walletRecords.values()].filter((w: any) => w.agentId === agentId);
-    },
-    async saveWallet(record: any) {
-      walletRecords.set(`${record.agentId}:${record.chain}`, record);
-    },
-    async insertTransaction(record: any) {
-      const list = txRecords.get(record.walletId) || [];
-      list.push(record);
-      txRecords.set(record.walletId, list);
-    },
-    async updateTransactionStatus(id: string, status: string, txHash?: string) {
-      for (const [, list] of txRecords) {
-        const tx = list.find((t: any) => t.id === id);
-        if (tx) { tx.status = status; if (txHash) tx.txHash = txHash; return; }
-      }
-    },
-    async getTransactions(walletId: string, limit = 20) {
-      return (txRecords.get(walletId) || []).slice(-limit).reverse();
-    },
-  };
-}
-
-function createMemoryCardStore(): ICardStore {
-  const cards = new Map<string, AgentCardRecord>();
-  const txRecords = new Map<string, CardTransactionRecord[]>();
-  return {
-    async getCard(agentId: string) {
-      return [...cards.values()].find(c => c.agentId === agentId) || null;
-    },
-    async saveCard(record: AgentCardRecord) {
-      cards.set(record.id, record);
-    },
-    async updateCardState(agentId: string, state: CardState) {
-      for (const card of cards.values()) {
-        if (card.agentId === agentId) { card.state = state; return; }
-      }
-    },
-    async insertTransaction(record: CardTransactionRecord) {
-      const list = txRecords.get(record.cardId) || [];
-      list.push(record);
-      txRecords.set(record.cardId, list);
-    },
-    async updateTransactionStatus(id: string, status: CardTxStatus) {
-      for (const [, list] of txRecords) {
-        const tx = list.find(t => t.id === id);
-        if (tx) { tx.status = status; return; }
-      }
-    },
-    async getTransactions(cardId: string, limit = 20) {
-      return (txRecords.get(cardId) || []).slice(-limit).reverse();
-    },
-    async getTransactionsByPeriod(cardId: string, since: number) {
-      return (txRecords.get(cardId) || []).filter(t => t.createdAt >= since);
-    },
-  };
-}
-
-/* ------------------------------------------------------------------ */
-/*  Factory                                                            */
-/* ------------------------------------------------------------------ */
-
-export function createExtensionPack(context: ExtensionContext): ExtensionPack {
-  const opts = (context.options || {}) as Partial<WalletConfig>;
-  const walletConfig: WalletConfig = {
-    enabled: opts.enabled ?? true,
-    chains: opts.chains || ['solana'],
-    custodyMode: opts.custodyMode || 'encrypted-hot',
-    allowedTokens: opts.allowedTokens || ['SOL', 'USDC'],
-    spendingPolicy: opts.spendingPolicy || DEFAULT_SPENDING_POLICY,
-    card: (opts as any).card,
-  };
-
-  // Build chain adapters
-  const adapters = new Map<ChainId, any>();
-  for (const chain of walletConfig.chains) {
-    if (chain === 'solana') adapters.set('solana', new SolanaWalletAdapter());
-    else adapters.set(chain, new EvmWalletAdapter({ chain }));
-  }
-
-  const masterSecret =
-    context.getSecret?.('WALLET_MASTER_SECRET')
-    || context.secrets?.['WALLET_MASTER_SECRET']
-    || process.env['WALLET_MASTER_SECRET']
-    || 'dev-secret-change-me';
-
-  const policyEnforcer = new SpendingPolicyEnforcer(walletConfig.spendingPolicy, createMemoryLedgerStore());
-
-  const walletManager = new AgentWalletManager({
-    masterSecret,
-    walletConfig,
-    store: createMemoryWalletStore(),
-    policyEnforcer,
-    adapters,
-  });
-
-  const checkBalance = createCheckBalanceTool(walletManager);
-  const sendCrypto = createSendCryptoTool(walletManager);
-  const walletHistory = createWalletHistoryTool(walletManager);
-
-  const descriptors: ExtensionPack['descriptors'] = [
-    { id: checkBalance.name, kind: 'tool' as const, priority: 50, payload: checkBalance },
-    { id: sendCrypto.name, kind: 'tool' as const, priority: 50, payload: sendCrypto },
-    { id: walletHistory.name, kind: 'tool' as const, priority: 50, payload: walletHistory },
-  ];
-
-  // Card tools (Lithic) — only if card config is enabled
-  let cardManager: CardManager | undefined;
-  const cardConfig = walletConfig.card;
-  if (cardConfig?.enabled) {
-    const lithicApiKey =
-      context.getSecret?.('LITHIC_API_KEY')
-      || context.secrets?.['LITHIC_API_KEY']
-      || process.env['LITHIC_API_KEY']
-      || '';
-
-    const lithicAdapter = new LithicCardAdapter({
-      apiKey: lithicApiKey,
-      sandbox: process.env['NODE_ENV'] !== 'production',
-    });
-
-    const mccMap = new MccCategoryMap();
-
-    cardManager = new CardManager({
-      adapter: lithicAdapter,
-      store: createMemoryCardStore(),
-      policyEnforcer,
-      mccMap,
-      config: cardConfig,
-    });
-
-    const issueCard = createIssueCardTool(cardManager);
-    const cardStatus = createCardStatusTool(cardManager);
-    const freezeCard = createFreezeCardTool(cardManager);
-    const unfreezeCard = createUnfreezeCardTool(cardManager);
-    const cardSpending = createCardSpendingSummaryTool(cardManager);
-    const payWithCard = createPayWithCardTool(cardManager);
-
-    descriptors.push(
-      { id: issueCard.name, kind: 'tool' as const, priority: 50, payload: issueCard },
-      { id: cardStatus.name, kind: 'tool' as const, priority: 50, payload: cardStatus },
-      { id: freezeCard.name, kind: 'tool' as const, priority: 50, payload: freezeCard },
-      { id: unfreezeCard.name, kind: 'tool' as const, priority: 50, payload: unfreezeCard },
-      { id: cardSpending.name, kind: 'tool' as const, priority: 50, payload: cardSpending },
-      { id: payWithCard.name, kind: 'tool' as const, priority: 50, payload: payWithCard },
-    );
-  }
-
-  const features: string[] = [`chains: ${walletConfig.chains.join(', ')}`];
-  if (cardConfig?.enabled) features.push('virtual card (Lithic)');
-
-  return {
-    name: '@framers/agentos-ext-wallet',
-    version: '0.2.0',
-    descriptors,
-    onActivate: async () => context.logger?.info(`Wallet extension activated (${features.join(', ')})`),
-    onDeactivate: async () => context.logger?.info('Wallet extension deactivated'),
-  };
-}
-
-/* ------------------------------------------------------------------ */
-/*  Re-exports                                                         */
-/* ------------------------------------------------------------------ */
-
-// Core
-export { AgentWalletManager, ApprovalRequiredError, SpendingPolicyViolation } from './AgentWalletManager.js';
-export type { AgentWalletManagerOptions, IWalletStore } from './AgentWalletManager.js';
-export { SpendingPolicyEnforcer } from './SpendingPolicyEnforcer.js';
-export type { ISpendingLedgerStore } from './SpendingPolicyEnforcer.js';
-
-// Types
-export type {
-  AgentWalletRecord,
-  CategoryBudget,
-  ChainId,
-  IChainWalletAdapter,
-  SpendCategory,
-  SpendCheckResult,
-  SpendingLedgerEntry,
-  SpendingPolicyConfig,
-  TokenInfo,
-  TokenSymbol,
-  WalletConfig,
-  WalletDirection,
-  WalletTransactionRecord,
-  WalletTxStatus,
-} from './types.js';
-export { DEFAULT_SPENDING_POLICY, DEFAULT_WALLET_CONFIG } from './types.js';
-
-// Chain adapters
-export { SolanaWalletAdapter } from './chains/SolanaWalletAdapter.js';
-export type { SolanaWalletAdapterOptions } from './chains/SolanaWalletAdapter.js';
-export { EvmWalletAdapter, KNOWN_TOKENS } from './chains/EvmWalletAdapter.js';
-export type { EvmWalletAdapterOptions } from './chains/EvmWalletAdapter.js';
-
-// Tool factories — crypto
-export { createCheckBalanceTool } from './tools/CheckBalanceTool.js';
-export { createSendCryptoTool } from './tools/SendCryptoTool.js';
-export { createWalletHistoryTool } from './tools/WalletHistoryTool.js';
-
-// Tool factories — card
-export { createIssueCardTool } from './tools/IssueCardTool.js';
-export { createCardStatusTool } from './tools/CardStatusTool.js';
-export { createFreezeCardTool } from './tools/FreezeCardTool.js';
-export { createUnfreezeCardTool } from './tools/UnfreezeCardTool.js';
-export { createCardSpendingSummaryTool } from './tools/CardSpendingSummaryTool.js';
-export { createPayWithCardTool } from './tools/PayWithCardTool.js';
-
-// Card subsystem
-export { CardManager } from './cards/CardManager.js';
-export type { CardManagerOptions } from './cards/CardManager.js';
-export { CardSpendingBlockedError } from './cards/CardManager.js';
-export { LithicCardAdapter, LithicApiError } from './cards/LithicCardAdapter.js';
-export type { LithicCardAdapterOptions } from './cards/LithicCardAdapter.js';
-export { MccCategoryMap } from './cards/MccCategoryMap.js';
-export type {
-  AgentCardRecord,
-  CardConfig,
-  CardTransactionRecord,
-  CardTxStatus,
-  CardState,
-  CardType,
-  CardNetwork,
-  ICardAdapter,
-  ICardStore,
-  LithicCardResponse,
-  LithicTransaction,
-  SpendingSummary,
-  SpendLimitDuration,
-} from './cards/types.js';
-export { DEFAULT_CARD_CONFIG } from './cards/types.js';
-
-export default createExtensionPack;

package/src/tools/CardSpendingSummaryTool.ts

@@ -1,52 +0,0 @@
-// @ts-nocheck
-/**
- * @fileoverview Agent-callable tool for card spending breakdown.
- * @module wallet/tools/CardSpendingSummaryTool
- */
-
-import type { ITool, ToolExecutionContext, ToolExecutionResult } from '@framers/agentos/core/tools/ITool';
-import type { CardManager } from '../cards/CardManager.js';
-import type { SpendingSummary } from '../cards/types.js';
-
-interface SpendingSummaryInput {
-  /** Time period: 'day' or 'month'. Defaults to 'month'. */
-  period?: 'day' | 'month';
-}
-
-export function createCardSpendingSummaryTool(cardManager: CardManager): ITool<SpendingSummaryInput, SpendingSummary> {
-  return {
-    id: 'wallet-card-spending-summary-v1',
-    name: 'card_spending_summary',
-    displayName: 'Card Spending Summary',
-    description:
-      'Get a spending breakdown for the agent\'s virtual card, grouped by category '
-      + '(dining, shopping, subscriptions, etc.). Shows daily or monthly totals.',
-    category: 'wallet',
-    version: '1.0.0',
-    hasSideEffects: false,
-    requiredCapabilities: ['capability:wallet', 'capability:wallet_card'],
-
-    inputSchema: {
-      type: 'object',
-      properties: {
-        period: {
-          type: 'string',
-          enum: ['day', 'month'],
-          description: 'Time period for the summary. Defaults to "month".',
-        },
-      },
-    },
-
-    async execute(args: SpendingSummaryInput, context: ToolExecutionContext): Promise<ToolExecutionResult<SpendingSummary>> {
-      try {
-        const agentId = context.gmiId;
-        const period = args.period || 'month';
-        const summary = await cardManager.getSpendingSummary(agentId, period);
-
-        return { success: true, output: summary };
-      } catch (err: any) {
-        return { success: false, error: err.message || String(err) };
-      }
-    },
-  };
-}

package/src/tools/CardStatusTool.ts

@@ -1,68 +0,0 @@
-// @ts-nocheck
-/**
- * @fileoverview Agent-callable tool for checking card status.
- * @module wallet/tools/CardStatusTool
- */
-
-import type { ITool, ToolExecutionContext, ToolExecutionResult } from '@framers/agentos/core/tools/ITool';
-import type { CardManager } from '../cards/CardManager.js';
-
-interface CardStatusInput {}
-
-interface CardStatusOutput {
-  cardId: string;
-  last4: string;
-  state: string;
-  cardType: string;
-  spendLimitUsd: number;
-  spendLimitDuration: string;
-  network: string;
-  memo?: string;
-}
-
-export function createCardStatusTool(cardManager: CardManager): ITool<CardStatusInput, CardStatusOutput> {
-  return {
-    id: 'wallet-card-status-v1',
-    name: 'card_status',
-    displayName: 'Card Status',
-    description:
-      'Get the current status of the agent\'s virtual card, including state (OPEN/PAUSED/CLOSED), '
-      + 'spending limit, and card type.',
-    category: 'wallet',
-    version: '1.0.0',
-    hasSideEffects: false,
-    requiredCapabilities: ['capability:wallet', 'capability:wallet_card'],
-
-    inputSchema: {
-      type: 'object',
-      properties: {},
-    },
-
-    async execute(_args: CardStatusInput, context: ToolExecutionContext): Promise<ToolExecutionResult<CardStatusOutput>> {
-      try {
-        const agentId = context.gmiId;
-        const card = await cardManager.getCard(agentId);
-
-        if (!card) {
-          return { success: false, error: 'No card found. Issue one first with issue_virtual_card.' };
-        }
-
-        return {
-          success: true,
-          output: {
-            cardId: card.id,
-            last4: card.last4,
-            state: card.state,
-            cardType: card.cardType,
-            spendLimitUsd: card.spendLimitUsd,
-            spendLimitDuration: card.spendLimitDuration,
-            network: card.network,
-            memo: card.memo,
-          },
-        };
-      } catch (err: any) {
-        return { success: false, error: err.message || String(err) };
-      }
-    },
-  };
-}

package/src/tools/CheckBalanceTool.ts

@@ -1,145 +0,0 @@
-// @ts-nocheck
-/**
- * @fileoverview Agent-callable tool for checking wallet balances.
- * @module wunderland/wallet/tools/CheckBalanceTool
- */
-
-import type { ITool, ToolExecutionContext, ToolExecutionResult } from '@framers/agentos/core/tools/ITool';
-import type { AgentWalletManager } from '../AgentWalletManager.js';
-import type { ChainId, TokenSymbol } from '../types.js';
-
-interface CheckBalanceInput {
-  /** Chain to check. Defaults to 'solana'. */
-  chain?: ChainId;
-  /** Token symbol. If omitted, returns native token balance. */
-  token?: TokenSymbol;
-}
-
-interface BalanceOutput {
-  chain: ChainId;
-  address: string;
-  token: string;
-  balanceRaw: string;
-  balanceFormatted: string;
-}
-
-/** Well-known SPL / ERC-20 mint addresses for balance lookups. */
-const TOKEN_MINTS: Record<string, Record<string, string>> = {
-  solana: {
-    USDC: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
-    USDT: 'Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB',
-  },
-  ethereum: {
-    USDC: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
-    USDT: '0xdAC17F958D2ee523a2206206994597C13D831ec7',
-  },
-  base: {
-    USDC: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
-    USDT: '0xfde4C96c8593536E31F229EA8f37b2ADa2699bb2',
-  },
-  polygon: {
-    USDC: '0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359',
-    USDT: '0xc2132D05D31c914a87C6611C10748AEb04B58e8F',
-  },
-};
-
-const DECIMALS: Record<string, number> = {
-  SOL: 9,
-  ETH: 18,
-  USDC: 6,
-  USDT: 6,
-};
-
-function formatBalance(raw: bigint, decimals: number): string {
-  const str = raw.toString().padStart(decimals + 1, '0');
-  const intPart = str.slice(0, str.length - decimals) || '0';
-  const fracPart = str.slice(str.length - decimals);
-  // Trim trailing zeros but keep at least 2 decimal places
-  const trimmed = fracPart.replace(/0+$/, '').padEnd(2, '0');
-  return `${intPart}.${trimmed}`;
-}
-
-export function createCheckBalanceTool(walletManager: AgentWalletManager): ITool<CheckBalanceInput, BalanceOutput> {
-  return {
-    id: 'wallet-check-balance-v1',
-    name: 'check_wallet_balance',
-    displayName: 'Check Wallet Balance',
-    description:
-      'Check the balance of the agent\'s personal wallet on a given blockchain. '
-      + 'Returns the balance in both raw units and human-readable format. '
-      + 'Supports SOL (Solana), ETH (Ethereum/Base), USDC, and USDT.',
-    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.',
-        },
-        token: {
-          type: 'string',
-          enum: ['SOL', 'ETH', 'USDC', 'USDT'],
-          description: 'Token to check. Omit for native token (SOL/ETH).',
-        },
-      },
-    },
-
-    async execute(args: CheckBalanceInput, context: ToolExecutionContext): Promise<ToolExecutionResult<BalanceOutput>> {
-      try {
-        const chain: ChainId = args.chain || 'solana';
-        const agentId = context.gmiId;
-
-        const wallet = await walletManager.getWallet(agentId, chain);
-        if (!wallet) {
-          return {
-            success: false,
-            error: `No ${chain} wallet found. Create one first with the wallet setup.`,
-          };
-        }
-
-        let balanceRaw: bigint;
-        let tokenLabel: string;
-
-        const nativeToken = chain === 'solana' ? 'SOL' : 'ETH';
-
-        if (!args.token || args.token === nativeToken) {
-          // Native token balance
-          balanceRaw = await walletManager.getBalance(agentId, chain);
-          tokenLabel = nativeToken;
-        } else {
-          // Token balance
-          const mint = TOKEN_MINTS[chain]?.[args.token];
-          if (!mint) {
-            return {
-              success: false,
-              error: `Token ${args.token} is not supported on ${chain}.`,
-            };
-          }
-          balanceRaw = await walletManager.getTokenBalance(agentId, chain, mint);
-          tokenLabel = args.token;
-        }
-
-        const decimals = DECIMALS[tokenLabel] || 18;
-        const formatted = formatBalance(balanceRaw, decimals);
-
-        return {
-          success: true,
-          output: {
-            chain,
-            address: wallet.address,
-            token: tokenLabel,
-            balanceRaw: balanceRaw.toString(),
-            balanceFormatted: `${formatted} ${tokenLabel}`,
-          },
-        };
-      } catch (err: any) {
-        return { success: false, error: err.message || String(err) };
-      }
-    },
-  };
-}

package/src/tools/FreezeCardTool.ts

@@ -1,52 +0,0 @@
-// @ts-nocheck
-/**
- * @fileoverview Agent-callable tool for freezing (pausing) a card.
- * @module wallet/tools/FreezeCardTool
- */
-
-import type { ITool, ToolExecutionContext, ToolExecutionResult } from '@framers/agentos/core/tools/ITool';
-import type { CardManager } from '../cards/CardManager.js';
-
-interface FreezeCardInput {}
-
-interface FreezeCardOutput {
-  state: string;
-  message: string;
-}
-
-export function createFreezeCardTool(cardManager: CardManager): ITool<FreezeCardInput, FreezeCardOutput> {
-  return {
-    id: 'wallet-freeze-card-v1',
-    name: 'freeze_card',
-    displayName: 'Freeze Card',
-    description:
-      'Temporarily freeze the agent\'s virtual card. All transactions will be declined until '
-      + 'the card is unfrozen. Useful when suspicious activity is detected or to pause spending.',
-    category: 'wallet',
-    version: '1.0.0',
-    hasSideEffects: true,
-    requiredCapabilities: ['capability:wallet', 'capability:wallet_card'],
-
-    inputSchema: {
-      type: 'object',
-      properties: {},
-    },
-
-    async execute(_args: FreezeCardInput, context: ToolExecutionContext): Promise<ToolExecutionResult<FreezeCardOutput>> {
-      try {
-        const agentId = context.gmiId;
-        await cardManager.freezeCard(agentId);
-
-        return {
-          success: true,
-          output: {
-            state: 'PAUSED',
-            message: 'Card has been frozen. All transactions will be declined until unfrozen.',
-          },
-        };
-      } catch (err: any) {
-        return { success: false, error: err.message || String(err) };
-      }
-    },
-  };
-}