@johpaz/hive-sdk 0.4.4 → 0.4.5

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 ## Sin publicar
 
+### Plataforma y seguridad
+
+- Runtime mínimo actualizado a **Bun 1.4.2** en `engines`, CI, publicación y
+  aplicaciones generadas.
+- Compilador actualizado a **TypeScript 7.0.2**. Se adaptaron las fronteras de
+  streams SSE, opciones WebSocket de Bun y memoria de audio a los tipos nuevos,
+  sin desactivar el chequeo.
+- Corregidas las alertas altas de PDF.js y SheetJS; los lectores Office ahora
+  limitan tamaño, páginas, hojas, filas y tiempo de procesamiento, y PDF.js
+  desactiva scripting y evaluación dinámica.
+- Eliminada la cadena vulnerable `pptxgenjs > image-size`. Hive conserva sólo
+  el artefacto ESM oficial necesario para PPTX de texto, con licencia,
+  procedencia, hash y una prueba funcional del OOXML generado.
+- Añadidas las guías `docs/UPGRADING.md` y
+  `docs/SECURITY-GUARDRAILS.md` para operación y auditoría.
+
 ### Corregido
 
 - **`browser_scrape` extraía con una tool que no ve lo que el navegador
@@ -103,9 +119,9 @@
   runtime. `cron-parser` además ni siquiera se importaba: estaba declarada en
   los dos `package.json` y se la bajaba todo el que instalara el SDK.
 
-  `Bun.cron()` **no** sirve como reemplazo —evaluado contra el runtime 1.4.0—:
+  `Bun.cron()` **no** sirve como reemplazo —reevaluado contra Bun 1.4.2—:
   acepta sólo 5 campos, rechaza una fecha ISO como patrón (que es como se
-  agendan los jobs `one_shot`), ignora la zona horaria en `parse()`, y su handle
+  agendan los jobs `one_shot`), no acepta una zona distinta por job, y su handle
   no expone la próxima corrida, de donde sale `next_run_at` y con lo que se
   detectan las corridas perdidas al arrancar. Tampoco tiene equivalente de
   `protect`, `maxRuns`, `interval`, `startAt`/`stopAt` ni `domAndDow`, todos
@@ -227,7 +243,7 @@
   de una browser tool. Una versión flotante bajada de npm en runtime, en
   producción. Eso ya no existe.
 
-  Requisitos ahora: un Chromium instalado (o `BUN_CHROME_PATH`) y **Bun ≥ 1.4**,
+  Requisitos ahora: un Chromium instalado (o `BUN_CHROME_PATH`) y **Bun ≥ 1.4.2**,
   declarado en `engines`. La clave de config `tools.browser.backend` sobrevive:
   `"agent-browser"` se acepta, avisa una vez y usa el WebView, así que las
   configuraciones viejas no se rompen.
@@ -242,7 +258,7 @@
   —clic por coordenadas, escribir, navegar— cuando no hay un selector CSS
   estable (canvas, UIs generadas, visores embebidos).
 
-- CI actualizado a **Bun 1.4.0**, alineado con `hive`.
+- CI actualizado a **Bun 1.4.2**, alineado con `hive`.
 
 ### Quitado
 

package/README.md

@@ -18,7 +18,7 @@ bun add @johpaz/hive-sdk
 
 - **Agentes**: ciclo ReAct nativo con checkpoint durable, 16 providers LLM y descubrimiento de tools/skills por búsqueda BM25.
 - **Catálogo**: 18 providers y 110 modelos sembrados, cada uno con su precio por millón de tokens — una sola fuente de verdad para el costo.
