@robota-sdk/agent-tools 3.0.0-beta.1 → 3.0.0-beta.11

package/README.md

@@ -1,90 +1,72 @@
 # @robota-sdk/agent-tools
 
-Tool registry, tool creation infrastructure, and built-in CLI tools for the Robota SDK. Provides everything needed to define custom tools with Zod schema validation and includes six ready-to-use file system tools.
+Tool registry, tool creation infrastructure, and 8 built-in CLI tools for the Robota SDK.
 
 ## Installation
 
 ```bash
 npm install @robota-sdk/agent-tools
-# or
-pnpm add @robota-sdk/agent-tools
 ```
 
+Peer dependency: `@robota-sdk/agent-core`
+
 ## Quick Start
 
-Create a custom tool with `createZodFunctionTool`:
+### Create a Tool with Zod
 
 ```typescript
-import { z } from 'zod';
 import { createZodFunctionTool } from '@robota-sdk/agent-tools';
+import { z } from 'zod';
 
 const weatherTool = createZodFunctionTool({
-  name: 'GetWeather',
+  name: 'get_weather',
   description: 'Get current weather for a city',
   schema: z.object({
     city: z.string().describe('City name'),
-    unit: z.enum(['celsius', 'fahrenheit']).default('celsius'),
   }),
-  execute: async ({ city, unit }) => {
-    // Your implementation here
-    return { temperature: 22, unit, city };
-  },
+  handler: async ({ city }) => ({
+    data: JSON.stringify({ city, temperature: 22, condition: 'sunny' }),
+  }),
 });
 ```
 
-## Built-in Tools
-
-Six CLI tools are included for file system operations:
-
-| Export      | Tool Name | Description                              |
-| ----------- | --------- | ---------------------------------------- |
-| `bashTool`  | `Bash`    | Execute shell commands via child_process |
-| `readTool`  | `Read`    | Read file contents with line numbers     |
-| `writeTool` | `Write`   | Write content to a file                  |
-| `editTool`  | `Edit`    | Replace a specific string in a file      |
-| `globTool`  | `Glob`    | Find files matching a glob pattern       |
-| `grepTool`  | `Grep`    | Search file contents with regex          |
+### Use Built-in Tools
 
 ```typescript
-import {
-  bashTool,
-  readTool,
-  writeTool,
-  editTool,
-  globTool,
-  grepTool,
-} from '@robota-sdk/agent-tools';
+import { bashTool, readTool, globTool, grepTool } from '@robota-sdk/agent-tools';
+import { Robota } from '@robota-sdk/agent-core';
+
+const agent = new Robota({
+  name: 'DevAgent',
+  aiProviders: [provider],
+  defaultModel: { provider: 'anthropic', model: 'claude-sonnet-4-6' },
+  tools: [bashTool, readTool, globTool, grepTool],
+});
 ```
 
-Each tool implements `getName()`, `getDescription()`, `getSchema()`, and `execute()`.
+## Built-in Tools (8)
 
-## Tool Infrastructure
+| Export          | Tool Name | Description                          |
+| --------------- | --------- | ------------------------------------ |
+| `bashTool`      | Bash      | Execute shell commands               |
+| `readTool`      | Read      | Read file contents with line numbers |
+| `writeTool`     | Write     | Write content to a file              |
+| `editTool`      | Edit      | Replace a specific string in a file  |
+| `globTool`      | Glob      | Find files matching a glob pattern   |
+| `grepTool`      | Grep      | Search file contents with regex      |
+| `webFetchTool`  | WebFetch  | Fetch URL content (HTML-to-text)     |
+| `webSearchTool` | WebSearch | Web search via Brave Search API      |
 
-| Export                  | Description                                 |
-| ----------------------- | ------------------------------------------- |
-| `ToolRegistry`          | Central tool registration and schema lookup |
-| `FunctionTool`          | JS function tool with Zod schema validation |
-| `createFunctionTool`    | Factory for creating function tools         |
-| `createZodFunctionTool` | Factory with Zod validation and conversion  |
-| `OpenAPITool`           | Tool generated from OpenAPI specification   |
-| `zodToJsonSchema`       | Converts Zod schemas to JSON Schema format  |
-
-## TToolResult
-
-Built-in tools return results using the `TToolResult` type:
-
-```typescript
-interface TToolResult {
-  success: boolean;
-  output: string;
-  error?: string;
-  exitCode?: number;
-}
-```
-
-## Documentation
+## Tool Infrastructure
 
