agent-neckbeard 0.1.0 → 1.0.1

package/README.md

@@ -1,139 +1,105 @@
-# agent-neckbeard
+<img width="1024" height="1024" alt="image" src="https://github.com/user-attachments/assets/52b7f9cf-b9c7-4cae-be11-62273cd1489a" />
 
-Deploy AI agents to E2B sandboxes with structured input/output validation.
+# neckbeard
 
-## The Problem
+There's a weird thing that happens when you try to deploy an AI agent.
 
-When building agentic workflows with the [Claude Agent SDK](https://github.com/anthropics/claude-code), the agent process needs to run **inside** a sandbox—not just the tool calls. This means:
+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.
 
-- The agent can execute bash commands, write files, and perform complex multi-step tasks
-- All execution is isolated and secure
-- The agent maintains conversation state across tool calls
+This creates an obvious problem: do you really want that process running on your production server?
 
-E2B provides sandboxed environments, but wiring up the deployment, bundling, and I/O is tedious. This package handles it for you.
+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.
 
-## How It Works
+That sounds simple. It's not.
 
-1. **Define** an agent with typed input/output schemas
-2. **Deploy** bundles your code with esbuild and uploads to E2B
-3. **Run** writes input to `/input/task.json`, executes, reads from `/output/result.json`
+## 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 'agent-neckbeard';
-import { query } from '@anthropic-ai/claude-code';
+import { query } from '@anthropic-ai/claude-agent-sdk';
 import { z } from 'zod';
 
-const summaryAgent = new Agent({
+const agent = new Agent({
   id: 'summary',
-  maxDuration: 120,
-  inputSchema: z.object({
-    topic: z.string(),
-  }),
+  inputSchema: z.object({ topic: z.string() }),
   outputSchema: z.object({
     title: z.string(),
     summary: z.string(),
     keyPoints: z.array(z.string()),
   }),
-  run: async (input, ctx) => {
-    let result = { title: '', summary: '', keyPoints: [] as string[] };
-
+  run: async (input) => {
     for await (const message of query({
-      prompt: `Research "${input.topic}" and return JSON with title, summary, keyPoints`,
-      options: { maxTurns: 10, allowedTools: ['write', 'read'] },
-      abortSignal: ctx.signal,
+      prompt: `Research "${input.topic}" and return JSON`,
+      options: { maxTurns: 10 },
     })) {
       if (message.type === 'result') {
-        result = JSON.parse(message.result ?? '{}');
+        return JSON.parse(message.result ?? '{}');
       }
     }
-
-    return result;
   },
 });
 
-// Deploy once
-await summaryAgent.deploy();
-
-// Run many times
-const result = await summaryAgent.run({ topic: 'TypeScript generics' });
-console.log(result.title);      // string - validated
-console.log(result.keyPoints);  // string[] - validated
+await agent.deploy();  // bundles, uploads to E2B
+const result = await agent.run({ topic: 'TypeScript generics' });
 ```
 
-## Installation
+`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 agent-neckbeard
 ```
 
-Set your E2B API key:
-
 ```bash
-export E2B_API_KEY=your-api-key
-```
-
-## API
-
-### `new Agent(config)`
-
-```typescript
-const agent = new Agent({
-  id: string,                    // Unique identifier
-  inputSchema: ZodSchema,        // Validates input before run
-  outputSchema: ZodSchema,       // Validates output after run
-  run: (input, ctx) => Promise,  // Your agent logic
-  maxDuration?: number,          // Timeout in seconds (default: 300)
-  sandboxId?: string,            // Reuse existing sandbox (skip deploy)
-});
+export E2B_API_KEY=your-key
+export ANTHROPIC_API_KEY=your-key
 ```
 
-### `agent.deploy()`
+## The Details
 
-Bundles your agent code with esbuild and uploads to a new E2B sandbox. Automatically detects the source file—no entry point needed.
+The constructor takes a few options:
 
 ```typescript
-await agent.deploy();
-console.log(agent.sandboxId);  // 'sandbox-abc123'
-```
-
-### `agent.run(input)`
-
-Executes the agent in the sandbox with validated input/output.
-
-```typescript
-const result = await agent.run({ topic: 'quantum computing' });
-// result is typed and validated against outputSchema
+new Agent({
+  id: string,
+  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
+})
 ```
 
-### Reusing a Sandbox
+If you already have a sandbox deployed, pass `sandboxId` and skip `deploy()`.
 
-If you already have a deployed sandbox, pass `sandboxId` to skip deployment:
+The `files` option downloads things into the sandbox before your agent runs—useful for models or config files. Relative paths resolve from `/home/user/`.
 
-```typescript
-const agent = new Agent({
-  id: 'summary',
-  sandboxId: 'existing-sandbox-id',  // Skip deploy()
-  inputSchema,
-  outputSchema,
-  run,
-});
+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.
 
-// No deploy needed
-const result = await agent.run({ topic: 'hello' });
-```
+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.
 
-## Context
-
-The `run` function receives a context object:
-
-```typescript
-run: async (input, ctx) => {
-  ctx.executionId  // Unique ID for this execution
-  ctx.signal       // AbortSignal for cancellation
-  ctx.env          // Environment variables
-  ctx.logger       // { debug, info, warn, error }
-}
-```
+The `run` function gets a context object with an `executionId`, an `AbortSignal`, environment variables, and a logger.
 
 ## License
 

package/dist/index.d.ts

@@ -12,9 +12,41 @@ interface AgentRunContext {
         error: (message: string, ...args: unknown[]) => void;
     };
 }
+type AgentRunResult<TOutput> = {
+    ok: true;
+    executionId: string;
+    output: TOutput;
+} | {
+    ok: false;
+    executionId: string;
+    error: Error;
+};
 interface SchemaLike<T> {
     parse: (data: unknown) => T;
 }
+interface OsDependencies {
+    /** APT packages to install (e.g., ['curl', 'git']) */
+    apt?: string[];
+    /** Custom shell commands to run during setup */
+    commands?: string[];
+}
+/**
+ * Configuration for downloading a file into the sandbox filesystem.
+ * Files are downloaded during deploy() before the agent runs.
+ */
+interface FileDownload {
+    /** URL to download the file from (supports http/https) */
+    url: string;
+    /**
+     * Destination path in the sandbox.
+     * Can be absolute (e.g., '/home/user/data/model.bin') or
+     * relative to /home/user/ (e.g., 'data/model.bin').
+     * Parent directories are created automatically.
+     */
+    path: string;
+}
+/** Default dependencies - empty by default, specify what you need */
+declare const DEFAULT_DEPENDENCIES: OsDependencies;
 interface AgentConfig<TInput, TOutput> {
     id: string;
     inputSchema: SchemaLike<TInput>;
@@ -22,12 +54,37 @@ interface AgentConfig<TInput, TOutput> {
     run: (input: TInput, ctx: AgentRunContext) => Promise<TOutput>;
     maxDuration?: number;
     sandboxId?: string;
+    /** OS-level dependencies to install in the sandbox. Defaults to Claude Code. Set to {} to skip. */
+    dependencies?: OsDependencies;
+    /**
+     * Files to download and initialize in the sandbox filesystem.
+     * Downloaded during deploy() before the agent code runs.
+     * Useful for pre-loading models, datasets, configuration files, etc.
+     */
+    files?: FileDownload[];
+    /**
+     * Local path to a .claude directory containing skills and settings.
+     * The directory will be uploaded to /home/user/.claude/ in the sandbox.
+     * This enables Claude Agent SDK to access skills defined in SKILL.md files
+     * within .claude/skills/ subdirectories.
+     *
+     * Example: claudeDir: './my-project/.claude'
+     *
+     * The Claude Agent SDK will discover skills when:
+     * - cwd is set to /home/user/ (containing .claude/)
+     * - settingSources includes 'project'
+     * - allowedTools includes 'Skill'
+     */
+    claudeDir?: string;
 }
 declare class Agent<TInput, TOutput> {
     readonly id: string;
     readonly inputSchema: SchemaLike<TInput>;
     readonly outputSchema: SchemaLike<TOutput>;
     readonly maxDuration: number;
+    readonly dependencies: OsDependencies;
+    readonly files: FileDownload[];
+    readonly claudeDir?: string;
     /** @internal Used by the sandbox runner - must be public for bundled code access */
     _run: (input: TInput, ctx: AgentRunContext) => Promise<TOutput>;
     private _sourceFile;
@@ -35,7 +92,7 @@ declare class Agent<TInput, TOutput> {
     constructor(config: AgentConfig<TInput, TOutput>);
     get sandboxId(): string | undefined;
     deploy(): Promise<void>;
-    run(input: TInput): Promise<TOutput>;
+    run(input: TInput): Promise<AgentRunResult<TOutput>>;
 }
 
-export { Agent, type AgentConfig, type AgentRunContext };
+export { Agent, type AgentConfig, type AgentRunContext, type AgentRunResult, DEFAULT_DEPENDENCIES, type FileDownload, type OsDependencies };

package/dist/index.js

@@ -1,7 +1,10 @@
 // src/index.ts
-import * as esbuild from "esbuild";
-import { Sandbox } from "e2b";
 import { fileURLToPath } from "url";
+import { readdirSync, readFileSync, statSync } from "fs";
+import { join, relative } from "path";
+var getEsbuild = () => import("esbuild");
+var getE2b = () => import("e2b");
+var DEFAULT_DEPENDENCIES = {};
 function getCallerFile() {
   const stack = new Error().stack?.split("\n") ?? [];
   for (const line of stack.slice(2)) {
@@ -9,16 +12,44 @@ function getCallerFile() {
     if (match) {
       let file = match[1];
       if (file.startsWith("file://")) file = fileURLToPath(file);
-      if (!file.includes("node:") && !file.includes("agent-neckbeard")) return 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 = readdirSync(currentPath);
+    for (const entry of entries) {
+      const fullPath = join(currentPath, entry);
+      const stat = statSync(fullPath);
+      if (stat.isDirectory()) {
+        walkDir(fullPath);
+      } else if (stat.isFile()) {
+        const relPath = 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 = 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: readFileSync(fullPath, "utf-8") });
+        }
+      }
+    }
+  }
+  walkDir(dirPath);
+  return files;
+}
 var Agent = class {
   id;
   inputSchema;
   outputSchema;
   maxDuration;
+  dependencies;
+  files;
+  claudeDir;
   /** @internal Used by the sandbox runner - must be public for bundled code access */
   _run;
   _sourceFile;
@@ -31,12 +62,22 @@ var Agent = class {
     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;
   }
   async deploy() {
     if (this._sandboxId) return;
+    const esbuild = await getEsbuild();
+    const { Sandbox } = await getE2b();
+    const collectedExternals = /* @__PURE__ */ new Set();
+    const mustBeExternal = [
+      /^@anthropic-ai\/claude-agent-sdk/
+      // Spawns cli.js as child process
+    ];
     const result = await esbuild.build({
       entryPoints: [this._sourceFile],
       bundle: true,
@@ -45,15 +86,55 @@ var Agent = class {
       format: "esm",
       write: false,
       minify: true,
-      keepNames: true
+      keepNames: true,
+      treeShaking: false,
+      // Preserve exports for the sandbox runner to import
+      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.id = config.id;
+                  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(".") || args.path.startsWith("/") || args.path.startsWith("node:")) {
+              return null;
+            }
+            for (const pattern of mustBeExternal) {
+              if (pattern.test(args.path)) {
+                const match = args.path.match(/^(@[^/]+\/[^/]+|[^/]+)/);
+                if (match) {
+                  collectedExternals.add(match[1]);
+                }
+                return { external: true };
+              }
+            }
+            return null;
+          });
+        }
+      }]
     });
     const runnerCode = `
 import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 
-mkdirSync('/input', { recursive: true });
-mkdirSync('/output', { recursive: true });
+mkdirSync('/home/user/input', { recursive: true });
+mkdirSync('/home/user/output', { recursive: true });
 
-const { input, executionId } = JSON.parse(readFileSync('/input/task.json', 'utf-8'));
+const { input, executionId } = JSON.parse(readFileSync('/home/user/input/task.json', 'utf-8'));
 
 const ctx = {
   executionId,
@@ -74,41 +155,114 @@ try {
   const validated = agent.inputSchema.parse(input);
   const output = await agent._run(validated, ctx);
   const validatedOutput = agent.outputSchema.parse(output);
-  writeFileSync('/output/result.json', JSON.stringify({ success: true, output: validatedOutput }));
+  writeFileSync('/home/user/output/result.json', JSON.stringify({ success: true, output: validatedOutput }));
 } catch (error) {
-  writeFileSync('/output/result.json', JSON.stringify({ success: false, error: { message: error.message, stack: error.stack } }));
+  writeFileSync('/home/user/output/result.json', JSON.stringify({ success: false, error: { message: error.message, stack: error.stack } }));
 }
 `;
     const sandbox = await Sandbox.create("base", {
       apiKey: process.env.E2B_API_KEY
     });
+    const { apt, commands } = this.dependencies;
+    if (apt && apt.length > 0) {
+      const aptCmd = `apt-get update && apt-get install -y ${apt.join(" ")}`;
+      const aptResult = await sandbox.commands.run(aptCmd, { timeoutMs: 3e5 });
+      if (aptResult.exitCode !== 0) {
+        throw new Error(`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 });
+        if (cmdResult.exitCode !== 0) {
+          throw new Error(`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 parentDir = destPath.substring(0, destPath.lastIndexOf("/"));
+        if (parentDir) {
+          await sandbox.commands.run(`mkdir -p "${parentDir}"`, { timeoutMs: 3e4 });
+        }
+        const curlCmd = `curl -fsSL -o "${destPath}" "${file.url}"`;
+        const downloadResult = await sandbox.commands.run(curlCmd, { timeoutMs: 3e5 });
+        if (downloadResult.exitCode !== 0) {
+          throw new Error(`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 });
+      for (const file of claudeFiles) {
+        const destPath = `/home/user/.claude/${file.relativePath}`;
+        const parentDir = destPath.substring(0, destPath.lastIndexOf("/"));
+        if (parentDir && parentDir !== "/home/user/.claude") {
+          await sandbox.commands.run(`mkdir -p "${parentDir}"`, { timeoutMs: 3e4 });
+        }
+        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);
+    if (collectedExternals.size > 0) {
+      const dependencies = {};
+      for (const pkg of collectedExternals) {
+        dependencies[pkg] = "*";
+      }
+      const pkgJson = JSON.stringify({
+        name: "agent-sandbox",
+        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 });
+      if (installResult.exitCode !== 0) {
+        throw new Error(`Failed to install external packages: ${installResult.stderr}`);
+      }
+    }
     this._sandboxId = sandbox.sandboxId;
   }
   async run(input) {
+    const executionId = `exec_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
     if (!this._sandboxId) {
-      throw new Error("Agent not deployed. Call agent.deploy() first or pass sandboxId to constructor.");
+      return {
+        ok: false,
+        executionId,
+        error: new Error("Agent not deployed. Call agent.deploy() first or pass sandboxId to constructor.")
+      };
     }
-    const validatedInput = this.inputSchema.parse(input);
-    const executionId = `exec_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
-    const sandbox = await Sandbox.connect(this._sandboxId, {
-      apiKey: process.env.E2B_API_KEY
-    });
-    await sandbox.files.write("/input/task.json", JSON.stringify({ input: validatedInput, executionId }));
-    const result = await sandbox.commands.run("node /home/user/runner.mjs", {
-      timeoutMs: this.maxDuration * 1e3
-    });
-    if (result.exitCode !== 0) throw new Error(`Agent failed: ${result.stderr}`);
-    const output = JSON.parse(await sandbox.files.read("/output/result.json"));
-    if (!output.success) {
-      const err = new Error(output.error.message);
-      err.stack = output.error.stack;
-      throw err;
+    try {
+      const { Sandbox } = await getE2b();
+      const validatedInput = this.inputSchema.parse(input);
+      const sandbox = await Sandbox.connect(this._sandboxId, {
+        apiKey: process.env.E2B_API_KEY
+      });
+      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", {
+        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}`) };
+      }
+      const output = JSON.parse(await sandbox.files.read("/home/user/output/result.json"));
+      if (!output.success) {
+        const err = new Error(output.error.message);
+        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)) };
     }
-    return this.outputSchema.parse(output.output);
   }
 };
 export {
-  Agent
+  Agent,
+  DEFAULT_DEPENDENCIES
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-neckbeard",
-  "version": "0.1.0",
+  "version": "1.0.1",
   "description": "Deploy AI agents to E2B sandboxes",
   "type": "module",
   "exports": {
@@ -13,7 +13,9 @@
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "engines": {
     "node": ">=20.0.0"
   },
@@ -23,21 +25,30 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "esbuild": "^0.24.0",
-    "e2b": "^1.0.0"
+    "e2b": "^1.0.0",
+    "esbuild": "^0.24.0"
   },
   "peerDependencies": {
-    "zod": "^3.0.0"
+    "zod": "^3.0.0 || ^4.0.0"
   },
   "peerDependenciesMeta": {
-    "zod": { "optional": true }
+    "zod": {
+      "optional": true
+    }
   },
   "devDependencies": {
-    "typescript": "^5.6.0",
+    "@types/node": "^22.0.0",
     "tsup": "^8.3.0",
-    "@types/node": "^22.0.0"
+    "typescript": "^5.6.0"
   },
-  "keywords": ["ai", "agent", "deploy", "e2b", "sandbox", "claude"],
+  "keywords": [
+    "ai",
+    "agent",
+    "deploy",
+    "e2b",
+    "sandbox",
+    "claude"
+  ],
   "license": "MIT",
   "author": "zacwellmer",
   "repository": {