@ai-code-agents/environment-utils 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,482 @@
+import { FlexibleSchema } from '@ai-sdk/provider-utils';
+import { ToolExecutionOptions } from 'ai';
+import * as z from 'zod';
+
+declare const ReadFileResult: z.ZodObject<{
+    path: z.ZodString;
+    content: z.ZodString;
+}, z.core.$strip>;
+type ReadFileResult = z.infer<typeof ReadFileResult>;
+declare const WriteFileResult: z.ZodObject<{
+    path: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>;
+type WriteFileResult = z.infer<typeof WriteFileResult>;
+declare const DeleteFileResult: z.ZodObject<{
+    path: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>;
+type DeleteFileResult = z.infer<typeof DeleteFileResult>;
+declare const MoveFileResult: z.ZodObject<{
+    sourcePath: z.ZodString;
+    destinationPath: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>;
+type MoveFileResult = z.infer<typeof MoveFileResult>;
+declare const CopyFileResult: z.ZodObject<{
+    sourcePath: z.ZodString;
+    destinationPath: z.ZodString;
+    message: z.ZodString;
+}, z.core.$strip>;
+type CopyFileResult = z.infer<typeof CopyFileResult>;
+declare const RunCommandResult: z.ZodObject<{
+    command: z.ZodString;
+    exitCode: z.ZodNumber;
+    stdout: z.ZodString;
+    stderr: z.ZodString;
+}, z.core.$strip>;
+type RunCommandResult = z.infer<typeof RunCommandResult>;
+interface FilesystemEnvironmentInterface {
+    get name(): string;
+    readFile(path: string): Promise<ReadFileResult>;
+    writeFile(path: string, content: string): Promise<WriteFileResult>;
+    deleteFile(path: string): Promise<DeleteFileResult>;
+    moveFile(sourcePath: string, destinationPath: string): Promise<MoveFileResult>;
+    copyFile(sourcePath: string, destinationPath: string): Promise<CopyFileResult>;
+}
+interface CommandLineEnvironmentInterface extends FilesystemEnvironmentInterface {
+    runCommand(command: string): Promise<RunCommandResult>;
+}
+/**
+ * Interface for environments that support explicit shutdown/cleanup.
+ *
+ * Environments implementing this interface may hold resources (connections,
+ * sandboxes, containers) that should be released when no longer needed.
+ */
+interface ShutdownableEnvironmentInterface {
+    /**
+     * Shuts down the environment and releases any held resources.
+     *
+     * @returns A promise that resolves when shutdown is complete.
+     */
+    shutdown(): Promise<void>;
+}
+type Environment = FilesystemEnvironmentInterface | CommandLineEnvironmentInterface;
+/**
+ * Type guard to check if an environment supports command-line operations.
+ *
+ * @param env - The environment to check.
+ * @returns True if the environment implements CommandLineEnvironmentInterface.
+ */
+declare function isCommandLine(env: Environment): env is CommandLineEnvironmentInterface;
+/**
+ * Type guard to check if an environment supports shutdown.
+ *
+ * @param env - The environment to check.
+ * @returns True if the environment implements ShutdownableEnvironmentInterface.
+ */
+declare function isShutdownable(env: Environment): env is Environment & ShutdownableEnvironmentInterface;
+type ModelTextResult = {
+    type: 'text';
+    value: string;
+};
+type ModelTextPart = {
+    type: 'text';
+    text: string;
+};
+type ModelMediaPart = {
+    type: 'media';
+    data: string;
+    mediaType: string;
+};
+type ModelToolResultToFormat<ToolInputType, ToolOutputType> = {
+    toolCallId: string;
+    input: ToolInputType;
+    output: ToolOutputType;
+};
+type ModelFormattedToolResult = ModelTextResult | {
+    type: 'content';
+    value: Array<ModelTextPart | ModelMediaPart>;
+};
+type ToolExample<ToolInputType, ToolOutputType> = {
+    input: ToolInputType;
+    output: ToolOutputType | string;
+};
+interface ToolInterface<ToolInputType, ToolOutputType> {
+    get name(): string;
+    get description(): string;
+    get inputSchema(): FlexibleSchema<ToolInputType>;
+    get outputSchema(): FlexibleSchema<ToolOutputType>;
+    execute(input: ToolInputType, options: ToolExecutionOptions): Promise<ToolOutputType>;
+    toModelOutput(options: ModelToolResultToFormat<ToolInputType, ToolOutputType>): ModelFormattedToolResult;
+    get examples(): Array<ToolExample<ToolInputType, ToolOutputType>>;
+    get inputExamples(): Array<{
+        input: ToolInputType;
+    }>;
+    get needsApproval(): boolean;
+}
+interface EnvironmentToolInterface<ToolInputType, ToolOutputType, EnvironmentType> extends ToolInterface<ToolInputType, ToolOutputType> {
+    get environment(): EnvironmentType;
+}
+type ToolConfig = {
+    name?: string;
+    description?: string;
+    needsApproval?: boolean;
+};
+
+/**
+ * Base class for a filesystem-based execution environment.
+ */
+declare abstract class FilesystemEnvironmentBase<EnvironmentConfig> implements FilesystemEnvironmentInterface {
+    protected _envConfig: EnvironmentConfig;
+    /**
+     * Constructs a new environment instance.
+     *
+     * @param config - Environment configuration.
+     */
+    constructor(config: EnvironmentConfig);
+    /**
+     * Gets the environment name.
+     *
+     * @returns The environment name.
+     */
+    abstract get name(): string;
+    /**
+     * Reads the content of a file at the specified path.
+     *
+     * @param path - The path to the file to read, relative to the project directory.
+     * @returns A promise that resolves to a ReadFileResult.
+     */
+    readFile(path: string): Promise<ReadFileResult>;
+    /**
+     * Writes content to a file at the specified path.
+     *
+     * If a file is already present at the path, it will be overwritten.
+     *
+     * @param path - The path to the file to write, relative to the project directory.
+     * @param content - The content to write to the file.
+     * @returns A promise that resolves to a WriteFileResult.
+     */
+    writeFile(path: string, content: string): Promise<WriteFileResult>;
+    /**
+     * Deletes a file at the specified path.
+     *
+     * @param path - The path to the file to delete, relative to the project directory.
+     * @returns A promise that resolves to a DeleteFileResult.
+     */
+    deleteFile(path: string): Promise<DeleteFileResult>;
+    /**
+     * Moves a file from a source path to a destination path.
+     *
+     * If a file is already present at the destination path, it will be overwritten.
+     *
+     * @param sourcePath - The path to the file to move.
+     * @param destinationPath - The path to move the file to.
+     * @returns A promise that resolves to a MoveFileResult.
+     */
+    moveFile(sourcePath: string, destinationPath: string): Promise<MoveFileResult>;
+    /**
+     * Copies a file from a source path to a destination path.
+     *
+     * If a file is already present at the destination path, it will be overwritten.
+     *
+     * @param sourcePath - The path to the file to copy.
+     * @param destinationPath - The path to copy the file to.
+     * @returns A promise that resolves to a CopyFileResult.
+     */
+    copyFile(sourcePath: string, destinationPath: string): Promise<CopyFileResult>;
+    /**
+     * Checks whether a file exists at the specified path relative to the project directory.
+     *
+     * @param relativePath - The path to the file to check, relative to the project directory.
+     * @returns True if the file exists, false otherwise.
+     */
+    protected abstract fileExists(relativePath: string): Promise<boolean>;
+    /**
+     * Gets the content of a file at the specified path, relative to the project directory.
+     *
+     * When this method is called, it is guaranteed that the file exists.
+     *
+     * @param relativePath - The path to the file to read, relative to the project directory.
+     * @returns The content of the file.
+     */
+    protected abstract readFileContent(relativePath: string): Promise<string>;
+    /**
+     * Writes content to a file at the specified path, relative to the project directory.
+     *
+     * This method unconditionally writes the content, even if a file already exists at the path, or if the file is new.
+     *
+     * @param relativePath - The path to the file to write, relative to the project directory.
+     * @param content - The content to write to the file.
+     */
+    protected abstract writeFileContent(relativePath: string, content: string): Promise<void>;
+    /**
+     * Deletes a file at the specified path, relative to the project directory.
+     *
+     * When this method is called, it is guaranteed that the file exists.
+     *
+     * @param relativePath - The path to the file to delete, relative to the project directory.
+     */
+    protected abstract deleteFileContent(relativePath: string): Promise<void>;
+    /**
+     * Moves the content of a file from a source path to a destination path, relative to the project directory.
+     *
+     * When this method is called, it is guaranteed that the source file exists.
+     * This method unconditionally moves the content, even if a file already exists at the destination path.
+     *
+     * @param relativeSourcePath - The path to the file to move, relative to the project directory.
+     * @param relativeDestinationPath - The path to move the file to, relative to the project directory.
+     */
+    protected moveFileContent(relativeSourcePath: string, relativeDestinationPath: string): Promise<void>;
+    /**
+     * Copies the content of a file from a source path to a destination path, relative to the project directory.
+     *
+     * When this method is called, it is guaranteed that the source file exists.
+     * This method unconditionally copies the content, even if a file already exists at the destination path.
+     *
+     * @param relativeSourcePath - The path to the file to copy, relative to the project directory.
+     * @param relativeDestinationPath - The path to copy the file to, relative to the project directory.
+     */
+    protected copyFileContent(relativeSourcePath: string, relativeDestinationPath: string): Promise<void>;
+}
+
+/**
+ * Base class for a command-line based execution environment.
+ */
+declare abstract class CommandLineEnvironmentBase<EnvironmentConfig> extends FilesystemEnvironmentBase<EnvironmentConfig> implements CommandLineEnvironmentInterface {
+    /**
+     * Runs a CLI command in environment.
+     *
+     * @param command - The command to run.
+     * @returns A promise that resolves to a RunCommandResult.
+     */
+    runCommand(command: string): Promise<RunCommandResult>;
+    /**
+     * Executes a command in the environment and returns the exit code, stdout, and stderr.
+     *
+     * @param command - The command to execute.
+     * @returns A promise that resolves to a tuple containing the exit code, stdout, and stderr.
+     */
+    protected abstract executeCommand(command: string): Promise<[number, string, string]>;
+}
+
+/**
+ * Base class for a Unix-like command line execution environment.
+ */
+declare abstract class UnixEnvironmentBase<EnvironmentConfig> extends CommandLineEnvironmentBase<EnvironmentConfig> {
+    /**
+     * Checks whether a file exists at the specified path relative to the project directory.
+     *
+     * @param relativePath - The path to the file to check, relative to the project directory.
+     * @returns True if the file exists, false otherwise.
+     */
+    protected fileExists(relativePath: string): Promise<boolean>;
+    /**
+     * Gets the content of a file at the specified path, relative to the project directory.
+     *
+     * When this method is called, it is guaranteed that the file exists.
+     *
+     * @param relativePath - The path to the file to read, relative to the project directory.
+     * @returns The content of the file.
+     */
+    protected readFileContent(relativePath: string): Promise<string>;
+    /**
+     * Writes content to a file at the specified path, relative to the project directory.
+     *
+     * This method unconditionally writes the content, even if a file already exists at the path, or if the file is new.
+     *
+     * @param relativePath - The path to the file to write, relative to the project directory.
+     * @param content - The content to write to the file.
+     */
+    protected writeFileContent(relativePath: string, content: string): Promise<void>;
+    /**
+     * Deletes a file at the specified path, relative to the project directory.
+     *
+     * When this method is called, it is guaranteed that the file exists.
+     *
+     * @param relativePath - The path to the file to delete, relative to the project directory.
+     */
+    protected deleteFileContent(relativePath: string): Promise<void>;
+    /**
+     * Moves the content of a file from a source path to a destination path, relative to the project directory.
+     *
+     * When this method is called, it is guaranteed that the source file exists.
+     * This method unconditionally moves the content, even if a file already exists at the destination path.
+     *
+     * @param relativeSourcePath - The path to the file to move, relative to the project directory.
+     * @param relativeDestinationPath - The path to move the file to, relative to the project directory.
+     */
+    protected moveFileContent(relativeSourcePath: string, relativeDestinationPath: string): Promise<void>;
+    /**
+     * Copies the content of a file from a source path to a destination path, relative to the project directory.
+     *
+     * When this method is called, it is guaranteed that the source file exists.
+     * This method unconditionally copies the content, even if a file already exists at the destination path.
+     *
+     * @param relativeSourcePath - The path to the file to copy, relative to the project directory.
+     * @param relativeDestinationPath - The path to copy the file to, relative to the project directory.
+     */
+    protected copyFileContent(relativeSourcePath: string, relativeDestinationPath: string): Promise<void>;
+}
+
+type FlexibleInputSchema<T> = ToolInterface<T, unknown>['inputSchema'];
+type FlexibleOutputSchema<T> = ToolInterface<unknown, T>['outputSchema'];
+type ToolMetadata<ToolInputType, ToolOutputType> = {
+    name: string;
+    description: string;
+    inputSchema: FlexibleInputSchema<ToolInputType>;
+    outputSchema: FlexibleOutputSchema<ToolOutputType>;
+    needsApproval: boolean;
+};
+/**
+ * Base class for a tool.
+ */
+declare abstract class ToolBase<ToolConfig extends ToolConfig, ToolInputType, ToolOutputType> implements ToolInterface<ToolInputType, ToolOutputType> {
+    readonly _toolConfig: ToolConfig;
+    protected readonly _name: string;
+    protected readonly _description: string;
+    protected readonly _inputSchema: FlexibleInputSchema<ToolInputType>;
+    protected readonly _outputSchema: FlexibleOutputSchema<ToolOutputType>;
+    protected readonly _needsApproval: boolean;
+    /**
+     * Constructs a new tool instance.
+     *
+     * @param toolConfig - Optional tool config, can be used to override some defaults.
+     */
+    constructor(toolConfig?: ToolConfig);
+    /**
+     * Gets the tool name.
+     *
+     * @returns The tool name.
+     */
+    get name(): string;
+    /**
+     * Gets the tool description.
+     *
+     * @returns The tool description.
+     */
+    get description(): string;
+    /**
+     * Gets the input schema for the tool.
+     *
+     * @returns The input schema.
+     */
+    get inputSchema(): FlexibleInputSchema<ToolInputType>;
+    /**
+     * Gets the input schema for the tool.
+     *
+     * @returns The input schema.
+     */
+    get outputSchema(): FlexibleInputSchema<ToolOutputType>;
+    /**
+     * Gets whether the tool needs approval before use.
+     *
+     * @returns True if the tool needs approval, false otherwise.
+     */
+    get needsApproval(): boolean;
+    /**
+     * Gets the input examples for the tool.
+     *
+     * This is used for AI SDK v6 compatibility, which supports input examples, but without output examples.
+     *
+     * @returns The tool input examples.
+     */
+    get inputExamples(): Array<{
+        input: ToolInputType;
+    }>;
+    /**
+     * Gets the examples for the tool.
+     *
+     * @returns The tool examples.
+     */
+    abstract get examples(): Array<ToolExample<ToolInputType, ToolOutputType>>;
+    /**
+     * Executes the tool with the given input.
+     *
+     * @param input - The input for the tool.
+     * @param options - Options for the tool execution.
+     * @returns A promise that resolves to the tool execution result.
+     */
+    abstract execute(input: ToolInputType, options: ToolExecutionOptions): Promise<ToolOutputType>;
+    /**
+     * Converts the tool output to a format suitable for model consumption.
+     *
+     * @param options - The tool result, including the output from the tool execution.
+     * @returns The formatted tool result.
+     */
+    abstract toModelOutput(options: ModelToolResultToFormat<ToolInputType, ToolOutputType>): ModelFormattedToolResult;
+    /**
+     * Returns the metadata for the tool.
+     *
+     * The name, description, and needsApproval properties are defaults which can be overridden in the constructor.
+     *
+     * @returns The tool metadata.
+     */
+    protected abstract getMetadata(): ToolMetadata<ToolInputType, ToolOutputType>;
+}
+
+type EnvironmentToolMetadata<ToolInputType, ToolOutputType> = ToolMetadata<ToolInputType, ToolOutputType>;
+/**
+ * Base class for an execution environment tool.
+ */
+declare abstract class EnvironmentToolBase<ToolConfig extends ToolConfig, ToolInputType, ToolOutputType, EnvironmentType> extends ToolBase<ToolConfig, ToolInputType, ToolOutputType> implements EnvironmentToolInterface<ToolInputType, ToolOutputType, EnvironmentType> {
+    protected readonly _environment: EnvironmentType;
+    /**
+     * Constructs a new `EnvironmentToolBase` instance.
+     *
+     * @param environment - The execution environment to apply the tool in.
+     * @param toolConfig - Optional tool config, can be used to override some defaults.
+     */
+    constructor(environment: EnvironmentType, toolConfig?: ToolConfig);
+    /**
+     * Gets the current execution environment for the tool.
+     *
+     * @returns The current execution environment.
+     */
+    get environment(): EnvironmentType;
+    /**
+     * Executes the tool with the given input.
+     *
+     * @param input - The input for the tool.
+     * @param _options - Options for the tool execution.
+     * @returns A promise that resolves to the tool execution result.
+     */
+    execute(input: ToolInputType, _options: ToolExecutionOptions): Promise<ToolOutputType>;
+    /**
+     * Returns the metadata for the tool.
+     *
+     * The name, description, and needsApproval properties are defaults which can be overridden in the constructor.
+     *
+     * @returns The tool metadata.
+     */
+    protected abstract getMetadata(): EnvironmentToolMetadata<ToolInputType, ToolOutputType>;
+    /**
+     * Executes the tool in the given execution environment with the given input.
+     *
+     * @param env - The execution environment to use.
+     * @param input - The input for the tool.
+     * @returns A promise that resolves to the tool execution result.
+     */
+    protected abstract executeForEnvironment(env: EnvironmentType, input: ToolInputType): Promise<ToolOutputType>;
+}
+
+/**
+ * Escapes a string to be used as a single command-line argument in a POSIX-compliant shell.
+ *
+ * The string is wrapped in single quotes, and any existing single quotes are
+ * safely escaped. This prevents the shell from interpreting special
+ * characters or expanding variables.
+ *
+ * @param arg - The argument string to escape.
+ * @returns The escaped and quoted argument string.
+ */
+declare function escapeCommandArg(arg: string): string;
+
+/**
+ * Validates that the given path is a relative path and does not contain path traversal.
+ *
+ * @param filePath - The file path to validate.
+ */
+declare function validateRelativePath(filePath: string): void;
+
+export { CommandLineEnvironmentBase, type CommandLineEnvironmentInterface, CopyFileResult, DeleteFileResult, type Environment, EnvironmentToolBase, type EnvironmentToolInterface, type EnvironmentToolMetadata, FilesystemEnvironmentBase, type FilesystemEnvironmentInterface, type ModelFormattedToolResult, type ModelToolResultToFormat, MoveFileResult, ReadFileResult, RunCommandResult, type ShutdownableEnvironmentInterface, ToolBase, type ToolConfig, type ToolExample, type ToolInterface, type ToolMetadata, UnixEnvironmentBase, WriteFileResult, escapeCommandArg, isCommandLine, isShutdownable, validateRelativePath };