@n8n/agents 0.1.0

package/dist/workspace/tools/process-tools.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createListProcessesTool = createListProcessesTool;
+exports.createKillProcessTool = createKillProcessTool;
+const zod_1 = require("zod");
+const tool_1 = require("../../sdk/tool");
+function createListProcessesTool(processes) {
+    return new tool_1.Tool('workspace_list_processes')
+        .description('List all background processes spawned in the sandbox')
+        .input(zod_1.z.object({}))
+        .output(zod_1.z.object({
+        processes: zod_1.z.array(zod_1.z.object({
+            pid: zod_1.z.number(),
+            command: zod_1.z.string().optional(),
+            exitCode: zod_1.z.number().optional(),
+        })),
+    }))
+        .handler(async () => {
+        const list = await processes.list();
+        return { processes: list };
+    })
+        .build();
+}
+function createKillProcessTool(processes) {
+    return new tool_1.Tool('workspace_kill_process')
+        .description('Kill a background process in the sandbox by PID')
+        .input(zod_1.z.object({
+        pid: zod_1.z.number().describe('PID of the process to kill'),
+    }))
+        .output(zod_1.z.object({ killed: zod_1.z.boolean() }))
+        .handler(async (input) => {
+        const killed = await processes.kill(input.pid);
+        return { killed };
+    })
+        .build();
+}
+//# sourceMappingURL=process-tools.js.map

package/dist/workspace/tools/process-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process-tools.js","sourceRoot":"","sources":["../../../src/workspace/tools/process-tools.ts"],"names":[],"mappings":";;AAMA,0DAoBC;AAED,sDAcC;AA1CD,6BAAwB;AAExB,yCAAsC;AAItC,SAAgB,uBAAuB,CAAC,SAAgC;IACvE,OAAO,IAAI,WAAI,CAAC,0BAA0B,CAAC;SACzC,WAAW,CAAC,sDAAsD,CAAC;SACnE,KAAK,CAAC,OAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;SACnB,MAAM,CACN,OAAC,CAAC,MAAM,CAAC;QACR,SAAS,EAAE,OAAC,CAAC,KAAK,CACjB,OAAC,CAAC,MAAM,CAAC;YACR,GAAG,EAAE,OAAC,CAAC,MAAM,EAAE;YACf,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;YAC9B,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;SAC/B,CAAC,CACF;KACD,CAAC,CACF;SACA,OAAO,CAAC,KAAK,IAAI,EAAE;QACnB,MAAM,IAAI,GAAG,MAAM,SAAS,CAAC,IAAI,EAAE,CAAC;QACpC,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IAC5B,CAAC,CAAC;SACD,KAAK,EAAE,CAAC;AACX,CAAC;AAED,SAAgB,qBAAqB,CAAC,SAAgC;IACrE,OAAO,IAAI,WAAI,CAAC,wBAAwB,CAAC;SACvC,WAAW,CAAC,iDAAiD,CAAC;SAC9D,KAAK,CACL,OAAC,CAAC,MAAM,CAAC;QACR,GAAG,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,4BAA4B,CAAC;KACtD,CAAC,CACF;SACA,MAAM,CAAC,OAAC,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,OAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;SACzC,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;QACxB,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/C,OAAO,EAAE,MAAM,EAAE,CAAC;IACnB,CAAC,CAAC;SACD,KAAK,EAAE,CAAC;AACX,CAAC"}

package/dist/workspace/tools/read-file.d.ts

@@ -0,0 +1,3 @@
+import type { BuiltTool } from '../../types/sdk/tool';
+import type { WorkspaceFilesystem } from '../types';
+export declare function createReadFileTool(filesystem: WorkspaceFilesystem): BuiltTool;

package/dist/workspace/tools/read-file.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createReadFileTool = createReadFileTool;
+const zod_1 = require("zod");
+const tool_1 = require("../../sdk/tool");
+function createReadFileTool(filesystem) {
+    return new tool_1.Tool('workspace_read_file')
+        .description('Read the contents of a file from the workspace')
+        .input(zod_1.z.object({
+        path: zod_1.z.string().describe('Path to the file to read'),
+        encoding: zod_1.z.enum(['utf-8', 'base64']).optional().describe('File encoding (default: utf-8)'),
+    }))
+        .output(zod_1.z.object({
+        content: zod_1.z.string().describe('File content'),
+    }))
+        .handler(async (input) => {
+        const content = await filesystem.readFile(input.path, {
+            encoding: (input.encoding ?? 'utf-8'),
+        });
+        return { content: content.toString() };
+    })
+        .build();
+}
+//# sourceMappingURL=read-file.js.map

