agent-neckbeard 1.1.1

package/dist/index.d.cts

@@ -0,0 +1,215 @@
+/**
+ * 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;
+    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;
+    };
+}
+type AgentRunResult<TOutput> = {
+    ok: true;
+    executionId: string;
+    output: TOutput;
+} | {
+    ok: false;
+    executionId: string;
+    error: Error | NeckbeardError;
+};
+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[];
+}
+interface BuildOptions {
+    /** External dependencies to exclude from the bundle */
+    external?: string[];
+    /**
+     * Automatically detect dependencies that shouldn't be bundled (native addons).
+     * @default true
+     */
+    autoDetectExternal?: boolean;
+}
+/**
+ * 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> {
+    /**
+     * E2B template name or ID to use for the sandbox.
+     * Templates define the sandbox's CPU, memory, and pre-installed software.
+     *
+     * Common templates:
+     * - 'code-interpreter-v1': 2 cores, 2048 MB (recommended for Claude Agent SDK)
+     * - 'base': 2 cores, 512 MB (minimal)
+     * - 'desktop': 8 cores, 8192 MB (for heavy workloads)
+     *
+     * Create custom templates via E2B CLI:
+     *   e2b template build --cpu-count 4 --memory-mb 4096 --name my-template
+     *
+     * @see https://e2b.dev/docs/template/overview
+     */
+    template: string;
+    inputSchema: SchemaLike<TInput>;
+    outputSchema: SchemaLike<TOutput>;
+    run: (input: TInput, ctx: AgentRunContext) => Promise<TOutput>;
+    maxDuration?: number;
+    /** 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/agent/.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/agent/ (containing .claude/)
+     * - settingSources includes 'project'
+     * - allowedTools includes 'Skill'
+     */
+    claudeDir?: string;
+    /**
+     * Environment variables to pass to the sandbox.
+     * These will be available to the agent code via process.env and ctx.env.
+     * Undefined values are filtered out.
+     *
+     * @example
+     * ```typescript
+     * envs: {
+     *   ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY,
+     *   MY_API_KEY: process.env.MY_API_KEY,
+     * }
+     * ```
+     */
+    envs?: Record<string, string | undefined>;
+    /** Build-time options for bundling */
+    build?: BuildOptions;
+}
+declare class Agent<TInput, TOutput> {
+    readonly template: string;
+    readonly inputSchema: SchemaLike<TInput>;
+    readonly outputSchema: SchemaLike<TOutput>;
+    readonly maxDuration: number;
+    readonly dependencies: OsDependencies;
+    readonly files: FileDownload[];
+    readonly claudeDir?: string;
+    readonly envs: Record<string, string | undefined>;
+    readonly build: BuildOptions;
+    /** @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;
+    /**
+     * 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.
+     *
+     * @returns The sandbox ID, which can be used to reconnect via `run(input, { sandboxId })`
+     * @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({ ... });
+     * const sandboxId = await agent.deploy();
+     * console.log(`Deployed to sandbox: ${sandboxId}`);
+     * ```
+     */
+    deploy(): Promise<string>;
+    /**
+     * Executes the agent with the given input.
+     *
+     * The agent must be deployed before calling this method, or a sandboxId must
+     * be provided in the options. 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
+     * @param options - Optional configuration for this run
+     * @param options.sandboxId - Sandbox ID to use, overrides the deployed sandbox
+     * @returns A result object indicating success or failure with output or error
+     *
+     * @example
+     * ```typescript
+     * // Using deployed sandbox
+     * const result = await agent.run({ prompt: 'Hello, world!' });
+     *
+     * // Using explicit sandboxId (for reconnecting)
+     * const result = await agent.run({ prompt: 'Hello!' }, { sandboxId: 'sbx_...' });
+     * ```
+     */
+    run(input: TInput, options?: {
+        sandboxId?: string;
+    }): Promise<AgentRunResult<TOutput>>;
+}
+
+export { Agent, type AgentConfig, type AgentRunContext, type AgentRunResult, type BuildOptions, ConfigurationError, DEFAULT_DEPENDENCIES, DeploymentError, ExecutionError, type FileDownload, NeckbeardError, type OsDependencies, ValidationError };

