twinclaw 1.2.0 → 1.2.1

package/dist/config/model-catalog.js

@@ -295,7 +295,7 @@ export const PROVIDER_INFO = {
     },
     modal: {
         name: 'Modal',
-        baseURL: 'https://api.us-west-2.modal.direct/v1/chat/completions',
+        baseURL: 'https://api.us-west-2.modal.direct/v1',
         apiKeyEnvName: 'MODAL_API_KEY',
         supportsVision: false
     },

package/dist/core/cli.js

@@ -37,17 +37,21 @@ export const handleHelpCli = async (argv) => {
             {
                 title: 'Commands',
                 content: {
-                    'twinclaw': 'Start the TwinClaw gateway (default)',
+                    'twinclaw': 'Start TwinClaw (default - runs onboarding first time)',
+                    'start': 'Start gateway in new terminal window',
+                    'start --current': 'Start gateway in current terminal',
+                    'chat': 'Start gateway with interactive chat REPL',
+                    'stop': 'Stop the gateway',
                     'status': 'Show system status and health overview',
                     'doctor': 'Run diagnostics and validate prerequisites',
                     'onboard': 'Run the interactive onboarding wizard',
-                    'setup': "Alias of 'onboard'",
+                    'persona': 'Manage the agent core persona (soul, identity, user)',
                     'pairing': 'Manage DM pairing approvals',
                     'secret': 'Manage secrets in the secure vault',
+                    'config': 'Manage all configuration (API keys, channels, models)',
                     'channels': 'Manage messaging channels (Telegram/WhatsApp)',
                     'gateway': 'Manage the TwinClaw background service',
                     'logs': 'View gateway logs',
-                    'config': 'Configuration management',
                     'queue': 'Message queue status',
                     'update': 'Check for and install latest version',
                     'self': 'Self-improving agent commands',
@@ -163,25 +167,31 @@ export const handleVersionCli = async (argv) => {
     return 0;
 };
 /**
- * Handle the `start` command.
- * Starts the gateway in a new terminal window.
+ * Handle the `start` and `chat` commands.
+ * - `start` - starts gateway in a new terminal window (default)
+ * - `start --current` - starts gateway in current terminal
+ * - `chat` - starts gateway with chat REPL immediately
  */
-export const handleStartCli = async (argv, isChatMode = false) => {
-    if (isChatMode) {
+export const handleStartCli = async (argv) => {
+    const command = argv[0];
+    const isChat = command === 'chat';
+    const runInCurrentTerminal = argv.includes('--current');
+    if (isChat) {
         global.TWINCLAW_CHAT_MODE = true;
     }
-    if (process.platform === 'win32') {
+    if (process.platform === 'win32' && !runInCurrentTerminal) {
         const { spawn } = await import('node:child_process');
-        console.log('[TwinClaw] Starting gateway in new window...');
         const entryScript = process.execPath;
-        const appPath = process.argv[1] || process.argv[0];
+        console.log('[TwinClaw] Starting gateway in new window...');
+        const targetCmd = isChat ? 'chat' : '';
+        const title = isChat ? 'TwinClaw Chat' : 'TwinClaw Gateway';
         const args = [
             '/c',
             'start',
-            '""',
+            `""`,
             'cmd.exe',
             '/k',
-            `"${entryScript}" chat`
+            targetCmd ? `"${entryScript}" ${targetCmd}` : `"${entryScript}"`
         ];
         spawn('cmd.exe', args, {
             detached: true,
@@ -192,6 +202,10 @@ export const handleStartCli = async (argv, isChatMode = false) => {
         console.log('[TwinClaw] You can now use this terminal for other commands.');
         return 0;
     }
+    // For --current flag or non-Windows, return 0 to let main() continue with gateway startup
+    if (runInCurrentTerminal) {
+        console.log('[TwinClaw] Running gateway in current terminal...');
+    }
     return 0;
 };
 /**
@@ -249,7 +263,7 @@ export function handleUnknownCommand(argv) {
         'secret',
         'doctor',
         'onboard',
-        'setup',
+        'persona',
         'channels',
         'gateway',
         'logs',
@@ -269,8 +283,8 @@ export function handleUnknownCommand(argv) {
     }
     // Suggest closest matching command
     const suggestions = {
-        'start': 'gateway start',
-        'stop': 'gateway stop',
+        'start': 'start (new terminal) or start --current',
+        'stop': 'stop',
         'staus': 'status',
         'statys': 'status',
         'hel': 'help',
@@ -283,7 +297,10 @@ export function handleUnknownCommand(argv) {
         'telegram': 'channels status',
         'log': 'logs',
         'pair': 'pairing list',
-        'update': 'update'
+        'onboard': 'onboard',
+        'setup': 'onboard',
+        'update': 'update',
+        'config': 'config (manage all settings)'
     };
     const lowerCommand = command.toLowerCase();
     let suggestion = '';

package/dist/core/config-cli.js

@@ -0,0 +1,171 @@
+import { handleOnboardCliV2 } from './onboarding.js';
+import { handleDoctorCli } from './cli.js';
+import { readConfig } from '../config/json-config.js';
+function printConfigHelp() {
+    console.log(`
+TwinClaw Configuration Manager
+================================
+
+Usage: twinclaw config [command]
+
+Commands:
+  edit              Open interactive configuration editor
+  show              Show current configuration
+  api               Manage API keys (openrouter, gemini, groq, modal, github)
+  channel           Manage messaging channels (telegram, whatsapp)
+  model             Manage AI models
+  doctor            Run diagnostics
+  reset             Reset configuration and run onboarding again
+
+Examples:
+  twinclaw config edit          # Interactive editor
+  twinclaw config show          # View current config
+  twinclaw config api           # Manage API keys
+  twinclaw config channel       # Manage channels
+  twinclaw config model         # Manage models
+  twinclaw config doctor        # Run diagnostics
+  twinclaw config reset         # Reset and re-onboard
+`);
+}
+async function showConfig() {
+    try {
+        const config = await readConfig();
+        console.log('\n=== TwinClaw Current Configuration ===\n');
+        console.log('Runtime:');
+        console.log(`  API Port: ${config.runtime.apiPort}`);
+        console.log(`  API Secret: ${config.runtime.apiSecret ? '***set***' : '***not set***'}`);
+        console.log('\nModels:');
+        console.log(`  Primary: ${config.models.primaryModel || '***not set***'}`);
+        console.log(`  Definitions: ${config.models.definitions?.length || 0} model(s) configured`);
+        if (config.models.openRouterApiKey)
+            console.log(`  OpenRouter: ***set***`);
+        if (config.models.modalApiKey)
+            console.log(`  Modal: ***set***`);
+        if (config.models.geminiApiKey)
+            console.log(`  Gemini: ***set***`);
+        if (config.models.githubToken)
+            console.log(`  GitHub: ***set***`);
+        console.log('\nMessaging:');
+        console.log(`  Telegram: ${config.messaging.telegram.enabled ? 'enabled' : 'disabled'}`);
+        if (config.messaging.telegram.botToken)
+            console.log(`    Bot Token: ***set***`);
+        if (config.messaging.telegram.userId)
+            console.log(`    User ID: ${config.messaging.telegram.userId}`);
+        console.log(`  WhatsApp: ${config.messaging.whatsapp.enabled ? 'enabled' : 'disabled'}`);
+        if (config.messaging.whatsapp.phoneNumber)
+            console.log(`    Phone: ${config.messaging.whatsapp.phoneNumber}`);
+        console.log('\nChannels (allowFrom):');
+        console.log(`  Telegram: ${config.messaging.telegram.allowFrom.join(', ') || 'none'}`);
+        console.log(`  WhatsApp: ${config.messaging.whatsapp.allowFrom.join(', ') || 'none'}`);
+        console.log('');
+        return 0;
+    }
+    catch (err) {
+        console.error('Failed to read config:', err);
+        return 1;
+    }
+}
+async function manageApiKeys() {
+    console.log(`
+API Key Management
+==================
+
+Available providers:
+  openrouter   - OpenRouter API key
+  modal        - Modal API key  
+  gemini       - Google Gemini API key
+  groq         - Groq API key
+  github       - GitHub Token (for Copilot/Models)
+
+Usage: twinclaw config api [provider] [value]
+
+Examples:
+  twinclaw config api openrouter sk-xxxxx
+  twinclaw config api gemini xxxxx
+  twinclaw config api                 # View current keys
+`);
+    return 0;
+}
+async function manageChannel() {
+    console.log(`
+Channel Management
+==================
+
+Usage: twinclaw channels [command]
+
+Examples:
+  twinclaw channels status          # Show channel status
+  twinclaw channels login telegram  # Login to Telegram
+  twinclaw channels login whatsapp  # Login to WhatsApp
+
+Or run: twinclaw channels
+`);
+    return 0;
+}
+async function manageModels() {
+    console.log(`
+Model Management
+================
+
+Current models:
+`);
+    try {
+        const config = await readConfig();
+        if (config.models.definitions && config.models.definitions.length > 0) {
+            for (const def of config.models.definitions) {
+                console.log(`  - ${def.provider}/${def.model}`);
+            }
+        }
+        else {
+            console.log('  No models configured');
+        }
+        console.log(`\nPrimary: ${config.models.primaryModel || 'not set'}`);
+    }
+    catch (err) {
+        console.log('  (Could not read models)');
+    }
+    console.log(`
+To change models, run: twinclaw onboard
+`);
+    return 0;
+}
+async function resetConfig() {
+    console.log('[TwinClaw] Resetting configuration...');
+    console.log('[TwinClaw] This will delete your config and run onboarding again.');
+    console.log('[TwinClaw] Note: This feature requires manual config deletion.');
+    console.log('\nTo reset, delete your config file and run:');
+    console.log('  twinclaw onboard');
+    return 0;
+}
+export const handleConfigCli = async (argv) => {
+    const subcommand = argv[1];
+    if (!subcommand || subcommand === 'help' || argv.includes('--help')) {
+        printConfigHelp();
+        return 0;
+    }
+    switch (subcommand) {
+        case 'show':
+        case 'view':
+            return await showConfig();
+        case 'edit':
+        case 'wizard':
+            return await handleOnboardCliV2(['onboard']);
+        case 'api':
+        case 'keys':
+            return await manageApiKeys();
+        case 'channel':
+        case 'channels':
+            return await manageChannel();
+        case 'model':
+        case 'models':
+            return await manageModels();
+        case 'doctor':
+            return await handleDoctorCli(['doctor']);
+        case 'reset':
+            return await resetConfig();
+        default:
+            console.error(`Unknown config command: ${subcommand}`);
+            printConfigHelp();
+            return 1;
+    }
+};

package/dist/core/onboarding.js

@@ -14,14 +14,256 @@ const rl = readline.createInterface({
     input: process.stdin,
     output: process.stdout,
 });
+const REPL_COMMANDS = [
+    { cmd: '/help', desc: 'Show all commands' },
+    { cmd: '/status', desc: 'Show gateway status' },
+    { cmd: '/models', desc: 'Show configured models' },
+    { cmd: '/model set <name>', desc: 'Set primary model (e.g., /model set modal)' },
+    { cmd: '/model list', desc: 'List available models in catalog' },
+    { cmd: '/keys', desc: 'Show API keys status' },
+    { cmd: '/key set <provider> <key>', desc: 'Set API key (e.g., /key set modal sk-xxx)' },
+    { cmd: '/channel', desc: 'Show messaging channels status' },
+    { cmd: '/channel telegram', desc: 'Configure Telegram settings' },
+    { cmd: '/channel whatsapp', desc: 'Configure WhatsApp settings' },
+    { cmd: '/persona', desc: 'Show current persona' },
+    { cmd: '/persona edit <soul|identity|user> <text>', desc: 'Edit persona' },
+    { cmd: '/doctor', desc: 'Run diagnostics' },
+    { cmd: '/config', desc: 'Open configuration menu' },
+    { cmd: '/clear', desc: 'Clear conversation' },
+    { cmd: '/quit', desc: 'Exit chat mode' },
+];
+function showReplHelp() {
+    console.log('\n╔═══════════════════════════════════════════╗');
+    console.log('║         TwinClaw Chat Commands            ║');
+    console.log('╠═══════════════════════════════════════════╣');
+    for (const c of REPL_COMMANDS) {
+        console.log(`║ ${c.cmd.padEnd(35)} ║`);
+        console.log(`║   ${c.desc.padEnd(33)} ║`);
+        console.log('║                                          ║');
+    }
+    console.log('╚═══════════════════════════════════════════╝\n');
+}
+async function showConfigStatus() {
+    try {
+        const { readConfig } = await import('../config/json-config.js');
+        const config = await readConfig();
+        console.log('\n╔═══════════════════════════════════════════╗');
+        console.log('║         Current Configuration            ║');
+        console.log('╠═══════════════════════════════════════════╣');
+        console.log(`║ Runtime                                      ║`);
+        console.log(`║   API Port: ${config.runtime.apiPort}                        ║`);
+        console.log(`║                                              ║`);
+        console.log(`║ Models                                       ║`);
+        console.log(`║   Primary: ${(config.models.primaryModel || 'not set').padEnd(25)} ║`);
+        if (config.models.definitions?.length) {
+            console.log(`║   Defined: ${config.models.definitions.length} models                         ║`);
+        }
+        console.log(`║                                              ║`);
+        console.log(`║ API Keys                                     ║`);
+        console.log(`║   Modal: ${config.models.modalApiKey ? '***set***' : 'not set'.padEnd(22)} ║`);
+        console.log(`║   OpenRouter: ${config.models.openRouterApiKey ? '***set***' : 'not set'.padEnd(17)} ║`);
+        console.log(`║   Gemini: ${config.models.geminiApiKey ? '***set***' : 'not set'.padEnd(21)} ║`);
+        console.log(`║   Groq: ${config.messaging.voice.groqApiKey ? '***set***' : 'not set'.padEnd(24)} ║`);
+        console.log(`║   GitHub: ${config.models.githubToken ? '***set***' : 'not set'.padEnd(21)} ║`);
+        console.log(`║                                              ║`);
+        console.log(`║ Channels                                     ║`);
+        console.log(`║   Telegram: ${config.messaging.telegram.enabled ? 'enabled' : 'disabled'.padEnd(19)} ║`);
+        console.log(`║   WhatsApp: ${config.messaging.whatsapp.enabled ? 'enabled' : 'disabled'.padEnd(18)} ║`);
+        console.log('╚═══════════════════════════════════════════╝\n');
+    }
+    catch (err) {
+        console.log('Error loading config:', err);
+    }
+}
+async function showModelStatus() {
+    try {
+        const { readConfig } = await import('../config/json-config.js');
+        const config = await readConfig();
+        console.log('\n--- Models ---');
+        console.log(`Primary: ${config.models.primaryModel || 'not set'}`);
+        if (config.models.definitions?.length) {
+            console.log('\nConfigured Models:');
+            for (const def of config.models.definitions) {
+                const isPrimary = def.model === config.models.primaryModel ? ' *' : '';
+                console.log(`  - ${def.provider}/${def.model}${isPrimary}`);
+            }
+        }
+        console.log('\nTo change: /model set <provider/model>');
+        console.log('-----------\n');
+    }
+    catch (err) {
+        console.log('Error:', err);
+    }
+}
+async function setModel(modelArg) {
+    if (!modelArg) {
+        console.log('\nUsage: /model set <model-id>\n');
+        console.log('Examples:');
+        console.log('  /model set modal');
+        console.log('  /model set openai/gpt-4o');
+        console.log('  /model set anthropic/claude-3-sonnet');
+        return;
+    }
+    try {
+        const { readConfig, writeConfig } = await import('../config/json-config.js');
+        const config = await readConfig();
+        config.models.primaryModel = modelArg;
+        await writeConfig(config);
+        console.log(`\n✅ Primary model set to: ${modelArg}\n`);
+    }
+    catch (err) {
+        console.log('Error setting model:', err);
+    }
+}
+async function setApiKey(provider, key) {
+    if (!provider || !key) {
+        console.log('\nUsage: /key set <provider> <api-key>');
+        console.log('\nProviders: modal, openrouter, gemini, groq, github');
+        console.log('\nExample: /key set modal sk-xxxxx');
+        return;
+    }
+    try {
+        const { readConfig, writeConfig } = await import('../config/json-config.js');
+        const config = await readConfig();
+        const keyLower = provider.toLowerCase();
+        if (keyLower === 'modal')
+            config.models.modalApiKey = key;
+        else if (keyLower === 'openrouter')
+            config.models.openRouterApiKey = key;
+        else if (keyLower === 'gemini')
+            config.models.geminiApiKey = key;
+        else if (keyLower === 'groq')
+            config.messaging.voice.groqApiKey = key;
+        else if (keyLower === 'github')
+            config.models.githubToken = key;
+        else {
+            console.log(`Unknown provider: ${provider}`);
+            console.log('Valid providers: modal, openrouter, gemini, groq, github');
+            return;
+        }
+        await writeConfig(config);
+        console.log(`\n✅ ${provider} API key updated\n`);
+    }
+    catch (err) {
+        console.log('Error setting key:', err);
+    }
+}
+async function showChannelStatus() {
+    try {
+        const { readConfig } = await import('../config/json-config.js');
+        const config = await readConfig();
+        console.log('\n--- Messaging Channels ---');
+        console.log(`Telegram: ${config.messaging.telegram.enabled ? 'enabled' : 'disabled'}`);
+        if (config.messaging.telegram.enabled) {
+            console.log(`  Bot Token: ${config.messaging.telegram.botToken ? '***set***' : 'not set'}`);
+            console.log(`  User ID: ${config.messaging.telegram.userId || 'not set'}`);
+            console.log(`  Allow From: ${config.messaging.telegram.allowFrom.join(', ') || 'none'}`);
+        }
+        console.log(`\nWhatsApp: ${config.messaging.whatsapp.enabled ? 'enabled' : 'disabled'}`);
+        if (config.messaging.whatsapp.enabled) {
+            console.log(`  Phone: ${config.messaging.whatsapp.phoneNumber || 'not set'}`);
+            console.log(`  Allow From: ${config.messaging.whatsapp.allowFrom.join(', ') || 'none'}`);
+        }
+        console.log('\nTo configure: twinclaw channels');
+        console.log('--------------\n');
+    }
+    catch (err) {
+        console.log('Error:', err);
+    }
+}
+function handleReplCommand(line, gateway, sessionId) {
+    const parts = line.trim().split(/\s+/);
+    const cmd = parts[0].toLowerCase();
+    const args = parts.slice(1).join(' ');
+    switch (cmd) {
+        case '/help':
+            showReplHelp();
+            return true;
+        case '/status':
+            console.log('\n--- Gateway Status ---');
+            console.log('Status: Running ✅');
+            console.log('Session:', sessionId);
+            console.log('----------------------\n');
+            return true;
+        case '/models':
+        case '/model':
+            if (args.startsWith('set ')) {
+                setModel(args.substring(4).trim());
+            }
+            else if (args === 'list') {
+                console.log('\n--- Model Catalog ---');
+                console.log('Use twinclaw config model to view full catalog');
+                console.log('--------------------\n');
+            }
+            else {
+                showModelStatus();
+            }
+            return true;
+        case '/keys':
+        case '/key':
+            if (args.startsWith('set ')) {
+                const keyParts = args.substring(4).trim().split(/\s+/);
+                if (keyParts.length >= 2) {
+                    setApiKey(keyParts[0], keyParts.slice(1).join(' '));
+                }
+                else {
+                    console.log('\nUsage: /key set <provider> <api-key>\n');
+                }
+            }
+            else {
+                showConfigStatus();
+            }
+            return true;
+        case '/channel':
+        case '/channels':
+            showChannelStatus();
+            return true;
+        case '/persona':
+            console.log('\nTo view/edit persona, use: twinclaw persona');
+            console.log('To edit in chat: /persona edit <soul|identity|user> <text>');
+            console.log('--------------\n');
+            return true;
+        case '/doctor':
+            console.log('\nRunning diagnostics...\n');
+            console.log('Use: twinclaw doctor');
+            console.log('------\n');
+            return true;
+        case '/config':
+            console.log('\n--- Configuration Menu ---');
+            console.log('Commands:');
+            console.log('  /config show     - Show full config');
+            console.log('  /config edit    - Open interactive editor');
+            console.log('  /model set <id> - Change primary model');
+            console.log('  /key set <prov> <key> - Set API key');
+            console.log('------------------------\n');
+            return true;
+        case '/clear':
+            console.log('\nConversation cleared.\n');
+            return true;
+        case '/quit':
+            console.log('\nExiting chat mode. Use Ctrl+C to exit.\n');
+            return true;
+        default:
+            return false;
+    }
+}
 export function startBasicREPL(gateway) {
     console.log('TwinClaw basic REPL started.');
+    console.log('Type /help for available commands.\n');
     void logThought('Basic REPL started.');
     const sessionId = 'default_repl';
     createSession(sessionId);
     rl.on('line', async (line) => {
+        if (!line.trim())
+            return;
         await logThought(`REPL input received (${line.length} chars).`);
         try {
+            // Handle / commands
+            if (line.trim().startsWith('/')) {
+                if (handleReplCommand(line, gateway, sessionId)) {
+                    return;
+                }
+            }
             const responseText = await gateway.processText(sessionId, line);
             console.log(`\nTwinClaw: ${responseText}\n`);
         }

package/dist/core/persona-cli.js

@@ -9,12 +9,16 @@ export const handlePersonaCli = async (argv) => {
     const subcommand = argv[1];
     if (!subcommand || subcommand === 'show' || subcommand === 'view') {
         const state = await service.getState();
-        console.log(', TwinClaw, Persona, State, ');, console.log('──────────────────────────────────────────────────'));
+        console.log('TwinClaw Persona State');
+        console.log('──────────────────────────────────────────────────');
         console.log(`Revision: ${state.revision}`);
         console.log(`Updated:  ${state.updatedAt}`);
-        console.log(', -- - SOUL-- - ');, console.log(state.soul || '(empty)'));
-        console.log(', -- - IDENTITY-- - ');, console.log(state.identity || '(empty)'));
-        console.log(', -- - USER, CONTEXT-- - ');, console.log(state.user || '(empty)'));
+        console.log('--- SOUL ---');
+        console.log(state.soul || '(empty)');
+        console.log('--- IDENTITY ---');
+        console.log(state.identity || '(empty)');
+        console.log('--- USER CONTEXT ---');
+        console.log(state.user || '(empty)');
         return 0;
     }
     if (subcommand === 'edit' || subcommand === 'update') {

package/dist/index.js

@@ -31,10 +31,12 @@ import { validatePreStartConfig } from './config/prestart-validation.js';
 import { getIdentityDir, getWorkspaceSubdir } from './config/workspace.js';
 import { handleSecretVaultCli } from './core/secret-vault-cli.js';
 import { handlePairingCli } from './core/pairing-cli.js';
-import { handleChannelsCli } from './core/channels-cli.js';
 import { handleGatewayCli } from './core/gateway-cli.js';
 import { handleLogsCli } from './core/logs-cli.js';
 import { handleQueueCli } from './core/queue-cli.js';
+import { handleConfigCli } from './core/config-cli.js';
+import { handlePersonaCli } from './core/persona-cli.js';
+import { handleChannelsCli } from './core/channels-cli.js';
 import { getDmPairingService } from './services/dm-pairing.js';
 import { randomUUID } from 'node:crypto';
 import { initializeSelfHealer, getSelfHealingService } from './services/self-healing.js';
@@ -58,22 +60,22 @@ const CLI_HANDLER_PRIORITY = {
     STATUS: 10,
 };
 const handleSecretCommandCli = async (args) => handleSecretVaultCli(['secret', ...args.slice(1)], secretVault) ? 0 : 1;
-const handleConfigCommandCli = async (args) => handleSecretVaultCli(['config', ...args.slice(1)], secretVault) ? 0 : 1;
 const CLI_HANDLERS = [
     { command: 'help', handler: handleHelpCli, priority: CLI_HANDLER_PRIORITY.HELP, description: 'Show help' },
     { command: 'self', handler: handleSelfImproveCli, priority: CLI_HANDLER_PRIORITY.SELF, description: 'Self-improvement commands' },
     { command: 'doctor', handler: handleDoctorCli, priority: CLI_HANDLER_PRIORITY.DOCTOR, description: 'Run diagnostics' },
     { command: 'update', handler: handleUpdateCli, priority: CLI_HANDLER_PRIORITY.UPDATE, description: 'Check for updates' },
     { command: ['version', '--version', '-v'], handler: handleVersionCli, priority: CLI_HANDLER_PRIORITY.VERSION, description: 'Show version' },
-    { command: 'start', handler: handleStartCli, priority: CLI_HANDLER_PRIORITY.START_STOP, description: 'Start gateway' },
+    { command: 'start', handler: handleStartCli, priority: CLI_HANDLER_PRIORITY.START_STOP, description: 'Start gateway in new terminal' },
+    { command: 'chat', handler: handleStartCli, priority: CLI_HANDLER_PRIORITY.START_STOP, description: 'Start gateway with chat REPL' },
     { command: 'stop', handler: handleStopCli, priority: CLI_HANDLER_PRIORITY.START_STOP, description: 'Stop gateway' },
-    { command: 'chat', handler: async (args) => { return await handleStartCli(['start', ...args.slice(1)], true); }, priority: CLI_HANDLER_PRIORITY.START_STOP, description: 'Open terminal chat' },
     { command: 'secret', handler: handleSecretCommandCli, priority: CLI_HANDLER_PRIORITY.CONFIG, description: 'Manage secrets' },
-    { command: 'config', handler: handleConfigCommandCli, priority: CLI_HANDLER_PRIORITY.CONFIG, description: 'Validate runtime config' },
+    { command: 'config', handler: handleConfigCli, priority: CLI_HANDLER_PRIORITY.CONFIG, description: 'Manage configuration' },
     { command: 'pairing', handler: async (args) => { return await handlePairingCli(args, pairingService) ? 0 : 1; }, priority: CLI_HANDLER_PRIORITY.CONFIG, description: 'Manage pairings' },
-    { command: ['onboard', 'setup'], handler: handleOnboardCliV2, priority: CLI_HANDLER_PRIORITY.ONBOARDING, description: 'Run onboarding' },
+    { command: 'persona', handler: handlePersonaCli, priority: CLI_HANDLER_PRIORITY.CONFIG, description: 'Manage agent persona' },
+    { command: 'onboard', handler: handleOnboardCliV2, priority: CLI_HANDLER_PRIORITY.ONBOARDING, description: 'Run onboarding wizard' },
     { command: 'logs', handler: async (args) => { return await handleLogsCli(args) ? 0 : 1; }, priority: CLI_HANDLER_PRIORITY.OPERATIONS, description: 'View logs' },
-    { command: 'gateway', handler: async (args) => { return await handleGatewayCli(args) ? 0 : 1; }, priority: CLI_HANDLER_PRIORITY.OPERATIONS, description: 'Manage gateway' },
+    { command: 'gateway', handler: async (args) => { return await handleGatewayCli(args) ? 0 : 1; }, priority: CLI_HANDLER_PRIORITY.OPERATIONS, description: 'Manage gateway service' },
     { command: 'channels', handler: async (args) => { return await handleChannelsCli(args) ? 0 : 1; }, priority: CLI_HANDLER_PRIORITY.OPERATIONS, description: 'Manage channels' },
     { command: 'status', handler: handleStatusCli, priority: CLI_HANDLER_PRIORITY.STATUS, description: 'Show status' },
     { command: 'queue', handler: async (args) => { return await handleQueueCli(args) ? 0 : 1; }, priority: CLI_HANDLER_PRIORITY.STATUS, description: 'Manage queue' },
@@ -84,7 +86,7 @@ function printPreStartValidationFailure(issues) {
         console.error(`  [${issue.class}] [${issue.key}] ${issue.message}`);
         console.error(`    Remediation: ${issue.remediation}`);
     }
-    console.error("Run 'twinclaw onboard' to fix configuration, then retry.");
+    console.error("Run 'twinclaw onboard' (or 'twinclaw setup') to fix configuration, then retry.");
 }
 function assertWindowsOnlyRuntime() {
     if (process.platform === 'win32') {
@@ -129,12 +131,6 @@ async function main() {
     assertWindowsOnlyRuntime();
     const argv = process.argv.slice(2);
     const command = argv[0];
-    // Handle --onboard flag as a shortcut
-    if (argv.includes('--onboard')) {
-        const onboardingArgs = ['onboard', ...argv.filter(a => a !== '--onboard')];
-        const exitCode = await handleOnboardCliV2(onboardingArgs);
-        process.exit(exitCode);
-    }
     // Sort handlers by priority
     const sortedHandlers = [...CLI_HANDLERS].sort((a, b) => b.priority - a.priority);
     if (command) {

package/dist/interfaces/dispatcher.js

@@ -131,8 +131,30 @@ export class Dispatcher {
             await this.#dispatch(normalized, responseText);
         }
         catch (err) {
-            console.error('[Dispatcher] Unhandled error processing message:', err);
-            await logThought(`[Dispatcher] Unhandled error: ${err instanceof Error ? err.message : String(err)}`);
+            const errorMessage = err instanceof Error ? err.message : String(err);
+            console.error('[Dispatcher] Error processing message:', err);
+            let friendlyMessage = "Sorry, I encountered an error. Please try again.";
+            // Handle vision/image errors gracefully
+            if (errorMessage.includes('does not support image') ||
+                errorMessage.includes('image input') ||
+                errorMessage.includes('vision') ||
+                errorMessage.includes('Cannot read') ||
+                errorMessage.includes('does not support vision')) {
+                friendlyMessage = "⚠️ Sorry, I can't process images with my current model. Please try sending a text message instead.";
+            }
+            // Handle model exhaustion errors
+            else if (errorMessage.includes('all configured models exhausted') ||
+                errorMessage.includes('models exhausted') ||
+                errorMessage.includes('tool_call_id')) {
+                friendlyMessage = "⚠️ I'm having trouble with my AI models right now. Please try again in a moment, or check that your API keys are configured correctly.";
+            }
+            // Always try to send a response
+            try {
+                await this.#dispatch(message, friendlyMessage);
+            }
+            catch (dispatchErr) {
+                console.error('[Dispatcher] Failed to send error message:', dispatchErr);
+            }
         }
     }
     #resolveAccessConfig(channel, config) {

package/dist/interfaces/telegram_handler.js

@@ -3,6 +3,20 @@ import os from 'node:os';
 import path from 'node:path';
 /** Minimum ms delay between processing successive messages (human-like pacing). */
 const RATE_LIMIT_MS = 1500;
+const TELEGRAM_COMMANDS = [
+    { cmd: '/start', desc: 'Show welcome message and menu' },
+    { cmd: '/help', desc: 'Show all available commands' },
+    { cmd: '/status', desc: 'Show gateway status' },
+    { cmd: '/menu', desc: 'Show this menu' },
+    { cmd: '/models', desc: 'Show configured models' },
+    { cmd: '/model set', desc: 'Set primary model' },
+    { cmd: '/keys', desc: 'Show API keys status' },
+    { cmd: '/key set', desc: 'Set API key' },
+    { cmd: '/channel', desc: 'Show channel status' },
+    { cmd: '/persona', desc: 'Show persona' },
+    { cmd: '/doctor', desc: 'Run diagnostics' },
+    { cmd: '/clear', desc: 'Clear conversation' },
+];
 /**
  * Wraps the Telegram Bot API to provide:
  *   - Inbound message normalization for the dispatcher
@@ -62,13 +76,153 @@ export class TelegramHandler {
             }
             // Process text - this runs whether voice succeeded or failed
             if (msg.text || base.text) {
-                await this.onMessage?.({ ...base, text: msg.text || base.text });
+                const text = msg.text ?? base.text;
+                if (!text)
+                    return;
+                // Handle commands
+                if (text.trim().startsWith('/')) {
+                    const command = text.trim().split(' ')[0];
+                    await this.handleCommand(msg.chat.id, command);
+                    return;
+                }
+                await this.onMessage?.({ ...base, text });
             }
         });
         this.#bot.on('polling_error', (err) => {
             console.error('[TelegramHandler] Polling error:', err.message);
         });
     }
+    // ── Command Handlers ─────────────────────────────────────────────────────────
+    async handleCommand(chatId, command) {
+        const parts = command.toLowerCase().trim().split(/\s+/);
+        const cmd = parts[0];
+        const args = parts.slice(1).join(' ');
+        switch (cmd) {
+            case '/start':
+            case '/menu':
+                const menuText = `🎯 *TwinClaw Menu*
+        
+${TELEGRAM_COMMANDS.map(c => `${c.cmd} - ${c.desc}`).join('\n')}
+
+_How can I help you today?_
+`;
+                await this.#bot.sendMessage(chatId, menuText, { parse_mode: 'Markdown' });
+                break;
+            case '/help':
+                await this.#bot.sendMessage(chatId, `📋 *Available Commands:*
+
+${TELEGRAM_COMMANDS.map(c => `${c.cmd} - ${c.desc}`).join('\n')}
+
+_Just send me a message and I'll respond!_
+`, { parse_mode: 'Markdown' });
+                break;
+            case '/status':
+                await this.#bot.sendMessage(chatId, `✅ *Gateway Status:*
+
+• Status: Running
+• Platform: Telegram
+• Mode: AI Assistant
+
+_All systems operational_
+`, { parse_mode: 'Markdown' });
+                break;
+            case '/models':
+            case '/model':
+                if (args.startsWith('set ') && args.length > 4) {
+                    const modelId = args.substring(4).trim();
+                    await this.#bot.sendMessage(chatId, `To change model to *${modelId}*, run:\n\n\`/key set modal ${modelId}\`\n\n_Or use: twinclaw config edit_`, { parse_mode: 'Markdown' });
+                }
+                else {
+                    await this.#bot.sendMessage(chatId, `📦 *Models*
+
+Use *twinclaw config* to manage models.
+
+Commands:
+• /model list - List available models
+• /model set <id> - Set primary model
+
+_Or run: twinclaw config model_
+`, { parse_mode: 'Markdown' });
+                }
+                break;
+            case '/keys':
+            case '/key':
+                if (args.startsWith('set ') && args.length > 4) {
+                    const keyParts = args.substring(4).trim().split(/\s+/);
+                    if (keyParts.length >= 2) {
+                        const provider = keyParts[0];
+                        const key = keyParts.slice(1).join(' ');
+                        await this.#bot.sendMessage(chatId, `🔐 To set *${provider}* API key, run:\n\n\`twinclaw secret set ${provider.toUpperCase()}_API_KEY ${key}\`\n\n_Or use: twinclaw config edit_
+`, { parse_mode: 'Markdown' });
+                    }
+                    else {
+                        await this.#bot.sendMessage(chatId, `Usage: /key set <provider> <api-key>\n\nExample: /key set modal sk-xxxxx`);
+                    }
+                }
+                else {
+                    await this.#bot.sendMessage(chatId, `🔑 *API Keys*
+
+Use *twinclaw config* to manage API keys.
+
+Commands:
+• /keys show - Show key status
+• /key set <provider> <key> - Set API key
+
+_Or run: twinclaw config_
+`, { parse_mode: 'Markdown' });
+                }
+                break;
+            case '/channel':
+            case '/channels':
+                await this.#bot.sendMessage(chatId, `📱 *Channels*
+
+Telegram: ✅ Connected
+WhatsApp: Use /channels to configure
+
+Run: *twinclaw channels* to manage
+`, { parse_mode: 'Markdown' });
+                break;
+            case '/persona':
+                await this.#bot.sendMessage(chatId, `👤 *Persona*
+
+Run: *twinclaw persona* to view/edit
+
+Commands:
+• twinclaw persona show - View persona
+• twinclaw persona edit soul "text" - Edit soul
+`, { parse_mode: 'Markdown' });
+                break;
+            case '/doctor':
+                await this.#bot.sendMessage(chatId, `🩺 *Diagnostics*
+
+Run: *twinclaw doctor* to check system health
+
+Checks:
+• Environment variables
+• API keys
+• Configuration
+• Channels
+`, { parse_mode: 'Markdown' });
+                break;
+            case '/config':
+                await this.#bot.sendMessage(chatId, `⚙️ *Configuration*
+
+Use: *twinclaw config* to:
+• Edit configuration
+• Set API keys
+• Change models
+• Manage channels
+
+Run: *twinclaw config* in terminal
+`, { parse_mode: 'Markdown' });
+                break;
+            case '/clear':
+                await this.#bot.sendMessage(chatId, '🗑️ Conversation cleared! Starting fresh.');
+                break;
+            default:
+                await this.#bot.sendMessage(chatId, `Unknown command: ${command}\nType /menu for available commands.`);
+        }
+    }
     // ── Public Send Methods ───────────────────────────────────────────────────────
     /** Send a plain-text reply to a chat. */
     async sendText(chatId, text) {

package/dist/services/embedding-service.js

@@ -105,7 +105,8 @@ export class EmbeddingService {
         const secretVault = getSecretVaultService();
         const apiKey = secretVault.readSecret('EMBEDDING_API_KEY') ?? secretVault.readSecret('OPENAI_API_KEY') ?? '';
         if (!apiKey) {
-            throw new Error('Missing EMBEDDING_API_KEY or OPENAI_API_KEY.');
+            this.debugLog('[EmbeddingService] OpenAI: No API key configured, skipping.');
+            return [];
         }
         const endpoint = getConfigValue('EMBEDDING_API_URL') ?? DEFAULT_OPENAI_URL;
         const model = getConfigValue('EMBEDDING_MODEL') ?? DEFAULT_OPENAI_MODEL;
@@ -139,25 +140,35 @@ export class EmbeddingService {
         const baseUrl = getConfigValue('OLLAMA_BASE_URL') ?? DEFAULT_OLLAMA_URL;
         const model = getConfigValue('OLLAMA_EMBEDDING_MODEL') ?? DEFAULT_OLLAMA_MODEL;
         const endpoint = `${baseUrl.replace(/\/$/, '')}/api/embeddings`;
-        const response = await fetch(endpoint, {
-            method: 'POST',
-            headers: {
-                'Content-Type': 'application/json',
-            },
-            body: JSON.stringify({
-                model,
-                prompt: input,
-            }),
-        });
+        let response;
+        try {
+            response = await fetch(endpoint, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                },
+                body: JSON.stringify({
+                    model,
+                    prompt: input,
+                }),
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            this.debugLog(`[EmbeddingService] Ollama: Connection failed (${message}). Is Ollama running?`);
+            return [];
+        }
         if (!response.ok) {
-            throw new Error(`Ollama embeddings request failed (${response.status}).`);
+            this.debugLog(`[EmbeddingService] Ollama: Request failed (${response.status}).`);
+            return [];
         }
         const data = await response.json();
         const embedding = typeof data === 'object' && data !== null
             ? data.embedding
             : undefined;
         if (!isFiniteNumberArray(embedding)) {
-            throw new Error('Ollama embeddings response did not contain an embedding array.');
+            this.debugLog('[EmbeddingService] Ollama: Invalid response format.');
+            return [];
         }
         return embedding;
     }

package/dist/services/model-router.js

@@ -525,9 +525,22 @@ export class ModelRouter {
         this.trackUsageAttempt(input.config.id);
         this.recordEvent('attempt', input.config, `Attempting ${input.config.model} (profile=${input.directive.profile}, severity=${input.directive.severity}).`);
         const startedAt = this.nowFn();
+        const timeoutMs = 60000; // 60 second timeout
+        // For providers that don't support tools well, strip them from the request
+        const providerId = this.resolveProviderId(input.config);
+        const noToolProviders = ['stepfun', 'openrouter'];
+        let payload = input.payload;
+        if (noToolProviders.includes(providerId) && input.payload.tools) {
+            payload = { ...input.payload };
+            delete payload.tools;
+            delete payload.tool_choice;
+        }
         try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
             const response = await fetch(input.config.baseURL, {
                 method: 'POST',
+                signal: controller.signal,
                 headers: {
                     'Content-Type': 'application/json',
                     Authorization: `Bearer ${input.apiKey}`,
@@ -535,8 +548,9 @@ export class ModelRouter {
                         ? { 'HTTP-Referer': 'https://twinclaw.ai', 'X-Title': 'TwinClaw' }
                         : {}),
                 },
-                body: JSON.stringify(input.payload),
+                body: JSON.stringify(payload),
             });
+            clearTimeout(timeoutId);
             const latencyMs = this.nowFn() - startedAt;
             if (response.status === 429) {
                 const cooldownMs = parseRetryAfterMs(response.headers.get('retry-after')) ?? this.defaultRateLimitCooldownMs;
@@ -650,11 +664,24 @@ export class ModelRouter {
         this.trackUsageAttempt(input.config.id);
         this.recordEvent('attempt', input.config, `Attempting streaming ${input.config.model} (profile=${input.directive.profile}).`);
         const startedAt = this.nowFn();
+        const timeoutMs = 60000;
         const responseContentParts = [];
         const toolCalls = [];
+        // For providers that don't support tools well, strip them from the request
+        const providerId = this.resolveProviderId(input.config);
+        const noToolProviders = ['stepfun', 'openrouter'];
+        let payload = input.payload;
+        if (noToolProviders.includes(providerId) && input.payload.tools) {
+            payload = { ...input.payload };
+            delete payload.tools;
+            delete payload.tool_choice;
+        }
         try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
             const response = await fetch(input.config.baseURL, {
                 method: 'POST',
+                signal: controller.signal,
                 headers: {
                     'Content-Type': 'application/json',
                     Authorization: `Bearer ${input.apiKey}`,
@@ -662,8 +689,9 @@ export class ModelRouter {
                         ? { 'HTTP-Referer': 'https://twinclaw.ai', 'X-Title': 'TwinClaw' }
                         : {}),
                 },
-                body: JSON.stringify(input.payload),
+                body: JSON.stringify(payload),
             });
+            clearTimeout(timeoutId);
             if (response.status === 429) {
                 const cooldownMs = parseRetryAfterMs(response.headers.get('retry-after')) ?? this.defaultRateLimitCooldownMs;
                 this.#recordFailure(`429 Too Many Requests: ${input.config.model}`);
@@ -1058,7 +1086,7 @@ export class ModelRouter {
             configModels.push({
                 id: MODEL_SLOT_IDS.PRIMARY,
                 model: 'zai-org/GLM-5-FP8',
-                baseURL: modalInfo?.baseURL || 'https://api.us-west-2.modal.direct/v1/chat/completions',
+                baseURL: modalInfo?.baseURL || 'https://api.us-west-2.modal.direct/v1',
                 apiKeyEnvName: 'MODAL_API_KEY',
             });
         }
@@ -1085,7 +1113,7 @@ export class ModelRouter {
             configModels.push({
                 id: MODEL_SLOT_IDS.PRIMARY,
                 model: 'zai-org/GLM-5-FP8',
-                baseURL: modalInfo?.baseURL || 'https://api.us-west-2.modal.direct/v1/chat/completions',
+                baseURL: modalInfo?.baseURL || 'https://api.us-west-2.modal.direct/v1',
                 apiKeyEnvName: 'MODAL_API_KEY',
             });
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "twinclaw",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Eagle-eyed agentic AI gateway with multi-modal hooks and proactive memory.",
   "main": "dist/index.js",
   "bin": {