@johpaz/hive-sdk 0.1.6 → 0.3.0

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

@@ -0,0 +1,203 @@
+/**
+ * Hooks — engancharse al ciclo de vida sin bifurcar el SDK.
+ *
+ * `HooksConfigSchema` (`config/loader.ts`) declaraba 14 hooks y **ninguno se
+ * invocaba**: era un esquema sin implementación. Quien lo encontrara asumiría
+ * que funciona.
+ *
+ * Acá se implementan, con dos formas y una decisión de diseño detrás:
+ *
+ *  - **Callbacks en proceso** (`registerHook`) — tipados, sin costo de arranque,
+ *    y pueden **devolver una decisión**: `beforeToolCall` puede impedir que una
+ *    tool se ejecute. Es el primitivo, porque quien consume el SDK ya está en el
+ *    mismo proceso.
+ *  - **Scripts externos** (`hooks.scripts` en la configuración) — para quien no
+ *    escribe TypeScript. Se montan encima del primitivo: cada script declarado
+ *    se registra como un callback que lo ejecuta. Cuestan un `Bun.spawn` por
+ *    invocación, así que conviene reservarlos para lo que no ocurre en cada
+ *    tool call.
+ *
+ * Sólo están los hooks que tienen un uso claro. Los otros nueve del esquema
+ * original se dejaron fuera a propósito: cada hook es una promesa que después
+ * hay que sostener, y uno que nadie usa es superficie que envejece mal.
+ */
+
+import { logger } from "../utils/logger.ts";
+import { loadConfig } from "../config/loader.ts";
+
+const log = logger.child("hooks");
+
+/** Lo que recibe un hook de tool. */
+export interface ToolCallContext {
+  toolName: string;
+  args: Record<string, unknown>;
+  agentId?: string;
+  userId?: string;
+  threadId?: string;
+}
+
+export interface ToolResultContext extends ToolCallContext {
+  result: unknown;
+  ok: boolean;
+  durationMs: number;
+}
+
+export interface CompactionContext {
+  threadId: string;
+  messageCount: number;
+  totalTokens: number;
+}
+
+export interface SessionContext {
+  threadId: string;
+  userId?: string;
+  channel?: string;
+}
+
+/**
+ * Lo que puede devolver `beforeToolCall`.
+ *
+ * `void` o `undefined` = seguir adelante. Devolver `{ block }` impide la
+ * ejecución y el motivo le llega al modelo como resultado de la tool, para que
+ * sepa por qué no se hizo en vez de reintentar a ciegas.
+ */
+export type BeforeToolCallResult = void | undefined | { block: true; reason: string };
+
+export interface HookMap {
+  beforeToolCall: (ctx: ToolCallContext) => BeforeToolCallResult | Promise<BeforeToolCallResult>;
+  afterToolCall: (ctx: ToolResultContext) => void | Promise<void>;
+  beforeCompaction: (ctx: CompactionContext) => void | Promise<void>;
+  sessionStart: (ctx: SessionContext) => void | Promise<void>;
+  sessionEnd: (ctx: SessionContext) => void | Promise<void>;
+}
+
+export type HookName = keyof HookMap;
+
+const registry: { [K in HookName]: Array<HookMap[K]> } = {
+  beforeToolCall: [],
+  afterToolCall: [],
+  beforeCompaction: [],
+  sessionStart: [],
+  sessionEnd: [],
+};
+
+/**
+ * Registra un hook. Devuelve la función para quitarlo.
+ *
+ * Se pueden registrar varios del mismo tipo: corren en orden de registro.
+ */
+export function registerHook<K extends HookName>(name: K, fn: HookMap[K]): () => void {
+  registry[name].push(fn);
+  return () => {
+    const i = registry[name].indexOf(fn);
+    if (i >= 0) registry[name].splice(i, 1);
+  };
+}
+
+/** Quita todos los hooks. Pensado para tests. */
+export function clearHooks(name?: HookName): void {
+  if (name) registry[name] = [];
+  else for (const k of Object.keys(registry) as HookName[]) registry[k] = [];
+}
+
+export function hasHooks(name: HookName): boolean {
+  return registry[name].length > 0;
+}
+
+/**
+ * Corre los `beforeToolCall` y devuelve el motivo del bloqueo, si alguno objeta.
+ *
+ * El primero que bloquea gana: no tiene sentido seguir preguntando cuando ya
+ * hay una negativa. Un hook que lanza **no** bloquea la ejecución —un error en
+ * el observador no debería impedir el trabajo— pero se registra.
+ */
+export async function runBeforeToolCall(ctx: ToolCallContext): Promise<string | null> {
+  for (const fn of registry.beforeToolCall) {
+    try {
+      const r = await fn(ctx);
+      if (r && typeof r === "object" && r.block) return r.reason;
+    } catch (err) {
+      log.warn(`beforeToolCall falló para ${ctx.toolName}: ${(err as Error).message}`);
+    }
+  }
+  return null;
+}
+
+/** Corre los hooks de observación. Nunca lanza: son observadores. */
+async function runObservers<K extends "afterToolCall" | "beforeCompaction" | "sessionStart" | "sessionEnd">(
+  name: K,
+  ctx: Parameters<HookMap[K]>[0],
+): Promise<void> {
+  for (const fn of registry[name]) {
+    try {
+      await (fn as (c: unknown) => unknown)(ctx);
+    } catch (err) {
+      log.warn(`${name} falló: ${(err as Error).message}`);
+    }
+  }
+}
+
+export const runAfterToolCall = (ctx: ToolResultContext) => runObservers("afterToolCall", ctx);
+export const runBeforeCompaction = (ctx: CompactionContext) => runObservers("beforeCompaction", ctx);
+export const runSessionStart = (ctx: SessionContext) => runObservers("sessionStart", ctx);
+export const runSessionEnd = (ctx: SessionContext) => runObservers("sessionEnd", ctx);
+
+// ─── Scripts declarados en la configuración ──────────────────────────────────
+
+/** Nombres del esquema de config → hooks implementados. */
+const SCRIPT_MAP: Record<string, HookName> = {
+  before_tool_call: "beforeToolCall",
+  after_tool_call: "afterToolCall",
+  before_compaction: "beforeCompaction",
+  session_start: "sessionStart",
+  session_end: "sessionEnd",
+};
+
+/**
+ * Ejecuta un script pasándole el contexto como JSON por stdin.
+ *
+ * Convención para `before_tool_call`: **salir con código distinto de 0 bloquea**
+ * la ejecución, y lo que el script escriba en stdout es el motivo que se le
+ * cuenta al modelo. Es el equivalente en procesos a devolver `{ block }`.
+ */
+async function runScript(path: string, ctx: unknown): Promise<{ blocked: boolean; reason: string }> {
+  const proc = Bun.spawn(["bun", path], { stdin: "pipe", stdout: "pipe", stderr: "pipe" });
+  proc.stdin.write(JSON.stringify(ctx));
+  proc.stdin.end();
+
+  const [salida, code] = await Promise.all([new Response(proc.stdout).text(), proc.exited]);
+  return { blocked: code !== 0, reason: salida.trim() || `el hook ${path} salió con código ${code}` };
+}
+
+let scriptsCargados = false;
+
+/**
+ * Registra los scripts declarados en `hooks.scripts`.
+ *
+ * Es opt-in y explícito: ejecutar procesos externos no es algo que deba pasar
+ * por el solo hecho de importar el SDK. Idempotente.
+ */
+export function loadConfiguredHookScripts(): number {
+  if (scriptsCargados) return 0;
+  const scripts = loadConfig().hooks?.scripts;
+  if (!scripts) return 0;
+
+  let n = 0;
+  for (const [clave, hook] of Object.entries(SCRIPT_MAP)) {
+    const path = (scripts as Record<string, string | undefined>)[clave];
+    if (!path) continue;
+
+    if (hook === "beforeToolCall") {
+      registerHook("beforeToolCall", async (ctx) => {
+        const r = await runScript(path, ctx);
+        return r.blocked ? { block: true as const, reason: r.reason } : undefined;
+      });
+    } else {
+      registerHook(hook as "afterToolCall", async (ctx) => { await runScript(path, ctx); });
+    }
+    n++;
+    log.info(`hook ${clave} → ${path}`);
+  }
+  scriptsCargados = true;
+  return n;
+}

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

