@swarmclawai/swarmclaw 0.6.4 → 0.6.7

package/src/lib/server/session-tools/chatroom.ts

@@ -13,7 +13,7 @@ export function buildChatroomTools(bctx: ToolBuildContext): StructuredToolInterf
   if (hasTool('manage_chatrooms')) {
     tools.push(
       tool(
-        async ({ action, chatroomId, name, description, agentIds, agentId, message }) => {
+        async ({ action, chatroomId, name, description, agentIds, agentId, message, chatMode, autoAddress }) => {
           try {
             const chatrooms = loadChatrooms() as Record<string, Chatroom>
 
@@ -31,13 +31,20 @@ export function buildChatroomTools(bctx: ToolBuildContext): StructuredToolInterf
             if (action === 'create_chatroom') {
               const id = genId()
               const agents = loadAgents()
-              const validAgentIds = (agentIds || []).filter((aid: string) => agents[aid])
+              const requestedAgentIds = agentIds || []
+              const invalidAgentIds = requestedAgentIds.filter((aid: string) => !agents[aid])
+              if (invalidAgentIds.length > 0) {
+                return `Error: unknown agent IDs: ${invalidAgentIds.join(', ')}`
+              }
+              const validAgentIds = requestedAgentIds
               const chatroom: Chatroom = {
                 id,
                 name: name || 'New Chatroom',
                 description: description || '',
                 agentIds: validAgentIds,
                 messages: [],
+                chatMode: chatMode === 'parallel' ? 'parallel' : 'sequential',
+                autoAddress: Boolean(autoAddress),
                 createdAt: Date.now(),
                 updatedAt: Date.now(),
               }
@@ -124,6 +131,8 @@ export function buildChatroomTools(bctx: ToolBuildContext): StructuredToolInterf
             name: z.string().optional().describe('Chatroom name (for create_chatroom)'),
             description: z.string().optional().describe('Chatroom description (for create_chatroom)'),
             agentIds: z.array(z.string()).optional().describe('Initial agent IDs (for create_chatroom)'),
+            chatMode: z.enum(['sequential', 'parallel']).optional().describe('Optional orchestration mode for create_chatroom'),
+            autoAddress: z.boolean().optional().describe('Whether to auto-address all members when no @mention is present'),
             agentId: z.string().optional().describe('Agent ID (for add_agent/remove_agent)'),
             message: z.string().optional().describe('Message text (for send_message)'),
           }),

package/src/lib/server/session-tools/context-mgmt.ts

@@ -28,7 +28,7 @@ export function buildContextTools(bctx: ToolBuildContext): StructuredToolInterfa
         },
         {
           name: 'context_status',
-          description: 'Check current context window usage for this session. Returns estimated tokens used, provider context limit, percentage used, and compaction strategy recommendation.',
+          description: 'Check how much of my context window I\'ve used. Returns my token usage, the model\'s limit, percentage used, and whether I should compact.',
           schema: z.object({}),
         },
       ),
@@ -108,7 +108,7 @@ export function buildContextTools(bctx: ToolBuildContext): StructuredToolInterfa
         },
         {
           name: 'context_summarize',
-          description: 'Summarize and compact the conversation history to free context window space. Old messages are consolidated to memory (preserving decisions, key facts, results) and replaced with a summary. Use context_status first to check if compaction is needed.',
+          description: 'Compact my conversation history to free up context space. I\'ll save important decisions, facts, and results to memory, then replace older messages with a summary. I should check context_status first to see if this is needed.',
           schema: z.object({
             keepLastN: z.number().optional().describe('Number of recent messages to keep (default 10, min 2).'),
           }),

package/src/lib/server/session-tools/index.ts

@@ -21,6 +21,8 @@ import { buildSubagentTools } from './subagent'
 import { buildCanvasTools } from './canvas'
 import { buildHttpTools } from './http'
 import { buildGitTools } from './git'
+import { buildWalletTools } from './wallet'
+import { buildOpenClawWorkspaceTools } from './openclaw-workspace'
 
 export type { ToolContext, SessionToolsResult }
 export { sweepOrphanedBrowsers, cleanupSessionBrowser, getActiveBrowserCount, hasActiveBrowser }
@@ -34,7 +36,9 @@ export async function buildSessionTools(cwd: string, enabledTools: string[], ctx
   const cliProcessTimeoutMs = runtime.cliProcessTimeoutMs
   const appSettings = loadSettings()
   const toolPolicy = resolveSessionToolPolicy(enabledTools, appSettings)
-  const activeTools = toolPolicy.enabledTools
+  const activeTools = toolPolicy.enabledTools.includes('shell') && !toolPolicy.enabledTools.includes('process')
+    ? [...toolPolicy.enabledTools, 'process']
+    : toolPolicy.enabledTools
   const hasTool = (toolName: string) => activeTools.includes(toolName)
 
   if (toolPolicy.blockedTools.length > 0) {
@@ -107,6 +111,8 @@ export async function buildSessionTools(cwd: string, enabledTools: string[], ctx
     ...buildCanvasTools(bctx),
     ...buildHttpTools(bctx),
     ...buildGitTools(bctx),
+    ...buildWalletTools(bctx),
+    ...buildOpenClawWorkspaceTools(bctx),
   )
 
   // ---------------------------------------------------------------------------
@@ -158,7 +164,7 @@ export async function buildSessionTools(cwd: string, enabledTools: string[], ctx
       },
       {
         name: 'request_tool_access',
-        description: 'Request access to a tool that is currently disabled. The user will be prompted to grant access, and a follow-up "Continue" message will be sent automatically once granted. End your current response after calling this — do NOT tell the user to "let you know" or ask them to confirm; the continuation is automatic.',
+        description: 'Ask the user for access to a tool I don\'t currently have. They\'ll get a prompt to grant it, and once they do, I\'ll automatically continue where I left off. I should end my current response after calling this — no need to ask the user to confirm, it happens on its own.',
         schema: z.object({
           toolId: z.string().describe('The tool ID to request access for (e.g. manage_tasks, shell, claude_code)'),
           reason: z.string().describe('Brief explanation of why you need this tool'),

package/src/lib/server/session-tools/memory.ts

@@ -165,12 +165,16 @@ export function buildMemoryTools(bctx: ToolBuildContext): StructuredToolInterfac
             if (action === 'knowledge_store') {
               const { addKnowledge } = await import('../memory-db')
               if (!value) return 'Error: value (content) is required for knowledge_store'
+              const source = (input as Record<string, unknown>).source as string | undefined
+              const sourceUrl = (input as Record<string, unknown>).sourceUrl as string | undefined
               const entry = addKnowledge({
                 title: key || 'Untitled',
                 content: value,
                 tags: tags,
                 createdByAgentId: ctx?.agentId || null,
                 createdBySessionId: ctx?.sessionId || null,
+                source: source || undefined,
+                sourceUrl: sourceUrl || undefined,
               })
               return `Knowledge stored: "${entry.title}" (id: ${entry.id})`
             }
@@ -178,16 +182,29 @@ export function buildMemoryTools(bctx: ToolBuildContext): StructuredToolInterfac
               const { searchKnowledge } = await import('../memory-db')
               const results = searchKnowledge(query || key || '', tags, 10)
               if (!results.length) return 'No knowledge entries found.'
-              return results.map(r => `[${r.id}] ${r.title}: ${r.content.slice(0, 200)}`).join('\n---\n')
+              return results.map(r => {
+                const meta = r.metadata as Record<string, unknown> | undefined
+                const src = meta?.source as string | undefined
+                const srcUrl = meta?.sourceUrl as string | undefined
+                let line = `[${r.id}] ${r.title}: ${r.content.slice(0, 200)}`
+                if (src && srcUrl) {
+                  line += ` [${src}](${srcUrl})`
+                } else if (src) {
+                  line += ` (source: ${src})`
+                } else if (srcUrl) {
+                  line += ` (${srcUrl})`
+                }
+                return line
+              }).join('\n---\n')
             }
             return `Unknown action "${action}". Use: store, get, search, list, delete, link, unlink, knowledge_store, or knowledge_search.`
-          } catch (err: any) {
-            return `Error: ${err.message}`
+          } catch (err: unknown) {
+            return `Error: ${err instanceof Error ? err.message : String(err)}`
           }
         },
         {
           name: 'memory_tool',
-          description: 'Store and retrieve long-term memories that persist across sessions. Memories can be shared or agent-scoped. Supports file references, image attachments, and linking memories together with depth traversal. Also supports a cross-agent knowledge base via "knowledge_store" and "knowledge_search". Use "store", "get", "search", "list", "delete", "link", "unlink", "knowledge_store", or "knowledge_search".',
+          description: 'My long-term memory — things I remember across conversations. I can store personal notes, recall past context, and build up knowledge over time. Memories can be private to me or shared with other agents. I can also attach files, link related memories, and contribute to a shared knowledge base. Actions: store, get, search, list, delete, link, unlink, knowledge_store, knowledge_search.',
           schema: z.object({
             action: z.enum(['store', 'get', 'search', 'list', 'delete', 'link', 'unlink', 'knowledge_store', 'knowledge_search']).describe('The action to perform'),
             key: z.string().describe('For store: memory title. For get/delete/link/unlink: memory ID. For search: optional query fallback.'),
@@ -224,6 +241,8 @@ export function buildMemoryTools(bctx: ToolBuildContext): StructuredToolInterfac
             linkedLimit: z.number().optional().describe('Max linked memories expanded during traversal. Respects configured server cap.'),
             targetIds: z.array(z.string()).optional().describe('Memory IDs to link/unlink (for link/unlink actions)'),
             tags: z.array(z.string()).optional().describe('Tags for categorizing knowledge entries'),
+            source: z.string().optional().describe("Source of the knowledge, e.g. 'user', 'web', 'document'"),
+            sourceUrl: z.string().optional().describe('URL where the knowledge was sourced from'),
             pinned: z.boolean().optional().describe('Mark memory as pinned (always preloaded in agent context). For store action.'),
             sharedWith: z.array(z.string()).optional().describe('Agent IDs to share this memory with (for store action). They can read it in their context.'),
           }),

package/src/lib/server/session-tools/openclaw-workspace.ts

@@ -0,0 +1,132 @@
+import { z } from 'zod'
+import { tool, type StructuredToolInterface } from '@langchain/core/tools'
+import { execFile } from 'child_process'
+import { promisify } from 'util'
+import * as path from 'path'
+import * as os from 'os'
+import { loadSettings } from '../storage'
+import type { ToolBuildContext } from './context'
+import { MAX_OUTPUT } from './context'
+
+const execFileAsync = promisify(execFile)
+
+function resolveWorkspacePath(): string {
+  const settings = loadSettings()
+  if (typeof settings.openclawWorkspacePath === 'string' && settings.openclawWorkspacePath.trim()) {
+    return settings.openclawWorkspacePath.trim()
+  }
+  return path.join(os.homedir(), '.openclaw', 'workspace')
+}
+
+async function gitInWorkspace(args: string[], timeoutMs = 15_000): Promise<{ stdout: string; stderr: string }> {
+  const cwd = resolveWorkspacePath()
+  return execFileAsync('git', args, {
+    cwd,
+    timeout: timeoutMs,
+    maxBuffer: MAX_OUTPUT,
+    env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+  })
+}
+
+export function buildOpenClawWorkspaceTools(bctx: ToolBuildContext): StructuredToolInterface[] {
+  if (!bctx.hasTool('openclaw_workspace')) return []
+
+  return [
+    tool(
+      async ({ message }) => {
+        try {
+          const workspace = resolveWorkspacePath()
+          // Verify it's a git repo
+          await execFileAsync('git', ['rev-parse', '--is-inside-work-tree'], {
+            cwd: workspace,
+            timeout: 5000,
+          })
+
+          const label = message || new Date().toISOString().replace(/[:.]/g, '-')
+          await gitInWorkspace(['add', '-A'])
+
+          // Check if there's anything to commit
+          const status = await gitInWorkspace(['status', '--porcelain'])
+          if (!status.stdout.trim()) {
+            return JSON.stringify({ ok: true, commitHash: null, message: 'Nothing to commit — workspace is clean.' })
+          }
+
+          await gitInWorkspace(['commit', '-m', `backup: ${label}`])
+          const { stdout } = await gitInWorkspace(['rev-parse', 'HEAD'])
+          return JSON.stringify({ ok: true, commitHash: stdout.trim() })
+        } catch (err: unknown) {
+          const execErr = err as { stderr?: string; message?: string }
+          return JSON.stringify({ ok: false, error: execErr.stderr || execErr.message || String(err) })
+        }
+      },
+      {
+        name: 'openclaw_workspace_backup',
+        description: 'Create a git backup of the OpenClaw workspace. Stages all changes and commits.',
+        schema: z.object({
+          message: z.string().optional().describe('Optional backup message (defaults to timestamp)'),
+        }),
+      },
+    ),
+    tool(
+      async ({ commitHash }) => {
+        try {
+          if (!commitHash) {
+            // Find first stable commit (skip auto-generated ones)
+            const { stdout } = await gitInWorkspace(['log', '--oneline', '--format=%H %s', '-50'])
+            const lines = stdout.trim().split('\n').filter(Boolean)
+            const autoPattern = /^(rollback|daily-backup|auto-backup|guardian-auto|backup:)/i
+            const stable = lines.find((line) => {
+              const msg = line.substring(41) // after hash + space
+              return !autoPattern.test(msg)
+            })
+            if (!stable) {
+              return JSON.stringify({ ok: false, error: 'No stable commit found to roll back to.' })
+            }
+            commitHash = stable.substring(0, 40)
+          }
+
+          const { stdout: prevHead } = await gitInWorkspace(['rev-parse', 'HEAD'])
+          await gitInWorkspace(['reset', '--hard', commitHash])
+          return JSON.stringify({ ok: true, rolledBackTo: commitHash, previousHead: prevHead.trim() })
+        } catch (err: unknown) {
+          const execErr = err as { stderr?: string; message?: string }
+          return JSON.stringify({ ok: false, error: execErr.stderr || execErr.message || String(err) })
+        }
+      },
+      {
+        name: 'openclaw_workspace_rollback',
+        description: 'Roll back the OpenClaw workspace to a specific commit, or automatically find the last stable (non-auto-generated) commit.',
+        schema: z.object({
+          commitHash: z.string().optional().describe('Target commit hash (if omitted, uses the last stable commit)'),
+        }),
+      },
+    ),
+    tool(
+      async ({ limit }) => {
+        try {
+          const count = Math.max(1, Math.min(limit ?? 20, 100))
+          const { stdout } = await gitInWorkspace(['log', '--oneline', `--format=%H %s`, `-${count}`])
+          const commits = stdout
+            .trim()
+            .split('\n')
+            .filter(Boolean)
+            .map((line) => ({
+              hash: line.substring(0, 40),
+              message: line.substring(41),
+            }))
+          return JSON.stringify({ commits })
+        } catch (err: unknown) {
+          const execErr = err as { stderr?: string; message?: string }
+          return JSON.stringify({ ok: false, error: execErr.stderr || execErr.message || String(err) })
+        }
+      },
+      {
+        name: 'openclaw_workspace_history',
+        description: 'List recent git commits in the OpenClaw workspace.',
+        schema: z.object({
+          limit: z.number().optional().describe('Number of commits to return (default 20, max 100)'),
+        }),
+      },
+    ),
+  ]
+}

package/src/lib/server/session-tools/shell.ts

@@ -49,7 +49,7 @@ export function buildShellTools(bctx: ToolBuildContext): StructuredToolInterface
         },
         {
           name: 'execute_command',
-          description: 'Execute a shell command in the session working directory. This is the PRIMARY tool for running servers, dev servers, installing packages, running scripts, git operations, and any command the user wants to run or test. Use background=true for long-running processes like servers. Supports timeout/yield controls.',
+          description: 'Run a shell command in my working directory. This is how I run servers, install packages, execute scripts, use git, and do anything hands-on. Use background=true for long-running processes like dev servers. Supports timeout/yield controls.',
           schema: z.object({
             command: z.string().describe('The shell command to execute'),
             background: z.boolean().optional().describe('If true, start command in background immediately'),

package/src/lib/server/session-tools/wallet.ts

@@ -0,0 +1,124 @@
+import { z } from 'zod'
+import { tool, type StructuredToolInterface } from '@langchain/core/tools'
+import type { ToolBuildContext } from './context'
+import { loadWallets, loadWalletTransactions } from '../storage'
+import type { AgentWallet, WalletTransaction } from '@/types'
+
+export function buildWalletTools(bctx: ToolBuildContext): StructuredToolInterface[] {
+  if (!bctx.hasTool('wallet')) return []
+
+  const agentId = bctx.ctx?.agentId
+
+  function getAgentWallet(): AgentWallet | null {
+    if (!agentId) return null
+    const wallets = loadWallets() as Record<string, AgentWallet>
+    return Object.values(wallets).find((w) => w.agentId === agentId) ?? null
+  }
+
+  return [
+    tool(
+      async ({ action, toAddress, amountSol, memo, limit }) => {
+        const wallet = getAgentWallet()
+        if (!wallet) {
+          return JSON.stringify({ error: 'No wallet linked to this agent. Ask the user to create one in the Wallets section.' })
+        }
+
+        switch (action) {
+          case 'balance': {
+            try {
+              const { getBalance, lamportsToSol } = await import('../solana')
+              const balanceLamports = await getBalance(wallet.publicKey)
+              return JSON.stringify({
+                address: wallet.publicKey,
+                chain: wallet.chain,
+                balanceLamports,
+                balanceSol: lamportsToSol(balanceLamports),
+              })
+            } catch (err: unknown) {
+              return JSON.stringify({ error: `Failed to fetch balance: ${err instanceof Error ? err.message : String(err)}` })
+            }
+          }
+
+          case 'address': {
+            return JSON.stringify({
+              address: wallet.publicKey,
+              chain: wallet.chain,
+            })
+          }
+
+          case 'send': {
+            if (!toAddress) return JSON.stringify({ error: 'toAddress is required for send action' })
+            if (!amountSol || amountSol <= 0) return JSON.stringify({ error: 'amountSol must be positive' })
+
+            const { isValidSolanaAddress, solToLamports, lamportsToSol } = await import('../solana')
+            if (!isValidSolanaAddress(toAddress)) {
+              return JSON.stringify({ error: 'Invalid Solana address' })
+            }
+
+            const amountLamports = solToLamports(amountSol)
+
+            // Check per-tx limit
+            const perTxLimit = wallet.spendingLimitLamports ?? 100_000_000
+            if (amountLamports > perTxLimit) {
+              return JSON.stringify({
+                error: `Amount ${amountSol} SOL exceeds per-transaction limit of ${lamportsToSol(perTxLimit)} SOL`,
+              })
+            }
+
+            // Send via API to enforce all limits and approval flow
+            try {
+              const baseUrl = process.env.NEXTAUTH_URL || `http://localhost:${process.env.PORT || 3456}`
+              const res = await fetch(`${baseUrl}/api/wallets/${wallet.id}/send`, {
+                method: 'POST',
+                headers: {
+                  'Content-Type': 'application/json',
+                  'X-Access-Key': process.env.ACCESS_KEY || '',
+                },
+                body: JSON.stringify({ toAddress, amountLamports, memo }),
+              })
+              const result = await res.json()
+              return JSON.stringify(result)
+            } catch (err: unknown) {
+              return JSON.stringify({ error: `Send failed: ${err instanceof Error ? err.message : String(err)}` })
+            }
+          }
+
+          case 'transactions': {
+            const allTxs = loadWalletTransactions() as Record<string, WalletTransaction>
+            const walletTxs = Object.values(allTxs)
+              .filter((tx) => tx.walletId === wallet.id)
+              .sort((a, b) => b.timestamp - a.timestamp)
+              .slice(0, limit ?? 10)
+              .map((tx) => ({
+                id: tx.id,
+                type: tx.type,
+                status: tx.status,
+                amountLamports: tx.amountLamports,
+                toAddress: tx.toAddress,
+                fromAddress: tx.fromAddress,
+                signature: tx.signature || undefined,
+                memo: tx.memo,
+                timestamp: tx.timestamp,
+              }))
+
+            return JSON.stringify({ transactions: walletTxs, count: walletTxs.length })
+          }
+
+          default:
+            return JSON.stringify({ error: `Unknown action: ${action}. Use balance, address, send, or transactions.` })
+        }
+      },
+      {
+        name: 'wallet_tool',
+        description: 'Manage your own crypto wallet. Actions: balance (check your SOL balance), address (get your wallet address), send (send SOL from your wallet — subject to your spending limits and user approval), transactions (view your recent transaction history).',
+        schema: z.object({
+          action: z.enum(['balance', 'address', 'send', 'transactions']).describe('Wallet action to perform'),
+          toAddress: z.string().optional().describe('Recipient Solana address (required for send)'),
+          amountSol: z.number().optional().describe('Amount in SOL to send (required for send)'),
+          memo: z.string().optional().describe('Reason or memo for the transaction'),
+          limit: z.number().optional().describe('Number of transactions to return (default 10, for transactions action)'),
+        }),
+      },
+    ),
+  ]
+}

package/src/lib/server/session-tools/web.ts

@@ -141,7 +141,7 @@ export function buildWebTools(bctx: ToolBuildContext): StructuredToolInterface[]
         },
         {
           name: 'web_search',
-          description: 'Search the web. Returns an array of results with title, url, and snippet.',
+          description: 'Search the web for information. Returns results with title, url, and snippet.',
           schema: z.object({
             query: z.string().describe('Search query'),
             maxResults: z.number().optional().describe('Maximum results to return (default 5, max 10)'),
@@ -179,7 +179,7 @@ export function buildWebTools(bctx: ToolBuildContext): StructuredToolInterface[]
         },
         {
           name: 'web_fetch',
-          description: 'Fetch a URL and return its text content (HTML stripped). Useful for reading web pages.',
+          description: 'Fetch a URL and read its content (HTML stripped to text). How I read web pages and pull in external information.',
           schema: z.object({
             url: z.string().describe('The URL to fetch'),
           }),

package/src/lib/server/solana.ts

@@ -0,0 +1,122 @@
+import { Keypair, Connection, PublicKey, SystemProgram, Transaction, LAMPORTS_PER_SOL, sendAndConfirmTransaction } from '@solana/web3.js'
+import bs58 from 'bs58'
+import { encryptKey, decryptKey } from './storage'
+
+const DEFAULT_RPC_URL = process.env.SOLANA_RPC_URL || 'https://api.mainnet-beta.solana.com'
+
+// ---------------------------------------------------------------------------
+// Keypair generation & encryption
+// ---------------------------------------------------------------------------
+
+export function generateSolanaKeypair(): { publicKey: string; encryptedPrivateKey: string } {
+  const keypair = Keypair.generate()
+  const secretKeyBase58 = bs58.encode(keypair.secretKey)
+  return {
+    publicKey: keypair.publicKey.toBase58(),
+    encryptedPrivateKey: encryptKey(secretKeyBase58),
+  }
+}
+
+export function getKeypairFromEncrypted(encryptedPrivateKey: string): Keypair {
+  const secretKeyBase58 = decryptKey(encryptedPrivateKey)
+  const secretKey = bs58.decode(secretKeyBase58)
+  return Keypair.fromSecretKey(secretKey)
+}
+
+// ---------------------------------------------------------------------------
+// Connection
+// ---------------------------------------------------------------------------
+
+export function getConnection(rpcUrl?: string): Connection {
+  return new Connection(rpcUrl || DEFAULT_RPC_URL, 'confirmed')
+}
+
+// ---------------------------------------------------------------------------
+// Balance
+// ---------------------------------------------------------------------------
+
+export async function getBalance(publicKey: string, rpcUrl?: string): Promise<number> {
+  const connection = getConnection(rpcUrl)
+  const pk = new PublicKey(publicKey)
+  return connection.getBalance(pk)
+}
+
+// ---------------------------------------------------------------------------
+// Send SOL
+// ---------------------------------------------------------------------------
+
+export async function sendSol(
+  encryptedPrivateKey: string,
+  toAddress: string,
+  lamports: number,
+  rpcUrl?: string,
+): Promise<{ signature: string; fee: number }> {
+  const connection = getConnection(rpcUrl)
+  const fromKeypair = getKeypairFromEncrypted(encryptedPrivateKey)
+  const toPublicKey = new PublicKey(toAddress)
+
+  const transaction = new Transaction().add(
+    SystemProgram.transfer({
+      fromPubkey: fromKeypair.publicKey,
+      toPubkey: toPublicKey,
+      lamports,
+    }),
+  )
+
+  const signature = await sendAndConfirmTransaction(connection, transaction, [fromKeypair])
+
+  // Fetch fee from confirmed tx
+  let fee = 5000 // default fee estimate
+  try {
+    const txInfo = await connection.getTransaction(signature, { commitment: 'confirmed' })
+    if (txInfo?.meta?.fee) fee = txInfo.meta.fee
+  } catch {
+    // use default
+  }
+
+  return { signature, fee }
+}
+
+// ---------------------------------------------------------------------------
+// Recent transactions
+// ---------------------------------------------------------------------------
+
+export async function getRecentTransactions(
+  publicKey: string,
+  limit = 20,
+  rpcUrl?: string,
+): Promise<Array<{ signature: string; blockTime: number | null; err: unknown }>> {
+  const connection = getConnection(rpcUrl)
+  const pk = new PublicKey(publicKey)
+  const signatures = await connection.getSignaturesForAddress(pk, { limit })
+  return signatures.map((s) => ({
+    signature: s.signature,
+    blockTime: s.blockTime ?? null,
+    err: s.err,
+  }))
+}
+
+// ---------------------------------------------------------------------------
+// Validate address
+// ---------------------------------------------------------------------------
+
+export function isValidSolanaAddress(address: string): boolean {
+  try {
+    new PublicKey(address)
+    return true
+  } catch {
+    return false
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+export function lamportsToSol(lamports: number): number {
+  return lamports / LAMPORTS_PER_SOL
+}
+
+export function solToLamports(sol: number): number {
+  return Math.round(sol * LAMPORTS_PER_SOL)
+}