@robota-sdk/agent-tools 3.0.0-beta.66 → 3.0.0-beta.68

package/dist/node/index.js

@@ -1,10 +1,11 @@
 import { chmod, mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
-import { basename, dirname, isAbsolute, join, posix, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, posix, resolve, sep } from "node:path";
 import { ToolExecutionError, ValidationError, logger } from "@robota-sdk/agent-core";
 import { spawn } from "node:child_process";
 import { z } from "zod";
 import { randomBytes } from "node:crypto";
 import fg from "fast-glob";
+import pLimit from "p-limit";
 //#region src/sandbox/e2b-sandbox-client.ts
 var E2BSandboxClient = class {
 	sandbox;
@@ -638,281 +639,6 @@ function createZodFunctionTool(name, description, zodSchema, fn) {
 	return new FunctionTool(schema, wrappedFn);
 }
 //#endregion
-//#region src/implementations/openapi-schema-converter.ts
-/**
-* HTTP methods to search when scanning OpenAPI paths
-*/
-const HTTP_METHODS = [
-	"get",
-	"post",
-	"put",
-	"delete",
-	"patch",
-	"head",
-	"options"
-];
-/**
-* Find an operation in the OpenAPI spec by operationId
-*/
-function findOperation(apiSpec, operationId) {
-	for (const [path, pathItem] of Object.entries(apiSpec.paths || {})) {
-		if (!pathItem) continue;
-		for (const method of HTTP_METHODS) {
-			const operation = pathItem[method];
-			if (operation?.operationId === operationId) return {
-				method,
-				path,
-				operation
-			};
-		}
-	}
-}
-/**
-* Map OpenAPI type to JSON schema type
-*/
-function mapOpenAPIType(type) {
-	switch (type) {
-		case "string": return "string";
-		case "number": return "number";
-		case "integer": return "integer";
-		case "boolean": return "boolean";
-		case "array": return "array";
-		case "object": return "object";
-		default: return "string";
-	}
-}
-/**
-* Convert OpenAPI schema to parameter schema
-*/
-function convertOpenAPISchemaToParameterSchema(schema) {
-	if ("$ref" in schema) return { type: "object" };
-	const result = { type: mapOpenAPIType(schema.type) };
-	if (schema.description) result.description = schema.description;
-	if (schema.enum) result.enum = schema.enum;
-	if (schema.minimum !== void 0) result.minimum = schema.minimum;
-	if (schema.maximum !== void 0) result.maximum = schema.maximum;
-	if (schema.pattern) result.pattern = schema.pattern;
-	if (schema.format) result.format = schema.format;
-	if (schema.default !== void 0) result.default = schema.default;
-	if (schema.type === "array" && schema.items) result.items = convertOpenAPISchemaToParameterSchema(schema.items);
-	if (schema.type === "object" && schema.properties) {
-		result.properties = {};
-		for (const [propName, propSchema] of Object.entries(schema.properties)) result.properties[propName] = convertOpenAPISchemaToParameterSchema(propSchema);
-		if (schema.required && schema.required.length > 0) result.required = schema.required;
-	}
-	return result;
-}
-/**
-* Convert OpenAPI parameter object to tool parameter schema
-*/
-function convertOpenAPIParamToSchema(param) {
-	const schema = param.schema;
-	return convertOpenAPISchemaToParameterSchema(schema);
-}
-/**
-* Create a tool schema from an OpenAPI operation specification
-*/
-function createSchemaFromOperation(operationId, opSpec) {
-	const properties = {};
-	const required = [];
-	const params = opSpec.parameters || [];
-	for (const param of params) {
-		properties[param.name] = convertOpenAPIParamToSchema(param);
-		if (param.required) required.push(param.name);
-	}
-	if (opSpec.requestBody) {
-		const jsonContent = opSpec.requestBody.content?.["application/json"];
-		if (jsonContent?.schema) {
-			const bodySchema = convertOpenAPISchemaToParameterSchema(jsonContent.schema);
-			if (bodySchema.type === "object" && bodySchema.properties) {
-				Object.assign(properties, bodySchema.properties);
-				const schemaWithRequired = bodySchema;
-				if (schemaWithRequired.required) required.push(...schemaWithRequired.required);
-			}
-		}
-	}
-	const schemaParams = {
-		type: "object",
-		properties
-	};
-	if (required.length > 0) schemaParams.required = required;
-	return {
-		name: operationId,
-		description: opSpec.summary || opSpec.description || `OpenAPI operation: ${operationId}`,
-		parameters: schemaParams
-	};
-}
-//#endregion
-//#region src/implementations/openapi-tool.ts
-/**
-* OpenAPI tool implementation
-* Executes API calls based on OpenAPI 3.0 specifications
-*
-* Implements ITool without extending AbstractTool to avoid
-* circular runtime dependency (tools → agents → tools).
-*/
-var OpenAPITool = class {
-	schema;
-	apiSpec;
-	operationId;
-	baseURL;
-	config;
-	eventService;
-	constructor(config) {
-		this.config = config;
-		if (typeof config.spec !== "object" || config.spec === null || typeof config.spec.openapi !== "string" || typeof config.spec.paths !== "object") throw new Error("Invalid OpenAPI spec: must contain \"openapi\" (string) and \"paths\" (object) fields");
-		this.apiSpec = config.spec;
-		this.operationId = config.operationId;
-		this.baseURL = config.baseURL;
-		this.schema = this.createSchemaFromOpenAPI();
-	}
-	/**
-	* Execute the OpenAPI tool
-	*/
-	async execute(parameters, context) {
-		const toolName = this.schema.name;
-		const validation = this.validateParameters(parameters);
-		if (!validation.isValid) throw new ValidationError(`Invalid parameters for OpenAPI tool "${toolName}": ${validation.errors.join(", ")}`);
-		try {
-			const startTime = Date.now();
-			return {
-				success: true,
-				data: await this.executeAPICall(parameters, context),
-				metadata: {
-					executionTime: Date.now() - startTime,
-					toolName,
-					operationId: this.operationId,
-					baseURL: this.baseURL
-				}
-			};
-		} catch (error) {
-			if (error instanceof ToolExecutionError || error instanceof ValidationError) throw error;
-			const safeError = error instanceof Error ? error : new Error(String(error));
-			throw new ToolExecutionError(`OpenAPI tool execution failed: ${safeError.message}`, toolName, safeError, {
-				operationId: this.operationId,
-				baseURL: this.baseURL,
-				parametersCount: Object.keys(parameters).length
-			});
-		}
-	}
-	/**
-	* Validate tool parameters
-	*/
-	validate(parameters) {
-		return this.validateParameters(parameters).isValid;
-	}
-	/**
-	* Validate tool parameters with detailed result
-	*/
-	validateParameters(parameters) {
-		const required = this.schema.parameters.required || [];
-		const errors = [];
-		for (const field of required) if (!(field in parameters)) errors.push(`Missing required parameter: ${field}`);
-		return {
-			isValid: errors.length === 0,
-			errors
-		};
-	}
-	/**
-	* Get tool name
-	*/
-	getName() {
-		return this.schema.name;
-	}
-	/**
-	* Set EventService for post-construction injection.
-	*/
-	setEventService(eventService) {
-		this.eventService = eventService;
-	}
-	/**
-	* Get tool description
-	*/
-	getDescription() {
-		return this.schema.description;
-	}
-	/**
-	* Execute the actual API call
-	* @private
-	*/
-	async executeAPICall(parameters, _context) {
-		const operation = findOperation(this.apiSpec, this.operationId);
-		if (!operation) throw new Error(`Operation ${this.operationId} not found in OpenAPI spec`);
-		this.buildRequestConfig(operation, parameters);
-		throw new Error("Not implemented: actual API execution is not yet available");
-	}
-	/**
-	* Build HTTP request configuration from OpenAPI operation and parameters
-	*/
-	buildRequestConfig(opInfo, parameters) {
-		const { method, path, operation } = opInfo;
-		let url = this.baseURL + path;
-		const headers = {};
-		let body;
-		const params = operation.parameters || [];
-		for (const param of params) {
-			const value = parameters[param.name];
-			if (value === void 0 && param.required) throw new Error(`Required parameter ${param.name} is missing`);
-			if (value !== void 0) switch (param.in) {
-				case "path":
-					url = url.replace(`{${param.name}}`, encodeURIComponent(String(value)));
-					break;
-				case "query": {
-					const separator = url.includes("?") ? "&" : "?";
-					url += `${separator}${param.name}=${encodeURIComponent(String(value))}`;
-					break;
-				}
-				case "header":
-					headers[param.name] = String(value);
-					break;
-			}
-		}
-		if ([
-			"post",
-			"put",
-			"patch"
-		].includes(method) && operation.requestBody) {
-			if (operation.requestBody.content?.["application/json"]) {
-				headers["Content-Type"] = "application/json";
-				const bodyParams = {};
-				for (const [key, value] of Object.entries(parameters)) if (!params.some((p) => p.name === key)) bodyParams[key] = value;
-				body = JSON.stringify(bodyParams);
-			}
-		}
-		if (this.config.auth) switch (this.config.auth.type) {
-			case "bearer":
-				headers["Authorization"] = `Bearer ${this.config.auth.token}`;
-				break;
-			case "apiKey": {
-				const headerName = this.config.auth.header || "X-API-Key";
-				headers[headerName] = this.config.auth.apiKey || "";
-				break;
-			}
-		}
-		const result = {
-			method,
-			url,
-			headers
-		};
-		if (body !== void 0) result.body = body;
-		return result;
-	}
-	/**
-	* Create tool schema from OpenAPI operation specification
-	*/
-	createSchemaFromOpenAPI() {
-		const operation = findOperation(this.apiSpec, this.operationId);
-		if (!operation) throw new Error(`[STRICT-POLICY][EMITTER-CONTRACT] OpenAPI operation not found: ${this.operationId}. Emitter contract must provide a valid operationId present in the OpenAPI document.`);
-		return createSchemaFromOperation(this.operationId, operation.operation);
-	}
-};
-/**
-* Factory function to create OpenAPI tools from specification
-*/
-function createOpenAPITool(config) {
-	return new OpenAPITool(config);
-}
-//#endregion
 //#region src/builtins/bash-tool.ts
 /**
 * BashTool — execute shell commands via child_process.spawn
@@ -932,7 +658,8 @@ const BashSchema = z.object({
 * Resolves with the TToolResult JSON string.
 */
 async function runBash(args, options = {}) {
-	const { command, timeout = DEFAULT_TIMEOUT_MS$2, workingDirectory } = args;
+	const { command, timeout: rawTimeout = DEFAULT_TIMEOUT_MS$2, workingDirectory } = args;
+	const timeout = Math.min(rawTimeout, 6e5);
 	if (options.sandboxClient) try {
 		const sandboxResult = await options.sandboxClient.run(command, {
 			timeoutMs: timeout,
@@ -1028,6 +755,25 @@ function createBashTool(options = {}) {
 */
 const bashTool = createBashTool();
 //#endregion
+//#region src/builtins/path-guard.ts
+/**
+* Returns a JSON-serialized TToolResult error when filePath is outside cwd.
+* Returns undefined when the path is within cwd or cwd is not set.
+*/
+function checkPathWithinCwd(filePath, cwd) {
+	if (cwd === void 0) return void 0;
+	const resolved = resolve(filePath);
+	const cwdResolved = resolve(cwd);
+	if (resolved !== cwdResolved && !resolved.startsWith(cwdResolved + sep)) {
+		const result = {
+			success: false,
+			output: "",
+			error: `Access denied: "${filePath}" is outside the working directory`
+		};
+		return JSON.stringify(result);
+	}
+}
+//#endregion
 //#region src/builtins/read-tool.ts
 /**
 * ReadTool — read a file and return its contents with line numbers (cat -n style).
@@ -1087,6 +833,8 @@ async function readFileTool(args, options = {}) {
 		};
 		return JSON.stringify(result);
 	}
+	const pathError = checkPathWithinCwd(filePath, options.cwd);
+	if (pathError !== void 0) return pathError;
 	let fileStats;
 	try {
 		fileStats = await stat(filePath);
@@ -1185,6 +933,10 @@ const WriteSchema = z.object({
 });
 async function writeFileTool(args, options = {}) {
 	const { filePath, content } = args;
+	if (!options.sandboxClient) {
+		const pathError = checkPathWithinCwd(filePath, options.cwd);
+		if (pathError !== void 0) return pathError;
+	}
 	try {
 		if (options.sandboxClient) await options.sandboxClient.writeFile(filePath, content);
 		else await atomicWriteUtf8File(filePath, content);
@@ -1230,6 +982,10 @@ const EditSchema = z.object({
 });
 async function editFileTool(args, options = {}) {
 	const { filePath, oldString, newString, replaceAll = false } = args;
+	if (!options.sandboxClient) {
+		const pathError = checkPathWithinCwd(filePath, options.cwd);
+		if (pathError !== void 0) return pathError;
+	}
 	let content;
 	try {
 		content = options.sandboxClient ? await options.sandboxClient.readFile(filePath) : await readFile(filePath, "utf8");
@@ -1326,7 +1082,8 @@ async function globFileTool(args) {
 		};
 		return JSON.stringify(result);
 	}
-	const withMtime = await Promise.all(matches.map(async (p) => {
+	const limit = pLimit(100);
+	const withMtime = await Promise.all(matches.map((p) => limit(async () => {
 		const absPath = resolve(cwd, p);
 		try {
 			return {
@@ -1339,7 +1096,7 @@ async function globFileTool(args) {
 				mtime: 0
 			};
 		}
-	}));
+	})));
 	withMtime.sort((a, b) => b.mtime - a.mtime);
 	const maxResults = args.limit ?? DEFAULT_MAX_RESULTS;
 	const totalMatches = withMtime.length;
@@ -1510,6 +1267,17 @@ const WebFetchSchema = z.object({
 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();
 }
+function classifyFetchError(err) {
+	if (!(err instanceof Error)) return String(err);
+	if (err.name === "AbortError") return `Request timed out after ${DEFAULT_TIMEOUT_MS$1 / 1e3}s. The server did not respond in time.`;
+	const code = err.code;
+	if (code === "ENOTFOUND" || code === "EAI_AGAIN") return `Network error: DNS resolution failed for this host. The URL may be incorrect or the host does not exist. Do not retry with the same URL.`;
+	if (code === "ECONNREFUSED") return `Network error: Connection refused. The server is not accepting connections at this address. Do not retry with the same URL.`;
+	if (code === "ECONNRESET") return `Network error: Connection was reset by the server. The server may be temporarily unavailable.`;
+	if (code === "ETIMEDOUT") return `Network error: Connection timed out. The server is not reachable within the expected time.`;
+	if (code === "CERT_HAS_EXPIRED" || code === "UNABLE_TO_VERIFY_LEAF_SIGNATURE") return `Network error: SSL certificate error (${code}). The server's certificate is invalid. Do not retry with the same URL.`;
+	return `Network error: ${err.message} Check that the URL is correct and the server is reachable.`;
+}
 async function runWebFetch(args) {
 	const { url, headers } = args;
 	try {
@@ -1518,7 +1286,7 @@ async function runWebFetch(args) {
 		const result = {
 			success: false,
 			output: "",
-			error: `Invalid URL: ${url}`
+			error: `Invalid URL: "${url}". Fix the URL format before retrying.`
 		};
 		return JSON.stringify(result);
 	}
@@ -1535,10 +1303,11 @@ async function runWebFetch(args) {
 		});
 		clearTimeout(timeout);
 		if (!response.ok) {
+			const retryHint = response.status >= 500 ? " The server is temporarily unavailable — retrying may help." : " Do not retry with the same URL.";
 			const result = {
 				success: false,
 				output: "",
-				error: `HTTP ${response.status} ${response.statusText}`
+				error: `HTTP ${response.status} ${response.statusText}.${retryHint}`
 			};
 			return JSON.stringify(result);
 		}
@@ -1548,7 +1317,7 @@ async function runWebFetch(args) {
 			const result = {
 				success: false,
 				output: "",
-				error: `Response too large: ${buffer.byteLength} bytes (max ${MAX_RESPONSE_BYTES})`
+				error: `Response too large: ${buffer.byteLength} bytes (max ${MAX_RESPONSE_BYTES}). Consider fetching a more specific URL or a paginated endpoint.`
 			};
 			return JSON.stringify(result);
 		}
@@ -1562,7 +1331,7 @@ async function runWebFetch(args) {
 		const result = {
 			success: false,
 			output: "",
-			error: err instanceof Error ? err.message : String(err)
+			error: classifyFetchError(err)
 		};
 		return JSON.stringify(result);
 	}
@@ -1635,6 +1404,6 @@ async function runWebSearch(args) {
 }
 const webSearchTool = createZodFunctionTool("WebSearch", "Search the web and return results with title, URL, and snippet.", WebSearchSchema, async (params) => runWebSearch(params));
 //#endregion
-export { E2BSandboxClient, FunctionTool, InMemorySandboxClient, OpenAPITool, ToolRegistry, applyWorkspaceManifest, bashTool, createBashTool, createEditTool, createFunctionTool, createOpenAPITool, createReadTool, createWriteTool, createZodFunctionTool, editTool, globTool, grepTool, readTool, validateWorkspaceManifestPath, webFetchTool, webSearchTool, writeTool, zodToJsonSchema };
+export { E2BSandboxClient, FunctionTool, InMemorySandboxClient, ToolRegistry, applyWorkspaceManifest, bashTool, createBashTool, createEditTool, createFunctionTool, createReadTool, createWriteTool, createZodFunctionTool, editTool, globTool, grepTool, readTool, validateWorkspaceManifestPath, webFetchTool, webSearchTool, writeTool, zodToJsonSchema };
 
 //# sourceMappingURL=index.js.map