-See [docs/SPEC.md](./docs/SPEC.md) for the full specification, architecture details, and type ownership.
+| Export                  | Description                                            |
+| ----------------------- | ------------------------------------------------------ |
+| `ToolRegistry`          | Central tool registration and schema lookup            |
+| `FunctionTool`          | JS function tool with Zod schema validation            |
+| `createFunctionTool`    | Factory for creating function tools                    |
+| `createZodFunctionTool` | Factory with Zod validation and JSON Schema conversion |
+| `OpenAPITool`           | Tool generated from OpenAPI specification              |
+| `zodToJsonSchema`       | Converts Zod schemas to JSON Schema format             |
 
 ## License
 

package/dist/node/index.cjs

@@ -41,6 +41,8 @@ __export(index_exports, {
   globTool: () => globTool,
   grepTool: () => grepTool,
   readTool: () => readTool,
+  webFetchTool: () => webFetchTool,
+  webSearchTool: () => webSearchTool,
   writeTool: () => writeTool,
   zodToJsonSchema: () => zodToJsonSchema
 });
@@ -274,6 +276,12 @@ function convertZodTypeToProperty(typeObj) {
         return { ...innerProperty, ...base };
       }
       throw new Error("ZodDefault is missing innerType; cannot convert to JSON schema.");
+    case "ZodRecord":
+      if (typeDef.valueType) {
+        const valueProperty = convertZodTypeToProperty(typeDef.valueType);
+        return { type: "object", additionalProperties: valueProperty, ...base };
+      }
+      return { type: "object", additionalProperties: { type: "string" }, ...base };
     default:
       throw new Error(`Unsupported Zod type: ${String(typeDef.typeName)}`);
   }
@@ -1010,7 +1018,7 @@ async function writeFileTool(args) {
     await (0, import_promises2.writeFile)(filePath, content, "utf8");
     const result = {
       success: true,
-      output: `Written ${content.length} bytes to ${filePath}`
+      output: `Written ${Buffer.byteLength(content, "utf8")} bytes to ${filePath}`
     };
     return JSON.stringify(result);
   } catch (err) {
@@ -1334,6 +1342,138 @@ var grepTool = createZodFunctionTool(
     return grepFileTool(params);
   }
 );
