@johpaz/hive-sdk 0.2.0 → 0.3.0

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

@@ -0,0 +1,130 @@
+/**
+ * Tools de imagen — redimensionar, convertir y medir.
+ *
+ * Se apoyan en `Bun.Image` (ver `images/`), así que no agregan dependencias: el
+ * SDK ya exige Bun ≥ 1.4.
+ *
+ * Trabajan sobre **artefactos**, no sobre base64 suelto, y eso es deliberado.
+ * Devolver una imagen en base64 al modelo es exactamente lo que llena la
+ * ventana de contexto —el problema que `mcp-result-normalizer.ts` existe para
+ * evitar—. Acá la entrada es un `artifact_id` y la salida es otro: el modelo
+ * maneja referencias y sólo mira la imagen si de verdad la necesita.
+ *
+ * Como cualquier otra tool, se activan o desactivan desde el catálogo.
+ */
+
+import type { Tool } from "../types.ts";
+import { createArtifact, readArtifactBytes } from "../../artifacts/store.ts";
+import { measureImage, transformImage, imagesSupported, type ImageFormat } from "../../images/index.ts";
+import { resolveUserId } from "../../storage/onboarding.ts";
+import { logger } from "../../utils/logger.ts";
+
+const log = logger.child("tools/images");
+
+const FORMATOS: ImageFormat[] = ["jpeg", "png", "webp", "avif", "heic"];
+
+/** Mensaje común: sin Bun 1.4 estas tools no pueden hacer nada. */
+function sinSoporte() {
+  return { ok: false, error: "El procesamiento de imágenes necesita Bun >= 1.4 (Bun.Image no está disponible)" };
+}
+
+async function leerArtefacto(artifactId: string) {
+  const datos = await readArtifactBytes(artifactId);
+  if (!datos) return null;
+  return datos;
+}
+
+export const imageMetadataTool: Tool = {
+  name: "image_metadata",
+  description:
+    "Lee las dimensiones y el formato de una imagen guardada, sin abrirla ni cargarla al contexto. " +
+    "Spanish: medir imagen, dimensiones de la imagen, tamaño de la foto, formato de imagen",
+  parameters: {
+    type: "object",
+    properties: {
+      artifact_id: { type: "string", description: "Id del artefacto que contiene la imagen" },
+    },
+    required: ["artifact_id"],
+  },
+  execute: async (params: Record<string, unknown>) => {
+    if (!imagesSupported()) return sinSoporte();
+    const id = params.artifact_id as string;
+    try {
+      const datos = await leerArtefacto(id);
+      if (!datos) return { ok: false, error: `No encontré el artefacto ${id}` };
+      const meta = await measureImage(datos.bytes);
+      return { ok: true, artifact_id: id, ...meta, bytes: datos.bytes.length };
+    } catch (error) {
+      return { ok: false, error: `No pude leer la imagen: ${(error as Error).message}` };
+    }
+  },
+};
+
+export const imageTransformTool: Tool = {
+  name: "image_transform",
+  description:
+    "Redimensiona, rota o convierte de formato una imagen guardada y devuelve un artefacto nuevo. " +
+    "El original no se toca. Spanish: redimensionar imagen, cambiar tamaño, convertir a webp, " +
+    "comprimir imagen, rotar foto, achicar imagen",
+  parameters: {
+    type: "object",
+    properties: {
+      artifact_id: { type: "string", description: "Id del artefacto de origen" },
+      width: { type: "number", description: "Ancho en píxeles. Si sólo se da uno, se mantiene la proporción" },
+      height: { type: "number", description: "Alto en píxeles" },
+      format: { type: "string", description: "Formato de salida", enum: FORMATOS },
+      quality: { type: "number", description: "1–100, sólo para formatos con pérdida", minimum: 1, maximum: 100 },
+      rotate: { type: "number", description: "Grados: 90, 180 o 270" },
+    },
+    required: ["artifact_id"],
+  },
+  execute: async (params: Record<string, unknown>) => {
+    if (!imagesSupported()) return sinSoporte();
+    const id = params.artifact_id as string;
+
+    const formato = params.format as ImageFormat | undefined;
+    if (formato && !FORMATOS.includes(formato)) {
+      return { ok: false, error: `Formato no soportado: ${formato}. Disponibles: ${FORMATOS.join(", ")}` };
+    }
+
+    try {
+      const datos = await leerArtefacto(id);
+      if (!datos) return { ok: false, error: `No encontré el artefacto ${id}` };
+
+      const { bytes, metadata } = await transformImage(datos.bytes, {
+        width: params.width as number | undefined,
+        height: params.height as number | undefined,
+        format: formato,
+        quality: params.quality as number | undefined,
+        rotate: params.rotate as number | undefined,
+      });
+
+      const userId = (await resolveUserId({}).catch(() => null)) ?? "";
+      const artefacto = await createArtifact({
+        bytes,
+        mimeType: `image/${metadata.format}`,
+        kind: "image",
+        userId,
+      });
+
+      log.info(`imagen ${id} → ${artefacto.id} (${metadata.width}x${metadata.height} ${metadata.format})`);
+      // Se devuelve la referencia, nunca los bytes: el base64 en el contexto es
+      // justo lo que se quiere evitar.
+      return {
+        ok: true,
+        artifact_id: artefacto.id,
+        width: metadata.width,
+        height: metadata.height,
+        format: metadata.format,
+        bytes: bytes.length,
+        original_bytes: datos.bytes.length,
+      };
+    } catch (error) {
+      return { ok: false, error: `No pude transformar la imagen: ${(error as Error).message}` };
+    }
+  },
+};
+
+export function createTools(): Tool[] {
+  return [imageMetadataTool, imageTransformTool];
+}

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

