plazbot-cli 0.2.26 → 0.3.1

package/src/studio/slash/handlers.ts

@@ -0,0 +1,226 @@
+import { writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { slashRegistry } from './registry.js';
+import type { SlashResult } from './registry.js';
+import { useStudioStore } from '../state/store.js';
+
+function expandTilde(p: string): string {
+  if (p === '~') return homedir();
+  if (p.startsWith('~/')) return resolve(homedir(), p.slice(2));
+  return p;
+}
+
+function slugify(s: string): string {
+  return s
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .replace(/[^a-zA-Z0-9-_]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .toLowerCase() || 'agent';
+}
+
+const CATEGORY_LABELS: Record<NonNullable<import('./registry.js').SlashCategory>, string> = {
+  general: 'General',
+  agent: 'Agent',
+  session: 'Session',
+};
+const CATEGORY_ORDER: Array<NonNullable<import('./registry.js').SlashCategory>> = [
+  'general',
+  'agent',
+  'session',
+];
+
+slashRegistry.register({
+  name: 'help',
+  aliases: ['?'],
+  description: 'Show this help with every available command',
+  category: 'general',
+  handler(): SlashResult {
+    const all = slashRegistry.list();
+    const grouped = new Map<string, typeof all>();
+    for (const cmd of all) {
+      const cat = cmd.category ?? 'general';
+      const arr = grouped.get(cat) ?? [];
+      arr.push(cmd);
+      grouped.set(cat, arr);
+    }
+
+    const lines: string[] = ['**Plazbot Studio — slash commands**', ''];
+    lines.push('Type plain text to chat with the assistant.');
+    lines.push('Slash commands run locally or send a templated prompt to the model.');
+    lines.push('');
+
+    for (const cat of CATEGORY_ORDER) {
+      const items = grouped.get(cat);
+      if (!items || items.length === 0) continue;
+      lines.push(`**${CATEGORY_LABELS[cat]}**`);
+      for (const cmd of items) {
+        const usage = cmd.usage ?? `/${cmd.name}`;
+        const aliasPart = cmd.aliases?.length
+          ? ` _(alias: ${cmd.aliases.map((a) => '/' + a).join(', ')})_`
+          : '';
+        lines.push(`- \`${usage}\`${aliasPart} — ${cmd.description}`);
+      }
+      lines.push('');
+    }
+
+    lines.push('**Keyboard shortcuts**');
+    lines.push('- `Esc` — cancel the current stream');
+    lines.push('- `Ctrl+C` — exit Studio');
+    lines.push('');
+    lines.push('**Tip:** you can also speak naturally — e.g. _"list my agents"_, _"create a sales agent for WhatsApp"_ or _"connect this agent to WhatsApp Business"_.');
+
+    useStudioStore.getState().pushSyntheticAssistant(lines.join('\n'));
+    return { kind: 'noop' };
+  },
+});
+
+slashRegistry.register({
+  name: 'clear',
+  aliases: ['cls'],
+  description: 'Clear the conversation (keeps the loaded agent and token usage)',
+  category: 'session',
+  handler(): SlashResult {
+    useStudioStore.getState().clearMessages();
+    return { kind: 'noop' };
+  },
+});
+
+slashRegistry.register({
+  name: 'reset',
+  description: 'Full reset: clears messages, loaded agent and token usage',
+  category: 'session',
+  handler(): SlashResult {
+    useStudioStore.getState().reset();
+    return { kind: 'noop' };
+  },
+});
+
+const COMPACT_PROMPT = [
+  'You are about to compact this conversation.',
+  '',
+  'Produce a concise but complete summary of everything we have discussed so far, in Markdown:',
+  '- Goal / task the user is working on.',
+  '- Key decisions and constraints.',
+  '- Current agent configuration state (if any) and its `id`.',
+  '- Pending items or next steps.',
+  '',
+  'Reply with ONLY the summary content (no preamble, no farewell).',
+  'After this message, the previous history will be replaced by your summary so we can keep working with less context.',
+].join('\n');
+
+slashRegistry.register({
+  name: 'compact',
+  description: 'Summarize the conversation and replace history with that summary',
+  category: 'session',
+  handler(): SlashResult {
+    const store = useStudioStore.getState();
+    if (store.messages.length === 0) {
+      store.pushSyntheticAssistant('Nothing to compact yet.', { error: true });
+      return { kind: 'noop' };
+    }
+    store.setPendingCompact(true);
+    return { kind: 'message', content: COMPACT_PROMPT };
+  },
+});
+
+slashRegistry.register({
+  name: 'quit',
+  aliases: ['exit', 'q'],
+  description: 'Exit Studio',
+  category: 'general',
+  handler(_parsed, ctx): SlashResult {
+    ctx.exit();
+    return { kind: 'exit' };
+  },
+});
+
+slashRegistry.register({
+  name: 'agents',
+  description: 'List the agents in the current workspace',
+  category: 'agent',
+  handler(): SlashResult {
+    return { kind: 'message', content: 'List all agents in my workspace.' };
+  },
+});
+
+slashRegistry.register({
+  name: 'load',
+  description: 'Load an agent by id and show its current configuration',
+  category: 'agent',
+  usage: '/load <agentId>',
+  handler(parsed): SlashResult {
+    const id = parsed.args[0];
+    if (!id) {
+      useStudioStore.getState().pushSyntheticAssistant('Usage: `/load <agentId>`', { error: true });
+      return { kind: 'noop' };
+    }
+    useStudioStore.getState().setAgentId(id);
+    return { kind: 'message', content: `Load the agent with id "${id}" and show me its current configuration.` };
+  },
+});
+
+slashRegistry.register({
+  name: 'save',
+  description: 'Save the currently loaded agent configuration to the backend',
+  category: 'agent',
+  handler(): SlashResult {
+    const { agentConfig } = useStudioStore.getState();
+    if (!agentConfig) {
+      useStudioStore.getState().pushSyntheticAssistant(
+        'No agent configuration loaded. Create one first or use `/load <id>`.',
+        { error: true },
+      );
+      return { kind: 'noop' };
+    }
+    return { kind: 'message', content: 'Save this agent with its current configuration.' };
+  },
+});
+
+slashRegistry.register({
+  name: 'diagnose',
+  description: 'Run diagnostics on the current agent and report any issues found',
+  category: 'agent',
+  handler(): SlashResult {
+    return { kind: 'message', content: 'Diagnose this agent and report any issues you find.' };
+  },
+});
+
+slashRegistry.register({
+  name: 'export',
+  aliases: ['download'],
+  description: 'Export the current agent configuration to a JSON file on disk',
+  category: 'agent',
+  usage: '/export [path]',
+  async handler(parsed): Promise<SlashResult> {
+    const store = useStudioStore.getState();
+    const { agentConfig } = store;
+
+    if (!agentConfig) {
+      store.pushSyntheticAssistant(
+        'No hay agente cargado. Crea o carga uno antes con `/load <id>`.',
+        { error: true },
+      );
+      return { kind: 'noop' };
+    }
+
+    const cfg = agentConfig as any;
+    const baseName = slugify(cfg?.name ?? store.agentId ?? 'agent');
+    const defaultPath = `./${baseName}.json`;
+    const targetArg = parsed.args[0] ?? defaultPath;
+    const targetPath = resolve(process.cwd(), expandTilde(targetArg));
+
+    try {
+      await writeFile(targetPath, JSON.stringify(agentConfig, null, 2), 'utf-8');
+      store.pushSyntheticAssistant(
+        `Agente exportado a \`${targetPath}\`.\n\nValídalo con: \`plazbot agent validate ${targetPath}\``,
+      );
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      store.pushSyntheticAssistant(`No pude escribir el archivo: ${message}`, { error: true });
+    }
+    return { kind: 'noop' };
+  },
+});
+

package/src/studio/slash/parser.ts

@@ -0,0 +1,41 @@
+export interface ParsedSlash {
+  name: string;
+  args: string[];
+  raw: string;
+}
+
+/**
+ * Parsea un input crudo del usuario.
+ *  - Si empieza con `/`, retorna { name, args, raw } para ejecutar como slash command.
+ *  - Si no, retorna null (mensaje normal al backend).
+ */
+export function parseSlash(input: string): ParsedSlash | null {
+  const trimmed = input.trim();
+  if (!trimmed.startsWith('/')) return null;
+  const without = trimmed.slice(1);
+  if (!without) return { name: '', args: [], raw: trimmed };
+  // Split por espacios respetando comillas básicas.
+  const tokens = tokenize(without);
+  const [name, ...args] = tokens;
+  return { name: (name ?? '').toLowerCase(), args, raw: trimmed };
+}
+
+function tokenize(s: string): string[] {
+  const out: string[] = [];
+  let cur = '';
+  let quote: '"' | "'" | null = null;
+  for (const ch of s) {
+    if (quote) {
+      if (ch === quote) { quote = null; continue; }
+      cur += ch;
+    } else if (ch === '"' || ch === "'") {
+      quote = ch;
+    } else if (/\s/.test(ch)) {
+      if (cur) { out.push(cur); cur = ''; }
+    } else {
+      cur += ch;
+    }
+  }
+  if (cur) out.push(cur);
+  return out;
+}

package/src/studio/slash/registry.ts

@@ -0,0 +1,54 @@
+import type { ParsedSlash } from './parser.js';
+
+/**
+ * Resultado de un slash handler:
+ *  - { kind: 'message', content }    -> enviar `content` como mensaje normal al backend.
+ *  - { kind: 'noop' }                -> ya consumido por el handler (sin tráfico).
+ *  - { kind: 'exit' }                -> el REPL debe cerrarse.
+ *  - { kind: 'error', content }      -> mostrar mensaje de error sintético.
+ */
+export type SlashResult =
+  | { kind: 'message'; content: string }
+  | { kind: 'noop' }
+  | { kind: 'exit' }
+  | { kind: 'error'; content: string };
+
+export interface SlashHandlerContext {
+  exit: () => void;
+}
+
+export type SlashHandler = (parsed: ParsedSlash, ctx: SlashHandlerContext) => SlashResult | Promise<SlashResult>;
+
+export type SlashCategory = 'general' | 'agent' | 'session';
+
+export interface SlashSpec {
+  name: string;
+  aliases?: string[];
+  description: string;
+  /** Group used by `/help` to render commands by section. Defaults to 'general'. */
+  category?: SlashCategory;
+  /** Optional usage line (e.g. `/load <agentId>`). Falls back to `/<name>`. */
+  usage?: string;
+  handler: SlashHandler;
+}
+
+class SlashRegistry {
+  private map = new Map<string, SlashSpec>();
+  private order: SlashSpec[] = [];
+
+  register(spec: SlashSpec): void {
+    this.order.push(spec);
+    this.map.set(spec.name, spec);
+    spec.aliases?.forEach((a) => this.map.set(a, spec));
+  }
+
+  get(name: string): SlashSpec | undefined {
+    return this.map.get(name);
+  }
+
+  list(): SlashSpec[] {
+    return this.order.slice();
+  }
+}
+
+export const slashRegistry = new SlashRegistry();

package/src/studio/state/store.ts

@@ -0,0 +1,273 @@
+import { create } from 'zustand';
+import { randomUUID } from 'node:crypto';
+import type { WaConnectState, WaConnectStatus, WhatsappLinkData } from '../whatsapp/types.js';
+
+export type Role = 'user' | 'assistant' | 'system';
+
+export interface ChatMessage {
+  id: string;
+  role: Role;
+  content: string;
+  /** Mensaje aún siendo recibido por streaming. */
+  streaming?: boolean;
+  /** Mensaje sintético generado por slash commands (no enviado al backend). */
+  synthetic?: boolean;
+  /** Marca de error visual. */
+  error?: boolean;
+}
+
+export type StepStatus = 'running' | 'success' | 'error';
+
+export interface ToolStep {
+  id: string;
+  toolName: string;
+  status: StepStatus;
+  /** Anclamos el step debajo del mensaje del assistant que lo originó. */
+  afterMessageId: string;
+  result?: unknown;
+  errorMessage?: string;
+}
+
+export interface StudioState {
+  messages: ChatMessage[];
+  steps: ToolStep[];
+  agentConfig: unknown | null;
+  agentId: string | null;
+  usage: { inputTokens: number; outputTokens: number };
+  streaming: boolean;
+  abortController: AbortController | null;
+  /** True mientras se está corriendo el flujo de /compact (el próximo assistant
+   *  reemplazará todo el historial cuando termine). */
+  pendingCompact: boolean;
+
+  pushUserMessage(content: string): string;
+  pushSyntheticAssistant(content: string, opts?: { error?: boolean }): string;
+  startAssistantMessage(): string;
+  appendAssistantText(id: string, delta: string): void;
+  finishAssistantMessage(id: string): void;
+
+  startStep(toolName: string, afterMessageId: string): string;
+  resolveLastStep(toolName: string, status: StepStatus, result?: unknown, errorMessage?: string): void;
+  failAllRunningSteps(message?: string): void;
+
+  setAgentConfig(cfg: unknown): void;
+  setAgentId(id: string | null): void;
+  addUsage(inT: number, outT: number): void;
+
+  setStreaming(s: boolean): void;
+  setAbortController(ctrl: AbortController | null): void;
+  abortStream(): void;
+
+  /** WhatsApp connection card state (only one active at a time). */
+  waConnect: WaConnectState | null;
+  startWaConnect(linkData: WhatsappLinkData, anchorMessageId: string): string;
+  updateWaConnect(patch: Partial<WaConnectState>): void;
+  setWaStatus(status: WaConnectStatus, extra?: Partial<WaConnectState>): void;
+  clearWaConnect(): void;
+
+  /** Borra mensajes/steps/waConnect pero MANTIENE agente cargado, usage y config. */
+  clearMessages(): void;
+  /** Marca que el próximo stream completo debe reemplazar el historial. */
+  setPendingCompact(v: boolean): void;
+  /** Reemplaza todo el historial por el contenido del mensaje `id` (el resumen). */
+  compactInto(id: string): void;
+  /** Reset total (mensajes + agente + usage). */
+  reset(): void;
+}
+
+function uid(): string {
+  // randomUUID está disponible en Node >=14.17 con crypto. Fallback simple.
+  try { return randomUUID(); } catch { return Math.random().toString(36).slice(2); }
+}
+
+export const useStudioStore = create<StudioState>((set, get) => ({
+  messages: [],
+  steps: [],
+  agentConfig: null,
+  agentId: null,
+  usage: { inputTokens: 0, outputTokens: 0 },
+  streaming: false,
+  abortController: null,
+  waConnect: null,
+  pendingCompact: false,
+
+  pushUserMessage(content) {
+    const id = uid();
+    set((s) => ({ messages: [...s.messages, { id, role: 'user', content }] }));
+    return id;
+  },
+
+  pushSyntheticAssistant(content, opts) {
+    const id = uid();
+    set((s) => ({
+      messages: [...s.messages, { id, role: 'assistant', content, synthetic: true, error: opts?.error }],
+    }));
+    return id;
+  },
+
+  startAssistantMessage() {
+    const id = uid();
+    set((s) => ({ messages: [...s.messages, { id, role: 'assistant', content: '', streaming: true }] }));
+    return id;
+  },
+
+  appendAssistantText(id, delta) {
+    set((s) => ({
+      messages: s.messages.map((m) => (m.id === id ? { ...m, content: m.content + delta } : m)),
+    }));
+  },
+
+  finishAssistantMessage(id) {
+    set((s) => ({
+      messages: s.messages.map((m) => (m.id === id ? { ...m, streaming: false } : m)),
+    }));
+  },
+
+  startStep(toolName, afterMessageId) {
+    const id = uid();
+    set((s) => ({ steps: [...s.steps, { id, toolName, status: 'running', afterMessageId }] }));
+    return id;
+  },
+
+  resolveLastStep(toolName, status, result, errorMessage) {
+    set((s) => {
+      const idx = [...s.steps].reverse().findIndex((x) => x.toolName === toolName && x.status === 'running');
+      if (idx === -1) return {};
+      const real = s.steps.length - 1 - idx;
+      const updated = [...s.steps];
+      updated[real] = { ...updated[real], status, result, errorMessage };
+      return { steps: updated };
+    });
+  },
+
+  failAllRunningSteps(message) {
+    set((s) => ({
+      steps: s.steps.map((x) =>
+        x.status === 'running' ? { ...x, status: 'error', errorMessage: message ?? 'Cancelado' } : x,
+      ),
+    }));
+  },
+
+  setAgentConfig(cfg) {
+    set({ agentConfig: cfg });
+  },
+
+  setAgentId(id) {
+    set({ agentId: id });
+  },
+
+  addUsage(inT, outT) {
+    set((s) => ({
+      usage: {
+        inputTokens: s.usage.inputTokens + (inT || 0),
+        outputTokens: s.usage.outputTokens + (outT || 0),
+      },
+    }));
+  },
+
+  setStreaming(streaming) {
+    set({ streaming });
+  },
+
+  setAbortController(abortController) {
+    set({ abortController });
+  },
+
+  abortStream() {
+    const ctrl = get().abortController;
+    if (ctrl && !ctrl.signal.aborted) ctrl.abort();
+  },
+
+  startWaConnect(linkData, anchorMessageId) {
+    const id = uid();
+    set({
+      waConnect: {
+        id,
+        linkData,
+        status: 'waiting',
+        anchorMessageId,
+        attempt: 0,
+      },
+    });
+    return id;
+  },
+
+  updateWaConnect(patch) {
+    set((s) => (s.waConnect ? { waConnect: { ...s.waConnect, ...patch } } : {}));
+  },
+
+  setWaStatus(status, extra) {
+    set((s) => (s.waConnect ? { waConnect: { ...s.waConnect, status, ...(extra ?? {}) } } : {}));
+  },
+
+  clearWaConnect() {
+    set({ waConnect: null });
+  },
+
+  clearMessages() {
+    const ctrl = get().abortController;
+    if (ctrl && !ctrl.signal.aborted) ctrl.abort();
+    set({
+      messages: [],
+      steps: [],
+      streaming: false,
+      abortController: null,
+      waConnect: null,
+      pendingCompact: false,
+      // agentConfig, agentId, usage se mantienen para seguir trabajando.
+    });
+  },
+
+  setPendingCompact(v) {
+    set({ pendingCompact: v });
+  },
+
+  compactInto(id) {
+    set((s) => {
+      const summary = s.messages.find((m) => m.id === id);
+      if (!summary || !summary.content.trim()) {
+        return { pendingCompact: false };
+      }
+      const newId = uid();
+      return {
+        messages: [
+          {
+            id: newId,
+            role: 'assistant',
+            content: summary.content,
+          },
+        ],
+        steps: [],
+        waConnect: null,
+        pendingCompact: false,
+      };
+    });
+  },
+
+  reset() {
+    const ctrl = get().abortController;
+    if (ctrl && !ctrl.signal.aborted) ctrl.abort();
+    set({
+      messages: [],
+      steps: [],
+      agentConfig: null,
+      agentId: null,
+      usage: { inputTokens: 0, outputTokens: 0 },
+      streaming: false,
+      abortController: null,
+      waConnect: null,
+      pendingCompact: false,
+    });
+  },
+}));
+
+/**
+ * Construye el array `messages` que se envía al backend a partir del estado.
+ * Filtra mensajes sintéticos (synthetic === true) y los aún en streaming vacíos.
+ */
+export function selectBackendMessages(): { role: 'user' | 'assistant'; content: string }[] {
+  const { messages } = useStudioStore.getState();
+  return messages
+    .filter((m) => !m.synthetic && (m.role === 'user' || m.role === 'assistant') && m.content.trim().length > 0)
+    .map((m) => ({ role: m.role as 'user' | 'assistant', content: m.content }));
+}

package/src/studio/whatsapp/api.ts

@@ -0,0 +1,96 @@
+import { getBaseUrl } from '../api/studioApi.js';
+import type { StudioStreamOptions } from '../api/types.js';
+import type { WorkspaceIntegrationItem } from './types.js';
+
+/**
+ * REST helpers used during the WhatsApp connection polling loop.
+ * Reuses the same zone/dev base URL + Bearer headers as the SSE client.
+ */
+
+interface WorkspaceFetchOpts {
+  apiKey: string;
+  workspaceId: string;
+  zone: 'LA' | 'EU';
+  dev?: boolean;
+  userId?: string;
+}
+
+interface WorkspaceShape {
+  id?: string;
+  integrations?: WorkspaceIntegrationItem[];
+}
+
+function headers(opts: WorkspaceFetchOpts): Record<string, string> {
+  const h: Record<string, string> = {
+    'Content-Type': 'application/json',
+    Authorization: `Bearer ${opts.apiKey}`,
+    'x-workspace-id': opts.workspaceId,
+  };
+  if (opts.userId) h['x-user-id'] = opts.userId;
+  return h;
+}
+
+/**
+ * GET /api/workspace/{workspaceId} — the API returns an array of workspaces
+ * (the front uses `[0]`). Returns the first element or null.
+ */
+export async function getWorkspaceById(
+  opts: WorkspaceFetchOpts,
+  signal?: AbortSignal,
+): Promise<WorkspaceShape | null> {
+  const url = `${getBaseUrl(opts.zone, opts.dev)}/api/workspace/${encodeURIComponent(opts.workspaceId)}`;
+  const res = await fetch(url, { method: 'GET', headers: headers(opts), signal });
+  if (!res.ok) {
+    throw new Error(`GET workspace ${res.status} ${res.statusText}`);
+  }
+  const json = (await res.json()) as WorkspaceShape | WorkspaceShape[] | null;
+  if (!json) return null;
+  if (Array.isArray(json)) return json[0] ?? null;
+  return json;
+}
+
+export interface ActivateResult {
+  success?: boolean;
+  message?: string;
+}
+
+/**
+ * POST /api/workspace/{workspaceId}/integrations/{integrationId}/activate
+ * Body: { isActive: true, platformCode: "whatsapp" }
+ */
+export async function activateIntegration(
+  opts: WorkspaceFetchOpts,
+  integrationId: string,
+  signal?: AbortSignal,
+): Promise<ActivateResult> {
+  const url = `${getBaseUrl(opts.zone, opts.dev)}/api/workspace/${encodeURIComponent(opts.workspaceId)}/integrations/${encodeURIComponent(integrationId)}/activate`;
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: headers(opts),
+    body: JSON.stringify({ isActive: true, platformCode: 'whatsapp' }),
+    signal,
+  });
+  const text = await res.text();
+  let parsed: ActivateResult = {};
+  if (text) {
+    try { parsed = JSON.parse(text) as ActivateResult; } catch { /* not json */ }
+  }
+  if (!res.ok) {
+    return { success: false, message: parsed.message || `HTTP ${res.status} ${res.statusText}` };
+  }
+  return parsed.success === false ? parsed : { success: true, ...parsed };
+}
+
+/** Re-export for callers that need just the auth shape. */
+export type WorkspaceAuthOpts = WorkspaceFetchOpts;
+
+/** Adapter: derives the workspace fetch options from a StudioStreamOptions. */
+export function workspaceOptsFromStream(stream: StudioStreamOptions): WorkspaceAuthOpts {
+  return {
+    apiKey: stream.apiKey,
+    workspaceId: stream.workspaceId,
+    zone: stream.zone,
+    dev: stream.dev,
+    userId: stream.userId,
+  };
+}