plazbot-cli 0.4.1 → 0.5.1

package/dist/commands/agent/monitor.js

@@ -1,8 +1,11 @@
-import { Command } from 'commander';
+import { Command, Option } from 'commander';
 import { Agent } from 'plazbot';
 import { getStoredCredentials } from '../../utils/credentials.js';
 import { logger } from '../../utils/logger.js';
-import { addExamples } from '../../utils/help.js';
+import { addExamples, addNotes } from '../../utils/help.js';
+import { jsonOption, fail, CliError } from '../../utils/output.js';
+import { describeAgentLoadError } from '../../utils/agent-errors.js';
+import { createApiClient } from '../../utils/api.js';
 import chalk from 'chalk';
 import readline from 'readline';
 import { HubConnectionBuilder, HttpTransportType, HubConnectionState } from '@microsoft/signalr';
@@ -48,8 +51,8 @@ function shortSession(sessionId) {
     return sessionId.substring(0, 6);
 }
 function renderLogLine(log, opts, lastSessionId) {
-    // Modo JSON crudo
-    if (opts.jsonMode) {
+    // Modo crudo: una linea JSON por evento
+    if (opts.raw) {
         return JSON.stringify(log);
     }
     const config = EVENT_COLORS[log.event_type] || DEFAULT_EVENT_COLOR;
@@ -102,38 +105,46 @@ const COMMANDS_HELP = `
   ${chalk.hex('#4CAF50')('/filter clear')}    Remove all filters
   ${chalk.hex('#4CAF50')('/filters')}         Show active filters
   ${chalk.hex('#4CAF50')('/clear')}           Clear screen
-  ${chalk.hex('#4CAF50')('/json')}            Toggle expanded JSON mode
+  ${chalk.hex('#4CAF50')('/raw')}             Toggle raw mode (one JSON object per event)
   ${chalk.hex('#4CAF50')('/help')}            Show these commands
 
   ${chalk.bold('Event types:')}
   ${Object.entries(EVENT_COLORS).map(([key, val]) => `  ${chalk.hex(val.color)('●')} ${key}`).join('\n')}
 `;
 export const monitorCommand = new Command('monitor')
-    .description('Real-time agent monitor (logs via SignalR)')
+    .description('Stream the activity of an agent in real time')
     .argument('<agentId>', 'Agent ID')
-    .option('-f, --filter <types>', 'Filter by comma-separated types (e.g. msg_in,msg_out)')
-    .option('--no-session', 'Hide session ID')
-    .option('--json', 'Raw JSON mode (for piping)', false)
-    .option('-w, --workspace <id>', 'Workspace ID (overrides local config)')
-    .option('-z, --zone <zone>', 'Zone LA or EU (overrides local config)')
+    .option('-f, --filter <types>', `Only show these comma-separated event types (${Object.keys(EVENT_COLORS).join(', ')})`)
+    .option('--no-session', 'Hide the short session ID on each line')
+    .addOption(jsonOption('Print one JSON object per event (JSON Lines) for piping'))
+    .addOption(new Option('-w, --workspace <id>', 'Workspace ID (overrides local config)').hideHelp())
+    .addOption(new Option('-z, --zone <zone>', 'Zone LA or EU (overrides local config)').hideHelp())
     .option('--dev', 'Use development environment', false)
     .action(async (agentId, options) => {
     try {
         const credentials = await getStoredCredentials();
         const effectiveWorkspace = options.workspace || credentials.workspace;
-        const effectiveZone = (options.zone?.toUpperCase() === 'EU' ? 'EU' : options.zone?.toUpperCase() === 'LA' ? 'LA' : credentials.zone);
+        const zoneOverride = options.zone?.toUpperCase();
+        if (zoneOverride && zoneOverride !== 'LA' && zoneOverride !== 'EU') {
+            throw new CliError(`Invalid zone "${options.zone}".`, 'invalid_zone', 'Use -z LA or -z EU.');
+        }
+        const effectiveZone = (zoneOverride || credentials.zone);
         const baseUrl = getBaseUrl(effectiveZone, options.dev);
+        // En modo --json todo lo que no es un evento va a stderr, para que stdout sea JSONL puro.
+        const status = (text) => (options.json ? process.stderr : process.stdout).write(text);
+        const statusLine = (text) => status(text + '\n');
         if (options.workspace || options.zone) {
-            console.log(chalk.hex('#FFA726')(`\n  Support mode: workspace=${effectiveWorkspace} zone=${effectiveZone}`));
+            status(chalk.hex('#FFA726')(`\n  Support mode: workspace=${effectiveWorkspace} zone=${effectiveZone}\n`));
         }
         // Filtros iniciales
         const activeFilters = new Set(options.filter ? options.filter.split(',').map(f => f.trim()) : []);
-        let jsonMode = options.json;
+        let rawMode = options.json;
         let lastSessionId = '';
-        // Cargar info del agente
+        // Cargar info del agente: si falla (ID, workspace o zona incorrectos) no se conecta,
+        // porque el monitor quedaria escuchando un agente que no existe sin mostrar nada.
         let agentName = 'Agent';
         try {
-            process.stdout.write(chalk.gray('  Connecting to agent...'));
+            status(chalk.gray('  Connecting to agent...'));
             const agent = new Agent({
                 workspaceId: effectiveWorkspace,
                 apiKey: credentials.apiKey,
@@ -141,16 +152,27 @@ export const monitorCommand = new Command('monitor')
                 ...(options.dev && { customUrl: 'http://localhost:5090' }),
             });
             const _res = await agent.getAgentById({ id: agentId });
-            const info = _res.agent || _res.data || _res;
-            if (info?.name)
+            const info = _res?.agent || _res?.data || _res;
+            if (!info || (!info.id && !info.name)) {
+                throw Object.assign(new Error('Agent not found'), { response: { status: 404 } });
+            }
+            if (info.name)
                 agentName = info.name;
-            process.stdout.write('\r' + ' '.repeat(40) + '\r');
+            status('\r' + ' '.repeat(40) + '\r');
         }
-        catch {
-            process.stdout.write('\r' + ' '.repeat(40) + '\r');
+        catch (loadErr) {
+            status('\r' + ' '.repeat(40) + '\r');
+            if (options.json)
+                fail(loadErr);
+            logger.error(describeAgentLoadError(loadErr, agentId, credentials, {
+                dev: options.dev,
+                workspaceOverride: options.workspace,
+                zoneOverride: options.zone,
+            }));
+            process.exit(1);
         }
         // Dibujar header
-        if (!jsonMode) {
+        if (!options.json) {
             console.clear();
             printHeader(agentName);
         }
@@ -163,6 +185,38 @@ export const monitorCommand = new Command('monitor')
         })
             .withAutomaticReconnect([0, 2000, 5000, 10000, 30000])
             .build();
+        // El hub no lleva headers de auth (WebSocket): la suscripcion se autoriza con un ticket
+        // firmado que emite GET /api/agent/monitor-token (valida que el agente sea del workspace).
+        // Si la API aun no tiene ese endpoint se usa el JoinAgentMonitor legado.
+        let monitorToken = null;
+        const api = createApiClient({
+            apiKey: credentials.apiKey,
+            workspace: effectiveWorkspace,
+            zone: effectiveZone,
+            dev: options.dev,
+        });
+        const joinMonitor = async () => {
+            if (!monitorToken) {
+                try {
+                    const { data } = await api.get('/api/agent/monitor-token', {
+                        params: { agentId, workspaceId: effectiveWorkspace },
+                    });
+                    monitorToken = data?.token ?? null;
+                }
+                catch (err) {
+                    const code = err?.response?.status;
+                    if (code && code !== 404) {
+                        throw new Error(err?.response?.data?.message || `Could not authorize the monitor (HTTP ${code})`);
+                    }
+                }
+            }
+            if (monitorToken) {
+                await connection.invoke('JoinAgentMonitorSecure', agentId, monitorToken);
+            }
+            else {
+                await connection.invoke('JoinAgentMonitor', agentId);
+            }
+        };
         // Evento de log
         connection.on('agent_log', (log) => {
             // Aplicar filtros
@@ -170,40 +224,35 @@ export const monitorCommand = new Command('monitor')
                 return;
             const line = renderLogLine(log, {
                 showSession: options.session,
-                jsonMode,
+                raw: rawMode,
             }, lastSessionId);
             console.log(line);
             lastSessionId = log.session_id || lastSessionId;
         });
         // Eventos de conexion
+        // En --json los avisos de conexion van a stderr (stdout solo lleva eventos)
         connection.onreconnecting(() => {
-            if (!jsonMode) {
-                console.log(chalk.hex('#FFA726')('  ⟳ Reconnecting...'));
-            }
+            statusLine(chalk.hex('#FFA726')('  ⟳ Reconnecting...'));
         });
         connection.onreconnected(() => {
-            if (!jsonMode) {
-                console.log(chalk.hex('#4ade80')('  ● Reconnected'));
-            }
-            connection.invoke('JoinAgentMonitor', agentId).catch(() => { });
+            statusLine(chalk.hex('#4ade80')('  ● Reconnected'));
+            joinMonitor().catch((err) => {
+                statusLine(chalk.hex('#ef4444')(`  Could not rejoin the monitor: ${err instanceof Error ? err.message : err}`));
+            });
         });
-        connection.onclose(() => {
-            if (!jsonMode) {
-                console.log(chalk.hex('#ef4444')('  ● Disconnected'));
-            }
+        connection.onclose((err) => {
+            statusLine(chalk.hex('#ef4444')(`  ● Disconnected${err?.message ? `: ${err.message}` : ''}`));
         });
         // Iniciar conexion
         try {
             await connection.start();
-            await connection.invoke('JoinAgentMonitor', agentId);
-            if (!jsonMode) {
-                console.log(chalk.hex('#4ade80')('  ● Connected to real-time monitor'));
+            await joinMonitor();
+            statusLine(chalk.hex('#4ade80')('  ● Connected to the real-time monitor'));
+            if (!options.json)
                 console.log();
-            }
         }
         catch (err) {
-            logger.error(`Could not connect to monitor: ${err instanceof Error ? err.message : err}`);
-            process.exit(1);
+            fail(new CliError(`Could not connect to the monitor: ${err instanceof Error ? err.message : err}`, 'monitor_connect_failed', 'Check your connection and try again.'));
         }
         // readline para comandos interactivos
         const rl = readline.createInterface({
@@ -223,9 +272,10 @@ export const monitorCommand = new Command('monitor')
                 printHeader(agentName);
                 return;
             }
-            if (cmd === '/json') {
-                jsonMode = !jsonMode;
-                console.log(chalk.gray(`  JSON mode: ${jsonMode ? 'enabled' : 'disabled'}`));
+            // /json se mantiene como alias de /raw
+            if (cmd === '/raw' || cmd === '/json') {
+                rawMode = !rawMode;
+                statusLine(chalk.gray(`  Raw mode: ${rawMode ? 'on' : 'off'}`));
                 return;
             }
             if (cmd === '/filters') {
@@ -273,9 +323,7 @@ export const monitorCommand = new Command('monitor')
         });
         // Cierre limpio
         const cleanup = async () => {
-            if (!jsonMode) {
-                console.log(chalk.gray('\n  Closing monitor...'));
-            }
+            statusLine(chalk.gray('\n  Closing monitor...'));
             try {
                 if (connection.state === HubConnectionState.Connected) {
                     await connection.invoke('LeaveAgentMonitor', agentId);
@@ -286,27 +334,25 @@ export const monitorCommand = new Command('monitor')
                 // Ignorar errores al cerrar
             }
             rl.close();
-            if (!jsonMode) {
-                console.log(chalk.gray('  Monitor closed.\n'));
-            }
+            statusLine(chalk.gray('  Monitor closed.'));
             process.exit(0);
         };
         process.on('SIGINT', cleanup);
         process.on('SIGTERM', cleanup);
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : 'Unknown error';
-        logger.error(message);
-        process.exit(1);
+        fail(error);
     }
 });
 addExamples(monitorCommand, [
     { description: 'Stream every event of an agent in real time',
-        command: 'plazbot agent monitor agt_AbcDef123' },
+        command: 'plazbot agent monitor age_AbcDef123' },
     { description: 'Only show inbound/outbound messages and errors',
-        command: 'plazbot agent monitor agt_AbcDef123 -f msg_in,msg_out,error' },
+        command: 'plazbot agent monitor age_AbcDef123 -f msg_in,msg_out,error' },
     { description: 'Emit raw JSON (one event per line) for piping to jq',
-        command: 'plazbot agent monitor agt_AbcDef123 --json' },
-    { description: 'Tail an agent from a different workspace (support mode)',
-        command: 'plazbot agent monitor agt_AbcDef123 -w wok_Other123 -z LA' },
+        command: 'plazbot agent monitor age_AbcDef123 --json' },
+]);
+addNotes(monitorCommand, [
+    'While it runs, type /help for commands: /filter <type>, /filters, /raw, /clear. Press Ctrl+C to exit.',
+    'With --json, stdout only carries events; status messages go to stderr.',
 ]);

package/dist/commands/agent/on-message.js

@@ -2,18 +2,24 @@ import { Command } from 'commander';
 import { Agent } from 'plazbot';
 import { getStoredCredentials } from '../../utils/credentials.js';
 import { logger } from '../../utils/logger.js';
-import { addExamples } from '../../utils/help.js';
+import { addExamples, addNotes } from '../../utils/help.js';
+import { createSpinner } from '../../utils/ui.js';
+import { jsonOption, isJsonMode, printJson, fail, CliError } from '../../utils/output.js';
 import crypto from 'crypto';
 export const messageCommand = new Command('message')
-    .description('Send a message to an agent and get its response')
+    .description('Send a single message to an agent and print its answer')
     .argument('<agentId>', 'Agent ID')
-    .requiredOption('-q, --question <text>', 'Message or question for the agent')
-    .option('-s, --session-id <id>', 'Session ID (optional)')
-    .option('-m, --multiple-answers', 'Allow multiple answers', false)
+    .requiredOption('-q, --question <text>', 'Message or question for the agent (required)')
+    .option('-s, --session-id <id>', 'Session ID to continue a conversation (default: a new random ID)')
+    .option('-m, --multiple-answers', 'Allow the agent to send several answers per turn', false)
+    .addOption(jsonOption('Print the answer as JSON ({"answer","sessionId","sources"})'))
     .option('--dev', 'Use development environment', false)
     .action(async (agentId, options) => {
     try {
-        // Obtener credenciales guardadas
+        const question = (options.question || '').trim();
+        if (!question) {
+            throw new CliError('The question cannot be empty.', 'missing_question', 'Pass it with -q, --question "<text>".');
+        }
         const credentials = await getStoredCredentials();
         const agent = new Agent({
             workspaceId: credentials.workspace,
@@ -23,46 +29,63 @@ export const messageCommand = new Command('message')
         });
         // Generar un sessionId si no se proporcionó uno
         const sessionId = options.sessionId || crypto.randomUUID();
-        logger.title('Sending message to agent');
-        logger.label('Agent ID', agentId);
-        logger.label('Question', options.question);
-        logger.label('Session ID', sessionId);
-        if (options.multipleAnswers) {
-            logger.info('Mode: Multiple answers');
+        const spinner = createSpinner('Waiting for the agent...');
+        spinner.start();
+        let response;
+        try {
+            response = await agent.onMessage({
+                agentId,
+                question,
+                sessionId,
+                multipleAnswers: options.multipleAnswers
+            });
         }
-        const response = await agent.onMessage({
-            agentId: agentId,
-            question: options.question,
-            sessionId,
-            multipleAnswers: options.multipleAnswers
-        });
-        logger.title('Agent Response');
-        console.log(response.answer);
-        if (response.sources && response.sources.length > 0) {
+        catch (err) {
+            spinner.fail('The agent did not answer');
+            throw err;
+        }
+        spinner.stop();
+        const sources = (response.sources || []).map((s) => ({
+            title: s.title || null,
+            url: s.url || null,
+        }));
+        if (isJsonMode()) {
+            printJson({
+                answer: response.answer ?? '',
+                sessionId,
+                ...(sources.length > 0 && { sources }),
+            });
+            return;
+        }
+        logger.title('Answer');
+        console.log(response.answer ?? '');
+        if (sources.length > 0) {
             logger.title('Sources');
-            response.sources.forEach((source) => {
+            sources.forEach((source) => {
                 logger.label('Title', source.title || 'Untitled');
                 if (source.url)
                     logger.label('URL', source.url);
             });
         }
-        logger.title('Session');
-        logger.label('ID', sessionId);
+        console.log();
+        logger.dim(`Session: ${sessionId}`);
+        logger.dim(`Continue it with: plazbot agent message ${agentId} -s ${sessionId} -q "..."`);
         if (options.dev) {
-            logger.warning('\nEnvironment: development');
+            logger.warning('Environment: development');
         }
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : 'Unknown error while sending the message';
-        logger.error(message);
-        process.exit(1);
+        fail(error);
     }
 });
 addExamples(messageCommand, [
     { description: 'Send a one-shot question to an agent',
-        command: 'plazbot agent message agt_AbcDef123 -q "What plans do you offer?"' },
+        command: 'plazbot agent message age_AbcDef123 -q "What plans do you offer?"' },
     { description: 'Continue an existing session',
-        command: 'plazbot agent message agt_AbcDef123 -q "And the price?" -s sess_AbcDef123' },
-    { description: 'Allow multiple answers per turn',
-        command: 'plazbot agent message agt_AbcDef123 -q "Tell me everything" -m' },
+        command: 'plazbot agent message age_AbcDef123 -q "And the price?" -s sess_AbcDef123' },
+    { description: 'Get only the answer text (scripts)',
+        command: "plazbot agent message age_AbcDef123 -q \"Hi\" --json | jq -r '.answer'" },
+]);
+addNotes(messageCommand, [
+    'Each call without -s starts a new conversation. Reuse the printed session ID to keep context.',
 ]);