package/dist/workspace/tools/read-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-file.js","sourceRoot":"","sources":["../../../src/workspace/tools/read-file.ts"],"names":[],"mappings":";;AAMA,gDAqBC;AA3BD,6BAAwB;AAExB,yCAAsC;AAItC,SAAgB,kBAAkB,CAAC,UAA+B;IACjE,OAAO,IAAI,WAAI,CAAC,qBAAqB,CAAC;SACpC,WAAW,CAAC,gDAAgD,CAAC;SAC7D,KAAK,CACL,OAAC,CAAC,MAAM,CAAC;QACR,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,0BAA0B,CAAC;QACrD,QAAQ,EAAE,OAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,gCAAgC,CAAC;KAC3F,CAAC,CACF;SACA,MAAM,CACN,OAAC,CAAC,MAAM,CAAC;QACR,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,cAAc,CAAC;KAC5C,CAAC,CACF;SACA,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;QACxB,MAAM,OAAO,GAAG,MAAM,UAAU,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE;YACrD,QAAQ,EAAE,CAAC,KAAK,CAAC,QAAQ,IAAI,OAAO,CAAmB;SACvD,CAAC,CAAC;QACH,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC;IACxC,CAAC,CAAC;SACD,KAAK,EAAE,CAAC;AACX,CAAC"}

package/dist/workspace/tools/rmdir.d.ts

@@ -0,0 +1,3 @@
+import type { BuiltTool } from '../../types/sdk/tool';
+import type { WorkspaceFilesystem } from '../types';
+export declare function createRmdirTool(filesystem: WorkspaceFilesystem): BuiltTool;

package/dist/workspace/tools/rmdir.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRmdirTool = createRmdirTool;
+const zod_1 = require("zod");
+const tool_1 = require("../../sdk/tool");
+function createRmdirTool(filesystem) {
+    return new tool_1.Tool('workspace_rmdir')
+        .description('Remove a directory from the workspace')
+        .input(zod_1.z.object({
+        path: zod_1.z.string().describe('Path of the directory to remove'),
+        recursive: zod_1.z
+            .boolean()
+            .optional()
+            .describe('Remove the directory and its contents recursively'),
+        force: zod_1.z.boolean().optional().describe('Ignore errors if the directory does not exist'),
+    }))
+        .output(zod_1.z.object({
+        success: zod_1.z.boolean().describe('Whether the directory was removed'),
+    }))
+        .handler(async (input) => {
+        await filesystem.rmdir(input.path, { recursive: input.recursive, force: input.force });
+        return { success: true };
+    })
+        .build();
+}
+//# sourceMappingURL=rmdir.js.map

package/dist/workspace/tools/rmdir.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rmdir.js","sourceRoot":"","sources":["../../../src/workspace/tools/rmdir.ts"],"names":[],"mappings":";;AAMA,0CAuBC;AA7BD,6BAAwB;AAExB,yCAAsC;AAItC,SAAgB,eAAe,CAAC,UAA+B;IAC9D,OAAO,IAAI,WAAI,CAAC,iBAAiB,CAAC;SAChC,WAAW,CAAC,uCAAuC,CAAC;SACpD,KAAK,CACL,OAAC,CAAC,MAAM,CAAC;QACR,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,iCAAiC,CAAC;QAC5D,SAAS,EAAE,OAAC;aACV,OAAO,EAAE;aACT,QAAQ,EAAE;aACV,QAAQ,CAAC,mDAAmD,CAAC;QAC/D,KAAK,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,+CAA+C,CAAC;KACvF,CAAC,CACF;SACA,MAAM,CACN,OAAC,CAAC,MAAM,CAAC;QACR,OAAO,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,CAAC,mCAAmC,CAAC;KAClE,CAAC,CACF;SACA,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;QACxB,MAAM,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC,CAAC;QACvF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC1B,CAAC,CAAC;SACD,KAAK,EAAE,CAAC;AACX,CAAC"}