@@ -0,0 +1,161 @@
+/**
+ * Imágenes — redimensionar, convertir y medir, sin dependencias nativas.
+ *
+ * Usa `Bun.Image` (Bun 1.4), que es sharp integrado en el runtime: no hay que
+ * instalar nada ni compilar bindings. El SDK ya exige Bun ≥ 1.4, así que esto
+ * no agrega ningún requisito.
+ *
+ * Sirve para dos cosas distintas y conviene no confundirlas:
+ *
+ *  1. **Tools activables** para el agente (`tools/images/`) — recortar, convertir
+ *     de formato, leer dimensiones. Es una capacidad de producto.
+ *  2. **Normalizar lo que entra** — una foto de 4 MB que un usuario manda por
+ *     WhatsApp no tiene por qué viajar entera al modelo. Redimensionarla antes
+ *     cuesta una fracción de los tokens y no cambia lo que el modelo puede ver.
+ *
+ * Nota sobre `Bun.Image`: las transformaciones son **diferidas**. `metadata()`
+ * sobre una cadena sin materializar devuelve las dimensiones del origen, no las
+ * del resultado — hay que pedir los bytes y releerlos. `measureImage()` lo hace
+ * por vos cuando hace falta.
+ */
+
+import { logger } from "../utils/logger.ts";
+
+const log = logger.child("images");
+
+/** Los que `Bun.Image` sabe escribir. */
+export type ImageFormat = "jpeg" | "png" | "webp" | "avif" | "heic";
+
+export interface ImageMetadata {
+  width: number;
+  height: number;
+  format: string;
+}
+
+export interface TransformOptions {
+  /** Ancho máximo; la altura se ajusta manteniendo la proporción si no se da. */
+  width?: number;
+  height?: number;
+  format?: ImageFormat;
+  /** 1–100. Sólo lo respetan los formatos con pérdida. */
+  quality?: number;
+  /** Grados: 90, 180, 270. */
+  rotate?: number;
+  flip?: boolean;
+  flop?: boolean;
+}
+
+function bunImage(): any {
+  const I = (Bun as any).Image;
+  if (!I) {
+    throw new Error("Bun.Image no está disponible: se necesita Bun >= 1.4");
+  }
+  return I;
+}
+
+function toBytes(input: Uint8Array | ArrayBuffer | Buffer | string): Uint8Array {
+  if (typeof input === "string") return Uint8Array.from(Buffer.from(input, "base64"));
+  if (input instanceof Uint8Array) return input;
+  return new Uint8Array(input as ArrayBuffer);
+}
+
+/** Dimensiones y formato sin decodificar la imagen entera. */
+export async function measureImage(input: Uint8Array | ArrayBuffer | Buffer | string): Promise<ImageMetadata> {
+  const meta = await new (bunImage())(toBytes(input)).metadata();
+  return { width: meta.width, height: meta.height, format: meta.format };
+}
+
+/**
+ * Aplica las transformaciones y devuelve los bytes resultantes.
+ *
+ * Sin `format` conserva el de origen. Sin nada que hacer devuelve la entrada tal
+ * cual, para no recomprimir de gusto.
+ */
+export async function transformImage(
+  input: Uint8Array | ArrayBuffer | Buffer | string,
+  opts: TransformOptions,
+): Promise<{ bytes: Uint8Array; metadata: ImageMetadata }> {
+  const bytes = toBytes(input);
+  const hayQueHacer = opts.width || opts.height || opts.format || opts.rotate || opts.flip || opts.flop;
+  if (!hayQueHacer) return { bytes, metadata: await measureImage(bytes) };
+
+  let img = new (bunImage())(bytes);
+
+  if (opts.width || opts.height) img = img.resize(opts.width, opts.height);
+  if (opts.rotate) img = img.rotate(opts.rotate);
+  if (opts.flip) img = img.flip();
+  if (opts.flop) img = img.flop();
+
+  const formato = opts.format ?? ((await measureImage(bytes)).format as ImageFormat);
+  const args = opts.quality !== undefined ? [{ quality: opts.quality }] : [];
+  img = typeof img[formato] === "function" ? img[formato](...args) : img;
+
+  const salida: Uint8Array = await img.bytes();
+  // Se releen los bytes porque `metadata()` sobre la cadena diferida informa el
+  // origen, no el resultado.
+  return { bytes: salida, metadata: await measureImage(salida) };
+}
+
+export interface NormalizeOptions {
+  /** Lado mayor permitido. Por encima se reduce manteniendo la proporción. */
+  maxDimension?: number;
+  /** Formato de salida; `webp` pesa mucho menos que un JPEG equivalente. */
+  format?: ImageFormat;
+  quality?: number;
+}
+
+/** Por defecto: 1024 px de lado mayor y webp al 80 — el punto donde un modelo de visión deja de ganar detalle. */
+const NORMALIZE_DEFAULTS: Required<NormalizeOptions> = {
+  maxDimension: 1024,
+  format: "webp",
+  quality: 80,
+};
+
+export interface NormalizeResult {
+  bytes: Uint8Array;
+  metadata: ImageMetadata;
+  /** Bytes originales, para saber cuánto se ahorró. */
+  originalBytes: number;
+  /** true si hubo que tocarla; false si ya era chica. */
+  changed: boolean;
+}
+
+/**
+ * Deja una imagen entrante en un tamaño razonable para mandársela a un modelo.
+ *
+ * Una foto de teléfono son varios megabytes y unos cuantos miles de tokens; a
+ * 1024 px el modelo ve lo mismo por una fracción del costo. Si ya está por
+ * debajo del límite no se toca — recomprimir una imagen chica sólo la empeora.
+ */
+export async function normalizeForModel(
+  input: Uint8Array | ArrayBuffer | Buffer | string,
+  opts: NormalizeOptions = {},
+): Promise<NormalizeResult> {
+  const cfg = { ...NORMALIZE_DEFAULTS, ...opts };
+  const bytes = toBytes(input);
+  const meta = await measureImage(bytes);
+  const mayor = Math.max(meta.width, meta.height);
+
+  if (mayor <= cfg.maxDimension && meta.format === cfg.format) {
+    return { bytes, metadata: meta, originalBytes: bytes.length, changed: false };
+  }
+
+  const escala = mayor > cfg.maxDimension ? cfg.maxDimension / mayor : 1;
+  const { bytes: salida, metadata } = await transformImage(bytes, {
+    width: Math.round(meta.width * escala),
+    height: Math.round(meta.height * escala),
+    format: cfg.format,
+    quality: cfg.quality,
+  });
+
+  log.info(
+    `imagen normalizada: ${meta.width}x${meta.height} ${meta.format} (${bytes.length}b) → ` +
+    `${metadata.width}x${metadata.height} ${metadata.format} (${salida.length}b)`,
+  );
+  return { bytes: salida, metadata, originalBytes: bytes.length, changed: true };
+}
+
+/** true si este runtime puede procesar imágenes. */
+export function imagesSupported(): boolean {
+  return typeof (Bun as any).Image === "function";
+}

