@darksol/terminal 0.8.1 → 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.8.1**
+- Current release: **0.9.1**
 - Changelog: `CHANGELOG.md`
 
 ## Install
@@ -56,9 +56,22 @@ darksol bridge send --from base --to arbitrum --token ETH -a 0.1
 darksol bridge status 0xTxHash...
 darksol bridge chains
 
-# AI trading assistant
+# Set up your agent identity
+darksol soul
+
+# AI trading assistant (now with personality + memory)
 darksol ai chat
 
+# View/search persistent memories
+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"
@@ -114,6 +127,9 @@ ai <prompt>   # chat with trading assistant
 | `trade` | Swap via LI.FI (31 DEXs) + Uniswap V3 fallback, snipe | Gas only |
 | `bridge` | Cross-chain bridge via LI.FI (60 chains, 27 bridges) | Gas only |
 | `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 |
@@ -190,9 +206,49 @@ darksol agent docs
 
 ---
 
+## 👤 Agent Soul System
+
+Give your terminal agent a name, personality, and persistent memory.
+
+```bash
+# First-run setup (or run anytime)
+darksol soul
+
+# View current identity
+darksol soul show
+
+# Reset and reconfigure
+darksol soul reset
+```
+
+**What it does:**
+- **Your name** — the agent addresses you personally
+- **Agent name** — name your AI (default: Darksol)
+- **Tone** — professional, casual, hacker, friendly, sarcastic, or custom freeform
+- Persists across sessions — your agent remembers who it is
+- Auto-injected into every LLM call as a system prompt
+
+**Session memory:** Conversations maintain context (up to 20 turns). When the limit is hit, older turns are summarized by the LLM — no hard context cliff.
+
+**Persistent memory:** Important facts, preferences, and decisions are auto-extracted and stored to disk (`~/.darksol/memory/`). Your agent learns over time.
+
+```bash
+# View recent memories
+darksol memory show --limit 20
+
+# Search memories
+darksol memory search "slippage preference"
+
+# Export / clear
+darksol memory export my-memories.json
+darksol memory clear
+```
+
+---
+
 ## 🧠 AI Trading Assistant
 
-Natural language trading powered by multi-provider LLM support.
+Natural language trading powered by multi-provider LLM support — now with soul personality and memory context.
 
 ```bash
 # Interactive chat with live market data

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@darksol/terminal",
-  "version": "0.8.1",
+  "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;
+}