package/dist/workspace/tools/workspace-tools.d.ts

@@ -0,0 +1,8 @@
+import type { BuiltTool } from '../../types/sdk/tool';
+import type { WorkspaceFilesystem, WorkspaceSandbox } from '../types';
+interface WorkspaceLike {
+    filesystem?: WorkspaceFilesystem;
+    sandbox?: WorkspaceSandbox;
+}
+export declare function createWorkspaceTools(workspace: WorkspaceLike): BuiltTool[];
+export {};

package/dist/workspace/tools/workspace-tools.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createWorkspaceTools = createWorkspaceTools;
+const append_file_1 = require("./append-file");
+const copy_file_1 = require("./copy-file");
+const delete_file_1 = require("./delete-file");
+const execute_command_1 = require("./execute-command");
+const file_stat_1 = require("./file-stat");
+const list_files_1 = require("./list-files");
+const mkdir_1 = require("./mkdir");
+const move_file_1 = require("./move-file");
+const process_tools_1 = require("./process-tools");
+const read_file_1 = require("./read-file");
+const rmdir_1 = require("./rmdir");
+const write_file_1 = require("./write-file");
+function createWorkspaceTools(workspace) {
+    const tools = [];
+    if (workspace.filesystem) {
+        tools.push((0, read_file_1.createReadFileTool)(workspace.filesystem));
+        tools.push((0, write_file_1.createWriteFileTool)(workspace.filesystem));
+        tools.push((0, list_files_1.createListFilesTool)(workspace.filesystem));
+        tools.push((0, file_stat_1.createFileStatTool)(workspace.filesystem));
+        tools.push((0, mkdir_1.createMkdirTool)(workspace.filesystem));
+        tools.push((0, delete_file_1.createDeleteFileTool)(workspace.filesystem));
+        tools.push((0, append_file_1.createAppendFileTool)(workspace.filesystem));
+        tools.push((0, copy_file_1.createCopyFileTool)(workspace.filesystem));
+        tools.push((0, move_file_1.createMoveFileTool)(workspace.filesystem));
+        tools.push((0, rmdir_1.createRmdirTool)(workspace.filesystem));
+    }
+    if (workspace.sandbox?.executeCommand) {
+        tools.push((0, execute_command_1.createExecuteCommandTool)(workspace.sandbox));
+    }
+    if (workspace.sandbox?.processes) {
+        tools.push((0, process_tools_1.createListProcessesTool)(workspace.sandbox.processes));
+        tools.push((0, process_tools_1.createKillProcessTool)(workspace.sandbox.processes));
+    }
+    return tools;
+}
+//# sourceMappingURL=workspace-tools.js.map

package/dist/workspace/tools/workspace-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-tools.js","sourceRoot":"","sources":["../../../src/workspace/tools/workspace-tools.ts"],"names":[],"mappings":";;AAoBA,oDA0BC;AA5CD,+CAAqD;AACrD,2CAAiD;AACjD,+CAAqD;AACrD,uDAA6D;AAC7D,2CAAiD;AACjD,6CAAmD;AACnD,mCAA0C;AAC1C,2CAAiD;AACjD,mDAAiF;AACjF,2CAAiD;AACjD,mCAA0C;AAC1C,6CAAmD;AAOnD,SAAgB,oBAAoB,CAAC,SAAwB;IAC5D,MAAM,KAAK,GAAgB,EAAE,CAAC;IAE9B,IAAI,SAAS,CAAC,UAAU,EAAE,CAAC;QAC1B,KAAK,CAAC,IAAI,CAAC,IAAA,8BAAkB,EAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC;QACrD,KAAK,CAAC,IAAI,CAAC,IAAA,gCAAmB,EAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC;QACtD,KAAK,CAAC,IAAI,CAAC,IAAA,gCAAmB,EAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC;QACtD,KAAK,CAAC,IAAI,CAAC,IAAA,8BAAkB,EAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC;QACrD,KAAK,CAAC,IAAI,CAAC,IAAA,uBAAe,EAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC;QAClD,KAAK,CAAC,IAAI,CAAC,IAAA,kCAAoB,EAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC;QACvD,KAAK,CAAC,IAAI,CAAC,IAAA,kCAAoB,EAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC;QACvD,KAAK,CAAC,IAAI,CAAC,IAAA,8BAAkB,EAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC;QACrD,KAAK,CAAC,IAAI,CAAC,IAAA,8BAAkB,EAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC;QACrD,KAAK,CAAC,IAAI,CAAC,IAAA,uBAAe,EAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC;IACnD,CAAC;IAED,IAAI,SAAS,CAAC,OAAO,EAAE,cAAc,EAAE,CAAC;QACvC,KAAK,CAAC,IAAI,CAAC,IAAA,0CAAwB,EAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;IACzD,CAAC;IAED,IAAI,SAAS,CAAC,OAAO,EAAE,SAAS,EAAE,CAAC;QAClC,KAAK,CAAC,IAAI,CAAC,IAAA,uCAAuB,EAAC,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC;QACjE,KAAK,CAAC,IAAI,CAAC,IAAA,qCAAqB,EAAC,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC;IAChE,CAAC;IAED,OAAO,KAAK,CAAC;AACd,CAAC"}