package/packages/core/src/index.ts

@@ -22,6 +22,7 @@ export type { Skill, SkillStep, OutputFormat, SkillsConfig } from "./skills/inde
 export { runAgent, runAgentIsolated, AgentLoop, getAgentLoop, buildAgentLoop, rebuildAgentLoop } from "./agent/agent-loop.ts";
 export type { AgentLoopOptions, StepEvent, StreamChunk } from "./agent/agent-loop.ts";
 export type { Provider } from "./agent/providers/index.ts";
+export { AgentRunner, createAgentRunner } from "./agent/providers/index.ts";
 
 // El cliente LLM es parte de la superficie pública: hasta 0.1.5 sólo se exportaba
 // el wrapper `AgentRunner`, así que no había forma de llamar a un provider ni de

package/packages/core/src/mcp/MCPClient.ts

@@ -1,12 +1,12 @@
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
-import type { MCPConfig, MCPServerConfig } from "./config";
-import { logger, type LogHandler } from "./logger";
+import type { MCPConfig, MCPServerConfig } from "./config.ts";
+import { logger, type LogHandler } from "./logger.ts";
 import * as path from "node:path";
 import {
   createTransport,
   type TransportType,
-} from "./transports/index";
+} from "./transports/index.ts";
 
 export interface MCPTool {
   name: string;

package/packages/core/src/mcp/hot-reload.ts

@@ -8,11 +8,11 @@
  * - MCP tools are loaded at runtime from connected servers (not stored in DB)
  */
 
-import { col, updateDoc } from "../storage/hive";
-import type { McpServerDoc } from "../storage/collections";
-import { logger } from "../utils/logger";
-import { loadMcpHeaders } from "../storage/crypto";
-import { syncMCPToolsToDB, syncMCPToolsToIndex, clearMCPToolsFromDB } from "./tool-sync";
+import { col, updateDoc } from "../storage/hive.ts";
+import type { McpServerDoc } from "../storage/collections.ts";
+import { logger } from "../utils/logger.ts";
+import { loadMcpHeaders } from "../storage/crypto.ts";
+import { syncMCPToolsToDB, syncMCPToolsToIndex, clearMCPToolsFromDB } from "./tool-sync.ts";
 import type { MCPClientManager } from "./MCPClient.ts";
 
 const log = logger.child("mcp:hot-reload");

package/packages/core/src/mcp/tool-sync.ts

@@ -13,15 +13,15 @@
  * 3. Offline visibility of what MCP tools were available
  */
 
-import { col } from "../storage/hive"
-import type { McpToolDoc } from "../storage/collections"
-import { logger } from "../utils/logger"
-import { mcpToolFullName } from "../agent/tool-selector"
+import { col } from "../storage/hive.ts"
+import type { McpToolDoc } from "../storage/collections.ts"
+import { logger } from "../utils/logger.ts"
+import { mcpToolFullName } from "../agent/tool-selector.ts"
 import {
     replaceCapabilityDocs,
     deleteCapabilitiesByServer,
     type CapabilityDoc,
-} from "../agent/capability-search"
+} from "../agent/capability-search.ts"
 
 const log = logger.child("mcp:tool-sync")
 

