@johpaz/hive-agents 0.0.34 → 0.0.36

package/packages/core/src/gateway/session.ts

@@ -0,0 +1,95 @@
+import type { ServerWebSocket } from "bun";
+
+export interface SessionId {
+  userId: string;
+}
+
+export function parseSessionId(sessionId: string): SessionId | null {
+  if (!sessionId || sessionId.trim() === "") {
+    return null;
+  }
+  return { userId: sessionId };
+}
+
+export function formatSessionId(session: SessionId): string {
+  return session.userId;
+}
+
+export interface Session {
+  id: string;
+  parsed: SessionId;
+  createdAt: Date;
+  lastActivityAt: Date;
+  messageCount: number;
+  ws?: ServerWebSocket<unknown>;
+}
+
+export class SessionManager {
+  private sessions: Map<string, Session> = new Map();
+
+  create(sessionId: string, ws?: ServerWebSocket<unknown>): Session {
+    const parsed = parseSessionId(sessionId);
+    if (!parsed) {
+      throw new Error(`Invalid session ID: ${sessionId}`);
+    }
+
+    const existing = this.sessions.get(sessionId);
+    if (existing) {
+      existing.lastActivityAt = new Date();
+      if (ws) {
+        existing.ws = ws;
+      }
+      return existing;
+    }
+
+    const session: Session = {
+      id: sessionId,
+      parsed,
+      createdAt: new Date(),
+      lastActivityAt: new Date(),
+      messageCount: 0,
+    };
+    if (ws !== undefined) {
+      session.ws = ws;
+    }
+
+    this.sessions.set(sessionId, session);
+    return session;
+  }
+
+  get(sessionId: string): Session | undefined {
+    return this.sessions.get(sessionId);
+  }
+
+  touch(sessionId: string): void {
+    const session = this.sessions.get(sessionId);
+    if (session) {
+      session.lastActivityAt = new Date();
+      session.messageCount++;
+    }
+  }
+
+  delete(sessionId: string): boolean {
+    return this.sessions.delete(sessionId);
+  }
+
+  list(): Session[] {
+    return Array.from(this.sessions.values());
+  }
+
+  prune(maxAgeMs: number): number {
+    const now = Date.now();
+    let pruned = 0;
+
+    for (const [id, session] of this.sessions) {
+      if (now - session.lastActivityAt.getTime() > maxAgeMs) {
+        this.sessions.delete(id);
+        pruned++;
+      }
+    }
+
+    return pruned;
+  }
+}
+
+export const sessionManager = new SessionManager();

package/packages/core/src/gateway/slash-commands.ts

