plazbot-cli 0.4.1 → 0.5.0

package/dist/schemas/agent.config.schema.json

@@ -7,6 +7,10 @@
     "name": { "type": "string" },
     "description": { "type": "string" },
     "prompt": { "type": "string" },
+    "imagePrompt": {
+      "type": "string",
+      "description": "Instruccion usada cuando llega una imagen/archivo sin texto del usuario (caption vacio)."
+    },
     "zone": {
       "type": "string",
       "enum": ["LA", "EU"]
@@ -43,15 +47,15 @@
         "personality": { "type": "string" },
         "objective": { "type": "string" },
         "language": { "type": "string" },
-        "emojis": { "type": "boolean" },
+        "emojis": { "type": ["boolean", "null"] },
         "preferredFormat": { "type": "string" },
         "maxWords": { "type": "integer" },
         "avoidTopics": {
           "type": "array",
           "items": { "type": "string" }
         },
-        "respondOnlyIfKnows": { "type": "boolean" },
-        "maintainToneBetweenMessages": { "type": "boolean" },
+        "respondOnlyIfKnows": { "type": ["boolean", "null"] },
+        "maintainToneBetweenMessages": { "type": ["boolean", "null"] },
         "greeting": { "type": "string" }
       }
     },
@@ -164,6 +168,17 @@
       "default": false,
       "description": "Si true, divide la respuesta del agente IA en varios mensajes (split por doble salto de linea)."
     },
+    "advisorNameModeWidget": {
+      "type": ["string", "null"],
+      "enum": ["agent", "custom", null],
+      "default": "agent",
+      "description": "Nombre que ve el cliente sobre los mensajes del asesor humano en el widget: agent (nombre del asesor asignado) o custom (advisorNameWidget)."
+    },
+    "advisorNameWidget": {
+      "type": ["string", "null"],
+      "maxLength": 60,
+      "description": "Nombre personalizado del asesor humano en el widget (solo si advisorNameModeWidget = custom). Ej: Equipo de Soporte."
+    },
     "enableAvatarWidget": { "type": "boolean" },
     "avatarGender": {
       "type": "string",
@@ -202,14 +217,24 @@
       "properties": {
         "enabled": { "type": "boolean" },
         "phoneNumber": { "type": "string", "description": "DID phone number, e.g., +573151234567" },
-        "ttsProvider": { "type": "string", "enum": ["google", "openai"] },
+        "ttsProvider": { "type": "string", "enum": ["google", "openai", "elevenlabs"] },
         "ttsVoiceId": { "type": "string", "description": "TTS voice ID, e.g., nova, es-US-Journey-D" },
         "ttsLanguage": { "type": "string", "description": "Language code, e.g., es-CO, es-MX" },
         "greeting": { "type": "string", "description": "Initial greeting message for TTS" },
         "maxCallDurationSeconds": { "type": "integer", "minimum": 60, "maximum": 1800, "default": 300 },
-        "silenceTimeoutMs": { "type": "integer", "minimum": 2000, "maximum": 15000, "default": 5000 },
+        "silenceTimeoutMs": { "type": "integer", "minimum": 15000, "maximum": 60000, "default": 15000 },
         "transferExtension": { "type": "string", "description": "SIP extension for human transfer" },
-        "voiceType": { "type": "string", "enum": ["compact", "complete"], "description": "compact=fast no tools, complete=full toolcalling+RAG" }
+        "voiceType": { "type": "string", "enum": ["compact", "complete"], "description": "compact=fast no tools, complete=full toolcalling+RAG" },
+        "elevenlabsApiKey": { "type": "string", "description": "ElevenLabs API key (BYOK)" },
+        "elevenlabsVoiceId": { "type": "string", "description": "ElevenLabs voice ID" },
+        "elevenlabsVoiceName": { "type": "string", "description": "ElevenLabs voice display name" },
+        "elevenlabsModelId": { "type": "string", "description": "ElevenLabs model ID (e.g., eleven_multilingual_v2)" },
+        "elevenlabsStability": { "type": "number", "minimum": 0, "maximum": 100, "description": "Voice stability 0-100" },
+        "elevenlabsSimilarity": { "type": "number", "minimum": 0, "maximum": 100, "description": "Voice similarity 0-100" },
+        "elevenlabsStyle": { "type": "number", "minimum": 0, "maximum": 100, "description": "Style exaggeration 0-100" },
+        "elevenlabsSpeakerBoost": { "type": "boolean", "description": "Enable speaker boost" },
+        "languageInstruction": { "type": "string", "description": "Custom language instruction appended to the LLM prompt (if empty, the PBX generates an automatic one based on ttsLanguage)" },
+        "fillersEnabled": { "type": "boolean", "description": "Enable filler phrases (e.g. 'Dejame revisar') while the AI processes the response", "default": true }
       }
     },
     "useToolCalling": {
@@ -280,6 +305,16 @@
         }
       }
     },
