@johpaz/hive-sdk 0.0.12 → 0.0.15

package/packages/core/src/agent/ConversationStore.ts

@@ -0,0 +1,244 @@
+/**
+ * Conversation Store — persists message history in the `conversations` table.
+ * Replaces the LangGraph BunSqliteSaver + lg_checkpoints approach.
+ *
+ * Also manages: summaries, scratchpad.
+ */
+
+import { getDb } from "../storage/SQLiteStorage.ts"
+import { logger } from "../utils/logger.ts"
+import type { LLMMessage, ContentPart } from "./providers/LLMClient"
+import { estimateTokens } from "../utils/toon.ts"
+
+const log = logger.child("conv-store")
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface StoredMessage {
+  id: number
+  thread_id: string
+  channel: string
+  role: "user" | "assistant" | "tool" | "system"
+  content: string
+  tool_calls_json: string | null
+  tool_call_id: string | null
+  reasoning_content: string | null  // Kimi K2 thinking — must be round-tripped
+  content_multimodal: string | null // JSON array of ContentPart[]
+  token_count: number
+  created_at: number
+}
+
+// ─── Message operations ───────────────────────────────────────────────────────
+
+export function addMessage(
+  threadId: string,
+  role: StoredMessage["role"],
+  content: string | ContentPart[],
+  opts?: {
+    channel?: string
+    tool_calls?: LLMMessage["tool_calls"]
+    tool_call_id?: string
+    reasoning_content?: string
+  }
+): number {
+  const db = getDb()
+  // Handle multimodal content by extracting text for the content column
+  const textContent = typeof content === "string"
+    ? content
+    : Array.isArray(content)
+      ? content.filter(p => p.type === "text").map(p => (p as any).text).join("\n")
+      : String(content)
+
+  const content_multimodal = Array.isArray(content) ? JSON.stringify(content) : null
+  const tool_calls_json = opts?.tool_calls ? JSON.stringify(opts.tool_calls) : null
+
+  const result = db.query(`
+    INSERT INTO conversations (thread_id, channel, role, content, content_multimodal, tool_calls_json, tool_call_id, reasoning_content, token_count, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, unixepoch())
+    RETURNING id
+  `).get(
+    threadId,
+    opts?.channel ?? "webchat",
+    role,
+    textContent,
+    content_multimodal,
+    tool_calls_json,
+    opts?.tool_call_id ?? null,
+    opts?.reasoning_content ?? null,
+    // Estimate tokens: content + tool_calls JSON
+    Math.max(1, estimateTokens(textContent) + estimateTokens(tool_calls_json ?? "")),
+  ) as { id: number }
+
+  return result.id
+}
+
+/**
+ * Returns all messages for the thread ordered oldest → newest.
+ */
+export function getHistory(threadId: string, limit = 200): StoredMessage[] {
+  const db = getDb()
+  return db.query(`
+    SELECT * FROM conversations
+    WHERE thread_id = ?
+    ORDER BY id ASC
+    LIMIT ?
+  `).all(threadId, limit) as StoredMessage[]
+}
+
+/**
+ * Returns only the last N messages (oldest → newest order),
+ * with leading orphaned tool messages stripped from the window start.
+ *
+ * A tool message is "orphaned" when the assistant message that issued its
+ * tool_call_id is not present in the loaded window (it was compacted away).
+ * Sending orphaned tool messages to the LLM causes provider errors.
+ */
+export function getRecentMessages(threadId: string, n: number): StoredMessage[] {
+  const db = getDb()
+  const rows = db.query(`
+    SELECT * FROM conversations
+    WHERE thread_id = ?
+    ORDER BY id DESC
+    LIMIT ?
+  `).all(threadId, n) as StoredMessage[]
+  return stripLeadingOrphanedTools(rows.reverse())
+}
+
+function stripLeadingOrphanedTools(rows: StoredMessage[]): StoredMessage[] {
+  // Collect all tool_call_ids referenced by assistant messages in this window
+  const knownIds = new Set<string>()
+  for (const r of rows) {
+    if (r.role === "assistant" && r.tool_calls_json) {
+      try {
+        const tcs = JSON.parse(r.tool_calls_json) as Array<{ id: string }>
+        for (const tc of tcs) knownIds.add(tc.id)
+      } catch { /* ignore malformed JSON */ }
+    }
+  }
+
+  // Drop tool messages at the start of the window whose assistant is missing
+  let start = 0
+  while (
+    start < rows.length &&
+    rows[start].role === "tool" &&
+    rows[start].tool_call_id !== null &&
+    !knownIds.has(rows[start].tool_call_id!)
+  ) {
+    start++
+  }
+
+  if (start > 0) {
+    log.warn(`[conv-store] Stripped ${start} leading orphaned tool message(s) from window (tool_call_ids outside window)`)
+  }
+  return start > 0 ? rows.slice(start) : rows
+}
+
+export function getMessageCount(threadId: string): number {
+  const db = getDb()
+  const row = db.query(
+    "SELECT COUNT(*) as cnt FROM conversations WHERE thread_id = ?"
+  ).get(threadId) as { cnt: number }
+  return row.cnt
+}
+
+export function getTotalTokens(threadId: string): number {
+  const db = getDb()
+  const row = db.query(
+    "SELECT COALESCE(SUM(token_count), 0) as total FROM conversations WHERE thread_id = ?"
+  ).get(threadId) as { total: number }
+  return row.total
+}
+
+/**
+ * Messages after a given message ID (for incremental summary updates).
+ */
+export function getMessagesAfter(threadId: string, afterId: number): StoredMessage[] {
+  const db = getDb()
+  return db.query(`
+    SELECT * FROM conversations
+    WHERE thread_id = ? AND id > ?
+    ORDER BY id ASC
+  `).all(threadId, afterId) as StoredMessage[]
+}
+
+// ─── Convert stored messages → LLMMessage array ───────────────────────────────
+
+export function toAPIMessages(rows: StoredMessage[]): LLMMessage[] {
+  return rows.map((r) => {
+    let content: string | ContentPart[] = r.content
+    if (r.content_multimodal) {
+      try { content = JSON.parse(r.content_multimodal) } catch { /* ignore */ }
+    }
+    const msg: LLMMessage = { role: r.role, content }
+    if (r.tool_calls_json) {
+      try { msg.tool_calls = JSON.parse(r.tool_calls_json) } catch { /* ignore */ }
+    }
+    if (r.tool_call_id) msg.tool_call_id = r.tool_call_id
+    if (r.reasoning_content) msg.reasoning_content = r.reasoning_content
+    return msg
+  })
+}
+
+// ─── Summaries ────────────────────────────────────────────────────────────────
+
+export interface Summary {
+  summary: string
+  last_message_id: number
+  messages_covered: number
+}
+
+export function getSummary(threadId: string): Summary | null {
+  const db = getDb()
+  return db.query(
+    "SELECT summary, last_message_id, messages_covered FROM summaries WHERE thread_id = ?"
+  ).get(threadId) as Summary | null
+}
+
+export function saveSummary(
+  threadId: string,
+  summary: string,
+  messagesCovered: number,
+  lastMessageId: number
+): void {
+  const db = getDb()
+  db.query(`
+    INSERT INTO summaries (thread_id, summary, messages_covered, last_message_id)
+    VALUES (?, ?, ?, ?)
+    ON CONFLICT(thread_id) DO UPDATE SET
+      summary        = excluded.summary,
+      messages_covered = excluded.messages_covered,
+      last_message_id  = excluded.last_message_id,
+      updated_at       = unixepoch()
+  `).run(threadId, summary, messagesCovered, lastMessageId)
+}
+
+// ─── Scratchpad ───────────────────────────────────────────────────────────────
+
+export function saveScratchpadNote(
+  threadId: string,
+  key: string,
+  value: string,
+  source?: string
+): void {
+  const db = getDb()
+  db.query(`
+    INSERT INTO scratchpad (thread_id, key, value, source)
+    VALUES (?, ?, ?, ?)
+    ON CONFLICT(thread_id, key) DO UPDATE SET
+      value      = excluded.value,
+      source     = excluded.source,
+      updated_at = unixepoch()
+  `).run(threadId, key, value, source ?? null)
+}
+
+export function getScratchpad(threadId: string): Array<{ key: string; value: string }> {
+  const db = getDb()
+  return db.query(
+    "SELECT key, value FROM scratchpad WHERE thread_id = ? ORDER BY updated_at DESC"
+  ).all(threadId) as Array<{ key: string; value: string }>
+}
+
+export function deleteScratchpadNote(threadId: string, key: string): void {
+  const db = getDb()
+  db.query("DELETE FROM scratchpad WHERE thread_id = ? AND key = ?").run(threadId, key)
+}