@@ -0,0 +1,207 @@
+import type { ServerWebSocket } from "bun";
+import { sessionManager } from "./session.ts";
+import { laneQueue } from "./lane-queue.ts";
+import { logger } from "../utils/logger.ts";
+
+export interface InboundMessage {
+  type: "message" | "command" | "ping" | "join" | "canvas_subscribe" | "canvas_unsubscribe" | "logs_subscribe" | "logs_unsubscribe" | "audio" | "canvas:interact" | "a2ui:action" | "stop";
+  sessionId: string;
+  content?: string;
+  audio?: string;
+  command?: string;
+  args?: string[];
+  metadata?: Record<string, unknown>;
+  componentId?: string;
+  data?: Record<string, unknown>;
+  action?: string;
+  image?: {
+    base64: string;
+    mimeType?: string;
+    caption?: string;
+  };
+  document?: {
+    base64: string;
+    mimeType?: string;
+    fileName?: string;
+  };
+}
+
+export interface OutboundMessage {
+  type: "message" | "stream" | "status" | "error" | "pong" | "command_result" | "joined" | "typing" | "audio" | "welcome" | "progress";
+  sessionId: string;
+  id?: string; // Message ID for streaming
+  content?: string;
+  chunk?: string;
+  isChunk?: boolean; // True if this is a streaming chunk
+  isLast?: boolean;
+  isTyping?: boolean;
+  isStep?: boolean;
+  stepType?: "plan" | "tool_call" | "tool_result" | "text";
+  status?: {
+    state: string;
+    model?: string;
+    tokens?: number;
+  };
+  error?: string;
+  result?: unknown;
+  audio?: string; // Base64 encoded audio
+  mimeType?: string; // Audio MIME type
+  // Welcome message fields
+  user?: {
+    id: string;
+    name: string;
+    language: string;
+  } | null;
+  agent?: {
+    id: string;
+    name: string;
+    provider: string;
+    model: string;
+  } | null;
+  channels?: string[];
+  voice?: {
+    enabled: boolean;
+    sttProvider: string | null;
+    ttsProvider: string | null;
+  };
+}
+
+export interface SlashCommand {
+  name: string;
+  description: string;
+  handler: (sessionId: string, args: string[], ws: ServerWebSocket<unknown>) => Promise<unknown>;
+}
+
+const slashCommands = new Map<string, SlashCommand>();
+
+export function registerSlashCommand(command: SlashCommand): void {
+  slashCommands.set(command.name, command);
+}
+
+export function isSlashCommand(content: string): boolean {
+  return content.startsWith("/") && content.length > 1;
+}
+
+export function parseSlashCommand(content: string): { name: string; args: string[] } | null {
+  if (!isSlashCommand(content)) return null;
+
+  const parts = content.slice(1).split(/\s+/);
+  const name = parts[0]?.toLowerCase();
+  if (!name) return null;
+
+  return {
+    name,
+    args: parts.slice(1),
+  };
+}
+
+export async function executeSlashCommand(
+  sessionId: string,
+  content: string,
+  ws: ServerWebSocket<unknown>
+): Promise<OutboundMessage | null> {
+  const parsed = parseSlashCommand(content);
+  if (!parsed) {
+    return null;
+  }
+
+  const command = slashCommands.get(parsed.name);
+  if (!command) {
+    return null;
+  }
+
+  logger.info(`Executing slash command: /${parsed.name}`, { sessionId, args: parsed.args });
+
+  try {
+    const result = await command.handler(sessionId, parsed.args, ws);
+    return {
+      type: "command_result",
+      sessionId,
+      result,
+    };
+  } catch (error) {
+    logger.error(`Slash command failed: /${parsed.name}`, { error: (error as Error).message });
+    return {
+      type: "error",
+      sessionId,
+      error: (error as Error).message,
+    };
+  }
+}
+
+registerSlashCommand({
+  name: "stop",
+  description: "Stop the current task",
+  handler: async (sessionId) => {
+    const cancelled = laneQueue.cancel(sessionId);
+    return {
+      success: cancelled,
+      message: cancelled ? "Task stopped" : "No task running",
+    };
+  },
+});
+
+registerSlashCommand({
+  name: "status",
+  description: "Show session status",
+  handler: async (sessionId) => {
+    const session = sessionManager.get(sessionId);
+    const queueStatus = laneQueue.getStatus(sessionId);
+
+    return {
+      sessionId,
+      createdAt: session?.createdAt,
+      messageCount: session?.messageCount,
+      queueLength: queueStatus.queueLength,
+      isProcessing: queueStatus.running !== undefined,
+    };
+  },
+});
+
+registerSlashCommand({
+  name: "new",
+  description: "Start a new session",
+  handler: async (sessionId) => {
+    sessionManager.delete(sessionId);
+    return { success: true, message: "Session reset" };
+  },
+});
+
+registerSlashCommand({
+  name: "compact",
+  description: "Force context compaction",
+  handler: async (sessionId) => {
+    logger.info(`Compaction requested for session: ${sessionId}`);
+    return { success: true, message: "Compaction triggered" };
+  },
+});
+
+registerSlashCommand({
+  name: "reset",
+  description: "Reset the current context",
+  handler: async (sessionId) => {
+    logger.info(`Context reset requested for session: ${sessionId}`);
+    return { success: true, message: "Context reset" };
+  },
+});
+
+registerSlashCommand({
+  name: "model",
+  description: "Switch model for this session",
+  handler: async (_sessionId, args) => {
+    const modelName = args[0];
+    if (!modelName) {
+      return { success: false, message: "Usage: /model <model-name>" };
+    }
+    return { success: true, message: `Model switched to: ${modelName}` };
+  },
+});
+
+registerSlashCommand({
+  name: "help",
+  description: "Show available commands",
+  handler: async () => {
+    const commands = Array.from(slashCommands.values()).map((c) => `/${c.name} - ${c.description}`);
+    return { commands };
+  },
+});

package/packages/core/src/gateway/tts/README.md

