@johpaz/hive-sdk 0.1.6 → 0.3.0

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

@@ -0,0 +1,268 @@
+/**
+ * Sessions — la conversación de un usuario, como una sola cosa.
+ *
+ * Hasta acá "sesión" estaba repartida en cuatro capas que nadie unía:
+ *
+ *  - `agent/thread-store.ts`      — identidad y catálogo (`conversationThreads`)
+ *  - `agent/conversation-store.ts`— los mensajes (`conversations`, por prefijo)
+ *  - `agent/run-store.ts`         — la ejecución: checkpoint, lease, resume
+ *  - `state/store.ts`             — un `Map` en memoria que muere con el proceso
+ *
+ * El resultado eran dos identificadores para lo mismo —`thread_id` para la
+ * conversación y `run_id` para la ejecución— y ninguna forma de preguntar "qué
+ * sesiones tiene este usuario" sin escanear mensajes.
+ *
+ * Este módulo **no agrega una tercera persistencia**: `Session` es una vista
+ * compuesta sobre las colecciones que ya existen. `Session.id` ES el `threadId`.
+ * Agregar una colección propia habría recreado exactamente la duplicación que
+ * este módulo viene a cerrar.
+ *
+ * `state/store.ts` queda para métricas efímeras; no es la sesión.
+ */
+
+import type { ContentPart } from "../multimodal/types.ts"
+import type { AgentRunDoc, ConversationThreadDoc } from "../storage/collections.ts"
+import {
+  addMessage,
+  getHistory,
+  type StoredMessage,
+} from "../agent/conversation-store.ts"
+import {
+  archiveThread,
+  createWebConversation,
+  deleteThread,
+  ensureThread,
+  getThread,
+  listThreads,
+  mostRecentWebThread,
+  renameThread,
+  threadForChannel,
+  unarchiveThread,
+} from "../agent/thread-store.ts"
+import {
+  deserializeCheckpoint,
+  findRunsByThread,
+  type RunCheckpointState,
+} from "../agent/run-store.ts"
+
+export * from "../agent/thread-id.ts"
+export * from "./resolve.ts"
+
+/** El estado de ejecución más reciente del hilo, si alguna vez corrió. */
+export interface SessionRun {
+  runId: string
+  agentId: string
+  status: AgentRunDoc["status"]
+  kind: AgentRunDoc["kind"]
+  updatedAt: number
+  /** true cuando quedó a medias y `resumeSession` puede retomarla. */
+  resumable: boolean
+}
+
+/**
+ * Una sesión: la identidad del hilo más, opcionalmente, su última ejecución.
+ * Es una vista, no una fila: se compone de `conversationThreads` + `agentRuns`.
+ */
+export interface Session {
+  /** ES el threadId (`${user}/${canal}/${peer}`). */
+  id: string
+  userId: string
+  channel: string
+  peerId: string
+  peerKind: "direct" | "group"
+  title: string | null
+  archived: boolean
+  createdAt: number
+  lastMessageAt: number
+  messageCount: number
+  lastRun?: SessionRun
+}
+
+/** Una ejecución interrumpida sigue siendo retomable; una terminada no. */
+const RESUMABLE_STATUSES: ReadonlySet<AgentRunDoc["status"]> = new Set([
+  "interrupted",
+  "running",
+])
+
+function toSessionRun(run: AgentRunDoc): SessionRun {
+  return {
+    runId: run.id,
+    agentId: run.agent_id,
+    status: run.status,
+    kind: run.kind,
+    updatedAt: run.updated_at ?? run.created_at,
+    resumable: RESUMABLE_STATUSES.has(run.status),
+  }
+}
+
+function toSession(doc: ConversationThreadDoc, lastRun?: SessionRun): Session {
+  return {
+    id: doc.id,
+    userId: doc.user_id,
+    channel: doc.channel,
+    peerId: doc.peer_id,
+    peerKind: doc.peer_kind,
+    title: doc.title,
+    archived: doc.archived,
+    createdAt: doc.created_at,
+    lastMessageAt: doc.last_message_at,
+    messageCount: doc.message_count,
+    ...(lastRun ? { lastRun } : {}),
+  }
+}
+
+/** La ejecución más reciente del hilo, o undefined si nunca corrió. */
+async function latestRun(threadId: string): Promise<SessionRun | undefined> {
+  const runs = await findRunsByThread(threadId)
+  if (runs.length === 0) return undefined
+  const newest = runs.reduce((a, b) =>
+    (b.updated_at ?? b.created_at) > (a.updated_at ?? a.created_at) ? b : a,
+  )
+  return toSessionRun(newest)
+}
+
+export interface CreateSessionInput {
+  userId: string
+  channel: string
+  peerId: string
+  peerKind?: "direct" | "group"
+}
+
+/**
+ * Abre la sesión de un usuario en un canal, o devuelve la que ya existía.
+ * Idempotente: se puede llamar en cada turno.
+ */
+export async function createSession(input: CreateSessionInput): Promise<Session> {
+  const threadId = await ensureThread(input)
+  const doc = await getThread(threadId)
+  if (!doc) throw new Error(`No se pudo abrir la sesión ${threadId}`)
+  return toSession(doc)
+}
+
+/** Una conversación nueva de la web, con su propio id (no reusa la anterior). */
+export async function createWebSession(userId: string, title?: string): Promise<Session> {
+  return toSession(await createWebConversation(userId, title))
+}
+
+export async function getSession(sessionId: string): Promise<Session | null> {
+  const doc = await getThread(sessionId)
+  if (!doc) return null
+  return toSession(doc, await latestRun(sessionId))
+}
+
+export interface ListSessionsOptions {
+  channel?: string
+  includeArchived?: boolean
+  /**
+   * Adjunta la última ejecución de cada sesión. Cuesta una consulta por sesión,
+   * así que está apagado por defecto: la lista de conversaciones no lo necesita.
+   */
+  withRuns?: boolean
+}
+
+/**
+ * Las sesiones de un usuario, de la más reciente a la más vieja.
+ *
+ * Es la consulta que antes no existía: el estado en memoria se perdía en cada
+ * reinicio y los mensajes sólo se podían leer por prefijo de un hilo conocido.
+ */
+export async function listSessions(
+  userId: string,
+  opts?: ListSessionsOptions,
+): Promise<Session[]> {
+  const docs = await listThreads(userId, {
+    channel: opts?.channel,
+    includeArchived: opts?.includeArchived,
+  })
+  if (!opts?.withRuns) return docs.map((d) => toSession(d))
+  return Promise.all(docs.map(async (d) => toSession(d, await latestRun(d.id))))
+}
+
+/** La sesión de webchat en la que el usuario seguiría escribiendo. */
+export async function mostRecentWebSession(userId: string): Promise<Session | null> {
+  const doc = await mostRecentWebThread(userId)
+  return doc ? toSession(doc) : null
+}
+
+/**
+ * La sesión por la que hablarle a alguien en un canal cuando no venimos de un
+ * mensaje suyo (un aviso de tarea programada, por ejemplo). null si no hay.
+ */
+export async function sessionForChannel(
+  userId: string,
+  channel: string,
+): Promise<string | null> {
+  return threadForChannel(userId, channel)
+}
+
+/**
+ * Agrega un mensaje y mantiene al día el catálogo (título, orden, contador):
+ * `addMessage` ya llama a `touchThread`, así que no hay que hacerlo acá.
+ *
+ * Ojo: esa actualización del catálogo es deliberadamente *fire-and-forget* —
+ * persistir el mensaje nunca se bloquea por el contador. En la práctica eso
+ * significa que `messageCount` y `title` son de consistencia eventual: leer la
+ * sesión inmediatamente después de escribir puede devolver el valor anterior.
+ * El historial (`getSessionHistory`) sí es consistente al instante.
+ */
+export async function appendMessage(
+  sessionId: string,
+  role: StoredMessage["role"],
+  content: string | ContentPart[],
+  opts?: Parameters<typeof addMessage>[3],
+): Promise<number> {
+  return addMessage(sessionId, role, content, opts)
+}
+
+export async function getSessionHistory(
+  sessionId: string,
+  limit?: number,
+): Promise<StoredMessage[]> {
+  return getHistory(sessionId, limit)
+}
+
+export interface ResumableSession {
+  run: SessionRun
+  checkpoint: RunCheckpointState
+}
+
+/**
+ * El trabajo a medias de una sesión, listo para retomar.
+ *
+ * Devuelve null cuando no hay nada que retomar — que es el caso normal. Un run
+ * `running` sin checkpoint tampoco sirve: murió antes de guardar estado.
+ */
+export async function resumeSession(sessionId: string): Promise<ResumableSession | null> {
+  const runs = await findRunsByThread(sessionId)
+  const candidates = runs
+    .filter((r) => RESUMABLE_STATUSES.has(r.status))
+    .sort((a, b) => (b.updated_at ?? b.created_at) - (a.updated_at ?? a.created_at))
+
+  for (const run of candidates) {
+    const checkpoint = deserializeCheckpoint(run)
+    if (checkpoint) return { run: toSessionRun(run), checkpoint }
+  }
+  return null
+}
+
+export async function renameSession(sessionId: string, title: string): Promise<void> {
+  return renameThread(sessionId, title)
+}
+
+/**
+ * Cierra la sesión sin perder nada: sale de la lista pero el historial queda.
+ * Para borrarla de verdad, `deleteSession`.
+ */
+export async function closeSession(sessionId: string): Promise<void> {
+  return archiveThread(sessionId)
+}
+
+/** Reabre una sesión archivada. */
+export async function reopenSession(sessionId: string): Promise<void> {
+  return unarchiveThread(sessionId)
+}
+
+/** Borra la sesión entera: mensajes, resumen, notas y su fila del catálogo. */
+export async function deleteSession(sessionId: string): Promise<void> {
+  return deleteThread(sessionId)
+}

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.