@johpaz/hive-sdk 0.2.0 → 0.3.0

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

@@ -13,7 +13,7 @@
 
 import { getHiveDb, getOpenHiveDb } from "./hivedb.ts";
 import { col } from "./hive.ts";
-import { seedAllData } from "./seed.ts";
+import { seedAllData, type SeedOptions } from "./seed.ts";
 import { ensureSecretsBackend } from "./crypto.ts";
 import { ensureLegacyThread } from "../agent/thread-store.ts";
 
@@ -106,6 +106,10 @@ const INDEXES: IndexSpec[] = [
   { 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> {
@@ -123,8 +127,8 @@ 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);
 }
 
 // Bootstrap state belongs to a specific database instance. A boolean that
@@ -138,6 +142,69 @@ let bootstrappedDb: Awaited<ReturnType<typeof getHiveDb>> | null = null;
  * 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");
@@ -154,16 +221,18 @@ async function ensureLegacyThreads(): Promise<void> {
  * static catalogs, and records the schema version. Safe to call on every
  * gateway boot.
  */
-export async function ensureHiveDb(): Promise<void> {
+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");

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

@@ -351,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
@@ -363,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
@@ -521,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
 }
 
@@ -552,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
@@ -613,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

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

@@ -29,6 +29,22 @@ interface SecretDoc {
 const _mem = new Map<string, string>()
 let _keychainOk: boolean | null = null // null = untested
 
+let _keychainApi: unknown = undefined
+
+/**
+ * A test double or a recovered runtime may replace Bun.secrets. Reset the
+ * cached availability result when that API object changes so a previous
+ * headless failure cannot poison the replacement backend forever.
+ */
+function _getKeychainApi(): any {
+  const api = (Bun as any).secrets
+  if (api !== _keychainApi) {
+    _keychainApi = api
+    _keychainOk = null
+  }
+  return api
+}
+
 async function _get(name: string): Promise<string | null> {
   const cached = _mem.get(name)
   if (cached !== undefined) return cached
@@ -82,11 +98,10 @@ async function _readCollectionSecret(name: string): Promise<string | null> {
 /**
  * Olvida si el keychain del SO respondió o no.
  *
- * `_keychainOk` se cachea a nivel de módulo a propósito: en un servidor sin
- * libsecret cada lectura tiraría y no tiene sentido reintentarlo. El costo es
- * que el resultado del primer sondeo vale para todo el proceso, y un test que
- * sustituya `Bun.secrets` por un doble queda cortocircuitado si algo ya sondeó
- * antes y falló. Resetear acá lo vuelve a dejar sin probar.
+ * Sustituir `Bun.secrets` por un doble ya NO necesita esto: `_getKeychainApi()`
+ * detecta que el objeto cambió e invalida el sondeo solo. Queda para el caso
+ * que aquello no cubre —vaciar además el caché en memoria (`_mem`)— y porque
+ * ya salió publicado.
  */
 export function resetKeychainProbe(): void {
   _keychainOk = null
@@ -94,9 +109,10 @@ export function resetKeychainProbe(): void {
 }
 
 async function _keychainGet(name: string): Promise<string | null> {
+  const keychain = _getKeychainApi()
   if (_keychainOk === false) return null
   try {
-    const val = await (Bun as any).secrets.get({ service: SERVICE, name })
+    const val = await keychain.get({ service: SERVICE, name })
     _keychainOk = true
     return val ?? null
   } catch {
@@ -106,9 +122,10 @@ async function _keychainGet(name: string): Promise<string | null> {
 }
 
 async function _keychainSet(name: string, value: string): Promise<boolean> {
+  const keychain = _getKeychainApi()
   if (_keychainOk === false) return false
   try {
-    await (Bun as any).secrets.set({ service: SERVICE, name, value })
+    await keychain.set({ service: SERVICE, name, value })
     _keychainOk = true
     return true
   } catch {

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

@@ -34,7 +34,7 @@ export type * from "./collections.ts";
 export { catalogModelKey, wireModelId, isResellerProvider } from "./model-id.ts";
 
 // ─── Seed del catálogo ───────────────────────────────────────────────────────
-export type { SeedData } from "./seed.ts";
+export type { SeedData, SeedOptions, SpecialistSeedMode } from "./seed.ts";
 export {
   SEED_DATA,
   seedAllData,
@@ -88,6 +88,7 @@ export {
 
 // ─── Onboarding e identidad ──────────────────────────────────────────────────
 export type { OnboardingSection } from "./onboarding.ts";
+export { activateBrowserTools } from "./onboarding.ts";
 export {
   resolveUserId,
   resolveAgentId,