@johpaz/hive-sdk 0.1.6 → 0.2.0

package/packages/core/src/tools/web/artifact-inspect.ts

@@ -1,5 +1,5 @@
-import type { Tool } from "../types";
-import { inspectArtifact } from "../../artifacts/store";
+import type { Tool } from "../types.ts";
+import { inspectArtifact } from "../../artifacts/store.ts";
 
 export const artifactInspectTool: Tool = {
   name: "artifact_inspect",

package/packages/core/src/tools/web/artifact-read.ts

@@ -0,0 +1,162 @@
+/**
+ * artifact_read — reads back the content an artifact_ref points at.
+ *
+ * mcp-result-normalizer.ts keeps oversized MCP text results out of the context
+ * window: the model gets `{ type: "artifact_ref", artifact_id, size, preview }`
+ * with a blind 500-char preview. That is the right call for the context, but
+ * without a way to read the artifact back it left the agent stuck — it would
+ * call artifact_inspect (metadata only), find no content, and burn its
+ * iterations until the turn died on an empty synthesis. This is the way back in.
+ *
+ * Slicing is by characters, not lines: the case this was built for is a single
+ * 245 KB JSON line from a Gmail MCP server, where line-based paging returns
+ * everything or nothing. `search` exists for the same reason — jumping straight
+ * to the three relevant messages beats paging through 245 KB in 20 KB chunks.
+ */
+
+import type { Tool } from "../types.ts";
+import { readArtifactText } from "../../artifacts/store.ts";
+
+const DEFAULT_LIMIT = 20_000;
+const MAX_LIMIT = 50_000;
+const MAX_MATCHES = 10;
+const DEFAULT_MATCH_CONTEXT = 600;
+const MAX_MATCH_CONTEXT = 8_000;
+/**
+ * What a search may return in total. Capping the per-match window alone would
+ * be the wrong knob: a record whose fields are 2 KB of mail headers needs a
+ * wide window to show its id, while ten such windows would put back into the
+ * context exactly what the artifact was created to keep out.
+ */
+const MAX_SEARCH_CHARS = 40_000;
+
+function clampNumber(value: unknown, fallback: number, min: number, max: number): number {
+  const parsed = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.min(max, Math.max(min, Math.floor(parsed)));
+}
+
+function findMatches(text: string, query: string, context: number): Array<{ offset: number; excerpt: string }> {
+  const haystack = text.toLowerCase();
+  const needle = query.toLowerCase();
+  const matches: Array<{ offset: number; excerpt: string }> = [];
+  const half = Math.floor(context / 2);
+  let from = 0;
+
+  let used = 0;
+
+  while (matches.length < MAX_MATCHES) {
+    const at = haystack.indexOf(needle, from);
+    if (at === -1) break;
+    const start = Math.max(0, at - half);
+    const end = Math.min(text.length, at + needle.length + half);
+    const excerpt = text.slice(start, end);
+    // The first match always comes back, however wide it is — returning zero
+    // results for a query that did match would be the worst possible answer.
+    if (matches.length > 0 && used + excerpt.length > MAX_SEARCH_CHARS) break;
+    matches.push({ offset: at, excerpt });
+    used += excerpt.length;
+    from = at + needle.length;
+  }
+
+  return matches;
+}
+
+function countMatches(text: string, query: string): number {
+  const haystack = text.toLowerCase();
+  const needle = query.toLowerCase();
+  let total = 0;
+  let from = 0;
+  for (;;) {
+    const at = haystack.indexOf(needle, from);
+    if (at === -1) return total;
+    total++;
+    from = at + needle.length;
+  }
+}
+
+export const artifactReadTool: Tool = {
+  name: "artifact_read",
+  description:
+    "Read the text content of a managed artifact in slices, or search inside it. Use this on any artifact_ref a tool returned instead of guessing from its preview. Spanish: leer artefacto, ver contenido del artefacto, abrir resultado grande, buscar dentro del artefacto",
+  parameters: {
+    type: "object",
+    properties: {
+      artifactId: {
+        type: "string",
+        description: "Managed artifact identifier (the artifact_id of an artifact_ref).",
+      },
+      offset: {
+        type: "number",
+        description: "Character position to start reading from (default: 0). Use next_offset from the previous call to continue.",
+      },
+      limit: {
+        type: "number",
+        description: `Characters to return (default: ${DEFAULT_LIMIT}, max: ${MAX_LIMIT}).`,
+      },
+      search: {
+        type: "string",
+        description: "Return excerpts around each case-insensitive match instead of a contiguous slice. Far cheaper than paging a large artifact.",
+      },
+      context: {
+        type: "number",
+        description: `Characters of surrounding text per match (default: ${DEFAULT_MATCH_CONTEXT}, max: ${MAX_MATCH_CONTEXT}). Widen it when records carry long fields and the excerpt cuts off the data you need.`,
+      },
+    },
+    required: ["artifactId"],
+  },
+  execute: async (params, config) => {
+    const artifactId = String(params.artifactId ?? "").trim();
+    if (!artifactId) return { ok: false, error: "artifactId is required" };
+
+    const userId = config?.configurable?.user_id as string | undefined;
+    const result = await readArtifactText(artifactId, { userId });
+    if (!result.ok || !result.artifact) {
+      return { ok: false, artifact_id: artifactId, error: result.error, status: result.status };
+    }
+
+    const artifact = result.artifact;
+    const text = result.text ?? "";
+    const search = typeof params.search === "string" ? params.search.trim() : "";
+
+    if (search) {
+      const context = clampNumber(params.context, DEFAULT_MATCH_CONTEXT, 40, MAX_MATCH_CONTEXT);
+      const matches = findMatches(text, search, context);
+      // Always the real count, never the number returned: collection stops at
+      // MAX_MATCHES or at the character budget, and an agent told "4 matches"
+      // when there are 8 stops looking.
+      const total = countMatches(text, search);
+      return {
+        ok: true,
+        artifact_id: artifact.id,
+        mime_type: artifact.mime_type,
+        total_chars: text.length,
+        query: search,
+        total_matches: total,
+        returned_matches: matches.length,
+        truncated: total > matches.length,
+        context,
+        matches,
+      };
+    }
+
+    const offset = clampNumber(params.offset, 0, 0, Math.max(0, text.length));
+    const limit = clampNumber(params.limit, DEFAULT_LIMIT, 1, MAX_LIMIT);
+    const content = text.slice(offset, offset + limit);
+    const nextOffset = offset + content.length;
+    const eof = nextOffset >= text.length;
+
+    return {
+      ok: true,
+      artifact_id: artifact.id,
+      mime_type: artifact.mime_type,
+      kind: artifact.kind,
+      total_chars: text.length,
+      offset,
+      returned_chars: content.length,
+      next_offset: eof ? null : nextOffset,
+      eof,
+      content,
+    };
+  },
+};

package/packages/core/src/tools/web/browser-backend.ts

@@ -1,23 +1,28 @@
 /**
  * BrowserBackend — el contrato que consumen las browser tools.
  *
- * Hay dos implementaciones con perfiles opuestos:
+ * Hay una sola implementación: `WebViewBackend` (webview-backend.ts), sobre
+ * `Bun.WebView`. In-process, sin instalación y sin subprocesos: ~0,3 ms un
+ * `evaluate`, ~2 ms un `snapshot`. Con motor chrome corre headless de verdad
+ * —Bun lanza el navegador con `--headless`—, así que sirve en un servidor sin
+ * display; lo único que necesita es un navegador Chromium instalado (o
+ * `BUN_CHROME_PATH`).
  *
- *  - `AgentBrowserBackend` (browser-service.ts): habla con el CLI de
- *    agent-browser por subproceso. Maneja Chrome de verdad, corre headless y
- *    por lo tanto sirve en Docker y en un servidor sin display. El costo es
- *    un `Bun.spawn` por operación —medido en ~68 ms de piso— más una
- *    instalación diferida de ~75 MB y la descarga de Chrome.
+ * El contrato sigue existiendo aunque el backend sea uno solo: es lo que hace
+ * que las tools no dependan del motor, y lo que deja al motor WebKit de macOS
+ * —que no tiene CDP— entrar por la misma puerta con menos capacidades.
  *
- *  - `WebViewBackend` (webview-backend.ts): usa `Bun.WebView`, in-process.
- *    Sin instalación, sin subprocesos, ~0.25 ms por `evaluate`. Necesita un
- *    entorno gráfico (WebKitGTK en Linux, WebKit del sistema en macOS), así
- *    que no sirve headless.
- *
- * El default sigue siendo agent-browser: es el único de los dos que funciona
- * donde suele correr el gateway. WebView se elige explícitamente.
+ * Dos cosas que hay que saber del WebView y que están resueltas adentro: el
+ * perfil de Chrome que abre Bun es efímero (`/tmp/.<hash>.bun-chrome`, y el
+ * hash cambia entre procesos), por eso las cookies se guardan y restauran a
+ * mano desde `browser-session.ts`; y como root sin `--no-sandbox` Chromium no
+ * arranca, por eso el Dockerfile apunta `BUN_CHROME_PATH` a un wrapper.
  */
 
+import { logger } from "../../utils/logger.ts";
+
+const log = logger.child("browser-backend");
+
 export interface ScreenshotOptions {
   encoding?: "blob" | "buffer" | "base64" | "shmem";
   format?: "png" | "jpeg" | "webp";
@@ -62,55 +67,126 @@ export interface BrowserBackend {
   resize(width: number, height: number): Promise<void>;
   /** Captura de un elemento puntual; el backend puede recortar sobre el viewport. */
   screenshotElement(selector: string): Promise<string>;
+  /**
+   * Puente CDP crudo. Opcional a propósito: lo tienen los backends con Chrome,
+   * no el motor WebKit de macOS. Quien lo use tiene que traer una alternativa.
+   */
+  cdp?<T = unknown>(method: string, params?: Record<string, unknown>): Promise<T>;
   close(): void;
 }
 
-export type BrowserBackendKind = "agent-browser" | "webview";
+/** Ya no hay más de uno; el tipo se conserva porque lo reportan doctor y el gateway. */
+export type BrowserBackendKind = "webview";
 
-/** `auto` resuelve a webview si el runtime lo soporta; si no, agent-browser. */
-export type BrowserBackendPreference = BrowserBackendKind | "auto";
+/**
+ * Lo que se puede pedir por config. `"agent-browser"` era el backend por CLI que
+ * se retiró: se sigue aceptando para no romper un `hive.json` viejo, pero avisa
+ * y usa el WebView.
+ */
+export type BrowserBackendPreference = BrowserBackendKind | "auto" | "agent-browser";
 
 /** Motor que usa `Bun.WebView` por debajo. */
 export type WebViewEngine = "webkit" | "chrome";
 
-const CHROME_PATHS = [
-  "/usr/bin/google-chrome",
-  "/usr/bin/google-chrome-stable",
-  "/usr/bin/chromium",
-  "/usr/bin/chromium-browser",
-  "/snap/bin/chromium",
-  "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
-  "/Applications/Chromium.app/Contents/MacOS/Chromium",
-  "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
-  "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe",
+/**
+ * Binarios que valen: cualquier Chromium sirve, porque lo que Bun necesita es
+ * `--remote-debugging-pipe`, que todos implementan. Edge y Brave son los que más
+ * aparecen en máquinas donde no hay Chrome "de marca".
+ */
+const CHROME_BINARIES = [
+  "google-chrome",
+  "google-chrome-stable",
+  "chromium",
+  "chromium-browser",
+  "brave-browser",
+  "microsoft-edge",
+  "microsoft-edge-stable",
+  "vivaldi",
+  "vivaldi-stable",
+  "opera",
 ];
 
-/** Chrome instalado en el sistema — `Bun.WebView` con motor chrome lo necesita. */
+/** Rutas conocidas por plataforma, en orden de preferencia. */
+function chromePathsForPlatform(): string[] {
+  const home = process.env.HOME ?? "";
+
+  if (process.platform === "darwin") {
+    return [
+      "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+      "/Applications/Chromium.app/Contents/MacOS/Chromium",
+      "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
+      "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+      "/Applications/Vivaldi.app/Contents/MacOS/Vivaldi",
+      `${home}/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`,
+    ];
+  }
+
+  if (process.platform === "win32") {
+    const programFiles = process.env["ProgramFiles"] ?? "C:\\Program Files";
+    const programFilesX86 = process.env["ProgramFiles(x86)"] ?? "C:\\Program Files (x86)";
+    const localAppData = process.env.LOCALAPPDATA ?? "";
+    return [
+      `${programFiles}\\Google\\Chrome\\Application\\chrome.exe`,
+      `${programFilesX86}\\Google\\Chrome\\Application\\chrome.exe`,
+      `${localAppData}\\Google\\Chrome\\Application\\chrome.exe`,
+      `${programFilesX86}\\Microsoft\\Edge\\Application\\msedge.exe`,
+      `${programFiles}\\Microsoft\\Edge\\Application\\msedge.exe`,
+      `${programFiles}\\BraveSoftware\\Brave-Browser\\Application\\brave.exe`,
+    ];
+  }
+
+  // Linux: paquetes del sistema, snap y los wrappers que exporta flatpak —que
+  // en la práctica son el único Chrome de muchas máquinas.
+  const flatpakDirs = ["/var/lib/flatpak/exports/bin", `${home}/.local/share/flatpak/exports/bin`];
+  const flatpakApps = ["com.google.Chrome", "org.chromium.Chromium", "com.brave.Browser", "com.microsoft.Edge"];
+  return [
+    "/usr/bin/google-chrome",
+    "/usr/bin/google-chrome-stable",
+    "/usr/bin/chromium",
+    "/usr/bin/chromium-browser",
+    "/usr/bin/brave-browser",
+    "/usr/bin/microsoft-edge",
+    "/usr/bin/microsoft-edge-stable",
+    "/usr/bin/vivaldi",
+    "/usr/bin/opera",
+    "/snap/bin/chromium",
+    "/snap/bin/brave",
+    ...flatpakDirs.flatMap((dir) => flatpakApps.map((app) => `${dir}/${app}`)),
+  ];
+}
+
+/** Navegador instalado — `Bun.WebView` con motor chrome lo necesita. */
 export function findChrome(): string | null {
   if (process.env.BUN_CHROME_PATH) return process.env.BUN_CHROME_PATH;
+
   const { existsSync } = require("node:fs") as typeof import("node:fs");
-  for (const candidate of CHROME_PATHS) {
-    if (existsSync(candidate)) return candidate;
+  for (const candidate of chromePathsForPlatform()) {
+    if (candidate && existsSync(candidate)) return candidate;
   }
-  // Último recurso: lo que esté en el PATH del usuario.
-  const home = process.env.HOME;
-  if (home) {
-    for (const name of ["google-chrome", "chromium"]) {
-      const local = `${home}/.local/bin/${name}`;
-      if (existsSync(local)) return local;
+
+  // Último recurso: lo que haya en el PATH, que cubre instalaciones a mano y
+  // los wrappers que el usuario tenga en ~/.local/bin.
+  const which = (globalThis as { Bun?: { which?: (cmd: string) => string | null } }).Bun?.which;
+  if (which) {
+    for (const name of CHROME_BINARIES) {
+      const found = which(name);
+      if (found) return found;
     }
   }
   return null;
 }
 
 /**
- * Motor a usar. WebKit no tiene dependencias externas pero sólo existe en macOS;
- * Chrome corre headless en cualquier lado —incluido Docker— siempre que el
- * binario esté instalado.
+ * Motor a usar.
+ *
+ * Chrome primero **también en macOS**: es el único que trae CDP, y de CDP
+ * dependen el árbol de accesibilidad del snapshot, la sesión persistente y los
+ * clics reales de `computer_use_task`. WebKit queda como respaldo para un mac
+ * sin ningún Chromium instalado: no necesita nada, pero da menos.
  */
 export function resolveWebViewEngine(): WebViewEngine | null {
-  if (process.platform === "darwin") return "webkit";
-  return findChrome() ? "chrome" : null;
+  if (findChrome()) return "chrome";
+  return process.platform === "darwin" ? "webkit" : null;
 }
 
 /** `Bun.WebView` existe desde Bun 1.3; además hace falta un motor utilizable. */
@@ -119,11 +195,32 @@ export function isWebViewSupported(): boolean {
   return resolveWebViewEngine() !== null;
 }
 
+/**
+ * Qué decirle a alguien que no tiene navegador. Lo usan el arranque del gateway
+ * y `hive doctor`, para que el mensaje sea el mismo en los dos lados.
+ */
+export function browserInstallHint(): string {
+  if (process.platform === "darwin") {
+    return "Instala Google Chrome (brew install --cask google-chrome) o define BUN_CHROME_PATH.";
+  }
+  if (process.platform === "win32") {
+    return "Instala Google Chrome o Microsoft Edge, o define BUN_CHROME_PATH.";
+  }
+  return "Instala Chromium o Chrome (apt install chromium · dnf install chromium) o define BUN_CHROME_PATH.";
+}
+
+let avisoBackendRetirado = false;
+
 export function resolveBackendKind(
   preference: BrowserBackendPreference | undefined,
 ): BrowserBackendKind {
-  const wanted = process.env.HIVE_BROWSER_BACKEND ?? preference ?? "agent-browser";
-  if (wanted === "webview") return "webview";
-  if (wanted === "auto") return isWebViewSupported() ? "webview" : "agent-browser";
-  return "agent-browser";
+  const wanted = process.env.HIVE_BROWSER_BACKEND ?? preference;
+  if (wanted === "agent-browser" && !avisoBackendRetirado) {
+    avisoBackendRetirado = true;
+    log.warn(
+      'tools.browser.backend: "agent-browser" ya no existe — se usa Bun.WebView. ' +
+        "Puedes quitar esa clave de la config.",
+    );
+  }
+  return "webview";
 }

package/packages/core/src/tools/web/browser-click.ts

@@ -43,7 +43,7 @@ export const browserClickTool: Tool = {
       log.warn("Browser not available");
       return {
         ok: false,
-        error: "Browser automation not available. Install agent-browser.",
+        error: "Browser automation not available. Install Chrome or Chromium (or run `hive doctor`).",
       };
     }
 
@@ -51,7 +51,7 @@ export const browserClickTool: Tool = {
 
     try {
       const view = await browserService.getView();
-      if (!view) return { ok: false, error: "Browser automation not available. Install agent-browser." };
+      if (!view) return { ok: false, error: "Browser automation not available. Install Chrome or Chromium (or run `hive doctor`)." };
 
       if (url) {
         await view.navigate(url);

package/packages/core/src/tools/web/browser-extract.ts

@@ -53,7 +53,7 @@ export const browserExtractTool: Tool = {
       log.warn("Browser not available");
       return {
         ok: false,
-        error: "Browser automation not available. Install agent-browser.",
+        error: "Browser automation not available. Install Chrome or Chromium (or run `hive doctor`).",
       };
     }
 
@@ -61,7 +61,7 @@ export const browserExtractTool: Tool = {
 
     try {
       const view = await browserService.getView();
-      if (!view) return { ok: false, error: "Browser automation not available. Install agent-browser." };
+      if (!view) return { ok: false, error: "Browser automation not available. Install Chrome or Chromium (or run `hive doctor`)." };
 
       if (url) {
         await view.navigate(url);

package/packages/core/src/tools/web/browser-navigate.ts

@@ -49,7 +49,7 @@ export const browserNavigateTool: Tool = {
       log.warn("Browser not available");
       return {
         ok: false,
-        error: "Browser automation not available. Install agent-browser.",
+        error: "Browser automation not available. Install Chrome or Chromium (or run `hive doctor`).",
       };
     }
 
@@ -57,7 +57,7 @@ export const browserNavigateTool: Tool = {
 
     try {
       const view = await browserService.getView();
-      if (!view) return { ok: false, error: "Browser automation not available. Install agent-browser." };
+      if (!view) return { ok: false, error: "Browser automation not available. Install Chrome or Chromium (or run `hive doctor`)." };
 
       await view.navigate(url);
 

package/packages/core/src/tools/web/browser-screenshot.ts

@@ -68,7 +68,7 @@ export const browserScreenshotTool: Tool = {
       log.warn("Browser not available");
       return {
         ok: false,
-        error: "Browser automation not available. Install agent-browser.",
+        error: "Browser automation not available. Install Chrome or Chromium (or run `hive doctor`).",
       };
     }
 
@@ -76,16 +76,23 @@ export const browserScreenshotTool: Tool = {
 
     try {
       const view = await browserService.getView();
-      if (!view) return { ok: false, error: "Browser automation not available. Install agent-browser." };
+      if (!view) return { ok: false, error: "Browser automation not available. Install Chrome or Chromium (or run `hive doctor`)." };
 
       if (url) {
         await view.navigate(url);
         await Bun.sleep(500);
       }
 
-      // Resize viewport before screenshot to keep image small
-      await view.resize(width, height);
-      await Bun.sleep(200);
+      // Fijar el viewport es un intento, no un requisito: `Emulation.setDevice
+      // MetricsOverride` no existe en todos los motores —y falla si todavía no
+      // se navegó a ninguna página—. Sin esto, un resize que no se puede hacer
+      // tiraba abajo la captura entera.
+      try {
+        await view.resize(width, height);
+        await Bun.sleep(200);
+      } catch (error) {
+        log.info(`el motor no permite fijar el viewport: ${(error as Error).message}`);
+      }
 
       let screenshot: string;
 

package/packages/core/src/tools/web/browser-script.ts

@@ -43,7 +43,7 @@ export const browserScriptTool: Tool = {
       log.warn("Browser not available");
       return {
         ok: false,
-        error: "Browser automation not available. Install agent-browser.",
+        error: "Browser automation not available. Install Chrome or Chromium (or run `hive doctor`).",
       };
     }
 
@@ -51,7 +51,7 @@ export const browserScriptTool: Tool = {
 
     try {
       const view = await browserService.getView();
-      if (!view) return { ok: false, error: "Browser automation not available. Install agent-browser." };
+      if (!view) return { ok: false, error: "Browser automation not available. Install Chrome or Chromium (or run `hive doctor`)." };
 
       if (url) {
         await view.navigate(url);