+    "enableContingency": {
+      "type": "boolean",
+      "default": false,
+      "description": "If true and multiple aiProviders exist, retries with the remaining providers when the default provider fails (Tool Calling orchestrator only)"
+    },
+    "enableAudioInput": {
+      "type": "boolean",
+      "default": false,
+      "description": "If true, transcribes received voice audios (Whisper) and the agent replies as text (Tool Calling orchestrator only)"
+    },
     "channels": {
       "type": "array",
       "items": {
@@ -301,7 +336,7 @@
           "intent": { "type": "string" },
           "reference": { "type": "string" },
           "enabled": { "type": "boolean", "default": true },
-          "method": { "type": "string", "enum": ["GET", "POST"] },
+          "method": { "type": "string", "enum": ["GET", "POST", "PUT", "PATCH", "DELETE"] },
           "tags": {
             "type": "array",
             "items": { "type": "string" }
@@ -334,6 +369,21 @@
                       "type": { "type": "string" }
                     }
                   }
+                },
+                "buttons": {
+                  "type": "array",
+                  "maxItems": 3,
+                  "items": {
+                    "type": "object",
+                    "required": ["text"],
+                    "properties": {
+                      "text": { "type": "string", "minLength": 1, "maxLength": 20 }
+                    }
+                  }
+                },
+                "contactField": {
+                  "type": "string",
+                  "enum": ["name", "lastname", "email", "phoneNumber", "documentNumber", "businessName"]
                 }
               }
             }
@@ -508,6 +558,21 @@
                       "type": { "type": "string" }
                     }
                   }
+                },
+                "buttons": {
+                  "type": "array",
+                  "maxItems": 3,
+                  "items": {
+                    "type": "object",
+                    "required": ["text"],
+                    "properties": {
+                      "text": { "type": "string", "minLength": 1, "maxLength": 20 }
+                    }
+                  }
+                },
+                "contactField": {
+                  "type": "string",
+                  "enum": ["name", "lastname", "email", "phoneNumber", "documentNumber", "businessName"]
                 }
               }
             }
@@ -541,10 +606,96 @@
                     "action.stage.remove",
                     "action.tag.remove",
                     "action.segmentation.remove",
-                    "action.worker"
+                    "action.worker",
+                    "action.transfer.voip",
+                    "action.transfer.voip.external",
+                    "action.send.image",
+                    "action.send.file",
+                    "action.send.template",
+                    "action.send.template.voip",
+                    "action.ai.summary",
+                    "action.agent.ask"
                   ]
                 },
                 "value": { "type": "string" },
