@darksol/terminal 0.9.0 → 0.9.1

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.1**
 - 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.1",
   "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',
+];

package/src/cli.js

@@ -29,6 +29,7 @@ import { listSkills, installSkill, skillInfo, uninstallSkill } from './services/
 import { runSetupWizard } from './setup/wizard.js';
 import { displaySoul, hasSoul, resetSoul, runSoulSetup } from './soul/index.js';
 import { clearMemories, exportMemories, getRecentMemories, searchMemories } from './memory/index.js';
+import { getAgentStatus, planAgentGoal, runAgentTask } from './agent/index.js';
 import { createRequire } from 'module';
 import { resolve } from 'path';
 const require = createRequire(import.meta.url);
@@ -764,7 +765,7 @@ export function cli(argv) {
   ai
     .command('chat')
     .description('Start interactive AI trading chat')
-    .option('-p, --provider <name>', 'LLM provider (openai, anthropic, openrouter, ollama)')
+    .option('-p, --provider <name>', 'LLM provider (openai, anthropic, openrouter, minimax, ollama)')
     .option('-m, --model <model>', 'Model name')
     .action((opts) => startChat(opts));
 
@@ -883,6 +884,93 @@ export function cli(argv) {
     .command('agent')
     .description('Secure agent signer — PK-isolated wallet for AI agents');
 
+  agent
+    .command('task <goal...>')
+    .description('Run the agent loop against a goal')
+    .option('--max-steps <n>', 'Maximum loop steps', '10')
+    .option('--allow-actions', 'Allow mutating tools such as swap/send/script-run')
+    .action(async (goalParts, opts) => {
+      showMiniBanner();
+      showSection('AGENT TASK');
+      const goal = goalParts.join(' ').trim();
+      info(`Goal: ${goal}`);
+      info(`Mode: ${opts.allowActions ? 'actions enabled' : 'safe mode'}`);
+      console.log('');
+
+      const result = await runAgentTask(goal, {
+        maxSteps: parseInt(opts.maxSteps, 10),
+        allowActions: opts.allowActions,
+        onProgress: (event) => {
+          if (event.type === 'thought') {
+            info(`Step ${event.step}: ${event.action}`);
+            if (event.thought) console.log(`  ${theme.dim(event.thought)}`);
+          }
+          if (event.type === 'observation') {
+            const summary = event.observation?.summary || event.observation?.error || '';
+            if (summary) console.log(`  ${theme.dim(summary)}`);
+            console.log('');
+          }
+        },
+      });
+
+      showSection('AGENT RESULT');
+      kvDisplay([
+        ['Status', result.status],
+        ['Steps', `${result.stepsTaken}/${result.maxSteps}`],
+        ['Stop Reason', result.stopReason],
+      ]);
+      console.log('');
+      if (result.final) {
+        success(result.final);
+        console.log('');
+      }
+    });
+
+  agent
+    .command('plan <goal...>')
+    .description('Generate a concise agent plan for a goal')
+    .action(async (goalParts) => {
+      showMiniBanner();
+      showSection('AGENT PLAN');
+      const goal = goalParts.join(' ').trim();
+      const plan = await planAgentGoal(goal);
+      info(plan.summary);
+      console.log('');
+      plan.steps.forEach((step, index) => console.log(`  ${theme.gold(String(index + 1).padStart(2, ' '))}. ${step}`));
+      console.log('');
+    });
+
+  agent
+    .command('status')
+    .description('Show the latest agent task or plan status')
+    .action(() => {
+      showMiniBanner();
+      showSection('AGENT STATUS');
+      const status = getAgentStatus();
+      if (!status || !status.status) {
+        warn('No agent runs recorded yet.');
+        console.log('');
+        return;
+      }
+
+      kvDisplay([
+        ['Status', status.status || '-'],
+        ['Goal', status.goal || '-'],
+        ['Summary', status.summary || '-'],
+        ['Steps', status.maxSteps ? `${status.stepsTaken || 0}/${status.maxSteps}` : String(status.stepsTaken || 0)],
+        ['Actions', status.allowActions ? 'enabled' : 'safe mode'],
+        ['Started', status.startedAt || '-'],
+        ['Completed', status.completedAt || '-'],
+        ['Updated', status.updatedAt || '-'],
+      ]);
+      if (Array.isArray(status.plan) && status.plan.length > 0) {
+        console.log('');
+        showSection('LAST PLAN');
+        status.plan.forEach((step) => console.log(`  ${theme.dim(step)}`));
+      }
+      console.log('');
+    });
+
   agent
     .command('start [wallet]')
     .description('Start the agent signing proxy')
@@ -1304,7 +1392,7 @@ function showCommandList() {
     ['dca', 'Dollar-cost averaging orders'],
     ['ai chat', 'Standalone AI chat session'],
     ['ai execute', 'Parse + execute a trade via AI'],
-    ['agent start', 'Start secure agent signer'],
+    ['agent task', 'Run bounded agent loop for a goal'],
     ['keys', 'API key vault'],
     ['soul', 'Identity and agent personality'],
     ['memory', 'Persistent cross-session memory'],

package/src/config/keys.js

@@ -84,6 +84,14 @@ export const SERVICES = {
     docsUrl: 'https://openrouter.ai/keys',
     validate: (key) => key.startsWith('sk-or-'),
   },
+  minimax: {
+    name: 'MiniMax',
+    category: 'llm',
+    description: 'MiniMax-M2.5 via OpenAI-compatible chat completions',
+    envVar: 'MINIMAX_API_KEY',
+    docsUrl: 'https://platform.minimax.io/docs/guides/models-intro',
+    validate: (key) => key.length > 10,
+  },
   ollama: {
     name: 'Ollama (Local)',
     category: 'llm',
@@ -420,7 +428,7 @@ export function hasKey(service) {
  */
 export function hasAnyLLM() {
   // Cloud providers — need real validated API keys
-  if (['openai', 'anthropic', 'openrouter', 'bankr'].some(s => hasKey(s))) return true;
+  if (['openai', 'anthropic', 'openrouter', 'minimax', 'bankr'].some(s => hasKey(s))) return true;
   // Ollama — check if explicitly configured via hasKey (validates URL format)
   if (hasKey('ollama')) return true;
   return false;

package/src/config/store.js

@@ -28,6 +28,22 @@ const config = new Conf({
         createdAt: '',
       },
     },
+    agentState: {
+      type: 'object',
+      default: {
+        status: '',
+        goal: '',
+        summary: '',
+        plan: [],
+        stepsTaken: 0,
+        maxSteps: 0,
+        allowActions: false,
+        startedAt: null,
+        completedAt: null,
+        stopReason: '',
+        updatedAt: null,
+      },
+    },
     dca: {
       type: 'object',
       default: {

package/src/llm/engine.js

@@ -39,6 +39,13 @@ const PROVIDERS = {
     parseResponse: (data) => data.choices?.[0]?.message?.content,
     parseUsage: (data) => data.usage,
   },
+  minimax: {
+    url: 'https://api.minimax.io/v1/chat/completions',
+    defaultModel: 'MiniMax-M2.5',
+    authHeader: (key) => ({ Authorization: `Bearer ${key}` }),
+    parseResponse: (data) => data.choices?.[0]?.message?.content,
+    parseUsage: (data) => data.usage,
+  },
   ollama: {
     url: null,
     defaultModel: 'llama3.1',

package/src/setup/wizard.js

@@ -52,11 +52,12 @@ export async function runSetupWizard(opts = {}) {
     name: 'provider',
     message: theme.gold('Choose your AI provider:'),
     choices: [
-      { name: '🤖 OpenAI (GPT-4o, GPT-5) — API key or OAuth', value: 'openai' },
-      { name: '🧠 Anthropic (Claude Opus, Sonnet) — API key or OAuth', value: 'anthropic' },
-      { name: '🔀 OpenRouter (any model, one key) — API key', value: 'openrouter' },
-      { name: '🏠 Ollama (local models, free, private) — no key needed', value: 'ollama' },
-      { name: '⏭️  Skip for now', value: 'skip' },
+      { name: 'OpenAI (GPT-4o, GPT-5) - API key or OAuth', value: 'openai' },
+      { name: 'Anthropic (Claude Opus, Sonnet) - API key or OAuth', value: 'anthropic' },
+      { name: 'OpenRouter (any model, one key) - API key', value: 'openrouter' },
+      { name: 'MiniMax (MiniMax-M2.5) - API key', value: 'minimax' },
+      { name: 'Ollama (local models, free, private) - no key needed', value: 'ollama' },
+      { name: 'Skip for now', value: 'skip' },
     ],
   }]);
 
@@ -112,7 +113,7 @@ export async function runSetupWizard(opts = {}) {
 }
 
 /**
- * Setup a cloud provider (OpenAI, Anthropic, OpenRouter)
+ * Setup a cloud provider (OpenAI, Anthropic, OpenRouter, MiniMax)
  */
 async function setupCloudProvider(provider) {
   const supportsOAuth = ['openai', 'anthropic'].includes(provider);
@@ -120,6 +121,7 @@ async function setupCloudProvider(provider) {
     openai: 'OpenAI',
     anthropic: 'Anthropic',
     openrouter: 'OpenRouter',
+    minimax: 'MiniMax',
   }[provider];
 
   if (supportsOAuth) {
@@ -156,6 +158,7 @@ async function setupAPIKey(provider) {
     openai: 'OpenAI',
     anthropic: 'Anthropic',
     openrouter: 'OpenRouter',
+    minimax: 'MiniMax',
   }[provider];
 
   const { key } = await inquirer.prompt([{
@@ -173,6 +176,7 @@ async function setupAPIKey(provider) {
   success(`${providerName} key saved (encrypted)`);
 
   // Set as default provider
+  setConfig('llm.provider', provider);
   setConfig('llmProvider', provider);
   info(`Default AI provider set to ${provider}`);
 }
@@ -193,6 +197,7 @@ async function setupOllama() {
     default: 'http://localhost:11434',
   }]);
 
+  setConfig('llm.ollamaHost', host);
   setConfig('ollamaHost', host);
 
   const { model } = await inquirer.prompt([{
@@ -202,7 +207,9 @@ async function setupOllama() {
     default: 'llama3',
   }]);
 
+  setConfig('llm.model', model);
   setConfig('ollamaModel', model);
+  setConfig('llm.provider', 'ollama');
   setConfig('llmProvider', 'ollama');
 
   success(`Ollama configured: ${host} / ${model}`);
@@ -231,8 +238,14 @@ function showKeyInstructions(provider) {
     console.log(theme.dim('  3. Copy the key (starts with sk-ant-)'));
     console.log(theme.dim('  4. Paste it below'));
     console.log('');
-    console.log(theme.dim('  💡 If you have a Claude Pro/Team subscription,'));
+    console.log(theme.dim('  If you have a Claude Pro/Team subscription,'));
     console.log(theme.dim('     you can use OAuth instead.'));
+  } else if (provider === 'minimax') {
+    showSection('GET A MINIMAX API KEY');
+    console.log(theme.dim('  1. Go to https://platform.minimax.io/docs/guides/models-intro'));
+    console.log(theme.dim('  2. Open your MiniMax developer console / API key page'));
+    console.log(theme.dim('  3. Create or copy an API key'));
+    console.log(theme.dim('  4. Paste it below'));
   }
 
   console.log('');
@@ -432,6 +445,7 @@ async function executeOAuthFlow(provider, clientId, clientSecret) {
             if (tokenData.refresh_token) {
               addKeyDirect(`${provider}_refresh`, tokenData.refresh_token);
             }
+            setConfig('llm.provider', provider);
             setConfig('llmProvider', provider);
 
             res.writeHead(200, { 'Content-Type': 'text/html' });

package/src/web/commands.js

@@ -452,6 +452,7 @@ export async function handlePromptResponse(id, value, meta, ws) {
       if (service === 'openai') ws.sendLine(`  ${ANSI.dim}Key should start with sk-${ANSI.reset}`);
       if (service === 'anthropic') ws.sendLine(`  ${ANSI.dim}Key should start with sk-ant-${ANSI.reset}`);
       if (service === 'openrouter') ws.sendLine(`  ${ANSI.dim}Key should start with sk-or-${ANSI.reset}`);
+      if (service === 'minimax') ws.sendLine(`  ${ANSI.dim}Get a key: ${svc.docsUrl}${ANSI.reset}`);
       if (service === 'ollama') ws.sendLine(`  ${ANSI.dim}Should be a URL like http://localhost:11434${ANSI.reset}`);
       ws.sendLine('');
       return {};
@@ -782,7 +783,7 @@ export function getAIStatus() {
   const dim = '\x1b[38;2;102;102;102m';
   const reset = '\x1b[0m';
 
-  const providers = ['openai', 'anthropic', 'openrouter', 'ollama', 'bankr'];
+  const providers = ['openai', 'anthropic', 'openrouter', 'minimax', 'ollama', 'bankr'];
   const connected = providers.filter(p => hasKey(p));
   const soul = hasSoul() ? getSoul() : null;
 
@@ -798,6 +799,7 @@ export function getAIStatus() {
     `  ${green}keys add openai sk-...${reset}         ${dim}OpenAI (GPT-4o)${reset}`,
     `  ${green}keys add anthropic sk-ant-...${reset}   ${dim}Anthropic (Claude)${reset}`,
     `  ${green}keys add openrouter sk-or-...${reset}   ${dim}OpenRouter (any model)${reset}`,
+    `  ${green}keys add minimax <key>${reset}          ${dim}MiniMax (MiniMax-M2.5)${reset}`,
     `  ${green}keys add bankr bk_...${reset}           ${dim}Bankr LLM Gateway (crypto credits)${reset}`,
     `  ${green}keys add ollama http://...${reset}      ${dim}Ollama (free, local)${reset}`,
     '',
@@ -850,6 +852,8 @@ export async function handleCommand(cmd, ws) {
     case 'agent':
     case 'signer':
       return await cmdAgent(args, ws);
+    case 'task':
+      return await cmdAgent(['task', ...args], ws);
     case 'ai':
     case 'ask':
     case 'chat':
@@ -1339,7 +1343,84 @@ async function showWalletDetail(name, ws) {
 async function cmdAgent(args, ws) {
   const sub = (args[0] || 'menu').toLowerCase();
 
+  if (sub === 'task') {
+    const goal = args.slice(1).join(' ').trim();
+    if (!goal) {
+      return {
+        output: `\r\n  ${ANSI.dim}Usage: agent task <goal> [--max-steps N] [--allow-actions]${ANSI.reset}\r\n  ${ANSI.dim}Shortcut: task <goal>${ANSI.reset}\r\n\r\n`,
+      };
+    }
+
+    const allowActions = args.includes('--allow-actions');
+    const maxIndex = args.findIndex((arg) => arg === '--max-steps');
+    const maxSteps = maxIndex >= 0 ? parseInt(args[maxIndex + 1], 10) || 10 : 10;
+    const filteredGoal = args
+      .slice(1)
+      .filter((arg, index, arr) => arg !== '--allow-actions' && !(arg === '--max-steps' || arr[index - 1] === '--max-steps'))
+      .join(' ')
+      .trim();
+
+    const { runAgentTask } = await import('../agent/index.js');
+    ws.sendLine(`${ANSI.gold}  ◆ AGENT TASK${ANSI.reset}`);
+    ws.sendLine(`${ANSI.dim}  ${'─'.repeat(50)}${ANSI.reset}`);
+    ws.sendLine(`  ${ANSI.white}Goal:${ANSI.reset} ${filteredGoal}`);
+    ws.sendLine(`  ${ANSI.darkGold}Mode:${ANSI.reset} ${allowActions ? 'actions enabled' : 'safe mode'}`);
+    ws.sendLine('');
+
+    const result = await runAgentTask(filteredGoal, {
+      maxSteps,
+      allowActions,
+      onProgress: (event) => {
+        if (event.type === 'thought') {
+          ws.sendLine(`  ${ANSI.darkGold}[step ${event.step}]${ANSI.reset} ${ANSI.white}${event.action}${ANSI.reset}`);
+          if (event.thought) {
+            ws.sendLine(`  ${ANSI.dim}${event.thought}${ANSI.reset}`);
+          }
+        }
+        if (event.type === 'observation') {
+          const summary = event.observation?.summary || event.observation?.error;
+          if (summary) ws.sendLine(`  ${ANSI.dim}${summary}${ANSI.reset}`);
+          ws.sendLine('');
+        }
+      },
+    });
+
+    ws.sendLine(`  ${ANSI.green}Final:${ANSI.reset} ${result.final}`);
+    ws.sendLine(`  ${ANSI.dim}Status ${result.status} • ${result.stepsTaken}/${result.maxSteps} steps • ${result.stopReason}${ANSI.reset}`);
+    ws.sendLine('');
+    return {};
+  }
+
+  if (sub === 'plan') {
+    const goal = args.slice(1).join(' ').trim();
+    if (!goal) {
+      return { output: `  ${ANSI.dim}Usage: agent plan <goal>${ANSI.reset}\r\n` };
+    }
+    const { planAgentGoal } = await import('../agent/index.js');
+    const plan = await planAgentGoal(goal);
+    ws.sendLine(`${ANSI.gold}  ◆ AGENT PLAN${ANSI.reset}`);
+    ws.sendLine(`${ANSI.dim}  ${'─'.repeat(50)}${ANSI.reset}`);
+    ws.sendLine(`  ${ANSI.white}${plan.summary}${ANSI.reset}`);
+    ws.sendLine('');
+    plan.steps.forEach((step, index) => ws.sendLine(`  ${ANSI.darkGold}${index + 1}.${ANSI.reset} ${step}`));
+    ws.sendLine('');
+    return {};
+  }
+
   if (sub === 'status') {
+    const { getAgentStatus } = await import('../agent/index.js');
+    const status = getAgentStatus();
+    if (status?.goal || status?.summary) {
+      ws.sendLine(`${ANSI.gold}  ◆ AGENT STATUS${ANSI.reset}`);
+      ws.sendLine(`${ANSI.dim}  ${'─'.repeat(50)}${ANSI.reset}`);
+      ws.sendLine(`  ${ANSI.darkGold}Status${ANSI.reset}       ${ANSI.white}${status.status || '-'}${ANSI.reset}`);
+      ws.sendLine(`  ${ANSI.darkGold}Goal${ANSI.reset}         ${ANSI.white}${status.goal || '-'}${ANSI.reset}`);
+      ws.sendLine(`  ${ANSI.darkGold}Summary${ANSI.reset}      ${ANSI.white}${status.summary || '-'}${ANSI.reset}`);
+      ws.sendLine(`  ${ANSI.darkGold}Steps${ANSI.reset}        ${ANSI.white}${status.stepsTaken || 0}${status.maxSteps ? `/${status.maxSteps}` : ''}${ANSI.reset}`);
+      ws.sendLine(`  ${ANSI.darkGold}Actions${ANSI.reset}      ${ANSI.white}${status.allowActions ? 'enabled' : 'safe mode'}${ANSI.reset}`);
+      ws.sendLine('');
+      return {};
+    }
     return await showSignerStatus(ws);
   }
 
@@ -1938,7 +2019,7 @@ async function cmdKeys(args, ws) {
 
     if (!svc) {
       ws.sendLine(`  ${ANSI.red}✗ Unknown service: ${service}${ANSI.reset}`);
-      ws.sendLine(`  ${ANSI.dim}Available: openai, anthropic, openrouter, ollama${ANSI.reset}`);
+      ws.sendLine(`  ${ANSI.dim}Available: openai, anthropic, openrouter, minimax, ollama, bankr${ANSI.reset}`);
       ws.sendLine('');
       return {};
     }
@@ -1986,7 +2067,7 @@ async function cmdKeys(args, ws) {
   ws.sendLine(`${ANSI.dim}  ${'─'.repeat(50)}${ANSI.reset}`);
   ws.sendLine('');
 
-  const llmProviders = ['openai', 'anthropic', 'openrouter', 'ollama', 'bankr'];
+  const llmProviders = ['openai', 'anthropic', 'openrouter', 'minimax', 'ollama', 'bankr'];
   ws.sendLine(`  ${ANSI.gold}LLM Providers:${ANSI.reset}`);
   for (const p of llmProviders) {
     const svc = SERVICES[p];
@@ -2000,6 +2081,7 @@ async function cmdKeys(args, ws) {
   ws.sendLine(`  ${ANSI.green}keys add openai sk-...${ANSI.reset}       ${ANSI.dim}Add OpenAI key${ANSI.reset}`);
   ws.sendLine(`  ${ANSI.green}keys add anthropic sk-ant-...${ANSI.reset} ${ANSI.dim}Add Anthropic key${ANSI.reset}`);
   ws.sendLine(`  ${ANSI.green}keys add openrouter sk-or-...${ANSI.reset} ${ANSI.dim}Add OpenRouter key${ANSI.reset}`);
+  ws.sendLine(`  ${ANSI.green}keys add minimax <key>${ANSI.reset}      ${ANSI.dim}Add MiniMax key${ANSI.reset}`);
   ws.sendLine(`  ${ANSI.green}keys add ollama http://...${ANSI.reset}   ${ANSI.dim}Add Ollama host${ANSI.reset}`);
   ws.sendLine('');