@johpaz/hive-sdk 0.1.6 → 0.3.0

package/packages/core/src/skills/bundled/web/browser_automate/SKILL.md

@@ -8,7 +8,7 @@ category: web
 permissions:
   - browser_control
 dependencies: []
-tools: [browser_navigate, browser_click, browser_type, browser_screenshot]
+tools: [browser_navigate, browser_wait, browser_click, browser_type, browser_screenshot, browser_script, computer_use_task]
 
 # Structured skill fields
 triggers:
@@ -38,13 +38,20 @@ steps:
     output: page_loaded
 
   - step: 2
+    action: browser_wait
+    instruction: "Wait for the element before acting on it. Clicking or typing before the element exists is the most common failure in web automation, and it fails silently"
+    params:
+      selector: "CSS selector of the element about to be used"
+    output: element_ready
+
+  - step: 3
     action: browser_click
     instruction: "Click on elements (buttons, links) to navigate or trigger actions"
     params:
       selector: "CSS selector for element"
     output: click_result
 
-  - step: 3
+  - step: 4
     action: browser_type
     instruction: "Type text into form fields (inputs, textareas)"
     params:
@@ -52,12 +59,14 @@ steps:
       text: "text to type"
     output: type_result
 
-  - step: 4
+  - step: 5
     action: browser_screenshot
     instruction: "Take screenshot to verify state after interactions"
     output: verification_screenshot
 
 rules:
+  - "Escalar sólo cuando haga falta, en este orden: `browser_click`/`browser_type` con un selector → `browser_script` si el elemento no se puede alcanzar con un selector estable → `computer_use_task` si la página no tiene selectores usables. Empezar por el último es lento y caro: mira la pantalla y razona en cada paso."
+  - "Esperar con `browser_wait` antes de cada clic o tipeo, no confiar en que la página ya cargó: es la falla más común de la automatización web, y falla en silencio."
   - "Wait for page to fully load after each navigation or significant interaction"
   - "Use specific, stable CSS selectors (IDs preferred over classes)"
   - "Take screenshots after critical steps for verification"

package/packages/core/src/skills/bundled/web/browser_scrape/SKILL.md

@@ -8,7 +8,7 @@ category: web
 permissions:
   - browser_control
 dependencies: []
-tools: [browser_navigate, browser_screenshot, web_fetch]
+tools: [browser_navigate, browser_screenshot, browser_extract, browser_wait]
 
 # Structured skill fields
 triggers:
@@ -39,16 +39,26 @@ steps:
     output: screenshot
 
   - step: 3
-    action: web_fetch
-    instruction: "Extract text content from rendered page as markdown"
-    output: extracted_content
+    action: browser_wait
+    instruction: "Wait for the content selector before extracting — an SPA renders after load fires"
+    params:
+      selector: "CSS selector of the content that must be present"
+    output: content_ready
 
   - step: 4
+    action: browser_extract
+    instruction: "Extract the rendered DOM. Omit the selector for a compact accessibility snapshot of the whole page"
+    params:
+      selector: "CSS selector, or 'body' for the whole page"
+    output: extracted_content
+
+  - step: 5
     action: synthesize
     instruction: "Combine screenshot and text content for comprehensive capture"
     output: scraped_data
 
 rules:
+  - "Extraer con `browser_extract`, NUNCA con `web_fetch`: web_fetch vuelve a pedir la URL al servidor y recibe el HTML sin renderizar, que es justamente lo que esta skill existe para evitar. En un SPA devuelve una cáscara vacía."
   - "Wait for full page load including JavaScript-rendered content"
   - "Take screenshot before extracting text to capture initial state"
   - "For infinite scroll pages, scroll down and capture multiple screenshots"
@@ -66,10 +76,10 @@ output_format:
 
 examples:
   - user_input: "capturá el contenido de https://example.com/dashboard"
-    expected_behavior: "browser_navigate → wait for JS render → browser_screenshot → browser_fetch → return both"
+    expected_behavior: "browser_navigate → browser_wait → browser_screenshot → browser_extract → return both"
 
   - user_input: "obtené la página renderizada de la app"
-    expected_behavior: "Navigate → wait for SPA to load → screenshot + fetch content"
+    expected_behavior: "Navigate → browser_wait for the SPA root → screenshot + browser_extract"
 
   - user_input: "scrapeá este sitio con javascript"
     expected_behavior: "Full browser render → capture visual and text content"