package/packages/core/src/mcp/transports/index.ts

@@ -4,8 +4,8 @@ import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 // CORRECCIÓN 1 — quitar extensión .ts de los imports
 // Bun resuelve los módulos sin extensión correctamente
 // Con .ts puede fallar en algunos contextos de build/bundle
-import { SSETransport, type SSETransportConfig } from "./sse";
-import { WebSocketTransport, type WebSocketTransportConfig } from "./websocket";
+import { SSETransport, type SSETransportConfig } from "./sse.ts";
+import { WebSocketTransport, type WebSocketTransportConfig } from "./websocket.ts";
 
 export { SSETransport, type SSETransportConfig };
 export { WebSocketTransport, type WebSocketTransportConfig };

package/packages/core/src/mcp/transports/sse.ts

@@ -1,5 +1,5 @@
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
-import { logger } from "../logger";
+import { logger } from "../logger.ts";
 
 export interface SSETransportConfig {
   url: string;                        // URL base

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

@@ -0,0 +1,36 @@
+/**
+ * Models — el catálogo de proveedores y modelos con el que arranca una colmena.
+ *
+ * El "seed de modelos" ya existía, pero repartido en `storage/`: los datos en
+ * `seed.ts`, las claves en `model-id.ts`, el precio en `usage.ts`. Quien quería
+ * consumirlo tenía que saber que un catálogo de modelos vive bajo "storage".
+ * Esto le da nombre y un punto de entrada; no mueve la implementación ni
+ * duplica nada.
+ *
+ * `SEED_DATA` es la fuente de verdad del catálogo (18 proveedores, ~110 modelos)
+ * y `seedAllData()` la aplica de forma idempotente en cada arranque — la llama
+ * `ensureHiveDb()`, así que normalmente no hace falta invocarla a mano.
+ *
+ * Nota de precios: cada modelo LLM declara `inputPer1M`/`outputPer1M`. Un modelo
+ * sin ellos no es "gratis", es un modelo cuyo costo no se puede calcular.
+ */
+
+// ─── Catálogo ────────────────────────────────────────────────────────────────
+export { SEED_DATA, seedAllData, seedToolsAndSkills } from "../storage/seed.ts";
+export type { SeedData } from "../storage/seed.ts";
+export { activateElement, deactivateElement, getAllElements, getActiveElements } from "../storage/seed.ts";
+
+// ─── Identidad de modelo ─────────────────────────────────────────────────────
+/**
+ * Los revendedores (openrouter, nvidia, groq, opencode-go, modelscope) sirven
+ * modelos de terceros bajo su propio endpoint, así que el id del wire colisiona
+ * entre proveedores. `catalogModelKey` prefija; `wireModelId` deshace el prefijo
+ * antes de salir a la API.
+ */
+export { catalogModelKey, wireModelId, isResellerProvider } from "../storage/model-id.ts";
+
+// ─── Costos ──────────────────────────────────────────────────────────────────
+export { calculateCost, invalidateModelPricingCache } from "../storage/usage.ts";
+
+// ─── Shapes ──────────────────────────────────────────────────────────────────
+export type { ModelDoc, ProviderDoc } from "../storage/collections.ts";

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

@@ -1,2 +1,2 @@
-export type { ContentPart, ImageInput, DocumentInput, VisionConfig, MultimodalMessageType } from "./types"
-export { multimodalService } from "./vision-service"
+export type { ContentPart, ImageInput, DocumentInput, VisionConfig, MultimodalMessageType } from "./types.ts"
+export { multimodalService } from "./vision-service.ts"

package/packages/core/src/multimodal/vision-service.ts

@@ -1,9 +1,9 @@
-import { col } from "../storage/hive"
-import type { ChannelDoc, ModelDoc, ProviderDoc } from "../storage/collections"
-import { loadProviderApiKey } from "../storage/crypto"
-import { logger } from "../utils/logger"
-import type { ImageInput, DocumentInput, VisionConfig } from "./types"
-import type { ContentPart } from "./types"
+import { col } from "../storage/hive.ts"
+import type { ChannelDoc, ModelDoc, ProviderDoc } from "../storage/collections.ts"
+import { loadProviderApiKey } from "../storage/crypto.ts"
+import { logger } from "../utils/logger.ts"
+import type { ImageInput, DocumentInput, VisionConfig } from "./types.ts"
+import type { ContentPart } from "./types.ts"
 
 const log = logger.child("multimodal")
 
@@ -35,6 +35,19 @@ class MultimodalService {
     }
   }
 