package/dist/workspace/tools/write-file.d.ts

@@ -0,0 +1,3 @@
+import type { BuiltTool } from '../../types/sdk/tool';
+import type { WorkspaceFilesystem } from '../types';
+export declare function createWriteFileTool(filesystem: WorkspaceFilesystem): BuiltTool;

package/dist/workspace/tools/write-file.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createWriteFileTool = createWriteFileTool;
+const zod_1 = require("zod");
+const tool_1 = require("../../sdk/tool");
+function createWriteFileTool(filesystem) {
+    return new tool_1.Tool('workspace_write_file')
+        .description('Write content to a file in the workspace')
+        .input(zod_1.z.object({
+        path: zod_1.z.string().describe('Path to the file to write'),
+        content: zod_1.z.string().describe('Content to write to the file'),
+        recursive: zod_1.z
+            .boolean()
+            .optional()
+            .describe('Create parent directories if they do not exist'),
+    }))
+        .output(zod_1.z.object({
+        success: zod_1.z.boolean().describe('Whether the write was successful'),
+    }))
+        .handler(async (input) => {
+        await filesystem.writeFile(input.path, input.content, { recursive: input.recursive });
+        return { success: true };
+    })
+        .build();
+}
+//# sourceMappingURL=write-file.js.map

package/dist/workspace/tools/write-file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-file.js","sourceRoot":"","sources":["../../../src/workspace/tools/write-file.ts"],"names":[],"mappings":";;AAMA,kDAuBC;AA7BD,6BAAwB;AAExB,yCAAsC;AAItC,SAAgB,mBAAmB,CAAC,UAA+B;IAClE,OAAO,IAAI,WAAI,CAAC,sBAAsB,CAAC;SACrC,WAAW,CAAC,0CAA0C,CAAC;SACvD,KAAK,CACL,OAAC,CAAC,MAAM,CAAC;QACR,IAAI,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,2BAA2B,CAAC;QACtD,OAAO,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,8BAA8B,CAAC;QAC5D,SAAS,EAAE,OAAC;aACV,OAAO,EAAE;aACT,QAAQ,EAAE;aACV,QAAQ,CAAC,gDAAgD,CAAC;KAC5D,CAAC,CACF;SACA,MAAM,CACN,OAAC,CAAC,MAAM,CAAC;QACR,OAAO,EAAE,OAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,CAAC,kCAAkC,CAAC;KACjE,CAAC,CACF;SACA,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE;QACxB,MAAM,UAAU,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC;QACtF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC1B,CAAC,CAAC;SACD,KAAK,EAAE,CAAC;AACX,CAAC"}

package/dist/workspace/types.d.ts