@@ -0,0 +1,94 @@
+# @johpaz/hive-tts
+
+Síntesis de voz **local y offline** para Hive, basada en [Piper TTS](https://github.com/rhasspy/piper).
+
+## ¿Cuándo usarlo?
+
+Este paquete es un **fallback opcional**. Hive usa primero los providers de voz configurados (ElevenLabs, OpenAI TTS, etc.). Este módulo se activa cuando:
+
+- No hay conexión a internet
+- No hay providers de voz configurados
+- El usuario prefiere procesamiento 100% local y privado
+- `packages/hivelearn` necesita generar archivos de audio narrados en el servidor (descargables, pre-generados para canales no-browser como Telegram/Discord)
+
+> **Nota:** En el browser, `packages/hivelearn` usa Web Speech API para reproducción interactiva. Este paquete es el complemento **server-side** para generación de archivos WAV.
+
+## Instalación
+
+```bash
+bun add @johpaz/hive-tts
+```
+
+El postinstall descarga automáticamente:
+- Binario de Piper (~8MB) para tu plataforma (Linux/Windows/macOS)
+- Modelo de voz español `es_ES-sharvard-medium` (~60MB)
+
+Solo se descarga una vez. Si falla por falta de internet, reintenta con:
+
+```bash
+bun run packages/tts/src/install.ts
+```
+
+## Uso
+
+### Iniciar el servidor TTS
+
+```bash
+bun run packages/tts/src/server.ts
+# Puerto custom:
+TTS_PORT=5501 bun run packages/tts/src/server.ts
+```
+
+### Desde packages/hivelearn
+
+```typescript
+import { isTTSAvailable, synthesizeToFile } from "@johpaz/hive-tts/client"
+
+if (await isTTSAvailable()) {
+  await synthesizeToFile(
+    "Bienvenido al módulo de álgebra lineal.",
+    "./lessons/intro.wav"
+  )
+}
+```
+
+### API HTTP directa
+
+```bash
+# Health check
+curl http://localhost:5500/health
+
+# Generar audio
+curl -X POST http://localhost:5500/tts \
+  -H "Content-Type: application/json" \
+  -d '{"text": "Hive está procesando tu solicitud."}' \
+  --output audio.wav
+
+# Reproducir (Linux)
+aplay audio.wav
+```
+
+## Variables de entorno
+
+| Variable   | Default                 | Descripción              |
+|------------|-------------------------|--------------------------|
+| `TTS_PORT` | `5500`                  | Puerto del servidor HTTP |
+| `TTS_VOICE`| `es_ES-sharvard-medium` | Voz por defecto          |
+| `TTS_URL`  | `http://localhost:5500` | URL para el cliente      |
+
+## Plataformas soportadas
+
+| Plataforma | Arquitectura | Estado      |
+|------------|-------------|-------------|
+| Linux      | x64         | ✅ Testeado  |
+| Linux      | arm64       | ✅ Soportado |
+| Windows    | x64         | ✅ Soportado |
+| macOS      | x64 (Intel) | ✅ Soportado |
+| macOS      | arm64 (M*)  | ✅ Soportado |
+
+## Voces adicionales
+
+Para instalar más voces, descargar manualmente desde:
+https://huggingface.co/rhasspy/piper-voices
+
+Colocar los archivos `.onnx` y `.onnx.json` en `packages/tts/voices/`.

package/packages/core/src/gateway/tts/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@johpaz/hive-tts",
+  "version": "0.1.0",
+  "description": "Offline local TTS for Hive — Piper-based fallback when no internet providers available",
+  "module": "src/index.ts",
+  "main": "src/index.ts",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./client": "./src/client.ts",
+    "./server": "./src/server.ts",
+    "./models": "./src/models.ts"
+  },
+  "scripts": {
+    "postinstall": "bun run src/install.ts",
+    "start": "bun run src/server.ts",
+    "dev": "bun --watch src/server.ts"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "keywords": ["hive", "tts", "offline", "piper", "voice", "spanish"],
+  "license": "MIT"
+}

package/packages/core/src/gateway/tts/src/client.ts

@@ -0,0 +1,59 @@
+/**
+ * Hive TTS Client
+ * No bloqueante: si TTS no está disponible, las funciones retornan null silenciosamente.
+ */
+
+const TTS_URL = process.env.TTS_URL ?? "http://localhost:5500"
+
+export async function isTTSAvailable(): Promise<boolean> {
+  try {
+    const res = await fetch(`${TTS_URL}/health`, {
+      signal: AbortSignal.timeout(500),
+    })
+    return res.ok
+  } catch {
+    return false
+  }
+}
+
+export async function synthesize(
+  text: string,
+  voice?: string
+): Promise<ArrayBuffer | null> {
+  try {
+    const res = await fetch(`${TTS_URL}/tts`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ text, voice }),
+      signal: AbortSignal.timeout(10_000),
+    })
+    if (!res.ok) return null
+    return res.arrayBuffer()
+  } catch {
+    return null
+  }
+}
+
+export async function synthesizeToFile(
+  text: string,
+  outputPath: string,
+  voice?: string
+): Promise<boolean> {
+  const audio = await synthesize(text, voice)
+  if (!audio) return false
+  await Bun.write(outputPath, audio)
+  return true
+}
+
+export async function listVoices(): Promise<string[]> {
+  try {
+    const res = await fetch(`${TTS_URL}/voices`, {
+      signal: AbortSignal.timeout(500),
+    })
+    if (!res.ok) return []
+    const data = await res.json()
+    return data.voices ?? []
+  } catch {
+    return []
+  }
+}

