@johpaz/hive-sdk 0.2.0 → 0.3.1

package/packages/core/src/sessions/resolve.ts

@@ -0,0 +1,108 @@
+/**
+ * Resolver quién habla y en qué hilo, cuando el mensaje llega por un canal.
+ *
+ * Un mensaje de Telegram trae un id de Telegram, no un usuario de la colmena.
+ * Esto traduce: busca la identidad en `userIdentities` y devuelve el usuario, el
+ * hilo y el agente que deben atenderlo — creando el hilo si hace falta.
+ *
+ * Ojo con el comportamiento de auto-vinculación: si la identidad no existe, se
+ * asocia al **único usuario existente**. Es coherente con hive, que es
+ * mono-usuario, pero en un despliegue con varios significa que el primer
+ * desconocido que escriba por un canal quedaría vinculado a quien estuviera.
+ * Para eso está `security/pairing.ts`, que exige aprobación antes de crear la
+ * identidad: un host multi-usuario debe usarlo delante de esto.
+ */
+
+import { col } from "../storage/hive.ts"
+import type { UserIdentityDoc, UserDoc, AgentDoc } from "../storage/collections.ts"
+import { ensureThread, mostRecentWebThread, createWebConversation } from "../agent/thread-store.ts"
+
+export interface ResolveContextResult {
+  userId: string
+  threadId: string
+  agentId: string
+  isNewUser: boolean
+}
+
+export interface ResolveContextOptions {
+  channel: string
+  channelUserId: string
+  /** Channel account the message arrived on — persisted so replies can be routed back to it. */
+  accountId?: string
+  /**
+   * Conversación concreta dentro del canal: el contacto o grupo en mensajería, el id
+   * de conversación en la web. Si falta, en los canales se usa `channelUserId` y en
+   * la web la conversación más reciente (o una nueva, si no hay ninguna).
+   */
+  peerId?: string
+  peerKind?: "direct" | "group"
+}
+
+export async function resolveContext(options: ResolveContextOptions): Promise<ResolveContextResult> {
+  const { channel, channelUserId, accountId } = options
+
+  const identitiesCol = await col<UserIdentityDoc>("userIdentities")
+  const usersCol = await col<UserDoc>("users")
+  const agentsCol = await col<AgentDoc>("agents")
+
+  const allIdentities = await identitiesCol.scan({})
+  const identity = allIdentities.find(e => e.doc.channel === channel && e.doc.channel_user_id === channelUserId)
+
+  let userId: string
+  let isNewUser = false
+
+  if (identity) {
+    userId = identity.doc.user_id
+    // Backfill/refresh the owning account so replies survive a restart, when
+    // the in-memory session→account map in ChannelManager is empty.
+    if (accountId && identity.doc.account_id !== accountId) {
+      await identitiesCol.put(identity.id, { ...identity.doc, account_id: accountId })
+    }
+  } else {
+    // Sistema mono-usuario: reutilizar el usuario del onboarding
+    const allUsers = await usersCol.scan({})
+    const existingUser = [...allUsers].sort((a, b) => a.doc.created_at - b.doc.created_at)[0]
+
+    if (!existingUser) {
+      throw new Error("No user found in database. Please run the onboarding process first.")
+    }
+
+    userId = existingUser.id
+
+    // Vincular este canal al usuario existente (auto-link en el primer mensaje)
+    // put(): si ya existe una fila (user_id, channel), actualiza channel_user_id
+    // con el valor real del canal (e.g. chat ID numérico de Telegram).
+    await identitiesCol.put(`${userId}:${channel}`, {
+      user_id: userId, channel, channel_user_id: channelUserId,
+      account_id: accountId, linked_at: Date.now(),
+    })
+  }
+
+  const coordinators = await agentsCol.findBy("role", "coordinator", { limit: 1 })
+  const agentId = coordinators[0]?.id || "bee"
+
+  // Un hilo por canal Y por contacto (`${user}/${canal}/${peer}` — ver
+  // agent/thread-id.ts). Antes todos los canales compartían un único hilo
+  // (`threadId = userId`), así que lo hablado por Telegram entraba en el mismo
+  // contexto que la web y un grupo de WhatsApp escribía en el chat privado del
+  // dueño. Los session IDs de transporte siguen enrutando las respuestas.
+  const threadId = options.peerId
+    ? await ensureThread({
+        userId,
+        channel,
+        peerId: options.peerId,
+        peerKind: options.peerKind,
+      })
+    : channel === "webchat"
+      // Sin conversación indicada, la web sigue donde se quedó: la más reciente
+      // —que puede ser el hilo previo a la separación por canal— o una nueva.
+      ? ((await mostRecentWebThread(userId))?.id ?? (await createWebConversation(userId)).id)
+      : await ensureThread({
+          userId,
+          channel,
+          peerId: channelUserId,
+          peerKind: options.peerKind,
+        })
+
+  return { userId, threadId, agentId, isNewUser }
+}

