@johpaz/hive-sdk 0.1.6 → 0.3.0

package/packages/core/src/agent/run-store.ts

@@ -10,14 +10,14 @@
  * should write to a run; single-writer pattern keeps contention minimal.
  */
 
-import { col, updateDoc, nextId, toIndexable } from "../storage/hive";
-import type { AgentRunDoc } from "../storage/collections";
-import { getBootId } from "../storage/boot-id";
-import { logger } from "../utils/logger";
-import { loadConfig } from "../config/loader";
-import type { LLMMessage } from "./llm-client";
-import type { RunEpoch } from "./run-epoch";
-import { formatInternalEvent } from "./conversation-store";
+import { col, updateDoc, nextId, toIndexable } from "../storage/hive.ts";
+import type { AgentRunDoc } from "../storage/collections.ts";
+import { getBootId } from "../storage/boot-id.ts";
+import { logger } from "../utils/logger.ts";
+import { loadConfig } from "../config/loader.ts";
+import type { LLMMessage } from "./llm-client.ts";
+import type { RunEpoch } from "./run-epoch.ts";
+import { formatInternalEvent } from "./conversation-store.ts";
 
 const log = logger.child("run-store");
 

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

@@ -12,15 +12,15 @@
  * - Eventos (cron, etc.)
  */
 
-import { logger } from "../utils/logger"
-import { buildSystemPromptWithProjects } from "./prompt-builder"
-import { getAgentLoop, rebuildAgentLoop } from "./agent-loop"
+import { logger } from "../utils/logger.ts"
+import { buildSystemPromptWithProjects } from "./prompt-builder.ts"
+import { getAgentLoop, rebuildAgentLoop } from "./agent-loop.ts"
 import type { MCPClientManager } from "../mcp/index.ts"
-import { resolveAgentId, resolveUserId } from "../storage/onboarding"
-import { getMCPManager as getSingletonMCPManager } from "../mcp/singleton"
-import type { ContentPart } from "./llm-client"
-import { col, fromIndexable } from "../storage/hive"
-import type { AgentDoc, EthicsDoc } from "../storage/collections"
+import { resolveAgentId, resolveUserId } from "../storage/onboarding.ts"
+import { getMCPManager as getSingletonMCPManager } from "../mcp/singleton.ts"
+import type { ContentPart } from "./llm-client.ts"
+import { col, fromIndexable } from "../storage/hive.ts"
+import type { AgentDoc, EthicsDoc } from "../storage/collections.ts"
 
 const log = logger.child("agent-service")
 
