@terminusagents/agents 0.1.0

package/dist/agents/types.d.ts

@@ -0,0 +1,20 @@
+export type ToolParams = Record<string, unknown>;
+export type ToolResult = {
+    success: boolean;
+    data: unknown;
+};
+export interface AgentTool {
+    name: string;
+    description: string;
+    parameters: string[];
+}
+export interface AgentDefinition {
+    id: string;
+    name: string;
+    description: string;
+    systemPrompt: string;
+    tools: AgentTool[];
+    keywords: string[];
+}
+export type ToolImplementation = (params: ToolParams) => Promise<unknown>;
+export type ToolRegistry = Record<string, ToolImplementation>;

package/dist/agents/types.js

@@ -0,0 +1,4 @@
+// =============================================================================
+// TERMINUS AGENTS - Agent Types
+// =============================================================================
+export {};

package/dist/cli/doctor.d.ts

@@ -0,0 +1,4 @@
+export interface DoctorCommandOptions {
+    full?: boolean;
+}
+export declare function doctorCommand(options?: DoctorCommandOptions): Promise<void>;

package/dist/cli/doctor.js

@@ -0,0 +1,184 @@
+// =============================================================================
+// TERMINUS AGENT - Doctor Command
+// =============================================================================
+import chalk from 'chalk';
+import WebSocket from 'ws';
+import { ethers } from 'ethers';
+import { checkOllamaAvailable } from '../llm/provider.js';
+import { configExists, loadConfig } from '../config/store.js';
+function printCheck(label, result) {
+    const status = result.ok ? chalk.green('PASS') : chalk.red('FAIL');
+    console.log(`${status} ${chalk.white(label)} ${chalk.gray('-')} ${result.message}`);
+}
+function isValidWallet(value) {
+    return /^0x[a-fA-F0-9]{40}$/.test(value);
+}
+function isWsUrl(value) {
+    return value.startsWith('ws://') || value.startsWith('wss://');
+}
+function getRuntimeGrokKey(storedApiKey) {
+    if (storedApiKey && storedApiKey !== '__ENV__')
+        return storedApiKey;
+    return process.env.TERMINUS_GROK_API_KEY?.trim() || process.env.XAI_API_KEY?.trim();
+}
+async function checkWebSocketReachability(url, timeoutMs) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const ws = new WebSocket(url);
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settled = true;
+            ws.terminate();
+            resolve({ ok: false, message: `No response within ${timeoutMs}ms` });
+        }, timeoutMs);
+        ws.once('open', () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            ws.close();
+            resolve({ ok: true, message: 'Socket is reachable' });
+        });
+        ws.once('error', (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({ ok: false, message: error.message });
+        });
+    });
+}
+async function checkGrokApiKey(apiKey, fullCheck) {
+    if (!apiKey.startsWith('xai-')) {
+        return { ok: false, message: 'Key format invalid (expected xai-...)' };
+    }
+    if (!fullCheck) {
+        return { ok: true, message: 'Key format looks valid' };
+    }
+    try {
+        const response = await fetch('https://api.x.ai/v1/models', {
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+            },
+        });
+        if (response.ok) {
+            return { ok: true, message: 'xAI API reachable and key accepted' };
+        }
+        return { ok: false, message: `xAI API returned ${response.status}` };
+    }
+    catch (error) {
+        return { ok: false, message: error.message };
+    }
+}
+async function checkOpenAiCompatible(baseUrl, fullCheck) {
+    if (!baseUrl) {
+        return { ok: false, message: 'Base URL is missing' };
+    }
+    if (!fullCheck) {
+        return { ok: true, message: `Configured (${baseUrl})` };
+    }
+    try {
+        const response = await fetch(`${baseUrl.replace(/\/$/, '')}/v1/models`);
+        if (response.ok) {
+            return { ok: true, message: 'Server reachable' };
+        }
+        return { ok: false, message: `Server returned ${response.status}` };
+    }
+    catch (error) {
+        return { ok: false, message: error.message };
+    }
+}
+export async function doctorCommand(options = {}) {
+    const fullCheck = options.full === true;
+    let allOk = true;
+    console.log();
+    console.log(chalk.cyan.bold('Terminus Agent Doctor'));
+    console.log(chalk.gray('Checks local config, auth readiness, connectivity, and provider health.\n'));
+    if (!configExists()) {
+        printCheck('Config file', { ok: false, message: 'Missing config (~/.terminus/config.json)' });
+        console.log(chalk.cyan('\nRun: npx terminus-agent init\n'));
+        return;
+    }
+    const config = loadConfig();
+    if (!config) {
+        printCheck('Config file', { ok: false, message: 'Config exists but is invalid. Re-run init.' });
+        console.log(chalk.cyan('\nRun: npx terminus-agent init --force\n'));
+        return;
+    }
+    const walletCheck = isValidWallet(config.wallet)
+        ? { ok: true, message: `${config.wallet.slice(0, 10)}...${config.wallet.slice(-8)}` }
+        : { ok: false, message: 'Invalid wallet format' };
+    printCheck('Wallet format', walletCheck);
+    allOk = allOk && walletCheck.ok;
+    const privateKey = process.env.TERMINUS_WALLET_PRIVATE_KEY?.trim();
+    const privateKeyCheck = privateKey
+        ? { ok: true, message: 'TERMINUS_WALLET_PRIVATE_KEY is set' }
+        : { ok: false, message: 'Missing TERMINUS_WALLET_PRIVATE_KEY' };
+    printCheck('Runtime private key', privateKeyCheck);
+    allOk = allOk && privateKeyCheck.ok;
+    if (privateKey) {
+        try {
+            const signer = new ethers.Wallet(privateKey.startsWith('0x') ? privateKey : `0x${privateKey}`);
+            const matches = signer.address.toLowerCase() === config.wallet.toLowerCase();
+            const matchResult = matches
+                ? { ok: true, message: 'Signer wallet matches configured wallet' }
+                : { ok: false, message: `Signer wallet ${signer.address} differs from config wallet` };
+            printCheck('Wallet/private key match', matchResult);
+            allOk = allOk && matchResult.ok;
+        }
+        catch (error) {
+            const invalidPk = { ok: false, message: `Invalid private key: ${error.message}` };
+            printCheck('Wallet/private key match', invalidPk);
+            allOk = false;
+        }
+    }
+    const cpUrlCheck = isWsUrl(config.controlPlaneUrl)
+        ? { ok: true, message: config.controlPlaneUrl }
+        : { ok: false, message: 'Control plane URL must start with ws:// or wss://' };
+    printCheck('Control plane URL format', cpUrlCheck);
+    allOk = allOk && cpUrlCheck.ok;
+    const mainnetWssCheck = config.networkProfile === 'mainnet' && !config.controlPlaneUrl.startsWith('wss://')
+        ? { ok: false, message: 'Mainnet profile requires wss:// URL' }
+        : { ok: true, message: 'Transport profile is valid' };
+    printCheck('Transport policy', mainnetWssCheck);
+    allOk = allOk && mainnetWssCheck.ok;
+    if (cpUrlCheck.ok) {
+        const reachability = await checkWebSocketReachability(config.controlPlaneUrl, 5000);
+        printCheck('Control plane reachability', reachability);
+        allOk = allOk && reachability.ok;
+    }
+    const provider = config.llmProvider || 'grok';
+    if (provider === 'grok') {
+        const key = getRuntimeGrokKey(config.apiKey);
+        const result = key
+            ? await checkGrokApiKey(key, fullCheck)
+            : { ok: false, message: 'No Grok key found (config or env)' };
+        printCheck('Grok provider', result);
+        allOk = allOk && result.ok;
+    }
+    else if (provider === 'ollama') {
+        const baseUrl = config.llmBaseUrl || 'http://localhost:11434';
+        const available = await checkOllamaAvailable(baseUrl);
+        const result = available
+            ? { ok: true, message: `Ollama reachable at ${baseUrl}` }
+            : { ok: false, message: `Ollama not reachable at ${baseUrl}` };
+        printCheck('Ollama provider', result);
+        allOk = allOk && result.ok;
+    }
+    else {
+        const result = await checkOpenAiCompatible(config.llmBaseUrl || '', fullCheck);
+        printCheck('OpenAI-compatible provider', result);
+        allOk = allOk && result.ok;
+    }
+    console.log();
+    if (allOk) {
+        console.log(chalk.green.bold('Doctor result: READY'));
+        console.log(chalk.cyan('Start node: npx terminus-agent run\n'));
+    }
+    else {
+        console.log(chalk.red.bold('Doctor result: NOT READY'));
+        console.log(chalk.cyan('Fix failed checks, then run: npx terminus-agent doctor --full\n'));
+        process.exitCode = 1;
+    }
+}