package/packages/core/src/skills/SkillLoader.ts

@@ -134,7 +134,14 @@ export interface Skill {
   examples?: SkillExample[];
 }
 
-function parseFrontmatter(content: string): { frontmatter: Record<string, unknown>; body: string } {
+/**
+ * Separa el frontmatter YAML del cuerpo markdown de un `SKILL.md`.
+ *
+ * Exportada porque `services/skills.ts` importa skills del disco a la BD y
+ * necesita exactamente este parseo: duplicarlo garantizaría que un día
+ * acepten formatos distintos.
+ */
+export function parseFrontmatter(content: string): { frontmatter: Record<string, unknown>; body: string } {
   const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
 
   if (!match) {

package/packages/core/src/skills/bundled/artifacts/artifact_reader/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: artifact_reader
+description: "Leer archivos grandes que llegaron como artifact_ref: por tramos o buscando dentro, sin volcarlos enteros al contexto."
+version: 1.0.0
+author: Hive Team
+icon: "📎"
+category: artifacts
+permissions:
+  - artifact_read
+dependencies: []
+tools: [artifact_read, artifact_inspect]
+
+# Structured skill fields
+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"
+
+preferred_agents: []
+
+steps:
+  - step: 1
+    action: artifact_inspect
+    instruction: "Ver tamaño y tipo antes de leer. Un artefacto de 2 MB no se lee entero: se busca dentro"
+    params:
+      artifactId: "id del artifact_ref"
+    output: metadatos
+
+  - step: 2
+    action: artifact_read
+    instruction: "Si se busca algo puntual, usar `search` — devuelve extractos alrededor de cada coincidencia y cuesta una fracción de paginar. Si hace falta el texto seguido, usar offset/limit"
+    params:
+      artifactId: "id del artefacto"
+      search: "término a buscar (opcional)"
+      offset: "desde qué carácter (opcional)"
+      limit: "cuántos caracteres (opcional)"
+    output: contenido
+
+  - step: 3
+    action: synthesize
+    instruction: "Responder con lo encontrado, citando de dónde salió"
+    output: respuesta
+
+rules:
+  - "**Buscar antes que paginar.** `search` devuelve extractos de todas las coincidencias en una sola llamada; paginar un archivo grande con offset/limit gasta varios turnos y llena el contexto con texto que no se necesitaba."
+  - "`artifact_inspect` no devuelve contenido: sirve para decidir cómo leer sin gastar contexto en averiguarlo."
+  - "Para continuar una lectura, usar el `next_offset` que devolvió la llamada anterior. No adivinar la posición."
+  - "Un `artifact_ref` aparece cuando un resultado fue demasiado grande para el contexto. No es un error: es el archivo esperando a que lo leas por partes."
+  - "Los artefactos de imagen no se leen con `artifact_read` — para eso están `image_metadata` e `image_transform`."
+
+output_format:
+  structure: markdown
+  sections:
+    - "lo encontrado"
+    - "de qué parte del archivo salió"
+  max_length: "Sólo lo relevante, nunca el archivo entero"
+
+examples:
+  - user_input: "buscá 'error de conexión' en el log adjunto"
+    expected_behavior: "artifact_read con search='error de conexión' — una llamada, no paginar"
+
+  - user_input: "qué dice el documento"
+    expected_behavior: "artifact_inspect para ver el tamaño → artifact_read del primer tramo → resumir"
+
+  - user_input: "seguí leyendo"
+    expected_behavior: "artifact_read con el next_offset de la llamada anterior"
+---
+
+# 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/skills/bundled/cron_manager/SKILL.md

@@ -54,8 +54,8 @@ steps:
       cron_expression: "Cron expression for recurring (e.g., '0 9 * * *')"
       fire_at: "ISO datetime for one_shot (e.g., '2026-04-20T09:00:00')"
       channel: "Notification channel (telegram, discord, webchat)"
-      start_at: "Optional ISO datetime - start of execution window (Croner startAt)"
-      stop_at: "Optional ISO datetime - end of execution window (Croner stopAt)"
+      start_at: "Optional ISO datetime - start of execution window"
+      stop_at: "Optional ISO datetime - end of execution window"
       dom_and_dow: "0 = OR logic (default), 1 = AND logic for day-of-month + day-of-week"
       max_runs: "Optional max executions"
     output: cron_id
@@ -133,22 +133,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 |

package/packages/core/src/skills/bundled/images/image_editor/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: image_editor
+description: "Convertir, redimensionar y rotar imágenes con Bun.Image. Inspeccionar dimensiones y formato sin cargar la imagen al contexto."
+version: 1.0.0
+author: Hive Team
+icon: "🖼️"
+category: images
+permissions:
+  - image_processing
+dependencies: []
+tools: [image_metadata, image_transform, artifact_inspect]
+
+# Structured skill fields
+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"
+
+preferred_agents: []
+
+steps:
+  - step: 1
+    action: image_metadata
+    instruction: "Leer ancho, alto y formato ANTES de transformar. Sin esto no se puede decidir un tamaño con criterio, y redimensionar a ciegas agranda imágenes chicas"
+    params:
+      artifact_id: "id del artefacto con la imagen"
+    output: dimensiones_originales
+
+  - step: 2
+    action: image_transform
+    instruction: "Transformar. Dando sólo ancho O sólo alto se mantiene la proporción; dando los dos, la imagen se deforma"
+    params:
+      artifact_id: "id del artefacto de origen"
+      width: "ancho en píxeles (opcional)"
+      format: "jpeg | png | webp | avif | heic (opcional)"
+      quality: "1-100, sólo para formatos con pérdida (opcional)"
+    output: artefacto_nuevo
+
+  - step: 3
+    action: notify
+    instruction: "Avisar con el id del artefacto resultante y su tamaño"
+    output: aviso
+
+rules:
+  - "Las imágenes se manejan por `artifact_id`, nunca por base64 en el mensaje: una imagen incrustada llena la ventana de contexto y se reenvía en cada turno."
+  - "`image_transform` NO modifica el original: crea un artefacto nuevo y devuelve su id. El original queda intacto."
+  - "Para conservar la proporción, dar sólo `width` o sólo `height`. Dar los dos deforma la imagen; hacelo únicamente si el usuario lo pidió."
+  - "`quality` sólo aplica a formatos con pérdida (jpeg, webp, avif). En png se ignora."
+  - "`rotate` acepta 90, 180 o 270. Otros valores se rechazan."
+  - "Si no sabés qué formato quiere el usuario, webp es la mejor opción por defecto: pesa menos que jpeg y png con calidad equivalente."
+
+output_format:
+  structure: markdown
+  sections:
+    - "artifact_id resultante"
+    - "formato y dimensiones"
+    - "tamaño en bytes"
+  max_length: "Breve — la imagen no se incrusta en la respuesta"
+
+examples:
+  - user_input: "convertí esta imagen a webp"
+    expected_behavior: "image_metadata para ver el formato → image_transform con format=webp → devolver el id nuevo"
+
+  - user_input: "hacela de 800 de ancho"
+    expected_behavior: "image_transform con width=800 y SIN height, para no deformarla"
+
+  - user_input: "hacé una miniatura"
+    expected_behavior: "image_transform con width≈200, format=webp, quality≈80"
+
+  - user_input: "qué tamaño tiene esta imagen"
+    expected_behavior: "image_metadata solo — no hace falta transformar nada"
+---
+
+# 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.

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