@johpaz/hive-sdk 0.1.4 → 0.1.6

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

@@ -0,0 +1,23 @@
+import type { Tool } from "../types";
+import { inspectArtifact } from "../../artifacts/store";
+
+export const artifactInspectTool: Tool = {
+  name: "artifact_inspect",
+  description: "Inspect managed artifact metadata, integrity, MIME type and dimensions without returning or modifying its binary content.",
+  parameters: {
+    type: "object",
+    properties: {
+      artifactId: {
+        type: "string",
+        description: "Managed artifact identifier returned by a Hive tool.",
+      },
+    },
+    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;
+    return inspectArtifact(artifactId, { userId });
+  },
+};

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

@@ -0,0 +1,129 @@
+/**
+ * BrowserBackend — el contrato que consumen las browser tools.
+ *
+ * Hay dos implementaciones con perfiles opuestos:
+ *
+ *  - `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.
+ *
+ *  - `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.
+ */
+
+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>;
+  close(): void;
+}
+
+export type BrowserBackendKind = "agent-browser" | "webview";
+
+/** `auto` resuelve a webview si el runtime lo soporta; si no, agent-browser. */
+export type BrowserBackendPreference = BrowserBackendKind | "auto";
+
+/** 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",
+];
+
+/** Chrome instalado en el sistema — `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;
+  }
+  // Ú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;
+    }
+  }
+  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.
+ */
+export function resolveWebViewEngine(): WebViewEngine | null {
+  if (process.platform === "darwin") return "webkit";
+  return findChrome() ? "chrome" : 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;
+}
+
+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";
+}

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

@@ -9,6 +9,7 @@
 import type { Tool } from "../types.ts";
 import { logger } from "../../utils/logger.ts";
 import { getBrowserService, screenshotElement } from "./browser-service.ts";
+import { createArtifact } from "../../artifacts/store.ts";
 
 const log = logger.child("browser-screenshot");
 
@@ -53,7 +54,7 @@ export const browserScreenshotTool: Tool = {
     },
     required: [],
   },