package/dist/cli/init.d.ts

@@ -0,0 +1,16 @@
+import type { NetworkProfile } from '../config/store.js';
+type LlmProvider = 'grok' | 'ollama' | 'openai-compatible';
+export interface InitCommandOptions {
+    agentType?: string;
+    wallet?: string;
+    llmProvider?: LlmProvider;
+    apiKey?: string;
+    llmBaseUrl?: string;
+    llmModel?: string;
+    controlPlaneUrl?: string;
+    profile?: NetworkProfile;
+    yes?: boolean;
+    force?: boolean;
+}
+export declare function initCommand(rawOptions?: InitCommandOptions): Promise<void>;
+export {};

package/dist/cli/init.js

@@ -0,0 +1,429 @@
+// =============================================================================
+// TERMINUS AGENT - Init Command (Onboarding Focused)
+// =============================================================================
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+import { saveConfig, generateNodeId, getConfigPath, configExists, loadConfig } from '../config/store.js';
+import { checkOllamaAvailable, listOllamaModels } from '../llm/provider.js';
+import { AGENTS } from '../agents/index.js';
+const BANNER = `
+╔═══════════════════════════════════════════════════════════════════╗
+║                                                                   ║
+║   ████████╗███████╗██████╗ ███╗   ███╗██╗███╗   ██╗██╗   ██╗███████╗   ║
+║   ╚══██╔══╝██╔════╝██╔══██╗████╗ ████║██║████╗  ██║██║   ██║██╔════╝   ║
+║      ██║   █████╗  ██████╔╝██╔████╔██║██║██╔██╗ ██║██║   ██║███████╗   ║
+║      ██║   ██╔══╝  ██╔══██╗██║╚██╔╝██║██║██║╚██╗██║██║   ██║╚════██║   ║
+║      ██║   ███████╗██║  ██║██║ ╚═╝ ██║██║██║ ╚████║╚██████╔╝███████║   ║
+║      ╚═╝   ╚══════╝╚═╝  ╚═╝╚═╝     ╚═╝╚═╝╚═╝  ╚═══╝ ╚═════╝ ╚══════╝   ║
+║                                                                   ║
+║                    Terminus Agent Setup Wizard                    ║
+║                                                                   ║
+╚═══════════════════════════════════════════════════════════════════╝
+`;
+const AGENT_EMOJIS = {
+    'travel-planner': '✈️',
+    'budget-planner': '💰',
+    'health-advisor': '🏥',
+    'fundamental-analyst': '📊',
+    'technical-analyst': '📈',
+    'crypto-advisor': '🪙',
+    'food-expert': '🍳',
+    'fitness-coach': '💪',
+    'legal-advisor': '⚖️',
+    'real-estate': '🏠',
+    'career-coach': '💼',
+    'event-planner': '🎉',
+    'tech-support': '🔧',
+    'shopping-assistant': '🛒',
+    'language-tutor': '🌍',
+};
+const NETWORK_LABELS = {
+    local: 'Local development',
+    testnet: 'Base Sepolia testnet',
+    mainnet: 'Base mainnet',
+};
+const NETWORK_URL_PRESETS = {
+    local: process.env.TERMINUS_CONTROL_PLANE_URL_LOCAL?.trim() || 'ws://localhost:8084',
+    testnet: process.env.TERMINUS_CONTROL_PLANE_URL_TESTNET?.trim() ||
+        process.env.TERMINUS_CONTROL_PLANE_URL?.trim() ||
+        'ws://localhost:8084',
+    mainnet: process.env.TERMINUS_CONTROL_PLANE_URL_MAINNET?.trim() ||
+        process.env.TERMINUS_CONTROL_PLANE_URL?.trim() ||
+        'wss://localhost:8084',
+};
+const LLM_CHOICES = [
+    {
+        name: `Grok API               ${chalk.gray('xAI Cloud (best quality)')}`,
+        value: 'grok',
+        short: 'Grok API',
+    },
+    {
+        name: `Ollama                 ${chalk.gray('Local LLM (free)')}`,
+        value: 'ollama',
+        short: 'Ollama',
+    },
+    {
+        name: `OpenAI-Compatible      ${chalk.gray('LM Studio / LocalAI / vLLM')}`,
+        value: 'openai-compatible',
+        short: 'OpenAI-Compatible',
+    },
+];
+function printBanner() {
+    console.clear();
+    console.log(chalk.cyan(BANNER));
+}
+function printInfo(label, value) {
+    console.log(chalk.gray(`   ${label}: `) + chalk.white(value));
+}
+function must(value, message) {
+    if (value === undefined || value === null) {
+        throw new Error(message);
+    }
+    return value;
+}
+function isValidWallet(input) {
+    return /^0x[a-fA-F0-9]{40}$/.test(input);
+}
+function isWsUrl(input) {
+    return input.startsWith('ws://') || input.startsWith('wss://');
+}
+function normalizeProvider(provider) {
+    if (!provider)
+        return undefined;
+    if (provider === 'grok' || provider === 'ollama' || provider === 'openai-compatible') {
+        return provider;
+    }
+    return undefined;
+}
+function normalizeProfile(profile) {
+    if (!profile)
+        return undefined;
+    if (profile === 'local' || profile === 'testnet' || profile === 'mainnet') {
+        return profile;
+    }
+    return undefined;
+}
+function getRuntimeGrokKey() {
+    return process.env.TERMINUS_GROK_API_KEY?.trim() || process.env.XAI_API_KEY?.trim();
+}
+async function promptForAgentType(initialValue, nonInteractive) {
+    if (initialValue) {
+        if (!AGENTS.some((agent) => agent.id === initialValue)) {
+            throw new Error(`Unknown agentType "${initialValue}".`);
+        }
+        return initialValue;
+    }
+    if (nonInteractive) {
+        return 'travel-planner';
+    }
+    const choices = AGENTS.map((agent) => ({
+        name: `${AGENT_EMOJIS[agent.id] || '🤖'} ${agent.name.padEnd(22)} ${chalk.gray(agent.description)}`,
+        value: agent.id,
+        short: agent.name,
+    }));
+    const { agentType } = await inquirer.prompt([
+        {
+            type: 'list',
+            name: 'agentType',
+            message: 'Select agent type:',
+            choices,
+            pageSize: 15,
+            loop: false,
+        },
+    ]);
+    return agentType;
+}
+async function promptForWallet(initialValue, nonInteractive) {
+    if (initialValue) {
+        if (!isValidWallet(initialValue)) {
+            throw new Error('Wallet must be a valid EVM address.');
+        }
+        return initialValue;
+    }
+    if (nonInteractive) {
+        throw new Error('wallet is required in non-interactive mode. Use --wallet 0x...');
+    }
+    const { wallet } = await inquirer.prompt([
+        {
+            type: 'input',
+            name: 'wallet',
+            message: 'Wallet address (0x...):',
+            validate: (input) => {
+                if (!input)
+                    return 'Wallet address is required';
+                if (!isValidWallet(input))
+                    return 'Invalid EVM wallet address';
+                return true;
+            },
+        },
+    ]);
+    return wallet;
+}
+async function promptForProvider(initialValue, nonInteractive) {
+    if (initialValue)
+        return initialValue;
+    if (nonInteractive)
+        return 'grok';
+    const { llmProvider } = await inquirer.prompt([
+        {
+            type: 'list',
+            name: 'llmProvider',
+            message: 'Select LLM provider:',
+            choices: LLM_CHOICES,
+            loop: false,
+        },
+    ]);
+    return llmProvider;
+}
+async function configureProvider(llmProvider, options, nonInteractive, ollamaModels) {
+    if (llmProvider === 'grok') {
+        const runtimeGrokKey = getRuntimeGrokKey();
+        if (options.apiKey?.trim()) {
+            return { apiKey: options.apiKey.trim() };
+        }
+        if (nonInteractive) {
+            if (!runtimeGrokKey) {
+                throw new Error('Grok selected but no key provided. Set --apiKey or TERMINUS_GROK_API_KEY/XAI_API_KEY.');
+            }
+            return { apiKey: '__ENV__' };
+        }
+        if (runtimeGrokKey) {
+            const { useRuntimeKey } = await inquirer.prompt([
+                {
+                    type: 'confirm',
+                    name: 'useRuntimeKey',
+                    message: 'Use Grok API key from runtime environment (recommended)?',
+                    default: true,
+                },
+            ]);
+            if (useRuntimeKey) {
+                return { apiKey: '__ENV__' };
+            }
+        }
+        const { key } = await inquirer.prompt([
+            {
+                type: 'password',
+                name: 'key',
+                message: 'Grok API key (xai-...):',
+                mask: '•',
+                validate: (input) => {
+                    if (!input)
+                        return 'API key is required';
+                    if (!input.startsWith('xai-'))
+                        return 'Grok API keys start with "xai-"';
+                    if (input.length < 20)
+                        return 'API key looks too short';
+                    return true;
+                },
+            },
+        ]);
+        return { apiKey: key.trim() };
+    }
+    if (llmProvider === 'ollama') {
+        const defaultBaseUrl = options.llmBaseUrl || 'http://localhost:11434';
+        const defaultModel = options.llmModel || ollamaModels[0] || 'llama3';
+        if (nonInteractive) {
+            return {
+                apiKey: '',
+                llmBaseUrl: defaultBaseUrl,
+                llmModel: defaultModel,
+            };
+        }
+        const answers = await inquirer.prompt([
+            {
+                type: 'input',
+                name: 'baseUrl',
+                message: 'Ollama server URL:',
+                default: defaultBaseUrl,
+            },
+            {
+                type: ollamaModels.length > 0 ? 'list' : 'input',
+                name: 'model',
+                message: ollamaModels.length > 0 ? 'Select model:' : 'Enter model name:',
+                choices: ollamaModels.length > 0 ? ollamaModels : undefined,
+                default: defaultModel,
+            },
+        ]);
+        return {
+            apiKey: '',
+            llmBaseUrl: String(answers.baseUrl),
+            llmModel: String(answers.model),
+        };
+    }
+    const defaultBaseUrl = options.llmBaseUrl || 'http://localhost:1234';
+    const defaultModel = options.llmModel || 'local-model';
+    const defaultApiKey = options.apiKey?.trim() || '';
+    if (nonInteractive) {
+        return {
+            apiKey: defaultApiKey,
+            llmBaseUrl: defaultBaseUrl,
+            llmModel: defaultModel,
+        };
+    }
+    const answers = await inquirer.prompt([
+        {
+            type: 'input',
+            name: 'baseUrl',
+            message: 'OpenAI-compatible server URL:',
+            default: defaultBaseUrl,
+        },
+        {
+            type: 'input',
+            name: 'model',
+            message: 'Model name:',
+            default: defaultModel,
+        },
+        {
+            type: 'password',
+            name: 'apiKey',
+            message: 'API key (optional):',
+            mask: '•',
+            default: defaultApiKey,
+        },
+    ]);
+    return {
+        apiKey: String(answers.apiKey || '').trim(),
+        llmBaseUrl: String(answers.baseUrl),
+        llmModel: String(answers.model),
+    };
+}
+async function selectNetworkProfile(initialValue, nonInteractive) {
+    if (initialValue)
+        return initialValue;
+    if (nonInteractive)
+        return 'testnet';
+    const { profile } = await inquirer.prompt([
+        {
+            type: 'list',
+            name: 'profile',
+            message: 'Target network:',
+            choices: [
+                { name: 'Testnet (Base Sepolia)', value: 'testnet' },
+                { name: 'Mainnet (Base)', value: 'mainnet' },
+                { name: 'Local Development', value: 'local' },
+            ],
+            default: 'testnet',
+        },
+    ]);
+    return profile;
+}
+async function selectControlPlaneUrl(profile, initialValue, nonInteractive) {
+    const defaultUrl = initialValue?.trim() || NETWORK_URL_PRESETS[profile];
+    if (nonInteractive) {
+        if (!isWsUrl(defaultUrl)) {
+            throw new Error('controlPlaneUrl must start with ws:// or wss://');
+        }
+        if (profile === 'mainnet' && !defaultUrl.startsWith('wss://')) {
+            throw new Error('Mainnet profile requires wss:// control-plane URL.');
+        }
+        return defaultUrl;
+    }
+    const { controlPlaneUrl } = await inquirer.prompt([
+        {
+            type: 'input',
+            name: 'controlPlaneUrl',
+            message: 'Control Plane URL:',
+            default: defaultUrl,
+            validate: (input) => {
+                if (!isWsUrl(input))
+                    return 'URL must start with ws:// or wss://';
+                if (profile === 'mainnet' && !input.startsWith('wss://')) {
+                    return 'Mainnet requires wss://';
+                }
+                return true;
+            },
+        },
+    ]);
+    return String(controlPlaneUrl);
+}
+export async function initCommand(rawOptions = {}) {
+    const options = {
+        ...rawOptions,
+        llmProvider: normalizeProvider(rawOptions.llmProvider),
+        profile: normalizeProfile(rawOptions.profile),
+    };
+    const nonInteractive = options.yes === true;
+    printBanner();
+    if (configExists()) {
+        const existing = loadConfig();
+        console.log(chalk.yellow('Existing configuration detected.\n'));
+        if (existing) {
+            printInfo('Agent', existing.agentType);
+            printInfo('Wallet', existing.wallet);
+            printInfo('Provider', existing.llmProvider || 'grok');
+            printInfo('Network', NETWORK_LABELS[existing.networkProfile || 'local']);
+        }
+        console.log();
+        const shouldOverwrite = options.force === true || nonInteractive
+            ? true
+            : (await inquirer.prompt([
+                {
+                    type: 'confirm',
+                    name: 'overwrite',
+                    message: 'Overwrite existing configuration?',
+                    default: false,
+                },
+            ])).overwrite;
+        if (!shouldOverwrite) {
+            console.log(chalk.gray('\nSetup cancelled.\n'));
+            return;
+        }
+    }
+    console.log(chalk.gray('Checking local LLM availability...'));
+    const ollamaAvailable = await checkOllamaAvailable();
+    const ollamaModels = ollamaAvailable ? await listOllamaModels() : [];
+    if (ollamaAvailable) {
+        console.log(chalk.green(`✓ Ollama detected (${ollamaModels.length} models)`));
+    }
+    else {
+        console.log(chalk.gray('○ Ollama not detected'));
+    }
+    console.log();
+    const agentType = await promptForAgentType(options.agentType, nonInteractive);
+    const wallet = await promptForWallet(options.wallet, nonInteractive);
+    const llmProvider = await promptForProvider(options.llmProvider, nonInteractive);
+    const providerConfig = await configureProvider(llmProvider, options, nonInteractive, ollamaModels);
+    const profile = await selectNetworkProfile(options.profile, nonInteractive);
+    const controlPlaneUrl = await selectControlPlaneUrl(profile, options.controlPlaneUrl, nonInteractive);
+    const nodeId = generateNodeId(agentType, wallet);
+    const config = {
+        agentType,
+        wallet,
+        apiKey: providerConfig.apiKey,
+        controlPlaneUrl,
+        nodeId,
+        llmProvider,
+        llmBaseUrl: providerConfig.llmBaseUrl,
+        llmModel: providerConfig.llmModel,
+        networkProfile: profile,
+    };
+    saveConfig(config);
+    const selectedAgent = AGENTS.find((item) => item.id === agentType);
+    console.log(chalk.green.bold('\nSetup complete.\n'));
+    printInfo('Agent', `${AGENT_EMOJIS[agentType] || '🤖'} ${selectedAgent?.name || agentType}`);
+    printInfo('Node ID', nodeId);
+    printInfo('Wallet', `${wallet.slice(0, 10)}...${wallet.slice(-8)}`);
+    printInfo('Provider', llmProvider);
+    if (providerConfig.llmModel) {
+        printInfo('Model', providerConfig.llmModel);
+    }
+    printInfo('Profile', NETWORK_LABELS[profile]);
+    printInfo('Control Plane', controlPlaneUrl);
+    printInfo('Config File', getConfigPath());
+    console.log();
+    console.log(chalk.yellow('Important: set TERMINUS_WALLET_PRIVATE_KEY in your shell before running.'));
+    console.log(chalk.cyan('  export TERMINUS_WALLET_PRIVATE_KEY=0x...'));
+    if (llmProvider === 'grok' && providerConfig.apiKey === '__ENV__') {
+        console.log(chalk.yellow('Important: Grok key will be read from TERMINUS_GROK_API_KEY or XAI_API_KEY.'));
+    }
+    console.log(chalk.cyan('\nNext steps:'));
+    console.log(chalk.cyan('  npx terminus-agent doctor'));
+    console.log(chalk.cyan('  npx terminus-agent run\n'));
+    // Ensure options are not silently ignored in strict mode.
+    if (nonInteractive) {
+        must(config.agentType, 'agentType is required');
+        must(config.wallet, 'wallet is required');
+        must(config.llmProvider, 'llmProvider is required');
+        must(config.controlPlaneUrl, 'controlPlaneUrl is required');
+    }
+}

package/dist/cli/run.d.ts

@@ -0,0 +1 @@
+export declare function runCommand(): Promise<void>;