@clawnch/clawtomaton 0.8.1 → 0.8.2

package/dist/skills/hummingbot.js

@@ -1,456 +1,1078 @@
 /**
- * Skill: hummingbot — Market making via Hummingbot integration.
+ * Skill: hummingbot — Professional market making via Hummingbot integration.
  *
- * Hummingbot is an open-source HFT framework (17k+ stars, 40+ exchange connectors).
- * This skill lets the agent manage Hummingbot instances for professional
- * market-making strategies on Clawnch tokens.
+ * Full-featured integration with the Hummingbot API server covering all 14
+ * upstream MCP tool capabilities: connector setup, multi-server config,
+ * portfolio, order placement, leverage/position mode, executors (with
+ * preferences), market data (all order book query types), controllers,
+ * bots, gateway (container/config/swaps/CLMM), and history search.
  *
- * Integration approach: External engine via Docker/CLI + Hummingbot's API.
- * The agent controls strategy parameters; Hummingbot executes the trades.
- *
- * Supported strategies:
- *   - pure_market_making: Provide liquidity with configurable spread/order size
- *   - avellaneda_market_making: Optimal market making (Avellaneda-Stoikov model)
- *   - grid: Grid trading with defined price levels
- *   - twap: Time-weighted average price execution
- *
- * Prerequisites:
- *   - Docker installed and running
- *   - Hummingbot image: docker pull hummingbot/hummingbot:latest
- *   - Or Hummingbot MCP server running locally
+ * Also includes Clawnch-specific strategy templates.
  *
  * @see https://github.com/hummingbot/hummingbot
  * @see https://github.com/hummingbot/mcp
  */
+import { HummingbotClient } from '@clawnch/clawncher-sdk';
 // ============================================================================
-// Hummingbot Docker management
+// Lazy client singleton
 // ============================================================================