package/packages/core/src/agent/Hooks.ts

@@ -0,0 +1,166 @@
+import type { Config } from "../config/loader.ts";
+import { logger } from "../utils/logger.ts";
+import * as childProcess from "node:child_process";
+
+export type HookName =
+  | "before_model_resolve"
+  | "before_prompt_build"
+  | "before_tool_call"
+  | "after_tool_call"
+  | "tool_result_persist"
+  | "before_compaction"
+  | "after_compaction"
+  | "message_received"
+  | "message_sending"
+  | "message_sent"
+  | "session_start"
+  | "session_end"
+  | "gateway_start"
+  | "gateway_stop";
+
+export interface HookContext {
+  sessionId?: string;
+  agentId?: string;
+  data?: Record<string, unknown>;
+  timestamp: Date;
+}
+
+export type HookHandler = (context: HookContext) => Promise<Record<string, unknown> | void>;
+
+export class HookPipeline {
+  private config: Config;
+  private log = logger.child("hooks");
+  private handlers: Map<HookName, HookHandler[]> = new Map();
+  private scriptCache: Map<HookName, string> = new Map();
+
+  constructor(config: Config) {
+    this.config = config;
+    this.loadScripts();
+  }
+
+  private loadScripts(): void {
+    const scripts = this.config.hooks?.scripts;
+    if (!scripts) return;
+
+    const hookNames: HookName[] = [
+      "before_model_resolve",
+      "before_prompt_build",
+      "before_tool_call",
+      "after_tool_call",
+      "tool_result_persist",
+      "before_compaction",
+      "after_compaction",
+      "message_received",
+      "message_sending",
+      "message_sent",
+      "session_start",
+      "session_end",
+      "gateway_start",
+      "gateway_stop",
+    ];
+
+    for (const name of hookNames) {
+      const script = scripts[name];
+      if (script) {
+        this.scriptCache.set(name, script);
+        this.log.debug(`Loaded script for hook: ${name}`);
+      }
+    }
+  }
+
+  registerHandler(name: HookName, handler: HookHandler): void {
+    const handlers = this.handlers.get(name) ?? [];
+    handlers.push(handler);
+    this.handlers.set(name, handlers);
+    this.log.debug(`Registered handler for hook: ${name}`);
+  }
+
+  unregisterHandler(name: HookName, handler: HookHandler): boolean {
+    const handlers = this.handlers.get(name);
+    if (!handlers) return false;
+
+    const index = handlers.indexOf(handler);
+    if (index >= 0) {
+      handlers.splice(index, 1);
+      return true;
+    }
+    return false;
+  }
+
+  async execute(name: HookName, context: HookContext): Promise<Record<string, unknown> | void> {
+    this.log.debug(`Executing hook: ${name}`, { sessionId: context.sessionId });
+
+    const handlers = this.handlers.get(name) ?? [];
+    for (const handler of handlers) {
+      try {
+        await handler(context);
+      } catch (error) {
+        this.log.error(`Handler failed for ${name}: ${(error as Error).message}`);
+      }
+    }
+
+    const script = this.scriptCache.get(name);
+    if (script) {
+      try {
+        const result = await this.executeScript(script, context);
+        return result;
+      } catch (error) {
+        this.log.error(`Script failed for ${name}: ${(error as Error).message}`);
+      }
+    }
+  }
+
+  private async executeScript(
+    scriptPath: string,
+    context: HookContext
+  ): Promise<Record<string, unknown> | void> {
+    return new Promise((resolve, reject) => {
+      const payload = JSON.stringify(context);
+
+      const proc = childProcess.spawn(scriptPath, [], {
+        stdio: ["pipe", "pipe", "pipe"],
+        shell: true,
+      }) as any;
+
+      let stdout = "";
+      let stderr = "";
+
+      proc.stdout?.on("data", (data) => {
+        stdout += data.toString();
+      });
+
+      proc.stderr?.on("data", (data) => {
+        stderr += data.toString();
+      });
+
+      proc.on("close", (code) => {
+        if (code === 0 && stdout) {
+          try {
+            resolve(JSON.parse(stdout));
+          } catch {
+            resolve();
+          }
+        } else if (stderr) {
+          reject(new Error(stderr));
+        } else {
+          resolve();
+        }
+      });
+
+      proc.on("error", (error) => {
+        reject(error);
+      });
+
+      proc.stdin?.write(payload);
+      proc.stdin?.end();
+    });
+  }
+
+  hasHandlers(name: HookName): boolean {
+    return (this.handlers.get(name)?.length ?? 0) > 0 || this.scriptCache.has(name);
+  }
+}
+
+export function createHookPipeline(config: Config): HookPipeline {
+  return new HookPipeline(config);
+}

