@johpaz/hive-sdk 0.0.16 → 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
@@ -347,4 +407,4 @@ const hiveDir = getHiveDir();  // ~/.hive o HIVE_DATA_DIR
 
 ---
 
-*Documentación Hive SDK v0.0.16*
+*Documentación Hive SDK v0.0.17*

package/docs/API-WORKERS-EVENTS.md

@@ -192,13 +192,13 @@ const results = await pool.executeWithConcurrency(tasks, 5);
 
 ---
 
-## CLI: hive add-worker
+## CLI: hives add-worker
 
 Genera un Bun Worker en tu proyecto:
 
 ```bash
 cd my-project
-hive add-worker researcher
+hives add-worker researcher
 ```
 
 Crea `src/workers/researcher.worker.ts`:
@@ -296,4 +296,4 @@ const canvas = new CanvasManager();
 
 ---
 
-*Documentación Hive SDK v0.0.16*
+*Documentación Hive SDK v0.0.17*

package/docs/INDEX.md

@@ -20,7 +20,7 @@
 ### 1. Crear una app harness completa
 
 ```bash
-hive create-app my-hive
+hives create-app my-hive
 cd my-hive
 bun install
 cp .env.example .env
@@ -187,4 +187,4 @@ bun test --timeout 60000
 
 ---
 
-*Documentación Hive SDK v0.0.16*
+*Documentación Hive SDK v0.0.17*

package/docs/TEMPLATE-HIVE-APP.md

@@ -7,7 +7,7 @@ El template `hive-app` genera una **aplicación harness completa** lista para ej
 ## Generar una app
 
 ```bash
-hive create-app my-hive
+hives create-app my-hive
 ```
 
 Esto crea el directorio `my-hive/` con la estructura completa.
@@ -320,8 +320,8 @@ await channelManager.initialize();
 
 ```bash
 cd my-hive
-hive add-worker researcher
-hive add-worker coder
+hives add-worker researcher
+hives add-worker coder
 ```
 
 Esto genera `src/workers/researcher.worker.ts` y `src/workers/coder.worker.ts`.
@@ -330,7 +330,7 @@ Esto genera `src/workers/researcher.worker.ts` y `src/workers/coder.worker.ts`.
 
 ```bash
 cd my-hive
-hive add-tool search-docs
+hives add-tool search-docs
 ```
 
 Genera `src/tools/search-docs.ts`.
@@ -339,7 +339,7 @@ Genera `src/tools/search-docs.ts`.
 
 ```bash
 cd my-hive
-hive add-skill onboarding
+hives add-skill onboarding
 ```
 
 Genera `src/skills/onboarding.ts`.
@@ -357,4 +357,4 @@ bun test
 
 ---
 
-*Documentación Hive SDK v0.0.16*
+*Documentación Hive SDK v0.0.17*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johpaz/hive-sdk",
-  "version": "0.0.16",
+  "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",
@@ -29,7 +29,7 @@
   "main": "./packages/core/src/index.ts",
   "types": "./packages/core/src/index.ts",
   "bin": {
-    "hive": "./packages/cli/bin/hive"
+    "hives": "./packages/cli/bin/hives"
   },
   "workspaces": [
     "packages/core",

package/packages/cli/src/index.ts

@@ -41,7 +41,7 @@ switch (command) {
 
 function printHelp() {
 	console.log(`
-Usage: hive <command> [options]
+Usage: hives <command> [options]
 
 Commands:
   init <name>         Initialize a new Hive agent project

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",
+    });
+  });
+});