agent-neckbeard 1.0.3 → 1.0.4

package/dist/index.cjs

@@ -31,7 +31,12 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   Agent: () => Agent,
-  DEFAULT_DEPENDENCIES: () => DEFAULT_DEPENDENCIES
+  ConfigurationError: () => ConfigurationError,
+  DEFAULT_DEPENDENCIES: () => DEFAULT_DEPENDENCIES,
+  DeploymentError: () => DeploymentError,
+  ExecutionError: () => ExecutionError,
+  NeckbeardError: () => NeckbeardError,
+  ValidationError: () => ValidationError
 });
 module.exports = __toCommonJS(index_exports);
 var import_node_url = require("url");
@@ -39,7 +44,67 @@ var import_node_fs = require("fs");
 var import_node_path = require("path");
 var getEsbuild = () => import("esbuild");
 var getE2b = () => import("e2b");
+var DEFAULT_MAX_DURATION = 300;
+var SANDBOX_COMMAND_TIMEOUT_MS = 3e5;
+var QUICK_COMMAND_TIMEOUT_MS = 3e4;
+var NODE_TARGET = "node20";
+var SANDBOX_HOME = "/home/user";
+var SANDBOX_PATHS = {
+  input: `${SANDBOX_HOME}/input`,
+  output: `${SANDBOX_HOME}/output`,
+  taskJson: `${SANDBOX_HOME}/input/task.json`,
+  resultJson: `${SANDBOX_HOME}/output/result.json`,
+  agentModule: `${SANDBOX_HOME}/agent.mjs`,
+  runnerModule: `${SANDBOX_HOME}/runner.mjs`,
+  claudeDir: `${SANDBOX_HOME}/.claude`,
+  packageJson: `${SANDBOX_HOME}/package.json`
+};
+var NeckbeardError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "NeckbeardError";
+  }
+};
+var DeploymentError = class extends NeckbeardError {
+  constructor(message, cause) {
+    super(message);
+    this.cause = cause;
+    this.name = "DeploymentError";
+  }
+};
+var ValidationError = class extends NeckbeardError {
+  constructor(message, cause) {
+    super(message);
+    this.cause = cause;
+    this.name = "ValidationError";
+  }
+};
+var ExecutionError = class extends NeckbeardError {
+  constructor(message, cause) {
+    super(message);
+    this.cause = cause;
+    this.name = "ExecutionError";
+  }
+};
+var ConfigurationError = class extends NeckbeardError {
+  constructor(message) {
+    super(message);
+    this.name = "ConfigurationError";
+  }
+};
 var DEFAULT_DEPENDENCIES = {};