+                "queryTemplate": {
+                  "type": "string",
+                  "description": "Pregunta a enviar al agente consultado (solo action.agent.ask; el agentId destino va en 'value'). Soporta {{variables}}. Vacio = el LLM formula la pregunta con el parametro 'query'."
+                },
+                "outputVariable": {
+                  "type": "string",
+                  "description": "Codigo de variable del contacto donde guardar la respuesta del agente consultado (solo action.agent.ask, opcional)."
+                },
+                "assignMode": {
+                  "type": "string",
+                  "enum": ["user", "workload", "random", "workgroup"],
+                  "description": "Solo action.asign. user (default): email fijo en 'value'. workload: miembro con menos chats abiertos. random: al azar. workgroup: miembro de workgroupId por carga de trabajo. En modos automaticos, 'value' (email) es el respaldo si no hay nadie disponible."
+                },
+                "workgroupId": {
+                  "type": "string",
+                  "description": "Solo action.asign con assignMode workgroup: id del grupo de trabajo del workspace."
+                },
+                "onlyOnlineAgents": {
+                  "type": "boolean",
+                  "description": "Solo action.asign en modos automaticos: considerar solo miembros conectados."
+                },
+                "sipServer": {
+                  "type": "string",
+                  "description": "Servidor/Proxy SIP del partner (solo action.transfer.voip.external). Ej: trunks.vpbx.me. La extension destino se guarda en 'value'."
+                },
+                "sipPort": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "maximum": 65535,
+                  "default": 5060,
+                  "description": "Puerto SIP del proxy (solo action.transfer.voip.external). Default: 5060"
+                },
+                "sipUser": {
+                  "type": "string",
+                  "description": "Usuario SIP para autenticacion saliente (solo action.transfer.voip.external)"
+                },
+                "sipPassword": {
+                  "type": "string",
+                  "description": "Clave SIP para autenticacion saliente (solo action.transfer.voip.external)"
+                },
+                "sipDomain": {
+                  "type": "string",
+                  "description": "From-domain opcional para PBX multi-tenant que lo exijan (solo action.transfer.voip.external)"
+                },
+                "fileName": {
+                  "type": "string",
+                  "description": "Nombre original del archivo subido a S3 (solo para action.send.image / action.send.file). La URL publica de S3 se guarda en 'value'."
+                },
+                "mimeType": {
+                  "type": "string",
+                  "description": "Content-Type del archivo subido (solo para action.send.image / action.send.file). Ej: image/png, application/pdf."
+                },
+                "countryPrefix": {
+                  "type": "string",
+                  "description": "Prefijo de pais obligatorio para action.send.template y action.send.template.voip (ej: +34 o 34). Se antepone al numero destino si este no lo tiene. El templateId se guarda en 'value'."
+                },
+                "phoneNumber": {
+                  "type": "string",
+                  "description": "Numero destino de la alerta SIN prefijo de pais (solo action.send.template). La plantilla se envia a este numero (alerta a otra persona), NO al contacto de la conversacion. Para varios numeros, crear varias acciones."
+                },
+                "waSenderId": {
+                  "type": "string",
+                  "description": "codeCellphoneNumberId de la integracion WhatsApp del workspace desde la que se envia la plantilla (obligatorio en action.send.template y action.send.template.voip)."
+                },
+                "templateVariables": {
+                  "type": "array",
+                  "description": "Valores de las variables {{n}} de la plantilla (action.send.template / .voip). Cada 'value' admite texto fijo y placeholders: {{contact.x}}, {{system.x}}, {{custom.x}} o {{campoRequerido}} de la accion.",
+                  "items": {
+                    "type": "object",
+                    "required": ["componentType", "variable"],
+                    "properties": {
+                      "componentType": { "type": "string", "enum": ["HEADER", "BODY"] },
+                      "variable": { "type": "string" },
+                      "value": { "type": "string" }
+                    },
+                    "additionalProperties": false
+                  }
+                },
                 "durationMinutes": {
                   "type": "integer",
                   "minimum": 5,

package/dist/studio/api/sseClient.js

@@ -33,7 +33,7 @@ export async function streamStudio(opts, request, onChunk, signal) {
         throw new StudioHttpError(res.status, res.statusText, text);
     }
     if (!res.body) {
-        throw new Error('Respuesta sin body en POST /api/agent/studio');
+        throw new Error('Empty response body from POST /api/agent/studio.');
     }
     const reader = res.body.getReader();
     const decoder = new TextDecoder();

package/dist/studio/api/studioApi.js

@@ -23,3 +23,11 @@ export function buildStudioHeaders(opts) {
         headers['x-user-id'] = opts.userId;
     return headers;
 }
+/**
+ * userId sent to Studio (optional; the backend uses it to attribute created/saved
+ * agents). Stored login sessions carry it; env-var credentials
+ * (PLAZBOT_API_KEY/PLAZBOT_WORKSPACE_ID) don't, so PLAZBOT_USER_ID fills the gap.
+ */
+export function resolveStudioUserId(creds) {
+    return creds.userId || process.env.PLAZBOT_USER_ID?.trim() || creds.email || undefined;
+}

package/dist/studio/components/App.js

@@ -161,6 +161,13 @@ export function App({ version, stream, initialAgentId, dev, supportMode }) {
                 agentId: useStudioStore.getState().agentId,
                 agentConfig: useStudioStore.getState().agentConfig,
             }, onChunk, controller.signal);