@@ -87,7 +97,12 @@ Esta skill se activa para sitios web dinámicos que requieren JavaScript renderi
 |------|----------|---------------|
 | `browser_navigate` | Navega y renderiza página completa | Sitios con JavaScript/SPA |
 | `browser_screenshot` | Captura estado visual | Evidencia de contenido renderizado |
-| `web_fetch` | Extrae texto como markdown | Contenido textual de página renderizada |
+| `browser_extract` | Extrae del DOM ya renderizado | Contenido textual o estructurado del SPA |
+| `browser_wait` | Espera a que aparezca un selector | Antes de extraer, en páginas que cargan por partes |
+
+> **No usar `web_fetch` acá.** Vuelve a pedir la URL al servidor y recibe el HTML
+> sin JavaScript ejecutado — en un SPA, una cáscara vacía. Para eso está
+> `browser_extract`, que lee el DOM que el navegador ya renderizó.
 
 ## Workflow
 

package/packages/core/src/skills/bundled-data.generated.ts

@@ -460,22 +460,32 @@ Para gestionar tareas programadas (cron jobs): crear, listar, actualizar, pausar
 | \`cron_expression\` | string | Expresión cron (solo para recurring) |
 | \`fire_at\` | string | Datetime ISO (solo para one_shot) |
 | \`channel\` | string | Canal de notificación |
-| \`start_at\` | string | Inicio de ventana opcional (Croner startAt) |
-| \`stop_at\` | string | Fin de ventana opcional (Croner stopAt) |
+| \`start_at\` | string | Inicio de ventana opcional |
+| \`stop_at\` | string | Fin de ventana opcional |
 | \`dom_and_dow\` | number | 0=OR (default), 1=AND (día mes + día semana) |
+| \`max_runs\` | number | Deja de correr después de N corridas ("recordámelo 3 veces") |
+| \`payload\` | object | Datos que recibe el agente al ejecutarse |
+| \`agent_id\` | string | Agente concreto que debe ejecutarla. Si se omite, decide el coordinador |
+| \`tool_name\` | string | Ejecutar una tool directamente, sin pasar por un agente |
+
+> **La zona horaria no se pasa acá**: sale del perfil del usuario. No la
+> inventes ni la pidas — si el usuario dice "a las 9", son las 9 de su reloj.
 
 ## Cron Expression Format
 
 \`\`\`
-* * * * *
-│ │ │ │ │
-│ │ │ │ └── Día semana (0-6, 0=Domingo)
-│ │ │ └──── Mes (1-12)
-│ │ └────── Día del mes (1-31)
-│ └──────── Hora (0-23)
-└────────── Minuto (0-59)
+┌───────── segundos (0-59)  ← opcional, sólo si hacen falta
+│ ┌─────── minuto (0-59)
+│ │ ┌───── hora (0-23)
+│ │ │ ┌─── día del mes (1-31)
+│ │ │ │ ┌─ mes (1-12 o JAN-DEC)
+│ │ │ │ │ ┌ día de semana (0-7 o SUN-SAT, 0 y 7 = domingo)
+* * * * * *
 \`\`\`
 
+Cinco campos, o seis poniendo los segundos adelante. Acepta \`*\`, listas \`1,15\`,
+rangos \`1-5\`, pasos \`*/2\`, y nombres de mes y de día.
+
 ## Ejemplos Comunes
 
 | Expresión | Significado |
@@ -834,7 +844,7 @@ Esta skill se activa cuando el usuario necesita:
     description: `Automate web workflows with navigation, clicks, form filling, and visual verification`,
     category: "web",
     version: "1.0.0",
-    tools: ["browser_navigate","browser_click","browser_type","browser_screenshot"],
+    tools: ["browser_navigate","browser_wait","browser_click","browser_type","browser_screenshot","browser_script","computer_use_task"],
     triggers: ["automatizá el navegador","automate browser","completá el formulario","fill form","hacé clic en","click on","iniciá sesión","login","registrate","sign up","interactuá con la web","interact with website","flujo web","web workflow"],
     body: `
 # Browser Automate Skill
@@ -879,7 +889,7 @@ Esta skill se activa para automatizar flujos de interacción con aplicaciones we
     description: `Navigate to web pages and capture rendered content including screenshots for dynamic sites`,
     category: "web",
     version: "1.0.0",