@@ -0,0 +1,178 @@
+import type { SandboxProcessManager } from './process';
+export type ProviderStatus = 'pending' | 'initializing' | 'ready' | 'starting' | 'running' | 'stopping' | 'stopped' | 'destroying' | 'destroyed' | 'error';
+export type FileContent = string | Buffer | Uint8Array;
+export interface FileEntry {
+    name: string;
+    type: 'file' | 'directory';
+    size?: number;
+}
+export interface FileStat {
+    name: string;
+    path: string;
+    type: 'file' | 'directory';
+    size: number;
+    createdAt: Date;
+    modifiedAt: Date;
+}
+export interface ReadOptions {
+    encoding?: BufferEncoding;
+}
+export interface WriteOptions {
+    recursive?: boolean;
+    overwrite?: boolean;
+}
+export interface ListOptions {
+    recursive?: boolean;
+    extension?: string;
+}
+export interface RemoveOptions {
+    recursive?: boolean;
+    force?: boolean;
+}
+export interface CopyOptions {
+    overwrite?: boolean;
+    recursive?: boolean;
+}
+export interface MountConfig {
+    type: 'local';
+    basePath: string;
+}
+export interface WorkspaceFilesystem {
+    readonly id: string;
+    readonly name: string;
+    readonly provider: string;
+    readonly readOnly?: boolean;
+    readonly basePath?: string;
+    status: ProviderStatus;
+    readFile(path: string, options?: ReadOptions): Promise<string | Buffer>;
+    writeFile(path: string, content: FileContent, options?: WriteOptions): Promise<void>;
+    appendFile(path: string, content: FileContent): Promise<void>;
+    deleteFile(path: string, options?: RemoveOptions): Promise<void>;
+    copyFile(src: string, dest: string, options?: CopyOptions): Promise<void>;
+    moveFile(src: string, dest: string, options?: CopyOptions): Promise<void>;
+    mkdir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    rmdir(path: string, options?: RemoveOptions): Promise<void>;
+    readdir(path: string, options?: ListOptions): Promise<FileEntry[]>;
+    exists(path: string): Promise<boolean>;
+    stat(path: string): Promise<FileStat>;
+    init?(): Promise<void>;
+    destroy?(): Promise<void>;
+    _init?(): Promise<void>;
+    _destroy?(): Promise<void>;
+    getInstructions?(): string;
+    getMountConfig?(): MountConfig;
+}
+export interface CommandResult {
+    success: boolean;
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    executionTimeMs: number;
+    timedOut?: boolean;
+    killed?: boolean;
+    command?: string;
+    args?: string[];
+}
+export interface CommandOptions {
+    timeout?: number;
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    onStdout?: (data: string) => void;
+    onStderr?: (data: string) => void;
+    abortSignal?: AbortSignal;
+}
+export type ExecuteCommandOptions = CommandOptions;
+export interface SandboxInfo {
+    id: string;
+    name: string;
+    provider: string;
+    status: ProviderStatus;
+    createdAt?: Date;
+    resources?: {
+        memoryMB?: number;
+        cpuCores?: number;
+    };
+    metadata?: Record<string, unknown>;
+}
+export interface WorkspaceSandbox {
+    readonly id: string;
+    readonly name: string;
+    readonly provider: string;
+    status: ProviderStatus;
+    getInstructions?(): string;
+    executeCommand?(command: string, args?: string[], options?: ExecuteCommandOptions): Promise<CommandResult>;
+    readonly processes?: SandboxProcessManager;
+    start?(): Promise<void>;
+    stop?(): Promise<void>;
+    destroy?(): Promise<void>;
+    _start?(): Promise<void>;
+    _stop?(): Promise<void>;
+    _destroy?(): Promise<void>;
+}
+export type SpawnProcessOptions = CommandOptions;
+export interface ProcessInfo {
+    pid: number;
+    command?: string;
+    exitCode?: number;
+}
+export { SandboxProcessManager, ProcessHandle } from './process';
+export interface BaseSandboxOptions {
+    processes?: SandboxProcessManager;
+    onStart?: (args: {
+        sandbox: WorkspaceSandbox;
+    }) => void | Promise<void>;
+    onStop?: (args: {
+        sandbox: WorkspaceSandbox;
+    }) => void | Promise<void>;
+    onDestroy?: (args: {
+        sandbox: WorkspaceSandbox;
+    }) => void | Promise<void>;
+}
+export interface LocalFilesystemOptions {
+    id?: string;
+    basePath: string;
+    contained?: boolean;
+    readOnly?: boolean;
+    instructions?: string;
+}
+export interface LocalSandboxOptions {
+    id?: string;
+    workingDirectory?: string;
+    env?: NodeJS.ProcessEnv;
+    timeout?: number;
+    instructions?: string;
+}
+export interface DaytonaSandboxOptions {
+    id?: string;
+    apiKey?: string;
+    apiUrl?: string;
+    timeout?: number;
+    language?: 'typescript' | 'javascript' | 'python';
+    resources?: {
+        cpu?: number;
+        memory?: number;
+        disk?: number;
+    };
+    env?: Record<string, string>;
+    labels?: Record<string, string>;
+    snapshot?: string;
+    image?: string;
+    ephemeral?: boolean;
+    autoStopInterval?: number;
+    name?: string;
+    networkBlockAll?: boolean;
+    networkAllowList?: string;
+}
+export interface WorkspaceConfig {
+    id?: string;
+    name?: string;
+    filesystem?: WorkspaceFilesystem;
+    sandbox?: WorkspaceSandbox;
+}
+export interface MountResult {
+    success: boolean;
+    mountPath: string;
+    error?: string;
+}

