@johpaz/hive-sdk 0.1.5 → 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

@@ -0,0 +1,226 @@
+/**
+ * BrowserBackend — el contrato que consumen las browser tools.
+ *
+ * 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`).
+ *
+ * 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.
+ *
+ * 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";
+  quality?: number;
+  clip?: { x: number; y: number; width: number; height: number; scale: number };
+}
+
+export interface SnapshotOptions {
+  /** Colapsa nodos sin nombre accesible y recorta el texto largo. Default: true. */
+  compact?: boolean;
+  /** Profundidad máxima del árbol. */
+  depth?: number;
+  /** Sólo elementos accionables (links, botones, inputs...). */
+  interactiveOnly?: boolean;
+}
+
+/**
+ * La superficie que las tools de `tools/web/` realmente usan. Se mantuvo
+ * deliberadamente chica: cualquier método que se agregue acá hay que
+ * implementarlo en los dos backends.
+ */
+export interface BrowserBackend {
+  readonly url: string;
+  readonly title: string;
+  readonly loading: boolean;
+
+  navigate(url: string): Promise<void>;
+  evaluate<T = unknown>(script: string): Promise<T>;
+  screenshot(options?: ScreenshotOptions): Promise<string>;
+  /** Árbol de accesibilidad en texto — lo que ve el modelo en vez del HTML crudo. */
+  snapshot(options?: SnapshotOptions): Promise<string>;
+  click(selector: string, options?: Record<string, unknown>): Promise<void>;
+  type(text: string): Promise<void>;
+  typeIn(selector: string, text: string): Promise<void>;
+  fill(selector: string, text: string): Promise<void>;
+  press(key: string, options?: { modifiers?: string[] }): Promise<void>;
+  scroll(dx: number, dy: number): Promise<void>;
+  scrollTo(selector: string, options?: { behavior?: "smooth" | "instant" }): Promise<void>;
+  back(): Promise<void>;
+  forward(): Promise<void>;
+  reload(): Promise<void>;
+  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;
+}
+
+/** Ya no hay más de uno; el tipo se conserva porque lo reportan doctor y el gateway. */
+export type BrowserBackendKind = "webview";
+
+/**
+ * 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";
+
+/**
+ * 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",
+];
+
+/** 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 chromePathsForPlatform()) {
+    if (candidate && existsSync(candidate)) return candidate;
+  }
+
+  // Ú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.
+ *
+ * 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 (findChrome()) return "chrome";
+  return process.platform === "darwin" ? "webkit" : null;
+}
+
+/** `Bun.WebView` existe desde Bun 1.3; además hace falta un motor utilizable. */
+export function isWebViewSupported(): boolean {
+  if (typeof (globalThis as { Bun?: { WebView?: unknown } }).Bun?.WebView !== "function") return false;
+  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;
+  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);