+
+// src/builtins/web-fetch-tool.ts
+var import_zod7 = require("zod");
+var DEFAULT_TIMEOUT_MS2 = 3e4;
+var MAX_RESPONSE_BYTES = 5e6;
+var WebFetchSchema = import_zod7.z.object({
+  url: import_zod7.z.string().describe("The URL to fetch"),
+  headers: import_zod7.z.record(import_zod7.z.string()).optional().describe("Optional HTTP headers as key-value pairs")
+});
+function htmlToText(html) {
+  return html.replace(/<script[\s\S]*?<\/script>/gi, "").replace(/<style[\s\S]*?<\/style>/gi, "").replace(/<[^>]+>/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&nbsp;/g, " ").replace(/\s+/g, " ").trim();
+}
+async function runWebFetch(args) {
+  const { url, headers } = args;
+  try {
+    new URL(url);
+  } catch {
+    const result = { success: false, output: "", error: `Invalid URL: ${url}` };
+    return JSON.stringify(result);
+  }
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS2);
+    const response = await fetch(url, {
+      headers: {
+        "User-Agent": "Robota-CLI/3.0",
+        ...headers ?? {}
+      },
+      signal: controller.signal,
+      redirect: "follow"
+    });
+    clearTimeout(timeout);
+    if (!response.ok) {
+      const result2 = {
+        success: false,
+        output: "",
+        error: `HTTP ${response.status} ${response.statusText}`
+      };
+      return JSON.stringify(result2);
+    }
+    const contentType = response.headers.get("content-type") ?? "";
+    const buffer = await response.arrayBuffer();
+    if (buffer.byteLength > MAX_RESPONSE_BYTES) {
+      const result2 = {
+        success: false,
+        output: "",
+        error: `Response too large: ${buffer.byteLength} bytes (max ${MAX_RESPONSE_BYTES})`
+      };
+      return JSON.stringify(result2);
+    }
+    let text = new TextDecoder().decode(buffer);
+    if (contentType.includes("html")) {
+      text = htmlToText(text);
+    }
+    const result = { success: true, output: text };
+    return JSON.stringify(result);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const result = { success: false, output: "", error: message };
+    return JSON.stringify(result);
+  }
+}
+var webFetchTool = createZodFunctionTool(
+  "WebFetch",
+  "Fetch a URL and return its content as text. HTML pages are converted to plain text.",
+  WebFetchSchema,
+  async (params) => runWebFetch(params)
+);
+
+// src/builtins/web-search-tool.ts
+var import_zod8 = require("zod");
+var DEFAULT_LIMIT2 = 10;
+var DEFAULT_TIMEOUT_MS3 = 15e3;
+var WebSearchSchema = import_zod8.z.object({
+  query: import_zod8.z.string().describe("The search query"),
+  limit: import_zod8.z.number().optional().describe(`Maximum number of results to return (default: ${DEFAULT_LIMIT2})`)
+});
+async function runWebSearch(args) {
+  const { query, limit = DEFAULT_LIMIT2 } = args;
+  const apiKey = process.env["BRAVE_API_KEY"];
+  if (!apiKey) {
+    const result = {
+      success: false,
+      output: "",
+      error: "Web search requires BRAVE_API_KEY environment variable. Get a free API key at https://brave.com/search/api/ (2,000 queries/month free)."
+    };
+    return JSON.stringify(result);
+  }
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS3);
+    const params = new URLSearchParams({
+      q: query,
+      count: String(Math.min(limit, 20))
+    });
+    const response = await fetch(`https://api.search.brave.com/res/v1/web/search?${params}`, {
+      headers: {
+        Accept: "application/json",
+        "Accept-Encoding": "gzip",
+        "X-Subscription-Token": apiKey
+      },
+      signal: controller.signal
+    });
+    clearTimeout(timeout);
+    if (!response.ok) {
+      const result2 = {
+        success: false,
+        output: "",
+        error: `Brave Search API error: HTTP ${response.status} ${response.statusText}`
+      };
+      return JSON.stringify(result2);
+    }
+    const data = await response.json();
+    const results = (data.web?.results ?? []).map((r) => ({
+      title: r.title,
+      url: r.url,
+      snippet: r.description
+    }));
+    const result = { success: true, output: JSON.stringify(results, null, 2) };
+    return JSON.stringify(result);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const result = { success: false, output: "", error: message };
+    return JSON.stringify(result);
+  }
+}
+var webSearchTool = createZodFunctionTool(
+  "WebSearch",
+  "Search the web and return results with title, URL, and snippet.",
+  WebSearchSchema,
+  async (params) => runWebSearch(params)
+);
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   FunctionTool,
@@ -1347,6 +1487,8 @@ var grepTool = createZodFunctionTool(
   globTool,
   grepTool,
   readTool,
+  webFetchTool,
+  webSearchTool,
   writeTool,
   zodToJsonSchema
 });

package/dist/node/index.d.cts