+            if (controller.signal.aborted) {
+                // Esc: the SSE client returns quietly on abort. Mark running steps and
+                // don't compact a half-written summary.
+                useStudioStore.getState().failAllRunningSteps('Cancelled');
+                useStudioStore.getState().setPendingCompact(false);
+                useStudioStore.getState().pushSyntheticAssistant('Response cancelled.');
+            }
         }
         catch (err) {
             const msg = formatError(err, dev);
@@ -215,6 +222,11 @@ function formatError(err, dev) {
     if (err instanceof Error) {
         if (err.name === 'AbortError')
             return '✖ Stream cancelled.';
+        if (err.name === 'TypeError' && /fetch failed/i.test(err.message)) {
+            return dev
+                ? '✖ Could not reach the local backend (http://localhost:5090). Is it running?'
+                : '✖ Could not reach the Plazbot API. Check your internet connection.';
+        }
         return `✖ ${err.message}`;
     }
     return '✖ Unknown error';

package/dist/studio/components/Footer.js

@@ -7,5 +7,5 @@ function fmt(n) {
     return String(n);
 }
 export function Footer({ inputTokens, outputTokens, streaming }) {
-    return (_jsxs(Box, { paddingX: 1, flexDirection: "row", justifyContent: "space-between", children: [_jsxs(Box, { children: [_jsx(Text, { dimColor: true, children: "tokens: " }), _jsx(Text, { children: fmt(inputTokens) }), _jsx(Text, { dimColor: true, children: " in / " }), _jsx(Text, { children: fmt(outputTokens) }), _jsx(Text, { dimColor: true, children: " out" }), streaming ? (_jsxs(_Fragment, { children: [_jsx(Text, { children: "  " }), _jsx(Text, { color: "yellow", children: _jsx(Spinner, { type: "dots" }) }), _jsx(Text, { color: "yellow", children: " streaming\u2026" })] })) : null] }), _jsx(Box, { children: _jsx(Text, { dimColor: true, children: "/help \u00B7 \u2191\u2193 history \u00B7 Tab accept \u00B7 Esc cancel \u00B7 Ctrl+C quit" }) })] }));
+    return (_jsxs(Box, { paddingX: 1, flexDirection: "row", justifyContent: "space-between", children: [_jsxs(Box, { children: [_jsx(Text, { dimColor: true, children: "tokens: " }), _jsx(Text, { children: fmt(inputTokens) }), _jsx(Text, { dimColor: true, children: " in / " }), _jsx(Text, { children: fmt(outputTokens) }), _jsx(Text, { dimColor: true, children: " out" }), streaming ? (_jsxs(_Fragment, { children: [_jsx(Text, { children: "  " }), _jsx(Text, { color: "yellow", children: _jsx(Spinner, { type: "dots" }) }), _jsx(Text, { color: "yellow", children: " streaming\u2026" })] })) : null] }), _jsx(Box, { children: _jsx(Text, { dimColor: true, children: streaming ? 'Esc cancel · Ctrl+C exit' : '/help · ↑↓ history · Tab/→ accept suggestion · Esc cancel · Ctrl+C exit' }) })] }));
 }

package/dist/studio/index.js

@@ -1,42 +1,105 @@
-import { Command } from 'commander';
+import { Command, Option } from 'commander';
+import { jsonOption, fail, CliError, setJsonMode } from '../utils/output.js';
+import { addExamples, addNotes } from '../utils/help.js';
+const WORKSPACE_DESC = 'Act on another workspace (support / white-label partner mode)';
+/** Hidden legacy alias of `--workspace` (kept for backwards compatibility). */
+function legacyWorkspaceIdOption() {
+    return new Option('--workspace-id <id>', WORKSPACE_DESC).hideHelp();
+}
 export const studioCommand = new Command('studio')
-    .description('Interactive Plazbot Studio REPL (create, diagnose and manage AI agents)')
+    .description('Open Plazbot Studio, an interactive assistant to create, diagnose and manage AI agents')
+    // Options written after `ask` belong to `ask` (otherwise `studio` would swallow
+    // `--json`, `--dev`, `-a`, `-w` and the subcommand would never see them).
+    .enablePositionalOptions()
     .option('--dev', 'Target the local backend (http://localhost:5090)', false)
-    .option('-a, --agent-id <id>', 'Preload an agent on startup')
-    .option('-w, --workspace-id <id>', 'Override the workspace (support / white-label partner mode)')
-    .option('-m, --message <text>', 'Run a one-shot prompt and exit')
+    .option('-a, --agent-id <id>', 'Preload an agent as context on startup')
+    .option('-w, --workspace <id>', WORKSPACE_DESC)
+    .addOption(legacyWorkspaceIdOption())
+    .option('-m, --message <text>', 'Alias of `studio ask`: run a one-shot prompt and exit')
+    .addOption(jsonOption('With -m: print the SSE chunks as NDJSON (one JSON object per line)'))
     .action(async (opts) => {
-    if (opts.message) {
+    const workspaceOverride = opts.workspace ?? opts.workspaceId;
+    if (opts.message !== undefined) {
+        if (!opts.message.trim()) {
+            fail(new CliError('The message is empty.', 'missing_message', 'Pass a prompt: plazbot studio -m "List my agents"'));
+        }
         const { runOneShot } = await import('./runOneShot.js');
         await runOneShot({
             dev: opts.dev,
             agentId: opts.agentId,
             message: opts.message,
-            workspaceOverride: opts.workspaceId,
+            json: opts.json,
+            workspaceOverride,
         });
         return;
     }
+    if (opts.json) {
+        fail(new CliError('--json only works with a one-shot prompt.', 'json_requires_message', 'Use: plazbot studio ask "List my agents" --json'));
+    }
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        fail(new CliError('The Studio REPL needs an interactive terminal.', 'not_interactive', 'Use a one-shot prompt instead: plazbot studio ask "List my agents"'));
+    }
     const { runRepl } = await import('./runRepl.js');
     await runRepl({
         dev: opts.dev,
         agentId: opts.agentId,
-        workspaceOverride: opts.workspaceId,
+        workspaceOverride,
     });
 });
-studioCommand
+addExamples(studioCommand, [
+    { description: 'Open the interactive Studio', command: 'plazbot studio' },
+    { description: 'Open Studio with an agent already loaded', command: 'plazbot studio -a age_AbcDef123' },
+    { description: 'Run a single prompt and exit (same as `studio ask`)', command: 'plazbot studio -m "Diagnose this agent" -a age_AbcDef123' },
+    { description: 'Act on a customer workspace (support / partner mode)', command: 'plazbot studio -w wok_AbcDef123' },
+]);
+addNotes(studioCommand, [
+    'Requires a session: run `plazbot login` (or set PLAZBOT_API_KEY and PLAZBOT_WORKSPACE_ID).',
+    'Keys: Enter send · ↑/↓ history · Tab or → accept the gray suggestion · Esc cancel the response · Ctrl+C exit.',
+    'Type /help inside Studio to list slash commands (/agents, /load, /diagnose, /save, /export, /clear, /compact...).',
+    'In support mode (-w) every action is tied to your user and visible in audit trails.',
+]);
+const askCommand = studioCommand
     .command('ask <message>')
-    .description('Run a one-shot studio query without opening the TUI')
+    .description('Run a one-shot Studio prompt without opening the interactive UI')
     .option('--dev', 'Target the local backend (http://localhost:5090)', false)
     .option('-a, --agent-id <id>', 'Agent to use as context')
-    .option('-w, --workspace-id <id>', 'Override the workspace (support / white-label partner mode)')
-    .option('--json', 'Print SSE chunks as raw NDJSON', false)
-    .action(async (message, opts) => {
+    .option('-w, --workspace <id>', WORKSPACE_DESC)
+    .addOption(legacyWorkspaceIdOption())
+    .addOption(jsonOption('Print the SSE chunks as NDJSON (one JSON object per line)'))
+    .action(async (message, askOpts, cmd) => {
+    // Also honor options written before `ask` (`plazbot studio --dev ask "..."`).
+    const parent = (cmd.parent?.opts() ?? {});
+    const opts = {
+        dev: askOpts.dev || !!parent.dev,
+        json: askOpts.json || !!parent.json,
+        agentId: askOpts.agentId ?? parent.agentId,
+        workspace: askOpts.workspace ?? parent.workspace,
+        workspaceId: askOpts.workspaceId ?? parent.workspaceId,
+    };
+    if (opts.json)
+        setJsonMode(true);
+    if (!message.trim()) {
+        fail(new CliError('The message is empty.', 'missing_message', 'Pass a prompt: plazbot studio ask "List my agents"'));
+    }
     const { runOneShot } = await import('./runOneShot.js');
     await runOneShot({
         dev: opts.dev,
         agentId: opts.agentId,
         message,
         json: opts.json,
-        workspaceOverride: opts.workspaceId,
+        workspaceOverride: opts.workspace ?? opts.workspaceId,
     });
 });
+addExamples(askCommand, [
+    { description: 'List the agents in your workspace', command: 'plazbot studio ask "List my agents"' },
+    { description: 'Diagnose a specific agent', command: 'plazbot studio ask "Diagnose this agent and report issues" -a age_AbcDef123' },
+    { description: 'Stream raw chunks for scripting', command: 'plazbot studio ask "List my agents" --json' },
+    { description: 'Ask about a customer workspace (support / partner mode)', command: 'plazbot studio ask "List the agents" -w wok_AbcDef123' },
+]);
+addNotes(askCommand, [
+    'The answer streams to stdout; tool steps, token usage and errors go to stderr.',
+    'With --json, stdout carries one JSON chunk per line: text, tool_call, tool_result, usage, error, done.',
+    'Exits with code 1 when the request fails or the stream returns an error chunk.',
+    'Each call is a fresh conversation (no history). Use `plazbot studio` for multi-turn sessions.',
+    'With PLAZBOT_API_KEY / PLAZBOT_WORKSPACE_ID credentials, set PLAZBOT_USER_ID to attribute created or saved agents to a user (optional).',
+]);

package/dist/studio/runOneShot.js

@@ -1,18 +1,16 @@
 import { getStoredCredentials } from '../utils/credentials.js';
-import { logger } from '../utils/logger.js';
+import { fail, CliError } from '../utils/output.js';
 import { streamStudio } from './api/sseClient.js';
 import { StudioHttpError } from './api/types.js';
 import { stepLabel } from './render/steps.js';
+import { resolveStudioUserId } from './api/studioApi.js';
 export async function runOneShot(opts) {
     let creds;
     try {
         creds = await getStoredCredentials();
     }
     catch {
-        logger.error('No active session. Run:');
-        console.log('  plazbot login');
-        process.exit(1);
-        return;
+        fail(new CliError('You are not signed in.', 'not_signed_in', 'Run `plazbot login`, or set PLAZBOT_API_KEY and PLAZBOT_WORKSPACE_ID.'));
     }
     const effectiveWorkspace = opts.workspaceOverride ?? creds.workspace;
     const supportMode = !!opts.workspaceOverride && opts.workspaceOverride !== creds.workspace;
@@ -22,15 +20,18 @@ export async function runOneShot(opts) {
     const stream = {
         apiKey: creds.apiKey,
         workspaceId: effectiveWorkspace,
-        userId: creds.userId ?? creds.email ?? undefined,
+        userId: resolveStudioUserId(creds),
         zone: creds.zone,
         dev: opts.dev,
     };
     const controller = new AbortController();
     process.on('SIGINT', () => controller.abort());
     let assistantText = '';
+    let streamError = null;
     const onChunk = (chunk) => {
         if (opts.json) {
+            if (chunk.type === 'error')
+                streamError = chunk.error || 'The Studio stream returned an error.';
             process.stdout.write(JSON.stringify(chunk) + '\n');
             return;
         }
@@ -53,7 +54,8 @@ export async function runOneShot(opts) {
                 process.stderr.write(`  tokens: ${chunk.input_tokens} in / ${chunk.output_tokens} out\n`);
                 break;
             case 'error':
-                process.stderr.write(`\n  ✖ ${chunk.error}\n`);
+                streamError = chunk.error || 'The Studio stream returned an error.';
+                process.stderr.write(`\n  ✖ ${streamError}\n`);
                 break;
             case 'done':
                 break;
@@ -65,32 +67,69 @@ export async function runOneShot(opts) {
             messages: [{ role: 'user', content: opts.message }],
             agentId: opts.agentId ?? null,
         }, onChunk, controller.signal);
+        if (controller.signal.aborted) {
+            if (!opts.json)
+                process.stdout.write('\n');
+            process.stderr.write('  Cancelled.\n');
+            process.exit(130);
+        }
         if (!opts.json)
             process.stdout.write('\n');
+        if (streamError) {
+            // In JSON mode the error chunk is already on stdout; also report it on stderr.
+            if (opts.json)
+                process.stderr.write(JSON.stringify({ error: { message: streamError, code: 'studio_error' } }) + '\n');
+            process.exit(1);
+        }
         if (!assistantText && !opts.json)
             process.stderr.write('  (no text response)\n');
     }
     catch (err) {
-        process.stderr.write('\n' + formatError(err, opts.dev) + '\n');
-        process.exit(1);
+        if (!opts.json)
+            process.stdout.write('\n');
+        fail(toCliError(err, opts.dev));
     }
 }
-function formatError(err, dev) {
+function toCliError(err, dev) {
     if (err instanceof StudioHttpError) {
-        if (err.status === 401)
-            return '✖ Token expired or invalid. Run `plazbot login`.';
-        if (err.status === 403)
-            return '✖ No permission for this workspace.';
-        if (err.status === 429)
-            return '✖ Rate limit reached.';
+        const apiMessage = extractApiMessage(err.body);
+        if (err.status === 401) {
+            return new CliError(apiMessage || 'Your session is invalid or expired.', 'unauthorized', 'Run `plazbot login` to sign in again.');
+        }
+        if (err.status === 403) {
+            return new CliError(apiMessage || 'You do not have permission for this workspace.', 'forbidden', 'Check the active workspace with `plazbot whoami`.');
+        }
+        if (err.status === 429) {
+            return new CliError(apiMessage || 'Too many requests.', 'rate_limited', 'Wait a few seconds and try again.');
+        }
         if (err.status >= 500) {
-            return dev
-                ? `✖ Backend ${err.status}: ${err.body ?? err.statusText}`
-                : `✖ Backend returned ${err.status}. Retry.`;
+            const detail = dev && err.body ? `: ${err.body}` : '.';
+            return new CliError(`Plazbot Studio error (HTTP ${err.status})${detail}`, 'api_error', 'Try again in a few seconds.');
         }
-        return `✖ HTTP ${err.status} ${err.statusText}`;
+        return new CliError(apiMessage || `Studio request failed (HTTP ${err.status} ${err.statusText}).`, 'request_failed');
+    }
+    if (err instanceof CliError)
+        return err;
+    if (err instanceof Error) {
+        const code = err.cause?.code;
+        if (err.name === 'TypeError' && /fetch failed/i.test(err.message)) {
+            return new CliError(dev
+                ? `Could not reach the local backend (http://localhost:5090)${code ? ` (${code})` : ''}.`
+                : `Could not reach the Plazbot API${code ? ` (${code})` : ''}.`, 'network_error', dev ? 'Is the backend running?' : 'Check your internet connection.');
+        }
+        return new CliError(err.message.endsWith('.') ? err.message : `${err.message}.`);
+    }
+    return new CliError('Unknown error.');
+}
+function extractApiMessage(body) {
+    if (!body)
+        return undefined;
+    try {
+        const parsed = JSON.parse(body);
+        const msg = parsed.message ?? parsed.error;
+        return typeof msg === 'string' && msg ? msg : undefined;
+    }
+    catch {
+        return undefined;
     }
-    if (err instanceof Error)
-        return `✖ ${err.message}`;
-    return '✖ Unknown error';
 }

package/dist/studio/runRepl.js

@@ -6,6 +6,8 @@ import { dirname, join } from 'node:path';
 import { App } from './components/App.js';
 import { getStoredCredentials } from '../utils/credentials.js';
 import { logger } from '../utils/logger.js';
+import { fail, CliError } from '../utils/output.js';
+import { resolveStudioUserId } from './api/studioApi.js';
 // Estilo Claude Code: NO usamos alt screen buffer. Razon: en el alt screen el
 // scrollback nativo de la terminal queda inaccesible y el usuario no puede
 // revisar la conversacion anterior. Aceptamos el tradeoff de que en algunos
@@ -16,10 +18,8 @@ export async function runRepl(opts) {
     try {
         creds = await getStoredCredentials();
     }
-    catch (err) {
-        logger.error('No active session. Run:');
-        console.log('  plazbot login');
-        process.exit(1);
+    catch {
+        fail(new CliError('You are not signed in.', 'not_signed_in', 'Run `plazbot login`, or set PLAZBOT_API_KEY and PLAZBOT_WORKSPACE_ID.'));
     }
     const effectiveWorkspace = opts.workspaceOverride ?? creds.workspace;
     const supportMode = !!opts.workspaceOverride && opts.workspaceOverride !== creds.workspace;
@@ -30,7 +30,7 @@ export async function runRepl(opts) {
     const stream = {
         apiKey: creds.apiKey,
         workspaceId: effectiveWorkspace,
-        userId: creds.userId ?? creds.email ?? undefined,
+        userId: resolveStudioUserId(creds),
         zone: creds.zone,
         dev: opts.dev,
     };