package/packages/core/src/agent/NativeTools.ts

@@ -0,0 +1,31 @@
+/**
+ * Native Tools Type Definitions
+ * 
+ * Tool interface for native Hive tools (no LangChain)
+ */
+
+export interface Tool {
+  name: string
+  description: string
+  parameters: {
+    type: "object"
+    properties: Record<string, ToolParameter>
+    required?: string[]
+  }
+  execute: (params: Record<string, unknown>, config?: any) => Promise<string | object>
+}
+
+export interface ToolParameter {
+  type: string
+  description?: string
+  enum?: string[]
+  items?: ToolParameter
+  properties?: Record<string, ToolParameter>
+  required?: string[]
+}
+
+export interface ToolResult {
+  success: boolean
+  result?: any
+  error?: string
+}

package/packages/core/src/agent/PromptBuilder.ts

@@ -0,0 +1,169 @@
+/**
+ * Prompt Builder — Construye el system prompt con la jerarquía constitucional.
+ *
+ * Orden de ensamblaje:
+ * 1. ÉTICA (capa constitucional, siempre completa, inmutable)
+ * 2. IDENTIDAD DEL AGENTE (de la tabla agents)
+ * 3. HIVE ECOSYSTEM (system prompt directo para el coordinador)
+ * 4. IDENTIDAD DEL USUARIO (de la tabla users)
+ *
+ * El Context Compiler agrega después:
+ * - Playbook rules (ACE)
+ * - Scratchpad notes
+ * - Skills activos
+ */
+
+import { getDb } from "../storage/SQLiteStorage.ts"
+import { logger } from "../utils/logger.ts"
+import { formatContext } from "../utils/toon.ts"
+import { resolveUserId } from "../storage/onboarding.ts"
+
+const log = logger.child("prompt-builder")
+
+export interface BuildSystemPromptOpts {
+  agentId: string
+  userId: string
+}
+
+/**
+ * Construye el system prompt completo para un agente.
+ *
+ * Jerarquía:
+ * 1. Ética (siempre completa, no se filtra, no se comprime)
+ * 2. Identidad del agente (role, description, system_prompt)
+ * 3. Hive Ecosystem (ya incluido en agents.system_prompt desde onboarding.ts)
+ * 4. Identidad del usuario (nombre, preferencias, contexto)
+ */
+export async function buildSystemPrompt(opts: BuildSystemPromptOpts): Promise<string> {
+  const db = getDb()
+  const { agentId, userId } = opts
+
+  // ──────────────────────────────────────────────────────────────────────────
+  // 1. ÉTICA — Capa constitucional (siempre completa)
+  // ──────────────────────────────────────────────────────────────────────────
+  const ethicsRules = db.query<any, []>(`
+    SELECT name, content, description
+    FROM ethics
+    WHERE enabled = 1 AND active = 1
+    ORDER BY is_default DESC, id ASC
+  `).all()
+
+  let ethicsSection = ""
+  if (ethicsRules.length > 0) {
+    const ethicsContent = ethicsRules.map((rule: any) => {
+      return `## ${rule.name}\n${rule.content}`
+    }).join("\n\n")
+
+    ethicsSection = `# ÉTICA Y REGLAS CONSTITUCIONALES\n\n${ethicsContent}\n\n`
+    log.info(`[prompt-builder] Loaded ${ethicsRules.length} ethics rules`)
+  } else {
+    // Ética por defecto si no hay reglas configuradas
+    ethicsSection = `# ÉTICA Y REGLAS CONSTITUCIONALES\n\n` +
+      `- Sé útil, inofensivo y honesto\n` +
+      `- No generes contenido dañino, ilegal o peligroso\n` +
+      `- Respeta la privacidad y seguridad del usuario\n` +
+      `- Si no sabes algo, admítelo\n\n`
+  }
+
+  // ──────────────────────────────────────────────────────────────────────────
+  // 2. IDENTIDAD DEL AGENTE
+  // ──────────────────────────────────────────────────────────────────────────
+  const agent = db.query<any, [string]>(`
+    SELECT id, name, role, description, system_prompt, tone, max_iterations, workspace
+    FROM agents
+    WHERE id = ?
+  `).get(agentId)
+
+  if (!agent) {
+    throw new Error(`Agent not found: ${agentId}`)
+  }
+
+  let agentSection = `# IDENTIDAD DEL AGENTE\n\n`
+  agentSection += `**Nombre**: ${agent.name}\n`
+  agentSection += `**Rol**: ${agent.role}\n`
+
+  if (agent.description) {
+    agentSection += `**Descripción**: ${agent.description}\n`
+  }
+
+  if (agent.tone) {
+    agentSection += `**Tono**: ${agent.tone}\n`
+  }
+
+  agentSection += `**Iteraciones máximas**: ${agent.max_iterations}\n\n`
+
+  // Workspace configuration
+  const workspacePath = agent.workspace || null
+  if (workspacePath) {
+    agentSection += `# WORKSPACE — ESPACIO DE TRABAJO EXCLUSIVO\n\n`
+    agentSection += `**Tu directorio de trabajo es**: \`${workspacePath}\`\n\n`
+    agentSection += `## REGLAS OBLIGATORIAS (no negociables)\n\n`
+    agentSection += `1. **TODAS** tus operaciones de archivos y comandos ocurren DENTRO de \`${workspacePath}\`. Sin excepciones.\n`
+    agentSection += `2. Cuando el sistema te pida listar archivos, explorar, leer o escribir — hazlo SIEMPRE dentro de \`${workspacePath}\`.\n`
+    agentSection += `3. Nunca uses \`ls\`, \`find\`, \`cat\` u otras herramientas apuntando a directorios del sistema (\`/\`, \`~\`, \`/home\`, \`/etc\`, etc.).\n`
+    agentSection += `4. Cuando uses \`cli_exec\`, el directorio de trabajo ya es \`${workspacePath}\` por defecto — NO necesitas especificar \`cwd\`.\n`
+    agentSection += `5. Para rutas relativas, son relativas a \`${workspacePath}\` — no al directorio del proceso.\n`
+    agentSection += `6. Si el usuario pide explorar "el proyecto" o "los archivos", asume que se refiere a \`${workspacePath}\`.\n`
+    agentSection += `7. Las tools de filesystem (\`fs_read\`, \`fs_write\`, \`fs_list\`, etc.) ya tienen tu workspace configurado — úsalas directamente con rutas relativas.\n\n`
+    agentSection += `> IMPORTANTE: Cualquier intento de acceder fuera de \`${workspacePath}\` será bloqueado automáticamente por el sistema.\n\n`
+    agentSection += `## CONSULTAS EN MCP, para llamar datos puedes buscar las tools por get o list recors\n\n`
+
+  }
+
+  // System prompt específico del agente (su "personalidad" especializada)
+  if (agent.system_prompt) {
+    agentSection += `## System Prompt\n\n${agent.system_prompt}\n\n`
+  }
+
+
+  // ──────────────────────────────────────────────────────────────────────────
+  // 3. IDENTIDAD DEL USUARIO
+  // ──────────────────────────────────────────────────────────────────────────
+  const user = db.query<any, [string]>(`
+    SELECT id, name, language,  timezone, occupation, notes
+    FROM users
+    WHERE id = ?
+  `).get(userId)
+
+  let userSection = `# IDENTIDAD DEL USUARIO\n\n`
+
+  if (user) {
+    const userData: Record<string, string | null> = {}
+
+    if (user.name) userData.Nombre = user.name
+    if (user.language) userData.Idioma = user.language
+    if (user.timezone) userData.ZonaHoraria = user.timezone
+    if (user.occupation) userData.Ocupación = user.occupation
+    if (user.notes) userData.Notes = user.notes
+
+    // Usar TOON para comprimir datos del usuario
+    if (Object.keys(userData).length > 0) {
+      userSection += formatContext(userData) + "\n\n"
+    } else {
+      userSection += `Usuario ID: ${userId}\n\n`
+    }
+  } else {
+    userSection += `Usuario ID: ${userId}\n\n`
+  }
+
+  // ──────────────────────────────────────────────────────────────────────────
+  // Ensamblar secciones en orden
+  // ──────────────────────────────────────────────────────────────────────────
+  const systemPrompt = `${ethicsSection}${agentSection}${userSection}`.trim()
+
+  log.info(`[prompt-builder] Built system prompt for agent=${agent.name} role=${agent.role}`)
+
+  return systemPrompt
+}
+
+/**
+ * Versión simplificada para cuando solo se necesita el agentId
+ * (usa userId por defecto de env o threadId)
+ */
+export async function buildSystemPromptWithProjects(opts: {
+  agentId: string
+  userId?: string
+}): Promise<string> {
+  const userId = opts.userId || resolveUserId({}) || "default"
+  return buildSystemPrompt({ agentId: opts.agentId, userId })
+}