@@ -86,6 +86,7 @@ interface IZodParseResult {
 interface IZodSchemaDef {
     typeName?: string;
     innerType?: IZodSchema;
+    valueType?: IZodSchema;
     checks?: Array<{
         kind: string;
         value?: TUniversalValue;
@@ -350,4 +351,20 @@ declare const globTool: FunctionTool;
  */
 declare const grepTool: FunctionTool;
 
-export { FunctionTool, type IFunctionToolExecutionMetadata, type IFunctionToolResult, type IFunctionToolValidationOptions, type ISchemaConversionOptions, type IZodParseResult, type IZodSchema, type IZodSchemaDef, OpenAPITool, type TToolResult, ToolRegistry, bashTool, createFunctionTool, createOpenAPITool, createZodFunctionTool, editTool, globTool, grepTool, readTool, writeTool, zodToJsonSchema };
+/**
+ * WebFetchTool — fetch a URL and return its content as text.
+ *
+ * HTML is stripped to plain text for readability. Uses Node.js native fetch.
+ * Output is capped at 30K chars (same as other tools).
+ */
+declare const webFetchTool: FunctionTool;
+
+/**
+ * WebSearchTool — search the web and return results.
+ *
+ * Uses Brave Search API when BRAVE_API_KEY is set.
+ * Returns an error with setup instructions otherwise.
+ */
+declare const webSearchTool: FunctionTool;
+
+export { FunctionTool, type IFunctionToolExecutionMetadata, type IFunctionToolResult, type IFunctionToolValidationOptions, type ISchemaConversionOptions, type IZodParseResult, type IZodSchema, type IZodSchemaDef, OpenAPITool, type TToolResult, ToolRegistry, bashTool, createFunctionTool, createOpenAPITool, createZodFunctionTool, editTool, globTool, grepTool, readTool, webFetchTool, webSearchTool, writeTool, zodToJsonSchema };

package/dist/node/index.d.ts

@@ -86,6 +86,7 @@ interface IZodParseResult {
 interface IZodSchemaDef {
     typeName?: string;
     innerType?: IZodSchema;
+    valueType?: IZodSchema;
     checks?: Array<{
         kind: string;
         value?: TUniversalValue;
@@ -350,4 +351,20 @@ declare const globTool: FunctionTool;
  */
 declare const grepTool: FunctionTool;
 
-export { FunctionTool, type IFunctionToolExecutionMetadata, type IFunctionToolResult, type IFunctionToolValidationOptions, type ISchemaConversionOptions, type IZodParseResult, type IZodSchema, type IZodSchemaDef, OpenAPITool, type TToolResult, ToolRegistry, bashTool, createFunctionTool, createOpenAPITool, createZodFunctionTool, editTool, globTool, grepTool, readTool, writeTool, zodToJsonSchema };
+/**
+ * WebFetchTool — fetch a URL and return its content as text.
+ *
+ * HTML is stripped to plain text for readability. Uses Node.js native fetch.
+ * Output is capped at 30K chars (same as other tools).
+ */
+declare const webFetchTool: FunctionTool;
+
+/**
+ * WebSearchTool — search the web and return results.
+ *
+ * Uses Brave Search API when BRAVE_API_KEY is set.
+ * Returns an error with setup instructions otherwise.
+ */
+declare const webSearchTool: FunctionTool;
+
+export { FunctionTool, type IFunctionToolExecutionMetadata, type IFunctionToolResult, type IFunctionToolValidationOptions, type ISchemaConversionOptions, type IZodParseResult, type IZodSchema, type IZodSchemaDef, OpenAPITool, type TToolResult, ToolRegistry, bashTool, createFunctionTool, createOpenAPITool, createZodFunctionTool, editTool, globTool, grepTool, readTool, webFetchTool, webSearchTool, writeTool, zodToJsonSchema };

package/dist/node/index.js

@@ -226,6 +226,12 @@ function convertZodTypeToProperty(typeObj) {
         return { ...innerProperty, ...base };
       }
       throw new Error("ZodDefault is missing innerType; cannot convert to JSON schema.");
+    case "ZodRecord":
+      if (typeDef.valueType) {
+        const valueProperty = convertZodTypeToProperty(typeDef.valueType);
+        return { type: "object", additionalProperties: valueProperty, ...base };
+      }
+      return { type: "object", additionalProperties: { type: "string" }, ...base };
     default:
       throw new Error(`Unsupported Zod type: ${String(typeDef.typeName)}`);
   }
@@ -962,7 +968,7 @@ async function writeFileTool(args) {
     await writeFile(filePath, content, "utf8");
     const result = {
       success: true,
-      output: `Written ${content.length} bytes to ${filePath}`
+      output: `Written ${Buffer.byteLength(content, "utf8")} bytes to ${filePath}`
     };
     return JSON.stringify(result);
   } catch (err) {
@@ -1286,6 +1292,138 @@ var grepTool = createZodFunctionTool(
     return grepFileTool(params);
   }
 );
+
+// src/builtins/web-fetch-tool.ts
+import { z as z7 } from "zod";
+var DEFAULT_TIMEOUT_MS2 = 3e4;
+var MAX_RESPONSE_BYTES = 5e6;
+var WebFetchSchema = z7.object({
+  url: z7.string().describe("The URL to fetch"),
+  headers: z7.record(z7.string()).optional().describe("Optional HTTP headers as key-value pairs")
+});
+function htmlToText(html) {
+  return html.replace(/<script[\s\S]*?<\/script>/gi, "").replace(/<style[\s\S]*?<\/style>/gi, "").replace(/<[^>]+>/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&nbsp;/g, " ").replace(/\s+/g, " ").trim();
+}
+async function runWebFetch(args) {
+  const { url, headers } = args;
+  try {
+    new URL(url);
+  } catch {
+    const result = { success: false, output: "", error: `Invalid URL: ${url}` };
+    return JSON.stringify(result);
+  }
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS2);
+    const response = await fetch(url, {
+      headers: {
+        "User-Agent": "Robota-CLI/3.0",
+        ...headers ?? {}
+      },
+      signal: controller.signal,
+      redirect: "follow"
+    });
+    clearTimeout(timeout);
+    if (!response.ok) {
+      const result2 = {
+        success: false,
+        output: "",
+        error: `HTTP ${response.status} ${response.statusText}`
+      };
+      return JSON.stringify(result2);
+    }
+    const contentType = response.headers.get("content-type") ?? "";
+    const buffer = await response.arrayBuffer();
+    if (buffer.byteLength > MAX_RESPONSE_BYTES) {
+      const result2 = {
+        success: false,
+        output: "",
+        error: `Response too large: ${buffer.byteLength} bytes (max ${MAX_RESPONSE_BYTES})`
+      };
+      return JSON.stringify(result2);
+    }
+    let text = new TextDecoder().decode(buffer);
+    if (contentType.includes("html")) {
+      text = htmlToText(text);
+    }
+    const result = { success: true, output: text };
+    return JSON.stringify(result);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const result = { success: false, output: "", error: message };
+    return JSON.stringify(result);
+  }
+}
+var webFetchTool = createZodFunctionTool(
+  "WebFetch",
+  "Fetch a URL and return its content as text. HTML pages are converted to plain text.",
+  WebFetchSchema,
+  async (params) => runWebFetch(params)
+);
+
+// src/builtins/web-search-tool.ts
+import { z as z8 } from "zod";
+var DEFAULT_LIMIT2 = 10;
+var DEFAULT_TIMEOUT_MS3 = 15e3;
+var WebSearchSchema = z8.object({
+  query: z8.string().describe("The search query"),
+  limit: z8.number().optional().describe(`Maximum number of results to return (default: ${DEFAULT_LIMIT2})`)
+});
+async function runWebSearch(args) {
+  const { query, limit = DEFAULT_LIMIT2 } = args;
+  const apiKey = process.env["BRAVE_API_KEY"];
+  if (!apiKey) {
+    const result = {
+      success: false,
+      output: "",
+      error: "Web search requires BRAVE_API_KEY environment variable. Get a free API key at https://brave.com/search/api/ (2,000 queries/month free)."
+    };
+    return JSON.stringify(result);
+  }
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS3);
+    const params = new URLSearchParams({
+      q: query,
+      count: String(Math.min(limit, 20))
+    });
+    const response = await fetch(`https://api.search.brave.com/res/v1/web/search?${params}`, {
+      headers: {
+        Accept: "application/json",
+        "Accept-Encoding": "gzip",
+        "X-Subscription-Token": apiKey
+      },
+      signal: controller.signal
+    });
+    clearTimeout(timeout);
+    if (!response.ok) {
+      const result2 = {
+        success: false,
+        output: "",
+        error: `Brave Search API error: HTTP ${response.status} ${response.statusText}`
+      };
+      return JSON.stringify(result2);
+    }
+    const data = await response.json();
+    const results = (data.web?.results ?? []).map((r) => ({
+      title: r.title,
+      url: r.url,
+      snippet: r.description
+    }));
+    const result = { success: true, output: JSON.stringify(results, null, 2) };
+    return JSON.stringify(result);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const result = { success: false, output: "", error: message };
+    return JSON.stringify(result);
+  }
+}
+var webSearchTool = createZodFunctionTool(
+  "WebSearch",
+  "Search the web and return results with title, URL, and snippet.",
+  WebSearchSchema,
+  async (params) => runWebSearch(params)
+);
 export {
   FunctionTool,
   OpenAPITool,
@@ -1298,6 +1436,8 @@ export {
   globTool,
   grepTool,
   readTool,
+  webFetchTool,
+  webSearchTool,
   writeTool,
   zodToJsonSchema
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robota-sdk/agent-tools",
-  "version": "3.0.0-beta.1",
+  "version": "3.0.0-beta.11",
   "description": "Tool registry and implementations for Robota SDK",
   "type": "module",
   "main": "dist/node/index.js",
@@ -26,7 +26,7 @@
     "zod": "^3.24.0"
   },
   "peerDependencies": {
-    "@robota-sdk/agent-core": "3.0.0-beta.1"
+    "@robota-sdk/agent-core": "3.0.0-beta.11"
   },
   "devDependencies": {
     "openapi-types": "^12.1.3",
@@ -34,7 +34,7 @@
     "tsup": "^8.0.1",
     "typescript": "^5.3.3",
     "vitest": "^1.6.1",
-    "@robota-sdk/agent-core": "3.0.0-beta.1"
+    "@robota-sdk/agent-core": "3.0.0-beta.11"
   },
   "license": "MIT",
   "publishConfig": {