@robota-sdk/agent-tools 3.0.0-beta.6 → 3.0.0-beta.60

package/README.md

@@ -46,16 +46,20 @@ const agent = new Robota({
 
 ## Built-in Tools (8)
 
-| 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          | Tool Name | Description                                      |
+| --------------- | --------- | ------------------------------------------------ |
+| `bashTool`      | Bash      | Execute shell commands via `child_process.spawn` |
+| `readTool`      | Read      | Read file contents with line numbers (cat -n)    |
+| `writeTool`     | Write     | Write content to a file (creates parent dirs)    |
+| `editTool`      | Edit      | Replace a specific string in a file              |
+| `globTool`      | Glob      | Find files matching a glob pattern (fast-glob)   |
+| `grepTool`      | Grep      | Search file contents with regex patterns         |
+| `webFetchTool`  | WebFetch  | Fetch URL content (HTML-to-text conversion)      |
+| `webSearchTool` | WebSearch | Web search via Brave Search API                  |
+
+## Edit and Write Safety
+
+Recent file tool updates keep write/edit behavior atomic and make Edit tool results easier for higher layers to display. Atomic replacements preserve existing target mode bits, so executable scripts remain executable after Write or Edit updates. The Edit tool returns line metadata for changed regions, allowing the CLI to render concise context hunks instead of dumping full files or opaque summaries.
 
 ## Tool Infrastructure
 
@@ -66,7 +70,31 @@ const agent = new Robota({
 | `createFunctionTool`    | Factory for creating function tools                    |
 | `createZodFunctionTool` | Factory with Zod validation and JSON Schema conversion |
 | `OpenAPITool`           | Tool generated from OpenAPI specification              |
+| `createOpenAPITool`     | Factory for creating OpenAPI tools                     |
 | `zodToJsonSchema`       | Converts Zod schemas to JSON Schema format             |
+| `TToolResult`           | Result type for built-in CLI tool invocations          |
+
+## TToolResult Shape
+
+```typescript
+interface TToolResult {
+  success: boolean;
+  output: string;
+  error?: string;
+  exitCode?: number;
+  startLine?: number; // Start line number of the edit in the original file (Edit tool only)
+}
+```
+
+`TToolResult` is the inner result type used by built-in tools. It is serialized to JSON and placed inside the `IToolResult.data` field before being returned to the Robota execution loop.
+
+## Dependencies
+
+| Dependency               | Kind | Purpose                                                |
+| ------------------------ | ---- | ------------------------------------------------------ |
+| `@robota-sdk/agent-core` | Peer | Abstract tool base class, tool interfaces, event types |
+| `fast-glob`              | Prod | High-performance glob matching for the Glob tool       |
+| `zod`                    | Prod | Schema validation for function tool parameters         |
 
 ## License
 

package/dist/node/index.cjs

@@ -215,7 +215,9 @@ function zodToJsonSchema(schema, options = {}) {
     type: "object",
     properties,
     required,
-    ...options.allowAdditionalProperties && { additionalProperties: true }
+    ...(options.allowAdditionalProperties || schemaDef.unknownKeys === "passthrough") && {
+      additionalProperties: true
+    }
   };
 }
 function convertZodTypeToProperty(typeObj) {
@@ -294,6 +296,100 @@ function isRequiredField(typeObj) {
   return typeDef.typeName !== "ZodOptional" && typeDef.typeName !== "ZodNullable" && typeDef.typeName !== "ZodDefault";
 }
 
+// src/implementations/function-tool/parameter-validator.ts
+function validateParameterType(key, value, schema) {
+  const expectedType = schema["type"];
+  switch (expectedType) {
+    case "string":
+      if (typeof value !== "string") {
+        return `Parameter "${key}" must be a string, got ${typeof value}`;
+      }
+      break;
+    case "number":
+      if (typeof value !== "number" || isNaN(value)) {
+        return `Parameter "${key}" must be a number, got ${typeof value}`;
+      }
+      break;
+    case "boolean":
+      if (typeof value !== "boolean") {
+        return `Parameter "${key}" must be a boolean, got ${typeof value}`;
+      }
+      break;
+    case "array":
+      if (!Array.isArray(value)) {
+        return `Parameter "${key}" must be an array, got ${typeof value}`;
+      }
+      if (schema.items) {
+        for (let i = 0; i < value.length; i++) {
+          const itemError = validateParameterType(`${key}[${i}]`, value[i], schema.items);
+          if (itemError) {
+            return itemError;
+          }
+        }
+      }
+      break;
+    case "object":
+      if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return `Parameter "${key}" must be an object, got ${typeof value}`;
+      }
+      break;
+  }
+  if (schema.enum && schema.enum.length > 0) {
+    const enumValues = schema.enum;
+    let isValidEnum = false;
+    for (const enumValue of enumValues) {
+      if (value === enumValue) {
+        isValidEnum = true;
+        break;
+      }
+    }
+    if (!isValidEnum) {
+      return `Parameter "${key}" must be one of: ${enumValues.join(", ")}, got ${value}`;
+    }
+  }
+  return void 0;
+}
+function getValidationErrors(parameters, schemaRequired, schemaProperties, additionalProperties) {
+  const errors = [];
+  for (const field of schemaRequired) {
+    if (!(field in parameters)) {
+      errors.push(`Missing required parameter: ${field}`);
+    }
+  }
+  for (const [key, value] of Object.entries(parameters)) {
+    const paramSchema = schemaProperties[key];
+    if (!paramSchema) {
+      if (additionalProperties === true) {
+        continue;
+      }
+      if (additionalProperties && typeof additionalProperties === "object") {
+        const additionalTypeError = validateParameterType(key, value, additionalProperties);
+        if (additionalTypeError) errors.push(additionalTypeError);
+        continue;
+      }
+      errors.push(`Unknown parameter: ${key}`);
+      continue;
+    }
+    const typeError = validateParameterType(key, value, paramSchema);
+    if (typeError) {
+      errors.push(typeError);
+    }
+  }
+  return errors;
+}
+function validateToolParameters(parameters, schemaRequired, schemaProperties, additionalProperties) {
+  const errors = getValidationErrors(
+    parameters,
+    schemaRequired,
+    schemaProperties,
+    additionalProperties
+  );
+  return {
+    isValid: errors.length === 0,
+    errors
+  };
+}
+
 // src/implementations/function-tool.ts
 var FunctionTool = class {
   schema;
@@ -324,7 +420,12 @@ var FunctionTool = class {
   async execute(parameters, context) {
     const toolName = this.schema.name;
     if (!this.validate(parameters)) {
-      const errors = this.getValidationErrors(parameters);
+      const errors = getValidationErrors(
+        parameters,
+        this.schema.parameters.required || [],
+        this.schema.parameters.properties || {},
+        this.schema.parameters.additionalProperties
+      );
       throw new import_agent_core3.ValidationError(`Invalid parameters for tool "${toolName}": ${errors.join(", ")}`);
     }
     const startTime = Date.now();
@@ -360,17 +461,23 @@ var FunctionTool = class {
    * Validate parameters (simple boolean result)
    */
   validate(parameters) {
-    return this.getValidationErrors(parameters).length === 0;
+    return getValidationErrors(
+      parameters,
+      this.schema.parameters.required || [],
+      this.schema.parameters.properties || {},
+      this.schema.parameters.additionalProperties
+    ).length === 0;
   }
   /**
    * Validate tool parameters with detailed result
    */
   validateParameters(parameters) {
-    const errors = this.getValidationErrors(parameters);
-    return {
-      isValid: errors.length === 0,
-      errors
-    };
+    return validateToolParameters(
+      parameters,
+      this.schema.parameters.required || [],
+      this.schema.parameters.properties || {},
+      this.schema.parameters.additionalProperties
+    );
   }
   /**
    * Get tool description
@@ -378,86 +485,6 @@ var FunctionTool = class {
   getDescription() {
     return this.schema.description;
   }
-  /**
-   * Get detailed validation errors
-   */
-  getValidationErrors(parameters) {
-    const errors = [];
-    const required = this.schema.parameters.required || [];
-    const properties = this.schema.parameters.properties || {};
-    for (const field of required) {
-      if (!(field in parameters)) {
-        errors.push(`Missing required parameter: ${field}`);
-      }
-    }
-    for (const [key, value] of Object.entries(parameters)) {
-      const paramSchema = properties[key];
-      if (!paramSchema) {
-        errors.push(`Unknown parameter: ${key}`);
-        continue;
-      }
-      const typeError = this.validateParameterType(key, value, paramSchema);
-      if (typeError) {
-        errors.push(typeError);
-      }
-    }
-    return errors;
-  }
-  /**
-   * Validate individual parameter type
-   */
-  validateParameterType(key, value, schema) {
-    const expectedType = schema["type"];
-    switch (expectedType) {
-      case "string":
-        if (typeof value !== "string") {
-          return `Parameter "${key}" must be a string, got ${typeof value}`;
-        }
-        break;
-      case "number":
-        if (typeof value !== "number" || isNaN(value)) {
-          return `Parameter "${key}" must be a number, got ${typeof value}`;
-        }
-        break;
-      case "boolean":
-        if (typeof value !== "boolean") {
-          return `Parameter "${key}" must be a boolean, got ${typeof value}`;
-        }
-        break;
-      case "array":
-        if (!Array.isArray(value)) {
-          return `Parameter "${key}" must be an array, got ${typeof value}`;
-        }
-        if (schema.items) {
-          for (let i = 0; i < value.length; i++) {
-            const itemError = this.validateParameterType(`${key}[${i}]`, value[i], schema.items);
-            if (itemError) {
-              return itemError;
-            }
-          }
-        }
-        break;
-      case "object":
-        if (typeof value !== "object" || value === null || Array.isArray(value)) {
-          return `Parameter "${key}" must be an object, got ${typeof value}`;
-        }
-        break;
-    }
-    if (schema.enum && schema.enum.length > 0) {
-      const enumValues = schema.enum;
-      let isValidEnum = false;
-      for (const enumValue of enumValues) {
-        if (value === enumValue) {
-          isValidEnum = true;
-          break;
-        }
-      }
-      if (!isValidEnum) {
-        return `Parameter "${key}" must be one of: ${enumValues.join(", ")}, got ${value}`;
-      }
-    }
-    return void 0;
-  }
   /**
    * Validate constructor inputs
    */
@@ -501,6 +528,132 @@ function createZodFunctionTool(name, description, zodSchema, fn) {
 
 // src/implementations/openapi-tool.ts
 var import_agent_core4 = require("@robota-sdk/agent-core");
+
+// src/implementations/openapi-schema-converter.ts
+var HTTP_METHODS = [
+  "get",
+  "post",
+  "put",
+  "delete",
+  "patch",
+  "head",
+  "options"
+];
+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 };
+      }
+    }
+  }
+  return void 0;
+}
+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";
+  }
+}
+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;
+}
+function convertOpenAPIParamToSchema(param) {
+  const schema = param.schema;
+  return convertOpenAPISchemaToParameterSchema(schema);
+}
+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 requestBody = opSpec.requestBody;
+    const jsonContent = 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
+  };
+}
+
+// src/implementations/openapi-tool.ts
 var OpenAPITool = class {
   schema;
   apiSpec;
@@ -607,36 +760,13 @@ var OpenAPITool = class {
    * @private
    */
   async executeAPICall(parameters, _context) {
-    const operation = this.findOperation();
+    const operation = findOperation(this.apiSpec, this.operationId);
     if (!operation) {
       throw new Error(`Operation ${this.operationId} not found in OpenAPI spec`);
     }
-    const requestConfig = this.buildRequestConfig(operation, parameters);
+    this.buildRequestConfig(operation, parameters);
     throw new Error("Not implemented: actual API execution is not yet available");
   }
-  /**
-   * Find the operation in the OpenAPI specification
-   */
-  findOperation() {
-    for (const [path, pathItem] of Object.entries(this.apiSpec.paths || {})) {
-      if (!pathItem) continue;
-      for (const method of [
-        "get",
-        "post",
-        "put",
-        "delete",
-        "patch",
-        "head",
-        "options"
-      ]) {
-        const operation = pathItem[method];
-        if (operation?.operationId === this.operationId) {
-          return { method, path, operation };
-        }
-      }
-    }
-    return void 0;
-  }
   /**
    * Build HTTP request configuration from OpenAPI operation and parameters
    */
@@ -708,121 +838,13 @@ var OpenAPITool = class {
    * Create tool schema from OpenAPI operation specification
    */
   createSchemaFromOpenAPI() {
-    const operation = this.findOperation();
+    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.`
       );
     }
-    const { operation: opSpec } = operation;
-    const properties = {};
-    const required = [];
-    const params = opSpec.parameters || [];
-    for (const param of params) {
-      properties[param.name] = this.convertOpenAPIParamToSchema(param);
-      if (param.required) {
-        required.push(param.name);
-      }
-    }
-    if (opSpec.requestBody) {
-      const requestBody = opSpec.requestBody;
-      const jsonContent = requestBody.content?.["application/json"];
-      if (jsonContent?.schema) {
-        const bodySchema = this.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: this.operationId,
-      description: opSpec.summary || opSpec.description || `OpenAPI operation: ${this.operationId}`,
-      parameters: schemaParams
-    };
-  }
-  /**
-   * Convert OpenAPI parameter to tool parameter schema
-   */
-  convertOpenAPIParamToSchema(param) {
-    const schema = param.schema;
-    return this.convertOpenAPISchemaToParameterSchema(schema);
-  }
-  /**
-   * Convert OpenAPI schema to parameter schema
-   */
-  convertOpenAPISchemaToParameterSchema(schema) {
-    if ("$ref" in schema) {
-      return { type: "object" };
-    }
-    const result = {
-      type: this.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 = this.convertOpenAPISchemaToParameterSchema(schema.items);
-    }
-    if (schema.type === "object" && schema.properties) {
-      result.properties = {};
-      for (const [propName, propSchema] of Object.entries(schema.properties)) {
-        result.properties[propName] = this.convertOpenAPISchemaToParameterSchema(propSchema);
-      }
-      if (schema.required && schema.required.length > 0) {
-        result.required = schema.required;
-      }
-    }
-    return result;
-  }
-  /**
-   * Map OpenAPI type to JSON schema type
-   */
-  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";
-    }
+    return createSchemaFromOperation(this.operationId, operation.operation);
   }
 };
 function createOpenAPITool(config) {
@@ -859,6 +881,11 @@ async function runBash(args) {
     const timer = setTimeout(() => {
       timedOut = true;
       child.kill("SIGTERM");
+      settle({
+        success: false,
+        output: Buffer.concat(stdoutChunks).toString("utf8"),
+        error: `Command timed out after ${timeout}ms`
+      });
     }, timeout);
     function settle(result) {
       if (settled) return;
@@ -1004,9 +1031,51 @@ var readTool = createZodFunctionTool(
 );
 
 // src/builtins/write-tool.ts
+var import_zod3 = require("zod");
+
+// src/builtins/atomic-file-write.ts
+var import_node_crypto = require("crypto");
 var import_promises2 = require("fs/promises");
 var import_node_path = require("path");
-var import_zod3 = require("zod");
+var TEMP_RANDOM_BYTES = 6;
+var PRESERVED_MODE_BITS = 4095;
+var MISSING_FILE_ERROR_CODE = "ENOENT";
+function createTempFilePath(filePath) {
+  const dir = (0, import_node_path.dirname)(filePath);
+  const name = (0, import_node_path.basename)(filePath);
+  const suffix = (0, import_node_crypto.randomBytes)(TEMP_RANDOM_BYTES).toString("hex");
+  return (0, import_node_path.join)(dir, `.${name}.robota-tmp-${process.pid}-${Date.now()}-${suffix}`);
+}
+async function readExistingMode(filePath) {
+  try {
+    const fileStats = await (0, import_promises2.stat)(filePath);
+    return fileStats.mode & PRESERVED_MODE_BITS;
+  } catch (error) {
+    if (error instanceof Error && hasErrorCode(error, MISSING_FILE_ERROR_CODE)) return void 0;
+    throw error;
+  }
+}
+function hasErrorCode(error, code) {
+  return "code" in error && error.code === code;
+}
+async function atomicWriteUtf8File(filePath, content) {
+  const dir = (0, import_node_path.dirname)(filePath);
+  await (0, import_promises2.mkdir)(dir, { recursive: true });
+  const existingMode = await readExistingMode(filePath);
+  const tempFilePath = createTempFilePath(filePath);
+  try {
+    await (0, import_promises2.writeFile)(tempFilePath, content, "utf8");
+    if (existingMode !== void 0) {
+      await (0, import_promises2.chmod)(tempFilePath, existingMode);
+    }
+    await (0, import_promises2.rename)(tempFilePath, filePath);
+  } catch (error) {
+    await (0, import_promises2.rm)(tempFilePath, { force: true }).catch(() => void 0);
+    throw error;
+  }
+}
+
+// src/builtins/write-tool.ts
 var WriteSchema = import_zod3.z.object({
   filePath: import_zod3.z.string().describe("The absolute path to the file to write"),
   content: import_zod3.z.string().describe("The content to write to the file")
@@ -1014,8 +1083,7 @@ var WriteSchema = import_zod3.z.object({
 async function writeFileTool(args) {
   const { filePath, content } = args;
   try {
-    await (0, import_promises2.mkdir)((0, import_node_path.dirname)(filePath), { recursive: true });
-    await (0, import_promises2.writeFile)(filePath, content, "utf8");
+    await atomicWriteUtf8File(filePath, content);
     const result = {
       success: true,
       output: `Written ${Buffer.byteLength(content, "utf8")} bytes to ${filePath}`
@@ -1086,7 +1154,7 @@ async function editFileTool(args) {
   }
   const updated = replaceAll ? content.split(oldString).join(newString) : content.slice(0, content.indexOf(oldString)) + newString + content.slice(content.indexOf(oldString) + oldString.length);
   try {
-    await (0, import_promises3.writeFile)(filePath, updated, "utf8");
+    await atomicWriteUtf8File(filePath, updated);
   } catch (err) {
     const result2 = {
       success: false,
@@ -1096,9 +1164,12 @@ async function editFileTool(args) {
     return JSON.stringify(result2);
   }
   const count = replaceAll ? content.split(oldString).length - 1 : 1;
+  const matchIdx = content.indexOf(oldString);
+  const startLine = matchIdx >= 0 ? content.substring(0, matchIdx).split("\n").length : 1;
   const result = {
     success: true,
-    output: `Replaced ${count} occurrence(s) in ${filePath}`
+    output: `Replaced ${count} occurrence(s) in ${filePath}`,
+    startLine
   };
   return JSON.stringify(result);
 }