-  execute: async (params: Record<string, unknown>) => {
+  execute: async (params: Record<string, unknown>, config?: any) => {
     const url = params.url as string | undefined;
     const fullPage = (params.fullPage as boolean) ?? false;
     const selector = params.selector as string | undefined;
@@ -99,14 +100,34 @@ export const browserScreenshotTool: Tool = {
       }
 
       const currentUrl = view.url;
-      log.info(`Screenshot captured: ${currentUrl} (${screenshot.length} base64 chars, ${format})`);
+      const bytes = Buffer.from(screenshot, "base64");
+      const effectiveFormat = selector ? "png" : format;
+      const mimeType = effectiveFormat === "png" ? "image/png" : "image/jpeg";
+      const configurable = config?.configurable ?? {};
+      const artifact = await createArtifact({
+        bytes,
+        mimeType,
+        kind: "browser_screenshot",
+        userId: String(configurable.user_id ?? ""),
+        runId: configurable.run_id ? String(configurable.run_id) : null,
+        taskId: configurable.task_id ? String(configurable.task_id) : null,
+        rootDir: configurable.artifact_dir ? String(configurable.artifact_dir) : undefined,
+        width,
+        height,
+      });
+      log.info(`Screenshot stored as artifact ${artifact.id} (${artifact.size} bytes, ${mimeType})`);
 
       return {
         ok: true,
         url: currentUrl,
-        screenshot,
-        format,
-        encoding: "base64",
+        artifact_id: artifact.id,
+        kind: artifact.kind,
+        mime_type: artifact.mime_type,
+        size: artifact.size,
+        sha256: artifact.sha256,
+        status: artifact.status,
+        expires_at: artifact.expires_at,
+        format: effectiveFormat,
         fullPage,
         selector,
         viewport: { width, height },

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

@@ -1,11 +1,18 @@
 /**
- * BrowserService — Browser automation via agent-browser CLI (Rust).
+ * BrowserService — automatización de navegador, con backend intercambiable.
  *
- * Flujo:
+ * `AgentBrowserBackend` (este archivo) habla con el CLI de agent-browser por
+ * subproceso: maneja Chrome de verdad y corre headless, así que es el único que
+ * sirve en Docker o en un servidor sin display. Por eso sigue siendo el default.
+ *
+ * `WebViewBackend` (webview-backend.ts) usa `Bun.WebView` in-process — sin
+ * instalación ni subprocesos, mucho más rápido — pero necesita entorno gráfico.
+ * Se elige con `tools.browser.backend` o `HIVE_BROWSER_BACKEND`.
+ *
+ * Flujo del backend por CLI:
  *  1. Detecta si agent-browser está instalado (lazy install en primer uso).
  *  2. Ejecuta comandos via CLI con --json para output estructurado.
  *  3. El daemon de agent-browser maneja Chrome internamente via CDP.
- *  4. Las herramientas de browser usan AgentBrowserView (API compatible con CDPClient).
  */
 
 import { logger } from "../../utils/logger.ts";
@@ -13,6 +20,13 @@ import type { Config } from "../../config/loader.ts";
 import { existsSync, mkdirSync, readFileSync, rmSync } from "fs";
 import { homedir, tmpdir } from "os";
 import { dirname, join, resolve } from "path";
+import {
+  resolveBackendKind,
+  type BrowserBackend,
+  type BrowserBackendKind,
+  type ScreenshotOptions,
+  type SnapshotOptions,
+} from "./browser-backend.ts";
 
 const log = logger.child("browser-service");
 
@@ -117,7 +131,7 @@ async function ensureChromeInstalled(): Promise<void> {
 
 // ─── AgentBrowserView (API compatible con CDPClient) ──────────────────────────
 
-export class AgentBrowserView {
+export class AgentBrowserView implements BrowserBackend {
   private sessionName: string;
   private _url = "";
 
@@ -162,12 +176,7 @@ export class AgentBrowserView {
     return res.data?.result as T;
   }
 
-  async screenshot(options?: {
-    encoding?: "blob" | "buffer" | "base64" | "shmem";
-    format?: "png" | "jpeg" | "webp";
-    quality?: number;
-    clip?: { x: number; y: number; width: number; height: number; scale: number };
-  }): Promise<string> {
+  async screenshot(options?: ScreenshotOptions): Promise<string> {
     // Build args
     const args: string[] = ["screenshot"];
 
@@ -178,6 +187,11 @@ export class AgentBrowserView {
       args.push("--screenshot-quality", String(options.quality));
     }
 
+    // If clip/selector is provided, agent-browser screenshot accepts a positional selector
+    // For element screenshots, we can pass a selector as first positional arg
+    // But we don't have selector in options here — the old CDPClient didn't use it either
+    // screenshotElement helper handles element-specific screenshots
+
     const res = await this.run(args);
     if (!res.success) throw new Error(res.error || "screenshot failed");
 
@@ -259,8 +273,21 @@ export class AgentBrowserView {
     if (!res.success) throw new Error(res.error || "resize failed");
   }
 
+  /** Screenshot recortado a un elemento — agent-browser acepta el selector posicional. */
+  async screenshotElement(selector: string): Promise<string> {
+    const res = await this.run(["screenshot", selector]);
+    if (!res.success) throw new Error(res.error || `screenshot failed: ${selector}`);
+
+    const path = res.data?.path as string;
+    if (!path) throw new Error("screenshot did not return a path");
+
+    const base64 = Buffer.from(readFileSync(path)).toString("base64");
+    try { rmSync(path); } catch { /* ignore */ }
+    return base64;
+  }
+
   /** Capture accessibility tree snapshot (compact, AI-optimized). ~200-600 chars vs ~3000+ innerText. */
-  async snapshot(options?: { compact?: boolean; depth?: number; interactiveOnly?: boolean }): Promise<string> {
+  async snapshot(options?: SnapshotOptions): Promise<string> {
     const args = ["snapshot"];
     if (options?.compact !== false) args.push("-c");
     if (options?.depth) args.push("-d", String(options.depth));
@@ -321,11 +348,17 @@ export type LaunchSpec = { kind: "remote"; cdpUrl: string };
 
 // ─── BrowserService (singleton) ───────────────────────────────────────────────
 
-export type BrowserView = AgentBrowserView;
+/** Alias histórico: las tools sólo dependen del contrato, no de la implementación. */
+export type BrowserView = BrowserBackend;
+
+/** Re-export para que quien importe el servicio no tenga que conocer el módulo del contrato. */
+export type { BrowserBackend, BrowserBackendKind } from "./browser-backend.ts";
+export { isWebViewSupported, resolveBackendKind } from "./browser-backend.ts";
 
-let _client: AgentBrowserView | null = null;
+let _client: BrowserBackend | null = null;
 let _available = false;
 let _launching = false;
+let _kind: BrowserBackendKind = "agent-browser";
 
 export class BrowserService {
   private static instance: BrowserService | null = null;
@@ -352,6 +385,17 @@ export class BrowserService {
       return false;
     }
 
+    _kind = resolveBackendKind(b?.backend);
+
+    if (_kind === "webview") {
+      // No hay nada que instalar ni que descargar: el WebView se crea al primer
+      // uso. Si el entorno no lo soporta, ensureView() falla ahí y el servicio
+      // queda no disponible, igual que cuando agent-browser no arranca.
+      _available = true;
+      log.info("✅ Backend de navegador: Bun.WebView (in-process, sin Chrome)");
+      return true;
+    }
+
     const installed = await isAgentBrowserInstalled();
 
     if (!installed) {
@@ -387,8 +431,13 @@ export class BrowserService {
     }
     _launching = true;
     try {
-      const sessionName = this.config.tools?.browser?.sessionName ?? DEFAULT_SESSION_NAME;
-      _client = new AgentBrowserView(sessionName);
+      if (_kind === "webview") {
+        const { WebViewBackend } = await import("./webview-backend.ts");
+        _client = new WebViewBackend({ show: this.config.tools?.browser?.headless === false });
+      } else {
+        const sessionName = this.config.tools?.browser?.sessionName ?? DEFAULT_SESSION_NAME;
+        _client = new AgentBrowserView(sessionName);
+      }
       log.info("✅ Browser abierto — el usuario verá las acciones del agente");
       return true;
     } catch (err) {
@@ -401,20 +450,25 @@ export class BrowserService {
     }
   }
 
-  async getView(): Promise<AgentBrowserView | null> {
+  async getView(): Promise<BrowserBackend | null> {
     if (!_available) return null;
     await this._ensureLaunched();
     return _client;
   }
 
-  getViewSync(): AgentBrowserView | null {
+  getViewSync(): BrowserBackend | null {
     return _client;
   }
 
-  async getPage(): Promise<AgentBrowserView | null> {
+  async getPage(): Promise<BrowserBackend | null> {
     return this.getView();
   }
 
+  /** Qué backend quedó activo — lo reporta `hive doctor` y los tests. */
+  getBackendKind(): BrowserBackendKind {
+    return _kind;
+  }
+
   isAvailable(): boolean {
     return _available;
   }
@@ -423,8 +477,8 @@ export class BrowserService {
     return _available && _client !== null;
   }
 
-  getInfo(): { running: boolean } {
-    return { running: this.isRunning() };
+  getInfo(): { running: boolean; backend: BrowserBackendKind } {
+    return { running: this.isRunning(), backend: _kind };
   }
 
   async stop(): Promise<void> {
@@ -457,7 +511,7 @@ export function getBrowserService(): BrowserService | null {
 // ─── Helpers (misma API que antes) ───────────────────────────────────────────
 
 export async function waitForSelector(
-  view: AgentBrowserView,
+  view: BrowserBackend,
   selector: string,
   timeout = 30000
 ): Promise<void> {
@@ -471,7 +525,7 @@ export async function waitForSelector(
 }
 
 export async function waitForCondition(
-  view: AgentBrowserView,
+  view: BrowserBackend,
   expression: string,
   timeout = 30000
 ): Promise<void> {
@@ -485,19 +539,10 @@ export async function waitForCondition(
 }
 
 export async function screenshotElement(
-  view: AgentBrowserView,
+  view: BrowserBackend,
   selector: string
 ): Promise<string> {
-  const res = await (view as any).run(["screenshot", selector]);
-  if (!res.success) throw new Error(res.error || `screenshot failed: ${selector}`);
-
-  const path = res.data?.path as string;
-  if (!path) throw new Error("screenshot did not return a path");
-
-  const data = readFileSync(path);
-  const base64 = Buffer.from(data).toString("base64");
-
-  try { rmSync(path); } catch { /* ignore */ }
-
-  return base64;
+  // Antes esto hacía `(view as any).run([...])`, atándose a la implementación por
+  // CLI: con dos backends el recorte es responsabilidad de cada uno.
+  return view.screenshotElement(selector);
 }

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

@@ -68,17 +68,12 @@ export const browserTypeTool: Tool = {
         await Bun.sleep(500);
       }
 
-      // click(selector) waits for actionability then focuses the element
-      await view.click(selector, { timeout });
-
       if (clear) {
-        // Ctrl+A → Backspace to clear existing content
-        await view.press("a", { modifiers: ["Control"] });
-        await view.press("Backspace");
+        await (view as any).fill(selector, text);
+      } else {
+        await (view as any).typeIn(selector, text);
       }
 
-      await view.type(text);
-
       const currentUrl = view.url;
       log.info(`Type successful: "${text.substring(0, 50)}${text.length > 50 ? "..." : ""}" into ${selector}`);
 

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

@@ -1,13 +1,12 @@
 /**
  * Web Tools - Browser automation + Web utilities
  * 
- * Browser tools use Puppeteer/Chromium (auto-managed).
+ * Browser tools use agent-browser (Rust CLI, auto-managed).
  */
 
 import type { Tool } from "../types.ts";
 import { webSearchTool } from "./web-search.ts";
 import { webFetchTool } from "./web-fetch.ts";
-import { apiRequestTool } from "./api-request.ts";
 import { browserNavigateTool } from "./browser-navigate.ts";
 import { browserScreenshotTool } from "./browser-screenshot.ts";
 import { browserClickTool } from "./browser-click.ts";
@@ -15,12 +14,12 @@ import { browserTypeTool } from "./browser-type.ts";
 import { browserExtractTool } from "./browser-extract.ts";
 import { browserScriptTool } from "./browser-script.ts";
 import { browserWaitTool } from "./browser-wait.ts";
+import { artifactInspectTool } from "./artifact-inspect.ts";
 
 export function createTools(): Tool[] {
   return [
     webSearchTool,
     webFetchTool,
-    apiRequestTool,
     browserNavigateTool,
     browserScreenshotTool,
     browserClickTool,
@@ -28,12 +27,12 @@ export function createTools(): Tool[] {
     browserExtractTool,
     browserScriptTool,
     browserWaitTool,
+    artifactInspectTool,
   ];
 }
 
 export * from "./web-search.ts";
 export * from "./web-fetch.ts";
-export * from "./api-request.ts";
 export * from "./browser-navigate.ts";
 export * from "./browser-screenshot.ts";
 export * from "./browser-click.ts";
@@ -42,3 +41,4 @@ export * from "./browser-extract.ts";
 export * from "./browser-script.ts";
 export * from "./browser-wait.ts";
 export * from "./browser-service.ts";
+export * from "./artifact-inspect.ts";