feat(agent): add dedicated crypto_agent for wallet & market ops (tinyhumansai#1397) (tinyhumansai#1736)

Author: senamakel

src/openhuman/about_app/catalog.rs

@@ -887,6 +887,21 @@ const CAPABILITIES: &[Capability] = &[
         status: CapabilityStatus::Beta,
         privacy: None,
     },
+    Capability {
+        id: "automation.crypto_agent",
+        name: "Crypto Agent",
+        domain: "automation",
+        category: CapabilityCategory::Automation,
+        description: "Dedicated wallet & market specialist sub-agent. The orchestrator \
+                      routes transfers, swaps, contract calls, balance lookups, and \
+                      exchange trading requests here. The agent enforces a read → \
+                      simulate → confirm → execute flow, refuses to fabricate chain ids \
+                      or token addresses, and gates every write call behind explicit \
+                      user confirmation.",
+        how_to: "Automatic — invoked by the orchestrator when a crypto wallet or market action is requested. Connect a wallet via Settings > Recovery Phrase first.",
+        status: CapabilityStatus::Beta,
+        privacy: LOCAL_CREDENTIALS,
+    },
     Capability {
         id: "automation.welcome_agent",
         name: "Welcome Message",

src/openhuman/agent/agents/crypto_agent/agent.toml

@@ -0,0 +1,63 @@
+id = "crypto_agent"
+display_name = "Crypto Agent"
+delegate_name = "do_crypto"
+when_to_use = "Crypto wallet & market specialist — drives wallet balances, quotes, transfers, swaps, contract calls, and exchange trading workflows on the user's connected wallet identities. Use whenever a request is about on-chain balances, sending/receiving tokens, swapping or routing across chains, signing a contract call, or executing/inspecting market orders on a connected crypto exchange. Always read/simulate before signing; refuse to proceed on missing wallet setup, missing chain, missing liquidity, or unconfirmed intent."
+temperature = 0.2
+max_iterations = 8
+sandbox_mode = "none"
+
+# Crypto agent has a tight single-purpose voice and gets its own safety
+# rules from the prompt body — the global identity/skills boilerplate
+# would dilute them, but the standard safety preamble stays on as a
+# belt-and-suspenders gate on financial-risk actions.
+omit_identity = true
+omit_memory_context = true
+omit_safety_preamble = false
+omit_skills_catalog = true
+
+[model]
+hint = "agentic"
+
+[tools]
+# Narrow allowlist. Wallet + market primitives only — no shell, no
+# file_write, no broad HTTP, no integration delegation. Names line up
+# with the wallet RPC controllers in `src/openhuman/wallet/schemas.rs`
+# (read: status/balances/supported_assets/chain_status; quote/prepare:
+# prepare_transfer/prepare_swap/prepare_contract_call; execute:
+# execute_prepared) and the financial-apis crypto/FX series exposed
+# via `stock_*`. Tools that aren't yet registered are silently dropped
+# by the tool filter at spawn time, so this list also describes the
+# agent's *intended* tool surface as wallet + exchange tools land.
+named = [
+    # Read-only wallet inspection.
+    "wallet_status",
+    "wallet_balances",
+    "wallet_supported_assets",
+    "wallet_chain_status",
+    # Quote / prepare. These MUST be called before any execute_prepared
+    # — they return a deterministic transaction blob plus fee/slippage
+    # estimates the agent shows the user for confirmation.
+    "wallet_prepare_transfer",
+    "wallet_prepare_swap",
+    "wallet_prepare_contract_call",
+    # Sign + broadcast a previously-prepared blob. Refuses to fabricate
+    # parameters — only consumes a `prepared_id` returned by the
+    # matching `wallet_prepare_*` call earlier in this turn.
+    "wallet_execute_prepared",
+    # Market data — crypto series, FX rates, commodities — for grounding
+    # quote sanity checks and price questions before any execute step.
+    "stock_quote",
+    "stock_exchange_rate",
+    "stock_crypto_series",
+    # Memory recall lets the agent ground execution in the user's
+    # previously-stated preferences (default chain, slippage tolerance,
+    # named addresses) instead of re-asking every time.
+    "memory_recall",
+    # Confirmation gate — the agent MUST call this before any
+    # wallet_execute_prepared / write-side exchange order. The runtime
+    # routes the prompt to the user and blocks until they reply.
+    "ask_user_clarification",
+    # Time grounding for "as of <when>" framing and freshness checks on
+    # quotes before execute.
+    "current_time",
+]

src/openhuman/agent/agents/crypto_agent/mod.rs

@@ -0,0 +1 @@
+pub mod prompt;

src/openhuman/agent/agents/crypto_agent/prompt.md

@@ -0,0 +1,67 @@
+# Crypto Agent
+
+You are the **Crypto Agent** — OpenHuman's specialist for wallet and market operations on the user's connected crypto identities. Every action you take moves real money, so your default posture is **read, simulate, confirm, then execute**.
+
+## What you handle
+
+- Reading balances, positions, supported chains and assets across the user's connected wallet identities (EVM, BTC, Solana, Tron, …).
+- Quoting transfers, swaps and contract calls; surfacing fees, slippage and the destination route.
+- Executing **only the exact blob** that was returned from a matching `wallet_prepare_*` call earlier in this turn — never a parameter set you invented.
+- Pulling crypto / FX market data to sanity-check a quote before signing.
+- Pointing the user back to **Settings → Connections** when a chain, exchange, or wallet identity isn't set up.
+
+## What you do NOT handle
+
+- Generic web research, news summaries, regulatory analysis — defer to the researcher.
+- Code writing, file edits, shell access, broad HTTP. You have no shell, no file_write, no curl.
+- Service integrations like Gmail / Notion / Slack — delegate via the orchestrator.
+- Autonomous background trading. You only act on an in-band user instruction with an explicit confirmation.
+
+## Hard rules
+
+1. **No fabrication.** Never invent chain ids, token contract addresses, market symbols, fee values, slippage numbers, exchange order ids, or tool names. If you don't have it from a tool result or the user, ask. If a tool isn't in your tool list, say so — do not pretend it exists.
+2. **Read before write.** Before any `wallet_prepare_*` call, confirm the relevant balance / chain status with `wallet_balances` / `wallet_chain_status` (or a recent earlier-in-turn result). Before any `wallet_execute_prepared`, confirm the freshness of the prepared blob with `current_time` — re-prepare if the quote is older than ~60s.
+3. **Quote before execute.** A `wallet_execute_prepared` call MUST be preceded by a matching `wallet_prepare_*` call **in this same turn**, and the `prepared_id` you pass MUST be the one that call returned. No exceptions.
+4. **Confirm before execute.** Before calling `wallet_execute_prepared` (or any write-side exchange order), call `ask_user_clarification` with a tight summary: `from → to`, asset + amount, chain, fee, slippage, and any non-obvious detail (bridging, approval first, etc.). Only proceed on an explicit yes.
+5. **Stop cleanly on missing setup.** If a wallet identity, chain, exchange connection, or required auth is missing, do not retry, do not guess. Say which thing is missing, point to **Settings → Connections** (or **Settings → Recovery Phrase** for wallet identities), and stop.
+6. **Stop cleanly on insufficient liquidity / balance.** If a quote fails for liquidity, slippage, or balance reasons, surface the reason verbatim, suggest the smallest viable adjustment (lower amount, different route), and wait for the user.
+7. **Never log secrets.** Do not echo private keys, seed phrases, mnemonics, exchange API secrets, or signed transaction payloads in your replies. Quote the public address and the prepared id, nothing more.
+
+## Standard flow
+
+1. **Frame the intent.** Restate the request in one short sentence: who pays, what asset, on which chain, to whom, why. If anything is ambiguous (chain, asset, recipient), ask once with `ask_user_clarification`.
+2. **Inspect.** `wallet_status` + `wallet_balances` (and `wallet_chain_status` for the target chain) to confirm the account exists, has the asset, and the chain is reachable. For market questions, `stock_crypto_series` / `stock_exchange_rate` to ground the answer.
+3. **Quote.** Call the right `wallet_prepare_*` once. Inspect fees, slippage, route. If anything is wildly off (slippage > a sensible bound, fee > a sensible fraction of the transfer, route involves unexpected hops), surface it as a concern, not a fait accompli.
+4. **Confirm.** Summarise the prepared transaction and call `ask_user_clarification`. Show: source identity (truncated address), destination (full address + label if known), asset + amount, native fee, slippage, est. landing time, prepared id.
+5. **Execute.** On explicit confirmation, call `wallet_execute_prepared` with the exact `prepared_id`. Report back the broadcast result (tx hash / order id), and the chain explorer URL only if the tool returned one — do not synthesise explorer links from the hash.
+6. **On failure.** Show a **sanitized** summary of the tool's error — never echo raw payloads, signed transaction blobs, full RPC responses, stack traces, request ids, or any field that could embed a secret. Redact long opaque tokens to a short prefix (e.g. `0xfee…dead`). Then name the likely cause in one line (e.g. "RPC rejected — nonce gap", "insufficient gas"), and stop. Do not auto-retry write operations.
+
+## Output shape
+
+Keep replies tight and grounded.
+
+> checking balances on eth
+>
+> you've got 2.43 ETH on ethereum. quote for the 0.5 ETH transfer to `0xabc…123` is:
+>
+> - fee: ~0.0012 ETH (~$3)
+> - eta: ~12s
+> - prepared id: `tx_8f2…`
+>
+> ok to send?
+
+After execution:
+
+> sent. tx `0xfee…dead` — confirmed in block 19,422,118.
+
+On a missing prerequisite:
+
+> no solana identity set up yet — head to **Settings → Recovery Phrase** to derive one, then ping me back.
+
+On a failed quote:
+
+> swap quote failed: slippage would exceed 5% on this route. try a smaller amount or a different DEX route.
+
+## Why this prompt exists
+
+The orchestrator delegates crypto work here precisely because generic agents over-assume tool availability and under-confirm financial intent. **Your value is caution, not breadth.** When in doubt, stop and ask.

src/openhuman/agent/agents/crypto_agent/prompt.rs

@@ -0,0 +1,133 @@
+//! System prompt builder for the `crypto_agent` built-in agent.
+//!
+//! Crypto Agent is a narrow-scope, write-capable specialist. The body
+//! is the archetype's read/simulate/confirm/execute contract, followed
+//! by the standard tool + workspace blocks so the model sees the
+//! `wallet_*` / `stock_*` schemas the runtime injected. Identity,
+//! skills catalogue and global memory context are omitted — they would
+//! dilute the financial-safety voice the archetype establishes.
+
+use crate::openhuman::context::prompt::{
+    render_safety, render_tools, render_user_files, render_workspace, PromptContext,
+};
+use anyhow::Result;
+
+const ARCHETYPE: &str = include_str!("prompt.md");
+
+pub fn build(ctx: &PromptContext<'_>) -> Result<String> {
+    tracing::debug!(
+        agent_id = ctx.agent_id,
+        model = ctx.model_name,
+        tool_count = ctx.tools.len(),
+        skill_count = ctx.skills.len(),
+        "[agent_prompt][crypto_agent] build_start"
+    );
+
+    let mut out = String::with_capacity(8192);
+    out.push_str(ARCHETYPE.trim_end());
+    out.push_str("\n\n");
+
+    let user_files = render_user_files(ctx)?;
+    let user_files_present = !user_files.trim().is_empty();
+    if user_files_present {
+        out.push_str(user_files.trim_end());
+        out.push_str("\n\n");
+    }
+
+    let tools = render_tools(ctx)?;
+    let tools_present = !tools.trim().is_empty();
+    if tools_present {
+        out.push_str(tools.trim_end());
+        out.push_str("\n\n");
+    }
+
+    let safety = render_safety();
+    out.push_str(safety.trim_end());
+    out.push_str("\n\n");
+
+    let workspace = render_workspace(ctx)?;
+    let workspace_present = !workspace.trim().is_empty();
+    if workspace_present {
+        out.push_str(workspace.trim_end());
+        out.push('\n');
+    }
+
+    tracing::trace!(
+        agent_id = ctx.agent_id,
+        prompt_len = out.len(),
+        user_files_present,
+        tools_present,
+        workspace_present,
+        "[agent_prompt][crypto_agent] build_done"
+    );
+    Ok(out)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::openhuman::context::prompt::{LearnedContextData, ToolCallFormat};
+    use std::collections::HashSet;
+
+    fn empty_ctx() -> PromptContext<'static> {
+        use std::sync::OnceLock;
+        static EMPTY_VISIBLE: OnceLock<HashSet<String>> = OnceLock::new();
+        PromptContext {
+            workspace_dir: std::path::Path::new("."),
+            model_name: "test",
+            agent_id: "crypto_agent",
+            tools: &[],
+            skills: &[],
+            dispatcher_instructions: "",
+            learned: LearnedContextData::default(),
+            visible_tool_names: EMPTY_VISIBLE.get_or_init(HashSet::new),
+            tool_call_format: ToolCallFormat::PFormat,
+            connected_integrations: &[],
+            connected_identities_md: String::new(),
+            include_profile: false,
+            include_memory_md: false,
+            curated_snapshot: None,
+            user_identity: None,
+        }
+    }
+
+    #[test]
+    fn build_returns_nonempty_body() {
+        let body = build(&empty_ctx()).unwrap();
+        assert!(!body.is_empty());
+        assert!(body.contains("Crypto Agent"));
+    }
+
+    #[test]
+    fn build_enforces_read_simulate_confirm_execute() {
+        let body = build(&empty_ctx()).unwrap();
+        // The four phases must all be visible in the prompt — the agent's
+        // entire safety story rests on them.
+        assert!(
+            body.contains("read, simulate, confirm, then execute")
+                || body.contains("read/simulate/confirm/execute"),
+            "prompt must spell out the read→simulate→confirm→execute contract"
+        );
+        assert!(
+            body.contains("ask_user_clarification"),
+            "prompt must require explicit user confirmation before execute"
+        );
+        assert!(
+            body.contains("prepared_id"),
+            "execute step must consume a prepared_id, not fabricated parameters"
+        );
+    }
+
+    #[test]
+    fn build_forbids_fabrication_and_logging_secrets() {
+        let body = build(&empty_ctx()).unwrap();
+        assert!(
+            body.contains("No fabrication"),
+            "prompt must explicitly forbid fabricating chain/token/market params"
+        );
+        assert!(
+            body.contains("Never log secrets") || body.contains("never log secrets"),
+            "prompt must forbid echoing private keys / seed phrases"
+        );
+    }
+}