@agether/agether 2.12.2 → 3.0.0

package/README.md

@@ -115,7 +115,9 @@ Once installed, the following tools are available to your AI agent:
 | `morpho_repay` | Repay USDC debt |
 | `morpho_withdraw` | Withdraw collateral back to EOA |
 | `morpho_sponsor` | Deposit collateral for another agent (by ID or address) |
-| `wallet_fund` | Transfer USDC from EOA into AgentAccount |
+| `wallet_fund_token` | Transfer any ERC-20 from EOA into AgentAccount |
+| `wallet_transfer` | Transfer any token/ETH from AgentAccount to any address or agent |
+| `wallet_approve` | Approve a spender for tokens in AgentAccount |
 | `x402_pay` | Make paid API calls via x402 protocol (supports auto-draw) |
 
 ## Slash Commands

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agether/agether",
-  "version": "2.12.2",
+  "version": "3.0.0",
   "description": "OpenClaw plugin for Agether — onchain credit for AI agents on Ethereum & Base",
   "main": "src/index.ts",
   "openclaw": {
@@ -9,7 +9,7 @@
     ]
   },
   "dependencies": {
-    "@agether/sdk": "^2.14.0",
+    "@agether/sdk": "^2.15.0",
     "axios": "^1.6.0",
     "ethers": "^6.9.0"
   },

package/skills/agether/SKILL.md

@@ -127,7 +127,7 @@ Both `agether_set_agent` and `agether_register` save the agentId to config perma
 ### Wallet (move funds between EOA ↔ AgentAccount)
 | Tool | Params | What it does |
 |------|--------|-------------|
-| `wallet_fund` | `amount` | Transfer USDC from EOA → AgentAccount |
+| `wallet_fund_token` | `token`, `amount` | Transfer any ERC-20 token from EOA → AgentAccount |
 | `wallet_withdraw_token` | `token`, `amount` | Withdraw any ERC-20 token from AgentAccount → EOA. Use `amount: "all"` for full balance. |
 | `wallet_withdraw_eth` | `amount` | Withdraw ETH from AgentAccount → EOA. Use `amount: "all"` for full balance. |
 
@@ -251,7 +251,7 @@ IF no auto-funding configured:
 ```
 1. Check token availability:
    - agether_health for AgentAccount balances
-   - If no tokens in AgentAccount but exists in EOA → wallet_fund first
+   - If no tokens in AgentAccount but exists in EOA → wallet_fund_token first
 2. morpho_markets                ← show supply APYs to pick best market
 3. morpho_supply(amount, market?, loanToken?) ← supply tokens to earn yield
 4. Later: morpho_supply_status   ← check earned yield
@@ -450,7 +450,7 @@ If something **fails**:
 | `Payment rejected (402)` | No USDC for x402 payment | Borrow USDC first, or enable autoDraw/autoYield in config |
 | `No collateral deposited` | Trying to borrow without collateral | `morpho_deposit` first |
 | `Insufficient collateral` | EOA doesn't have enough of that token | Tell user to send collateral to EOA address |
-| `Insufficient USDC in AgentAccount` | Not enough loan token for repay/pay | Fund via borrow, yield withdrawal, or `wallet_fund` |
+| `Insufficient USDC in AgentAccount` | Not enough loan token for repay/pay | Fund via borrow, yield withdrawal, or `wallet_fund_token` |
 | `ExecutionFailed` | Smart contract call reverted | Check inner error, usually LTV or approval issue |
 | `PositionNotActive` | No collateral deposited for this token | Deposit collateral with `morpho_deposit` first |
 
@@ -494,7 +494,9 @@ Morpho Blue (direct lending, overcollateralized 125%)
         └── Yield tracked via Morpho GraphQL API (no database needed)
 
 Wallet transfers:
-  ├── wallet_fund           → USDC from EOA → AgentAccount
+  ├── wallet_fund_token     → any ERC-20 from EOA → AgentAccount
+  ├── wallet_transfer       → any ERC-20 or ETH from AgentAccount → any address/agent
+  ├── wallet_approve        → approve spender for tokens in AgentAccount
   ├── wallet_withdraw_token → any ERC-20 from AgentAccount → EOA
   └── wallet_withdraw_eth   → ETH from AgentAccount → EOA
 ```

package/src/index.ts