+function requireEnv(name) {
+  const value = process.env[name];
+  if (!value) {
+    throw new ConfigurationError(
+      `${name} environment variable is required. Please set it before calling deploy() or run().`
+    );
+  }
+  return value;
+}
+function shellEscape(str) {
+  return `'${str.replace(/'/g, "'\\''")}'`;
+}
 function getCallerFile() {
   const stack = new Error().stack?.split("\n") ?? [];
   for (const line of stack.slice(2)) {
@@ -93,7 +158,7 @@ var Agent = class {
     this.id = config.id;
     this.inputSchema = config.inputSchema;
     this.outputSchema = config.outputSchema;
-    this.maxDuration = config.maxDuration ?? 300;
+    this.maxDuration = config.maxDuration ?? DEFAULT_MAX_DURATION;
     this._run = config.run;
     this._sourceFile = getCallerFile();
     this._sandboxId = config.sandboxId;
@@ -104,8 +169,29 @@ var Agent = class {
   get sandboxId() {
     return this._sandboxId;
   }
+  /**
+   * Deploys the agent to an E2B sandbox.
+   *
+   * This method bundles the agent code using esbuild, creates a new E2B sandbox,
+   * installs any specified OS dependencies, downloads configured files, and
+   * uploads the agent code to the sandbox.
+   *
+   * The sandbox ID is stored and can be accessed via the `sandboxId` property
+   * after deployment completes.
+   *
+   * @throws {ConfigurationError} If E2B_API_KEY environment variable is not set
+   * @throws {DeploymentError} If sandbox creation, dependency installation, or file upload fails
+   *
+   * @example
+   * ```typescript
+   * const agent = new Agent({ ... });
+   * await agent.deploy();
+   * console.log(`Deployed to sandbox: ${agent.sandboxId}`);
+   * ```
+   */
   async deploy() {
     if (this._sandboxId) return;
+    const e2bApiKey = requireEnv("E2B_API_KEY");
     const esbuild = await getEsbuild();
     const { Sandbox } = await getE2b();
     const collectedExternals = /* @__PURE__ */ new Set();
@@ -117,13 +203,20 @@ var Agent = class {
       entryPoints: [this._sourceFile],
       bundle: true,
       platform: "node",
-      target: "node20",
+      target: NODE_TARGET,
       format: "esm",
       write: false,
       minify: true,
       keepNames: true,
       treeShaking: false,
       // Preserve exports for the sandbox runner to import
+      banner: {
+        js: `import { fileURLToPath as __neckbeard_fileURLToPath } from 'node:url';
+import { dirname as __neckbeard_dirname } from 'node:path';
+const __filename = __neckbeard_fileURLToPath(import.meta.url);
+const __dirname = __neckbeard_dirname(__filename);
+`
+      },
       plugins: [{
         name: "agent-neckbeard-externals",
         setup(build) {
@@ -196,52 +289,52 @@ try {
 }
 `;
     const sandbox = await Sandbox.create("base", {
-      apiKey: process.env.E2B_API_KEY
+      apiKey: e2bApiKey
     });
     const { apt, commands } = this.dependencies;
     if (apt && apt.length > 0) {
       const aptCmd = `sudo apt-get update && sudo apt-get install -y ${apt.join(" ")}`;
-      const aptResult = await sandbox.commands.run(aptCmd, { timeoutMs: 3e5 });
+      const aptResult = await sandbox.commands.run(aptCmd, { timeoutMs: SANDBOX_COMMAND_TIMEOUT_MS });
       if (aptResult.exitCode !== 0) {
-        throw new Error(`Failed to install apt packages: ${aptResult.stderr}`);
+        throw new DeploymentError(`Failed to install apt packages: ${aptResult.stderr}`);
       }
     }
     if (commands && commands.length > 0) {
       for (const cmd of commands) {
-        const cmdResult = await sandbox.commands.run(cmd, { timeoutMs: 3e5 });
+        const cmdResult = await sandbox.commands.run(cmd, { timeoutMs: SANDBOX_COMMAND_TIMEOUT_MS });
         if (cmdResult.exitCode !== 0) {
-          throw new Error(`Failed to run command "${cmd}": ${cmdResult.stderr}`);
+          throw new DeploymentError(`Failed to run command "${cmd}": ${cmdResult.stderr}`);
         }
       }
     }
     if (this.files.length > 0) {
       for (const file of this.files) {
-        const destPath = file.path.startsWith("/") ? file.path : `/home/user/${file.path}`;
+        const destPath = file.path.startsWith("/") ? file.path : `${SANDBOX_HOME}/${file.path}`;
         const parentDir = destPath.substring(0, destPath.lastIndexOf("/"));
         if (parentDir) {
-          await sandbox.commands.run(`mkdir -p "${parentDir}"`, { timeoutMs: 3e4 });
+          await sandbox.commands.run(`mkdir -p ${shellEscape(parentDir)}`, { timeoutMs: QUICK_COMMAND_TIMEOUT_MS });
         }
-        const curlCmd = `curl -fsSL -o "${destPath}" "${file.url}"`;
-        const downloadResult = await sandbox.commands.run(curlCmd, { timeoutMs: 3e5 });
+        const curlCmd = `curl -fsSL -o ${shellEscape(destPath)} ${shellEscape(file.url)}`;
+        const downloadResult = await sandbox.commands.run(curlCmd, { timeoutMs: SANDBOX_COMMAND_TIMEOUT_MS });
         if (downloadResult.exitCode !== 0) {
-          throw new Error(`Failed to download file from ${file.url} to ${destPath}: ${downloadResult.stderr}`);
+          throw new DeploymentError(`Failed to download file from ${file.url} to ${destPath}: ${downloadResult.stderr}`);
         }
       }
     }
     if (this.claudeDir) {
       const claudeFiles = readDirectoryRecursively(this.claudeDir);
-      await sandbox.commands.run("mkdir -p /home/user/.claude", { timeoutMs: 3e4 });
+      await sandbox.commands.run(`mkdir -p ${SANDBOX_PATHS.claudeDir}`, { timeoutMs: QUICK_COMMAND_TIMEOUT_MS });
       for (const file of claudeFiles) {
-        const destPath = `/home/user/.claude/${file.relativePath}`;
+        const destPath = `${SANDBOX_PATHS.claudeDir}/${file.relativePath}`;
         const parentDir = destPath.substring(0, destPath.lastIndexOf("/"));
-        if (parentDir && parentDir !== "/home/user/.claude") {
-          await sandbox.commands.run(`mkdir -p "${parentDir}"`, { timeoutMs: 3e4 });
+        if (parentDir && parentDir !== SANDBOX_PATHS.claudeDir) {
+          await sandbox.commands.run(`mkdir -p ${shellEscape(parentDir)}`, { timeoutMs: QUICK_COMMAND_TIMEOUT_MS });
         }
         await sandbox.files.write(destPath, file.content);
       }
     }
-    await sandbox.files.write("/home/user/agent.mjs", result.outputFiles[0].text);
-    await sandbox.files.write("/home/user/runner.mjs", runnerCode);
+    await sandbox.files.write(SANDBOX_PATHS.agentModule, result.outputFiles[0].text);
+    await sandbox.files.write(SANDBOX_PATHS.runnerModule, runnerCode);
     if (collectedExternals.size > 0) {
       const dependencies = {};
       for (const pkg of collectedExternals) {
@@ -252,42 +345,64 @@ try {
         type: "module",
         dependencies
       });
-      await sandbox.files.write("/home/user/package.json", pkgJson);
-      const installResult = await sandbox.commands.run("cd /home/user && npm install", { timeoutMs: 3e5 });
+      await sandbox.files.write(SANDBOX_PATHS.packageJson, pkgJson);
+      const installResult = await sandbox.commands.run(`cd ${SANDBOX_HOME} && npm install`, { timeoutMs: SANDBOX_COMMAND_TIMEOUT_MS });
       if (installResult.exitCode !== 0) {
-        throw new Error(`Failed to install external packages: ${installResult.stderr}`);
+        throw new DeploymentError(`Failed to install external packages: ${installResult.stderr}`);
       }
     }
     this._sandboxId = sandbox.sandboxId;
   }
+  /**
+   * Executes the agent with the given input.
+   *
+   * The agent must be deployed before calling this method. Input is validated
+   * against the input schema, then the agent runs in the sandbox with the
+   * validated input. Output is validated against the output schema before
+   * being returned.
+   *
+   * @param input - The input data for the agent, must conform to inputSchema
+   * @returns A result object indicating success or failure with output or error
+   *
+   * @example
+   * ```typescript
+   * const result = await agent.run({ prompt: 'Hello, world!' });
+   * if (result.ok) {
+   *   console.log('Output:', result.output);
+   * } else {
+   *   console.error('Error:', result.error.message);
+   * }
+   * ```
+   */
   async run(input) {
     const executionId = `exec_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
     if (!this._sandboxId) {
       return {
         ok: false,
         executionId,
-        error: new Error("Agent not deployed. Call agent.deploy() first or pass sandboxId to constructor.")
+        error: new ExecutionError("Agent not deployed. Call agent.deploy() first or pass sandboxId to constructor.")
       };
     }
     try {
+      const e2bApiKey = requireEnv("E2B_API_KEY");
       const { Sandbox } = await getE2b();
       const validatedInput = this.inputSchema.parse(input);
       const sandbox = await Sandbox.connect(this._sandboxId, {
-        apiKey: process.env.E2B_API_KEY
+        apiKey: e2bApiKey
       });
-      await sandbox.files.write("/home/user/input/task.json", JSON.stringify({ input: validatedInput, executionId }));
-      const result = await sandbox.commands.run("node /home/user/runner.mjs", {
+      await sandbox.files.write(SANDBOX_PATHS.taskJson, JSON.stringify({ input: validatedInput, executionId }));
+      const result = await sandbox.commands.run(`node ${SANDBOX_PATHS.runnerModule}`, {
         timeoutMs: this.maxDuration * 1e3,
         envs: {
           ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY ?? ""
         }
       });
       if (result.exitCode !== 0) {
-        return { ok: false, executionId, error: new Error(`Agent failed: ${result.stderr}`) };
+        return { ok: false, executionId, error: new ExecutionError(`Agent failed: ${result.stderr}`) };
       }
-      const output = JSON.parse(await sandbox.files.read("/home/user/output/result.json"));
+      const output = JSON.parse(await sandbox.files.read(SANDBOX_PATHS.resultJson));
       if (!output.success) {
-        const err = new Error(output.error.message);
+        const err = new ExecutionError(output.error.message);
         err.stack = output.error.stack;
         return { ok: false, executionId, error: err };
       }
@@ -300,5 +415,10 @@ try {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Agent,
-  DEFAULT_DEPENDENCIES
+  ConfigurationError,
+  DEFAULT_DEPENDENCIES,
+  DeploymentError,
+  ExecutionError,
+  NeckbeardError,
+  ValidationError
 });

package/dist/index.d.cts

@@ -1,6 +1,41 @@
 /**
  * agent-neckbeard - Deploy AI agents to E2B sandboxes
  */
+/**
+ * Base error class for agent-neckbeard errors.
+ * All custom errors extend this class.
+ */
+declare class NeckbeardError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when sandbox deployment fails.
+ * This includes sandbox creation, dependency installation, and file upload failures.
+ */
+declare class DeploymentError extends NeckbeardError {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+/**
+ * Error thrown when input or output schema validation fails.
+ */
+declare class ValidationError extends NeckbeardError {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+/**
+ * Error thrown when agent execution fails in the sandbox.
+ */
+declare class ExecutionError extends NeckbeardError {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+/**
+ * Error thrown when required environment variables are missing.
+ */
+declare class ConfigurationError extends NeckbeardError {
+    constructor(message: string);
+}
 interface AgentRunContext {
     executionId: string;
     signal: AbortSignal;
@@ -19,7 +54,7 @@ type AgentRunResult<TOutput> = {
 } | {
     ok: false;
     executionId: string;
-    error: Error;
+    error: Error | NeckbeardError;
 };
 interface SchemaLike<T> {
     parse: (data: unknown) => T;
@@ -91,8 +126,49 @@ declare class Agent<TInput, TOutput> {
     private _sandboxId?;
     constructor(config: AgentConfig<TInput, TOutput>);
     get sandboxId(): string | undefined;
+    /**
+     * Deploys the agent to an E2B sandbox.
+     *
+     * This method bundles the agent code using esbuild, creates a new E2B sandbox,
+     * installs any specified OS dependencies, downloads configured files, and
+     * uploads the agent code to the sandbox.
+     *
+     * The sandbox ID is stored and can be accessed via the `sandboxId` property
+     * after deployment completes.
+     *
+     * @throws {ConfigurationError} If E2B_API_KEY environment variable is not set
+     * @throws {DeploymentError} If sandbox creation, dependency installation, or file upload fails
+     *
+     * @example
+     * ```typescript
+     * const agent = new Agent({ ... });
+     * await agent.deploy();
+     * console.log(`Deployed to sandbox: ${agent.sandboxId}`);
+     * ```
+     */
     deploy(): Promise<void>;
+    /**
+     * Executes the agent with the given input.
+     *
+     * The agent must be deployed before calling this method. Input is validated
+     * against the input schema, then the agent runs in the sandbox with the
+     * validated input. Output is validated against the output schema before
+     * being returned.
+     *
+     * @param input - The input data for the agent, must conform to inputSchema
+     * @returns A result object indicating success or failure with output or error
+     *
+     * @example
+     * ```typescript
+     * const result = await agent.run({ prompt: 'Hello, world!' });
+     * if (result.ok) {
+     *   console.log('Output:', result.output);
+     * } else {
+     *   console.error('Error:', result.error.message);
+     * }
+     * ```
+     */
     run(input: TInput): Promise<AgentRunResult<TOutput>>;
 }
 
-export { Agent, type AgentConfig, type AgentRunContext, type AgentRunResult, DEFAULT_DEPENDENCIES, type FileDownload, type OsDependencies };
+export { Agent, type AgentConfig, type AgentRunContext, type AgentRunResult, ConfigurationError, DEFAULT_DEPENDENCIES, DeploymentError, ExecutionError, type FileDownload, NeckbeardError, type OsDependencies, ValidationError };

package/dist/index.d.ts

@@ -1,6 +1,41 @@
 /**
  * agent-neckbeard - Deploy AI agents to E2B sandboxes
  */
+/**
+ * Base error class for agent-neckbeard errors.
+ * All custom errors extend this class.
+ */
+declare class NeckbeardError extends Error {
+    constructor(message: string);
+}
+/**
+ * Error thrown when sandbox deployment fails.
+ * This includes sandbox creation, dependency installation, and file upload failures.
+ */
+declare class DeploymentError extends NeckbeardError {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+/**
+ * Error thrown when input or output schema validation fails.
+ */
+declare class ValidationError extends NeckbeardError {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+/**
+ * Error thrown when agent execution fails in the sandbox.
+ */
+declare class ExecutionError extends NeckbeardError {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+/**
+ * Error thrown when required environment variables are missing.
+ */
+declare class ConfigurationError extends NeckbeardError {
+    constructor(message: string);
+}
 interface AgentRunContext {
     executionId: string;
     signal: AbortSignal;
@@ -19,7 +54,7 @@ type AgentRunResult<TOutput> = {
 } | {
     ok: false;
     executionId: string;
-    error: Error;
+    error: Error | NeckbeardError;
 };
 interface SchemaLike<T> {
     parse: (data: unknown) => T;
@@ -91,8 +126,49 @@ declare class Agent<TInput, TOutput> {
     private _sandboxId?;
     constructor(config: AgentConfig<TInput, TOutput>);
     get sandboxId(): string | undefined;
+    /**
+     * Deploys the agent to an E2B sandbox.
+     *
+     * This method bundles the agent code using esbuild, creates a new E2B sandbox,
+     * installs any specified OS dependencies, downloads configured files, and
+     * uploads the agent code to the sandbox.
+     *
+     * The sandbox ID is stored and can be accessed via the `sandboxId` property
+     * after deployment completes.
+     *
+     * @throws {ConfigurationError} If E2B_API_KEY environment variable is not set
+     * @throws {DeploymentError} If sandbox creation, dependency installation, or file upload fails
+     *
+     * @example
+     * ```typescript
+     * const agent = new Agent({ ... });
+     * await agent.deploy();
+     * console.log(`Deployed to sandbox: ${agent.sandboxId}`);
+     * ```
+     */
     deploy(): Promise<void>;
+    /**
+     * Executes the agent with the given input.
+     *
+     * The agent must be deployed before calling this method. Input is validated
+     * against the input schema, then the agent runs in the sandbox with the
+     * validated input. Output is validated against the output schema before
+     * being returned.
+     *
+     * @param input - The input data for the agent, must conform to inputSchema
+     * @returns A result object indicating success or failure with output or error
+     *
+     * @example
+     * ```typescript
+     * const result = await agent.run({ prompt: 'Hello, world!' });
+     * if (result.ok) {
+     *   console.log('Output:', result.output);
+     * } else {
+     *   console.error('Error:', result.error.message);
+     * }
+     * ```
+     */
     run(input: TInput): Promise<AgentRunResult<TOutput>>;
 }
 
-export { Agent, type AgentConfig, type AgentRunContext, type AgentRunResult, DEFAULT_DEPENDENCIES, type FileDownload, type OsDependencies };
+export { Agent, type AgentConfig, type AgentRunContext, type AgentRunResult, ConfigurationError, DEFAULT_DEPENDENCIES, DeploymentError, ExecutionError, type FileDownload, NeckbeardError, type OsDependencies, ValidationError };

package/dist/index.js

@@ -4,7 +4,67 @@ import { readdirSync, readFileSync, statSync } from "fs";
 import { join, relative } from "path";
 var getEsbuild = () => import("esbuild");
 var getE2b = () => import("e2b");
+var DEFAULT_MAX_DURATION = 300;
+var SANDBOX_COMMAND_TIMEOUT_MS = 3e5;
+var QUICK_COMMAND_TIMEOUT_MS = 3e4;
+var NODE_TARGET = "node20";
+var SANDBOX_HOME = "/home/user";
+var SANDBOX_PATHS = {
+  input: `${SANDBOX_HOME}/input`,
+  output: `${SANDBOX_HOME}/output`,
+  taskJson: `${SANDBOX_HOME}/input/task.json`,
+  resultJson: `${SANDBOX_HOME}/output/result.json`,
+  agentModule: `${SANDBOX_HOME}/agent.mjs`,
+  runnerModule: `${SANDBOX_HOME}/runner.mjs`,
+  claudeDir: `${SANDBOX_HOME}/.claude`,
+  packageJson: `${SANDBOX_HOME}/package.json`
+};
+var NeckbeardError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "NeckbeardError";
+  }
+};
+var DeploymentError = class extends NeckbeardError {
+  constructor(message, cause) {
+    super(message);
+    this.cause = cause;
+    this.name = "DeploymentError";
+  }
+};
+var ValidationError = class extends NeckbeardError {
+  constructor(message, cause) {
+    super(message);
+    this.cause = cause;
+    this.name = "ValidationError";
+  }
+};
+var ExecutionError = class extends NeckbeardError {
+  constructor(message, cause) {
+    super(message);
+    this.cause = cause;
+    this.name = "ExecutionError";
+  }
+};
+var ConfigurationError = class extends NeckbeardError {
+  constructor(message) {
+    super(message);
+    this.name = "ConfigurationError";
+  }
+};
 var DEFAULT_DEPENDENCIES = {};
+function requireEnv(name) {
+  const value = process.env[name];
+  if (!value) {
+    throw new ConfigurationError(
+      `${name} environment variable is required. Please set it before calling deploy() or run().`
+    );
+  }
+  return value;
+}
+function shellEscape(str) {
+  return `'${str.replace(/'/g, "'\\''")}'`;
+}
 function getCallerFile() {
   const stack = new Error().stack?.split("\n") ?? [];
   for (const line of stack.slice(2)) {
@@ -58,7 +118,7 @@ var Agent = class {
     this.id = config.id;
     this.inputSchema = config.inputSchema;
     this.outputSchema = config.outputSchema;
-    this.maxDuration = config.maxDuration ?? 300;
+    this.maxDuration = config.maxDuration ?? DEFAULT_MAX_DURATION;
     this._run = config.run;
     this._sourceFile = getCallerFile();
     this._sandboxId = config.sandboxId;
@@ -69,8 +129,29 @@ var Agent = class {
   get sandboxId() {
     return this._sandboxId;
   }
+  /**
+   * Deploys the agent to an E2B sandbox.
+   *
+   * This method bundles the agent code using esbuild, creates a new E2B sandbox,
+   * installs any specified OS dependencies, downloads configured files, and
+   * uploads the agent code to the sandbox.
+   *
+   * The sandbox ID is stored and can be accessed via the `sandboxId` property
+   * after deployment completes.
+   *
+   * @throws {ConfigurationError} If E2B_API_KEY environment variable is not set
+   * @throws {DeploymentError} If sandbox creation, dependency installation, or file upload fails
+   *
+   * @example
+   * ```typescript
+   * const agent = new Agent({ ... });
+   * await agent.deploy();
+   * console.log(`Deployed to sandbox: ${agent.sandboxId}`);
+   * ```
+   */
   async deploy() {
     if (this._sandboxId) return;
+    const e2bApiKey = requireEnv("E2B_API_KEY");
     const esbuild = await getEsbuild();
     const { Sandbox } = await getE2b();
     const collectedExternals = /* @__PURE__ */ new Set();
@@ -82,13 +163,20 @@ var Agent = class {
       entryPoints: [this._sourceFile],
       bundle: true,
       platform: "node",
-      target: "node20",
+      target: NODE_TARGET,
       format: "esm",
       write: false,
       minify: true,
       keepNames: true,
       treeShaking: false,
       // Preserve exports for the sandbox runner to import
+      banner: {
+        js: `import { fileURLToPath as __neckbeard_fileURLToPath } from 'node:url';
+import { dirname as __neckbeard_dirname } from 'node:path';
+const __filename = __neckbeard_fileURLToPath(import.meta.url);
+const __dirname = __neckbeard_dirname(__filename);
+`
+      },
       plugins: [{
         name: "agent-neckbeard-externals",
         setup(build) {
@@ -161,52 +249,52 @@ try {
 }
 `;
     const sandbox = await Sandbox.create("base", {
-      apiKey: process.env.E2B_API_KEY
+      apiKey: e2bApiKey
     });
     const { apt, commands } = this.dependencies;
     if (apt && apt.length > 0) {
       const aptCmd = `sudo apt-get update && sudo apt-get install -y ${apt.join(" ")}`;
-      const aptResult = await sandbox.commands.run(aptCmd, { timeoutMs: 3e5 });
+      const aptResult = await sandbox.commands.run(aptCmd, { timeoutMs: SANDBOX_COMMAND_TIMEOUT_MS });
       if (aptResult.exitCode !== 0) {
-        throw new Error(`Failed to install apt packages: ${aptResult.stderr}`);
+        throw new DeploymentError(`Failed to install apt packages: ${aptResult.stderr}`);
       }
     }
     if (commands && commands.length > 0) {
       for (const cmd of commands) {
-        const cmdResult = await sandbox.commands.run(cmd, { timeoutMs: 3e5 });
+        const cmdResult = await sandbox.commands.run(cmd, { timeoutMs: SANDBOX_COMMAND_TIMEOUT_MS });
         if (cmdResult.exitCode !== 0) {
-          throw new Error(`Failed to run command "${cmd}": ${cmdResult.stderr}`);
+          throw new DeploymentError(`Failed to run command "${cmd}": ${cmdResult.stderr}`);
         }
       }
     }
     if (this.files.length > 0) {
       for (const file of this.files) {
-        const destPath = file.path.startsWith("/") ? file.path : `/home/user/${file.path}`;
+        const destPath = file.path.startsWith("/") ? file.path : `${SANDBOX_HOME}/${file.path}`;
         const parentDir = destPath.substring(0, destPath.lastIndexOf("/"));
         if (parentDir) {
-          await sandbox.commands.run(`mkdir -p "${parentDir}"`, { timeoutMs: 3e4 });
+          await sandbox.commands.run(`mkdir -p ${shellEscape(parentDir)}`, { timeoutMs: QUICK_COMMAND_TIMEOUT_MS });
         }
-        const curlCmd = `curl -fsSL -o "${destPath}" "${file.url}"`;
-        const downloadResult = await sandbox.commands.run(curlCmd, { timeoutMs: 3e5 });
+        const curlCmd = `curl -fsSL -o ${shellEscape(destPath)} ${shellEscape(file.url)}`;
+        const downloadResult = await sandbox.commands.run(curlCmd, { timeoutMs: SANDBOX_COMMAND_TIMEOUT_MS });
         if (downloadResult.exitCode !== 0) {
-          throw new Error(`Failed to download file from ${file.url} to ${destPath}: ${downloadResult.stderr}`);
+          throw new DeploymentError(`Failed to download file from ${file.url} to ${destPath}: ${downloadResult.stderr}`);
         }
       }
     }
     if (this.claudeDir) {
       const claudeFiles = readDirectoryRecursively(this.claudeDir);
-      await sandbox.commands.run("mkdir -p /home/user/.claude", { timeoutMs: 3e4 });
+      await sandbox.commands.run(`mkdir -p ${SANDBOX_PATHS.claudeDir}`, { timeoutMs: QUICK_COMMAND_TIMEOUT_MS });
       for (const file of claudeFiles) {
-        const destPath = `/home/user/.claude/${file.relativePath}`;
+        const destPath = `${SANDBOX_PATHS.claudeDir}/${file.relativePath}`;
         const parentDir = destPath.substring(0, destPath.lastIndexOf("/"));
-        if (parentDir && parentDir !== "/home/user/.claude") {
-          await sandbox.commands.run(`mkdir -p "${parentDir}"`, { timeoutMs: 3e4 });
+        if (parentDir && parentDir !== SANDBOX_PATHS.claudeDir) {
+          await sandbox.commands.run(`mkdir -p ${shellEscape(parentDir)}`, { timeoutMs: QUICK_COMMAND_TIMEOUT_MS });
         }
         await sandbox.files.write(destPath, file.content);
       }
     }
-    await sandbox.files.write("/home/user/agent.mjs", result.outputFiles[0].text);
-    await sandbox.files.write("/home/user/runner.mjs", runnerCode);
+    await sandbox.files.write(SANDBOX_PATHS.agentModule, result.outputFiles[0].text);
+    await sandbox.files.write(SANDBOX_PATHS.runnerModule, runnerCode);
     if (collectedExternals.size > 0) {
       const dependencies = {};
       for (const pkg of collectedExternals) {
@@ -217,42 +305,64 @@ try {
         type: "module",
         dependencies
       });
-      await sandbox.files.write("/home/user/package.json", pkgJson);
-      const installResult = await sandbox.commands.run("cd /home/user && npm install", { timeoutMs: 3e5 });
+      await sandbox.files.write(SANDBOX_PATHS.packageJson, pkgJson);
+      const installResult = await sandbox.commands.run(`cd ${SANDBOX_HOME} && npm install`, { timeoutMs: SANDBOX_COMMAND_TIMEOUT_MS });
       if (installResult.exitCode !== 0) {
-        throw new Error(`Failed to install external packages: ${installResult.stderr}`);
+        throw new DeploymentError(`Failed to install external packages: ${installResult.stderr}`);
       }
     }
     this._sandboxId = sandbox.sandboxId;
   }
+  /**
+   * Executes the agent with the given input.
+   *
+   * The agent must be deployed before calling this method. Input is validated
+   * against the input schema, then the agent runs in the sandbox with the
+   * validated input. Output is validated against the output schema before
+   * being returned.
+   *
+   * @param input - The input data for the agent, must conform to inputSchema
+   * @returns A result object indicating success or failure with output or error
+   *
+   * @example
+   * ```typescript
+   * const result = await agent.run({ prompt: 'Hello, world!' });
+   * if (result.ok) {
+   *   console.log('Output:', result.output);
+   * } else {
+   *   console.error('Error:', result.error.message);
+   * }
+   * ```
+   */
   async run(input) {
     const executionId = `exec_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
     if (!this._sandboxId) {
       return {
         ok: false,
         executionId,
-        error: new Error("Agent not deployed. Call agent.deploy() first or pass sandboxId to constructor.")
+        error: new ExecutionError("Agent not deployed. Call agent.deploy() first or pass sandboxId to constructor.")
       };
     }
     try {
+      const e2bApiKey = requireEnv("E2B_API_KEY");
       const { Sandbox } = await getE2b();
       const validatedInput = this.inputSchema.parse(input);
       const sandbox = await Sandbox.connect(this._sandboxId, {
-        apiKey: process.env.E2B_API_KEY
+        apiKey: e2bApiKey
       });
-      await sandbox.files.write("/home/user/input/task.json", JSON.stringify({ input: validatedInput, executionId }));
-      const result = await sandbox.commands.run("node /home/user/runner.mjs", {
+      await sandbox.files.write(SANDBOX_PATHS.taskJson, JSON.stringify({ input: validatedInput, executionId }));
+      const result = await sandbox.commands.run(`node ${SANDBOX_PATHS.runnerModule}`, {
         timeoutMs: this.maxDuration * 1e3,
         envs: {
           ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY ?? ""
         }
       });
       if (result.exitCode !== 0) {
-        return { ok: false, executionId, error: new Error(`Agent failed: ${result.stderr}`) };
+        return { ok: false, executionId, error: new ExecutionError(`Agent failed: ${result.stderr}`) };
       }
-      const output = JSON.parse(await sandbox.files.read("/home/user/output/result.json"));
+      const output = JSON.parse(await sandbox.files.read(SANDBOX_PATHS.resultJson));
       if (!output.success) {
-        const err = new Error(output.error.message);
+        const err = new ExecutionError(output.error.message);
         err.stack = output.error.stack;
         return { ok: false, executionId, error: err };
       }
@@ -264,5 +374,10 @@ try {
 };
 export {
   Agent,
-  DEFAULT_DEPENDENCIES
+  ConfigurationError,
+  DEFAULT_DEPENDENCIES,
+  DeploymentError,
+  ExecutionError,
+  NeckbeardError,
+  ValidationError
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-neckbeard",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Deploy AI agents to E2B sandboxes",
   "type": "module",
   "exports": {
@@ -16,7 +16,9 @@
     }
   },
   "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
   "types": "./dist/index.d.cts",
+  "sideEffects": false,
   "files": [
     "dist"
   ],
@@ -26,7 +28,8 @@
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "prepare": "npm run build"
   },
   "dependencies": {
     "e2b": "^1.0.0",