-/** Container name prefix for Hummingbot instances */
-const HB_CONTAINER_PREFIX = 'clawnch-hb';
-/** Regex for valid Docker container names: alphanumeric, dash, underscore */
-const SAFE_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/;
-/** Regex for valid Ethereum addresses */
-const ETH_ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
-/**
- * Sanitize a string for use in shell commands.
- * Only allows Docker-safe characters: alphanumeric, dash, underscore, dot.
- * Throws if the name contains invalid characters.
- */
-function sanitizeName(name) {
-    if (!SAFE_NAME_RE.test(name) || name.length > 128) {
-        throw new Error(`Invalid name "${name}": must be 1-128 chars, alphanumeric/dash/underscore/dot, start with alphanumeric`);
+let _client = null;
+function getClient(ctx) {
+    if (!_client) {
+        const config = {
+            apiUrl: process.env.HUMMINGBOT_API_URL ?? 'http://localhost:8000',
+            username: process.env.HUMMINGBOT_USERNAME ?? 'admin',
+            password: process.env.HUMMINGBOT_PASSWORD ?? 'admin',
+            timeout: parseInt(process.env.HUMMINGBOT_TIMEOUT ?? '30000', 10),
+            maxRetries: parseInt(process.env.HUMMINGBOT_MAX_RETRIES ?? '3', 10),
+            retryDelay: parseInt(process.env.HUMMINGBOT_RETRY_DELAY ?? '2000', 10),
+        };
+        _client = new HummingbotClient(config);
     }
-    return name;
+    return _client;
 }
-/**
- * Execute a shell command and return stdout.
- * All arguments must be pre-sanitized before being interpolated into the command.
- */
-async function exec(command) {
-    const { execSync } = await import('child_process');
-    try {
-        return execSync(command, { encoding: 'utf8', timeout: 30000 }).trim();
-    }
-    catch (err) {
-        throw new Error(`Command failed: ${command}\n${err.stderr ?? err.message}`);
-    }
-}
-/**
- * Check if Docker is available and Hummingbot image exists.
- */
-async function checkPrerequisites() {
-    let docker = false;
-    let image = false;
-    let mcp = false;
-    try {
-        await exec('docker info --format "{{.ID}}"');
-        docker = true;
-    }
-    catch { /* Docker not available */ }
-    if (docker) {
-        try {
-            const images = await exec('docker images hummingbot/hummingbot --format "{{.Tag}}"');
-            image = images.length > 0;
-        }
-        catch { /* Image not found */ }
-    }
-    // Check for MCP server
-    try {
-        const response = await fetch('http://localhost:8000/health', { signal: AbortSignal.timeout(2000) });
-        mcp = response.ok;
-    }
-    catch { /* MCP not running */ }
-    return { docker, image, mcp };
-}
-/**
- * Generate a Hummingbot strategy config file content.
- */
-function generateStrategyConfig(strategy, params, tokenAddress, walletAddress) {
-    const base = {
-        strategy,
-        exchange: 'uniswap_base_base',
-        market: `${tokenAddress}-WETH`,
-    };
-    switch (strategy) {
-        case 'pure_market_making':
-            return yamlify({
-                ...base,
-                bid_spread: params.bid_spread ?? 0.01,
-                ask_spread: params.ask_spread ?? 0.01,
-                order_amount: params.order_amount ?? 0.001,
-                order_refresh_time: params.order_refresh_time ?? 30,
-                inventory_skew_enabled: true,
-                inventory_target_base_pct: params.inventory_target ?? 0.5,
-                filled_order_delay: 10,
-            });
-        case 'avellaneda_market_making':
-            return yamlify({
-                ...base,
-                risk_factor: params.risk_factor ?? 0.5,
-                order_amount: params.order_amount ?? 0.001,
-                order_refresh_time: params.order_refresh_time ?? 10,
-                inventory_target_base_pct: params.inventory_target ?? 0.5,
-                min_spread: params.min_spread ?? 0.002,
-                max_spread: params.max_spread ?? 0.05,
-                vol_to_spread_multiplier: params.vol_multiplier ?? 1.0,
-                execution_timeframe: 'infinite',
-            });
-        case 'grid':
-            return yamlify({
-                ...base,
-                n_levels: params.levels ?? 5,
-                grid_price_ceiling: params.price_ceiling ?? 0,
-                grid_price_floor: params.price_floor ?? 0,
-                order_amount: params.order_amount ?? 0.001,
-                order_refresh_time: params.order_refresh_time ?? 300,
-                start_order_spread: params.start_spread ?? 0.01,
-            });
-        case 'twap':
-            return yamlify({
-                ...base,
-                trade_side: params.side ?? 'buy',
-                target_asset_amount: params.total_amount ?? 0.01,
-                order_step_size: params.step_size ?? 0.001,
-                order_delay_time: params.delay_seconds ?? 60,
-                is_time_span_execution: true,
-                cancel_order_wait_time: params.cancel_wait ?? 30,
-            });
-        default:
-            return yamlify(base);
-    }
-}
-/** Simple YAML serializer for config objects */
-function yamlify(obj) {
-    const lines = [];
-    for (const [key, value] of Object.entries(obj)) {
-        if (value === undefined || value === null)
-            continue;
-        if (typeof value === 'boolean') {
-            lines.push(`${key}: ${value ? 'true' : 'false'}`);
-        }
-        else if (typeof value === 'number') {
-            lines.push(`${key}: ${value}`);
-        }
-        else {
-            lines.push(`${key}: "${value}"`);
-        }
-    }
-    return lines.join('\n');
-}
-/**
- * List running Hummingbot instances managed by Clawtomaton.
- */
-async function listInstances() {
-    try {
-        const output = await exec(`docker ps -a --filter "name=${HB_CONTAINER_PREFIX}" --format "{{.Names}}|{{.Status}}|{{.CreatedAt}}"`);
-        if (!output)
-            return [];
-        return output.split('\n').filter(Boolean).map(line => {
-            const [name, status, created] = line.split('|');
-            return { name, status, created };
-        });
-    }
-    catch {
-        return [];
-    }
+/** Helper to split comma-separated strings into arrays */
+function splitCsv(val) {
+    if (!val)
+        return undefined;
+    return String(val).split(',').map(s => s.trim()).filter(Boolean);
 }
 // ============================================================================
 // Skill definition
 // ============================================================================
 export const hummingbotSkill = {
     name: 'hummingbot',
-    description: 'Market making via Hummingbot. Start/stop/configure professional trading bots for Clawnch tokens. ' +
-        'Strategies: pure_market_making, avellaneda_market_making (optimal), grid, twap. ' +
-        'Requires Docker with hummingbot/hummingbot image, or Hummingbot MCP server.',
+    description: 'Professional market making and trading via Hummingbot. ' +
+        'Actions: "status", "portfolio", "order", "leverage", "executor", "market_data", ' +
+        '"controller", "bot", "gateway", "history", "templates", "connector", "servers", ' +
+        '"backtest", "discovery", "archived", "scripts", "analytics", "accounts". ' +
+        'Requires Hummingbot API server (default: localhost:8000).',
     parameters: [
         {
             name: 'action',
             type: 'string',
-            description: 'Action: "status" (check prerequisites + running instances), "start" (launch a strategy), ' +
-                '"stop" (stop an instance), "list" (list running instances), "logs" (get instance logs), "configure" (generate strategy config).',
+            description: 'Action: "status", "portfolio", "order", "leverage", "executor", "market_data", ' +
+                '"controller", "bot", "gateway", "history", "templates", "connector", "servers", ' +
+                '"backtest", "discovery", "archived", "scripts", "analytics", "accounts".',
             required: true,
         },
         {
-            name: 'strategy',
-            type: 'string',
-            description: 'Strategy name for start/configure: "pure_market_making" (simple spread), ' +
-                '"avellaneda_market_making" (optimal, Avellaneda-Stoikov model), "grid" (grid trading), "twap" (time-weighted execution).',
-            required: false,
-        },
-        {
-            name: 'token_address',
-            type: 'string',
-            description: 'Token address to market-make. Uses agent\'s deployed token by default.',
-            required: false,
-        },
-        {
-            name: 'instance_name',
-            type: 'string',
-            description: 'Instance name for stop/logs. Auto-generated if not provided for start.',
-            required: false,
-        },
-        {
-            name: 'bid_spread',
-            type: 'number',
-            description: 'Bid spread as decimal (0.01 = 1%). Default: 0.01.',
-            required: false,
-        },
-        {
-            name: 'ask_spread',
-            type: 'number',
-            description: 'Ask spread as decimal (0.01 = 1%). Default: 0.01.',
-            required: false,
-        },
-        {
-            name: 'order_amount',
+            name: 'sub_action',
             type: 'string',
-            description: 'Order size in base token (e.g. "0.001" ETH). Default: 0.001.',
-            required: false,
-        },
-        {
-            name: 'risk_factor',
-            type: 'number',
-            description: 'Risk factor for Avellaneda strategy (0-1). Lower = wider spreads, lower risk. Default: 0.5.',
-            required: false,
-        },
-        {
-            name: 'levels',
-            type: 'number',
-            description: 'Number of grid levels for grid strategy. Default: 5.',
+            description: 'Sub-action for compound actions. ' +
+                'executor: create|search|stop|logs|positions|get_preferences|save_preferences|reset_preferences|clear_position|types|type_config|summary|get_by_id. ' +
+                'bot: deploy|status|logs|stop|stop_controllers|start_controllers|history|runs|archive. ' +
+                'gateway: container_status|container_start|container_stop|container_restart|container_logs|' +
+                'config_list|config_get|config_update|config_add|config_delete|' +
+                'swap_quote|swap_execute|swap_search|swap_status|' +
+                'clmm_list|clmm_info|clmm_open|clmm_close|clmm_fees|clmm_positions. ' +
+                'market_data: prices|candles|historical_candles|funding|orderbook|vwap|add_pair|remove_pair. ' +
+                'history: orders|perp_positions|clmm_positions. ' +
+                'templates: list|describe|build. ' +
+                'connector: list|setup|delete. ' +
+                'controller: list|describe|upsert|delete. ' +
+                'servers: list|add|modify|set_default|remove. ' +
+                'discovery: connectors|config_map|trading_rules|order_types. ' +
+                'archived: list|summary|performance|trades|orders. ' +
+                'scripts: list|get|upsert|delete|configs|get_config|upsert_config|delete_config|template. ' +
+                'analytics: history|distribution|accounts_distribution|funding_payments|rates|rate. ' +
+                'accounts: list|credentials|create|delete.',
             required: false,
         },
+        // --- Shared ---
+        { name: 'connector_name', type: 'string', description: 'Exchange connector name.', required: false },
+        { name: 'trading_pair', type: 'string', description: 'Trading pair (e.g. "ETH-USDT").', required: false },
+        { name: 'trading_pairs', type: 'string', description: 'Comma-separated trading pairs.', required: false },
+        { name: 'account_name', type: 'string', description: 'Account name.', required: false },
+        { name: 'account_names', type: 'string', description: 'Comma-separated account names.', required: false },
+        { name: 'connector_names', type: 'string', description: 'Comma-separated connector names for filtering.', required: false },
+        // --- Order ---
+        { name: 'side', type: 'string', description: 'Trade side: "BUY" or "SELL".', required: false },
+        { name: 'amount', type: 'string', description: 'Order amount (base currency, or "$100" for USD value).', required: false },
+        { name: 'order_type', type: 'string', description: 'Order type: "MARKET", "LIMIT", "LIMIT_MAKER".', required: false },
+        { name: 'price', type: 'string', description: 'Price for limit orders.', required: false },
+        { name: 'position_action', type: 'string', description: 'Position action for perps: "OPEN" or "CLOSE".', required: false },
+        // --- Leverage ---
+        { name: 'leverage', type: 'number', description: 'Leverage multiplier for perpetuals.', required: false },
+        { name: 'position_mode', type: 'string', description: 'Position mode: "HEDGE" or "ONE-WAY".', required: false },
+        // --- Executor ---
+        { name: 'executor_type', type: 'string', description: 'Executor type: grid_executor, dca_executor, position_executor, order_executor.', required: false },
+        { name: 'executor_id', type: 'string', description: 'Executor ID for stop/logs/search.', required: false },
+        { name: 'executor_config', type: 'string', description: 'JSON string of executor/controller configuration.', required: false },
+        { name: 'keep_position', type: 'boolean', description: 'Keep position when stopping executor.', required: false },
+        { name: 'preferences_content', type: 'string', description: 'Markdown content for save_preferences.', required: false },
+        // --- Bot ---
+        { name: 'bot_name', type: 'string', description: 'Bot name.', required: false },
+        { name: 'controllers_config', type: 'string', description: 'Comma-separated controller config/names.', required: false },
+        // --- Market data ---
+        { name: 'interval', type: 'string', description: 'Candle interval: "1m", "5m", "15m", "30m", "1h", "4h", "1d".', required: false },
+        { name: 'days', type: 'number', description: 'Days of historical data for candles.', required: false },
+        { name: 'query_type', type: 'string', description: 'Order book query type: snapshot, volume_for_price, price_for_volume, quote_volume_for_price, price_for_quote_volume.', required: false },
+        { name: 'query_value', type: 'number', description: 'Query value for order book queries (price or volume).', required: false },
+        { name: 'is_buy', type: 'boolean', description: 'Side for order book queries (default: true).', required: false },
+        // --- Controller ---
+        { name: 'target', type: 'string', description: 'Controller target: "controller" or "config".', required: false },
+        { name: 'controller_type', type: 'string', description: 'Controller type: directional_trading, market_making, generic.', required: false },
+        { name: 'controller_name', type: 'string', description: 'Controller name.', required: false },
+        { name: 'controller_code', type: 'string', description: 'Python code for controller upsert.', required: false },
+        { name: 'config_name', type: 'string', description: 'Config name for controller operations.', required: false },
+        { name: 'config_data', type: 'string', description: 'JSON config data for controller upsert.', required: false },
+        { name: 'confirm_override', type: 'boolean', description: 'Confirm overwrite for controller/connector.', required: false },
+        // --- Templates ---
+        { name: 'template', type: 'string', description: 'Strategy template name.', required: false },
+        // --- History ---
+        { name: 'limit', type: 'number', description: 'Max results.', required: false },
+        { name: 'offset', type: 'number', description: 'Pagination offset.', required: false },
+        { name: 'status', type: 'string', description: 'Status filter (OPEN, CLOSED, FILLED, CANCELED, RUNNING, TERMINATED, etc).', required: false },
+        { name: 'start_time', type: 'number', description: 'Start time (unix seconds) for history.', required: false },
+        { name: 'end_time', type: 'number', description: 'End time (unix seconds) for history.', required: false },
+        // --- Gateway ---
+        { name: 'network', type: 'string', description: 'Network for gateway (e.g. "solana-mainnet-beta").', required: false },
+        { name: 'pool_address', type: 'string', description: 'Pool address for CLMM.', required: false },
+        { name: 'position_address', type: 'string', description: 'Position NFT address for CLMM.', required: false },
+        { name: 'wallet_address', type: 'string', description: 'Wallet address for gateway operations.', required: false },
+        { name: 'slippage_pct', type: 'string', description: 'Slippage tolerance percentage (e.g. "1.0").', required: false },
+        { name: 'lower_price', type: 'string', description: 'Lower price bound for CLMM open_position.', required: false },
+        { name: 'upper_price', type: 'string', description: 'Upper price bound for CLMM open_position.', required: false },
+        { name: 'base_token_amount', type: 'string', description: 'Base token amount for CLMM.', required: false },
+        { name: 'quote_token_amount', type: 'string', description: 'Quote token amount for CLMM.', required: false },
+        { name: 'transaction_hash', type: 'string', description: 'Transaction hash for swap status lookup.', required: false },
+        // --- Gateway config ---
+        { name: 'resource_type', type: 'string', description: 'Gateway config resource: chains, networks, tokens, connectors, pools, wallets.', required: false },
+        { name: 'chain', type: 'string', description: 'Blockchain chain name.', required: false },
+        { name: 'private_key', type: 'string', description: 'Private key for wallet operations.', required: false },
+        { name: 'token_address', type: 'string', description: 'Token contract address.', required: false },
+        { name: 'token_symbol', type: 'string', description: 'Token symbol.', required: false },
+        { name: 'token_decimals', type: 'number', description: 'Token decimals.', required: false },
+        { name: 'pool_type', type: 'string', description: 'Pool type: CLMM or AMM.', required: false },
+        { name: 'search', type: 'string', description: 'Search/filter term.', required: false },
+        // --- Connector setup ---
+        { name: 'credentials', type: 'string', description: 'JSON credentials for connector setup.', required: false },
+        // --- Server config ---
+        { name: 'host', type: 'string', description: 'API server host for servers action.', required: false },
+        { name: 'port', type: 'number', description: 'API server port.', required: false },
+        { name: 'server_name', type: 'string', description: 'Server name for servers action.', required: false },
+        // --- Backtesting ---
+        { name: 'config', type: 'string', description: 'Config name or JSON for backtesting.', required: false },
+        { name: 'resolution', type: 'string', description: 'Backtesting resolution (1m, 5m, 1h).', required: false },
+        { name: 'trade_cost', type: 'number', description: 'Trade cost as decimal (0.0006 = 0.06%).', required: false },
+        // --- Scripts ---
+        { name: 'script_name', type: 'string', description: 'Script name.', required: false },
+        { name: 'script_content', type: 'string', description: 'Python source code for script upsert.', required: false },
+        // --- Rate Oracle ---
+        { name: 'db_path', type: 'string', description: 'Archived bot database path.', required: false },
+        // --- Active Orders / Trades ---
+        { name: 'client_order_id', type: 'string', description: 'Client order ID for cancellation.', required: false },
+        { name: 'trade_types', type: 'string', description: 'Comma-separated trade types filter.', required: false },
+        { name: 'verbose', type: 'boolean', description: 'Verbose output for bot history.', required: false },
+        { name: 'run_status', type: 'string', description: 'Bot run status filter.', required: false },
+        { name: 'volume', type: 'number', description: 'Volume for VWAP calculation.', required: false },
+        // --- Portfolio ---
+        { name: 'refresh', type: 'boolean', description: 'Force refresh portfolio from exchanges.', required: false },
+        { name: 'as_distribution', type: 'boolean', description: 'Show portfolio as distribution percentages.', required: false },
+        { name: 'include_balances', type: 'boolean', description: 'Include token balances in portfolio.', required: false },
+        { name: 'include_perp_positions', type: 'boolean', description: 'Include perp positions in portfolio.', required: false },
+        { name: 'include_lp_positions', type: 'boolean', description: 'Include LP positions in portfolio.', required: false },
+        { name: 'include_active_orders', type: 'boolean', description: 'Include active orders in portfolio.', required: false },
+        // --- Gateway container ---
+        { name: 'passphrase', type: 'string', description: 'Gateway container passphrase.', required: false },
+        { name: 'image', type: 'string', description: 'Docker image for gateway/bot.', required: false },
+        { name: 'tail', type: 'number', description: 'Number of log lines.', required: false },
     ],
     execute: async (params, ctx) => {
         try {
+            const client = getClient(ctx);
             const action = params.action;
             switch (action) {
                 // ================================================================
-                // Status: check prerequisites and running instances
+                // Status
                 // ================================================================
                 case 'status': {
-                    const prereqs = await checkPrerequisites();
-                    const instances = prereqs.docker ? await listInstances() : [];
+                    const prereqs = await client.checkPrerequisites();
+                    const dockerInstances = prereqs.docker ? await client.listDockerInstances() : [];
                     const lines = [
                         'Hummingbot Status:',
-                        `  Docker: ${prereqs.docker ? 'available' : 'NOT FOUND — install Docker to use Hummingbot'}`,
-                        `  Image: ${prereqs.image ? 'hummingbot/hummingbot installed' : 'NOT FOUND — run: docker pull hummingbot/hummingbot:latest'}`,
-                        `  MCP Server: ${prereqs.mcp ? 'running at localhost:8000' : 'not running'}`,
-                        `  Active instances: ${instances.length}`,
+                        `  API Server: ${prereqs.api ? `connected at ${process.env.HUMMINGBOT_API_URL ?? 'localhost:8000'}` : 'NOT CONNECTED'}`,
+                        `  Docker: ${prereqs.docker ? 'available' : 'NOT FOUND'}`,
+                        `  HB Image: ${prereqs.image ? 'installed' : 'not found'}`,
+                        `  MCP Server: ${prereqs.mcp ? 'running' : 'not running'}`,
                     ];
-                    if (instances.length > 0) {
-                        lines.push('');
-                        lines.push('Running instances:');
-                        for (const inst of instances) {
+                    if (prereqs.api) {
+                        lines.push('', 'Full capabilities available: portfolio, order, leverage, executor, market_data, controller, bot, gateway, history, templates, connector, servers');
+                    }
+                    else {
+                        lines.push('', 'Set HUMMINGBOT_API_URL, HUMMINGBOT_USERNAME, HUMMINGBOT_PASSWORD to connect.');
+                    }
+                    if (dockerInstances.length > 0) {
+                        lines.push('', `Docker instances (${dockerInstances.length}):`);
+                        for (const inst of dockerInstances) {
                             lines.push(`  ${inst.name}: ${inst.status} (created ${inst.created})`);
                         }
                     }
-                    if (!prereqs.docker && !prereqs.mcp) {
-                        lines.push('');
-                        lines.push('To get started:');
-                        lines.push('  1. Install Docker: https://docs.docker.com/get-docker/');
-                        lines.push('  2. Pull image: docker pull hummingbot/hummingbot:latest');
-                        lines.push('  3. Or install Hummingbot MCP: https://github.com/hummingbot/mcp');
-                    }
                     return { callId: '', success: true, result: lines.join('\n') };
                 }
                 // ================================================================
-                // Start: launch a market-making instance
+                // Portfolio
+                // ================================================================
+                case 'portfolio': {
+                    const result = await client.getPortfolioOverview({
+                        accountNames: splitCsv(params.account_names),
+                        connectorNames: splitCsv(params.connector_names) ?? (params.connector_name ? [params.connector_name] : undefined),
+                        includeBalances: params.include_balances ?? true,
+                        includePerpPositions: params.include_perp_positions ?? true,
+                        includeLPPositions: params.include_lp_positions ?? true,
+                        includeActiveOrders: params.include_active_orders ?? true,
+                        asDistribution: params.as_distribution ?? false,
+                        refresh: params.refresh ?? true,
+                    });
+                    return { callId: '', success: true, result };
+                }
+                // ================================================================
+                // Order
+                // ================================================================
+                case 'order': {
+                    const connectorName = params.connector_name;
+                    const tradingPair = params.trading_pair;
+                    const side = params.side;
+                    const amount = params.amount;
+                    if (!connectorName || !tradingPair || !side || !amount) {
+                        return {
+                            callId: '', success: false, result: null,
+                            error: 'Required: connector_name, trading_pair, side (BUY/SELL), amount.',
+                        };
+                    }
+                    const result = await client.placeOrder({
+                        connectorName,
+                        tradingPair,
+                        tradeType: side.toUpperCase(),
+                        amount,
+                        orderType: params.order_type?.toUpperCase() ?? 'MARKET',
+                        price: params.price,
+                        positionAction: params.position_action?.toUpperCase() ?? 'OPEN',
+                        accountName: params.account_name,
+                    });
+                    return {
+                        callId: '', success: result.success, result: result.result,
+                        error: result.success ? undefined : result.result,
+                    };
+                }
+                // ================================================================
+                // Leverage / Position Mode
+                // ================================================================
+                case 'leverage': {
+                    const accountName = params.account_name ?? 'master_account';
+                    const connectorName = params.connector_name;
+                    if (!connectorName) {
+                        return { callId: '', success: false, result: null, error: 'connector_name required for leverage.' };
+                    }
+                    const result = await client.setPositionModeAndLeverage({
+                        accountName,
+                        connectorName,
+                        tradingPair: params.trading_pair,
+                        positionMode: params.position_mode?.toUpperCase(),
+                        leverage: params.leverage,
+                    });
+                    return { callId: '', success: true, result };
+                }
+                // ================================================================
+                // Executor
+                // ================================================================
+                case 'executor': {
+                    const subAction = params.sub_action ?? 'search';
+                    switch (subAction) {
+                        case 'create': {
+                            const configStr = params.executor_config;
+                            if (!configStr) {
+                                const executorType = params.executor_type;
+                                if (executorType) {
+                                    const result = await client.getExecutorTypeConfig(executorType);
+                                    return { callId: '', success: true, result };
+                                }
+                                const result = await client.getExecutorTypes();
+                                return { callId: '', success: true, result };
+                            }
+                            let config;
+                            try {
+                                config = JSON.parse(configStr);
+                            }
+                            catch {
+                                return { callId: '', success: false, result: null, error: 'executor_config must be valid JSON.' };
+                            }
+                            const result = await client.createExecutor(config);
+                            return { callId: '', success: true, result };
+                        }
+                        case 'search': {
+                            const result = await client.searchExecutors({
+                                executorId: params.executor_id,
+                                executorTypes: params.executor_type ? [params.executor_type] : undefined,
+                                connectorNames: splitCsv(params.connector_names) ?? (params.connector_name ? [params.connector_name] : undefined),
+                                tradingPairs: splitCsv(params.trading_pairs) ?? (params.trading_pair ? [params.trading_pair] : undefined),
+                                status: params.status,
+                                limit: params.limit ?? 50,
+                            });
+                            return { callId: '', success: true, result };
+                        }
+                        case 'stop': {
+                            if (!params.executor_id) {
+                                return { callId: '', success: false, result: null, error: 'executor_id required to stop.' };
+                            }
+                            const result = await client.stopExecutor(params.executor_id, params.keep_position ?? false);
+                            return { callId: '', success: true, result };
+                        }
+                        case 'logs': {
+                            if (!params.executor_id) {
+                                return { callId: '', success: false, result: null, error: 'executor_id required for logs.' };
+                            }
+                            const result = await client.getExecutorLogs(params.executor_id);
+                            return { callId: '', success: true, result };
+                        }
+                        case 'positions': {
+                            const result = await client.getPositionsSummary(params.connector_name, params.trading_pair);
+                            return { callId: '', success: true, result };
+                        }
+                        case 'clear_position': {
+                            if (!params.connector_name || !params.trading_pair) {
+                                return { callId: '', success: false, result: null, error: 'connector_name and trading_pair required.' };
+                            }
+                            const result = await client.clearPosition(params.connector_name, params.trading_pair);
+                            return { callId: '', success: true, result };
+                        }
+                        case 'types': {
+                            const result = await client.getExecutorTypes();
+                            return { callId: '', success: true, result };
+                        }
+                        case 'type_config': {
+                            if (!params.executor_type)
+                                return { callId: '', success: false, result: null, error: 'executor_type required.' };
+                            const result = await client.getExecutorTypeConfig(params.executor_type);
+                            return { callId: '', success: true, result };
+                        }
+                        case 'summary': {
+                            const result = await client.getExecutorsSummary();
+                            return { callId: '', success: true, result };
+                        }
+                        case 'get_by_id': {
+                            if (!params.executor_id)
+                                return { callId: '', success: false, result: null, error: 'executor_id required.' };
+                            const result = await client.getExecutorById(params.executor_id);
+                            return { callId: '', success: true, result };
+                        }
+                        default:
+                            return {
+                                callId: '', success: false, result: null,
+                                error: `Unknown executor sub_action: "${subAction}". Use: create, search, stop, logs, positions, clear_position, types, type_config, summary, get_by_id.`,
+                            };
+                    }
+                }
+                // ================================================================
+                // Market Data
+                // ================================================================
+                case 'market_data': {
+                    const subAction = params.sub_action ?? 'prices';
+                    const connectorName = params.connector_name;
+                    if (!connectorName) {
+                        return { callId: '', success: false, result: null, error: 'connector_name required for market_data.' };
+                    }
+                    switch (subAction) {
+                        case 'prices': {
+                            const pairs = splitCsv(params.trading_pairs) ?? splitCsv(params.trading_pair) ?? [];
+                            if (pairs.length === 0) {
+                                return { callId: '', success: false, result: null, error: 'trading_pairs or trading_pair required.' };
+                            }
+                            const result = await client.getPrices(connectorName, pairs);
+                            return { callId: '', success: true, result };
+                        }
+                        case 'candles': {
+                            if (!params.trading_pair) {
+                                return { callId: '', success: false, result: null, error: 'trading_pair required for candles.' };
+                            }
+                            const result = await client.getCandles(connectorName, params.trading_pair, params.interval ?? '1h', params.days ?? 30);
+                            return { callId: '', success: true, result };
+                        }
+                        case 'funding': {
+                            if (!params.trading_pair) {
+                                return { callId: '', success: false, result: null, error: 'trading_pair required for funding.' };
+                            }
+                            const result = await client.getFundingRate(connectorName, params.trading_pair);
+                            return { callId: '', success: true, result };
+                        }
+                        case 'orderbook': {
+                            if (!params.trading_pair) {
+                                return { callId: '', success: false, result: null, error: 'trading_pair required for orderbook.' };
+                            }
+                            const result = await client.getOrderBook(connectorName, params.trading_pair, params.query_type ?? 'snapshot', params.query_value, params.is_buy ?? true);
+                            return { callId: '', success: true, result };
+                        }
+                        case 'historical_candles': {
+                            if (!params.trading_pair)
+                                return { callId: '', success: false, result: null, error: 'trading_pair required.' };
+                            if (!params.start_time || !params.end_time)
+                                return { callId: '', success: false, result: null, error: 'start_time and end_time required.' };
+                            const result = await client.getHistoricalCandles({
+                                connectorName,
+                                tradingPair: params.trading_pair,
+                                interval: params.interval ?? '1h',
+                                startTime: params.start_time,
+                                endTime: params.end_time,
+                            });
+                            return { callId: '', success: true, result };
+                        }
+                        case 'vwap': {
+                            if (!params.trading_pair)
+                                return { callId: '', success: false, result: null, error: 'trading_pair required.' };
+                            if (!params.volume)
+                                return { callId: '', success: false, result: null, error: 'volume required for VWAP.' };
+                            const result = await client.getVWAP(connectorName, params.trading_pair, params.is_buy ?? true, params.volume);
+                            return { callId: '', success: true, result };
+                        }
+                        case 'add_pair': {
+                            if (!params.trading_pair)
+                                return { callId: '', success: false, result: null, error: 'trading_pair required.' };
+                            const result = await client.addTradingPair(connectorName, params.trading_pair, params.account_name);
+                            return { callId: '', success: true, result };
+                        }
+                        case 'remove_pair': {
+                            if (!params.trading_pair)
+                                return { callId: '', success: false, result: null, error: 'trading_pair required.' };
+                            const result = await client.removeTradingPair(connectorName, params.trading_pair, params.account_name);
+                            return { callId: '', success: true, result };
+                        }
+                        default:
+                            return {
+                                callId: '', success: false, result: null,
+                                error: `Unknown market_data sub_action: "${subAction}". Use: prices, candles, historical_candles, funding, orderbook, vwap, add_pair, remove_pair.`,
+                            };
+                    }
+                }
+                // ================================================================
+                // Controller management
                 // ================================================================
-                case 'start': {
-                    const strategy = params.strategy;
-                    if (!strategy) {
-                        return { callId: '', success: false, result: null, error: 'strategy is required for start. Options: pure_market_making, avellaneda_market_making, grid, twap.' };
+                case 'controller': {
+                    const subAction = params.sub_action ?? 'list';
+                    const target = params.target ?? 'controller';
+                    switch (subAction) {
+                        case 'list': {
+                            if (target === 'config') {
+                                const result = await client.listControllerConfigs();
+                                return { callId: '', success: true, result };
+                            }
+                            const result = await client.listControllers(params.controller_type);
+                            return { callId: '', success: true, result };
+                        }
+                        case 'describe': {
+                            if (target === 'config' && params.config_name) {
+                                const result = await client.getControllerConfig(params.config_name);
+                                return { callId: '', success: true, result };
+                            }
+                            if (!params.controller_name) {
+                                return { callId: '', success: false, result: null, error: 'controller_name required.' };
+                            }
+                            const result = await client.getController(params.controller_name);
+                            return { callId: '', success: true, result };
+                        }
+                        case 'upsert': {
+                            if (target === 'config') {
+                                if (!params.config_name || !params.config_data) {
+                                    return { callId: '', success: false, result: null, error: 'config_name and config_data required.' };
+                                }
+                                let configData;
+                                try {
+                                    configData = JSON.parse(params.config_data);
+                                }
+                                catch {
+                                    return { callId: '', success: false, result: null, error: 'config_data must be valid JSON.' };
+                                }
+                                const result = await client.upsertControllerConfig(params.config_name, configData);
+                                return { callId: '', success: true, result };
+                            }
+                            if (!params.controller_name) {
+                                return { callId: '', success: false, result: null, error: 'controller_name required.' };
+                            }
+                            const result = await client.upsertController(params.controller_name, {
+                                controllerType: params.controller_type,
+                                controllerCode: params.controller_code,
+                            });
+                            return { callId: '', success: true, result };
+                        }
+                        case 'delete': {
+                            if (target === 'config' && params.config_name) {
+                                const result = await client.deleteControllerConfig(params.config_name);
+                                return { callId: '', success: true, result };
+                            }
+                            if (!params.controller_name) {
+                                return { callId: '', success: false, result: null, error: 'controller_name required.' };
+                            }
+                            const result = await client.deleteController(params.controller_name);
+                            return { callId: '', success: true, result };
+                        }
+                        default:
+                            return { callId: '', success: false, result: null, error: `Unknown controller sub_action: "${subAction}". Use: list, describe, upsert, delete.` };
                     }
-                    const validStrategies = ['pure_market_making', 'avellaneda_market_making', 'grid', 'twap'];
-                    if (!validStrategies.includes(strategy)) {
-                        return { callId: '', success: false, result: null, error: `Invalid strategy "${strategy}". Valid: ${validStrategies.join(', ')}` };
+                }
+                // ================================================================
+                // Bot management
+                // ================================================================
+                case 'bot': {
+                    const subAction = params.sub_action ?? 'status';
+                    switch (subAction) {
+                        case 'deploy': {
+                            const botName = params.bot_name;
+                            const configsStr = params.controllers_config;
+                            if (!botName || !configsStr) {
+                                return { callId: '', success: false, result: null, error: 'bot_name and controllers_config required.' };
+                            }
+                            const result = await client.deployBot({
+                                botName,
+                                controllersConfig: configsStr.split(',').map(s => s.trim()),
+                                accountName: params.account_name,
+                                image: params.image,
+                            });
+                            return { callId: '', success: true, result };
+                        }
+                        case 'status': {
+                            const result = await client.getBotsStatus();
+                            return { callId: '', success: true, result };
+                        }
+                        case 'logs': {
+                            if (!params.bot_name) {
+                                return { callId: '', success: false, result: null, error: 'bot_name required.' };
+                            }
+                            const result = await client.getBotLogs({
+                                botName: params.bot_name,
+                                limit: params.limit ?? 50,
+                                searchTerm: params.search,
+                            });
+                            return { callId: '', success: true, result };
+                        }
+                        case 'stop': {
+                            if (!params.bot_name) {
+                                return { callId: '', success: false, result: null, error: 'bot_name required.' };
+                            }
+                            const result = await client.stopBot(params.bot_name);
+                            return { callId: '', success: true, result };
+                        }
+                        case 'stop_controllers':
+                        case 'start_controllers': {
+                            if (!params.bot_name || !params.controllers_config) {
+                                return { callId: '', success: false, result: null, error: 'bot_name and controllers_config required.' };
+                            }
+                            const names = params.controllers_config.split(',').map(s => s.trim());
+                            const result = subAction === 'stop_controllers'
+                                ? await client.stopControllers(params.bot_name, names)
+                                : await client.startControllers(params.bot_name, names);
+                            return { callId: '', success: true, result };
+                        }
+                        case 'history': {
+                            const name = params.bot_name;
+                            if (!name)
+                                return { callId: '', success: false, result: null, error: 'bot_name required.' };
+                            const result = await client.getBotHistory(name, params.days ?? 0, params.verbose ?? false);
+                            return { callId: '', success: true, result };
+                        }
+                        case 'runs': {
+                            const result = await client.getBotRuns({
+                                botName: params.bot_name,
+                                accountName: params.account_name,
+                                runStatus: params.run_status,
+                                limit: params.limit,
+                                offset: params.offset,
+                            });
+                            return { callId: '', success: true, result };
+                        }
+                        case 'archive': {
+                            const name = params.bot_name;
+                            if (!name)
+                                return { callId: '', success: false, result: null, error: 'bot_name required.' };
+                            const result = await client.archiveBot(name);
+                            return { callId: '', success: true, result };
+                        }
+                        default:
+                            return {
+                                callId: '', success: false, result: null,
+                                error: `Unknown bot sub_action: "${subAction}". Use: deploy, status, logs, stop, stop_controllers, start_controllers, history, runs, archive.`,
+                            };
+                    }
+                }
+                // ================================================================
+                // Gateway: container, config, swaps, CLMM
+                // ================================================================
+                case 'gateway': {
+                    const subAction = params.sub_action ?? 'container_status';
+                    // --- Container lifecycle ---
+                    if (subAction === 'container_status') {
+                        const result = await client.getGatewayStatus();
+                        return { callId: '', success: true, result };
                     }
-                    const prereqs = await checkPrerequisites();
-                    if (!prereqs.docker) {
-                        return { callId: '', success: false, result: null, error: 'Docker not available. Install Docker first or start the Hummingbot MCP server.' };
+                    if (subAction === 'container_start') {
+                        const result = await client.startGateway({
+                            passphrase: params.passphrase ?? 'clawnch',
+                            image: params.image ?? 'hummingbot/gateway:latest',
+                            port: params.port,
+                            environment: undefined,
+                        });
+                        return { callId: '', success: true, result };
                     }
-                    if (!prereqs.image) {
-                        return { callId: '', success: false, result: null, error: 'Hummingbot image not found. Run: docker pull hummingbot/hummingbot:latest' };
+                    if (subAction === 'container_stop') {
+                        const result = await client.stopGateway();
+                        return { callId: '', success: true, result };
                     }
-                    const tokenAddr = params.token_address ?? ctx.identity.tokenAddress;
-                    if (!tokenAddr) {
-                        return { callId: '', success: false, result: null, error: 'No token address. Deploy a token first or specify token_address.' };
+                    if (subAction === 'container_logs') {
+                        const result = await client.getGatewayLogs(params.tail);
+                        return { callId: '', success: true, result };
                     }
-                    if (!ETH_ADDRESS_RE.test(tokenAddr)) {
-                        return { callId: '', success: false, result: null, error: `Invalid token address: "${tokenAddr}". Must be a 0x-prefixed 40-hex-char address.` };
+                    // --- Gateway config ---
+                    if (subAction === 'config_chains') {
+                        const result = await client.listGatewayChains();
+                        return { callId: '', success: true, result };
                     }
-                    if (!ctx.identity.address || !ETH_ADDRESS_RE.test(ctx.identity.address)) {
-                        return { callId: '', success: false, result: null, error: 'Agent identity has no valid wallet address.' };
+                    if (subAction === 'config_networks') {
+                        const result = await client.listGatewayNetworks(params.chain);
+                        return { callId: '', success: true, result };
                     }
-                    const rawInstanceName = params.instance_name ??
-                        `${HB_CONTAINER_PREFIX}-${strategy.replace(/_/g, '-')}-${Date.now().toString(36)}`;
-                    let instanceName;
-                    try {
-                        instanceName = sanitizeName(rawInstanceName);
-                    }
-                    catch (err) {
-                        return { callId: '', success: false, result: null, error: err.message };
-                    }
-                    // Generate strategy config
-                    const config = generateStrategyConfig(strategy, params, tokenAddr, ctx.identity.address);
-                    // Write config to temp file and mount into container
-                    const { writeFileSync, mkdirSync } = await import('fs');
-                    const { join } = await import('path');
-                    const configDir = join(process.env.HOME ?? '/tmp', '.clawncher', 'hummingbot', instanceName);
-                    mkdirSync(configDir, { recursive: true });
-                    writeFileSync(join(configDir, `${strategy}.yml`), config);
-                    // Start Hummingbot container
-                    // Uses bridge networking (not --network host) to limit container's access
-                    const dockerCmd = [
-                        'docker run -d',
-                        `--name "${instanceName}"`,
-                        `-v "${configDir}":/home/hummingbot/conf`,
-                        `hummingbot/hummingbot:latest`,
-                    ].join(' ');
-                    try {
-                        const containerId = await exec(dockerCmd);
+                    if (subAction === 'config_connectors') {
+                        const result = await client.listGatewayConnectors();
+                        return { callId: '', success: true, result };
+                    }
+                    if (subAction === 'config_tokens') {
+                        const result = await client.listGatewayTokens(params.chain, params.network, params.search);
+                        return { callId: '', success: true, result };
+                    }
+                    if (subAction === 'config_wallets') {
+                        const result = await client.listGatewayWallets(params.chain);
+                        return { callId: '', success: true, result };
+                    }
+                    if (subAction === 'config_add_token') {
+                        const result = await client.addGatewayToken({
+                            chain: params.chain,
+                            network: params.network,
+                            tokenAddress: params.token_address,
+                            tokenSymbol: params.token_symbol,
+                            tokenDecimals: params.token_decimals,
+                            tokenName: params.token_name,
+                        });
+                        return { callId: '', success: true, result };
+                    }
+                    if (subAction === 'config_add_wallet') {
+                        const result = await client.addGatewayWallet(params.chain, params.private_key);
+                        return { callId: '', success: true, result };
+                    }
+                    // --- Swaps ---
+                    if (subAction === 'swap_quote') {
+                        const result = await client.getGatewayAmmPrice({
+                            connector: params.connector_name,
+                            chain: params.chain,
+                            network: params.network,
+                            tradingPair: params.trading_pair,
+                            side: params.side?.toUpperCase(),
+                            amount: params.amount,
+                        });
+                        return { callId: '', success: true, result };
+                    }
+                    if (subAction === 'swap_execute') {
+                        const result = await client.executeGatewayAmmTrade({
+                            connector: params.connector_name,
+                            chain: params.chain,
+                            network: params.network,
+                            tradingPair: params.trading_pair,
+                            side: params.side?.toUpperCase(),
+                            amount: params.amount,
+                            slippagePct: params.slippage_pct,
+                            walletAddress: params.wallet_address ?? ctx.identity.address,
+                        });
+                        return { callId: '', success: true, result };
+                    }
+                    // --- CLMM ---
+                    if (subAction === 'clmm_list') {
+                        const result = await client.listCLMMPools({
+                            connector: params.connector_name,
+                            chain: params.chain,
+                            network: params.network,
+                            limit: params.limit ?? 50,
+                            searchTerm: params.search,
+                        });
+                        return { callId: '', success: true, result };
+                    }
+                    if (subAction === 'clmm_info') {
+                        const result = await client.getCLMMPoolInfo({
+                            connector: params.connector_name,
+                            chain: params.chain,
+                            network: params.network,
+                            poolAddress: params.pool_address,
+                        });
+                        return { callId: '', success: true, result };
+                    }
+                    if (subAction === 'clmm_positions') {
+                        const result = await client.getCLMMPositions({
+                            connector: params.connector_name,
+                            chain: params.chain,
+                            network: params.network,
+                            walletAddress: params.wallet_address ?? ctx.identity.address,
+                            poolAddress: params.pool_address,
+                        });
+                        return { callId: '', success: true, result };
+                    }
+                    if (subAction === 'clmm_open') {
+                        const result = await client.addCLMMLiquidity({
+                            connector: params.connector_name,
+                            chain: params.chain,
+                            network: params.network,
+                            poolAddress: params.pool_address,
+                            walletAddress: params.wallet_address ?? ctx.identity.address,
+                            lowerPrice: params.lower_price,
+                            upperPrice: params.upper_price,
+                            baseTokenAmount: params.base_token_amount,
+                            quoteTokenAmount: params.quote_token_amount,
+                            slippagePct: params.slippage_pct,
+                        });
+                        return { callId: '', success: true, result };
+                    }
+                    if (subAction === 'clmm_close') {
+                        const result = await client.removeCLMMLiquidity({
+                            connector: params.connector_name,
+                            chain: params.chain,
+                            network: params.network,
+                            positionAddress: params.position_address,
+                            walletAddress: params.wallet_address ?? ctx.identity.address,
+                            slippagePct: params.slippage_pct,
+                        });
+                        return { callId: '', success: true, result };
+                    }
+                    return {
+                        callId: '', success: false, result: null,
+                        error: `Unknown gateway sub_action: "${subAction}". Prefixes: container_, config_, swap_, clmm_.`,
+                    };
+                }
+                // ================================================================
+                // History
+                // ================================================================
+                case 'history': {
+                    const dataType = params.sub_action ?? 'orders';
+                    const validTypes = ['orders', 'perp_positions', 'clmm_positions'];
+                    if (!validTypes.includes(dataType)) {
                         return {
-                            callId: '',
-                            success: true,
-                            result: [
-                                `Hummingbot instance started.`,
-                                `  Instance: ${instanceName}`,
-                                `  Container: ${containerId.substring(0, 12)}`,
-                                `  Strategy: ${strategy}`,
-                                `  Token: ${tokenAddr}`,
-                                `  Config: ${configDir}/${strategy}.yml`,
-                                '',
-                                `Monitor: use action "logs" with instance_name "${instanceName}"`,
-                                `Stop: use action "stop" with instance_name "${instanceName}"`,
-                            ].join('\n'),
-                            metadata: { instance_name: instanceName, container_id: containerId.substring(0, 12) },
+                            callId: '', success: false, result: null,
+                            error: `Invalid history sub_action: "${dataType}". Use: orders, perp_positions, clmm_positions.`,
                         };
                     }
-                    catch (err) {
-                        return { callId: '', success: false, result: null, error: `Failed to start container: ${err.message}` };
-                    }
+                    const result = await client.searchHistory({
+                        dataType: dataType,
+                        accountNames: splitCsv(params.account_names),
+                        connectorNames: splitCsv(params.connector_names) ?? (params.connector_name ? [params.connector_name] : undefined),
+                        tradingPairs: splitCsv(params.trading_pairs) ?? (params.trading_pair ? [params.trading_pair] : undefined),
+                        status: params.status,
+                        startTime: params.start_time,
+                        endTime: params.end_time,
+                        limit: params.limit ?? 50,
+                        offset: params.offset ?? 0,
+                        network: params.network,
+                        walletAddress: params.wallet_address,
+                    });
+                    return { callId: '', success: true, result };
                 }
                 // ================================================================
-                // Stop: terminate a market-making instance
+                // Templates
                 // ================================================================
-                case 'stop': {
-                    const rawStopName = params.instance_name;
-                    if (!rawStopName) {
-                        const instances = await listInstances();
-                        if (instances.length === 0) {
-                            return { callId: '', success: true, result: 'No running Hummingbot instances.' };
+                case 'templates': {
+                    const subAction = params.sub_action ?? 'list';
+                    if (subAction === 'list') {
+                        const templates = client.getStrategyTemplates();
+                        const clawnchTemplates = templates.filter((t) => t.template.startsWith('clawnch_'));
+                        const genericTemplates = templates.filter((t) => !t.template.startsWith('clawnch_'));
+                        const lines = [
+                            'Clawnch Token Strategy Templates:',
+                            ...clawnchTemplates.map((t) => `  ${t.template}: ${t.description} (executor: ${t.executorType})`),
+                            '',
+                            'Generic Strategy Templates:',
+                            ...genericTemplates.map((t) => `  ${t.template}: ${t.description} (executor: ${t.executorType})`),
+                            '', 'Use sub_action="describe" with template to see details, or sub_action="build" to create.',
+                        ];
+                        return { callId: '', success: true, result: lines.join('\n') };
+                    }
+                    if (subAction === 'describe') {
+                        if (!params.template) {
+                            return { callId: '', success: false, result: null, error: 'template parameter required.' };
+                        }
+                        const tmpl = client.getStrategyTemplate(params.template);
+                        if (!tmpl) {
+                            return { callId: '', success: false, result: null, error: `Unknown template: ${params.template}` };
                         }
                         return {
-                            callId: '',
-                            success: false,
-                            result: null,
-                            error: `instance_name is required. Running instances:\n${instances.map(i => `  ${i.name}: ${i.status}`).join('\n')}`,
+                            callId: '', success: true,
+                            result: `Template: ${tmpl.template}\nDescription: ${tmpl.description}\nExecutor Type: ${tmpl.executorType}\nDefaults: ${JSON.stringify(tmpl.defaultConfig, null, 2)}\nRequired: ${tmpl.requiredOverrides.join(', ')}`,
                         };
                     }
-                    let instanceName;
-                    try {
-                        instanceName = sanitizeName(rawStopName);
+                    if (subAction === 'build') {
+                        if (!params.template)
+                            return { callId: '', success: false, result: null, error: 'template required.' };
+                        if (!params.executor_config)
+                            return { callId: '', success: false, result: null, error: 'executor_config (JSON) required.' };
+                        let overrides;
+                        try {
+                            overrides = JSON.parse(params.executor_config);
+                        }
+                        catch {
+                            return { callId: '', success: false, result: null, error: 'executor_config must be valid JSON.' };
+                        }
+                        const config = client.buildFromTemplate(params.template, overrides);
+                        const result = await client.createExecutor(config);
+                        return { callId: '', success: true, result };
                     }
-                    catch (err) {
-                        return { callId: '', success: false, result: null, error: err.message };
+                    return { callId: '', success: false, result: null, error: `Unknown templates sub_action: "${subAction}". Use: list, describe, build.` };
+                }
+                // ================================================================
+                // Connector setup
+                // ================================================================
+                case 'connector': {
+                    const subAction = params.sub_action ?? 'list';
+                    if (subAction === 'list') {
+                        const result = await client.listConnectors();
+                        return { callId: '', success: true, result };
                     }
+                    if (subAction === 'config_map') {
+                        if (!params.connector_name) {
+                            return { callId: '', success: false, result: null, error: 'connector_name required.' };
+                        }
+                        const result = await client.getConnectorConfigMap(params.connector_name);
+                        return { callId: '', success: true, result };
+                    }
+                    if (subAction === 'setup') {
+                        if (!params.connector_name || !params.credentials) {
+                            return { callId: '', success: false, result: null, error: 'connector_name and credentials (JSON) required.' };
+                        }
+                        let creds;
+                        try {
+                            creds = JSON.parse(params.credentials);
+                        }
+                        catch {
+                            return { callId: '', success: false, result: null, error: 'credentials must be valid JSON.' };
+                        }
+                        const accountName = params.account_name ?? 'master_account';
+                        const result = await client.addConnector(accountName, params.connector_name, creds);
+                        return { callId: '', success: true, result };
+                    }
+                    if (subAction === 'trading_rules') {
+                        if (!params.connector_name) {
+                            return { callId: '', success: false, result: null, error: 'connector_name required.' };
+                        }
+                        const tradingPairs = params.trading_pair ? [params.trading_pair] : undefined;
+                        const result = await client.getTradingRules(params.connector_name, tradingPairs);
+                        return { callId: '', success: true, result };
+                    }
+                    if (subAction === 'order_types') {
+                        if (!params.connector_name) {
+                            return { callId: '', success: false, result: null, error: 'connector_name required.' };
+                        }
+                        const result = await client.getOrderTypes(params.connector_name);
+                        return { callId: '', success: true, result };
+                    }
+                    return { callId: '', success: false, result: null, error: `Unknown connector sub_action: "${subAction}". Use: list, config_map, setup, trading_rules, order_types.` };
+                }
+                // ================================================================
+                // Backtesting
+                // ================================================================
+                case 'backtest': {
+                    let config = params.config;
                     try {
-                        await exec(`docker stop "${instanceName}"`);
-                        await exec(`docker rm "${instanceName}"`);
-                        return { callId: '', success: true, result: `Stopped and removed instance: ${instanceName}` };
+                        config = JSON.parse(config);
+                    }
+                    catch { /* keep as string (config name) */ }
+                    const result = await client.runBacktest({
+                        config,
+                        startTime: params.start_time,
+                        endTime: params.end_time,
+                        resolution: params.resolution,
+                        tradeCost: params.trade_cost,
+                    });
+                    return { callId: '', success: true, result };
+                }
+                // ================================================================
+                // Connector / Market Discovery
+                // ================================================================
+                case 'discovery': {
+                    const subAction = params.sub_action;
+                    if (subAction === 'connectors' || !subAction) {
+                        const result = await client.listConnectors();
+                        return { callId: '', success: true, result };
+                    }
+                    if (subAction === 'config_map') {
+                        const result = await client.getConnectorConfigMap(params.connector_name);
+                        return { callId: '', success: true, result };
                     }
-                    catch (err) {
-                        return { callId: '', success: false, result: null, error: `Failed to stop ${instanceName}: ${err.message}` };
+                    if (subAction === 'trading_rules') {
+                        const result = await client.getTradingRules(params.connector_name, splitCsv(params.trading_pairs));
+                        return { callId: '', success: true, result };
                     }
+                    if (subAction === 'order_types') {
+                        const result = await client.getOrderTypes(params.connector_name);
+                        return { callId: '', success: true, result };
+                    }
+                    return { callId: '', success: false, result: null, error: `Unknown discovery sub_action: "${subAction}". Use: connectors, config_map, trading_rules, order_types.` };
                 }
                 // ================================================================
-                // List: show running instances
+                // Archived Bot Analytics
                 // ================================================================
-                case 'list': {
-                    const instances = await listInstances();
-                    if (instances.length === 0) {
-                        return { callId: '', success: true, result: 'No running Hummingbot instances.' };
+                case 'archived': {
+                    const subAction = params.sub_action;
+                    if (subAction === 'list' || !subAction) {
+                        const result = await client.listArchivedBots();
+                        return { callId: '', success: true, result };
                     }
-                    const lines = instances.map(i => `  ${i.name}: ${i.status} (created ${i.created})`);
-                    return {
-                        callId: '',
-                        success: true,
-                        result: `${instances.length} Hummingbot instance(s):\n${lines.join('\n')}`,
-                    };
+                    const dbPath = params.db_path;
+                    if (!dbPath)
+                        return { callId: '', success: false, result: null, error: 'db_path required for archived bot queries.' };
+                    if (subAction === 'summary') {
+                        const result = await client.getArchivedBotSummary(dbPath);
+                        return { callId: '', success: true, result };
+                    }
+                    if (subAction === 'performance') {
+                        const result = await client.getArchivedBotPerformance(dbPath);
+                        return { callId: '', success: true, result };
+                    }
+                    if (subAction === 'trades') {
+                        const result = await client.getArchivedBotTrades(dbPath, params.limit ?? 100, params.offset ?? 0);
+                        return { callId: '', success: true, result };
+                    }
+                    if (subAction === 'orders') {
+                        const result = await client.getArchivedBotOrders(dbPath, params.limit ?? 100, params.offset ?? 0, params.status);
+                        return { callId: '', success: true, result };
+                    }
+                    return { callId: '', success: false, result: null, error: `Unknown archived sub_action: "${subAction}". Use: list, summary, performance, trades, orders.` };
                 }
                 // ================================================================
-                // Logs: get recent logs from an instance
+                // Script Management
                 // ================================================================
-                case 'logs': {
-                    const rawLogsName = params.instance_name;
-                    if (!rawLogsName) {
-                        return { callId: '', success: false, result: null, error: 'instance_name is required for logs.' };
+                case 'scripts': {
+                    const subAction = params.sub_action;
+                    if (subAction === 'list' || !subAction) {
+                        const result = await client.listScripts();
+                        return { callId: '', success: true, result };
                     }
-                    let instanceName;
-                    try {
-                        instanceName = sanitizeName(rawLogsName);
+                    if (subAction === 'get') {
+                        const result = await client.getScript(params.script_name);
+                        return { callId: '', success: true, result };
                     }
-                    catch (err) {
-                        return { callId: '', success: false, result: null, error: err.message };
+                    if (subAction === 'upsert') {
+                        const result = await client.upsertScript(params.script_name, params.script_content);
+                        return { callId: '', success: true, result };
                     }
-                    try {
-                        const logs = await exec(`docker logs --tail 50 "${instanceName}"`);
-                        return { callId: '', success: true, result: `Last 50 lines from ${instanceName}:\n${logs}` };
+                    if (subAction === 'delete') {
+                        const result = await client.deleteScript(params.script_name);
+                        return { callId: '', success: true, result };
+                    }
+                    if (subAction === 'configs') {
+                        const result = await client.listScriptConfigs();
+                        return { callId: '', success: true, result };
+                    }
+                    if (subAction === 'get_config') {
+                        const result = await client.getScriptConfig(params.config_name);
+                        return { callId: '', success: true, result };
+                    }
+                    if (subAction === 'upsert_config') {
+                        let data;
+                        try {
+                            data = JSON.parse(params.config_data);
+                        }
+                        catch {
+                            return { callId: '', success: false, result: null, error: 'config_data must be valid JSON.' };
+                        }
+                        const result = await client.upsertScriptConfig(params.config_name, data);
+                        return { callId: '', success: true, result };
+                    }
+                    if (subAction === 'delete_config') {
+                        const result = await client.deleteScriptConfig(params.config_name);
+                        return { callId: '', success: true, result };
                     }
-                    catch (err) {
-                        return { callId: '', success: false, result: null, error: `Failed to get logs for ${instanceName}: ${err.message}` };
+                    if (subAction === 'template') {
+                        const result = await client.getScriptConfigTemplate(params.script_name);
+                        return { callId: '', success: true, result };
                     }
+                    return { callId: '', success: false, result: null, error: `Unknown scripts sub_action: "${subAction}". Use: list, get, upsert, delete, configs, get_config, upsert_config, delete_config, template.` };
                 }
                 // ================================================================
-                // Configure: preview strategy config without starting
+                // Portfolio Analytics & Rate Oracle
                 // ================================================================
-                case 'configure': {
-                    const strategy = params.strategy;
-                    if (!strategy) {
-                        return { callId: '', success: false, result: null, error: 'strategy is required for configure.' };
+                case 'analytics': {
+                    const subAction = params.sub_action;
+                    if (subAction === 'history') {
+                        const result = await client.getPortfolioHistory({
+                            accountNames: splitCsv(params.account_names),
+                            connectorNames: splitCsv(params.connector_names),
+                            startTime: params.start_time,
+                            endTime: params.end_time,
+                            interval: params.interval,
+                            limit: params.limit,
+                        });
+                        return { callId: '', success: true, result };
                     }
-                    const tokenAddr = params.token_address ?? ctx.identity.tokenAddress ?? '0x0000000000000000000000000000000000000000';
-                    if (tokenAddr !== '0x0000000000000000000000000000000000000000' && !ETH_ADDRESS_RE.test(tokenAddr)) {
-                        return { callId: '', success: false, result: null, error: `Invalid token address: "${tokenAddr}"` };
+                    if (subAction === 'distribution') {
+                        const result = await client.getPortfolioDistribution({
+                            accountNames: splitCsv(params.account_names),
+                            connectorNames: splitCsv(params.connector_names),
+                        });
+                        return { callId: '', success: true, result };
                     }
-                    const config = generateStrategyConfig(strategy, params, tokenAddr, ctx.identity.address);
-                    return {
-                        callId: '',
-                        success: true,
-                        result: `Strategy config preview (${strategy}):\n\n${config}\n\nUse action "start" with the same parameters to launch.`,
-                    };
+                    if (subAction === 'accounts_distribution') {
+                        const result = await client.getAccountsDistribution();
+                        return { callId: '', success: true, result };
+                    }
+                    if (subAction === 'funding_payments') {
+                        const result = await client.getFundingPayments({
+                            accountNames: splitCsv(params.account_names),
+                            connectorNames: splitCsv(params.connector_names),
+                            tradingPair: params.trading_pair,
+                            limit: params.limit,
+                        });
+                        return { callId: '', success: true, result };
+                    }
+                    if (subAction === 'rates') {
+                        const pairs = splitCsv(params.trading_pairs);
+                        if (!pairs?.length)
+                            return { callId: '', success: false, result: null, error: 'trading_pairs required.' };
+                        const result = await client.getRates(pairs);
+                        return { callId: '', success: true, result };
+                    }
+                    if (subAction === 'rate') {
+                        const result = await client.getRate(params.trading_pair);
+                        return { callId: '', success: true, result };
+                    }
+                    return { callId: '', success: false, result: null, error: `Unknown analytics sub_action: "${subAction}". Use: history, distribution, accounts_distribution, funding_payments, rates, rate.` };
+                }
+                // ================================================================
+                // Account Management
+                // ================================================================
+                case 'accounts': {
+                    const subAction = params.sub_action;
+                    if (subAction === 'list' || !subAction) {
+                        const result = await client.listAccounts();
+                        return { callId: '', success: true, result };
+                    }
+                    if (subAction === 'credentials') {
+                        const result = await client.getAccountCredentials(params.account_name);
+                        return { callId: '', success: true, result };
+                    }
+                    if (subAction === 'create') {
+                        const result = await client.createAccount(params.account_name);
+                        return { callId: '', success: true, result };
+                    }
+                    if (subAction === 'delete') {
+                        const result = await client.deleteAccount(params.account_name);
+                        return { callId: '', success: true, result };
+                    }
+                    return { callId: '', success: false, result: null, error: `Unknown accounts sub_action: "${subAction}". Use: list, credentials, create, delete.` };
                 }
+                // ================================================================
+                // Unknown
+                // ================================================================
                 default:
                     return {
-                        callId: '',
-                        success: false,
-                        result: null,
-                        error: `Unknown hummingbot action: "${action}". Valid: status, start, stop, list, logs, configure.`,
+                        callId: '', success: false, result: null,
+                        error: `Unknown hummingbot action: "${action}". Valid: status, portfolio, order, leverage, executor, market_data, controller, bot, gateway, history, templates, connector, servers, backtest, discovery, archived, scripts, analytics, accounts.`,
                     };
             }
         }
         catch (err) {
-            return { callId: '', success: false, result: null, error: err instanceof Error ? err.message : String(err) };
+            const message = err?.code ? `[${err.code}] ${err.message}` : err?.message ?? String(err);
+            return { callId: '', success: false, result: null, error: message };
         }
     },
 };