@@ -99,25 +99,155 @@ interface PluginConfig {
 
 function txLink(hash: string): string {
   if (!hash) return "";
-  const explorer = CHAIN_DEFAULTS[activeChainId]?.explorer ?? CHAIN_DEFAULTS[ChainId.Ethereum].explorer;
+  const explorer = CHAIN_DEFAULTS[state.activeChainId]?.explorer ?? CHAIN_DEFAULTS[ChainId.Ethereum].explorer;
   return `${explorer}/${hash}`;
 }
 
+
+
+// ─── Unified State Management ─────────────────────────────
+// Phase 1 Fix: Replace scattered module-level state with single class.
+// Eliminates race conditions between memory cache, config, and disk persistence.
+
+class AgetherState {
+  private agentsByChain: Record<number, string> = {};
+  private _activeChainId: ChainId = ChainId.Ethereum;
+  private _chainExplicitlySet: boolean = false;
+  private configPath: string;
+
+  constructor() {
+    const home = process.env.HOME || process.env.USERPROFILE || "/root";
+    this.configPath = path.join(home, ".openclaw", "openclaw.json");
+    this.restore();
+  }
+
+  /** Restore state from openclaw.json on startup */
+  private restore(): void {
+    try {
+      if (!fs.existsSync(this.configPath)) return;
+      const raw = fs.readFileSync(this.configPath, "utf-8");
+      const json = JSON.parse(raw);
+      const cfg = json?.plugins?.entries?.agether?.config;
+      if (!cfg) return;
+
+      if (cfg.chain !== undefined && cfg.chain !== null && cfg.chain !== "") {
+        this._activeChainId = cfg.chain as ChainId;
+        this._chainExplicitlySet = true;
+      }
+      if (cfg.agentId) {
+        this.agentsByChain[this._activeChainId] = String(cfg.agentId);
+      }
+      if (cfg.agentsByChain) {
+        for (const [k, v] of Object.entries(cfg.agentsByChain)) {
+          this.agentsByChain[Number(k)] = String(v);
+        }
+      }
+    } catch {
+      // Silently fail on restore — fresh state is fine
+    }
+  }
+
+  /** Persist current state to openclaw.json atomically */
+  private persist(): void {
+    try {
+      let json: any = {};
+      if (fs.existsSync(this.configPath)) {
+        json = JSON.parse(fs.readFileSync(this.configPath, "utf-8"));
+      }
+      if (!json.plugins) json.plugins = {};
+      if (!json.plugins.entries) json.plugins.entries = {};
+      if (!json.plugins.entries.agether) json.plugins.entries.agether = {};
+      if (!json.plugins.entries.agether.config) json.plugins.entries.agether.config = {};
+
+      const cfg = json.plugins.entries.agether.config;
+      cfg.chain = this._activeChainId;
+      cfg.agentId = this.agentsByChain[this._activeChainId] || cfg.agentId;
+      cfg.agentsByChain = { ...this.agentsByChain };
+
+      fs.writeFileSync(this.configPath, JSON.stringify(json, null, 2));
+    } catch (e) {
+      console.warn("[agether] state persist failed:", e instanceof Error ? e.message : String(e));
+    }
+  }
+
+  get activeChainId(): ChainId { return this._activeChainId; }
+  get chainConfigured(): boolean { return this._chainExplicitlySet; }
+
+  getAgentId(chainId?: ChainId): string | undefined {
+    return this.agentsByChain[chainId ?? this._activeChainId];
+  }
+
+  setChain(chainId: ChainId): string {
+    this._activeChainId = chainId;
+    this._chainExplicitlySet = true;
+    this.persist();
+    return "saved";
+  }
+
+  setAgentId(agentId: string, chainId?: ChainId): string {
+    const chain = chainId ?? this._activeChainId;
+    this.agentsByChain[chain] = agentId;
+    this.persist();
+    return "saved";
+  }
+}
+
+// Single global state instance — replaces scattered cachedAgentIds, activeChainId, chainOverride
+const state = new AgetherState();
+
 function ok(text: string) {
+  // Enhanced: Extract transaction links and key info for user visibility
+  try {
+    const data = JSON.parse(text);
+    let enhanced = "";
+    
+    // Show transaction link if present
+    if (data.tx) {
+      enhanced += `🔗 **Transaction:** ${txLink(data.tx)}\n`;
+    }
+    
+    // Show agent ID if present
+    if (data.agentId && data.agentId !== '?') {
+      enhanced += `🤖 **Agent:** ${data.agentId}\n`;
+    }
+    
+    // Show balances if present
+    if (data.eth || data.usdc) {
+      enhanced += `💰 **EOA:** ${data.eth || '0'} ETH, $${data.usdc || '0'} USDC\n`;
+    }
+    
+    if (enhanced) {
+      return { content: [{ type: "text" as const, text: enhanced + "\n```json\n" + text + "\n```" }] };
+    }
+  } catch {
+    // Not JSON, just return as-is
+  }
+  
   return { content: [{ type: "text" as const, text }] };
 }
 
 function fail(err: unknown) {
   let msg = err instanceof Error ? err.message : String(err);
+  
+  // Add helpful suggestions for common errors
+  let suggestion = "";
   if (msg.includes("0xda04aecc")) {
     msg = "ExceedsMaxLtv — collateral too low for this borrow amount";
+    suggestion = "\n💡 Try: Reduce borrow amount or check morpho_max_borrowable";
   } else if (msg.includes("0xfeca99cb")) {
     msg = "ExecutionFailed — the inner contract call reverted. Likely ExceedsMaxLtv or insufficient collateral.";
+    suggestion = "\n💡 Try: Check morpho_status and agether_balance";
   } else if (msg.includes("0xa920ef9f")) {
     msg = "PositionNotActive — no collateral deposited for this token";
+    suggestion = "\n💡 Try: morpho_deposit first, then borrow";
+  } else if (msg.includes("agentId not set")) {
+    suggestion = "\n💡 Try: agether_register() first";
+  } else if (msg.includes("Chain not configured")) {
+    suggestion = "\n💡 Try: agether_set_chain('base') or agether_set_chain('ethereum')";
   }
+  
   if (msg.length > 300) msg = msg.slice(0, 250) + "…";
-  return { content: [{ type: "text" as const, text: `❌ ${msg}` }], isError: true };
+  return { content: [{ type: "text" as const, text: `❌ ${msg}${suggestion}` }], isError: true };
 }
 
 // ─── Secrets-first config resolution ──────────────────────
@@ -163,26 +293,22 @@ function resolvePrivateKey(): string {
 }
 
 function getConfig(api: any): PluginConfig {
-  const cfg = api.config?.plugins?.entries?.["agether"]?.config ?? {};
-  // chainOverride (set by agether_set_chain at runtime) takes priority over
-  // api.config which is a stale in-memory snapshot that never refreshes.
-  const rawChain = chainOverride ?? cfg.chain;
-  const chainConfigured = rawChain !== undefined && rawChain !== null && rawChain !== "";
-  const chainId = (rawChain as ChainId) || ChainId.Ethereum;
-  activeChainId = chainId; // Update module-level for txLink
+  // Phase 1 Fix: Use unified AgetherState instead of scattered module variables.
+  // State reads from single source of truth (state object) which is
+  // initialized from openclaw.json and updated atomically on mutations.
+  const chainId = state.activeChainId;
   return {
     privateKey: resolvePrivateKey(),
-    agentId: cachedAgentIds[chainId] || cfg.agentId,
+    agentId: state.getAgentId(chainId),
     rpcUrl: resolveRpcUrl(chainId),
     chainId,
-    chainConfigured,
+    chainConfigured: state.chainConfigured,
   };
 }
 
-// Module-level cache
-const cachedAgentIds: Record<number, string> = {}; // chainId → agentId (chain-specific!)
-let activeChainId: ChainId = ChainId.Ethereum;
-let chainOverride: ChainId | undefined; // set by agether_set_chain, survives stale api.config
+// Legacy module-level aliases — kept for backward compatibility with txLink()
+// These now delegate to state object instead of being independent variables.
+function get_activeChainId(): ChainId { return state.activeChainId; }
 
 /**
  * Hard guardrail: refuse to proceed if chain was never explicitly configured.
@@ -204,7 +330,7 @@ function requireChain(cfg: PluginConfig): void {
  * client (only register() and getBalances() available).
  */
 function createAgetherClient(cfg: PluginConfig): AgetherClient {
-  const agentId = cachedAgentIds[cfg.chainId] || cfg.agentId;
+  const agentId = state.getAgentId(cfg.chainId) || cfg.agentId;
   if (agentId) {
     return AgetherClient.fromPrivateKey(cfg.privateKey, BigInt(agentId), cfg.chainId);
   }
@@ -216,7 +342,7 @@ function createAgetherClient(cfg: PluginConfig): AgetherClient {
  * Requires agentId — use AgetherClient.register() first.
  */
 function createMorphoClient(cfg: PluginConfig): MorphoClient {
-  const agentId = cachedAgentIds[cfg.chainId] || cfg.agentId;
+  const agentId = state.getAgentId(cfg.chainId) || cfg.agentId;
   if (!agentId) {
     throw new Error("agentId not set. Register first with agether_register, then try again.");
   }
@@ -233,51 +359,14 @@ function createClient(cfg: PluginConfig): MorphoClient {
   return createMorphoClient(cfg);
 }
 
-/** Persist agentId to openclaw.json so it survives restarts. */
+/** Persist agentId — now delegates to AgetherState for atomic updates. */
 function persistAgentId(agentId: string): string {
-  cachedAgentIds[activeChainId] = agentId;
-  try {
-    const home = process.env.HOME || process.env.USERPROFILE || "/root";
-    const cfgPath = path.join(home, ".openclaw", "openclaw.json");
-    const raw = fs.readFileSync(cfgPath, "utf-8");
-    const json = JSON.parse(raw);
-
-    // Ensure config path exists
-    if (!json.plugins) json.plugins = {};
-    if (!json.plugins.entries) json.plugins.entries = {};
-    if (!json.plugins.entries.agether) json.plugins.entries.agether = {};
-    if (!json.plugins.entries.agether.config) json.plugins.entries.agether.config = {};
-
-    json.plugins.entries.agether.config.agentId = agentId;
-    fs.writeFileSync(cfgPath, JSON.stringify(json, null, 2));
-    return "saved";
-  } catch (e) {
-    return `write failed: ${e instanceof Error ? e.message : String(e)}`;
-  }
+  return state.setAgentId(agentId);
 }
 
-/** Persist chain to openclaw.json so it survives restarts. */
+/** Persist chain — now delegates to AgetherState for atomic updates. */
 function persistChainId(chainId: ChainId): string {
-  activeChainId = chainId;
-  chainOverride = chainId; // In-memory override so getConfig() picks it up immediately
-  try {
-    const home = process.env.HOME || process.env.USERPROFILE || "/root";
-    const cfgPath = path.join(home, ".openclaw", "openclaw.json");
-    const raw = fs.readFileSync(cfgPath, "utf-8");
-    const json = JSON.parse(raw);
-
-    // Ensure config path exists
-    if (!json.plugins) json.plugins = {};
-    if (!json.plugins.entries) json.plugins.entries = {};
-    if (!json.plugins.entries.agether) json.plugins.entries.agether = {};
-    if (!json.plugins.entries.agether.config) json.plugins.entries.agether.config = {};
-
-    json.plugins.entries.agether.config.chain = chainId;
-    fs.writeFileSync(cfgPath, JSON.stringify(json, null, 2));
-    return "saved";
-  } catch (e) {
-    return `write failed: ${e instanceof Error ? e.message : String(e)}`;
-  }
+  return state.setChain(chainId);
 }
 
 // ─── Plugin Entry ─────────────────────────────────────────
@@ -288,8 +377,7 @@ export default function register(api: any) {
   // ═══════════════════════════════════════════════════════
   api.registerTool({
     name: "agether_balance",
-    description:
-      "Check ETH and USDC balances for the agent's EOA wallet and AgentAccount.",
+    description: "Check all token balances (ETH, USDC, collateral) for EOA and AgentAccount.",
     parameters: { type: "object", properties: {}, required: [] },
     async execute() {
       try {
@@ -306,9 +394,7 @@ export default function register(api: any) {
   // ═══════════════════════════════════════════════════════
   api.registerTool({
     name: "agether_register",
-    description:
-      "Register a new ERC-8004 agent identity and create a Safe smart account (via Safe7579). " +
-      "REQUIRES chain to be configured first — call agether_set_chain before this tool. Returns the new agentId.",
+    description: "Register new agent identity (ERC-8004) and deploy Safe account. Set chain first via agether_set_chain.",
     parameters: {
       type: "object",
       properties: {
@@ -321,6 +407,29 @@ export default function register(api: any) {
         const cfg = getConfig(api);
         requireChain(cfg);
         const client = createAgetherClient(cfg);
+
+        // Phase 1 Fix: Warn if agentId already cached for this chain
+        // The SDK's register() handles double-reg gracefully (returns alreadyRegistered=true),
+        // but this gives the user an earlier, clearer signal.
+        const existingAgentId = state.getAgentId(cfg.chainId);
+        if (existingAgentId) {
+          // Agent already registered on this chain — verify before re-registering
+          try {
+            const verifyClient = AgetherClient.fromPrivateKey(cfg.privateKey, BigInt(existingAgentId), cfg.chainId);
+            const acctAddr = await verifyClient.getAccountAddress();
+            if (acctAddr) {
+              return ok(JSON.stringify({
+                status: "already_registered",
+                agentId: existingAgentId,
+                agentAccount: acctAddr,
+                warning: "Agent already registered on this chain. Use agether_set_agent if you need to change agentId.",
+              }));
+            }
+          } catch {
+            // Verification failed — maybe stale cache, allow re-registration
+          }
+        }
+
         const result = await client.register({ name: _params.name });
         const persistStatus = persistAgentId(result.agentId);
         const kyaMessage = result.kyaRequired
@@ -563,9 +672,8 @@ export default function register(api: any) {
   //  TOOL: morpho_deposit
   // ═══════════════════════════════════════════════════════
   api.registerTool({
-    name: "morpho_deposit",
-    description:
-      "Deposit collateral into Morpho Blue via AgentAccount. Enables borrowing against it. Token is auto-discovered from available markets.",
+    name: "morpho_deposit_collateral",
+    description: "Deposit collateral into Morpho Blue to enable borrowing. Validates balance first.",
     parameters: {
       type: "object",
       properties: {
@@ -579,6 +687,26 @@ export default function register(api: any) {
         const cfg = getConfig(api);
         requireChain(cfg);
         const client = createMorphoClient(cfg);
+
+        // Phase 1 Fix: Validate balance before attempting deposit
+        try {
+          const agether = createAgetherClient(cfg);
+          const balances = await agether.getBalances();
+          const tokenBalance = balances.agentAccount?.collateral?.[params.token.toUpperCase()]
+            || balances.collateral?.[params.token.toUpperCase()]
+            || "0";
+          const available = parseFloat(tokenBalance);
+          const requested = parseFloat(params.amount);
+          if (requested > available && available >= 0) {
+            return fail(new Error(
+              `Insufficient ${params.token} balance. Have: ${available}, Need: ${requested}. ` +
+              `Fund your wallet with ${params.token} first, or use wallet_fund_token.`
+            ));
+          }
+        } catch {
+          // Balance check failed — proceed anyway, on-chain will validate
+        }
+
         const result = await client.supplyCollateral(params.token, params.amount);
         return ok(JSON.stringify({
           status: "deposited",
@@ -595,35 +723,32 @@ export default function register(api: any) {
   // ═══════════════════════════════════════════════════════
   api.registerTool({
     name: "morpho_deposit_and_borrow",
-    description:
-      "Deposit collateral AND borrow in one batched transaction via AgentAccount (ERC-7579 batch mode). " +
-      "Deposits collateral from EOA into Morpho, then borrows loan token. All in one tx. " +
-      "Supports any loan token (USDC, WETH, etc.).",
+    description: "Deposit collateral and borrow in one atomic transaction. Gas-efficient batch operation.",
     parameters: {
       type: "object",
       properties: {
-        collateralAmount: { type: "string", description: "Amount of collateral (e.g. '0.05')" },
+        amount: { type: "string", description: "Collateral amount (e.g. '0.05')" },
         token: { type: "string", description: "Collateral token" },
         borrowAmount: { type: "string", description: "Amount to borrow (e.g. '50')" },
         loanToken: { type: "string", description: "Loan token to borrow (e.g. 'USDC', 'WETH'). Optional — defaults to most liquid market." },
       },
-      required: ["collateralAmount", "token", "borrowAmount"],
+      required: ["amount", "token", "borrowAmount"],
     },
-    async execute(_id: string, params: { collateralAmount: string; token: string; borrowAmount: string; loanToken?: string }) {
+    async execute(_id: string, params: { amount: string; token: string; borrowAmount: string; loanToken?: string }) {
       try {
         const cfg = getConfig(api);
         requireChain(cfg);
         const client = createMorphoClient(cfg);
         const result = await client.depositAndBorrow(
           params.token,
-          params.collateralAmount,
+          params.amount,
           params.borrowAmount,
           undefined,
           params.loanToken,
         );
         return ok(JSON.stringify({
           status: "deposited_and_borrowed",
-          collateral: `${params.collateralAmount} ${params.token}`,
+          collateral: `${params.amount} ${params.token}`,
           borrowed: `${params.borrowAmount}`,
           agentAccount: result.agentAccount,
           tx: txLink(result.tx),
@@ -632,56 +757,13 @@ export default function register(api: any) {
     },
   });
 
-  // ═══════════════════════════════════════════════════════
-  //  TOOL: morpho_sponsor
-  // ═══════════════════════════════════════════════════════
-  api.registerTool({
-    name: "agether_sponsor",
-    description:
-      "Transfer tokens to another agent's Safe account (or any address). " +
-      "The target agent can then supply the tokens to Morpho Blue or use them directly.",
-    parameters: {
-      type: "object",
-      properties: {
-        agentId: { type: "string", description: "Target agent's ERC-8004 ID (e.g. '17676')" },
-        agentAddress: { type: "string", description: "Target account address (alternative to agentId)" },
-        amount: { type: "string", description: "Token amount (e.g. '0.05')" },
-        token: { type: "string", description: "Token to send (e.g. 'WETH', 'USDC')" },
-      },
-      required: ["amount", "token"],
-    },
-    async execute(_id: string, params: { agentId?: string; agentAddress?: string; amount: string; token: string }) {
-      try {
-        if (!params.agentId && !params.agentAddress) return fail("Provide either agentId or agentAddress");
-        const cfg = getConfig(api);
-        requireChain(cfg);
-        const client = createAgetherClient(cfg);
-
-        const target = params.agentId
-          ? { agentId: params.agentId }
-          : { address: params.agentAddress! };
-
-        const result = await client.sponsor(target, params.token, params.amount);
-        return ok(JSON.stringify({
-          status: "sponsored",
-          target: result.targetAccount,
-          targetAgentId: result.targetAgentId || "by address",
-          amount: `${params.amount} ${params.token}`,
-          tx: txLink(result.tx),
-        }));
-      } catch (e) { return fail(e); }
-    },
-  });
 
   // ═══════════════════════════════════════════════════════
   //  TOOL: morpho_borrow
   // ═══════════════════════════════════════════════════════
   api.registerTool({
     name: "morpho_borrow",
-    description:
-      "Borrow loan token against deposited collateral via Morpho Blue. " +
-      "Borrowed tokens land in AgentAccount. Requires collateral deposited first. " +
-      "Supports any loan token (USDC, WETH, etc.).",
+    description: "Borrow against deposited collateral. Pre-checks health factor and max borrowable.",
     parameters: {
       type: "object",
       properties: {
@@ -696,14 +778,59 @@ export default function register(api: any) {
         const cfg = getConfig(api);
         requireChain(cfg);
         const client = createMorphoClient(cfg);
+
+        // Phase 1 Fix: Pre-check health factor before borrow
+        // Warns if resulting HF would be dangerously low
+        let healthWarning = "";
+        try {
+          const [status, maxBorrow] = await Promise.all([
+            client.getStatus(),
+            client.getMaxBorrowable(),
+          ]);
+          const maxBorrowUsd = Number(maxBorrow.total) / 1e6;
+          const requestedAmount = parseFloat(params.amount);
+
+          if (requestedAmount > maxBorrowUsd && maxBorrowUsd > 0) {
+            return fail(new Error(
+              `Borrow amount $${requestedAmount} exceeds max borrowable $${maxBorrowUsd.toFixed(2)}. ` +
+              `Reduce amount or deposit more collateral first.`
+            ));
+          }
+
+          // Estimate resulting health factor
+          if (status.positions.length > 0) {
+            const currentDebt = parseFloat(status.totalDebt);
+            const totalCollateralValue = maxBorrow.byMarket.reduce(
+              (sum: number, m: any) => sum + Number(m.collateralValue) / 1e6, 0
+            );
+            const newDebt = currentDebt + requestedAmount;
+            const lltv = 0.80; // Approximate LLTV
+            const estimatedHF = totalCollateralValue > 0 ? (totalCollateralValue * lltv) / newDebt : Infinity;
+
+            if (estimatedHF < 1.1 && estimatedHF !== Infinity) {
+              return fail(new Error(
+                `⚠️ This borrow would result in estimated Health Factor of ${estimatedHF.toFixed(2)} — DANGEROUSLY CLOSE to liquidation (HF < 1.0). ` +
+                `Current debt: $${currentDebt.toFixed(2)}, Collateral value: $${totalCollateralValue.toFixed(2)}. ` +
+                `Reduce borrow amount or add more collateral.`
+              ));
+            } else if (estimatedHF < 1.5 && estimatedHF !== Infinity) {
+              healthWarning = `⚠️ Warning: Estimated HF after borrow: ${estimatedHF.toFixed(2)} (below safe threshold of 1.5). Consider a smaller amount.`;
+            }
+          }
+        } catch {
+          // Pre-check failed — proceed with borrow anyway, on-chain will catch errors
+        }
+
         const result = await client.borrow(params.amount, params.token, undefined, params.loanToken);
-        return ok(JSON.stringify({
+        const response: any = {
           status: "borrowed",
           amount: params.amount,
           collateral: result.collateralToken,
           agentAccount: result.agentAccount,
           tx: txLink(result.tx),
-        }));
+        };
+        if (healthWarning) response.healthWarning = healthWarning;
+        return ok(JSON.stringify(response));
       } catch (e) { return fail(e); }
     },
   });
@@ -713,10 +840,7 @@ export default function register(api: any) {
   // ═══════════════════════════════════════════════════════
   api.registerTool({
     name: "morpho_repay",
-    description:
-      "Repay borrowed loan token back to Morpho Blue from AgentAccount. Reduces debt. " +
-      "Use amount 'all' to repay full debt and clear dust shares. " +
-      "Supports any loan token (USDC, WETH, etc.).",
+    description: "Repay debt to Morpho Blue. Use amount='all' for full repayment including dust.",
     parameters: {
       type: "object",
       properties: {
@@ -784,7 +908,7 @@ export default function register(api: any) {
   //  TOOL: morpho_supply  (lender-side — earn yield)
   // ═══════════════════════════════════════════════════════
   api.registerTool({
-    name: "morpho_supply",
+    name: "morpho_lend",
     description:
       "Supply a loan token (USDC, WETH, etc.) to a Morpho Blue market as a LENDER to earn yield. " +
       "This is the lending side — your tokens earn interest from borrowers. " +
@@ -828,7 +952,7 @@ export default function register(api: any) {
   //  TOOL: morpho_supply_status  (supply positions + yield)
   // ═══════════════════════════════════════════════════════
   api.registerTool({
-    name: "morpho_supply_status",
+    name: "morpho_lending_status",
     description:
       "Show all supply (lending) positions with earned yield. " +
       "Tracks yield WITHOUT any database — reads Morpho events directly from blockchain. " +
@@ -881,7 +1005,7 @@ export default function register(api: any) {
   //  TOOL: morpho_withdraw_supply  (withdraw lent tokens)
   // ═══════════════════════════════════════════════════════
   api.registerTool({
-    name: "morpho_withdraw_supply",
+    name: "morpho_withdraw_lending",
     description:
       "Withdraw supplied tokens (principal + earned interest) from a Morpho Blue lending position. " +
       "By default keeps tokens in AgentAccount. Set toEoa=true to send to EOA wallet. " +
@@ -923,9 +1047,7 @@ export default function register(api: any) {
   // ═══════════════════════════════════════════════════════
   api.registerTool({
     name: "morpho_markets",
-    description:
-      "List available Morpho Blue markets — liquidity, supply/borrow APY, utilization, LLTV. " +
-      "Supports all loan tokens (USDC, WETH, etc.). Optionally filter by collateral or loan token.",
+    description: "List Morpho Blue markets — collateral/loan pairs, APY rates, liquidity.",
     parameters: {
       type: "object",
       properties: {
@@ -1060,7 +1182,7 @@ export default function register(api: any) {
   //  TOOL: morpho_supply_options  (find lending opportunities)
   // ═══════════════════════════════════════════════════════
   api.registerTool({
-    name: "morpho_supply_options",
+    name: "morpho_lending_options",
     description:
       "Find supply/lending opportunities for a specific loan token. " +
       "Use when user asks 'what can I supply to earn WETH?', 'where can I lend USDC?', " +
@@ -1133,9 +1255,7 @@ export default function register(api: any) {
   // ═══════════════════════════════════════════════════════
   api.registerTool({
     name: "agether_score",
-    description:
-      "Get the agent's current onchain credit score. " +
-      "Use 'refresh' param to request a fresh score computation (costs USDC via x402).",
+    description: "Get credit score. Set refresh=true to recompute (costs USDC via x402). Checks staleness first.",
     parameters: {
       type: "object",
       properties: {
@@ -1151,6 +1271,25 @@ export default function register(api: any) {
         const agentId = client.getAgentId().toString();
 
         if (params.refresh) {
+          // Phase 1 Fix: Check if current score is still fresh before paying for refresh
+          try {
+            const scoring0 = new ScoringClient({ endpoint: BACKEND_URL, chainId: cfg.chainId });
+            const current = await scoring0.getCurrentScore(agentId);
+            if (current && current.fresh) {
+              return ok(JSON.stringify({
+                status: "score_still_fresh",
+                warning: "Current score is still fresh — paying for a new score is unnecessary.",
+                currentScore: current.score,
+                scoreAge: current.age,
+                suggestion: "Score will need refresh when age exceeds freshness threshold. " +
+                  "To force refresh anyway, call agether_score with refresh=true again.",
+                ...current,
+              }));
+            }
+          } catch {
+            // If staleness check fails, proceed with refresh anyway
+          }
+
           // x402-gated fresh score via ScoringClient
           const accountAddress = await client.getAccountAddress();
           const contracts = getContractAddresses(cfg.chainId);
@@ -1181,15 +1320,46 @@ export default function register(api: any) {
   });
 
   // ═══════════════════════════════════════════════════════
-  //  TOOL: wallet_fund
+  //  TOOL: wallet_withdraw_token
+  // ═══════════════════════════════════════════════════════
+  api.registerTool({
+    name: "wallet_withdraw_token",
+    description: "Withdraw ERC-20 token from AgentAccount to EOA. Use amount='all' for full balance.",
+    parameters: {
+      type: "object",
+      properties: {
+        token: { type: "string", description: "Token to withdraw (e.g. 'USDC', 'WETH')" },
+        amount: { type: "string", description: "Amount to withdraw (e.g. '100' or 'all')" },
+      },
+      required: ["token", "amount"],
+    },
+    async execute(_id: string, params: { token: string; amount: string }) {
+      try {
+        const cfg = getConfig(api);
+        requireChain(cfg);
+        const client = createAgetherClient(cfg);
+        const result = await client.withdrawToken(params.token, params.amount);
+        return ok(JSON.stringify({
+          status: "withdrawn",
+          token: result.token,
+          amount: result.amount,
+          destination: result.destination,
+          tx: txLink(result.tx),
+        }));
+      } catch (e) { return fail(e); }
+    },
+  });
+
+  // ═══════════════════════════════════════════════════════
+  //  TOOL: wallet_withdraw_eth
   // ═══════════════════════════════════════════════════════
   api.registerTool({
-    name: "wallet_fund",
-    description: "Transfer USDC from EOA wallet into AgentAccount.",
+    name: "wallet_withdraw_eth",
+    description: "Withdraw ETH from AgentAccount to EOA. Use amount='all' for full balance.",
     parameters: {
       type: "object",
       properties: {
-        amount: { type: "string", description: "USDC amount (e.g. '50')" },
+        amount: { type: "string", description: "ETH amount to withdraw (e.g. '0.01' or 'all')" },
       },
       required: ["amount"],
     },
@@ -1198,10 +1368,43 @@ export default function register(api: any) {
         const cfg = getConfig(api);
         requireChain(cfg);
         const client = createAgetherClient(cfg);
-        const result = await client.fundAccount(params.amount);
+        const result = await client.withdrawEth(params.amount);
+        return ok(JSON.stringify({
+          status: "withdrawn",
+          token: "ETH",
+          amount: `${result.amount} ETH`,
+          destination: result.destination,
+          tx: txLink(result.tx),
+        }));
+      } catch (e) { return fail(e); }
+    },
+  });
+
+  // ═══════════════════════════════════════════════════════
+  //  TOOL: wallet_fund_token
+  // ═══════════════════════════════════════════════════════
+  api.registerTool({
+    name: "wallet_fund_token",
+    description:
+      "Transfer any ERC-20 token from EOA wallet into AgentAccount. " +
+      "Works with USDC, WETH, wstETH, cbBTC, or any token supported by Morpho markets.",
+    parameters: {
+      type: "object",
+      properties: {
+        token: { type: "string", description: "Token to transfer (e.g. 'USDC', 'WETH')" },
+        amount: { type: "string", description: "Amount to transfer (e.g. '100')" },
+      },
+      required: ["token", "amount"],
+    },
+    async execute(_id: string, params: { token: string; amount: string }) {
+      try {
+        const cfg = getConfig(api);
+        requireChain(cfg);
+        const client = createAgetherClient(cfg);
+        const result = await client.fundAccountToken(params.token, params.amount);
         return ok(JSON.stringify({
           status: "funded",
-          amount: `$${params.amount}`,
+          amount: `${params.amount} ${params.token}`,
           tx: txLink(result.txHash),
         }));
       } catch (e) { return fail(e); }
@@ -1209,32 +1412,45 @@ export default function register(api: any) {
   });
 
   // ═══════════════════════════════════════════════════════
-  //  TOOL: wallet_withdraw_token
+  //  TOOL: wallet_transfer
   // ═══════════════════════════════════════════════════════
   api.registerTool({
-    name: "wallet_withdraw_token",
+    name: "wallet_transfer",
     description:
-      "Withdraw (transfer) a token from AgentAccount to EOA wallet. " +
-      "Works with any ERC-20 token (USDC, WETH, wstETH, cbBTC, etc.). " +
-      "Use amount 'all' to withdraw the full balance.",
+      "Transfer any ERC-20 token or ETH from AgentAccount to any address or agent. " +
+      "Specify either 'address' (0x...) or 'agentId' as destination. " +
+      "Set token to 'ETH' for native ETH transfers. Use amount 'all' to send full balance.",
     parameters: {
       type: "object",
       properties: {
-        token: { type: "string", description: "Token to withdraw (e.g. 'USDC', 'WETH')" },
-        amount: { type: "string", description: "Amount to withdraw (e.g. '100' or 'all')" },
+        token: { type: "string", description: "Token to send (e.g. 'USDC', 'WETH', 'ETH')" },
+        amount: { type: "string", description: "Amount to send (e.g. '100' or 'all')" },
+        address: { type: "string", description: "Destination address (0x...)" },
+        agentId: { type: "string", description: "Destination agent ID" },
       },
       required: ["token", "amount"],
     },
-    async execute(_id: string, params: { token: string; amount: string }) {
+    async execute(_id: string, params: { token: string; amount: string; address?: string; agentId?: string }) {
       try {
         const cfg = getConfig(api);
         requireChain(cfg);
         const client = createAgetherClient(cfg);
-        const result = await client.withdrawToken(params.token, params.amount);
+
+        if (!params.address && !params.agentId) {
+          return fail(new Error("Provide either 'address' or 'agentId' as destination"));
+        }
+        const to = params.address ? { address: params.address } : { agentId: params.agentId };
+
+        let result;
+        if (params.token.toUpperCase() === 'ETH') {
+          result = await client.transferEth(params.amount, to);
+        } else {
+          result = await client.transferToken(params.token, params.amount, to);
+        }
+
         return ok(JSON.stringify({
-          status: "withdrawn",
-          token: result.token,
-          amount: result.amount,
+          status: "transferred",
+          amount: `${result.amount} ${result.token}`,
           destination: result.destination,
           tx: txLink(result.tx),
         }));
@@ -1243,31 +1459,41 @@ export default function register(api: any) {
   });
 
   // ═══════════════════════════════════════════════════════
-  //  TOOL: wallet_withdraw_eth
+  //  TOOL: wallet_approve
   // ═══════════════════════════════════════════════════════
   api.registerTool({
-    name: "wallet_withdraw_eth",
+    name: "wallet_approve",
     description:
-      "Withdraw ETH from AgentAccount to EOA wallet. " +
-      "Use amount 'all' to withdraw the full ETH balance.",
+      "Approve a spender (address or agent) to use ERC-20 tokens from AgentAccount. " +
+      "Specify either 'address' (0x...) or 'agentId' as spender. " +
+      "Use amount 'max' for unlimited approval.",
     parameters: {
       type: "object",
       properties: {
-        amount: { type: "string", description: "ETH amount to withdraw (e.g. '0.01' or 'all')" },
+        token: { type: "string", description: "Token to approve (e.g. 'USDC', 'WETH')" },
+        amount: { type: "string", description: "Allowance amount (e.g. '1000' or 'max')" },
+        address: { type: "string", description: "Spender address (0x...)" },
+        agentId: { type: "string", description: "Spender agent ID" },
       },
-      required: ["amount"],
+      required: ["token", "amount"],
     },
-    async execute(_id: string, params: { amount: string }) {
+    async execute(_id: string, params: { token: string; amount: string; address?: string; agentId?: string }) {
       try {
         const cfg = getConfig(api);
         requireChain(cfg);
         const client = createAgetherClient(cfg);
-        const result = await client.withdrawEth(params.amount);
+
+        if (!params.address && !params.agentId) {
+          return fail(new Error("Provide either 'address' or 'agentId' as spender"));
+        }
+        const spender = params.address ? { address: params.address } : { agentId: params.agentId };
+
+        const result = await client.approveToken(params.token, params.amount, spender);
         return ok(JSON.stringify({
-          status: "withdrawn",
-          token: "ETH",
-          amount: `${result.amount} ETH`,
-          destination: result.destination,
+          status: "approved",
+          token: result.token,
+          amount: result.amount,
+          spender: result.spender,
           tx: txLink(result.tx),
         }));
       } catch (e) { return fail(e); }
@@ -1568,7 +1794,7 @@ export default function register(api: any) {
         if (safeUsdc > 0) {
           checks.push({ check: "USDC (AgentAccount)", status: `✅ $${safeUsdc.toFixed(2)}` });
         } else if (eoaUsdc > 0) {
-          checks.push({ check: "USDC", status: `⚠️ $${eoaUsdc.toFixed(2)} in EOA only`, detail: "Use wallet_fund or morpho_deposit_and_borrow to get USDC into AgentAccount" });
+          checks.push({ check: "USDC", status: `⚠️ $${eoaUsdc.toFixed(2)} in EOA only`, detail: "Use wallet_fund_token or morpho_deposit_and_borrow to get USDC into AgentAccount" });
         } else {
           checks.push({ check: "USDC", status: "❌ no USDC anywhere", detail: "Deposit collateral and borrow, or send USDC to EOA" });
         }
@@ -1584,120 +1810,8 @@ export default function register(api: any) {
   //  SLASH COMMANDS (no AI needed)
   // ═══════════════════════════════════════════════════════
 
-  api.registerCommand({
-    name: "balance",
-    description: "Show agent wallet balances (no AI)",
-    handler: async () => {
-      try {
-        const cfg = getConfig(api);
-        const client = createAgetherClient(cfg);
-        const b = await client.getBalances();
-
-        const nz = (v: string) => parseFloat(v) > 0;
-
-        let text = `💰 Agent #${b.agentId}\n`;
-        text += `Address: ${b.address}`;
-        if (nz(b.eth)) text += `\nETH: ${parseFloat(b.eth).toFixed(6)}`;
-        if (nz(b.usdc)) text += `\nUSDC: $${b.usdc}`;
-        for (const [sym, val] of Object.entries(b.collateral ?? {})) {
-          if (nz(val)) text += `\n${sym}: ${parseFloat(val).toFixed(6)}`;
-        }
-
-        if (b.agentAccount) {
-          const a = b.agentAccount;
-          const hasAny = nz(a.eth) || nz(a.usdc) ||
-            Object.values(a.collateral ?? {}).some(nz);
-          if (hasAny) {
-            text += `\n\n🏦 AgentAccount: ${a.address}`;
-            if (nz(a.eth)) text += `\nETH: ${parseFloat(a.eth).toFixed(6)}`;
-            if (nz(a.usdc)) text += `\nUSDC: $${a.usdc}`;
-            for (const [sym, val] of Object.entries(a.collateral ?? {})) {
-              if (nz(val)) text += `\n${sym}: ${parseFloat(val).toFixed(6)}`;
-            }
-          } else {
-            text += `\n\n🏦 AgentAccount: ${a.address}\n(empty)`;
-          }
-        }
-
-        return { text };
-      } catch (e: any) {
-        return { text: `❌ ${e.message}` };
-      }
-    },
-  });
-
-  api.registerCommand({
-    name: "morpho",
-    description: "Show Morpho positions with Health Factor (no AI)",
-    handler: async () => {
-      try {
-        const cfg = getConfig(api);
-        const client = createMorphoClient(cfg);
-        const [s, maxBorrow] = await Promise.all([
-          client.getStatus(),
-          client.getMaxBorrowable(),
-        ]);
-
-        let text = `📊 Morpho\nAccount: ${s.agentAccount}\nTotal debt: $${s.totalDebt}\n`;
-        for (const p of s.positions) {
-          const mm = maxBorrow.byMarket.find((m: any) => m.collateralToken === p.collateralToken);
-          const cv = mm ? Number(mm.collateralValue) / 1e6 : 0;
-          const debt = parseFloat(p.debt);
-          const ltv = cv > 0 ? debt / cv : 0;
-          const hf = ltv > 0 ? 0.80 / ltv : Infinity;
-          const hfStr = debt === 0 ? "∞" : hf.toFixed(2);
-          const icon = debt === 0 ? "🟢" : hf <= 1.0 ? "🔴" : hf <= 1.15 ? "🟡" : "🟢";
-          text += `\n${icon} ${p.collateralToken}: ${p.collateral} col, $${p.debt} debt, HF ${hfStr}`;
-        }
-        if (s.positions.length === 0) text += "\nNo active positions.";
-        return { text };
-      } catch (e: any) {
-        return { text: `❌ ${e.message}` };
-      }
-    },
-  });
-
-  api.registerCommand({
-    name: "health",
-    description: "Quick position health check — LTV, liquidation risk, balances (no AI)",
-    handler: async () => {
-      try {
-        const cfg = getConfig(api);
-        const agetherCfg = api.config?.plugins?.entries?.agether?.config ?? {};
-        const healthThreshold = agetherCfg.healthAlertThreshold ?? 70;
-        const agether = createAgetherClient(cfg);
-        const morpho = createMorphoClient(cfg);
-
-        const [balances, status, maxBorrow] = await Promise.all([
-          agether.getBalances(),
-          morpho.getStatus(),
-          morpho.getMaxBorrowable(),
-        ]);
-
-        let text = `🏥 Health — Agent #${balances.agentId}\n`;
-        text += `EOA: ${balances.eth} ETH, $${balances.usdc} USDC\n`;
-        if (balances.agentAccount) {
-          text += `Safe: $${balances.agentAccount.usdc} USDC\n`;
-        }
-        text += `Total debt: $${status.totalDebt}\n`;
-        text += `Headroom: $${(Number(maxBorrow.total) / 1e6).toFixed(2)}\n`;
 
-        for (const p of status.positions) {
-          const mm = maxBorrow.byMarket.find((m: any) => m.collateralToken === p.collateralToken);
-          const cv = mm ? Number(mm.collateralValue) / 1e6 : 0;
-          const debt = parseFloat(p.debt);
-          const ltv = cv > 0 ? (debt / cv) * 100 : 0;
-          const icon = debt === 0 ? "🟢" : ltv >= 80 ? "🔴" : ltv >= healthThreshold ? "🟡" : "🟢";
-          text += `\n${icon} ${p.collateralToken}: ${p.collateral} col, $${p.debt} debt, LTV ${ltv.toFixed(1)}%`;
-        }
-        if (status.positions.length === 0) text += "\nNo active positions.";
 
-        return { text };
-      } catch (e: any) {
-        return { text: `❌ ${e.message}` };
-      }
-    },
-  });
 
   api.registerCommand({
     name: "rates",
@@ -1736,7 +1850,7 @@ export default function register(api: any) {
         const balances = await client.getBalances();
         const agentId = balances.agentId ?? "?";
         const safeUsdc = balances.agentAccount?.usdc ?? "0";
-        const chainName = CHAIN_DEFAULTS[cfg.chainId]?.chainName ?? `Chain ${cfg.chainId}`;
+        const chainName = CHAIN_DEFAULTS[state.activeChainId]?.chainName ?? `Chain ${state.activeChainId}`;
         api.logger?.info?.(
           `[agether] Session start — ${chainName}, Agent #${agentId}, EOA: ${balances.eth} ETH / $${balances.usdc} USDC, Safe: $${safeUsdc} USDC`,
         );