package/packages/core/src/gateway/tts/src/detect.ts

@@ -0,0 +1,42 @@
+export type Platform =
+  | "linux-x64"
+  | "linux-arm64"
+  | "windows-x64"
+  | "macos-x64"
+  | "macos-arm64"
+
+export function detectPlatform(): Platform {
+  const os = process.platform
+  const arch = process.arch
+
+  if (os === "linux" && arch === "x64") return "linux-x64"
+  if (os === "linux" && arch === "arm64") return "linux-arm64"
+  if (os === "win32" && arch === "x64") return "windows-x64"
+  if (os === "darwin" && arch === "x64") return "macos-x64"
+  if (os === "darwin" && arch === "arm64") return "macos-arm64"
+
+  throw new Error(`Plataforma no soportada: ${os}/${arch}`)
+}
+
+const PIPER_VERSION = "2023.11.14-2"
+const PIPER_BASE_URL = `https://github.com/rhasspy/piper/releases/download/${PIPER_VERSION}`
+
+export const PIPER_URLS: Record<Platform, string> = {
+  "linux-x64": `${PIPER_BASE_URL}/piper_linux_x86_64.tar.gz`,
+  "linux-arm64": `${PIPER_BASE_URL}/piper_linux_aarch64.tar.gz`,
+  "windows-x64": `${PIPER_BASE_URL}/piper_windows_amd64.zip`,
+  "macos-x64": `${PIPER_BASE_URL}/piper_macos_x86_64.tar.gz`,
+  "macos-arm64": `${PIPER_BASE_URL}/piper_macos_aarch64.tar.gz`,
+}
+
+export function getPiperBinaryName(platform: Platform): string {
+  return platform.startsWith("windows") ? "piper.exe" : "piper"
+}
+
+export const DEFAULT_VOICE = "es_MX-claude-14947-epoch-high"
+export const VOICE_BASE_URL =
+  "https://huggingface.co/spaces/HirCoir/Piper-TTS-Spanish"
+export const VOICE_URLS = {
+  model: `${VOICE_BASE_URL}/resolve/main/es_MX-claude-14947-epoch-high.onnx`,
+  config: `${VOICE_BASE_URL}/resolve/main/es_MX-claude-14947-epoch-high.onnx.json`,
+}

package/packages/core/src/gateway/tts/src/index.ts

@@ -0,0 +1,15 @@
+/**
+ * @johpaz/hive-tts
+ *
+ * Paquete standalone opcional para síntesis de voz offline en Hive.
+ * Fallback local cuando no hay internet o no hay providers configurados.
+ *
+ * Iniciar servidor:
+ *   bun run packages/core/src/gateway/tts/src/server.ts
+ *
+ * Uso:
+ *   import { isTTSAvailable, synthesize } from "@johpaz/hive-tts/client"
+ */
+
+export * from "./client.js"
+export { detectPlatform } from "./detect.js"

package/packages/core/src/gateway/tts/src/install.ts

