@johpaz/hive-sdk 0.0.17 → 0.0.18

package/docs/API-TOOLS-SKILLS-CHANNELS.md

@@ -80,6 +80,57 @@ const tools = selectTools("Buscar archivos en el proyecto");
 const webTools = tools.filter(t => t.category === "web");
 ```
 
+### Built-in Web + API Tools
+
+El SDK expone herramientas web/browser listas para usar:
+
+```typescript
+import {
+  webSearchTool,
+  webFetchTool,
+  apiRequestTool,
+  browserNavigateTool,
+  browserScreenshotTool,
+  browserClickTool,
+  browserTypeTool,
+  browserExtractTool,
+  browserScriptTool,
+  browserWaitTool,
+} from "@johpaz/hive-sdk";
+```
+
+#### Browser automation (agent-browser)
+
+Las herramientas `browser_*` usan [`agent-browser`](https://www.npmjs.com/package/agent-browser), un CLI Rust que gestiona Chrome/Chromium internamente vía CDP. En el primer uso se instala automáticamente en `~/.hive/agent-browser` y se descarga Chrome si es necesario.
+
+```typescript
+import { initializeBrowserService, getBrowserService } from "@johpaz/hive-sdk";
+
+const browserService = initializeBrowserService(config);
+await browserService.start();
+
+const view = await browserService.getView();
+await view.navigate("https://example.com");
+const snapshot = await view.snapshot({ compact: true, depth: 3 });
+```
+
+#### api_request
+
+Conecta APIs REST con autenticación y métodos HTTP:
+
+```typescript
+const result = await apiRequestTool.execute({
+  url: "https://api.example.com/items",
+  method: "POST",
+  headers: { "X-Custom": "value" },
+  body: { name: "example" },
+  auth: { type: "bearer", token: process.env.API_TOKEN! },
+  timeoutMs: 30000,
+});
+
+// Auth soportada: bearer, basic, api_key (header o query)
+```
+
 ---
 
 ## Skills
@@ -115,6 +166,15 @@ const skills = loader.list();
 const skill = loader.get("file-manager");
 ```
 
+### Skills empaquetadas
+
+El SDK incluye skills empaquetadas para casos comunes. Algunas útiles para web y APIs:
+
+- `web_research` — búsqueda y síntesis con `web_search` + `web_fetch`.
+- `web_browser_research` — investigación profunda combinando `web_search` con navegación real (`browser_navigate`, `browser_extract`) para sitios dinámicos.
+- `browser_scrape` — captura de contenido renderizado con screenshots.
+- `browser_automate` — automatización de flujos web (clicks, formularios).
+
 ---
 
 ## MCP

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johpaz/hive-sdk",
-  "version": "0.0.17",
+  "version": "0.0.18",
   "private": false,
   "description": "Hive SDK — The Agent Harness SDK. Build, deploy, and scale AI agent applications with multi-channel support, context engineering, and swarm orchestration.",
   "license": "MIT",

package/packages/core/src/agent/selectors/ToolSelector.ts

