agent-neckbeard 1.1.1

package/README.md

@@ -0,0 +1,128 @@
+<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 'agent-neckbeard';
+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()),
+  }),
+  envs: {
+    ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY,
+  },
+  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 ?? '{}');
+      }
+    }
+  },
+});
+
+const sandboxId = await agent.deploy();  // bundles, uploads to E2B, returns sandboxId
+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 agent-neckbeard
+```
+
+```bash
+export E2B_API_KEY=your-key
+export ANTHROPIC_API_KEY=your-key  # Pass via envs config, not auto-forwarded
+```
+
+## 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
+  dependencies?: {
+    apt?: string[],
+    commands?: string[],
+  },
+  files?: [{ url, path }],     // pre-download into sandbox
+  claudeDir?: string,          // upload .claude/ skills directory
+  envs?: Record<string, string | undefined>, // environment variables for sandbox
+})
+```
+
+`deploy()` returns the sandbox ID, which you can save for reconnecting later:
+
+```typescript
+const sandboxId = await agent.deploy();
+// Later, reconnect to the same sandbox:
+const result = await agent.run({ topic: 'hello' }, { sandboxId });
+```
+
+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.
+
+The `envs` option passes environment variables to the sandbox. These are available to your agent code via `process.env` and `ctx.env`. Undefined values are filtered out:
+
+```typescript
+const agent = new Agent({
+  template: 'code-interpreter-v1',
+  envs: {
+    ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY,
+    MY_API_KEY: process.env.MY_API_KEY,
+  },
+  // ...
+});
+```
+
+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