package/dist/workspace/types.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProcessHandle = exports.SandboxProcessManager = void 0;
+var process_1 = require("./process");
+Object.defineProperty(exports, "SandboxProcessManager", { enumerable: true, get: function () { return process_1.SandboxProcessManager; } });
+Object.defineProperty(exports, "ProcessHandle", { enumerable: true, get: function () { return process_1.ProcessHandle; } });
+//# sourceMappingURL=types.js.map

package/dist/workspace/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/workspace/types.ts"],"names":[],"mappings":";;;AAwJA,qCAAiE;AAAxD,gHAAA,qBAAqB,OAAA;AAAE,wGAAA,aAAa,OAAA"}

package/dist/workspace/workspace.d.ts

@@ -0,0 +1,21 @@
+import type { WorkspaceConfig, WorkspaceFilesystem, WorkspaceSandbox, ProviderStatus } from './types';
+import type { BuiltTool } from '../types/sdk/tool';
+export declare class Workspace {
+    readonly id: string;
+    readonly name: string;
+    private _status;
+    private filesystemInstance?;
+    private sandboxInstance?;
+    private initPromise?;
+    private destroyPromise?;
+    constructor(config: WorkspaceConfig);
+    get status(): ProviderStatus;
+    get filesystem(): WorkspaceFilesystem | undefined;
+    get sandbox(): WorkspaceSandbox | undefined;
+    init(): Promise<void>;
+    destroy(): Promise<void>;
+    getInstructions(): string;
+    getTools(): BuiltTool[];
+    private performInit;
+    private performDestroy;
+}

package/dist/workspace/workspace.js