@@ -147,6 +147,7 @@ export const CORE_TOOL_CATALOG: ToolDescriptor[] = [
     // Web tools
     { name: "web_search", description: "Search web for current information, find up-to-date news facts and research. Spanish keywords: buscar en internet, buscar web, información, noticias, investigación, buscar", category: "web", abstractionLevel: "atomic" },
     { name: "web_fetch", description: "Fetch content from URL, download and extract content from web pages. Spanish keywords: obtener página, descargar web, extraer contenido, obtener contenido, página web", category: "web", abstractionLevel: "atomic" },
+    { name: "api_request", description: "Connect to REST APIs, make HTTP requests with authentication and custom headers. Spanish keywords: conectar api, peticion http, llamada api, rest api, endpoint, bearer token, api key, basic auth", category: "web", abstractionLevel: "atomic" },
 
     // Memory tools
     { name: "memory_write", description: "Store in long-term memory, save information to persistent memory for later retrieval. Spanish keywords: guardar memoria, guardar información, recordar, guardar dato, memoria", category: "memory", abstractionLevel: "atomic" },

package/packages/core/src/api/createAgent.ts

@@ -37,6 +37,16 @@ export async function createAgent(config: AgentConfig): Promise<Agent> {
 	await initializeDatabase();
 
 	const coreConfig = await loadConfig();
+
+	// Initialize browser automation (agent-browser) if enabled
+	try {
+		const { initializeBrowserService } = await import("../tools/web/browser-service.ts");
+		const browserService = initializeBrowserService(coreConfig);
+		await browserService.start();
+	} catch (err) {
+		log.warn(`Browser service initialization skipped: ${(err as Error).message}`);
+	}
+
 	const allBuiltInTools = createAllTools(coreConfig);
 
 	const customTools = (config.tools ?? []).map(t => ({

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

@@ -116,7 +116,7 @@ const WebConfigSchema = z.object({
 
 const BrowserConfigSchema = z.object({
   enabled: z.boolean().optional(),
-  cdpUrl: z.string().optional(),
+  sessionName: z.string().optional(),
   headless: z.boolean().optional(),
   timeoutMs: z.number().optional(),
 });
@@ -437,7 +437,7 @@ function buildDefaultConfig(): Config {
       },
       browser: {
         enabled: true,
-        cdpUrl: "ws://127.0.0.1:9222",
+        sessionName: "hive",
         headless: true,
         timeoutMs: 30000,
       },

package/packages/core/src/index.ts

@@ -8,6 +8,19 @@ export type { ToolDefinition } from "./tools/ToolRegistry.ts";
 export { ToolRegistry } from "./tools/ToolRegistry.ts";
 export { ToolExecutor } from "./tools/ToolExecutor.ts";
 export type { ToolExecutionResult } from "./tools/ToolExecutor.ts";
+export {
+  webSearchTool,
+  webFetchTool,
+  apiRequestTool,
+  browserNavigateTool,
+  browserScreenshotTool,
+  browserClickTool,
+  browserTypeTool,
+  browserExtractTool,
+  browserScriptTool,
+  browserWaitTool,
+} from "./tools/index.ts";
+export type { ApiAuth, HttpMethod, ResponseFormat } from "./tools/web/api-request.ts";
 
 // ─── Skills ──────────────────────────────────────────────────────────────────
 export { defineSkill } from "./skills/defineSkill.ts";

package/packages/core/src/skills/bundled-data.generated.ts

@@ -338,6 +338,56 @@ Esta skill se activa para automatizar flujos de interacción con aplicaciones we
 - ❌ No esperar carga de página
 - ❌ Ignorar errores de elementos
 - ❌ No verificar estado después de acciones
+`,
+  },
+  {
+    name: "web_browser_research",
+    description: `Search the web and navigate results with a real browser to extract content from dynamic or JavaScript-heavy sites`,
+    category: "web",
+    version: "1.0.0",
+    tools: ["web_search","browser_navigate","browser_extract","web_fetch"],
+    triggers: ["investigá en web con navegador","web browser research","buscá y navegá","search and browse","research with browser","navegá los resultados","browse search results","contenido dinámico","dynamic content research","sitios con javascript","javascript sites research"],
+    body: `
+# Web Browser Research Skill
+
+## Cuándo se Activa
+
+Esta skill se activa cuando el usuario necesita investigación web profunda, especialmente cuando:
+- Los resultados de búsqueda pueden requerir navegación real por sitios dinámicos.
+- El contenido objetivo está renderizado con JavaScript (SPAs, dashboards, etc.).
+- Se necesita extraer datos estructurados de páginas web.
+
+## Herramientas Disponibles
+
+| Tool | Qué hace | Cuándo usarla |
+|------|----------|---------------|
+| \`web_search\` | Busca en internet y devuelve resultados | Encontrar URLs relevantes |
+| \`browser_navigate\` | Navega y renderiza la página completa | Sitios dinámicos con JavaScript |
+| \`browser_extract\` | Extrae datos con selectores CSS/XPath | Obtener contenido estructurado |
+| \`web_fetch\` | Descarga contenido estático | Páginas simples o respaldo |
+
+## Workflow
+
+1. **Buscar** → \`web_search({ query, numResults: 5 })\`
+2. **Seleccionar fuentes** → Elegir 2-3 URLs relevantes y confiables.
+3. **Navegar** → \`browser_navigate({ url })\` para cada fuente dinámica.
+4. **Extraer** → \`browser_extract({ selector: "article, .content, main" })\` o similar.
+5. **Respaldo estático** → Si el browser falla, usar \`web_fetch({ url })\`.
+6. **Sintetizar** → Responder con puntos clave y citas con URLs completas.
+
+## Mejores Prácticas
+
+- Priorizar sitios oficiales, documentación y fuentes primarias.
+- Usar selectores estables (etiquetas semánticas como \`article\`, \`main\`).
+- Si el contenido es largo, extraer por secciones.
+- Siempre incluir URLs de fuentes en la respuesta final.
+
+## Errores a Evitar
+
+- ❌ Usar solo \`web_fetch\` para SPAs sin probar el browser primero.
+- ❌ Seleccionar selectores frágiles basados en clases aleatorias.
+- ❌ No citar las fuentes usadas.
+- ❌ Confundir snippets de búsqueda con contenido completo verificado.
 `,
   },
   {

package/packages/core/src/skills/skills.test.ts

@@ -0,0 +1,21 @@
+import { describe, it, expect } from "bun:test";
+import { BUNDLED_SKILLS_DATA } from "./bundled-data.generated.ts";
+
+describe("Bundled skills", () => {
+  it("includes web_browser_research skill", () => {
+    const skill = BUNDLED_SKILLS_DATA.find((s) => s.name === "web_browser_research");
+    expect(skill).toBeDefined();
+    expect(skill?.category).toBe("web");
+    expect(skill?.tools).toContain("web_search");
+    expect(skill?.tools).toContain("browser_navigate");
+    expect(skill?.tools).toContain("browser_extract");
+    expect(skill?.triggers.length).toBeGreaterThan(0);
+  });
+
+  it("includes existing web and browser skills", () => {
+    const names = BUNDLED_SKILLS_DATA.map((s) => s.name);
+    expect(names).toContain("web_research");
+    expect(names).toContain("browser_scrape");
+    expect(names).toContain("browser_automate");
+  });
+});

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

@@ -139,6 +139,7 @@ export {
 export {
   webSearchTool,
   webFetchTool,
+  apiRequestTool,
   browserNavigateTool,
   browserScreenshotTool,
   browserClickTool,

package/packages/core/src/tools/web/api-request.test.ts

@@ -0,0 +1,170 @@
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { apiRequestTool } from "./api-request.ts";
+
+describe("apiRequestTool", () => {
+  let originalFetch: typeof fetch;
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  function mockFetch(response: Response) {
+    globalThis.fetch = Object.assign(async () => response, { preconnect: async () => undefined }) as typeof fetch;
+  }
+
+  function mockResponse(
+    body: BodyInit,
+    init: ResponseInit & { headers?: Record<string, string> } = {}
+  ): Response {
+    return new Response(body, {
+      status: init.status ?? 200,
+      statusText: init.statusText ?? "OK",
+      headers: init.headers ?? {},
+    });
+  }
+
+  it("executes a simple GET request", async () => {
+    let capturedUrl = "";
+    let capturedInit: RequestInit = {};
+    globalThis.fetch = Object.assign(async (url, init) => {
+      capturedUrl = url.toString();
+      capturedInit = init ?? {};
+      return mockResponse(JSON.stringify({ ok: true }), { headers: { "content-type": "application/json" } });
+    }, { preconnect: async () => undefined }) as typeof fetch;
+
+    const result = await apiRequestTool.execute({ url: "https://api.example.com/data" });
+
+    expect(capturedUrl).toBe("https://api.example.com/data");
+    expect(capturedInit.method).toBe("GET");
+    expect(result).toMatchObject({
+      ok: true,
+      status: 200,
+      data: { ok: true },
+    });
+  });
+
+  it("sends POST with JSON body", async () => {
+    let capturedInit: RequestInit = {};
+    globalThis.fetch = Object.assign(async (_url, init) => {
+      capturedInit = init ?? {};
+      return mockResponse(JSON.stringify({ id: 1 }), { headers: { "content-type": "application/json" } });
+    }, { preconnect: async () => undefined }) as typeof fetch;
+
+    const result = await apiRequestTool.execute({
+      url: "https://api.example.com/items",
+      method: "POST",
+      body: { name: "test" },
+    });
+
+    expect(capturedInit.method).toBe("POST");
+    expect(capturedInit.headers).toMatchObject({ "content-type": "application/json" });
+    expect(capturedInit.body).toBe(JSON.stringify({ name: "test" }));
+    expect(result).toMatchObject({ ok: true, data: { id: 1 } });
+  });
+
+  it("applies bearer auth", async () => {
+    let capturedInit: RequestInit = {};
+    globalThis.fetch = Object.assign(async (_url, init) => {
+      capturedInit = init ?? {};
+      return mockResponse("{}");
+    }, { preconnect: async () => undefined }) as typeof fetch;
+
+    await apiRequestTool.execute({
+      url: "https://api.example.com/private",
+      auth: { type: "bearer", token: "secret-token" },
+    });
+
+    expect(new Headers(capturedInit.headers).get("Authorization")).toBe("Bearer secret-token");
+  });
+
+  it("applies basic auth", async () => {
+    let capturedInit: RequestInit = {};
+    globalThis.fetch = Object.assign(async (_url, init) => {
+      capturedInit = init ?? {};
+      return mockResponse("{}");
+    }, { preconnect: async () => undefined }) as typeof fetch;
+
+    await apiRequestTool.execute({
+      url: "https://api.example.com/private",
+      auth: { type: "basic", username: "alice", password: "secret" },
+    });
+
+    expect(new Headers(capturedInit.headers).get("Authorization")).toBe(`Basic ${btoa("alice:secret")}`);
+  });
+
+  it("applies api_key in header", async () => {
+    let capturedInit: RequestInit = {};
+    globalThis.fetch = Object.assign(async (_url, init) => {
+      capturedInit = init ?? {};
+      return mockResponse("{}");
+    }, { preconnect: async () => undefined }) as typeof fetch;
+
+    await apiRequestTool.execute({
+      url: "https://api.example.com/private",
+      auth: { type: "api_key", in: "header", name: "X-API-Key", value: "abc123" },
+    });
+
+    expect(new Headers(capturedInit.headers).get("X-API-Key")).toBe("abc123");
+  });
+
+  it("applies api_key in query", async () => {
+    let capturedUrl = "";
+    globalThis.fetch = Object.assign(async (url, _init) => {
+      capturedUrl = url.toString();
+      return mockResponse("{}");
+    }, { preconnect: async () => undefined }) as typeof fetch;
+
+    await apiRequestTool.execute({
+      url: "https://api.example.com/private",
+      auth: { type: "api_key", in: "query", name: "api_key", value: "abc123" },
+    });
+
+    expect(capturedUrl).toBe("https://api.example.com/private?api_key=abc123");
+  });
+
+  it("returns error for non-ok HTTP response", async () => {
+    globalThis.fetch = Object.assign(async () => mockResponse("Not found", { status: 404, statusText: "Not Found" }), { preconnect: async () => undefined }) as typeof fetch;
+
+    const result = await apiRequestTool.execute({ url: "https://api.example.com/missing" });
+
+    expect(result).toMatchObject({
+      ok: false,
+      status: 404,
+      error: "HTTP 404: Not Found",
+    });
+  });
+
+  it("rejects non-http URLs", async () => {
+    const result = await apiRequestTool.execute({ url: "file:///etc/passwd" });
+
+    expect(result).toMatchObject({
+      ok: false,
+      error: "Invalid URL. Only http:// and https:// are allowed.",
+    });
+  });
+
+  it("respects timeout", async () => {
+    globalThis.fetch = Object.assign(async (_url, init) => {
+      expect(init?.signal).toBeDefined();
+      return mockResponse("{}");
+    }, { preconnect: async () => undefined }) as typeof fetch;
+
+    const result = await apiRequestTool.execute({ url: "https://api.example.com/data", timeoutMs: 5000 });
+    expect(result).toMatchObject({ ok: true });
+  });
+
+  it("returns text for non-json responses", async () => {
+    globalThis.fetch = Object.assign(async () => mockResponse("hello world", { headers: { "content-type": "text/plain" } }), { preconnect: async () => undefined }) as typeof fetch;
+
+    const result = await apiRequestTool.execute({ url: "https://api.example.com/text" });
+
+    expect(result).toMatchObject({
+      ok: true,
+      data: "hello world",
+    });
+  });
+});

package/packages/core/src/tools/web/api-request.ts

@@ -0,0 +1,239 @@
+/**
+ * api_request - Make generic HTTP requests to connect REST APIs
+ *
+ * @category web
+ * @seedId api_request
+ * @spanish conectar api, peticion http, llamada api, rest api, endpoint
+ */
+
+import type { Tool } from "../types.ts";
+import { logger } from "../../utils/logger.ts";
+
+const log = logger.child("api-request");
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_RESPONSE_CHARS = 100_000;
+
+export type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS";
+export type ResponseFormat = "auto" | "json" | "text" | "binary";
+
+export interface ApiAuthBearer {
+  type: "bearer";
+  token: string;
+}
+
+export interface ApiAuthBasic {
+  type: "basic";
+  username: string;
+  password: string;
+}
+
+export interface ApiAuthApiKey {
+  type: "api_key";
+  in: "header" | "query";
+  name: string;
+  value: string;
+}
+
+export type ApiAuth = ApiAuthBearer | ApiAuthBasic | ApiAuthApiKey;
+
+function applyAuth(
+  url: string,
+  init: RequestInit,
+  auth?: ApiAuth
+): { url: string; init: RequestInit } {
+  if (!auth) return { url, init };
+
+  const headers = new Headers(init.headers);
+
+  switch (auth.type) {
+    case "bearer":
+      headers.set("Authorization", `Bearer ${auth.token}`);
+      break;
+    case "basic": {
+      const credentials = btoa(`${auth.username}:${auth.password}`);
+      headers.set("Authorization", `Basic ${credentials}`);
+      break;
+    }
+    case "api_key":
+      if (auth.in === "query") {
+        const parsed = new URL(url);
+        parsed.searchParams.set(auth.name, auth.value);
+        url = parsed.toString();
+      } else {
+        headers.set(auth.name, auth.value);
+      }
+      break;
+  }
+
+  return { url, init: { ...init, headers } };
+}
+
+function isValidHttpUrl(url: string): boolean {
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === "http:" || parsed.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+async function parseResponse(
+  response: Response,
+  format: ResponseFormat
+): Promise<{ data: unknown; contentType: string }> {
+  const contentType = response.headers.get("content-type") || "";
+
+  if (format === "json" || (format === "auto" && contentType.includes("application/json"))) {
+    const json = await response.json();
+    return { data: json, contentType };
+  }
+
+  if (format === "text" || (format === "auto" && contentType.includes("text/"))) {
+    const text = await response.text();
+    return { data: text.slice(0, MAX_RESPONSE_CHARS), contentType };
+  }
+
+  if (format === "binary") {
+    const arrayBuffer = await response.arrayBuffer();
+    const base64 = Buffer.from(arrayBuffer).toString("base64");
+    return { data: base64, contentType };
+  }
+
+  // Fallback: try text, then JSON
+  const text = await response.text();
+  if (text.trim().startsWith("{") || text.trim().startsWith("[")) {
+    try {
+      return { data: JSON.parse(text), contentType };
+    } catch {
+      /* fallthrough */
+    }
+  }
+  return { data: text.slice(0, MAX_RESPONSE_CHARS), contentType };
+}
+
+export const apiRequestTool: Tool = {
+  name: "api_request",
+  description:
+    "Connect to REST APIs: make HTTP requests with methods, headers, body and authentication. Spanish: conectar api, peticion http, llamada api, rest api, endpoint, bearer, api key",
+  parameters: {
+    type: "object",
+    properties: {
+      url: {
+        type: "string",
+        description: "The API endpoint URL (http:// or https://)",
+      },
+      method: {
+        type: "string",
+        enum: ["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"],
+        description: "HTTP method (default: GET)",
+      },
+      headers: {
+        type: "object",
+        additionalProperties: { type: "string" },
+        description: "Optional HTTP headers as key-value pairs",
+      },
+      body: {
+        type: "string",
+        description: "Request body. Objects should be passed as JSON strings; strings are sent as-is",
+      },
+      auth: {
+        type: "object",
+        description: "Optional authentication configuration",
+        properties: {
+          type: {
+            type: "string",
+            enum: ["bearer", "basic", "api_key"],
+          },
+          token: { type: "string" },
+          username: { type: "string" },
+          password: { type: "string" },
+          in: { type: "string", enum: ["header", "query"] },
+          name: { type: "string" },
+          value: { type: "string" },
+        },
+        required: ["type"],
+      },
+      timeoutMs: {
+        type: "number",
+        description: "Request timeout in milliseconds (default: 30000)",
+      },
+      responseFormat: {
+        type: "string",
+        enum: ["auto", "json", "text", "binary"],
+        description: "How to parse the response (default: auto)",
+      },
+    },
+    required: ["url"],
+  },
+  execute: async (params: Record<string, unknown>) => {
+    const url = params.url as string;
+    const method = (params.method as HttpMethod) ?? "GET";
+    const headers = (params.headers as Record<string, string>) ?? {};
+    const bodyParam = params.body;
+    const auth = params.auth as ApiAuth | undefined;
+    const timeoutMs = (params.timeoutMs as number) ?? DEFAULT_TIMEOUT_MS;
+    const responseFormat = (params.responseFormat as ResponseFormat) ?? "auto";
+
+    if (!isValidHttpUrl(url)) {
+      return { ok: false, error: "Invalid URL. Only http:// and https:// are allowed." };
+    }
+
+    log.info(`API request: ${method} ${url}`);
+
+    let body: BodyInit | undefined;
+    const finalHeaders: Record<string, string> = { ...headers };
+
+    if (bodyParam !== undefined) {
+      if (typeof bodyParam === "string") {
+        body = bodyParam;
+      } else {
+        body = JSON.stringify(bodyParam);
+        if (!finalHeaders["content-type"] && !finalHeaders["Content-Type"]) {
+          finalHeaders["content-type"] = "application/json";
+        }
+      }
+    }
+
+    let init: RequestInit = {
+      method,
+      headers: finalHeaders,
+      body,
+      signal: AbortSignal.timeout(timeoutMs),
+    };
+
+    const final = applyAuth(url, init, auth);
+
+    try {
+      const response = await fetch(final.url, final.init);
+      const { data, contentType } = await parseResponse(response, responseFormat);
+
+      const responseHeaders: Record<string, string> = {};
+      response.headers.forEach((value, key) => {
+        responseHeaders[key] = value;
+      });
+
+      const result = {
+        ok: response.ok,
+        status: response.status,
+        statusText: response.statusText,
+        url: final.url,
+        contentType,
+        headers: responseHeaders,
+        data,
+      };
+
+      if (!response.ok) {
+        log.warn(`API request returned ${response.status} for ${final.url}`);
+        return { ok: false, error: `HTTP ${response.status}: ${response.statusText}`, ...result };
+      }
+
+      log.info(`API request successful: ${response.status} ${final.url}`);
+      return result;
+    } catch (error) {
+      const message = (error as Error).message;
+      log.error(`API request failed: ${message}`);
+      return { ok: false, error: `API request failed: ${message}` };
+    }
+  },
+};

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 Chrome/Chromium.",
+        error: "Browser automation not available. Install agent-browser.",
       };
     }
 
@@ -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 Chrome/Chromium." };
+      if (!view) return { ok: false, error: "Browser automation not available. Install agent-browser." };
 
       if (url) {
         await view.navigate(url);