@@ -0,0 +1,129 @@
+#!/usr/bin/env bun
+/**
+ * Hive TTS — instalador de Piper
+ * Los datos se guardan en $HIVE_HOME/tts/ (por defecto ~/.hive/tts/).
+ */
+
+import { existsSync, mkdirSync, readdirSync, renameSync } from "fs"
+import { join } from "path"
+import { homedir } from "os"
+import {
+  detectPlatform,
+  PIPER_URLS,
+  VOICE_URLS,
+  getPiperBinaryName,
+  DEFAULT_VOICE,
+} from "./detect.js"
+
+const log = {
+  info: (msg: string) => console.log(`[TTS] ${msg}`),
+  warn: (msg: string) => console.warn(`[TTS] ${msg}`),
+  error: (msg: string) => console.error(`[TTS] ${msg}`),
+}
+
+async function downloadFile(url: string, dest: string): Promise<void> {
+  const filename = url.split("/").pop()!
+  log.info(`Descargando ${filename}...`)
+  const res = await fetch(url)
+  if (!res.ok) throw new Error(`HTTP ${res.status} al descargar ${url}`)
+  const buf = await res.arrayBuffer()
+  await Bun.write(dest, buf)
+  log.info(`${filename} — ${(buf.byteLength / 1024 / 1024).toFixed(1)} MB`)
+}
+
+async function extractTarGz(archivePath: string, destDir: string): Promise<void> {
+  const code = await Bun.spawn(["tar", "-xzf", archivePath, "-C", destDir], {
+    stdout: "inherit",
+    stderr: "inherit",
+  }).exited
+  if (code !== 0) throw new Error(`tar falló con código ${code}`)
+  await Bun.spawn(["rm", "-f", archivePath]).exited
+}
+
+async function extractZip(archivePath: string, destDir: string): Promise<void> {
+  const code = await Bun.spawn(["unzip", "-q", archivePath, "-d", destDir], {
+    stdout: "inherit",
+    stderr: "inherit",
+  }).exited
+  if (code !== 0) throw new Error(`unzip falló con código ${code}`)
+  await Bun.spawn(["rm", "-f", archivePath]).exited
+}
+
+/**
+ * Instala Piper TTS en el directorio indicado.
+ * Exportado para llamarse inline desde el gateway sin necesidad de un script externo.
+ */
+export async function runInstall(ttsRoot: string): Promise<void> {
+  const BIN_DIR = join(ttsRoot, "bin")
+  const VOICES_DIR = join(ttsRoot, "voices")
+
+  mkdirSync(BIN_DIR, { recursive: true })
+  mkdirSync(VOICES_DIR, { recursive: true })
+
+  // ── Piper binary ──────────────────────────────────────────────────────────
+  const platform = detectPlatform()
+  const binaryName = getPiperBinaryName(platform)
+  const binaryPath = join(BIN_DIR, binaryName)
+
+  if (!existsSync(binaryPath)) {
+    const url = PIPER_URLS[platform]
+    const archiveExt = url.endsWith(".zip") ? ".zip" : ".tar.gz"
+    const archivePath = join(BIN_DIR, `piper${archiveExt}`)
+
+    log.info(`Instalando Piper para ${platform}...`)
+    await downloadFile(url, archivePath)
+    log.info("Extrayendo...")
+    if (archiveExt === ".zip") {
+      await extractZip(archivePath, BIN_DIR)
+    } else {
+      await extractTarGz(archivePath, BIN_DIR)
+    }
+
+    const piperSubdir = join(BIN_DIR, "piper")
+    if (existsSync(piperSubdir)) {
+      const tempDir = join(BIN_DIR, "_piper_tmp")
+      renameSync(piperSubdir, tempDir)
+      for (const entry of readdirSync(tempDir)) {
+        renameSync(join(tempDir, entry), join(BIN_DIR, entry))
+      }
+      await Bun.spawn(["rm", "-rf", tempDir]).exited
+    }
+
+    if (!existsSync(binaryPath)) {
+      throw new Error(`Binario no encontrado tras extracción: ${binaryPath}`)
+    }
+    if (!platform.startsWith("windows")) {
+      await Bun.spawn(["chmod", "+x", binaryPath]).exited
+    }
+    log.info(`Piper instalado en ${BIN_DIR}`)
+  } else {
+    log.info("Piper ya instalado, omitiendo descarga.")
+  }
+
+  // ── Voice model ───────────────────────────────────────────────────────────
+  const modelPath = join(VOICES_DIR, `${DEFAULT_VOICE}.onnx`)
+  const configPath = join(VOICES_DIR, `${DEFAULT_VOICE}.onnx.json`)
+
+  if (!existsSync(modelPath) || !existsSync(configPath)) {
+    log.info(`Descargando modelo de voz ${DEFAULT_VOICE}...`)
+    await downloadFile(VOICE_URLS.model, modelPath)
+    await downloadFile(VOICE_URLS.config, configPath)
+    log.info(`Voz instalada en ${VOICES_DIR}`)
+  } else {
+    log.info("Modelo de voz ya instalado, omitiendo descarga.")
+  }
+
+  log.info("Hive TTS listo.")
+}
+
+// Ejecución directa: bun run src/install.ts
+// @ts-ignore
+if (import.meta.main) {
+  const ttsRoot =
+    process.env.HIVE_TTS_ROOT ??
+    join(process.env.HIVE_HOME ?? join(homedir(), ".hive"), "tts")
+  runInstall(ttsRoot).catch((err) => {
+    log.error(`Hive TTS no pudo instalarse: ${err instanceof Error ? err.message : err}`)
+    process.exit(1)
+  })
+}