neckbeard-agent 0.0.1

package/README.md

@@ -0,0 +1,106 @@
+<img width="1024" height="1024" alt="image" src="https://github.com/user-attachments/assets/52b7f9cf-b9c7-4cae-be11-62273cd1489a" />
+
+# neckbeard
+
+There's a weird thing that happens when you try to deploy an AI agent.
+
+Most people think of agents as fancy API calls. You send a prompt, you get a response. But that's not what's actually happening. The agent is running code. It's executing bash commands, writing files, installing packages. It runs for minutes at a time, maintaining state between steps. It's a process, not a request.
+
+This creates an obvious problem: do you really want that process running on your production server?
+
+Anthropic's answer is no. Their [hosting docs](https://docs.claude.com/en/docs/agent-sdk/hosting) say you should run the entire agent inside a sandbox. Not just intercept the dangerous tool calls—put the whole thing in a container where it can't escape.
+
+That sounds simple. It's not.
+
+## The Plumbing Problem
+
+Sandboxes like E2B give you a fresh Linux container. Your agent code lives in your repo. Bridging these two worlds is surprisingly annoying.
+
+First, you have to get your code into the sandbox. You could bake it into a custom template, but then you're rebuilding templates every time you change a line. You could git clone on boot, but that's slow and requires auth. You could bundle and upload at runtime, which works, but now you're writing bundler configs.
+
+Then you have to pass input. How do you get the user's prompt into a process running inside a sandbox? CLI arguments require escaping and have length limits. Environment variables have size limits. Writing to a file works, but adds boilerplate.
+
+The worst part is output. When you run `sandbox.exec("node agent.js")`, you get back everything the process printed. SDK logs, debug output, streaming tokens, and somewhere in there, your actual result. Good luck parsing that reliably.
+
+So you end up writing results to a file, reading it back, parsing JSON, validating the shape, handling errors. Every team building sandboxed agents writes some version of this plumbing. It's tedious.
+
+## What This Does
+
+Neckbeard handles all of that so you can just write your agent:
+
+```typescript
+import { Agent } from 'neckbeard-agent';
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+
+const agent = new Agent({
+  template: 'code-interpreter-v1',
+  inputSchema: z.object({ topic: z.string() }),
+  outputSchema: z.object({
+    title: z.string(),
+    summary: z.string(),
+    keyPoints: z.array(z.string()),
+  }),
+  run: async (input) => {
+    for await (const message of query({
+      prompt: `Research "${input.topic}" and return JSON`,
+      options: { maxTurns: 10 },
+    })) {
+      if (message.type === 'result') {
+        return JSON.parse(message.result ?? '{}');
+      }
+    }
+  },
+});
+
+await agent.deploy();  // bundles, uploads to E2B
+const result = await agent.run({ topic: 'TypeScript generics' });
+```
+
+`deploy()` bundles your code with esbuild and uploads it. `run()` writes input to a file, executes, reads the result back, and validates it against your schema. You don't think about file paths or stdout parsing.
+
+## Setup
+
+```bash
+npm install neckbeard-agent
+```
+
+```bash
+export E2B_API_KEY=your-key
+export ANTHROPIC_API_KEY=your-key
+```
+
+## The Details
+
+The constructor takes a few options:
+
+```typescript
+new Agent({
+  template: string,             // E2B template (e.g. 'code-interpreter-v1')
+  inputSchema: ZodSchema,
+  outputSchema: ZodSchema,
+  run: (input, ctx) => Promise,
+  maxDuration?: number,        // seconds, default 300
+  sandboxId?: string,          // reuse existing sandbox
+  dependencies?: {
+    apt?: string[],
+    commands?: string[],
+  },
+  files?: [{ url, path }],     // pre-download into sandbox
+  claudeDir?: string,          // upload .claude/ skills directory
+})
+```
+
+If you already have a sandbox deployed, pass `sandboxId` and skip `deploy()`.
+
+The `files` option downloads things into the sandbox before your agent runs—useful for models or config files. Relative paths resolve from `/home/user/`.
+
+The `claudeDir` option uploads a local `.claude/` directory to the sandbox, enabling Claude Agent SDK skills. Point it at a directory containing `.claude/skills/*/SKILL.md` files.
+
+Some packages can't be bundled because they spawn child processes or have native modules. The Claude Agent SDK is like this. These get automatically marked as external and installed via npm in the sandbox.
+
+The `run` function gets a context object with an `executionId`, an `AbortSignal`, environment variables, and a logger.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,590 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Agent: () => Agent,
+  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");
+var import_node_fs = require("fs");
+var import_node_path = require("path");
+var import_node_module = require("module");
+var getEsbuild = () => import("esbuild");
+var getE2b = () => import("e2b");
+var getPkgTypes = () => import("pkg-types");
+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_AGENT_DIR = `${SANDBOX_HOME}/agent`;
+var SANDBOX_PATHS = {
+  /** Agent code directory */
+  agentDir: SANDBOX_AGENT_DIR,
+  /** I/O directory for input/output files */
+  ioDir: `${SANDBOX_HOME}/io`,
+  /** Task input file */
+  inputJson: `${SANDBOX_HOME}/io/input.json`,
+  /** Result output file (contains success/error) */
+  outputJson: `${SANDBOX_HOME}/io/output.json`,
+  /** Bundled agent module */
+  agentModule: `${SANDBOX_AGENT_DIR}/agent.mjs`,
+  /** Runner module that executes the agent */
+  runnerModule: `${SANDBOX_AGENT_DIR}/runner.mjs`,
+  /** Claude skills and settings directory */
+  claudeDir: `${SANDBOX_AGENT_DIR}/.claude`,
+  /** Package.json for npm dependencies */
+  packageJson: `${SANDBOX_AGENT_DIR}/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, "'\\''")}'`;
+}
+async function runSandboxCommand(sandbox, cmd, timeoutMs) {
+  let stdout = "";
+  let stderr = "";
+  try {
+    const result = await sandbox.commands.run(cmd, {
+      timeoutMs,
+      onStdout: (data) => {
+        stdout += data;
+      },
+      onStderr: (data) => {
+        stderr += data;
+      }
+    });
+    return {
+      exitCode: result.exitCode,
+      stdout: stdout || result.stdout,
+      stderr: stderr || result.stderr
+    };
+  } catch (error) {
+    const exitCode = error.exitCode ?? 1;
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    return {
+      exitCode,
+      stdout,
+      stderr: stderr || errorMessage
+    };
+  }
+}
+async function resolvePackageVersion(pkg, sourceFileDir) {
+  try {
+    const pkgJsonPath = require.resolve(`${pkg}/package.json`, { paths: [sourceFileDir] });
+    const pkgJson = JSON.parse((0, import_node_fs.readFileSync)(pkgJsonPath, "utf-8"));
+    if (pkgJson.version) return pkgJson.version;
+  } catch {
+  }
+  try {
+    const pkgJsonPath = require.resolve(`${pkg}/package.json`, { paths: [process.cwd()] });
+    const pkgJson = JSON.parse((0, import_node_fs.readFileSync)(pkgJsonPath, "utf-8"));
+    if (pkgJson.version) return pkgJson.version;
+  } catch {
+  }
+  try {
+    const { resolvePackageJSON, readPackageJSON } = await getPkgTypes();
+    const pkgDir = (0, import_node_path.join)(process.cwd(), "node_modules", pkg);
+    const pkgJsonPath = await resolvePackageJSON(pkgDir);
+    if (pkgJsonPath) {
+      const pkgJson = await readPackageJSON(pkgJsonPath);
+      if (pkgJson.version) return pkgJson.version;
+    }
+  } catch {
+  }
+  try {
+    const directPath = (0, import_node_path.join)(process.cwd(), "node_modules", pkg, "package.json");
+    const pkgJson = JSON.parse((0, import_node_fs.readFileSync)(directPath, "utf-8"));
+    if (pkgJson.version) return pkgJson.version;
+  } catch {
+  }
+  let currentDir = sourceFileDir;
+  while (currentDir !== (0, import_node_path.dirname)(currentDir)) {
+    try {
+      const pkgJsonPath = (0, import_node_path.join)(currentDir, "node_modules", pkg, "package.json");
+      const pkgJson = JSON.parse((0, import_node_fs.readFileSync)(pkgJsonPath, "utf-8"));
+      if (pkgJson.version) return pkgJson.version;
+    } catch {
+    }
+    currentDir = (0, import_node_path.dirname)(currentDir);
+  }
+  throw new Error(
+    `Could not resolve version for package "${pkg}". Ensure it is installed in node_modules. Searched from: ${sourceFileDir} and ${process.cwd()}`
+  );
+}
+function getCallerFile() {
+  const stack = new Error().stack?.split("\n") ?? [];
+  for (const line of stack.slice(2)) {
+    const match = line.match(/\((.+?):\d+:\d+\)/) || line.match(/at (.+?):\d+:\d+/);
+    if (match) {
+      let file = match[1];
+      if (file.startsWith("file://")) file = (0, import_node_url.fileURLToPath)(file);
+      if (!file.includes("node:") && !file.includes("node_modules/agent-neckbeard") && !file.includes("agent-neckbeard/dist")) return file;
+    }
+  }
+  throw new Error("Could not determine source file");
+}
+function readDirectoryRecursively(dirPath) {
+  const files = [];
+  function walkDir(currentPath) {
+    const entries = (0, import_node_fs.readdirSync)(currentPath);
+    for (const entry of entries) {
+      const fullPath = (0, import_node_path.join)(currentPath, entry);
+      const stat = (0, import_node_fs.statSync)(fullPath);
+      if (stat.isDirectory()) {
+        walkDir(fullPath);
+      } else if (stat.isFile()) {
+        const relPath = (0, import_node_path.relative)(dirPath, fullPath);
+        const isBinary = /\.(png|jpg|jpeg|gif|ico|pdf|zip|tar|gz|bin|exe|dll|so|dylib|wasm)$/i.test(entry);
+        if (isBinary) {
+          const buffer = (0, import_node_fs.readFileSync)(fullPath);
+          const arrayBuffer = buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
+          files.push({ relativePath: relPath, content: arrayBuffer });
+        } else {
+          files.push({ relativePath: relPath, content: (0, import_node_fs.readFileSync)(fullPath, "utf-8") });
+        }
+      }
+    }
+  }
+  walkDir(dirPath);
+  return files;
+}
+var Agent = class {
+  template;
+  inputSchema;
+  outputSchema;
+  maxDuration;
+  dependencies;
+  files;
+  claudeDir;
+  /** @internal Used by the sandbox runner - must be public for bundled code access */
+  _run;
+  _sourceFile;
+  _sandboxId;
+  constructor(config) {
+    this.template = config.template;
+    this.inputSchema = config.inputSchema;
+    this.outputSchema = config.outputSchema;
+    this.maxDuration = config.maxDuration ?? DEFAULT_MAX_DURATION;
+    this._run = config.run;
+    this._sourceFile = getCallerFile();
+    this._sandboxId = config.sandboxId;
+    this.dependencies = config.dependencies ?? DEFAULT_DEPENDENCIES;
+    this.files = config.files ?? [];
+    this.claudeDir = config.claudeDir;
+  }
+  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, Template } = await getE2b();
+    const templateExists = await Template.aliasExists(this.template, { apiKey: e2bApiKey });
+    if (!templateExists) {
+      throw new DeploymentError(
+        `Template "${this.template}" not found. Create it via E2B CLI: e2b template build --name ${this.template} --cpu-count 2 --memory-mb 2048
+Or use an existing template like 'code-interpreter-v1' (2 cores, 2048 MB) or 'base' (2 cores, 512 MB).`
+      );
+    }
+    const collectedExternals = /* @__PURE__ */ new Set();
+    const result = await esbuild.build({
+      entryPoints: [this._sourceFile],
+      bundle: true,
+      platform: "node",
+      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';
+var __filename = __neckbeard_fileURLToPath(import.meta.url);
+var __dirname = __neckbeard_dirname(__filename);
+`
+      },
+      plugins: [{
+        name: "agent-neckbeard-externals",
+        setup(build) {
+          build.onResolve({ filter: /^agent-neckbeard$/ }, () => ({
+            path: "agent-neckbeard",
+            namespace: "agent-shim"
+          }));
+          build.onLoad({ filter: /.*/, namespace: "agent-shim" }, () => ({
+            contents: `
+              export class Agent {
+                constructor(config) {
+                  this.inputSchema = config.inputSchema;
+                  this.outputSchema = config.outputSchema;
+                  this.maxDuration = config.maxDuration ?? 300;
+                  this._run = config.run;
+                }
+              }
+            `,
+            loader: "js"
+          }));
+          build.onResolve({ filter: /^[^.\/]|^\.[^.\/]|^\.\.[^\/]/ }, (args) => {
+            if (args.path.startsWith("node:")) {
+              return null;
+            }
+            if (import_node_module.builtinModules.includes(args.path.replace("node:", ""))) {
+              return null;
+            }
+            const match = args.path.match(/^(@[^/]+\/[^/]+|[^/]+)/);
+            if (match) {
+              collectedExternals.add(match[1]);
+            }
+            return { external: true };
+          });
+        }
+      }]
+    });
+    const runnerCode = `
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+
+const IO_DIR = '/home/user/io';
+const INPUT_FILE = IO_DIR + '/input.json';
+const OUTPUT_FILE = IO_DIR + '/output.json';
+
+mkdirSync(IO_DIR, { recursive: true });
+
+let input, executionId;
+try {
+  const taskData = JSON.parse(readFileSync(INPUT_FILE, 'utf-8'));
+  input = taskData.input;
+  executionId = taskData.executionId;
+} catch (parseError) {
+  writeFileSync(OUTPUT_FILE, JSON.stringify({ success: false, error: { message: 'Task parse failed: ' + parseError.message, stack: parseError.stack } }));
+  process.exit(0);
+}
+
+let mod;
+try {
+  mod = await import('./agent.mjs');
+} catch (importError) {
+  writeFileSync(OUTPUT_FILE, JSON.stringify({ success: false, error: { message: 'Import failed: ' + importError.message, stack: importError.stack } }));
+  process.exit(0);
+}
+
+const agent = mod.default || Object.values(mod).find(v => v instanceof Object && v._run);
+if (!agent) {
+  writeFileSync(OUTPUT_FILE, JSON.stringify({ success: false, error: { message: 'No agent found in module. Exports: ' + Object.keys(mod).join(', ') } }));
+  process.exit(0);
+}
+
+const ctx = {
+  executionId,
+  signal: AbortSignal.timeout(${this.maxDuration * 1e3}),
+  env: process.env,
+  logger: {
+    debug: (msg, ...args) => console.log('[DEBUG]', msg, ...args),
+    info: (msg, ...args) => console.log('[INFO]', msg, ...args),
+    warn: (msg, ...args) => console.warn('[WARN]', msg, ...args),
+    error: (msg, ...args) => console.error('[ERROR]', msg, ...args),
+  },
+};
+
+try {
+  const validated = agent.inputSchema.parse(input);
+  const output = await agent._run(validated, ctx);
+  const validatedOutput = agent.outputSchema.parse(output);
+  writeFileSync(OUTPUT_FILE, JSON.stringify({ success: true, output: validatedOutput }));
+} catch (error) {
+  writeFileSync(OUTPUT_FILE, JSON.stringify({ success: false, error: { message: error.message, stack: error.stack } }));
+}
+`;
+    const sandbox = await Sandbox.create(this.template, {
+      apiKey: e2bApiKey
+    });
+    await runSandboxCommand(sandbox, `mkdir -p ${SANDBOX_PATHS.agentDir}`, QUICK_COMMAND_TIMEOUT_MS);
+    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 runSandboxCommand(sandbox, aptCmd, SANDBOX_COMMAND_TIMEOUT_MS);
+      if (aptResult.exitCode !== 0) {
+        const details = [
+          `Failed to install apt packages: ${apt.join(", ")}`,
+          aptResult.stderr ? `stderr: ${aptResult.stderr}` : "",
+          aptResult.stdout ? `stdout: ${aptResult.stdout}` : ""
+        ].filter(Boolean).join("\n");
+        throw new DeploymentError(details);
+      }
+    }
+    if (commands && commands.length > 0) {
+      for (const cmd of commands) {
+        const cmdResult = await runSandboxCommand(sandbox, cmd, SANDBOX_COMMAND_TIMEOUT_MS);
+        if (cmdResult.exitCode !== 0) {
+          const details = [
+            `Failed to run command: ${cmd}`,
+            cmdResult.stderr ? `stderr: ${cmdResult.stderr}` : "",
+            cmdResult.stdout ? `stdout: ${cmdResult.stdout}` : ""
+          ].filter(Boolean).join("\n");
+          throw new DeploymentError(details);
+        }
+      }
+    }
+    if (this.files.length > 0) {
+      for (const file of this.files) {
+        const destPath = file.path.startsWith("/") ? file.path : `${SANDBOX_HOME}/${file.path}`;
+        const parentDir = destPath.substring(0, destPath.lastIndexOf("/"));
+        if (parentDir) {
+          await runSandboxCommand(sandbox, `mkdir -p ${shellEscape(parentDir)}`, QUICK_COMMAND_TIMEOUT_MS);
+        }
+        const curlCmd = `curl -fsSL -o ${shellEscape(destPath)} ${shellEscape(file.url)}`;
+        const downloadResult = await runSandboxCommand(sandbox, curlCmd, SANDBOX_COMMAND_TIMEOUT_MS);
+        if (downloadResult.exitCode !== 0) {
+          const details = [
+            `Failed to download file from ${file.url} to ${destPath}`,
+            downloadResult.stderr ? `stderr: ${downloadResult.stderr}` : "",
+            downloadResult.stdout ? `stdout: ${downloadResult.stdout}` : ""
+          ].filter(Boolean).join("\n");
+          throw new DeploymentError(details);
+        }
+      }
+    }
+    if (this.claudeDir) {
+      const claudeFiles = readDirectoryRecursively(this.claudeDir);
+      await runSandboxCommand(sandbox, `mkdir -p ${SANDBOX_PATHS.claudeDir}`, QUICK_COMMAND_TIMEOUT_MS);
+      for (const file of claudeFiles) {
+        const destPath = `${SANDBOX_PATHS.claudeDir}/${file.relativePath}`;
+        const parentDir = destPath.substring(0, destPath.lastIndexOf("/"));
+        if (parentDir && parentDir !== SANDBOX_PATHS.claudeDir) {
+          await runSandboxCommand(sandbox, `mkdir -p ${shellEscape(parentDir)}`, QUICK_COMMAND_TIMEOUT_MS);
+        }
+        await sandbox.files.write(destPath, file.content);
+      }
+    }
+    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 = {};
+      const sourceFileDir = (0, import_node_path.dirname)(this._sourceFile);
+      for (const pkg of collectedExternals) {
+        try {
+          dependencies[pkg] = await resolvePackageVersion(pkg, sourceFileDir);
+        } catch (err) {
+          throw new DeploymentError(
+            `Failed to resolve version for package "${pkg}": ${err instanceof Error ? err.message : String(err)}`
+          );
+        }
+      }
+      const pkgJson = JSON.stringify({
+        name: "agent-sandbox",
+        type: "module",
+        dependencies
+      });
+      await sandbox.files.write(SANDBOX_PATHS.packageJson, pkgJson);
+      const installResult = await runSandboxCommand(sandbox, `cd ${SANDBOX_PATHS.agentDir} && npm install --legacy-peer-deps`, SANDBOX_COMMAND_TIMEOUT_MS);
+      if (installResult.exitCode !== 0) {
+        const details = [
+          `Failed to install npm packages: ${Object.keys(dependencies).join(", ")}`,
+          installResult.stderr ? `stderr: ${installResult.stderr}` : "",
+          installResult.stdout ? `stdout: ${installResult.stdout}` : ""
+        ].filter(Boolean).join("\n");
+        throw new DeploymentError(details);
+      }
+    }
+    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 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: e2bApiKey
+      });
+      await sandbox.files.write(SANDBOX_PATHS.inputJson, JSON.stringify({ input: validatedInput, executionId }));
+      let capturedStdout = "";
+      let capturedStderr = "";
+      const result = await sandbox.commands.run(`cd ${SANDBOX_PATHS.agentDir} && node runner.mjs`, {
+        timeoutMs: this.maxDuration * 1e3,
+        envs: {
+          ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY ?? ""
+        },
+        onStdout: (data) => {
+          capturedStdout += data;
+        },
+        onStderr: (data) => {
+          capturedStderr += data;
+        }
+      });
+      if (result.exitCode !== 0) {
+        let resultError = "";
+        try {
+          const resultJson = await sandbox.files.read(SANDBOX_PATHS.outputJson);
+          const parsed = JSON.parse(resultJson);
+          if (!parsed.success && parsed.error) {
+            resultError = `
+Result: ${parsed.error.message}`;
+            if (parsed.error.stack) resultError += `
+Stack: ${parsed.error.stack}`;
+          }
+        } catch {
+        }
+        const errorDetails = [
+          `Agent failed with exit code ${result.exitCode}`,
+          result.stderr ? `Stderr: ${result.stderr}` : "",
+          capturedStderr ? `Captured stderr: ${capturedStderr}` : "",
+          capturedStdout ? `Stdout: ${capturedStdout}` : "",
+          resultError
+        ].filter(Boolean).join("\n");
+        return { ok: false, executionId, error: new ExecutionError(errorDetails) };
+      }
+      const output = JSON.parse(await sandbox.files.read(SANDBOX_PATHS.outputJson));
+      if (!output.success) {
+        const errorDetails = [
+          output.error.message,
+          capturedStderr ? `
+Captured stderr: ${capturedStderr}` : "",
+          capturedStdout ? `
+Stdout: ${capturedStdout}` : ""
+        ].filter(Boolean).join("");
+        const err = new ExecutionError(errorDetails);
+        err.stack = output.error.stack;
+        return { ok: false, executionId, error: err };
+      }
+      return { ok: true, executionId, output: this.outputSchema.parse(output.output) };
+    } catch (err) {
+      return { ok: false, executionId, error: err instanceof Error ? err : new Error(String(err)) };
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Agent,
+  ConfigurationError,
+  DEFAULT_DEPENDENCIES,
+  DeploymentError,
+  ExecutionError,
+  NeckbeardError,
+  ValidationError
+});