@emblemvault/agentwallet 1.3.1 → 3.0.0

package/README.md

@@ -1,6 +1,8 @@
 # @emblemvault/agentwallet
 
-CLI for **Agent Hustle** - EmblemVault's autonomous crypto AI with 256+ trading tools across 7 blockchains.
+The CLI for **EmblemVault Agent Wallet** -- giving AI agents their own crypto wallets across 7 blockchains. Designed for use in [OpenClaw](https://openclaw.ai), autonomous agent frameworks, and any system where AI agents need to hold, send, and manage crypto independently.
+
+Each agent gets a deterministic wallet derived from a password. No seed phrases, no manual key management. The agent authenticates once and gets addresses on Solana, Ethereum, Base, BSC, Polygon, Hedera, and Bitcoin -- ready to trade, hold, and transact.
 
 ## Install
 
@@ -8,31 +10,96 @@ CLI for **Agent Hustle** - EmblemVault's autonomous crypto AI with 256+ trading
 npm install -g @emblemvault/agentwallet
 ```
 
-## Usage
+## Quick Start
+
+```bash
+# Agent mode -- give your AI agent a wallet (auto-generates credentials on first run)
+emblemai --agent -m "What are my wallet addresses?"
+
+# Agent mode with a specific wallet identity
+emblemai --agent -p "my-agent-password-here" -m "Show my balances across all chains"
+
+# Interactive mode -- opens browser for human authentication
+emblemai
+```
+
+## Authentication
+
+EmblemAI v3 supports two authentication methods:
+
+### Browser Auth (Interactive Mode)
+
+When you run `emblemai` without `-p`, the CLI:
+
+1. Checks for a saved session in `~/.emblemai/session.json`
+2. If no valid session, opens your browser to authenticate via the EmblemVault auth modal
+3. Captures the JWT session and saves it locally
+4. On subsequent runs, restores the saved session automatically (no login needed until it expires)
+
+If the browser fails to open, the URL is printed for manual copy-paste. If authentication times out (5 minutes), falls back to password prompt.
+
+### Password Auth (Agent Mode)
+
+Agent mode always uses password authentication:
+
+- Auto-generates a secure password on first run if none provided
+- Password is stored encrypted via dotenvx in `~/.emblemai/.env`
+- Use `-p` flag to provide a specific password
+
+**Login and signup are the same action.** The first use of a password creates a vault; subsequent uses return the same vault. Different passwords produce different wallets.
+
+- Password must be 16+ characters
+- No recovery if lost (treat it like a private key)
+
+## Operating Modes
+
+### Interactive Mode (Default)
+
+Readline-based interactive mode with streaming AI responses, glow markdown rendering, and slash commands.
+
+```bash
+emblemai              # Browser auth (recommended)
+emblemai -p "your-password"  # Password auth
+```
+
+### Agent Mode
 
-### Agent Mode (For AI Agents)
+Agent mode is the primary integration point for AI agents, automation scripts, and agent frameworks like OpenClaw. It sends a single message, prints the response to stdout, and exits -- designed for programmatic use where another system is orchestrating the agent.
 
-Single-shot queries that return a response and exit:
+**Zero-config setup**: On first run without a password, agent mode auto-generates a secure password and stores it encrypted. The agent gets a wallet immediately with no human intervention.
 
 ```bash
-# Query Hustle AI
-emblemai --agent -p "your-password-16-chars-min" -m "What are my wallet addresses?"
+# First run -- auto-generates password, creates wallet, answers query
+emblemai --agent -m "What are my wallet addresses?"
+
+# Explicit password -- use when you need a specific wallet identity
+emblemai --agent -p "your-password" -m "Show my balances"
+
+# Pipe output to other tools
+emblemai -a -m "What is my SOL balance?" | jq .
 
-# Using environment variable
-export EMBLEM_PASSWORD="your-password-16-chars-min"
-emblemai --agent -p "$EMBLEM_PASSWORD" -m "Show my balances"
+# Use in scripts
+ADDRESSES=$(emblemai -a -m "List my addresses as JSON")
 ```
 
-### Interactive Mode (For Humans)
+Agent mode always uses password auth (never browser auth), retains conversation history between calls, and supports the full Hustle AI toolset including trading, transfers, portfolio queries, and cross-chain operations.
 
-Full interactive CLI with streaming, tools, and auth menu:
+#### Integrating with Agent Frameworks
+
+Any system that can shell out to a CLI can give its agents a wallet:
 
 ```bash
-# With password argument
-emblemai -p "your-password-16-chars-min"
+# OpenClaw, CrewAI, AutoGPT, or any agent framework
+emblemai --agent -m "Send 0.1 SOL to <address>"
+emblemai --agent -m "Swap 100 USDC to ETH on Base"
+emblemai --agent -m "What tokens do I hold across all chains?"
+```
 
-# Or let it prompt for password
-emblemai
+Each password produces a unique, deterministic wallet. To give multiple agents separate wallets, use different passwords:
+
+```bash
+emblemai --agent -p "agent-alice-wallet-001" -m "My addresses?"
+emblemai --agent -p "agent-bob-wallet-002" -m "My addresses?"
 ```
 
 ### Reset Conversation
@@ -41,58 +108,104 @@ emblemai
 emblemai --reset
 ```
 
+## CLI Flags
+
+| Flag | Description |
+|------|-------------|
+| `-p`, `--password <pw>` | EmblemVault password (min 16 chars) -- skips browser auth |
+| `-m`, `--message <msg>` | Message to send (agent mode) |
+| `-a`, `--agent` | Agent mode (single message, exit) |
+| `--restore-auth <path>` | Restore credentials from a backup file and exit |
+| `--debug` | Enable debug output |
+| `--stream` | Toggle streaming (default: on) |
+| `--log` | Enable stream logging |
+| `--log-file <path>` | Override log file path |
+| `--reset` | Clear conversation history |
+| `--hustle-url <url>` | Override Hustle API endpoint |
+| `--auth-url <url>` | Override auth endpoint |
+| `--api-url <url>` | Override API endpoint |
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `EMBLEM_PASSWORD` | Password (alternative to `-p`) |
+| `HUSTLE_API_URL` | Hustle API endpoint override |
+| `EMBLEM_AUTH_URL` | Auth endpoint override |
+| `EMBLEM_API_URL` | API endpoint override |
+| `ELIZA_URL` | ElizaOS URL for inverse discovery |
+
 ## Interactive Commands
 
 | Command | Description |
 |---------|-------------|
 | `/help` | Show all commands |
-| `/settings` | Show current config |
-| `/auth` | Open auth menu (API key, addresses, etc.) |
-| `/stream on\|off` | Toggle streaming mode |
+| `/plugins` | List all plugins with status |
+| `/plugin <name> on\|off` | Toggle a plugin |
+| `/tools` | List available tools |
+| `/tools add\|remove <id>` | Manage tool selection |
+| `/tools clear` | Enable auto-tools mode |
+| `/auth` | Authentication menu (session info, addresses, backup, logout) |
+| `/wallet` | Show wallet addresses |
+| `/portfolio` | Show portfolio |
+| `/settings` | Show current settings |
+| `/model <id>` | Set AI model (or `clear` to reset) |
+| `/stream on\|off` | Toggle streaming |
 | `/debug on\|off` | Toggle debug mode |
 | `/history on\|off` | Toggle history retention |
-| `/reset` | Clear conversation history |
-| `/models` | List available models |
-| `/model <id>` | Set model |
-| `/tools` | List tool categories |
-| `/tools add\|remove <id>` | Manage tools |
-| `/exit` | Exit the CLI |
+| `/payment` | PAYG billing status |
+| `/payment enable\|disable` | Toggle PAYG billing |
+| `/payment token <T>` | Set payment token |
+| `/payment mode <M>` | Set payment mode |
+| `/secrets` | Manage encrypted plugin secrets |
+| `/glow on\|off` | Toggle glow markdown rendering |
+| `/log on\|off` | Toggle stream logging |
+| `/reset` | Clear conversation |
+| `/exit` | Exit |
 
-## Example Queries
+## Auth Backup and Restore
+
+The `/auth` menu includes a **Backup Agent Auth** option that exports your credentials to a single JSON file. To restore on another machine:
 
 ```bash
-# Check wallet addresses
-emblemai --agent -p "$PASSWORD" -m "What are my wallet addresses?"
+emblemai --restore-auth ~/emblemai-auth-backup.json
+```
 
-# Check balances
-emblemai --agent -p "$PASSWORD" -m "Show all my balances across all chains"
+This places the credential files in `~/.emblemai/` and you're ready to go.
 
-# Swap tokens
-emblemai --agent -p "$PASSWORD" -m "Swap $20 worth of SOL to USDC"
+## Plugins
 
-# Market trends
-emblemai --agent -p "$PASSWORD" -m "What's trending on Solana right now?"
-```
+The ElizaOS plugin is loaded by default:
 
-## Authentication
+| Plugin | Package | Description |
+|--------|---------|-------------|
+| ElizaOS | `@agenthustle/plugin-masq` | ElizaOS agent framework with MASQ and inverse discovery |
 
-**Login and signup are the same action.**
+Additional plugins exist but are currently disabled. See [docs/PLUGINS.md](docs/PLUGINS.md) for details.
 
-| Scenario | What Happens |
-|----------|--------------|
-| First time with a password | Creates a new vault with unique addresses |
-| Same password again | Returns the same vault (deterministic) |
-| Different password | Creates a completely different vault |
+## Optional: Glow (Markdown Rendering)
 
-- Password must be 16+ characters
-- No recovery if lost (treat it like a private key)
+Install [glow](https://github.com/charmbracelet/glow) for rich markdown rendering in AI responses:
+
+```bash
+brew install glow    # macOS
+sudo snap install glow  # Linux
+```
+
+Toggle with `/glow on|off`.
 
 ## Supported Chains
 
 Solana, Ethereum, Base, BSC, Polygon, Hedera, Bitcoin
 
+## Documentation
+
+- [Setup Guide](docs/SETUP.md) -- installation, auth, running modes
+- [Commands](docs/COMMANDS.md) -- full command reference
+- [Plugins](docs/PLUGINS.md) -- plugin system and tool reference
+
 ## Links
 
 - [EmblemVault](https://emblemvault.dev)
 - [Hustle AI](https://agenthustle.ai)
-- [OpenClaw Skill](https://github.com/EmblemCompany/EmblemAi-AgentWallet)
+- [GitHub](https://github.com/EmblemCompany/EmblemAi-AgentWallet)

package/docs/COMMANDS.md

@@ -0,0 +1,171 @@
+# EmblemAI Command Reference
+
+## Slash Commands
+
+All commands are prefixed with `/`. Type them in the input bar and press Enter.
+
+### General
+
+| Command | Description |
+|---------|-------------|
+| `/help` | Show all available commands |
+| `/settings` | Show current configuration (vault ID, model, streaming, debug, tools) |
+| `/exit` | Exit the CLI (also: `/quit`) |
+
+### Chat and History
+
+| Command | Description |
+|---------|-------------|
+| `/reset` | Clear conversation history and start fresh |
+| `/clear` | Alias for `/reset` |
+| `/history on` | Enable history retention between messages |
+| `/history off` | Disable history retention (stateless mode) |
+| `/history` | Show history status and recent messages |
+
+### Streaming and Debug
+
+| Command | Description |
+|---------|-------------|
+| `/stream on` | Enable streaming mode (tokens appear as generated) |
+| `/stream off` | Disable streaming mode (wait for full response) |
+| `/stream` | Show current streaming status |
+| `/debug on` | Enable debug mode (shows tool args, intent context) |
+| `/debug off` | Disable debug mode |
+| `/debug` | Show current debug status |
+
+### Model Selection
+
+| Command | Description |
+|---------|-------------|
+| `/model <id>` | Set the active model by ID |
+| `/model clear` | Reset to API default model |
+| `/model` | Show currently selected model |
+
+### Tool Management
+
+| Command | Description |
+|---------|-------------|
+| `/tools` | List all tools with selection status |
+| `/tools add <id>` | Add a tool to the active set |
+| `/tools remove <id>` | Remove a tool from the active set |
+| `/tools clear` | Clear tool selection (enable auto-tools mode) |
+
+When no tools are selected, the AI operates in **auto-tools mode**, dynamically choosing appropriate tools based on conversation context.
+
+### Authentication
+
+| Command | Description |
+|---------|-------------|
+| `/auth` | Open authentication menu |
+| `/wallet` | Show wallet addresses (EVM, Solana, BTC, Hedera) |
+| `/portfolio` | Show portfolio (routes as a chat query) |
+
+The `/auth` menu provides:
+
+| Option | Description |
+|--------|-------------|
+| 1. Get API Key | Fetch your vault API key |
+| 2. Get Vault Info | Show vault ID, addresses, creation date |
+| 3. Session Info | Show current session details (identifier, expiry, auth type) |
+| 4. Refresh Session | Refresh the auth session token |
+| 5. EVM Address | Show your Ethereum/EVM address |
+| 6. Solana Address | Show your Solana address |
+| 7. BTC Addresses | Show your Bitcoin addresses (P2PKH, P2WPKH, P2TR) |
+| 8. Backup Agent Auth | Export credentials to a backup file |
+| 9. Logout | Clear session and exit (requires re-authentication on next run) |
+
+### Payment (PAYG Billing)
+
+| Command | Description |
+|---------|-------------|
+| `/payment` | Show PAYG billing status (enabled, mode, debt, tokens) |
+| `/payment enable` | Enable pay-as-you-go billing |
+| `/payment disable` | Disable pay-as-you-go billing |
+| `/payment token <TOKEN>` | Set payment token (SOL, ETH, HUSTLE, etc.) |
+| `/payment mode <MODE>` | Set payment mode: `pay_per_request` or `debt_accumulation` |
+
+### Plugin Management
+
+| Command | Description |
+|---------|-------------|
+| `/plugins` | List all plugins with enabled/disabled status |
+| `/plugin <name> on` | Enable a plugin by name |
+| `/plugin <name> off` | Disable a plugin by name |
+
+### Secrets
+
+| Command | Description |
+|---------|-------------|
+| `/secrets` | Manage encrypted plugin secrets (interactive menu) |
+
+Secrets are encrypted with your vault key and stored in `~/.emblemai/secrets.json`. Plugins are hot-reloaded after setting a secret (no restart needed).
+
+### Markdown Rendering
+
+| Command | Description |
+|---------|-------------|
+| `/glow on` | Enable markdown rendering via glow |
+| `/glow off` | Disable markdown rendering |
+| `/glow` | Show glow status and version |
+
+Requires [glow](https://github.com/charmbracelet/glow) to be installed.
+
+### Logging
+
+| Command | Description |
+|---------|-------------|
+| `/log on` | Enable stream logging to file |
+| `/log off` | Disable stream logging |
+| `/log` | Show logging status and file path |
+
+Log file defaults to `~/.emblemai-stream.log`. Override with `--log-file <path>`.
+
+## Keyboard Shortcuts
+
+### Simple Mode (Default)
+
+| Key | Action |
+|-----|--------|
+| `Enter` | Send message |
+| `Up` | Recall previous input |
+| `Ctrl+C` | Exit |
+| `Ctrl+D` | Exit (EOF) |
+
+### TUI Mode
+
+| Key | Action |
+|-----|--------|
+| `Tab` / `Shift+Tab` | Cycle focus between panels |
+| `Enter` | Send message |
+| `Ctrl+C` | Exit |
+| `Up/Down` | Scroll panel content |
+| Mouse scroll | Scroll in focused panel |
+
+## Command Examples
+
+### Session management
+
+```
+/settings
+/auth
+/wallet
+/payment
+/reset
+```
+
+### Tool and model management
+
+```
+/tools
+/model gpt-4
+/stream off
+/debug on
+```
+
+### Plugin management
+
+```
+/plugins
+/plugin hustle-elizaos on
+/plugin hustle-elizaos off
+```

package/docs/PLUGINS.md

@@ -0,0 +1,106 @@
+# EmblemAI Plugin Reference
+
+EmblemAI uses a plugin system to extend AI capabilities with client-side tools. Plugins are loaded at startup and register tools that the AI can call during conversations.
+
+---
+
+## Active Plugin
+
+### ElizaOS -- AI Agent Framework
+
+**Package**: `@agenthustle/plugin-masq`
+**Status**: Loaded by default
+**Description**: Connects Hustle to the ElizaOS agent framework. Provides MASQ mode (HTTP server on port 3001) and inverse discovery to discover and register ElizaOS actions as client tools.
+
+#### Configuration
+
+The plugin is auto-configured at startup with:
+
+- **MASQ**: Enabled on port 3001 -- exposes Hustle as an ElizaOS-compatible HTTP agent
+- **Inverse discovery**: Enabled -- discovers actions from a running ElizaOS instance and registers them as client tools
+- **Hustle client**: Wired automatically for inverse control (ElizaOS actions route through `hustleClient.chat()`)
+
+#### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `ELIZA_URL` | ElizaOS agent URL for inverse discovery | `http://localhost:3000` |
+| `ELIZA_API_URL` | ElizaOS API URL (via `--eliza-url` flag) | -- |
+
+---
+
+## Available Plugins (Not Loaded)
+
+The following plugins exist as packages but are currently disabled in the plugin loader. They can be re-enabled in `src/plugins/loader.js` by uncommenting their specs.
+
+| Plugin | Package | Description |
+|--------|---------|-------------|
+| A2A | `@agenthustle/plugin-a2a` | Google Agent-to-Agent protocol v0.3.0 (discovery, messaging, tasks) |
+| ACP | `@agenthustle/plugin-acp` | Virtuals Agent Commerce Protocol (marketplace, jobs, autonomous mode) |
+| Bridge | `@agenthustle/plugin-bridge` | Cross-protocol message router (A2A, ACP, ElizaOS) |
+
+---
+
+## Plugin Management
+
+### Commands
+
+```
+/plugins                    # List all plugins and their status
+/plugin <name> on           # Enable a plugin
+/plugin <name> off          # Disable a plugin
+```
+
+### Tool Selection
+
+```
+/tools                      # List all available tools
+/tools add <id>             # Add a tool to the active set
+/tools remove <id>          # Remove a tool from the active set
+/tools clear                # Clear selection (enable auto-tools mode)
+```
+
+When no tools are explicitly selected, the AI uses **auto-tools mode**, dynamically selecting appropriate tools based on conversation context.
+
+---
+
+## Plugin Architecture
+
+### Plugin Interface
+
+Plugins follow the `HustlePlugin` interface:
+
+```js
+{
+  name: 'plugin-name',
+  version: '1.0.0',
+  tools: [
+    {
+      name: 'tool_name',
+      description: 'What the tool does',
+      parameters: { type: 'object', properties: { ... } },
+    },
+  ],
+  executors: {
+    tool_name: async (args) => { /* implementation */ },
+  },
+}
+```
+
+### Loading
+
+Plugins are loaded in `src/plugins/loader.js` via `PluginManager.loadAll()`. Each plugin spec declares:
+
+- `mod` -- npm package name
+- `factory` -- exported factory function name
+- `configKey` -- key in the config object for per-plugin settings
+
+Missing packages are silently skipped.
+
+### Secrets
+
+Plugins can declare secrets (e.g., API keys) that are encrypted with the user's vault key and stored in `~/.emblemai/secrets.json`. Secrets are lazily decrypted on first tool use. Use `/secrets` to manage them interactively.
+
+### Custom Plugins
+
+User-created plugins are stored in `~/.emblemai-plugins.json` and loaded at startup. Custom plugins use serialized executor code that is compiled at load time.