agent-neckbeard 0.0.1

package/README.md

@@ -0,0 +1,140 @@
+# agent-neckbeard
+
+Deploy AI agents to E2B sandboxes with structured input/output validation.
+
+## The Problem
+
+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:
+
+- 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
+
+E2B provides sandboxed environments, but wiring up the deployment, bundling, and I/O is tedious. This package handles it for you.
+
+## How It Works
+
+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`
+
+```typescript
+import { Agent } from 'agent-neckbeard';
+import { query } from '@anthropic-ai/claude-code';
+import { z } from 'zod';
+
+const summaryAgent = new Agent({
+  id: 'summary',
+  maxDuration: 120,
+  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[] };
+
+    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,
+    })) {
+      if (message.type === 'result') {
+        result = 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
+```
+
+## Installation
+
+```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)
+});
+```
+
+### `agent.deploy()`
+
+Bundles your agent code with esbuild and uploads to a new E2B sandbox. Automatically detects the source file—no entry point needed.
+
+```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
+```
+
+### Reusing a Sandbox
+
+If you already have a deployed sandbox, pass `sandboxId` to skip deployment:
+
+```typescript
+const agent = new Agent({
+  id: 'summary',
+  sandboxId: 'existing-sandbox-id',  // Skip deploy()
+  inputSchema,
+  outputSchema,
+  run,
+});
+
+// No deploy needed
+const result = await agent.run({ topic: 'hello' });
+```
+
+## 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 }
+}
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * agent-neckbeard - Deploy AI agents to E2B sandboxes
+ */
+interface AgentRunContext {
+    executionId: string;
+    signal: AbortSignal;
+    env: Record<string, string>;
+    logger: {
+        debug: (message: string, ...args: unknown[]) => void;
+        info: (message: string, ...args: unknown[]) => void;
+        warn: (message: string, ...args: unknown[]) => void;
+        error: (message: string, ...args: unknown[]) => void;
+    };
+}
+interface SchemaLike<T> {
+    parse: (data: unknown) => T;
+}
+interface AgentConfig<TInput, TOutput> {
+    id: string;
+    inputSchema: SchemaLike<TInput>;
+    outputSchema: SchemaLike<TOutput>;
+    run: (input: TInput, ctx: AgentRunContext) => Promise<TOutput>;
+    maxDuration?: number;
+    sandboxId?: string;
+}
+declare class Agent<TInput, TOutput> {
+    readonly id: string;
+    readonly inputSchema: SchemaLike<TInput>;
+    readonly outputSchema: SchemaLike<TOutput>;
+    readonly maxDuration: number;
+    /** @internal Used by the sandbox runner - must be public for bundled code access */
+    _run: (input: TInput, ctx: AgentRunContext) => Promise<TOutput>;
+    private _sourceFile;
+    private _sandboxId?;
+    constructor(config: AgentConfig<TInput, TOutput>);
+    get sandboxId(): string | undefined;
+    deploy(): Promise<void>;
+    run(input: TInput): Promise<TOutput>;
+}
+
+export { Agent, type AgentConfig, type AgentRunContext };

package/dist/index.js

@@ -0,0 +1,114 @@
+// src/index.ts
+import * as esbuild from "esbuild";
+import { Sandbox } from "e2b";
+import { fileURLToPath } from "url";
+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 = fileURLToPath(file);
+      if (!file.includes("node:") && !file.includes("agent-neckbeard")) return file;
+    }
+  }
+  throw new Error("Could not determine source file");
+}
+var Agent = class {
+  id;
+  inputSchema;
+  outputSchema;
+  maxDuration;
+  /** @internal Used by the sandbox runner - must be public for bundled code access */
+  _run;
+  _sourceFile;
+  _sandboxId;
+  constructor(config) {
+    this.id = config.id;
+    this.inputSchema = config.inputSchema;
+    this.outputSchema = config.outputSchema;
+    this.maxDuration = config.maxDuration ?? 300;
+    this._run = config.run;
+    this._sourceFile = getCallerFile();
+    this._sandboxId = config.sandboxId;
+  }
+  get sandboxId() {
+    return this._sandboxId;
+  }
+  async deploy() {
+    if (this._sandboxId) return;
+    const result = await esbuild.build({
+      entryPoints: [this._sourceFile],
+      bundle: true,
+      platform: "node",
+      target: "node20",
+      format: "esm",
+      write: false,
+      minify: true,
+      keepNames: true
+    });
+    const runnerCode = `
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+
+mkdirSync('/input', { recursive: true });
+mkdirSync('/output', { recursive: true });
+
+const { input, executionId } = JSON.parse(readFileSync('/input/task.json', 'utf-8'));
+
+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),
+  },
+};
+
+const mod = await import('./agent.mjs');
+const agent = mod.default || Object.values(mod).find(v => v instanceof Object && v.id);
+
+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 }));
+} catch (error) {
+  writeFileSync('/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
+    });
+    await sandbox.files.write("/home/user/agent.mjs", result.outputFiles[0].text);
+    await sandbox.files.write("/home/user/runner.mjs", runnerCode);
+    this._sandboxId = sandbox.sandboxId;
+  }
+  async run(input) {
+    if (!this._sandboxId) {
+      throw 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;
+    }
+    return this.outputSchema.parse(output.output);
+  }
+};
+export {
+  Agent
+};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "agent-neckbeard",
+  "version": "0.0.1",
+  "description": "Deploy AI agents to E2B sandboxes",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist"],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "esbuild": "^0.24.0",
+    "e2b": "^1.0.0"
+  },
+  "peerDependencies": {
+    "zod": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": { "optional": true }
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "tsup": "^8.3.0",
+    "@types/node": "^22.0.0"
+  },
+  "keywords": ["ai", "agent", "deploy", "e2b", "sandbox", "claude"],
+  "license": "MIT",
+  "author": "zacwellmer",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zacwellmer/agent-neckbeard.git"
+  },
+  "homepage": "https://github.com/zacwellmer/agent-neckbeard#readme",
+  "bugs": {
+    "url": "https://github.com/zacwellmer/agent-neckbeard/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}