-    tools: ["browser_navigate","browser_screenshot","web_fetch"],
+    tools: ["browser_navigate","browser_screenshot","browser_extract","browser_wait"],
     triggers: ["capturá el contenido","scrape content","obtené la página renderizada","get rendered page","sitios dinámicos","dynamic sites","web con javascript","javascript websites","tomá screenshot y contenido","screenshot and content"],
     body: `
 # Browser Scrape Skill
@@ -894,7 +904,12 @@ Esta skill se activa para sitios web dinámicos que requieren JavaScript renderi
 |------|----------|---------------|
 | \`browser_navigate\` | Navega y renderiza página completa | Sitios con JavaScript/SPA |
 | \`browser_screenshot\` | Captura estado visual | Evidencia de contenido renderizado |
-| \`web_fetch\` | Extrae texto como markdown | Contenido textual de página renderizada |
+| \`browser_extract\` | Extrae del DOM ya renderizado | Contenido textual o estructurado del SPA |
+| \`browser_wait\` | Espera a que aparezca un selector | Antes de extraer, en páginas que cargan por partes |
+
+> **No usar \`web_fetch\` acá.** Vuelve a pedir la URL al servidor y recibe el HTML
+> sin JavaScript ejecutado — en un SPA, una cáscara vacía. Para eso está
+> \`browser_extract\`, que lee el DOM que el navegador ya renderizó.
 
 ## Workflow
 
@@ -1430,6 +1445,89 @@ Para crear flujos interactivos multi-paso usando A2UI v0.9. Usar cuando se neces
 - Agregar validación con \`checks\` en TextField
 - Mantener el estado del flujo en el data model (\`/data/step\`, \`/data/serviceType\`, etc.)
 - Eliminar surfaces con \`a2ui_delete_surface\` al completar o cancelar
+`,
+  },
+  {
+    name: "image_editor",
+    description: `Convertir, redimensionar y rotar imágenes con Bun.Image. Inspeccionar dimensiones y formato sin cargar la imagen al contexto.`,
+    category: "images",
+    version: "1.0.0",
+    tools: ["image_metadata","image_transform","artifact_inspect"],
+    triggers: ["convertí la imagen","convert image","redimensioná la imagen","resize image","achicá la foto","make it smaller","pasala a webp","convert to webp","rotá la imagen","rotate image","qué tamaño tiene","image dimensions","comprimí la imagen","compress image","hacé una miniatura","make a thumbnail"],
+    body: `
+# Image Editor Skill
+
+## Cuándo se Activa
+
+Cuando el usuario quiere **cambiar** una imagen (formato, tamaño, rotación) o
+**saber** sus características. Corre sobre \`Bun.Image\`, nativo del runtime.
+
+## Herramientas Disponibles
+
+| Tool | Qué hace | Cuándo usarla |
+|------|----------|---------------|
+| \`image_metadata\` | Ancho, alto y formato | Siempre antes de transformar |
+| \`image_transform\` | Convierte, redimensiona, rota | El trabajo en sí |
+| \`artifact_inspect\` | Tipo MIME, integridad, tamaño | Cuando no está claro si el artefacto es una imagen |
+
+## Lo Que Hay Que Entender
+
+**Todo pasa por artefactos.** Una imagen no viaja en el mensaje: vive como
+artefacto y se la nombra por su \`artifact_id\`. Es lo que evita que una foto de 4
+MB entre a la ventana de contexto y se reenvíe en cada turno de la conversación.
+
+**Transformar no destruye.** \`image_transform\` devuelve un artefacto **nuevo**.
+El original sigue disponible, así que se puede probar un tamaño, ver que no
+gustó y probar otro sin haber perdido nada.
+
+**La proporción se pierde en silencio.** Si se pasan \`width\` y \`height\` juntos,
+la imagen se estira sin avisar. Pasando uno solo, el otro se calcula.
+
+## Formatos
+
+\`jpeg\` · \`png\` · \`webp\` · \`avif\` · \`heic\`
+
+Ante la duda, **webp**: pesa bastante menos que jpeg y png a calidad comparable,
+y lo entienden todos los navegadores actuales.
+`,
+  },
+  {
+    name: "artifact_reader",
+    description: `Leer archivos grandes que llegaron como artifact_ref: por tramos o buscando dentro, sin volcarlos enteros al contexto.`,
+    category: "artifacts",
+    version: "1.0.0",
+    tools: ["artifact_read","artifact_inspect"],
+    triggers: ["leé el archivo adjunto","read the attachment","qué dice el documento","what does the document say","buscá en el archivo","search in the file","artifact_ref","el resultado quedó truncado","the result was truncated","seguí leyendo","keep reading"],
+    body: `
+# Artifact Reader Skill
+
+## Cuándo se Activa
+
+Cuando aparece un **\`artifact_ref\`**: un archivo, un adjunto o el resultado de
+una tool que era demasiado grande para entrar en el contexto.
+
+## Herramientas Disponibles
+
+| Tool | Qué hace | Cuándo usarla |
+|------|----------|---------------|
+| \`artifact_inspect\` | Tamaño, tipo MIME, integridad | Antes de leer, para decidir cómo |
+| \`artifact_read\` | Contenido, por tramos o buscando | Para leer de verdad |
+
+## Lo Que Hay Que Entender
+
+**Un \`artifact_ref\` no es un error.** Es el mecanismo por el que un archivo
+grande queda fuera de la ventana de contexto y a la vez disponible. El archivo
+está entero; lo que cambia es que se lee a pedido en vez de entrar completo en
+cada turno de la conversación.
+
+**Buscar cuesta mucho menos que paginar.** \`artifact_read\` con \`search\` recorre
+el archivo del lado del servidor y devuelve extractos de cada coincidencia con
+su contexto alrededor. Paginar el mismo archivo con \`offset\`/\`limit\` gasta un
+turno por tramo y mete en el contexto un montón de texto que no hacía falta.
+Cuando se sabe qué se busca, se busca.
+
+**Continuar es explícito.** Cada lectura devuelve \`next_offset\`. Ese es el valor
+que se pasa para seguir — no se calcula a mano.
 `,
   },
 ];