@@ -13,8 +13,9 @@ import * as filesystem from "./filesystem/index.ts";
 
 // Web (10)
 import * as web from "./web/index.ts";
+import * as images from "./images/index.ts";
 
-// Cron (8) - Croner-based scheduler tools
+// Cron (8) - scheduler tools
 import * as cron from "./cron/index.ts";
 
 // CLI (1)
@@ -70,6 +71,7 @@ export function createAllTools(config: Config): Tool[] {
 
     // WEB (10)
     ...web.createTools(),
+    ...images.createTools(),
 
     // CRON (8)
     ...cron.createTools(),
@@ -215,3 +217,14 @@ export {
 export {
   apiRequestTool,
 } from "./api/index.ts";
+
+// Arranque del navegador. Las browser tools existen en el catálogo desde el
+// seed, pero no operan hasta que alguien levanta el servicio: quien construya
+// sobre el SDK necesita poder hacerlo sin importar rutas internas.
+export {
+  initializeBrowserService,
+  getBrowserService,
+  shutdownBrowser,
+} from "./web/browser-service.ts";
+
+export * from "./images/index.ts";

package/packages/core/src/tools/office/office-escribir-xlsx.ts

@@ -10,6 +10,7 @@ import type { Tool } from "../types.ts";
 import { logger } from "../../utils/logger.ts";
 import * as path from "node:path";
 import * as fs from "node:fs";
+import { cargarXlsx } from "./xlsx-loader.ts";
 
 const log = logger.child("office-escribir-xlsx");
 
@@ -55,7 +56,7 @@ export const officeEscribirXlsxTool: Tool = {
     log.debug(`Generando XLSX: ${ruta}`);
 
     try {
-      const XLSX = await import("xlsx");
+      const XLSX = await cargarXlsx();
 
       const workbook = XLSX.utils.book_new();
 

package/packages/core/src/tools/office/office-leer-xlsx.ts

@@ -10,6 +10,7 @@ import type { Tool } from "../types.ts";
 import { logger } from "../../utils/logger.ts";
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { cargarXlsx } from "./xlsx-loader.ts";
 
 const log = logger.child("office-leer-xlsx");
 
@@ -55,7 +56,7 @@ export const officeLeerXlsxTool: Tool = {
         return { ok: false, error: `Archivo no encontrado: ${rutaAbsoluta}` };
       }
 
-      const XLSX = await import("xlsx");
+      const XLSX = await cargarXlsx();
       const buffer = fs.readFileSync(rutaAbsoluta);
       const workbook = XLSX.read(buffer, { type: "buffer" });
 

package/packages/core/src/tools/office/xlsx-loader.ts

@@ -0,0 +1,19 @@
+/**
+ * Carga el lector de hojas de cálculo, o explica por qué no puede.
+ *
+ * `xlsx` se importa en caliente para no pagarlo en cada arranque, y eso deja el
+ * fallo a merced del momento: si la dependencia no llegó a instalarse —su
+ * tarball se cayó una vez en mitad de un release— el usuario recibía un
+ * "Cannot find module" crudo en medio de una respuesta.
+ */
+export async function cargarXlsx(): Promise<typeof import("xlsx")> {
+  try {
+    return await import("xlsx");
+  } catch (error) {
+    throw new Error(
+      "El soporte de hojas de cálculo no está disponible en esta instalación: " +
+        `falta la dependencia «xlsx» (${(error as Error).message}). ` +
+        "Reinstala las dependencias con `bun install` para recuperarlo.",
+    );
+  }
+}