+  /**
+   * Convierte una imagen entrante en las partes que ve el modelo.
+   *
+   * Antes de mandarla la **normaliza**: una foto de teléfono son varios
+   * megabytes y unos cuantos miles de tokens, y a 1024 px el modelo ve lo mismo
+   * por una fracción del costo. Esa imagen no viaja una sola vez — queda en el
+   * historial y se reenvía en cada turno siguiente, así que el ahorro se
+   * multiplica por la longitud de la conversación.
+   *
+   * Es best-effort: si el runtime no puede procesarla (Bun < 1.4) o la imagen
+   * está corrupta, se manda tal cual. Perder la imagen sería peor que mandarla
+   * grande.
+   */
   async processImage(image: ImageInput, visionModelId?: string): Promise<ContentPart[]> {
     const parts: ContentPart[] = []
 
@@ -43,25 +56,44 @@ class MultimodalService {
     }
 
     if (image.type === "url") {
+      // Una URL no ocupa contexto: la descarga la hace el proveedor.
       parts.push({ type: "image_url", image_url: { url: image.data as string } })
-    } else if (image.type === "base64") {
-      parts.push({
-        type: "image_base64",
-        base64: image.data as string,
-        mimeType: image.mimeType || "image/jpeg",
-      })
-    } else if (image.type === "buffer") {
-      const base64 = Buffer.from(image.data as Buffer).toString("base64")
-      parts.push({
-        type: "image_base64",
-        base64,
-        mimeType: image.mimeType || "image/jpeg",
-      })
+      return parts
     }
 
+    const crudo = image.type === "base64"
+      ? (image.data as string)
+      : Buffer.from(image.data as Buffer).toString("base64")
+
+    const { base64, mimeType } = await this.normalizeIncoming(crudo, image.mimeType)
+    parts.push({ type: "image_base64", base64, mimeType })
+
     return parts
   }
 
