@robota-sdk/agent-tools 3.0.0-beta.7 → 3.0.0-beta.70

package/dist/node/index.d.ts

@@ -1,139 +1,303 @@
-import { IToolRegistry, ITool, IToolSchema, TToolParameters, TUniversalValue, IFunctionTool, TToolExecutor, IEventService, IToolExecutionContext, IToolResult, IParameterValidationResult, IOpenAPIToolConfig } from '@robota-sdk/agent-core';
+import { IEventService, IFunctionTool, IParameterValidationResult, ITool, IToolExecutionContext, IToolRegistry, IToolResult, IToolSchema, TToolExecutor, TToolParameters, TUniversalValue } from "@robota-sdk/agent-core";
 
+//#region src/types/tool-result.d.ts
 /**
  * Result returned by a CLI tool invocation
  */
 interface TToolResult {
-    success: boolean;
-    output: string;
-    error?: string;
-    exitCode?: number;
+  success: boolean;
+  output: string;
+  error?: string;
+  exitCode?: number;
+  /** Start line number of the edit in the original file (Edit tool only) */
+  startLine?: number;
 }
-
+//#endregion
+//#region src/sandbox/types.d.ts
+interface ISandboxRunOptions {
+  timeoutMs?: number;
+  workingDirectory?: string;
+}
+interface ISandboxRunResult {
+  stdout: string;
+  stderr?: string;
+  exitCode: number;
+}
+interface IWorkspaceManifestFileEntry {
+  type: 'file';
+  content: string;
+  encoding?: 'utf8';
+}
+interface IWorkspaceManifestDirectoryEntry {
+  type: 'dir';
+}
+interface IWorkspaceManifestLocalFileEntry {
+  type: 'localFile';
+  src: string;
+}
+interface IWorkspaceManifestLocalDirectoryEntry {
+  type: 'localDir';
+  src: string;
+}
+interface IWorkspaceManifestGitRepositoryEntry {
+  type: 'gitRepo';
+  url: string;
+  ref?: string;
+  shallow?: boolean;
+}
+interface IWorkspaceManifestS3MountEntry {
+  type: 's3Mount';
+  bucket: string;
+  prefix?: string;
+  region: string;
+}
+interface IWorkspaceManifestGcsMountEntry {
+  type: 'gcsMount';
+  bucket: string;
+  prefix?: string;
+}
+interface IWorkspaceManifestR2MountEntry {
+  type: 'r2Mount';
+  bucket: string;
+  accountId: string;
+  prefix?: string;
+}
+interface IWorkspaceManifestAzureBlobMountEntry {
+  type: 'azureBlobMount';
+  container: string;
+  account: string;
+  prefix?: string;
+}
+type TWorkspaceManifestEntry = IWorkspaceManifestFileEntry | IWorkspaceManifestDirectoryEntry | IWorkspaceManifestLocalFileEntry | IWorkspaceManifestLocalDirectoryEntry | IWorkspaceManifestGitRepositoryEntry | IWorkspaceManifestS3MountEntry | IWorkspaceManifestGcsMountEntry | IWorkspaceManifestR2MountEntry | IWorkspaceManifestAzureBlobMountEntry;
+interface IWorkspaceManifestPermissions {
+  read?: string[];
+  write?: string[];
+}
+interface IWorkspaceManifest {
+  entries: Record<string, TWorkspaceManifestEntry>;
+  environment?: Record<string, string>;
+  permissions?: IWorkspaceManifestPermissions;
+}
+interface IWorkspaceManifestApplyOptions {
+  targetRoot?: string;
+  hostRoot?: string;
+}
+type TWorkspaceManifestApplyStatus = 'applied' | 'unsupported';
+interface IWorkspaceManifestAppliedEntry {
+  path: string;
+  type: TWorkspaceManifestEntry['type'];
+  status: TWorkspaceManifestApplyStatus;
+  message?: string;
+}
+interface IWorkspaceManifestApplyResult {
+  entries: IWorkspaceManifestAppliedEntry[];
+}
+interface ISandboxClient {
+  run(command: string, options?: ISandboxRunOptions): Promise<ISandboxRunResult>;
+  readFile(path: string): Promise<string>;
+  writeFile(path: string, content: string): Promise<void>;
+  applyManifest?(manifest: IWorkspaceManifest, options?: IWorkspaceManifestApplyOptions): Promise<IWorkspaceManifestApplyResult>;
+  /** Return a provider-owned resumable workspace reference. */
+  snapshot?(): Promise<string>;
+  /** Hydrate this client from a provider-owned workspace reference. */
+  restore?(snapshotId: string): Promise<void>;
+}
+interface ISandboxToolOptions {
+  sandboxClient?: ISandboxClient;
+  /** When set, Read/Write/Edit operations on the host (non-sandbox) are restricted to this directory. */
+  cwd?: string;
+}
+//#endregion
+//#region src/sandbox/e2b-sandbox-client.d.ts
+interface IE2BCommandStartOptions {
+  timeoutMs?: number;
+  cwd?: string;
+  background?: false;
+}
+interface IE2BCommandResult {
+  stdout?: string;
+  stderr?: string;
+  exitCode?: number;
+  exit_code?: number;
+}
+interface IE2BCommands {
+  run(command: string, options?: IE2BCommandStartOptions): Promise<IE2BCommandResult>;
+}
+interface IE2BFiles {
+  read(path: string): Promise<string | Uint8Array>;
+  write(path: string, content: string): Promise<void>;
+}
+interface IE2BSnapshot {
+  snapshotId?: string;
+  id?: string;
+}
+interface IE2BSandboxAdapter {
+  sandboxId?: string;
+  commands: IE2BCommands;
+  files: IE2BFiles;
+  pause?(): Promise<boolean | string | void>;
+  connect?(): Promise<IE2BSandboxAdapter>;
+  createSnapshot?(): Promise<IE2BSnapshot>;
+}
+interface IE2BSandboxClientOptions {
+  sandbox: IE2BSandboxAdapter;
+  connectSandbox?: (sandboxId: string) => Promise<IE2BSandboxAdapter>;
+  createSandboxFromSnapshot?: (snapshotId: string) => Promise<IE2BSandboxAdapter>;
+}
+declare class E2BSandboxClient implements ISandboxClient {
+  private sandbox;
+  private readonly connectSandbox?;
+  private readonly createSandboxFromSnapshot?;
+  constructor(options: IE2BSandboxClientOptions);
+  run(command: string, options?: ISandboxRunOptions): Promise<ISandboxRunResult>;
+  readFile(path: string): Promise<string>;
+  writeFile(path: string, content: string): Promise<void>;
+  snapshot(): Promise<string>;
+  restore(snapshotId: string): Promise<void>;
+}
+//#endregion
+//#region src/sandbox/in-memory-sandbox-client.d.ts
+type TInMemorySandboxRunHandler = (command: string, options: ISandboxRunOptions | undefined, files: ReadonlyMap<string, string>) => Promise<ISandboxRunResult> | ISandboxRunResult;
+interface IInMemorySandboxClientOptions {
+  files?: Record<string, string>;
+  runHandler?: TInMemorySandboxRunHandler;
+}
+declare class InMemorySandboxClient implements ISandboxClient {
+  private readonly files;
+  private readonly snapshots;
+  private readonly runHandler?;
+  private snapshotSequence;
+  constructor(options?: IInMemorySandboxClientOptions);
+  run(command: string, options?: ISandboxRunOptions): Promise<ISandboxRunResult>;
+  readFile(path: string): Promise<string>;
+  writeFile(path: string, content: string): Promise<void>;
+  snapshot(): Promise<string>;
+  restore(snapshotId: string): Promise<void>;
+  getFile(path: string): string | undefined;
+}
+//#endregion
+//#region src/sandbox/workspace-manifest.d.ts
+declare function applyWorkspaceManifest(sandboxClient: ISandboxClient, manifest: IWorkspaceManifest, options?: IWorkspaceManifestApplyOptions): Promise<IWorkspaceManifestApplyResult>;
+declare function validateWorkspaceManifestPath(path: string): string;
+//#endregion
+//#region src/registry/tool-registry.d.ts
 /**
  * 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;
+  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
- */
-
+//#endregion
+//#region src/implementations/function-tool/types.d.ts
 /**
  * Zod schema compatibility types
+ *
+ * Widened to `unknown` so that actual Zod schemas (ZodObject<...>) are structurally
+ * assignable without `as unknown as IZodSchema` casts at call sites.
  */
 interface IZodParseResult {
-    success: boolean;
-    data?: TToolParameters;
-    error?: string | Error;
+  success: boolean;
+  data?: unknown;
+  error?: unknown;
 }
 interface IZodSchemaDef {
-    typeName?: string;
-    innerType?: IZodSchema;
-    valueType?: IZodSchema;
-    checks?: Array<{
-        kind: string;
-        value?: TUniversalValue;
-    }>;
-    shape?: () => Record<string, IZodSchema>;
-    type?: IZodSchema;
-    values?: TUniversalValue[];
-    description?: string;
+  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;
+  parse(value: unknown): unknown;
+  safeParse(value: unknown): IZodParseResult;
+  _def?: IZodSchemaDef;
 }
 /**
  * Parameter type validation options
  */
 interface IFunctionToolValidationOptions {
-    strict?: boolean;
-    allowUnknown?: boolean;
-    validateTypes?: boolean;
+  strict?: boolean;
+  allowUnknown?: boolean;
+  validateTypes?: boolean;
 }
 /**
  * Schema conversion options
  */
 interface ISchemaConversionOptions {
-    includeDescription?: boolean;
-    strictTypes?: boolean;
-    allowAdditionalProperties?: boolean;
+  includeDescription?: boolean;
+  strictTypes?: boolean;
+  allowAdditionalProperties?: boolean;
 }
 /**
  * Tool execution metadata
  */
 interface IFunctionToolExecutionMetadata {
-    executionTime: number;
-    toolName: string;
-    parameters: TToolParameters;
+  executionTime: number;
+  toolName: string;
+  parameters: TToolParameters;
 }
 /**
  * Tool result with metadata
  */
 interface IFunctionToolResult {
-    success: boolean;
-    data: TUniversalValue;
-    metadata?: IFunctionToolExecutionMetadata;
+  success: boolean;
+  data: TUniversalValue;
+  metadata?: IFunctionToolExecutionMetadata;
 }