-- **Tools**: 60 tools incluidas — filesystem, web search, browser automation (`Bun.WebView`), APIs (`api_request`), a2ui, office, cron, delegación.
+- **Tools**: 60 tools incluidas — filesystem, web search, browser automation (`Bun.WebView`), APIs (`api_request`), a2ui, office, cron, delegación. Las de office validan la entrada antes de parsear (PDF 25 MiB, XLSX 15 MiB, 200 páginas, 50 hojas, 10 000 filas por hoja, 30 s de tope) y devuelven un error de tool en vez de truncar en silencio — importa cuando el archivo lo sube un tercero. Ver [SECURITY-GUARDRAILS.md](./docs/SECURITY-GUARDRAILS.md).
 - **Skills**: 23 workflows bundled, más los tuyos con `defineSkill` y `SkillLoader`.
 - **Canales**: Telegram, Discord, WhatsApp, Slack y WebChat con `ChannelManager`.
 - **Swarm**: orquestación multi-agente con `DAGScheduler`, `TaskGraph` y `WorkerPool`.
@@ -38,12 +38,39 @@ mismo CRUD que usan las tools, en funciones tipadas.
 
 ## Instalación
 
-> **Requiere Bun.** El paquete se publica como TypeScript y usa APIs de Bun
+> **Requiere Bun 1.4.2 o posterior y TypeScript 7.0.2.** El paquete se publica como TypeScript y usa APIs de Bun
 > (`Bun.secrets`, `Bun.spawn`, Workers) en 18 archivos del core, así que no
 > corre sobre Node aunque se le apliquen los flags de type-stripping. Si tu
 > backend es Node, hoy la vía es un proceso Bun aparte; el build a JS que
 > levantaría esa restricción todavía no existe.
 
+### Compilar el SDK desde tu proyecto
+
+Como el paquete se publica **en TypeScript**, tu `tsc` no lee declaraciones ya
+validadas: recompila el código del SDK con **tu** configuración. Eso significa que
+`skipLibCheck` no ayuda —sólo salta archivos `.d.ts`, y acá son `.ts` de verdad— y
+que una config más estricta que la del SDK puede sacar errores en código que no
+escribiste.
+
+El SDK se mantiene compilable en los dos entornos de tipos que importan:
+
+| entorno | `lib` | `types` | `strict` | errores |
+|---|---|---|---|---|
+| el del SDK | `ESNext, DOM, DOM.Iterable` | — | `false` | 0 |
+| servidor (Bun) | `ES2022` | `["bun"]` | `true` | 0 |
+
+Para lograrlo, el core no usa alias que sólo existen en la lib DOM
+(`RequestInfo`, `HeadersInit`, `BlobPart`): las uniones van escritas. Si tu
+proyecto es un backend, no necesitás agregar `DOM` a tu `lib` para consumirlo
+—y no conviene, porque `BufferSource` y `BlobPart` de DOM chocan con
+`Uint8Array` y `Buffer` de Node en tu propio código.
+
+Los `*.test.ts` no se publican, así que nada de la suite entra en tu typecheck.
+
+Para actualizar un proyecto existente, consulta [UPGRADING.md](./docs/UPGRADING.md).
+Los límites de entrada y controles de runtime están inventariados en
+[SECURITY-GUARDRAILS.md](./docs/SECURITY-GUARDRAILS.md).
+
 ```bash
 # Instalar globalmente para el CLI
 bun install -g @johpaz/hive-sdk
@@ -159,10 +186,15 @@ console.log(`Gateway at http://127.0.0.1:18790`);
 HIVE_HOME=~/.hive             # Directorio de datos (HiveDB vive en <HIVE_HOME>/data)
 HIVE_DB_PATH=                 # Ruta explícita de la base; ":memory:" para efímera
 HIVE_HOST=127.0.0.1           # Gateway host
-HIVE_PORT=18790               # Gateway port
+HIVE_PORT=18790               # Gateway port (inválido → avisa y usa el default)
 LOG_LEVEL=info                # debug | info | warn | error
 ```
 
+Desde Bun 1.4 `Bun.serve` lanza `RangeError` con un puerto fuera de `[0, 65535]`
+o con `NaN` —lo que devuelve `parseInt("no-es-un-numero")`— en vez de recortarlo,
+así que un `HIVE_PORT` mal escrito tumbaba el arranque con una excepción sin
+capturar. El SDK lo resuelve con `resolvePort`: avisa y sigue con el default.
+
 La API key de cada provider se guarda cifrada en la base. Como alternativa, el
 SDK cae a `<PROVIDER>_API_KEY` del entorno, en mayúsculas y con el id del
 provider tal cual:
@@ -179,15 +211,24 @@ OPENROUTER_API_KEY=sk-or-...
 ## Tests
 
 ```bash