package/dist/index.d.ts

@@ -0,0 +1,215 @@
+/**
+ * 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;
+    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;
+    };
+}
+type AgentRunResult<TOutput> = {
+    ok: true;
+    executionId: string;
+    output: TOutput;
+} | {
+    ok: false;
+    executionId: string;
+    error: Error | NeckbeardError;
+};
+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[];
+}
+interface BuildOptions {
+    /** External dependencies to exclude from the bundle */
+    external?: string[];
+    /**
+     * Automatically detect dependencies that shouldn't be bundled (native addons).
+     * @default true
+     */
+    autoDetectExternal?: boolean;
+}
+/**
+ * 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> {
+    /**
+     * E2B template name or ID to use for the sandbox.
+     * Templates define the sandbox's CPU, memory, and pre-installed software.
+     *
+     * Common templates:
+     * - 'code-interpreter-v1': 2 cores, 2048 MB (recommended for Claude Agent SDK)
+     * - 'base': 2 cores, 512 MB (minimal)
+     * - 'desktop': 8 cores, 8192 MB (for heavy workloads)
+     *
+     * Create custom templates via E2B CLI:
+     *   e2b template build --cpu-count 4 --memory-mb 4096 --name my-template
+     *
+     * @see https://e2b.dev/docs/template/overview
+     */
+    template: string;
+    inputSchema: SchemaLike<TInput>;
+    outputSchema: SchemaLike<TOutput>;
+    run: (input: TInput, ctx: AgentRunContext) => Promise<TOutput>;
+    maxDuration?: number;
+    /** 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/agent/.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/agent/ (containing .claude/)
+     * - settingSources includes 'project'
+     * - allowedTools includes 'Skill'
+     */
+    claudeDir?: string;
+    /**
+     * Environment variables to pass to the sandbox.
+     * These will be available to the agent code via process.env and ctx.env.
+     * Undefined values are filtered out.
+     *
+     * @example
+     * ```typescript
+     * envs: {
+     *   ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY,
+     *   MY_API_KEY: process.env.MY_API_KEY,
+     * }
+     * ```
+     */
+    envs?: Record<string, string | undefined>;
+    /** Build-time options for bundling */
+    build?: BuildOptions;
+}
+declare class Agent<TInput, TOutput> {
+    readonly template: string;
+    readonly inputSchema: SchemaLike<TInput>;
+    readonly outputSchema: SchemaLike<TOutput>;
+    readonly maxDuration: number;
+    readonly dependencies: OsDependencies;
+    readonly files: FileDownload[];
+    readonly claudeDir?: string;
+    readonly envs: Record<string, string | undefined>;
+    readonly build: BuildOptions;
+    /** @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;
+    /**
+     * 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.
+     *
+     * @returns The sandbox ID, which can be used to reconnect via `run(input, { sandboxId })`
+     * @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({ ... });
+     * const sandboxId = await agent.deploy();
+     * console.log(`Deployed to sandbox: ${sandboxId}`);
+     * ```
+     */
+    deploy(): Promise<string>;
+    /**
+     * Executes the agent with the given input.
+     *
+     * The agent must be deployed before calling this method, or a sandboxId must
+     * be provided in the options. 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
+     * @param options - Optional configuration for this run
+     * @param options.sandboxId - Sandbox ID to use, overrides the deployed sandbox
+     * @returns A result object indicating success or failure with output or error
+     *
+     * @example
+     * ```typescript
+     * // Using deployed sandbox
+     * const result = await agent.run({ prompt: 'Hello, world!' });
+     *
+     * // Using explicit sandboxId (for reconnecting)
+     * const result = await agent.run({ prompt: 'Hello!' }, { sandboxId: 'sbx_...' });
+     * ```
+     */
+    run(input: TInput, options?: {
+        sandboxId?: string;
+    }): Promise<AgentRunResult<TOutput>>;
+}
+
+export { Agent, type AgentConfig, type AgentRunContext, type AgentRunResult, type BuildOptions, ConfigurationError, DEFAULT_DEPENDENCIES, DeploymentError, ExecutionError, type FileDownload, NeckbeardError, type OsDependencies, ValidationError };