-
+//#endregion
+//#region src/implementations/function-tool.d.ts
 /**
  * Function tool implementation
  * Wraps a JavaScript function as a tool with schema validation
@@ -142,48 +306,40 @@ interface IFunctionToolResult {
  * 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;
+  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
@@ -193,141 +349,54 @@ declare function createFunctionTool(name: string, description: string, parameter
  * 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
- */
-
+//#endregion
+//#region src/implementations/function-tool/schema-converter.d.ts
 /**
  * Convert Zod schema to JSON Schema format with safe undefined handling
  */
 declare function zodToJsonSchema(schema: IZodSchema, options?: ISchemaConversionOptions): IToolSchema['parameters'];
-
+//#endregion
+//#region src/builtins/bash-tool.d.ts
 /**
- * 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).
+ * Create a BashTool instance — register with Robota agent tools registry.
  */
+declare function createBashTool(options?: ISandboxToolOptions): FunctionTool;
 /**
  * BashTool instance — register with Robota agent tools registry.
  */
 declare const bashTool: FunctionTool;
-
+//#endregion
+//#region src/builtins/read-tool.d.ts
 /**
- * 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.
+ * Create a ReadTool instance — register with Robota agent tools registry.
  */
+declare function createReadTool(options?: ISandboxToolOptions): FunctionTool;
 /**
  * ReadTool instance — register with Robota agent tools registry.
  */
 declare const readTool: FunctionTool;