package/packages/core/src/storage/bootstrap.ts

@@ -11,10 +11,11 @@
  * instead of `DELETE`+`INSERT`.
  */
 
-import { getHiveDb } from "./hivedb";
-import { col } from "./hive";
-import { seedAllData } from "./seed";
-import { ensureSecretsBackend } from "./crypto";
+import { getHiveDb, getOpenHiveDb } from "./hivedb.ts";
+import { col } from "./hive.ts";
+import { seedAllData, type SeedOptions } from "./seed.ts";
+import { ensureSecretsBackend } from "./crypto.ts";
+import { ensureLegacyThread } from "../agent/thread-store.ts";
 
 interface IndexSpec {
   collection: string;
@@ -102,6 +103,13 @@ const INDEXES: IndexSpec[] = [
   // Stage 7 — meeting
   { collection: "meetingSessions", field: "user_id" },
   { collection: "meetingSessions", field: "status" },
+  { collection: "conversationThreads", field: "user_id" },
+  { collection: "conversationThreads", field: "channel" },
+  { collection: "conversationThreads", field: "archived" },
+  { collection: "swarms", field: "enabled" },
+  { collection: "apiEndpoints", field: "enabled" },
+  { collection: "memory", field: "user_id" },
+  { collection: "playbook", field: "user_id" },
 ];
 
 async function ensureIndexes(): Promise<void> {
@@ -119,33 +127,120 @@ async function ensureIndexes(): Promise<void> {
  * user-toggleable fields (enabled/active) and doesn't touch `users`, so it's
  * safe to call unconditionally before any onboarding has happened.
  */
-async function ensureSeedData(): Promise<void> {
-  await seedAllData();
+async function ensureSeedData(opts?: SeedOptions): Promise<void> {
+  await seedAllData(opts);
 }
 
-let bootstrapped = false;
+// Bootstrap state belongs to a specific database instance. A boolean that
+// survives closeHiveDb() can report a closed/replaced database as ready when
+// tests or long-running processes open a fresh instance in the same runtime.
+let bootstrappedDb: Awaited<ReturnType<typeof getHiveDb>> | null = null;
+
+/**
+ * Antes de la separación por canal todos los canales compartían un solo hilo cuyo
+ * `thread_id` era el `userId`. Esa conversación se registra —sin mover un solo
+ * mensaje— como una conversación más de la web, para que siga siendo legible desde
+ * la lista. Idempotente: no hace nada si ya está registrada o si no hay historial.
+ */
+/**
+ * Reasigna las memorias anteriores al aislamiento por usuario.
+ *
+ * Antes la colección era global: `id` era el título y no había `user_id`. Al
+ * introducir el aislamiento esas filas quedarían invisibles —nadie las
+ * encontraría, porque toda lectura filtra por dueño— así que se les asigna el
+ * usuario existente y se re-clavean a `${userId}:${title}`.
+ *
+ * Idempotente: una fila que ya tiene `user_id` no se toca. Si todavía no hay
+ * usuario (onboarding sin terminar) se deja para el próximo arranque, cuando lo
+ * haya, en vez de asignarlas a `""` y tener que deshacerlo.
+ */
+async function migrateLegacyMemories(): Promise<void> {
+  try {
+    const memories = await col<{ id: string; user_id?: string; title: string }>("memory");
+    const legacy = (await memories.scan({})).filter((e) => !e.doc.user_id);
+    if (legacy.length === 0) return;
+
+    const users = await col<{ id: string }>("users");
+    const primero = (await users.scan({ limit: 1 }))[0];
+    if (!primero) return;
+
+    for (const entry of legacy) {
+      const nuevoId = `${primero.id}:${entry.doc.title}`;
+      await memories.put(nuevoId, { ...entry.doc, id: nuevoId, user_id: primero.id });
+      if (nuevoId !== entry.id) await memories.delete(entry.id).catch(() => {});
+    }
+  } catch {
+    // La memoria no es crítica para arrancar: si falla, se reintenta al próximo boot.
+  }
+}
+
+/**
+ * Reglas del playbook anteriores a `user_id`.
+ *
+ * Se aprendieron cuando la instalación era de un solo usuario, así que son de
+ * él. Dejarlas sin dueño las volvería globales y se las inyectaría a cualquier
+ * usuario que se dé de alta después, que es exactamente el aislamiento que este
+ * campo viene a cerrar. Las sembradas no pasan por acá: `seedAllData()` les
+ * pone `user_id: ""` en cada arranque.
+ */
+async function migrateLegacyPlaybook(): Promise<void> {
+  try {
+    const playbook = await col<{ id: string; user_id?: string }>("playbook");
+    const legacy = (await playbook.scan({})).filter((e) => e.doc.user_id === undefined);
+    if (legacy.length === 0) return;
+
+    const users = await col<{ id: string }>("users");
+    const primero = (await users.scan({ limit: 1 }))[0];
+    if (!primero) return;
+
+    for (const entry of legacy) {
+      await playbook.put(
+        entry.id,
+        { ...entry.doc, user_id: primero.id },
+        { expectedVersion: entry.version },
+      );
+    }
+  } catch {
+    // El playbook no es crítico para arrancar: se reintenta al próximo boot.
+  }
+}
+
+async function ensureLegacyThreads(): Promise<void> {
+  try {
+    const users = await col<{ id: string }>("users");
+    for (const user of await users.scan({})) {
+      await ensureLegacyThread(user.id);
+    }
+  } catch {
+    // Base sin usuarios todavía (onboarding pendiente) — nada que registrar.
+  }
+}
 
 /**
  * Idempotent entry point: opens the database, ensures indexes, reseeds the
  * static catalogs, and records the schema version. Safe to call on every
  * gateway boot.
  */
-export async function ensureHiveDb(): Promise<void> {
-  await getHiveDb();
+export async function ensureHiveDb(opts?: SeedOptions): Promise<void> {
+  const db = await getHiveDb();
   await ensureIndexes();
   // Mint the master key before anything can save an API key, so a fresh
   // install is durable from the first keystroke rather than after a restart
   // has already dropped the secret.
   ensureSecretsBackend();
-  await ensureSeedData();
+  await ensureSeedData(opts);
+
+  await ensureLegacyThreads();
+  await migrateLegacyMemories();
+  await migrateLegacyPlaybook();
 
   const meta = await col<{ value: number }>("meta");
   const existing = await meta.get("schemaVersion");
   if (!existing) await meta.put("schemaVersion", { value: 1 }, { expectedVersion: 0 });
 
-  bootstrapped = true;
+  bootstrappedDb = db;
 }
 
 export function isBootstrapped(): boolean {
-  return bootstrapped;
+  return bootstrappedDb !== null && bootstrappedDb === getOpenHiveDb();
 }

package/packages/core/src/storage/causal-events.ts

@@ -6,7 +6,7 @@
  * co-located with the DB singleton accessor.
  */
 
-import { getHiveDb } from "./hivedb"
+import { getHiveDb } from "./hivedb.ts"
 import type { Event, EventPattern } from "@johpaz/hive-db"
 
 export type { Event as CausalEvent, EventPattern as CausalEventPattern }

package/packages/core/src/storage/collections.ts

@@ -40,7 +40,8 @@ export interface ModelDoc {
   id: string
   provider_id: string
   name: string
-  model_type: "llm" | "stt" | "tts" | "vision" | "embedding"
+  /** "realtime": voz full-duplex (Live API), no confundir con stt+tts encadenados. */
+  model_type: "llm" | "stt" | "tts" | "vision" | "embedding" | "realtime"
   context_window: number
   capabilities: string | null
   enabled: boolean
@@ -269,6 +270,14 @@ export interface RefreshTokenDoc {
 export type TurnSource =
   | "message" | "audio" | "a2ui" | "canvas" | "api"
   | "task_complete" | "delegation_summary"
+  /** Turno hablado en una sesión de voz en tiempo real. A diferencia de "audio"
+   *  (nota de voz: STT → turno → TTS) la voz la pone el modelo realtime, así que
+   *  el turno nunca sintetiza audio al final. */
+  | "realtime"
+  /** Charla hablada que la voz YA resolvió sin tocar la colmena. Se guarda como
+   *  contexto del hilo, nunca como pedido pendiente: tratarla como accionable
+   *  hacía que el coordinador re-delegara todo lo que se había dicho en voz. */
+  | "realtime_chat"
 
 /** What gets persisted — adds the synthetic marker for rows written before `source` existed. */
 export type MessageSource = TurnSource | "legacy_internal"
@@ -298,6 +307,28 @@ export interface SummaryDoc {
   last_message_id: string | null
 }
 
+/**
+ * Una conversación: el registro de un `conversations.thread_id`, con lo necesario
+ * para listarla en la web sin escanear los mensajes. `id` ES el threadId
+ * (`${user}/${canal}/${peer}` — ver agent/thread-id.ts), salvo la fila del hilo
+ * legacy anterior a la separación por canal, cuyo id es el userId pelado.
+ */
+export interface ConversationThreadDoc {
+  id: string
+  user_id: string
+  channel: string
+  /** Contacto/grupo del canal, o el id de conversación en la web. */
+  peer_id: string
+  peer_kind: "direct" | "group"
+  /** null hasta el primer mensaje del usuario, de donde se deriva. */
+  title: string | null
+  /** Borrado suave: sigue en la base pero no se lista ni se reabre. */
+  archived: boolean
+  created_at: number
+  last_message_at: number
+  message_count: number
+}
+
 export interface TraceDoc {
   id: string
   thread_id: string
@@ -320,6 +351,8 @@ export interface TraceDoc {
 export interface ReflectionDoc {
   id: string
   trace_ids: string
+  /** Usuario del que salieron las trazas. `""` cuando abarca varios. */
+  user_id: string
   insight_type: "success_pattern" | "failure_pattern" | "optimization" | "ethics_violation" | "root_cause" | "learning_proposal"
   description: string
   affected_tools: string | null
@@ -332,6 +365,16 @@ export interface PlaybookDoc {
   id: string
   rule: string
   category: string
+  /**
+   * De quién es lo aprendido. `""` = global, que es lo que corresponde a las
+   * reglas sembradas: son conocimiento del producto, no de nadie en particular.
+   *
+   * Sin esto el playbook era global a la instalación, así que **lo que el agente
+   * aprendía interactuando con una persona se le aplicaba a todas**. En una
+   * instalación de un solo usuario da igual; en un host multi-inquilino es una
+   * fuga entre workspaces.
+   */
+  user_id: string
   applicable_to: string | null
   helpful_count: number
   harmful_count: number
@@ -490,7 +533,15 @@ export interface ArtifactDoc {
   height: number | null
   status: "active" | "expired"
   created_at: number
-  expires_at: number
+  /**
+   * `null` = no expira nunca.
+   *
+   * Los artefactos internos —capturas, resultados de tools grandes— son basura
+   * transitoria y se limpian solos a los 7 días. Pero un archivo que el usuario
+   * subió o transformó no es basura: borrárselo a la semana convierte un
+   * servicio en una pérdida de datos. Quien lo crea decide.
+   */
+  expires_at: number | null
   expired_at: number | null
 }
 
@@ -521,8 +572,21 @@ export interface TaskRunDoc {
 // ─── Stage 6: orchestration ───────────────────────────────────────────────────
 
 /** id = title — the old `notes`/`memory_*` table never existed, so this is a from-scratch fix. */
+/**
+ * Memoria de largo plazo de un usuario.
+ *
+ * `id` es `${user_id}:${title}`. Hasta acá era sólo el título y la colección era
+ * global al proceso —coherente con que hive es mono-usuario, pero inservible
+ * para un runtime donde cada quien arma su colmena: dos usuarios no podían
+ * tener una memoria con el mismo título, y cualquiera veía la del otro.
+ *
+ * Las filas anteriores (id = título, sin `user_id`) se migran al arrancar
+ * asignándolas al usuario existente. Ver `migrateLegacyMemories`.
+ */
 export interface MemoryDoc {
   id: string
+  /** Dueño de la memoria. Las filas legacy se migran al usuario único. */
+  user_id: string
   title: string
   content: string
   created_at: number
@@ -582,6 +646,78 @@ export interface DelegationGroupDoc {
   notified_at: number | null
 }
 
+/**
+ * Un enjambre guardado: qué agentes lo componen, con qué rol y en qué orden.
+ *
+ * Hasta acá un enjambre sólo existía mientras corría — `runRoleSwarm()` recibe
+ * los agentes en la llamada y no persiste nada. Quien armara uno desde una
+ * interfaz lo perdía al cerrar la ventana, y por eso hive-cloud terminó creando
+ * sus propias tablas en Postgres: no le quedaba alternativa.
+ *
+ * `agents_json` guarda `[{agentId, role, orderIndex}]`. Se deja como JSON y no
+ * como colección aparte a propósito: un enjambre se lee y se escribe entero,
+ * nunca por agente suelto, así que una tabla de unión sólo agregaría joins.
+ */
+/**
+ * Un endpoint HTTP registrado como herramienta.
+ *
+ * Una tool normal es código con un `execute`, así que desde una interfaz no hay
+ * dónde ponerlo. Un endpoint declarativo invierte eso: el usuario aporta
+ * **datos** —URL, método, cabeceras, qué parámetros acepta— y el ejecutor es
+ * genérico y vive en el SDK. Es la única forma de que alguien sume una
+ * capacidad propia desde una UI sin abrir la puerta a ejecutar código
+ * arbitrario, y sin levantar un servidor MCP.
+ *
+ * Las credenciales NO viven acá: van cifradas en el secret store bajo
+ * `endpoint:<id>:headers`, igual que las de proveedores y canales. Esta fila es
+ * pública y se muestra en la UI; la clave, no.
+ */
+export interface ApiEndpointDoc {
+  id: string
+  name: string
+  description: string
+  method: string
+  url: string
+  /** Cabeceras no sensibles. Las que llevan credenciales van al secret store. */
+  headers_json: string | null
+  /** Query fijos que siempre acompañan la llamada. */
+  query_json: string | null
+  /**
+   * Cuerpo con marcadores `{{param}}` que se reemplazan por lo que pase el
+   * modelo. Sin esto un endpoint POST sólo serviría con cuerpo fijo.
+   */
+  body_template: string | null
+  /** JSON Schema de lo que el modelo puede pasar — lo que ve como parámetros. */
+  param_schema_json: string | null
+  enabled: boolean
+  created_at: number
+  updated_at: number
+}
+
+export interface SwarmDoc {
+  id: string
+  name: string
+  description: string | null
+  /** Cómo se coordinan: en cadena, en paralelo, o con un orquestador que delega. */
+  strategy: "sequential" | "parallel" | "hierarchical"
+  /** Requerido por `hierarchical`; null en las otras dos. */
+  orchestrator_agent_id: string | null
+  /** `[{ agentId, role, orderIndex }]` — ver SwarmMemberSpec. */
+  agents_json: string
+  enabled: boolean
+  /** Tope de delegaciones en la estrategia jerárquica; null = el del runtime. */
+  max_delegations: number | null
+  created_at: number
+  updated_at: number
+}
+
+/** Un integrante del enjambre, tal como se serializa en `SwarmDoc.agents_json`. */
+export interface SwarmMemberSpec {
+  agentId: string
+  role: "orchestrator" | "worker"
+  orderIndex: number
+}
+
 export interface AgentBusMessageDoc {
   id: string
   event_type: string