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

package/README.md

@@ -1,6 +1,6 @@
 # @robota-sdk/agent-tools
 
-Tool registry, tool creation infrastructure, and 8 built-in CLI tools for the Robota SDK.
+Tool registry, tool creation infrastructure, 8 built-in CLI tools, sandbox execution ports, and sandbox workspace manifests for the Robota SDK.
 
 ## Installation
 
@@ -46,16 +46,57 @@ const agent = new Robota({
 
 ## Built-in Tools (8)
 
-| 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                  |
+| Export          | Tool Name | Description                                               |
+| --------------- | --------- | --------------------------------------------------------- |
+| `bashTool`      | Bash      | Execute shell commands via host process or sandbox client |
+| `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                           |
+
+Factory exports (`createBashTool`, `createReadTool`, `createWriteTool`, `createEditTool`) accept an optional `sandboxClient`. The default singleton exports keep host-local behavior.
+
+## Sandbox Execution
+
+`ISandboxClient` is the provider-neutral execution-plane port used by sandbox-aware built-in tools:
+
+```typescript
+import { E2BSandboxClient, createBashTool, createReadTool } from '@robota-sdk/agent-tools';
+import { Sandbox } from 'e2b';
+
+const e2b = await Sandbox.create();
+const sandboxClient = new E2BSandboxClient({ sandbox: e2b });
+
+const bashTool = createBashTool({ sandboxClient });
+const readTool = createReadTool({ sandboxClient });
+```
+
+The package does not depend on E2B directly. `E2BSandboxClient` adapts an E2B-compatible object with `commands.run`, `files.read`, `files.write`, and optional `createSnapshot`, `pause`, `connect`, or factory methods supplied by the application. `snapshot()` returns a provider-owned resumable workspace reference; `restore(snapshotId)` hydrates the adapter from that reference. `InMemorySandboxClient` is available for deterministic tests and contract verification.
+
+### Workspace Manifests
+
+`IWorkspaceManifest` declares the fresh sandbox workspace before a session starts. Paths are workspace-relative and cannot escape the target root.
+
+```typescript
+import { applyWorkspaceManifest, E2BSandboxClient } from '@robota-sdk/agent-tools';
+import { Sandbox } from 'e2b';
+
+const sandbox = await Sandbox.create();
+const sandboxClient = new E2BSandboxClient({ sandbox });
+
+await applyWorkspaceManifest(sandboxClient, {
+  entries: {
+    'task.md': { type: 'file', content: 'Analyze this repository.\n' },
+    repo: { type: 'gitRepo', url: 'https://github.com/example/project.git', ref: 'main' },
+    output: { type: 'dir' },
+  },
+});
+```
+
+The generic applicator writes inline/local files, creates directories, and clones Git repositories through `ISandboxClient`. Cloud storage mount entries are part of the contract, but they return `unsupported` until a provider-specific adapter implements native mounting.
 
 ## Edit and Write Safety
 
@@ -63,16 +104,21 @@ Recent file tool updates keep write/edit behavior atomic and make Edit tool resu
 
 ## Tool Infrastructure
 
-| 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              |
-| `createOpenAPITool`     | Factory for creating OpenAPI tools                     |
-| `zodToJsonSchema`       | Converts Zod schemas to JSON Schema format             |
-| `TToolResult`           | Result type for built-in CLI tool invocations          |
+| 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                  |
+| `createOpenAPITool`      | Factory for creating OpenAPI tools                         |
+| `zodToJsonSchema`        | Converts Zod schemas to JSON Schema format                 |
+| `TToolResult`            | Result type for built-in CLI tool invocations              |
+| `ISandboxClient`         | Provider-neutral sandbox execution port                    |
+| `IWorkspaceManifest`     | Declarative sandbox workspace setup contract               |
+| `applyWorkspaceManifest` | Generic manifest applicator for sandbox clients            |
+| `E2BSandboxClient`       | Adapter for E2B-compatible sandbox instances and snapshots |
+| `InMemorySandboxClient`  | Deterministic sandbox client for tests                     |
 
 ## TToolResult Shape
 

package/dist/browser/browser.d.ts

@@ -0,0 +1,268 @@
+import { IToolRegistry, ITool, IToolSchema, TToolParameters, TUniversalValue, IFunctionTool, TToolExecutor, IEventService, IToolExecutionContext, IToolResult, IParameterValidationResult, IOpenAPIToolConfig } from '@robota-sdk/agent-core';
+
+/**
+ * Result returned by a CLI tool invocation
+ */
+interface TToolResult {
+    success: boolean;
+    output: string;
+    error?: string;
+    exitCode?: number;
+    /** Start line number of the edit in the original file (Edit tool only) */
+    startLine?: number;
+}
+
+/**
+ * Tool registry implementation
+ * Manages tool registration, validation, and retrieval
+ */
+declare class ToolRegistry implements IToolRegistry {
+    private tools;
+    /**
+     * Register a tool
+     */
+    register(tool: ITool): void;
+    /**
+     * Unregister a tool
+     */
+    unregister(name: string): void;
+    /**
+     * Get tool by name
+     */
+    get(name: string): ITool | undefined;
+    /**
+     * Get all registered tools
+     */
+    getAll(): ITool[];
+    /**
+     * Get tool schemas
+     */
+    getSchemas(): IToolSchema[];
+    /**
+     * Check if tool exists
+     */
+    has(name: string): boolean;
+    /**
+     * Clear all tools
+     */
+    clear(): void;
+    /**
+     * Get tool names
+     */
+    getToolNames(): string[];
+    /**
+     * Get tools by pattern
+     */
+    getToolsByPattern(pattern: string | RegExp): ITool[];
+    /**
+     * Get tool count
+     */
+    size(): number;
+    /**
+     * Validate tool schema
+     */
+    private validateToolSchema;
+}
+
+/**
+ * FunctionTool - Type definitions for Facade pattern implementation
+ *
+ * REASON: Complex Zod schema type compatibility requires separation of concerns
+ * ALTERNATIVES_CONSIDERED:
+ * 1. Fix all Zod undefined issues in single file (creates maintenance burden)
+ * 2. Use any types strategically (reduces type safety)
+ * 3. Remove Zod support entirely (breaks existing functionality)
+ * 4. Create complex conditional types (adds cognitive overhead)
+ * 5. Use type assertions everywhere (increases runtime risk)
+ * NOTE: Tool functionality is now integrated into @robota-sdk/agent-tools package
+ */
+
+/**
+ * Zod schema compatibility types
+ */
+interface IZodParseResult {
+    success: boolean;
+    data?: TToolParameters;
+    error?: string | Error;
+}
+interface IZodSchemaDef {
+    typeName?: string;
+    innerType?: IZodSchema;
+    valueType?: IZodSchema;
+    checks?: Array<{
+        kind: string;
+        value?: TUniversalValue;
+    }>;
+    shape?: () => Record<string, IZodSchema>;
+    type?: IZodSchema;
+    values?: TUniversalValue[];
+    description?: string;
+    unknownKeys?: 'passthrough' | 'strip' | 'strict';
+}
+interface IZodSchema {
+    parse(value: TToolParameters): TToolParameters;
+    safeParse(value: TToolParameters): IZodParseResult;
+    _def?: IZodSchemaDef;
+}
+/**
+ * Parameter type validation options
+ */
+interface IFunctionToolValidationOptions {
+    strict?: boolean;
+    allowUnknown?: boolean;
+    validateTypes?: boolean;
+}
+/**
+ * Schema conversion options
+ */
+interface ISchemaConversionOptions {
+    includeDescription?: boolean;
+    strictTypes?: boolean;
+    allowAdditionalProperties?: boolean;
+}
+/**
+ * Tool execution metadata
+ */
+interface IFunctionToolExecutionMetadata {
+    executionTime: number;
+    toolName: string;
+    parameters: TToolParameters;
+}
+/**
+ * Tool result with metadata
+ */
+interface IFunctionToolResult {
+    success: boolean;
+    data: TUniversalValue;
+    metadata?: IFunctionToolExecutionMetadata;
+}
+
+/**
+ * Function tool implementation
+ * Wraps a JavaScript function as a tool with schema validation
+ *
+ * Implements IFunctionTool without extending AbstractTool to avoid
+ * circular runtime dependency (tools → agents → tools).
+ */
+declare class FunctionTool implements IFunctionTool {
+    readonly schema: IToolSchema;
+    readonly fn: TToolExecutor;
+    private eventService;
+    constructor(schema: IToolSchema, fn: TToolExecutor);
+    /**
+     * Get tool name
+     */
+    getName(): string;
+    /**
+     * Set EventService for post-construction injection.
+     * Accepts EventService as-is without transformation.
+     * Caller is responsible for providing properly configured EventService.
+     */
+    setEventService(eventService: IEventService | undefined): void;
+    /**
+     * Execute the function tool
+     */
+    execute(parameters: TToolParameters, context?: IToolExecutionContext): Promise<IToolResult>;
+    /**
+     * Validate parameters (simple boolean result)
+     */
+    validate(parameters: TToolParameters): boolean;
+    /**
+     * Validate tool parameters with detailed result
+     */
+    validateParameters(parameters: TToolParameters): IParameterValidationResult;
+    /**
+     * Get tool description
+     */
+    getDescription(): string;
+    /**
+     * Validate constructor inputs
+     */
+    private validateConstructorInputs;
+}
+/**
+ * Helper function to create a function tool from a simple function
+ */
+declare function createFunctionTool(name: string, description: string, parameters: IToolSchema['parameters'], fn: TToolExecutor): FunctionTool;
+/**
+ * Helper function to create a function tool from Zod schema
+ */
+declare function createZodFunctionTool(name: string, description: string, zodSchema: IZodSchema, fn: TToolExecutor): FunctionTool;
+
+/**
+ * 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).
+ */
+declare class OpenAPITool implements ITool {
+    readonly schema: IToolSchema;
+    private readonly apiSpec;
+    private readonly operationId;
+    private readonly baseURL;
+    private readonly config;
+    private eventService;
+    constructor(config: IOpenAPIToolConfig);
+    /**
+     * Execute the OpenAPI tool
+     */
+    execute(parameters: TToolParameters, context?: IToolExecutionContext): Promise<IToolResult>;
+    /**
+     * Validate tool parameters
+     */
+    validate(parameters: TToolParameters): boolean;
+    /**
+     * Validate tool parameters with detailed result
+     */
+    validateParameters(parameters: TToolParameters): IParameterValidationResult;
+    /**
+     * Get tool name
+     */
+    getName(): string;
+    /**
+     * Set EventService for post-construction injection.
+     */
+    setEventService(eventService: IEventService | undefined): void;
+    /**
+     * Get tool description
+     */
+    getDescription(): string;
+    /**
+     * Execute the actual API call
+     * @private
+     */
+    private executeAPICall;
+    /**
+     * Build HTTP request configuration from OpenAPI operation and parameters
+     */
+    private buildRequestConfig;
+    /**
+     * Create tool schema from OpenAPI operation specification
+     */
+    private createSchemaFromOpenAPI;
+}
+/**
+ * Factory function to create OpenAPI tools from specification
+ */
+declare function createOpenAPITool(config: IOpenAPIToolConfig): OpenAPITool;
+
+/**
+ * FunctionTool - Schema conversion utilities for Facade pattern
+ *
+ * REASON: Complex Zod to JSON schema conversion requires isolated utility functions
+ * ALTERNATIVES_CONSIDERED:
+ * 1. Keep conversion logic in main class (violates single responsibility)
+ * 2. Use third-party library (adds external dependency)
+ * 3. Manual conversion each time (code duplication)
+ * 4. Runtime type checking only (loses compile-time safety)
+ * 5. Remove Zod support (breaks backward compatibility)
+ * TODO: Consider caching conversion results for performance
+ */
+
+/**
+ * Convert Zod schema to JSON Schema format with safe undefined handling
+ */
+declare function zodToJsonSchema(schema: IZodSchema, options?: ISchemaConversionOptions): IToolSchema['parameters'];
+
+export { FunctionTool, type IFunctionToolExecutionMetadata, type IFunctionToolResult, type IFunctionToolValidationOptions, type ISchemaConversionOptions, type IZodParseResult, type IZodSchema, type IZodSchemaDef, OpenAPITool, type TToolResult, ToolRegistry, createFunctionTool, createOpenAPITool, createZodFunctionTool, zodToJsonSchema };

package/dist/browser/browser.js

@@ -0,0 +1 @@
+import {ValidationError,logger,ToolExecutionError}from'@robota-sdk/agent-core';var S=class{tools=new Map;register(e){if(!e.schema?.name)throw new ValidationError("Tool must have a valid schema with name");let t=e.schema.name;this.validateToolSchema(e.schema),this.tools.has(t)&&logger.warn(`Tool "${t}" is already registered, overriding`,{toolName:t,existingTool:this.tools.get(t)?.constructor.name}),this.tools.set(t,e),logger.debug(`Tool "${t}" registered successfully`,{toolName:t,toolType:e.constructor.name,parameters:Object.keys(e.schema.parameters?.properties||{})});}unregister(e){if(!this.tools.has(e)){logger.warn(`Attempted to unregister non-existent tool "${e}"`);return}this.tools.delete(e),logger.debug(`Tool "${e}" unregistered successfully`);}get(e){return this.tools.get(e)}getAll(){return Array.from(this.tools.values())}getSchemas(){let e=this.getAll();return logger.debug("[TOOL-FLOW] ToolRegistry.getSchemas() - Tools before schema extraction",{count:e.length,tools:e.map(t=>({name:t.schema?.name??"unnamed",hasSchema:!!t.schema,schemaType:typeof t.schema,toolType:t.constructor?.name||"unknown"}))}),this.getAll().map(t=>t.schema)}has(e){return this.tools.has(e)}clear(){let e=this.tools.size;this.tools.clear(),logger.debug(`Cleared ${e} tools from registry`);}getToolNames(){return Array.from(this.tools.keys())}getToolsByPattern(e){let t=typeof e=="string"?new RegExp(e):e;return this.getAll().filter(o=>t.test(o.schema.name))}size(){return this.tools.size}validateToolSchema(e){if(!e.name||typeof e.name!="string")throw new ValidationError("Tool schema must have a valid name");if(!e.description||typeof e.description!="string")throw new ValidationError("Tool schema must have a description");if(!e.parameters||typeof e.parameters!="object"||e.parameters===null||Array.isArray(e.parameters))throw new ValidationError("Tool schema must have parameters object");if(e.parameters.type!=="object")throw new ValidationError('Tool parameters type must be "object"');if(e.parameters.properties)for(let t of Object.keys(e.parameters.properties)){let o=e.parameters.properties[t];if(!o?.type)throw new ValidationError(`Parameter "${t}" must have a type`);if(!["string","number","boolean","array","object"].includes(o.type))throw new ValidationError(`Parameter "${t}" has invalid type "${o.type}"`)}if(e.parameters.required){let t=e.parameters.properties||{};for(let o of e.parameters.required)if(!t[o])throw new ValidationError(`Required parameter "${o}" is not defined in properties`)}}};function v(r,e={}){let t={},o=[],n=r._def;if(!n)throw new Error("Zod schema is missing _def; cannot convert to JSON schema.");if(n.typeName==="ZodObject"&&n.shape){let a=typeof n.shape=="function"?n.shape():n.shape;for(let[s,i]of Object.entries(a)){let c=f(i);t[s]=c,Z(i)&&o.push(s);}}return {type:"object",properties:t,required:o,...(e.allowAdditionalProperties||n.unknownKeys==="passthrough")&&{additionalProperties:true}}}function f(r){let e=r._def;if(!e)throw new Error("Zod type is missing _def; cannot convert to JSON schema.");let t={};switch(e.description&&(t.description=e.description),e.typeName){case "ZodString":return {type:"string",...t};case "ZodNumber":return {type:"number",...t};case "ZodBoolean":return {type:"boolean",...t};case "ZodArray":{if(!e.type)throw new Error("ZodArray is missing item type; cannot convert to JSON schema.");return {type:"array",items:f(e.type),...t}}case "ZodObject":return {type:"object",...t};case "ZodEnum":{let o=e.values;if(!o||!Array.isArray(o))throw new Error("ZodEnum is missing enum values; cannot convert to JSON schema.");return {type:"string",enum:o,...t}}case "ZodOptional":if(e.innerType)return {...f(e.innerType),...t};throw new Error("ZodOptional is missing innerType; cannot convert to JSON schema.");case "ZodNullable":if(e.innerType)return {...f(e.innerType),...t};throw new Error("ZodNullable is missing innerType; cannot convert to JSON schema.");case "ZodDefault":if(e.innerType)return {...f(e.innerType),...t};throw new Error("ZodDefault is missing innerType; cannot convert to JSON schema.");case "ZodRecord":return e.valueType?{type:"object",additionalProperties:f(e.valueType),...t}:{type:"object",additionalProperties:{type:"string"},...t};default:throw new Error(`Unsupported Zod type: ${String(e.typeName)}`)}}function Z(r){let e=r._def;if(!e)throw new Error("Zod schema is missing _def; cannot determine required fields.");return e.typeName!=="ZodOptional"&&e.typeName!=="ZodNullable"&&e.typeName!=="ZodDefault"}function w(r,e,t){switch(t.type){case "string":if(typeof e!="string")return `Parameter "${r}" must be a string, got ${typeof e}`;break;case "number":if(typeof e!="number"||isNaN(e))return `Parameter "${r}" must be a number, got ${typeof e}`;break;case "boolean":if(typeof e!="boolean")return `Parameter "${r}" must be a boolean, got ${typeof e}`;break;case "array":if(!Array.isArray(e))return `Parameter "${r}" must be an array, got ${typeof e}`;if(t.items)for(let n=0;n<e.length;n++){let a=w(`${r}[${n}]`,e[n],t.items);if(a)return a}break;case "object":if(typeof e!="object"||e===null||Array.isArray(e))return `Parameter "${r}" must be an object, got ${typeof e}`;break}if(t.enum&&t.enum.length>0){let n=t.enum,a=false;for(let s of n)if(e===s){a=true;break}if(!a)return `Parameter "${r}" must be one of: ${n.join(", ")}, got ${e}`}}function I(r,e,t,o){let n=[];for(let a of e)a in r||n.push(`Missing required parameter: ${a}`);for(let[a,s]of Object.entries(r)){let i=t[a];if(!i){if(o===true)continue;if(o&&typeof o=="object"){let p=w(a,s,o);p&&n.push(p);continue}n.push(`Unknown parameter: ${a}`);continue}let c=w(a,s,i);c&&n.push(c);}return n}function E(r,e,t,o){let n=I(r,e,t,o);return {isValid:n.length===0,errors:n}}var T=class{schema;fn;eventService;constructor(e,t){this.schema=e,this.fn=t,this.validateConstructorInputs();}getName(){return this.schema.name}setEventService(e){this.eventService=e;}async execute(e,t){let o=this.schema.name;if(!this.validate(e)){let i=I(e,this.schema.parameters.required||[],this.schema.parameters.properties||{},this.schema.parameters.additionalProperties);throw new ValidationError(`Invalid parameters for tool "${o}": ${i.join(", ")}`)}let n=Date.now(),a;try{a=await this.fn(e,t);}catch(i){throw i instanceof ToolExecutionError||i instanceof ValidationError?i:new ToolExecutionError(`Function tool execution failed: ${i instanceof Error?i.message:String(i)}`,o,i instanceof Error?i:new Error(String(i)),{parameterCount:Object.keys(e||{}).length,hasContext:!!t})}let s=Date.now()-n;return {success:true,data:a,metadata:{executionTime:s,toolName:o,parameters:e}}}validate(e){return I(e,this.schema.parameters.required||[],this.schema.parameters.properties||{},this.schema.parameters.additionalProperties).length===0}validateParameters(e){return E(e,this.schema.parameters.required||[],this.schema.parameters.properties||{},this.schema.parameters.additionalProperties)}getDescription(){return this.schema.description}validateConstructorInputs(){if(!this.schema)throw new ValidationError("Tool schema is required");if(!this.fn||typeof this.fn!="function")throw new ValidationError("Tool function is required and must be a function");if(!this.schema.name)throw new ValidationError("Tool schema must have a name")}};function N(r,e,t,o){let n={name:r,description:e,parameters:t};return new T(n,o)}function C(r,e,t,o){let n=v(t),a={name:r,description:e,parameters:n},s=async(i,c)=>{let p=t.safeParse(i);if(!p.success)throw new ValidationError(`Zod validation failed: ${p.error}`);let d=await o(p.data||i,c);return typeof d=="string"?d:JSON.stringify(d)};return new T(a,s)}var k=["get","post","put","delete","patch","head","options"];function O(r,e){for(let[t,o]of Object.entries(r.paths||{}))if(o)for(let n of k){let a=o[n];if(a?.operationId===e)return {method:n,path:t,operation:a}}}function U(r){switch(r){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 P(r){if("$ref"in r)return {type:"object"};let e={type:U(r.type)};if(r.description&&(e.description=r.description),r.enum&&(e.enum=r.enum),r.minimum!==void 0&&(e.minimum=r.minimum),r.maximum!==void 0&&(e.maximum=r.maximum),r.pattern&&(e.pattern=r.pattern),r.format&&(e.format=r.format),r.default!==void 0&&(e.default=r.default),r.type==="array"&&r.items&&(e.items=P(r.items)),r.type==="object"&&r.properties){e.properties={};for(let[t,o]of Object.entries(r.properties))e.properties[t]=P(o);r.required&&r.required.length>0&&(e.required=r.required);}return e}function D(r){let e=r.schema;return P(e)}function j(r,e){let t={},o=[],n=e.parameters||[];for(let s of n)t[s.name]=D(s),s.required&&o.push(s.name);if(e.requestBody){let i=e.requestBody.content?.["application/json"];if(i?.schema){let c=P(i.schema);if(c.type==="object"&&c.properties){Object.assign(t,c.properties);let p=c;p.required&&o.push(...p.required);}}}let a={type:"object",properties:t};return o.length>0&&(a.required=o),{name:r,description:e.summary||e.description||`OpenAPI operation: ${r}`,parameters:a}}var b=class{schema;apiSpec;operationId;baseURL;config;eventService;constructor(e){if(this.config=e,typeof e.spec!="object"||e.spec===null||typeof e.spec.openapi!="string"||typeof e.spec.paths!="object")throw new Error('Invalid OpenAPI spec: must contain "openapi" (string) and "paths" (object) fields');this.apiSpec=e.spec,this.operationId=e.operationId,this.baseURL=e.baseURL,this.schema=this.createSchemaFromOpenAPI();}async execute(e,t){let o=this.schema.name,n=this.validateParameters(e);if(!n.isValid)throw new ValidationError(`Invalid parameters for OpenAPI tool "${o}": ${n.errors.join(", ")}`);try{let a=Date.now(),s=await this.executeAPICall(e,t),i=Date.now()-a;return {success:!0,data:s,metadata:{executionTime:i,toolName:o,operationId:this.operationId,baseURL:this.baseURL}}}catch(a){if(a instanceof ToolExecutionError||a instanceof ValidationError)throw a;let s=a instanceof Error?a:new Error(String(a));throw new ToolExecutionError(`OpenAPI tool execution failed: ${s.message}`,o,s,{operationId:this.operationId,baseURL:this.baseURL,parametersCount:Object.keys(e).length})}}validate(e){return this.validateParameters(e).isValid}validateParameters(e){let t=this.schema.parameters.required||[],o=[];for(let n of t)n in e||o.push(`Missing required parameter: ${n}`);return {isValid:o.length===0,errors:o}}getName(){return this.schema.name}setEventService(e){this.eventService=e;}getDescription(){return this.schema.description}async executeAPICall(e,t){let o=O(this.apiSpec,this.operationId);throw o?(this.buildRequestConfig(o,e),new Error("Not implemented: actual API execution is not yet available")):new Error(`Operation ${this.operationId} not found in OpenAPI spec`)}buildRequestConfig(e,t){let{method:o,path:n,operation:a}=e,s=this.baseURL+n,i={},c,p=a.parameters||[];for(let m of p){let l=t[m.name];if(l===void 0&&m.required)throw new Error(`Required parameter ${m.name} is missing`);if(l!==void 0)switch(m.in){case "path":s=s.replace(`{${m.name}}`,encodeURIComponent(String(l)));break;case "query":{let g=s.includes("?")?"&":"?";s+=`${g}${m.name}=${encodeURIComponent(String(l))}`;break}case "header":i[m.name]=String(l);break}}if(["post","put","patch"].includes(o)&&a.requestBody&&a.requestBody.content?.["application/json"]){i["Content-Type"]="application/json";let g={};for(let[x,$]of Object.entries(t))p.some(q=>q.name===x)||(g[x]=$);c=JSON.stringify(g);}if(this.config.auth)switch(this.config.auth.type){case "bearer":i.Authorization=`Bearer ${this.config.auth.token}`;break;case "apiKey":{let m=this.config.auth.header||"X-API-Key";i[m]=this.config.auth.apiKey||"";break}}let d={method:o,url:s,headers:i};return c!==void 0&&(d.body=c),d}createSchemaFromOpenAPI(){let e=O(this.apiSpec,this.operationId);if(!e)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 j(this.operationId,e.operation)}};function F(r){return new b(r)}export{T as FunctionTool,b as OpenAPITool,S as ToolRegistry,N as createFunctionTool,F as createOpenAPITool,C as createZodFunctionTool,v as zodToJsonSchema};