-
+//#endregion
+//#region src/builtins/write-tool.d.ts
 /**
- * WriteTool — write content to a file, auto-creating parent directories.
+ * Create a WriteTool instance — register with Robota agent tools registry.
  */
+declare function createWriteTool(options?: ISandboxToolOptions): FunctionTool;
 /**
  * WriteTool instance — register with Robota agent tools registry.
  */
 declare const writeTool: FunctionTool;
-
+//#endregion
+//#region src/builtins/edit-tool.d.ts
 /**
- * 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.
+ * Create an EditTool instance — register with Robota agent tools registry.
  */
+declare function createEditTool(options?: ISandboxToolOptions): FunctionTool;
 /**
  * EditTool instance — register with Robota agent tools registry.
  */
 declare const editTool: FunctionTool;
-
+//#endregion
+//#region src/builtins/glob-tool.d.ts
 /**
  * GlobTool — fast file pattern search using fast-glob.
  *
@@ -338,7 +407,8 @@ declare const editTool: FunctionTool;
  * GlobTool instance — register with Robota agent tools registry.
  */
 declare const globTool: FunctionTool;
-
+//#endregion
+//#region src/builtins/grep-tool.d.ts
 /**
  * GrepTool — recursive regex content search.
  *
@@ -350,15 +420,11 @@ declare const globTool: FunctionTool;
  * GrepTool instance — register with Robota agent tools registry.
  */
 declare const grepTool: FunctionTool;