-# Todos los tests (paralelo)
+# Toda la suite
 bun test
 
-# Tests con timeout extendido
+# Repartida entre procesos, uno por núcleo
+bun test --parallel
+
+# Timeout extendido
 bun test --timeout 60000
 ```
 
+`--parallel` (Bun 1.4) reparte los archivos entre procesos e implica
+`--isolate`, un global nuevo por archivo. Medido en este repo: **48 s → 18 s**,
+con resultados idénticos. Es lo que corre CI; en local `bun test` a secas sigue
+siendo secuencial, que da una salida más legible cuando estás sobre un archivo.
+
 La suite usa una base efímera (`HIVE_DB_PATH=":memory:"`, fijado en
-`test/preload.ts`) para no escribir en la del usuario.
+`test/preload.ts`) para no escribir en la del usuario. El `preload` sigue
+corriendo por archivo bajo `--isolate`.
 
 ## Publicar
 
@@ -230,4 +271,4 @@ npm view @johpaz/hive-sdk dist-tags   # verificar después del release
 
 ---
 
-*Hive SDK v0.4.4 — MIT*
+*Hive SDK v0.4.5 — MIT*

package/SECURITY.md

@@ -0,0 +1,17 @@
+# Security policy
+
+Los controles de entrada, dependencias, runtime y publicación están
+documentados en [`docs/SECURITY-GUARDRAILS.md`](docs/SECURITY-GUARDRAILS.md).
+
+## Vendored security-sensitive dependencies
+
+### PptxGenJS 4.0.1 ESM
+
+Hive vendors the official PptxGenJS 4.0.1 ESM artifact for the text-only
+`office_escribir_pptx` tool. The upstream npm package declares the vulnerable
+`image-size` package even though its ESM artifact does not import it. Vendoring
+that artifact removes `image-size` from Hive's installable dependency graph.
+
+The vendored copy, license, provenance, and update instructions live in
+`packages/core/src/vendor/pptxgenjs/`. Do not expose PPTX image input without a
+new security review.

package/docs/API-AGENTS.md

@@ -0,0 +1,430 @@
+# API Reference — Agentes
+
+## Índice
+
+1. [createAgent](#createagent)
+2. [AgentLoop](#agentloop)
+3. [Tool Selector](#tool-selector)
+4. [Skill Selector](#skill-selector)
+5. [LLM Providers](#llm-providers)
+
+---
+
+## createAgent
+
+Función de alto nivel para crear y ejecutar agentes.
+
+### Firma
+
+```typescript
+import { createAgent } from "@johpaz/hive-sdk";
+
+const agent = await createAgent(config: AgentConfig): Promise<Agent>
+```
+
+### AgentConfig
+
+```typescript
+interface AgentConfig {
+  name: string;
+  model?: string;         // id tal como lo nombra su dueño, ej. "claude-opus-5"
+  provider?: Provider;    // cualquiera de los 16 del catálogo
+  systemPrompt?: string;
+  tools?: ToolDefinition[];                 // Tools custom
+  skills?: SkillDefinition[];               // Skills custom
+  mcpServers?: Record<string, {             // Servidores MCP
+    command?: string;                       // STDIO transport
+    url?: string;                           // SSE transport
+    args?: string[];
+    env?: Record<string, string>;
+  }>;
+  maxIterations?: number;
+  workspace?: string;
+}
+```
+
+La config **se persiste en la fila del agente**, que es de donde el loop resuelve
+provider y modelo en cada turno. Consecuencias que conviene tener presentes:
+
+- `model` exige `provider`: el mismo modelo lo sirven varios providers y la clave
+  del catálogo depende de cuál. Sin provider, `createAgent` lanza.
+- El modelo tiene que existir en `SEED_DATA.models`, o lanza con el nombre del
+  provider al que no pertenece.
+- `name` deriva el id del agente (`"Mi Agente"` → `mi_agente`), así que dos
+  `createAgent` con el mismo nombre comparten fila e historial.
+- Las tools pasadas acá quedan registradas **y** indexadas, así que el modelo
+  puede descubrirlas con `search_knowledge` como a las nativas.
+
+> Hasta 0.1.5 `provider`, `model`, `maxIterations`, `skills` y `workspace` se
+> aceptaban y se descartaban: el agente corría con lo que hubiera en la base.
+
+### Agent
+
+```typescript
+interface Agent {
+  readonly name: string;
+  readonly config: AgentConfig;
+
+  // Streaming chat
+  chat(message: string, opts?: {
+    threadId?: string;
+    channel?: string;
+  }): AsyncGenerator<AgentEvent>;
+
+  // Run to completion (devuelve string final)
+  run(task: string, opts?: {
+    threadId?: string;
+    channel?: string;
+  }): Promise<string>;
+}
+```
+
+### AgentEvent
+
+```typescript
+type AgentEvent =
+  | { type: "token"; content: string }      // sólo con `stream: true`
+  | { type: "text"; content: string }
+  | { type: "tool_call"; name: string; args: Record<string, unknown> }
+  | { type: "tool_result"; name: string; result: unknown }
+  | { type: "done"; response: string };
+```
+
+#### Streaming por token
+
+```typescript
+for await (const ev of agent.chat("resumime esto", { stream: true })) {
+  if (ev.type === "token") process.stdout.write(ev.content);   // se va pintando
+  if (ev.type === "done") console.log("\n", ev.response);
+}
+```
+
+Sin `stream: true` el comportamiento es el de siempre: `text` con la respuesta
+completa del turno. Los proveedores ya emitían estos deltas, pero hasta 0.3.0
+ningún punto de entrada los pasaba, así que la respuesta aparecía de golpe al
+terminar.
+
+### Ejemplo
+
+```typescript
+import { createAgent, defineTool } from "@johpaz/hive-sdk";
+
+const agent = await createAgent({
+  name: "asistente",
+  provider: "openai",
+  model: "gpt-5.6-luna",
+  systemPrompt: "Eres un asistente útil.",
+});
+
+// Streaming
+for await (const event of agent.chat("Hola!")) {
+  if (event.type === "text") process.stdout.write(event.content);
+}
+
+// Run to completion
+const respuesta = await agent.run("Analiza las ventas del mes");
+```
+
+---
+
+## defineTool
+
+Define una herramienta que el agente puede invocar.
+
+```typescript
+import { defineTool } from "@johpaz/hive-sdk";
+
+const tool = defineTool({
+  name: "saludar",
+  description: "Saluda a alguien por su nombre",
+  execute: async (args: { nombre: string }) => {
+    return { mensaje: `¡Hola ${args.nombre}!` };
+  },
+});
+```
+
+### ToolDefinition
+
+```typescript
+interface ToolDefinition {
+  name: string;
+  description: string;
+  schema?: z.ZodType;             // Validación Zod opcional
+  execute: (args: any, config?: any) => Promise<any>;
+  category?: string;
+}
+```
+
+---
+
+## defineSkill
+
+Define una composición de herramientas con triggers semánticos.
+
+```typescript
+import { defineSkill } from "@johpaz/hive-sdk";
+
+const skill = defineSkill({
+  name: "analisis-datos",
+  description: "Analiza datos y genera reportes",
+  steps: [
+    { action: "web_search", instruction: "Buscar datos relevantes" },
+    { action: "create_report", instruction: "Generar reporte" },
+  ],
+  tools: ["web_search", "create_report"],
+  triggers: ["analizar", "reporte", "datos"],
+});
+```
+
+---
+
+## AgentLoop
+
+Clase de bajo nivel para control directo del bucle del agente.
+
+```typescript
+import { AgentLoop, buildAgentLoop } from "@johpaz/hive-sdk";
+
+const loop = buildAgentLoop({ mcpManager });
+
+const stream = loop.stream(
+  { messages: [{ role: "user", content: "Hola" }] },
+  { configurable: { thread_id: "thread-1" } }
+);
+
+for await (const chunk of stream) {
+  if (chunk.agent?.messages) {
+    console.log(chunk.agent.messages[0].content);
+  }
+  if (chunk.tools?.messages) {
+    console.log("Tool result:", chunk.tools.messages);
+  }
+}
+```
+
+### StreamChunk
+
+```typescript
+interface StreamChunk {
+  agent?: { messages: any[]; streamed?: boolean };
+  tools?: { messages: any[] };
+  usage?: { input_tokens: number; output_tokens: number };
+  /** Imágenes que produjeron las tools de este turno, como referencias. */
+  artifacts?: { images: Array<{ artifactId: string; mimeType: string }> };
+}
+```
+
+Cada `yield` es **una respuesta completa del modelo** o un resultado de tool, no
+un delta. Para deltas, `onToken` en `AgentLoopOptions` o `stream: true` en
+`agent.chat()`.
+
+### runAgent (bajo nivel)
+
+```typescript
+import { runAgent, runAgentIsolated } from "@johpaz/hive-sdk";
+
+// Streaming
+for await (const chunk of runAgent({
+  agentId: "assistant",
+  userMessage: "Analiza las ventas",
+  threadId: "thread-123",
+})) {
+  // procesar chunk
+}
+
+// Modo aislado (para workers DAG)
+const result = await runAgentIsolated({
+  agentId: "processor",
+  taskDescription: "Procesa estos datos",
+  threadId: "dag-thread",
+});
+```
+
+---
+
+## Tool Selector
+
+Selección automática de tools por búsqueda BM25 sobre el índice de capacidad.
+
+```typescript
+import { selectTools, CORE_TOOL_CATALOG } from "@johpaz/hive-sdk";
+
+// Seleccionar tools relevantes
+const tools = selectTools("Buscar archivos en el proyecto");
+console.log(tools.map(t => t.name));
+
+// Con límite personalizado
+const limited = selectTools("search query", CORE_TOOL_CATALOG, 3);
+```
+
+### Constantes
+
+```typescript
+const MIN_RELEVANCE_THRESHOLD = -30;
+```
+
+### CORE_TOOL_CATALOG
+
+60 tools built-in organizadas por categoría:
+
+| Categoría | # | Descripción |
+|-----------|---|-------------|
+| agents | 15 | delegación (`task_delegate`, `task_revise`), memoria, catálogo de modelos |
+| web | 10 | `web_search`, `web_fetch`, automatización de browser, `artifact_inspect` |
+| cron | 8 | tareas programadas |
+| office | 8 | PDF, DOCX, XLSX, PPTX |
+| filesystem | 7 | read, write, edit, delete, list, glob, exists |
+| a2ui | 4 | superficies de UI generadas por el agente |
+| core | 4 | `save_note`, `notify`, `report_progress`, `search_knowledge` |
+| cli | 1 | ejecución de comandos |
+| api | 1 | `api_request` |
+
+Las categorías `projects`, `canvas`, `codebridge`, `voice` y `meeting`
+desaparecieron en 0.1.5 junto con sus tools.
+
+---
+
+## Skill Selector
+
+```typescript
+import { selectSkills, getMinimalSkills } from "@johpaz/hive-sdk";
+
+// Skills según mensaje
+const skills = selectSkills("Analyze the sales data");
+
+// Skills mínimos siempre disponibles
+const minimal = getMinimalSkills();
+```
+
+---
+
+## LLM Providers
+
+### Providers Soportados
+
+16 providers, todos sembrados con su catálogo de modelos y su precio por millón
+de tokens. `provider` en `createAgent` acepta cualquiera de estos ids.
+
+| Provider | Adapter | Notas |
+|----------|---------|-------|
+| `anthropic` | nativo | extended thinking, round-trip de thinking blocks |
+| `gemini` | nativo | REST v1beta |
+| `ollama` | nativo | modelos locales, flag `think` |
+| `openai` | OpenAI-compat | Sol / Terra / Luna |
+| `deepseek`, `kimi` | OpenAI-compat | round-trip de `reasoning_content` |
+| `mistral`, `groq`, `qwen`, `minimax` | OpenAI-compat | |
+| `z-ai` | OpenAI-compat | sirve en `/api/paas/v4`, no en `/v1` |
+| `hiveagents` | OpenAI-compat | |
+| `nvidia`, `openrouter`, `opencode-go`, `modelscope` | OpenAI-compat | **revendedores** |
+
+Los cuatro revendedores prefijan sus ids de modelo con su propio id de provider
+(`modelscope/Qwen/Qwen3.5-397B-A17B`), porque sirven modelos de terceros que se
+solapan entre sí y la colección `models` se indexa por una sola clave. El
+prefijo no llega al cable: el adapter lo quita antes del request.
+
+```typescript
+import { catalogModelKey, wireModelId } from "@johpaz/hive-sdk";
+
+catalogModelKey("modelscope", "Qwen/Qwen3.5-397B-A17B"); // modelscope/Qwen/Qwen3.5-397B-A17B
+wireModelId("modelscope", "modelscope/Qwen/Qwen3.5-397B-A17B"); // Qwen/Qwen3.5-397B-A17B
+```
+
+### Errores del provider
+
+`callLLM` nunca lanza: devuelve `stop_reason: "error"` con un campo `error`
+tipado. Chequealo antes de persistir `content` en cualquier lado — es texto para
+mostrar, no salida del modelo.
+
+```typescript
+const response = await callLLM({ ... });
+
+if (response.stop_reason === "error") {
+  console.error(response.error?.message);
+  // HTTP 404/410 → el proveedor retiró el modelo; reintentar no sirve.
+  if (response.error?.modelUnavailable) selectAnotherModel();
+}
+```
+
+### callLLM
+
+```typescript
+import { callLLM, resolveProviderConfig } from "@johpaz/hive-sdk";
+
+const config = await resolveProviderConfig("openai", "gpt-5.6-luna");
+
+const response = await callLLM({
+  provider: config.provider,
+  model: config.model,
+  messages: [{ role: "user", content: "Hola" }],
+});
+```
+
+---
+
+## Errores Comunes
+
+### createAgent: no se encuentra el agente
+
+```typescript
+// El agente no necesita existir en DB — createAgent lo gestiona internamente
+// Si falla, verificar API keys en variables de entorno
+```
+
+### Tool no encontrada
+
+```typescript
+// Verificar que la tool está registrada
+const reg = new ToolRegistry();
+reg.register(myTool);
+reg.has("my_tool"); // true
+```
+
+### Context too large
+
+```typescript
+// Usar maybeCompact para reducir historial
+const { maybeCompact } = await import("../agent/Compaction.ts");
+await maybeCompact(threadId, { channel, userId });
+```
+
+## Resto de la superficie del loop
+
+Todo desde `@johpaz/hive-sdk`.
+
+### Ejecutar
+
+| | |
+|---|---|
+| `runAgent(opts)` | El loop. Devuelve un `AsyncGenerator<StreamChunk>`. |
+| `runAgentIsolated(opts)` | Un worker en contexto aislado; devuelve sólo el texto final. Es lo que usan el enjambre y `task_delegate`. |
+| `runAgentIsolatedDetailed(opts)` | Igual, pero además devuelve la evidencia de las tools que usó — la necesita quien tenga que justificar una entrega. |
+| `createAgentRunner(config, opts?)` | Un `AgentRunner` listo. Construye el loop global, que es lo que `generate()` necesita: `new AgentRunner()` a secas se instancia sin quejarse y falla en la primera llamada. |
+
+### El loop global
+
+`buildAgentLoop(opts)` lo construye, `getAgentLoop()` lo devuelve (o `null`), y
+`rebuildAgentLoop(opts)` lo rehace — por ejemplo tras conectar un manager MCP.
+
+Es estado de proceso: un host multi-inquilino que corra varias colmenas a la vez
+debería usar `runAgent()` directo con `credentials` por llamada, no este
+singleton.
+
+### Errores
+
+| | |
+|---|---|
+| `LLMCallTimeoutError` | Una llamada al proveedor agotó su ventana. Es por llamada, no del turno entero. |
+| `AgentSynthesisError` | El modelo no pudo redactar la respuesta final tras dos intentos. |
+
+`withTimeout(op, ms)` acota una operación a su propia ventana, independiente de
+la del turno. Es lo que evita que una tool lenta se lleve puesto el turno entero.
+
+### Interno, expuesto por utilidad
+
+`synthesizeFinalResponse` fuerza el cierre de un turno que se quedó sin
+iteraciones. `injectArtifactReadIfNeeded` agrega `artifact_read` al loadout en
+cuanto un resultado devuelve un `artifact_ref` que el modelo va a necesitar
+abrir: descubrirla por búsqueda costaría una iteración y asume que al modelo se
+le ocurra buscarla.
+
+*Documentación Hive SDK — ver `version` en package.json*

package/docs/API-ARTIFACTS.md

@@ -0,0 +1,55 @@
+# API-ARTIFACTS — archivos fuera de la ventana de contexto
+
+## Por qué existe
+
+Cuando algo grande entra al turno —una imagen, un PDF, la salida enorme de un
+servidor MCP— serializarlo 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 `artifact_read` si de
+verdad necesita el contenido.
+
+Es el mismo mecanismo que sostiene tres cosas distintas: los resultados grandes
+de MCP (`mcp-result-normalizer.ts`), las capturas de navegador, y las imágenes
+que manda el usuario en una conversación.
+
+```typescript
+import { createArtifact, listArtifacts } from "@johpaz/hive-sdk/artifacts";
+```
+
+## Guardar y leer
+
+| | |
+|---|---|
+| `createArtifact(input)` | Guarda bytes y devuelve la ficha. `expiresAt: null` = no caduca. |
+| `readArtifactBytes(id)` | Los bytes crudos — lo que usa un canal para adjuntar una imagen. |
+| `readArtifactText(id, opts?)` | El contenido como texto, para consumo en proceso. Rechaza lo binario y lo que supere 25 MB: un artefacto más grande que eso ya no es algo que quepa en una ventana de contexto. |
+| `inspectArtifact(id, opts?)` | Metadatos sin abrirlo. |
+| `listArtifacts(userId, opts?)` | Lo que tiene un usuario, de lo más reciente a lo más viejo. Filtra por `kind`. |
+
+## Retención
+
+Los artefactos **internos** —capturas, resultados de tools— son basura
+transitoria y se limpian solos a los 7 días. Lo que **sube o transforma un
+usuario** no lo es: borrárselo a la semana convierte un servicio en una pérdida
+de datos.
+
+| | |
+|---|---|
+| `setArtifactRetention(id, expiresAt)` | `null` = conservarlo indefinidamente. |
+| `deleteArtifact(id)` | Borra la fila y el archivo, ahora. |
+| `expireArtifacts(now?)` | La limpieza. Salta los `expires_at: null`. |
+
+`deleteArtifact` elimina la fila; `expireArtifacts` la conserva marcada como
+`expired`. La diferencia es intencional: si alguien pidió borrar, dejar el rastro
+es lo contrario de lo que pidió.
+
+> **Cuidado al tocar la limpieza**: en JavaScript `null > now` es `false`, así
+> que una comprobación de caducidad escrita a la ligera trataría "no expira
+> nunca" como "ya venció" y **borraría el archivo**. La comprobación del `null`
+> va antes de comparar fechas.
+
+Para trabajar con imágenes concretamente, `@johpaz/hive-sdk/services` expone
+`uploadImage`, `listImages` y `setImageRetention`, que es esta misma capa con la
+forma que espera una UI.
+
+*Documentación Hive SDK — ver `version` en package.json*