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

package/dist/node/index.d.cts

@@ -0,0 +1,353 @@
+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;
+}
+
+/**
+ * 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;
+    checks?: Array<{
+        kind: string;
+        value?: TUniversalValue;
+    }>;
+    shape?: () => Record<string, IZodSchema>;
+    type?: IZodSchema;
+    values?: TUniversalValue[];
+    description?: string;
+}
+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;
+    /**
+     * Get detailed validation errors
+     */
+    private getValidationErrors;
+    /**
+     * Validate individual parameter type
+     */
+    private validateParameterType;
+    /**
+     * 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;
+    /**
+     * Find the operation in the OpenAPI specification
+     */
+    private findOperation;
+    /**
+     * Build HTTP request configuration from OpenAPI operation and parameters
+     */
+    private buildRequestConfig;
+    /**
+     * Create tool schema from OpenAPI operation specification
+     */
+    private createSchemaFromOpenAPI;
+    /**
+     * Convert OpenAPI parameter to tool parameter schema
+     */
+    private convertOpenAPIParamToSchema;
+    /**
+     * Convert OpenAPI schema to parameter schema
+     */
+    private convertOpenAPISchemaToParameterSchema;
+    /**
+     * Map OpenAPI type to JSON schema type
+     */
+    private mapOpenAPIType;
+}
+/**
+ * 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'];
+
+/**
+ * BashTool — execute shell commands via child_process.spawn
+ *
+ * Returns TToolResult JSON string. Non-zero exit is returned as success:true
+ * with exitCode set, matching Claude Code behaviour (the command ran, it just
+ * exited non-zero — the LLM can decide what to do with that information).
+ */
+/**
+ * BashTool instance — register with Robota agent tools registry.
+ */
+declare const bashTool: FunctionTool;
+
+/**
+ * ReadTool — read a file and return its contents with line numbers (cat -n style).
+ *
+ * Supports offset/limit for partial reads. Detects binary files and refuses to
+ * return their raw bytes. Default limit is 2000 lines.
+ */
+/**
+ * ReadTool instance — register with Robota agent tools registry.
+ */
+declare const readTool: FunctionTool;
+
+/**
+ * WriteTool — write content to a file, auto-creating parent directories.
+ */
+/**
+ * WriteTool instance — register with Robota agent tools registry.
+ */
+declare const writeTool: FunctionTool;
+
+/**
+ * EditTool — perform string-replace edits on a file.
+ *
+ * By default, requires the oldString to appear exactly once in the file
+ * (ensuring surgical edits). Pass replaceAll:true to replace all occurrences.
+ */
+/**
+ * EditTool instance — register with Robota agent tools registry.
+ */
+declare const editTool: FunctionTool;
+
+/**
+ * GlobTool — fast file pattern search using fast-glob.
+ *
+ * Excludes node_modules and .git by default.
+ * Results are sorted by modification time (most recently modified first).
+ */
+/**
+ * GlobTool instance — register with Robota agent tools registry.
+ */
+declare const globTool: FunctionTool;
+
+/**
+ * GrepTool — recursive regex content search.
+ *
+ * Supports two output modes:
+ * - files_with_matches (default): return only file paths that contain a match
+ * - content: return matching lines with optional context lines
+ */
+/**
+ * GrepTool instance — register with Robota agent tools registry.
+ */
+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 };

package/dist/node/index.d.ts

@@ -0,0 +1,353 @@
+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;
+}
+
+/**
+ * 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;
+    checks?: Array<{
+        kind: string;
+        value?: TUniversalValue;
+    }>;
+    shape?: () => Record<string, IZodSchema>;
+    type?: IZodSchema;
+    values?: TUniversalValue[];
+    description?: string;
+}
+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;
+    /**
+     * Get detailed validation errors
+     */
+    private getValidationErrors;
+    /**
+     * Validate individual parameter type
+     */
+    private validateParameterType;
+    /**
+     * 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;
+    /**
+     * Find the operation in the OpenAPI specification
+     */
+    private findOperation;
+    /**
+     * Build HTTP request configuration from OpenAPI operation and parameters
+     */
+    private buildRequestConfig;
+    /**
+     * Create tool schema from OpenAPI operation specification
+     */
+    private createSchemaFromOpenAPI;
+    /**
+     * Convert OpenAPI parameter to tool parameter schema
+     */
+    private convertOpenAPIParamToSchema;
+    /**
+     * Convert OpenAPI schema to parameter schema
+     */
+    private convertOpenAPISchemaToParameterSchema;
+    /**
+     * Map OpenAPI type to JSON schema type
+     */
+    private mapOpenAPIType;
+}
+/**
+ * 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'];
+
+/**
+ * BashTool — execute shell commands via child_process.spawn
+ *
+ * Returns TToolResult JSON string. Non-zero exit is returned as success:true
+ * with exitCode set, matching Claude Code behaviour (the command ran, it just
+ * exited non-zero — the LLM can decide what to do with that information).
+ */
+/**
+ * BashTool instance — register with Robota agent tools registry.
+ */
+declare const bashTool: FunctionTool;
+
+/**
+ * ReadTool — read a file and return its contents with line numbers (cat -n style).
+ *
+ * Supports offset/limit for partial reads. Detects binary files and refuses to
+ * return their raw bytes. Default limit is 2000 lines.
+ */
+/**
+ * ReadTool instance — register with Robota agent tools registry.
+ */
+declare const readTool: FunctionTool;
+
+/**
+ * WriteTool — write content to a file, auto-creating parent directories.
+ */
+/**
+ * WriteTool instance — register with Robota agent tools registry.
+ */
+declare const writeTool: FunctionTool;
+
+/**
+ * EditTool — perform string-replace edits on a file.
+ *
+ * By default, requires the oldString to appear exactly once in the file
+ * (ensuring surgical edits). Pass replaceAll:true to replace all occurrences.
+ */
+/**
+ * EditTool instance — register with Robota agent tools registry.
+ */
+declare const editTool: FunctionTool;
+
+/**
+ * GlobTool — fast file pattern search using fast-glob.
+ *
+ * Excludes node_modules and .git by default.
+ * Results are sorted by modification time (most recently modified first).
+ */
+/**
+ * GlobTool instance — register with Robota agent tools registry.
+ */
+declare const globTool: FunctionTool;
+
+/**
+ * GrepTool — recursive regex content search.
+ *
+ * Supports two output modes:
+ * - files_with_matches (default): return only file paths that contain a match
+ * - content: return matching lines with optional context lines
+ */
+/**
+ * GrepTool instance — register with Robota agent tools registry.
+ */
+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 };