-
-/**
- * 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).
- */
+//#endregion
+//#region src/builtins/web-fetch-tool.d.ts
 declare const webFetchTool: FunctionTool;
-
+//#endregion
+//#region src/builtins/web-search-tool.d.ts
 /**
  * WebSearchTool — search the web and return results.
  *
@@ -366,5 +432,6 @@ declare const webFetchTool: FunctionTool;
  * 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 };
+//#endregion
+export { E2BSandboxClient, FunctionTool, type IE2BSandboxAdapter, type IE2BSandboxClientOptions, type IFunctionToolExecutionMetadata, type IFunctionToolResult, type IFunctionToolValidationOptions, type IInMemorySandboxClientOptions, type ISandboxClient, type ISandboxRunOptions, type ISandboxRunResult, type ISandboxToolOptions, type ISchemaConversionOptions, type IWorkspaceManifest, type IWorkspaceManifestAppliedEntry, type IWorkspaceManifestApplyOptions, type IWorkspaceManifestApplyResult, type IWorkspaceManifestAzureBlobMountEntry, type IWorkspaceManifestDirectoryEntry, type IWorkspaceManifestFileEntry, type IWorkspaceManifestGcsMountEntry, type IWorkspaceManifestGitRepositoryEntry, type IWorkspaceManifestLocalDirectoryEntry, type IWorkspaceManifestLocalFileEntry, type IWorkspaceManifestPermissions, type IWorkspaceManifestR2MountEntry, type IWorkspaceManifestS3MountEntry, type IZodParseResult, type IZodSchema, type IZodSchemaDef, InMemorySandboxClient, type TInMemorySandboxRunHandler, type TToolResult, type TWorkspaceManifestApplyStatus, type TWorkspaceManifestEntry, ToolRegistry, applyWorkspaceManifest, bashTool, createBashTool, createEditTool, createFunctionTool, createReadTool, createWriteTool, createZodFunctionTool, editTool, globTool, grepTool, readTool, validateWorkspaceManifestPath, webFetchTool, webSearchTool, writeTool, zodToJsonSchema };
+//# sourceMappingURL=index.d.ts.map