@darksol/terminal 0.9.0 → 0.9.2

package/README.md

@@ -15,7 +15,7 @@ A unified CLI for market intel, trading, AI-powered analysis, on-chain oracle, c
 [![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-gold.svg)](https://www.gnu.org/licenses/gpl-3.0)
 [![Node](https://img.shields.io/badge/node-%3E%3D18.0.0-green.svg)](https://nodejs.org/)
 
-- Current release: **0.9.0**
+- Current release: **0.9.2**
 - Changelog: `CHANGELOG.md`
 
 ## Install
@@ -66,6 +66,12 @@ darksol ai chat
 darksol memory show
 darksol memory search "preferred chain"
 
+# Autonomous agent task (ReAct loop)
+darksol agent task "check AERO price and tell me if it's above $2"
+darksol agent task "analyze my portfolio" --max-steps 5
+darksol agent task "swap 0.1 ETH for USDC" --allow-actions
+darksol agent plan "DCA strategy for AERO"
+
 # Agent email
 darksol mail setup
 darksol mail send --to user@example.com --subject "Hello"
@@ -123,6 +129,7 @@ ai <prompt>   # chat with trading assistant
 | `dca` | Dollar-cost averaging engine | Gas only |
 | `soul` | Agent identity & personality configuration | Free |
 | `memory` | Persistent cross-session memory store | Free |
+| `agent task` | Autonomous ReAct agent loop with tool use | Provider dependent |
 | `ai` | LLM-powered trading assistant & intent execution | Provider dependent |
 | `agent` | Secure agent signer (PK-isolated proxy) | Free |
 | `keys` | Encrypted API key vault (LLMs/data/RPCs) | Free |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@darksol/terminal",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "DARKSOL Terminal — unified CLI for all DARKSOL services. Market intel, trading, oracle, casino, and more.",
   "type": "module",
   "bin": {

package/src/agent/index.js

@@ -0,0 +1,134 @@
+import { getAllConfig, getConfig, setConfig } from '../config/store.js';
+import { createLLM } from '../llm/engine.js';
+import { getRecentMemories, saveMemory } from '../memory/index.js';
+import { createToolExecutor, createToolRegistry, listTools } from './tools.js';
+import { DEFAULT_MAX_STEPS, runAgentLoop } from './loop.js';
+
+const AGENT_STATE_KEY = 'agentState';
+
+function agentSystemPrompt({ goal, allowActions, maxSteps, recentMemories }) {
+  const cfg = getAllConfig();
+  return [
+    'You are DARKSOL Terminal agent mode.',
+    'Operate in a bounded ReAct loop and keep outputs terse and operational.',
+    `Goal: ${goal}`,
+    `Max steps: ${maxSteps}`,
+    `Actions enabled: ${allowActions ? 'yes' : 'no'}`,
+    `Chain: ${cfg.chain || 'base'}`,
+    `Active wallet: ${cfg.activeWallet || '(none)'}`,
+    `Slippage: ${cfg.slippage || 0.5}%`,
+    recentMemories.length
+      ? `Recent memories:\n${recentMemories.map((memory) => `- [${memory.category}] ${memory.content}`).join('\n')}`
+      : 'Recent memories: none',
+    'Prefer read-only verification before any action.',
+  ].join('\n\n');
+}
+
+async function persistAgentMemories(result) {
+  const outcome = result.final || result.summary;
+  if (outcome) {
+    await saveMemory(`Agent outcome: ${outcome}`, 'lesson', 'agent');
+  }
+  if (result.goal) {
+    await saveMemory(`Agent worked on: ${result.goal}`, 'decision', 'agent');
+  }
+}
+
+function saveAgentStatus(state) {
+  const previous = getConfig(AGENT_STATE_KEY) || {};
+  setConfig(AGENT_STATE_KEY, {
+    ...previous,
+    ...state,
+    updatedAt: new Date().toISOString(),
+  });
+}
+
+export async function planAgentGoal(goal, opts = {}) {
+  const llm = opts.llm || await createLLM(opts);
+  const memories = await getRecentMemories(5);
+  llm.setSystemPrompt(agentSystemPrompt({
+    goal,
+    allowActions: false,
+    maxSteps: opts.maxSteps || DEFAULT_MAX_STEPS,
+    recentMemories: memories,
+  }));
+
+  const result = await llm.json([
+    'Create a concise execution plan for this goal.',
+    `Goal: ${goal}`,
+    'Return JSON only: {"summary":"string","steps":["step 1","step 2"]}',
+  ].join('\n\n'), {
+    ephemeral: true,
+    skipMemoryExtraction: true,
+  });
+
+  const parsed = result.parsed || {};
+  const plan = {
+    goal,
+    summary: String(parsed.summary || `Plan for: ${goal}`),
+    steps: Array.isArray(parsed.steps) ? parsed.steps.map((step) => String(step)) : [],
+    createdAt: new Date().toISOString(),
+  };
+
+  saveAgentStatus({
+    status: 'planned',
+    goal,
+    summary: plan.summary,
+    plan: plan.steps,
+    allowActions: false,
+    stepsTaken: 0,
+    startedAt: null,
+    completedAt: null,
+  });
+  await saveMemory(`Agent plan: ${plan.summary}`, 'decision', 'agent');
+  return plan;
+}
+
+export async function runAgentTask(goal, opts = {}) {
+  const maxSteps = Number(opts.maxSteps) > 0 ? Number(opts.maxSteps) : DEFAULT_MAX_STEPS;
+  const allowActions = Boolean(opts.allowActions);
+  const llm = opts.llm || await createLLM(opts);
+  const recentMemories = await getRecentMemories(5);
+  const registry = opts.registry || createToolRegistry(opts.toolDeps);
+  const tools = listTools(registry);
+  const executeTool = opts.executeTool || createToolExecutor({
+    registry,
+    allowActions,
+    onEvent: opts.onToolEvent,
+  });
+
+  llm.setSystemPrompt(agentSystemPrompt({ goal, allowActions, maxSteps, recentMemories }));
+
+  const result = await runAgentLoop({
+    goal,
+    llm,
+    tools,
+    executeTool,
+    maxSteps,
+    allowActions,
+    onProgress: opts.onProgress,
+    saveOutcome: async (state) => {
+      saveAgentStatus({
+        status: state.status,
+        goal: state.goal,
+        summary: state.final,
+        stepsTaken: state.stepsTaken,
+        maxSteps: state.maxSteps,
+        allowActions: state.allowActions,
+        startedAt: state.startedAt,
+        completedAt: state.completedAt,
+        stopReason: state.stopReason,
+        lastTool: state.steps[state.steps.length - 1]?.action || null,
+        plan: state.steps.map((step) => `${step.step}. ${step.action}`),
+      });
+      await persistAgentMemories(state);
+    },
+    persistStatus: async (state) => saveAgentStatus(state),
+  });
+
+  return result;
+}
+
+export function getAgentStatus() {
+  return getConfig(AGENT_STATE_KEY) || null;
+}

package/src/agent/loop.js

@@ -0,0 +1,190 @@
+export const DEFAULT_MAX_STEPS = 10;
+
+function normalizeDecision(raw, fallbackStep) {
+  if (!raw || typeof raw !== 'object') {
+    return {
+      thought: 'No structured response returned.',
+      action: 'finish',
+      actionInput: {},
+      final: 'Agent stopped because the model did not return valid JSON.',
+      stop: true,
+      stopReason: 'invalid_response',
+    };
+  }
+
+  return {
+    thought: String(raw.thought || '').trim() || `Step ${fallbackStep}`,
+    action: String(raw.action || 'finish').trim(),
+    actionInput: raw.actionInput && typeof raw.actionInput === 'object' ? raw.actionInput : {},
+    final: raw.final ? String(raw.final).trim() : '',
+    stop: Boolean(raw.stop),
+    stopReason: raw.stopReason ? String(raw.stopReason).trim() : '',
+  };
+}
+
+function sameAction(a, b) {
+  return a && b && a.action === b.action && JSON.stringify(a.actionInput || {}) === JSON.stringify(b.actionInput || {});
+}
+
+function buildPrompt({ goal, allowActions, maxSteps, stepNumber, tools, steps }) {
+  const history = steps.length === 0
+    ? 'No prior steps yet.'
+    : steps.map((step) => {
+      const bits = [
+        `Step ${step.step}`,
+        `thought=${step.thought}`,
+        `action=${step.action}`,
+        `input=${JSON.stringify(step.actionInput || {})}`,
+        step.observation ? `observation=${step.observation}` : '',
+      ].filter(Boolean);
+      return bits.join('\n');
+    }).join('\n\n');
+
+  return [
+    'You are the DARKSOL agent loop controller.',
+    `Goal: ${goal}`,
+    `Current step: ${stepNumber}/${maxSteps}`,
+    `Safe mode: ${allowActions ? 'off' : 'on'}${allowActions ? '' : ' (mutating tools are blocked)'}`,
+    'Available tools:',
+    tools.map((tool) => `- ${tool.name}${tool.mutating ? ' [mutating]' : ''}: ${tool.description}`).join('\n'),
+    'Prior step log:',
+    history,
+    'Rules:',
+    '- Think briefly and act conservatively.',
+    '- Use read-only tools first unless the goal clearly requires an action and actions are allowed.',
+    '- If you have enough information, return action "finish" with a concise final answer.',
+    '- If the last tool was blocked or failed, adjust instead of repeating forever.',
+    '- Respond as JSON only.',
+    'JSON schema:',
+    '{"thought":"string","action":"tool-name|finish","actionInput":{},"final":"string","stop":false,"stopReason":"string"}',
+  ].join('\n\n');
+}
+
+export async function runAgentLoop({
+  goal,
+  llm,
+  tools,
+  executeTool,
+  maxSteps = DEFAULT_MAX_STEPS,
+  allowActions = false,
+  onProgress = () => {},
+  saveOutcome = async () => {},
+  persistStatus = async () => {},
+}) {
+  const startedAt = new Date().toISOString();
+  const steps = [];
+
+  await persistStatus({
+    status: 'running',
+    goal,
+    allowActions,
+    maxSteps,
+    startedAt,
+    completedAt: null,
+    stepsTaken: 0,
+    summary: '',
+  });
+
+  for (let stepNumber = 1; stepNumber <= maxSteps; stepNumber += 1) {
+    const prompt = buildPrompt({ goal, allowActions, maxSteps, stepNumber, tools, steps });
+    onProgress({ type: 'step-start', step: stepNumber, maxSteps });
+
+    const response = await llm.json(prompt, {
+      ephemeral: true,
+      skipMemoryExtraction: true,
+    });
+    const decision = normalizeDecision(response.parsed, stepNumber);
+    const stepLog = {
+      step: stepNumber,
+      thought: decision.thought,
+      action: decision.action,
+      actionInput: decision.actionInput,
+      observation: '',
+    };
+    steps.push(stepLog);
+    onProgress({ type: 'thought', step: stepNumber, thought: decision.thought, action: decision.action, actionInput: decision.actionInput });
+
+    const previous = steps.length > 1 ? steps[steps.length - 2] : null;
+    const repeatedLoop = sameAction(stepLog, previous) && sameAction(previous, steps.length > 2 ? steps[steps.length - 3] : null);
+    if (repeatedLoop) {
+      const completedAt = new Date().toISOString();
+      const result = {
+        status: 'stopped',
+        goal,
+        allowActions,
+        maxSteps,
+        startedAt,
+        completedAt,
+        stepsTaken: steps.length,
+        stopReason: 'repeat_guard',
+        final: 'Agent stopped after repeating the same step three times.',
+        steps,
+      };
+      await persistStatus({ ...result, summary: result.final });
+      await saveOutcome(result);
+      return result;
+    }
+
+    if (decision.stop || decision.action === 'finish' || decision.final) {
+      const completedAt = new Date().toISOString();
+      const final = decision.final || 'Agent stopped without a final answer.';
+      const result = {
+        status: 'completed',
+        goal,
+        allowActions,
+        maxSteps,
+        startedAt,
+        completedAt,
+        stepsTaken: steps.length,
+        stopReason: decision.stopReason || 'final',
+        final,
+        steps,
+      };
+      await persistStatus({ ...result, summary: final });
+      await saveOutcome(result);
+      onProgress({ type: 'final', final });
+      return result;
+    }
+
+    const observation = await executeTool(decision.action, decision.actionInput || {});
+    stepLog.observation = observation.summary || observation.error || JSON.stringify(observation);
+    stepLog.result = observation;
+    onProgress({ type: 'observation', step: stepNumber, tool: decision.action, observation });
+
+    if (observation.blocked) {
+      stepLog.observation = observation.error;
+    }
+
+    await persistStatus({
+      status: 'running',
+      goal,
+      allowActions,
+      maxSteps,
+      startedAt,
+      completedAt: null,
+      stepsTaken: steps.length,
+      lastTool: decision.action,
+      lastObservation: stepLog.observation,
+      summary: '',
+    });
+  }
+
+  const completedAt = new Date().toISOString();
+  const final = `Agent reached the step limit (${maxSteps}) before finishing.`;
+  const result = {
+    status: 'stopped',
+    goal,
+    allowActions,
+    maxSteps,
+    startedAt,
+    completedAt,
+    stepsTaken: steps.length,
+    stopReason: 'max_steps',
+    final,
+    steps,
+  };
+  await persistStatus({ ...result, summary: final });
+  await saveOutcome(result);
+  onProgress({ type: 'final', final });
+  return result;
+}

package/src/agent/tools.js

@@ -0,0 +1,311 @@
+import fetch from 'node-fetch';
+import { ethers } from 'ethers';
+import { getConfig, getRPC } from '../config/store.js';
+import { loadWallet } from '../wallet/keystore.js';
+
+const DEXSCREENER_API = 'https://api.dexscreener.com/latest/dex/search?q=';
+const USDC_ADDRESSES = {
+  base: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
+  ethereum: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',
+  arbitrum: '0xaf88d065e77c8cC2239327C5EDb3A432268e5831',
+  optimism: '0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85',
+  polygon: '0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359',
+};
+const PORTFOLIO_CHAINS = {
+  base: { name: 'Base' },
+  ethereum: { name: 'Ethereum' },
+  arbitrum: { name: 'Arbitrum' },
+  optimism: { name: 'Optimism' },
+  polygon: { name: 'Polygon' },
+};
+const ERC20_ABI = [
+  'function balanceOf(address) view returns (uint256)',
+  'function decimals() view returns (uint8)',
+];
+
+function compactNumber(value) {
+  const num = Number(value || 0);
+  if (!Number.isFinite(num)) return '0';
+  if (num >= 1e9) return `${(num / 1e9).toFixed(2)}B`;
+  if (num >= 1e6) return `${(num / 1e6).toFixed(2)}M`;
+  if (num >= 1e3) return `${(num / 1e3).toFixed(1)}K`;
+  return num.toFixed(2);
+}
+
+function summarizeResult(result) {
+  if (!result) return 'No result';
+  if (typeof result === 'string') return result;
+  if (result.summary) return result.summary;
+  if (result.final) return result.final;
+  if (result.error) return result.error;
+  if (result.token && result.priceUsd) return `${result.token} at $${result.priceUsd}`;
+  return JSON.stringify(result).slice(0, 240);
+}
+
+async function fetchBestPair(query, fetchImpl = fetch) {
+  const response = await fetchImpl(`${DEXSCREENER_API}${encodeURIComponent(query)}`);
+  const data = await response.json();
+  const pairs = Array.isArray(data.pairs) ? data.pairs : [];
+  if (pairs.length === 0) return null;
+  return pairs.sort((a, b) => (b.liquidity?.usd || 0) - (a.liquidity?.usd || 0))[0];
+}
+
+async function getEthPrice(fetchImpl = fetch) {
+  try {
+    const response = await fetchImpl('https://api.coingecko.com/api/v3/simple/price?ids=ethereum&vs_currencies=usd');
+    const data = await response.json();
+    return Number(data.ethereum?.usd) || 3000;
+  } catch {
+    return 3000;
+  }
+}
+
+async function readTokenBalance(provider, address, tokenAddress) {
+  if (!tokenAddress) return 0;
+  try {
+    const contract = new ethers.Contract(tokenAddress, ERC20_ABI, provider);
+    const raw = await contract.balanceOf(address);
+    const decimals = await contract.decimals();
+    return Number(ethers.formatUnits(raw, decimals));
+  } catch {
+    return 0;
+  }
+}
+
+function requireWallet(walletName) {
+  const resolved = walletName || getConfig('activeWallet');
+  if (!resolved) {
+    throw new Error('No active wallet configured');
+  }
+  return loadWallet(resolved);
+}
+
+function defaultRegistry(deps = {}) {
+  const fetchImpl = deps.fetch || fetch;
+  const providerFactory = deps.providerFactory || ((chain) => new ethers.JsonRpcProvider(getRPC(chain)));
+
+  return {
+    price: {
+      description: 'Fetch a live token price and liquidity snapshot',
+      mutating: false,
+      handler: async ({ token, query }) => {
+        const resolved = token || query;
+        if (!resolved) throw new Error('price requires token or query');
+        const pair = await fetchBestPair(resolved, fetchImpl);
+        if (!pair) return { ok: false, token: resolved, summary: `No market data for ${resolved}` };
+        return {
+          ok: true,
+          token: pair.baseToken?.symbol || resolved.toUpperCase(),
+          name: pair.baseToken?.name || resolved,
+          chain: pair.chainId,
+          dex: pair.dexId,
+          priceUsd: Number(pair.priceUsd || 0),
+          change24h: Number(pair.priceChange?.h24 || 0),
+          liquidityUsd: Number(pair.liquidity?.usd || 0),
+          volume24hUsd: Number(pair.volume?.h24 || 0),
+          pairAddress: pair.pairAddress,
+          summary: `${pair.baseToken?.symbol || resolved} ${Number(pair.priceUsd || 0).toFixed(6)} USD, 24h ${Number(pair.priceChange?.h24 || 0).toFixed(2)}%, liq $${compactNumber(pair.liquidity?.usd)}`,
+        };
+      },
+    },
+    gas: {
+      description: 'Fetch current gas data for a chain',
+      mutating: false,
+      handler: async ({ chain }) => {
+        const resolvedChain = chain || getConfig('chain') || 'base';
+        const provider = providerFactory(resolvedChain);
+        const feeData = await provider.getFeeData();
+        const gasPriceWei = feeData.gasPrice || 0n;
+        const gasPriceGwei = Number(ethers.formatUnits(gasPriceWei, 'gwei'));
+        const ethPrice = await getEthPrice(fetchImpl);
+        return {
+          ok: true,
+          chain: resolvedChain,
+          gasPriceGwei,
+          maxFeeGwei: Number(ethers.formatUnits(feeData.maxFeePerGas || 0n, 'gwei')),
+          priorityFeeGwei: Number(ethers.formatUnits(feeData.maxPriorityFeePerGas || 0n, 'gwei')),
+          ethPriceUsd: ethPrice,
+          summary: `${resolvedChain} gas ${gasPriceGwei.toFixed(2)} gwei`,
+        };
+      },
+    },
+    'wallet-balance': {
+      description: 'Read the active or named wallet native and USDC balances',
+      mutating: false,
+      handler: async ({ wallet, chain }) => {
+        const walletData = requireWallet(wallet);
+        const resolvedChain = chain || getConfig('chain') || walletData.chain || 'base';
+        const provider = providerFactory(resolvedChain);
+        const native = Number(ethers.formatEther(await provider.getBalance(walletData.address)));
+        const usdc = await readTokenBalance(provider, walletData.address, USDC_ADDRESSES[resolvedChain]);
+        return {
+          ok: true,
+          wallet: walletData.name,
+          address: walletData.address,
+          chain: resolvedChain,
+          native,
+          nativeSymbol: 'ETH',
+          usdc,
+          summary: `${walletData.name} on ${resolvedChain}: ${native.toFixed(6)} ETH and ${usdc.toFixed(2)} USDC`,
+        };
+      },
+    },
+    portfolio: {
+      description: 'Read wallet balances across supported chains',
+      mutating: false,
+      handler: async ({ wallet }) => {
+        const walletData = requireWallet(wallet);
+        const ethPrice = await getEthPrice(fetchImpl);
+        const chains = await Promise.all(
+          Object.entries(PORTFOLIO_CHAINS).map(async ([chainId, meta]) => {
+            try {
+              const provider = providerFactory(chainId);
+              const native = Number(ethers.formatEther(await provider.getBalance(walletData.address)));
+              const usdc = await readTokenBalance(provider, walletData.address, USDC_ADDRESSES[chainId]);
+              const totalUsd = native * ethPrice + usdc;
+              return { chain: chainId, name: meta.name, native, usdc, totalUsd };
+            } catch (error) {
+              return { chain: chainId, name: meta.name, native: 0, usdc: 0, totalUsd: 0, error: error.message };
+            }
+          }),
+        );
+        const totalUsd = chains.reduce((sum, item) => sum + (item.totalUsd || 0), 0);
+        return {
+          ok: true,
+          wallet: walletData.name,
+          address: walletData.address,
+          totalUsd,
+          chains,
+          summary: `${walletData.name} portfolio totals $${totalUsd.toFixed(2)} across ${chains.length} chains`,
+        };
+      },
+    },
+    market: {
+      description: 'Get top market movers or token comparison context',
+      mutating: false,
+      handler: async ({ query, token, chain, limit }) => {
+        const resolved = query || token || chain || getConfig('chain') || 'base';
+        const pair = await fetchBestPair(resolved, fetchImpl);
+        if (!pair) return { ok: false, summary: `No market snapshot for ${resolved}` };
+        return {
+          ok: true,
+          query: resolved,
+          token: pair.baseToken?.symbol || resolved,
+          chain: pair.chainId,
+          priceUsd: Number(pair.priceUsd || 0),
+          change24h: Number(pair.priceChange?.h24 || 0),
+          liquidityUsd: Number(pair.liquidity?.usd || 0),
+          volume24hUsd: Number(pair.volume?.h24 || 0),
+          limit: limit || 1,
+          summary: `Market snapshot ${pair.baseToken?.symbol || resolved}: $${Number(pair.priceUsd || 0).toFixed(6)}, vol $${compactNumber(pair.volume?.h24)}`,
+        };
+      },
+    },
+    watch: {
+      description: 'Take a quick watch snapshot for a token',
+      mutating: false,
+      handler: async ({ token, query }) => {
+        const resolved = token || query;
+        if (!resolved) throw new Error('watch requires token or query');
+        const pair = await fetchBestPair(resolved, fetchImpl);
+        if (!pair) return { ok: false, summary: `No watch data for ${resolved}` };
+        return {
+          ok: true,
+          token: pair.baseToken?.symbol || resolved,
+          priceUsd: Number(pair.priceUsd || 0),
+          change24h: Number(pair.priceChange?.h24 || 0),
+          liquidityUsd: Number(pair.liquidity?.usd || 0),
+          note: 'Watch tool returns a single snapshot inside the agent loop',
+          summary: `Watch snapshot ${pair.baseToken?.symbol || resolved}: $${Number(pair.priceUsd || 0).toFixed(6)}`,
+        };
+      },
+    },
+    swap: {
+      description: 'Execute a token swap',
+      mutating: true,
+      handler: deps.swapHandler || (async (args) => {
+        const { executeSwap } = await import('../trading/swap.js');
+        return executeSwap(args);
+      }),
+    },
+    send: {
+      description: 'Send ETH or ERC-20 tokens',
+      mutating: true,
+      handler: deps.sendHandler || (async (args) => {
+        const { sendFunds } = await import('../wallet/manager.js');
+        return sendFunds(args);
+      }),
+    },
+    'script-run': {
+      description: 'Execute a saved automation script',
+      mutating: true,
+      handler: deps.scriptRunHandler || (async (args) => {
+        const { runScript } = await import('../scripts/engine.js');
+        return runScript(args.name, args);
+      }),
+    },
+  };
+}
+
+export function createToolRegistry(deps = {}) {
+  const base = defaultRegistry(deps);
+  return {
+    ...base,
+    ...(deps.overrides || {}),
+  };
+}
+
+export function listTools(registry) {
+  return Object.entries(registry).map(([name, tool]) => ({
+    name,
+    description: tool.description,
+    mutating: Boolean(tool.mutating),
+  }));
+}
+
+export function createToolExecutor({ registry = createToolRegistry(), allowActions = false, onEvent = () => {} } = {}) {
+  return async function executeTool(name, input = {}) {
+    const tool = registry[name];
+    if (!tool) {
+      return { ok: false, blocked: true, error: `Unknown tool: ${name}`, summary: `Unknown tool ${name}` };
+    }
+
+    if (tool.mutating && !allowActions) {
+      return {
+        ok: false,
+        blocked: true,
+        error: `Tool "${name}" is blocked in safe mode. Re-run with --allow-actions to enable mutating tools.`,
+        summary: `Blocked ${name} in safe mode`,
+      };
+    }
+
+    onEvent({ type: 'tool-start', tool: name, input, mutating: Boolean(tool.mutating) });
+    try {
+      const result = await tool.handler(input);
+      const normalized = typeof result === 'object' && result !== null ? result : { value: result };
+      const finalResult = {
+        ok: normalized.ok !== false,
+        ...normalized,
+        summary: summarizeResult(normalized),
+      };
+      onEvent({ type: 'tool-result', tool: name, result: finalResult });
+      return finalResult;
+    } catch (error) {
+      const failure = { ok: false, error: error.message, summary: error.message };
+      onEvent({ type: 'tool-error', tool: name, error: error.message });
+      return failure;
+    }
+  };
+}
+
+export const AGENT_TOOL_NAMES = [
+  'price',
+  'gas',
+  'wallet-balance',
+  'portfolio',
+  'market',
+  'watch',
+  'swap',
+  'send',
+  'script-run',
+];