+  /** Achica la imagen para el modelo; ante cualquier problema devuelve la original. */
+  private async normalizeIncoming(
+    base64: string,
+    mimeType?: string,
+  ): Promise<{ base64: string; mimeType: string }> {
+    const original = { base64, mimeType: mimeType || "image/jpeg" }
+    try {
+      const { imagesSupported, normalizeForModel } = await import("../images/index.ts")
+      if (!imagesSupported()) return original
+
+      const r = await normalizeForModel(base64)
+      if (!r.changed) return original
+
+      return {
+        base64: Buffer.from(r.bytes).toString("base64"),
+        mimeType: `image/${r.metadata.format}`,
+      }
+    } catch (err) {
+      log.warn(`no pude normalizar la imagen entrante, va sin achicar: ${(err as Error).message}`)
+      return original
+    }
+  }
+
   async ocrImage(image: ImageInput, providerId?: string): Promise<string> {
     const resolved = providerId || "openai"
 

package/packages/core/src/plugins/loader.ts

@@ -30,7 +30,10 @@ export class PluginLoader {
   private commands: Map<string, CLICommand> = new Map();
   private log = logger.child("plugins");
 
-  constructor(private options: PluginLoaderOptions) {
+  private options: PluginLoaderOptions;
+
+  constructor(options: PluginLoaderOptions) {
+    this.options = options;
     if (!existsSync(options.pluginDir)) {
       mkdirSync(options.pluginDir, { recursive: true });
     }

package/packages/core/src/resilience/circuit-breaker.ts

@@ -39,10 +39,16 @@ export class CircuitBreaker {
   private totalFailures = 0;
   private totalSuccesses = 0;
 
+  private readonly name: string;
+  private readonly options: CircuitBreakerOptions;
+
   constructor(
-    private readonly name: string,
-    private readonly options: CircuitBreakerOptions = defaultOptions
-  ) { }
+    name: string,
+    options: CircuitBreakerOptions = defaultOptions
+  ) {
+    this.name = name;
+    this.options = options;
+  }
 
   async execute<T>(fn: () => Promise<T>): Promise<T> {
     if (this.state === "open") {
@@ -175,12 +181,17 @@ export class CircuitBreaker {
 }
 
 export class CircuitBreakerOpenError extends Error {
+  public readonly circuitName: string;
+  public readonly retryAfterMs: number;
+
   constructor(
     message: string,
-    public readonly circuitName: string,
-    public readonly retryAfterMs: number
+    circuitName: string,
+    retryAfterMs: number
   ) {
     super(message);
+    this.circuitName = circuitName;
+    this.retryAfterMs = retryAfterMs;
     this.name = "CircuitBreakerOpenError";
   }
 }

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

@@ -0,0 +1,13 @@
+/**
+ * Resilience — reintentos y circuit breakers.
+ *
+ * `withRetry` aplica backoff exponencial con jitter y respeta `Retry-After`
+ * cuando el proveedor lo manda; `isRetryableError` decide qué merece otro
+ * intento (429/5xx/timeout/red) y qué no (un 400 no mejora reintentando).
+ *
+ * El `CircuitBreaker` corta las llamadas a un servicio que ya viene fallando,
+ * en vez de seguir gastando intentos contra algo caído.
+ */
+
+export * from "./retry.ts";
+export * from "./circuit-breaker.ts";

package/packages/core/src/resilience/retry.ts

@@ -5,7 +5,7 @@
  * only decides whether a single call should be retried and how long to wait.
  */
 
-import { logger } from "../utils/logger";
+import { logger } from "../utils/logger.ts";
 
 const log = logger.child("retry");