@@ -0,0 +1,131 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Workspace = void 0;
+const node_crypto_1 = require("node:crypto");
+const lifecycle_1 = require("./lifecycle");
+const workspace_tools_1 = require("./tools/workspace-tools");
+class Workspace {
+    constructor(config) {
+        this._status = 'pending';
+        this.id = config.id ?? `workspace-${(0, node_crypto_1.randomUUID)()}`;
+        this.name = config.name ?? `workspace-${this.id}`;
+        this.filesystemInstance = config.filesystem;
+        this.sandboxInstance = config.sandbox;
+    }
+    get status() {
+        return this._status;
+    }
+    get filesystem() {
+        return this.filesystemInstance;
+    }
+    get sandbox() {
+        return this.sandboxInstance;
+    }
+    async init() {
+        if (this._status === 'ready')
+            return;
+        if (this._status === 'destroyed') {
+            throw new Error(`Workspace "${this.id}" has been destroyed and cannot be re-initialized`);
+        }
+        if (this.initPromise)
+            return await this.initPromise;
+        this._status = 'initializing';
+        this.initPromise = this.performInit();
+        try {
+            await this.initPromise;
+        }
+        finally {
+            this.initPromise = undefined;
+        }
+    }
+    async destroy() {
+        if (this.destroyPromise)
+            return await this.destroyPromise;
+        if (this.initPromise) {
+            try {
+                await this.initPromise;
+            }
+            catch {
+            }
+        }
+        this.destroyPromise = this.performDestroy();
+        try {
+            await this.destroyPromise;
+        }
+        finally {
+            this.destroyPromise = undefined;
+        }
+    }
+    getInstructions() {
+        const parts = [];
+        if (this.sandboxInstance?.getInstructions) {
+            const instructions = this.sandboxInstance.getInstructions();
+            if (instructions)
+                parts.push(instructions);
+        }
+        if (this.filesystemInstance?.getInstructions) {
+            const instructions = this.filesystemInstance.getInstructions();
+            if (instructions)
+                parts.push(instructions);
+        }
+        return parts.join('\n\n');
+    }
+    getTools() {
+        return (0, workspace_tools_1.createWorkspaceTools)(this);
+    }
+    async performInit() {
+        try {
+            if (this.filesystemInstance) {
+                await (0, lifecycle_1.callLifecycle)(this.filesystemInstance, 'init');
+            }
+            if (this.sandboxInstance) {
+                await (0, lifecycle_1.callLifecycle)(this.sandboxInstance, 'start');
+            }
+        }
+        catch (error) {
+            if (this.filesystemInstance) {
+                try {
+                    await (0, lifecycle_1.callLifecycle)(this.filesystemInstance, 'destroy');
+                }
+                catch {
+                }
+            }
+            if (this.sandboxInstance) {
+                try {
+                    await (0, lifecycle_1.callLifecycle)(this.sandboxInstance, 'destroy');
+                }
+                catch {
+                }
+            }
+            this._status = 'error';
+            throw error;
+        }
+        this._status = 'ready';
+    }
+    async performDestroy() {
+        let firstError;
+        if (this.sandboxInstance) {
+            try {
+                await (0, lifecycle_1.callLifecycle)(this.sandboxInstance, 'destroy');
+            }
+            catch (error) {
+                firstError = error;
+            }
+        }
+        if (this.filesystemInstance) {
+            try {
+                await (0, lifecycle_1.callLifecycle)(this.filesystemInstance, 'destroy');
+            }
+            catch (error) {
+                firstError ??= error;
+            }
+        }
+        this._status = 'destroyed';
+        if (firstError) {
+            this._status = 'error';
+            throw firstError;
+        }
+    }
+}
+exports.Workspace = Workspace;
+//# sourceMappingURL=workspace.js.map

package/dist/workspace/workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../../src/workspace/workspace.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@n8n/agents",
+  "version": "0.1.0",
+  "description": "AI agent SDK for n8n's code-first execution engine",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/**/*"
+  ],
+  "dependencies": {
+    "@ai-sdk/anthropic": "^3.0.58",
+    "@ai-sdk/google": "^3.0.43",
+    "@ai-sdk/openai": "^3.0.41",
+    "@ai-sdk/xai": "^3.0.67",
+    "@ai-sdk/provider-utils": "^4.0.21",
+    "@modelcontextprotocol/sdk": "1.26.0",
+    "ajv": "^8.18.0",
+    "@libsql/client": "^0.17.0",
+    "ai": "^6.0.116",
+    "pg": "8.17.0",
+    "zod": "3.25.67"
+  },
+  "peerDependencies": {
+    "langsmith": ">=0.3.0",
+    "@opentelemetry/sdk-trace-node": ">=1.0.0",
+    "@opentelemetry/sdk-trace-base": ">=1.0.0",
+    "@opentelemetry/exporter-trace-otlp-http": ">=0.50.0"
+  },
+  "peerDependenciesMeta": {
+    "langsmith": {
+      "optional": true
+    },
+    "@opentelemetry/sdk-trace-node": {
+      "optional": true
+    },
+    "@opentelemetry/sdk-trace-base": {
+      "optional": true
+    },
+    "@opentelemetry/exporter-trace-otlp-http": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/json-schema": "^7.0.15",
+    "@types/pg": "^8.15.6",
+    "testcontainers": "11.11.0",
+    "@n8n/typescript-config": "1.3.0"
+  },
+  "scripts": {
+    "clean": "rimraf dist .turbo",
+    "dev": "pnpm watch",
+    "typecheck": "tsc --noEmit",
+    "build": "rimraf dist && tsc -p tsconfig.build.json",
+    "format": "biome format --write src examples",
+    "format:check": "biome ci src examples",
+    "lint": "eslint . --quiet",
+    "lint:fix": "eslint . --fix",
+    "watch": "tsc -p tsconfig.build.json --watch",
+    "test": "jest",
+    "test:unit": "jest",
+    "test:dev": "jest --watch",
+    "test:integration": "vitest run --config vitest.integration.config.mjs"
+  }
+}