@@ -161,7 +161,7 @@ export class AgentService {
    */
   async reloadSkills(): Promise<void> {
     log.info("Reloading skills...")
-    const { syncSkillsToIndex } = await import("./context-compiler")
+    const { syncSkillsToIndex } = await import("./context-compiler.ts")
     await syncSkillsToIndex()
     log.info("Skills reloaded")
   }
@@ -252,7 +252,7 @@ export class AgentService {
    * Ejecuta un agente con un mensaje
    */
   async runAgent(message: string | ContentPart[], threadId: string, userId?: string): Promise<string> {
-    const { runAgentIsolated } = await import("./agent-loop")
+    const { runAgentIsolated } = await import("./agent-loop.ts")
     const result = await runAgentIsolated({
       agentId: this.agentId,
       taskDescription: message,

package/packages/core/src/agent/skill-selector.ts

@@ -16,17 +16,17 @@
  * 5. Returns skill content for injection into system prompt
  */
 
-import { col } from "../storage/hive"
+import { col } from "../storage/hive.ts"
 import type { SkillDoc } from "../storage/collections"
-import { logger } from "../utils/logger"
-import { isMinimalSkill } from "./minimal-loadout"
-import { isCalendarOperation } from "./routing-intent"
+import { logger } from "../utils/logger.ts"
+import { isMinimalSkill } from "./minimal-loadout.ts"
+import { isCalendarOperation } from "./routing-intent.ts"
 import {
     searchCapabilities,
     applyRelativeCutoff,
     replaceCapabilityDocs,
     type CapabilityDoc,
-} from "./capability-search"
+} from "./capability-search.ts"
 
 const log = logger.child("skill-selector")
 
@@ -109,7 +109,7 @@ const STOPWORDS = new Set([
     "más", "mas", "ya", "yo", "tu", "te", "ti", "mi", "me",
     "hola", "hi", "hello", "hey", "gracias", "thank", "please",
     "ok", "okay", "yes", "si", "no", "bien", "good", "great",
-    "puedes", "necesito", "quiero", "podés", "necesitás", "querés",
+    "puedes", "necesito", "quiero", "necesitas", "quieres",
 ])
 
 /** Conversational patterns that should return empty skill list */

package/packages/core/src/agent/thread-id.ts

@@ -0,0 +1,71 @@
+/**
+ * Thread identity — `${userId}/${channel}/${peerId}`.
+ *
+ * Un hilo por canal Y por contacto: el chat privado de Telegram, cada grupo de
+ * WhatsApp y cada conversación de la web tienen historial propio. Antes había un
+ * único hilo por usuario (`threadId = userId`) compartido por todos los canales.
+ *
+ * Dos reglas de formato que no son cosméticas:
+ *
+ * 1. El separador es "/" y NO ":". Los mensajes viven en `conversations` con id
+ *    `${threadId}:${seq}` y se leen por prefijo (`scan({ prefix: "${threadId}:" })`),
+ *    sin índice secundario. El hilo legacy (id = userId pelado) se lee con prefijo
+ *    `${userId}:`; si los hilos nuevos fueran `${userId}:webchat:...` ese scan se los
+ *    tragaría enteros. Con "/" el historial viejo queda aislado sin migrar una fila.
+ *
+ * 2. Ningún segmento puede contener ":" — se sustituye por "_". Sin esto los peerIds
+ *    compuestos rompen el aislamiento por prefijo: el DM de Telegram `12345` y el grupo
+ *    `12345:678` (telegram.ts arma así el peerId de grupo) producirían los prefijos
+ *    `.../12345:` y `.../12345:678:`, y el primero es prefijo del segundo — el DM leería
+ *    los mensajes del grupo. Colapsar ":" hace que `${threadId}:` sea siempre un
+ *    separador inequívoco, y mantiene válido el `lastIndexOf(":")` con que
+ *    conversation-store extrae el número de secuencia.
+ */
+
+export const THREAD_SEP = "/"
+
+/** Canal sintético de las tareas programadas: un hilo estable por cron job. */
+export const CRON_CHANNEL = "cron"
+
+export interface ThreadParts {
+  userId: string
+  channel: string
+  peerId: string
+}
+
+/**
+ * Deja un segmento apto para formar parte de un threadId: sin "/" (rompería el
+ * parseo) y sin ":" (rompería el aislamiento por prefijo — ver cabecera).
+ */
+export function sanitizeSegment(value: string): string {
+  return value.replace(/[/:]/g, "_").trim()
+}
+
+export function makeThreadId(userId: string, channel: string, peerId: string): string {
+  const parts = [userId, channel, peerId].map((p) => sanitizeSegment(p || "") || "default")
+  return parts.join(THREAD_SEP)
+}
+
+/**
+ * Descompone un threadId con formato. Devuelve null para todo lo que no lo tenga:
+ * el hilo legacy (`userId` pelado), los hilos aislados de los workers
+ * (`task-<id>-<agente>`) y cualquier id heredado. Quien llame debe conservar su
+ * comportamiento anterior ante un null, nunca inventar partes.
+ */
+export function parseThreadId(threadId: string): ThreadParts | null {
+  if (!threadId) return null
+  const parts = threadId.split(THREAD_SEP)
+  if (parts.length !== 3) return null
+  const [userId, channel, peerId] = parts
+  if (!userId || !channel || !peerId) return null
+  return { userId, channel, peerId }
+}
+
+export function isStructuredThreadId(threadId: string): boolean {
+  return parseThreadId(threadId) !== null
+}
+
+/** Id de una conversación nueva de la web. No lo elige el cliente. */
+export function newWebConversationId(): string {
+  return `conv-${crypto.randomUUID().replace(/-/g, "").slice(0, 12)}`
+}

package/packages/core/src/agent/thread-store.ts

@@ -0,0 +1,293 @@
+/**
+ * Thread store — el registro de conversaciones (`conversationThreads`).
+ *
+ * `conversations` no tiene índice secundario: los mensajes se leen por prefijo del
+ * threadId. Esta colección es el catálogo que permite listar las conversaciones de
+ * un usuario, ponerles título y borrarlas sin escanear todos los mensajes.
+ *
+ * El id de cada fila ES el threadId. La única fila cuyo id no tiene formato
+ * `${user}/${canal}/${peer}` es la del hilo legacy anterior a la separación por
+ * canal (ver ensureLegacyThread).
+ */
+
+import { col, updateDoc } from "../storage/hive.ts"
+import { logger } from "../utils/logger.ts"
+import type { ConversationThreadDoc, ConversationDoc, SummaryDoc } from "../storage/collections.ts"
+import { makeThreadId, parseThreadId, newWebConversationId } from "./thread-id.ts"
+import { runSessionStart, runSessionEnd } from "../hooks/index.ts"
+
+const log = logger.child("thread-store")
+
+const TITLE_MAX_CHARS = 60
+
+/** Reintentos del contador ante mensajes concurrentes del mismo hilo. */
+const TOUCH_MAX_RETRIES = 5
+
+export interface EnsureThreadInput {
+  userId: string
+  channel: string
+  peerId: string
+  peerKind?: "direct" | "group"
+}
+
+async function threadsCol() {
+  return col<ConversationThreadDoc>("conversationThreads")
+}
+
+export async function getThread(threadId: string): Promise<ConversationThreadDoc | null> {
+  const c = await threadsCol()
+  const entry = await c.get(threadId)
+  return entry?.doc ?? null
+}
+
+/**
+ * Crea la fila de la conversación si aún no existe y devuelve su threadId.
+ * Idempotente: se llama en cada turno desde resolveContext.
+ */
+export async function ensureThread(input: EnsureThreadInput): Promise<string> {
+  const threadId = makeThreadId(input.userId, input.channel, input.peerId)
+  const c = await threadsCol()
+  const existing = await c.get(threadId)
+  if (existing) return threadId
+
+  const now = Date.now()
+  try {
+    await c.put(threadId, {
+      id: threadId,
+      user_id: input.userId,
+      channel: input.channel,
+      peer_id: input.peerId,
+      peer_kind: input.peerKind ?? "direct",
+      title: null,
+      archived: false,
+      created_at: now,
+      last_message_at: now,
+      message_count: 0,
+    }, { expectedVersion: 0 })
+  } catch {
+    // Otro turno del mismo canal la creó primero — ambos quieren lo mismo.
+    return threadId
+  }
+
+  // `sessionStart` se dispara acá y no en `createSession` porque esa función es
+  // idempotente y se llama en cada turno: engancharla ahí haría que el hook
+  // corriera con cada mensaje. El `put` con `expectedVersion: 0` es el punto de
+  // serialización, así que dispararlo justo después de que ese put haya salido
+  // bien evita el doble disparo cuando dos turnos del mismo canal llegan juntos
+  // — el perdedor se fue por el catch de arriba. Cubre además a quien llame
+  // `ensureThread` directamente desde un canal, sin pasar por `sessions`.
+  await runSessionStart({ threadId, userId: input.userId, channel: input.channel })
+  return threadId
+}
+
+/** Conversación nueva de la web. El id lo elige el servidor, nunca el cliente. */
+export async function createWebConversation(userId: string, title?: string): Promise<ConversationThreadDoc> {
+  const peerId = newWebConversationId()
+  const threadId = await ensureThread({ userId, channel: "webchat", peerId, peerKind: "direct" })
+  if (title?.trim()) await renameThread(threadId, title)
+  const doc = await getThread(threadId)
+  if (!doc) throw new Error(`No pude crear la conversación ${threadId}`)
+  return doc
+}
+
+/**
+ * Título derivado del primer mensaje del usuario. El contenido llega con el
+ * prefijo `[Timestamp: ...]` que le añaden el gateway y las rutas REST: esa línea
+ * no describe nada, así que se descarta antes de recortar.
+ */
+export function deriveTitle(text: string): string | null {
+  const withoutTimestamp = text.replace(/^\[Timestamp:[^\]]*\]\s*/, "").trim()
+  const firstLine = withoutTimestamp.split("\n").find((l) => l.trim().length > 0)?.trim()
+  if (!firstLine) return null
+  return firstLine.length > TITLE_MAX_CHARS
+    ? `${firstLine.slice(0, TITLE_MAX_CHARS - 1)}…`
+    : firstLine
+}
+
+/**
+ * Registra actividad en el hilo: contador, fecha del último mensaje y —la primera
+ * vez que habla el usuario— el título.
+ *
+ * Si el hilo tiene formato y no existe la fila, la crea (es el caso de un hilo que
+ * nació fuera de resolveContext, como el de una tarea programada). Si no lo tiene
+ * —hilo legacy, hilos aislados `task-*`— solo actualiza una fila ya existente:
+ * nunca inventa conversaciones para los hilos internos de los workers.
+ */
+export async function touchThread(
+  threadId: string,
+  opts: { role: "user" | "assistant" | "tool"; text?: string; internal?: boolean }
+): Promise<void> {
+  try {
+    const c = await threadsCol()
+    let existing = await c.get(threadId)
+
+    if (!existing) {
+      const parts = parseThreadId(threadId)
+      if (!parts) return
+      await ensureThread({ userId: parts.userId, channel: parts.channel, peerId: parts.peerId })
+      existing = await c.get(threadId)
+      if (!existing) return
+    }
+
+    // El contador se recalcula DENTRO del reintento, no fuera. `addMessage` llama
+    // acá sin esperar el resultado, así que dos mensajes seguidos se solapan: con
+    // el incremento calculado una sola vez, el reintento por conflicto de versión
+    // vuelve a escribir el valor viejo y el conteo se queda corto para siempre.
+    for (let attempt = 0; attempt < TOUCH_MAX_RETRIES; attempt++) {
+      const fresh = attempt === 0 ? existing : await c.get(threadId)
+      if (!fresh) return
+
+      const next: ConversationThreadDoc = {
+        ...fresh.doc,
+        last_message_at: Date.now(),
+        message_count: fresh.doc.message_count + 1,
+      }
+      // El título sale del primer mensaje humano: ni de la respuesta del agente ni
+      // de un evento interno (fan-in de delegación), que no describen el tema.
+      if (!fresh.doc.title && opts.role === "user" && !opts.internal && opts.text) {
+        const title = deriveTitle(opts.text)
+        if (title) next.title = title
+      }
+
+      try {
+        await c.put(threadId, next, { expectedVersion: fresh.version })
+        return
+      } catch {
+        // Conflicto de versión: otro mensaje del mismo hilo llegó primero.
+      }
+    }
+    log.warn(`demasiada contención actualizando el hilo ${threadId}`)
+  } catch (err) {
+    // El registro es un catálogo, no la fuente de verdad: nunca debe tumbar un turno.
+    log.warn(`no pude actualizar el hilo ${threadId}: ${(err as Error).message}`)
+  }
+}
+
+export async function listThreads(
+  userId: string,
+  opts?: { channel?: string; includeArchived?: boolean }
+): Promise<ConversationThreadDoc[]> {
+  const c = await threadsCol()
+  const rows = await c.findBy("user_id", userId)
+  return rows
+    .map((r) => r.doc)
+    .filter((d) => (opts?.channel ? d.channel === opts.channel : true))
+    .filter((d) => (opts?.includeArchived ? true : !d.archived))
+    .sort((a, b) => b.last_message_at - a.last_message_at)
+}
+
+/** La conversación de webchat en la que seguiría escribiendo el usuario. */
+export async function mostRecentWebThread(userId: string): Promise<ConversationThreadDoc | null> {
+  const threads = await listThreads(userId, { channel: "webchat" })
+  return threads[0] ?? null
+}
+
+export async function renameThread(threadId: string, title: string): Promise<void> {
+  const clean = title.trim().slice(0, 200)
+  await updateDoc<ConversationThreadDoc>("conversationThreads", threadId, { title: clean || null })
+}
+
+/**
+ * Archiva el hilo: sale de la lista pero no se pierde nada.
+ *
+ * Vive acá y no en `sessions/index.ts` para que las cuatro transiciones del
+ * ciclo de vida —crear, archivar, reabrir, borrar— disparen sus hooks desde un
+ * solo archivo. Repartidas, la próxima que se agregue se olvida de disparar.
+ */
+export async function archiveThread(threadId: string): Promise<void> {
+  const anterior = await getThread(threadId)
+  await updateDoc<ConversationThreadDoc>("conversationThreads", threadId, { archived: true })
+  // Archivar dos veces es un no-op, y el hook no debería enterarse dos veces.
+  if (anterior?.archived) return
+  await runSessionEnd({ threadId, userId: anterior?.user_id, channel: anterior?.channel })
+}
+
+/** Reabre un hilo archivado: vuelve a estar activo, y eso es un `sessionStart`. */
+export async function unarchiveThread(threadId: string): Promise<void> {
+  const anterior = await getThread(threadId)
+  await updateDoc<ConversationThreadDoc>("conversationThreads", threadId, { archived: false })
+  if (anterior && !anterior.archived) return
+  await runSessionStart({ threadId, userId: anterior?.user_id, channel: anterior?.channel })
+}
+
+/**
+ * Borra la conversación entera: mensajes, resumen, notas y la fila del registro.
+ * Los mensajes se localizan por prefijo, igual que los lee conversation-store.
+ */
+export async function deleteThread(threadId: string): Promise<void> {
+  const conversations = await col<ConversationDoc>("conversations")
+  const messages = await conversations.scan({ prefix: `${threadId}:` })
+  for (const m of messages) await conversations.delete(m.id)
+
+  const summaries = await col<SummaryDoc>("summaries")
+  await summaries.delete(threadId).catch(() => {})
+
+  const scratchpad = await col<{ threadId: string }>("scratchpad")
+  const notes = await scratchpad.scan({ prefix: `${threadId}:` })
+  for (const n of notes) await scratchpad.delete(n.id)
+
+  const c = await threadsCol()
+  // La fila se lee antes de borrarla: después no hay de dónde sacar el usuario
+  // ni el canal para el contexto del hook. El threadId los lleva codificados,
+  // pero el hilo legacy es id = userId pelado y no parsea.
+  const fila = (await c.get(threadId))?.doc
+  await c.delete(threadId).catch(() => {})
+
+  log.info(`conversación ${threadId} borrada (${messages.length} mensajes)`)
+  await runSessionEnd({
+    threadId,
+    userId: fila?.user_id ?? parseThreadId(threadId)?.userId,
+    channel: fila?.channel ?? parseThreadId(threadId)?.channel,
+  })
+}
+
+/**
+ * El hilo por el que hablarle a alguien en un canal cuando no venimos de un
+ * mensaje suyo (avisos de tareas programadas, por ejemplo).
+ *
+ * En la web es la conversación activa; en los demás canales, el contacto al que
+ * apunta `userIdentities`. Devuelve null si no hay ninguno, y quien llame decide
+ * el fallback.
+ */
+export async function threadForChannel(userId: string, channel: string): Promise<string | null> {
+  if (channel === "webchat") return (await mostRecentWebThread(userId))?.id ?? null
+
+  const identities = await col<{ channel_user_id?: string }>("userIdentities")
+  const identity = await identities.get(`${userId}:${channel}`)
+  const peerId = identity?.doc.channel_user_id
+  return peerId ? makeThreadId(userId, channel, peerId) : null
+}
+
+/**
+ * Registra el hilo anterior a la separación por canal —`thread_id = userId`, un
+ * único hilo compartido por todos los canales— como una conversación más de la
+ * web, para que su historial siga siendo accesible. No mueve ni reescribe ningún
+ * mensaje: la fila apunta al mismo prefijo de siempre.
+ */
+export async function ensureLegacyThread(userId: string): Promise<boolean> {
+  const c = await threadsCol()
+  if (await c.get(userId)) return false
+
+  const conversations = await col<ConversationDoc>("conversations")
+  const sample = await conversations.scan({ prefix: `${userId}:`, limit: 1 })
+  if (sample.length === 0) return false
+
+  const all = await conversations.scan({ prefix: `${userId}:` })
+  const lastAt = all.reduce((max, e) => Math.max(max, e.doc.created_at), 0)
+
+  await c.put(userId, {
+    id: userId,
+    user_id: userId,
+    channel: "webchat",
+    peer_id: "legacy",
+    peer_kind: "direct",
+    title: "Conversación anterior",
+    archived: false,
+    created_at: all[0]?.doc.created_at ?? Date.now(),
+    last_message_at: lastAt || Date.now(),
+    message_count: all.length,
+  }, { expectedVersion: 0 }).catch(() => {})
+
+  log.info(`hilo legacy ${userId} registrado como conversación (${all.length} mensajes)`)
+  return true
+}

package/packages/core/src/agent/tool-selector.ts

@@ -40,16 +40,16 @@
  *    - core (notify, report_progress, save_note)
  */
 
-import { col } from "../storage/hive"
-import type { ToolDoc } from "../storage/collections"
-import { logger } from "../utils/logger"
+import { col } from "../storage/hive.ts"
+import type { ToolDoc } from "../storage/collections.ts"
+import { logger } from "../utils/logger.ts"
 import {
     searchCapabilities,
     applyRelativeCutoff,
     replaceCapabilityDocs,
     type CapabilityDoc,
-} from "./capability-search"
-import { isCalendarOperation } from "./routing-intent"
+} from "./capability-search.ts"
+import { isCalendarOperation } from "./routing-intent.ts"
 
 const log = logger.child("tool-selector")
 
@@ -200,7 +200,11 @@ export const CORE_TOOL_CATALOG: ToolDescriptor[] = [
     { name: "api_request", description: "Perform an authorized HTTP request against a REST endpoint and validate the response. Spanish keywords: llamar api, request rest, consumir endpoint, petición http, hacer get, hacer post", category: "api", abstractionLevel: "atomic" },
 
     // Artifacts
+    { name: "computer_use_task", description: "Operate the browser by looking at the screen: click by coordinates, type and navigate when no stable CSS selector exists (canvas, generated UIs, embedded viewers). Acts on Hive's own browser, never on the user screen. Spanish keywords: usar el navegador, hacer clic donde veas, operar una página, rellenar formulario, computer use, mirar la pantalla", category: "browser", abstractionLevel: "orchestration" },
     { name: "artifact_inspect", description: "Inspect a managed artifact's integrity and metadata without modifying it. Spanish keywords: inspeccionar artefacto, verificar archivo generado, metadatos artefacto, comprobar entrega", category: "web", abstractionLevel: "atomic" },
+    { name: "artifact_read", description: "Read a managed artifact's text content in slices, or search inside it — the way to open any artifact_ref a tool returned. Spanish keywords: leer artefacto, ver contenido del artefacto, abrir resultado grande, buscar dentro del artefacto", category: "web", abstractionLevel: "atomic" },
+    { name: "image_metadata", description: "Read a stored image's dimensions and format without loading it into context. Spanish keywords: medir imagen, dimensiones de la imagen, tamaño de la foto, formato de imagen", category: "images", abstractionLevel: "atomic" },
+    { name: "image_transform", description: "Resize, rotate or convert a stored image, returning a new artifact — the original is untouched. Spanish keywords: redimensionar imagen, cambiar tamaño, convertir a webp, comprimir imagen, rotar foto, achicar imagen", category: "images", abstractionLevel: "atomic" },
 
     // Office documents — read
     { name: "office_leer_pdf", description: "Read and extract text from a PDF document. Spanish keywords: leer pdf, extraer texto pdf, abrir pdf, contenido pdf", category: "office", abstractionLevel: "atomic" },

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

@@ -6,9 +6,9 @@
  * `agents.lastTraceAt` field used by the Curator's stale-worker detection.
  */
 
-import { logger } from "../utils/logger"
-import { col, nextId, updateDoc } from "../storage/hive"
-import type { TraceDoc, AgentDoc } from "../storage/collections"
+import { logger } from "../utils/logger.ts"
+import { col, nextId, updateDoc } from "../storage/hive.ts"
+import type { TraceDoc, AgentDoc } from "../storage/collections.ts"
 
 const log = logger.child("tracer")
 
@@ -82,7 +82,7 @@ async function checkReflectorTrigger(): Promise<void> {
   _tracesSinceLastReflection = 0
 
   // Lazy import to avoid circular deps
-  const { runReflector } = await import("./reflector")
+  const { runReflector } = await import("./reflector.ts")
   runReflector().catch((err) => {
     log.warn("[tracer] Reflector run failed:", err)
   })
@@ -98,7 +98,7 @@ export function recordLLMUsage(opts: {
 }): void {
   Promise.resolve().then(async () => {
     try {
-      const { recordUsage } = await import("../storage/usage")
+      const { recordUsage } = await import("../storage/usage.ts")
       recordUsage({
         provider: opts.provider,
         model: opts.model,

package/packages/core/src/api/createAgent.ts

@@ -35,11 +35,28 @@ export interface Agent {
 	readonly name: string;
 	readonly id: string;
 	readonly config: AgentConfig;
-	chat(message: string, opts?: { threadId?: string; channel?: string }): AsyncGenerator<AgentEvent>;
+	/**
+	 * Con `stream: true` se emiten eventos `token` con los deltas del proveedor
+	 * a medida que llegan, además del `text` con la respuesta completa del turno.
+	 */
+	chat(
+		message: string,
+		opts?: { threadId?: string; channel?: string; stream?: boolean },
+	): AsyncGenerator<AgentEvent>;
 	run(task: string, opts?: { threadId?: string; channel?: string }): Promise<string>;
 }
 
 export type AgentEvent =
+	/**
+	 * Un fragmento recién llegado del proveedor, para pintar la respuesta
+	 * mientras se genera.
+	 *
+	 * Sólo aparece si se pide `stream: true`. Los proveedores ya emitían estos
+	 * deltas —el mecanismo estaba implementado— pero ningún punto de entrada los
+	 * pasaba, así que nunca llegaban a nadie: la respuesta aparecía de golpe al
+	 * terminar el turno.
+	 */
+	| { type: "token"; content: string }
 	| { type: "text"; content: string }
 	| { type: "tool_call"; name: string; args: Record<string, unknown> }
 	| { type: "tool_result"; name: string; result: unknown }
@@ -92,7 +109,7 @@ export async function createAgent(config: AgentConfig): Promise<Agent> {
 
 	const coreConfig = await loadConfig();
 
-	// Browser automation (agent-browser) si está habilitado.
+	// Browser automation (Bun.WebView) si está habilitado.
 	try {
 		const { initializeBrowserService } = await import("../tools/web/browser-service.ts");
 		const browserService = initializeBrowserService(coreConfig);
@@ -128,6 +145,40 @@ export async function createAgent(config: AgentConfig): Promise<Agent> {
 		}
 	}
 
+	// Las skills declaradas seguían el mismo camino que las tools —y hasta acá no
+	// lo seguían: `config.skills` estaba tipado y se descartaba en silencio, así
+	// que declarar una skill no hacía absolutamente nada. Una skill no necesita
+	// ejecutor (es instruccional: metadatos más el cuerpo que se le inyecta al
+	// agente), pero sí necesita su fila y su entrada en el índice, o el modelo
+	// nunca la descubre.
+	if (config.skills?.length) {
+		const { createSkill, getSkill, updateSkill } = await import("../services/skills.ts");
+
+		for (const skill of config.skills) {
+			// El cuerpo se arma con los pasos declarados: es lo que lee el agente.
+			const body = [
+				skill.description,
+				"",
+				...skill.steps.map((s, i) => `${i + 1}. **${s.action}** — ${s.instruction}`),
+			].join("\n");
+
+			const campos = {
+				name: skill.name,
+				description: skill.description,
+				category: skill.category,
+				body,
+				tools: skill.tools,
+				triggers: skill.triggers,
+				version: skill.version,
+			};
+
+			// Idempotente: declarar la misma skill dos veces la actualiza.
+			const existente = await getSkill(skill.name);
+			if (existente) await updateSkill(skill.name, campos);
+			else await createSkill({ id: skill.name, ...campos });
+		}
+	}
+
 	// ─── Provider y modelo ────────────────────────────────────────────────────
 	// El loop los lee de la fila del agente, así que hay que dejarlos escritos.
 	const providerId = config.provider ?? "";
@@ -241,6 +292,17 @@ export async function createAgent(config: AgentConfig): Promise<Agent> {
 			const threadId = opts?.threadId ?? crypto.randomUUID();
 			let response = "";
 
+			// `onToken` es un callback y esto es un generador: los deltas se
+			// encolan y se drenan entre chunks. Sin buffer habría que elegir entre
+			// perder tokens o bloquear al proveedor mientras el consumidor lee.
+			const pendientes: string[] = [];
+			const onToken = opts?.stream ? (t: string) => { pendientes.push(t); } : undefined;
+			const drenar = function* () {
+				while (pendientes.length > 0) {
+					yield { type: "token" as const, content: pendientes.shift()! };
+				}
+			};
+
 			for await (const chunk of runAgent({
 				agentId,
 				userMessage: message,
@@ -248,7 +310,9 @@ export async function createAgent(config: AgentConfig): Promise<Agent> {
 				channel: opts?.channel ?? "cli",
 				mcpManager,
 				userId,
+				onToken,
 			})) {
+				yield* drenar();
 				for (const msg of chunk.agent?.messages ?? []) {
 					if (typeof msg.content === "string" && msg.content) {
 						response = msg.content;
@@ -268,6 +332,7 @@ export async function createAgent(config: AgentConfig): Promise<Agent> {
 				}
 			}
 
+			yield* drenar();
 			yield { type: "done" as const, response };
 		},
 		async run(task, opts) {

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

@@ -0,0 +1,15 @@
+/**
+ * Artifacts — los archivos que produce un agente, fuera de la ventana de contexto.
+ *
+ * Cuando una tool devuelve algo grande —una imagen, un PDF, la salida enorme de
+ * un servidor MCP— serializarlo entero al prompt es lo peor que se puede hacer:
+ * se come el contexto y no aporta. En su lugar se guarda como artefacto y al
+ * modelo le llega una referencia (`artifact_ref`) que puede abrir con la tool
+ * `artifact_read` si de verdad necesita el contenido.
+ *
+ * `createArtifact` guarda; `inspectArtifact` da metadatos sin abrirlo;
+ * `readArtifactText` lo lee para consumo del propio proceso; `readArtifactBytes`
+ * devuelve los bytes crudos, que es lo que usa un canal para mandar la imagen.
+ */
+
+export * from "./store.ts";