agent-bundle 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Yujia Chen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,161 @@
+# agent-bundle
+
+[![CI](https://github.com/yujiachen-y/agent-bundle/actions/workflows/ci.yml/badge.svg)](https://github.com/yujiachen-y/agent-bundle/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/yujiachen-y/agent-bundle/graph/badge.svg?token=NW998X95RW)](https://codecov.io/gh/yujiachen-y/agent-bundle)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+[![Node](https://img.shields.io/badge/Node-%3E%3D20-green.svg)](https://nodejs.org/)
+[![Website](https://img.shields.io/badge/Website-agent--bundle.com-8b5cf6)](https://agent-bundle.com)
+
+> Define skills in YAML. Develop with a live sandbox UI. Ship as a typed TypeScript package.
+
+**Anthropic · OpenAI · Gemini · Ollama · OpenRouter** — **E2B · Kubernetes sandboxes** — **AWS ECS Fargate deploy** _(beta)_
+
+---
+
+## Why
+
+Agent skills work great inside local coding agents. Deploying them to production is a different story.
+
+|  | Without agent-bundle | With agent-bundle |
+|--|---------------------|-------------------|
+| **Develop** | Skills run in local coding agents only | `agent-bundle dev` — WebUI with live sandbox view |
+| **Ship** | Rewrite skill logic into a service from scratch | `agent-bundle build` — typed TypeScript factory + Docker image |
+| **Behave** | Dev and prod diverge silently | Same sandbox runtime in both modes |
+
+---
+
+## Quick Start
+
+### 1. Install
+
+```bash
+pnpm install && pnpm build
+```
+
+### 2. Define your bundle
+
+```yaml
+# agent-bundle.yaml
+name: my-agent
+
+model:
+  provider: anthropic
+  model: claude-sonnet-4-5
+
+prompt:
+  system: |
+    You are a helpful agent.
+    Follow the skill instructions precisely.
+  variables:
+    - user_name
+
+sandbox:
+  provider: kubernetes
+  kubernetes:
+    image: my-sandbox:latest
+
+skills:
+  - path: ./skills/my-skill
+```
+
+See [Agent Skills](https://github.com/agent-skills/spec) for the skill format and [Configuration Guide](./docs/configuration.md) for all options.
+
+### 3. Run locally
+
+```bash
+agent-bundle dev
+```
+
+Opens a WebUI at `http://localhost:3000` where you can chat with the agent and watch its file tree and terminal output in real time — see exactly what it's doing inside the sandbox.
+
+Ready to deploy? See [Build & Embed](#build--embed) below.
+
+---
+
+## Features
+
+- **Live sandbox view** — WebUI at localhost:3000 shows the agent's file tree and terminal in real time. No more black boxes.
+- **Type-safe codegen** — Prisma-style `generate`. Variable names are checked at compile time — miss one and it won't build.
+- **Dev-prod parity** — `dev`, `serve`, and `build` share the same sandbox abstraction. What passes locally ships as-is.
+- **No vendor lock-in** — Swap model providers or sandbox backends with one line of YAML.
+- **Session recovery** — Agent crashes mid-run? Resume from its last conversation state.
+- **Token-scoped MCP** — Connect to internal services via MCP servers. Even under prompt injection, the agent cannot exceed what the MCP server permits for that token.
+
+---
+
+## Build & Embed
+
+```bash
+agent-bundle build
+```
+
+Produces a typed, embeddable package:
+
+```
+dist/my-agent/
+├── index.ts        ← typed agent factory
+├── types.ts        ← variable types
+├── bundle.json     ← config snapshot
+└── package.json    ← scoped package metadata
+```
+
+If `sandbox.kubernetes.build` is configured, `agent-bundle build` runs a local `docker build` for that image tag. Image push/import is still an explicit user step.
+If `sandbox.provider` is `e2b`, `agent-bundle build` generates a temporary E2B context (`/skills`, `/tools`, `e2b.Dockerfile`) and bakes the resolved template ref into `bundle.json`. See [Configuration Guide](./docs/configuration.md#sandbox) for SDK/CLI fallback and auth details.
+
+### Deploy to AWS _(beta)_
+
+```bash
+agent-bundle deploy --target aws --secret API_KEY
+```
+
+Pushes the built Docker image to ECR and deploys to ECS Fargate — no Terraform or CloudFormation required. See [Deploy](./docs/configuration.md#deploy-beta) for details.
+
+Integrate into any Node.js service:
+
+```typescript
+import { MyAgent } from "./dist/my-agent";
+
+const agent = await MyAgent.init({
+  variables: { user_name: "Alice" },
+});
+
+const response = await agent.respond([
+  { role: "user", content: "Extract all line items" },
+]);
+await agent.shutdown();
+```
+
+Variable names are checked at compile time. Lifecycle hooks, file I/O, and session recovery are covered in the [Configuration Guide](./docs/configuration.md).
+
+---
+
+## Architecture
+
+![Architecture](.github/architecture.png)
+
+The agent orchestrator routes between the LLM provider, sandbox, and MCP servers. All three interfaces share the same abstraction across `dev`, `serve`, and `build` modes.
+
+---
+
+If agent-bundle is useful to you, consider giving it a ⭐. It helps others discover the project.
+
+---
+
+## Roadmap
+
+- [ ] `deploy --target aws` GA — currently beta, stability not guaranteed
+- [ ] GCP Cloud Run deploy target
+- [ ] Pluggable agent loop engines — Claude Code, Codex via process bridge
+- [ ] Fine-grained Docker sandbox isolation
+
+---
+
+## Contributing
+
+Contributions welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.
+
+---
+
+## License
+
+[MIT](./LICENSE)

package/dist/agent/agent.d.ts

@@ -0,0 +1,32 @@
+import { type ResponseInput, type ResponseOutput } from "../agent-loop/index.js";
+import { type AgentDependencies } from "./dependencies.js";
+import type { Agent, AgentConfig, AgentStatus, InitOptions, RespondStreamOptions } from "./types.js";
+export declare class AgentImpl<V extends string> implements Agent {
+    private readonly config;
+    private readonly options;
+    private readonly dependencies;
+    readonly name: string;
+    private statusValue;
+    private sandbox;
+    private loop;
+    private mcpClientManager;
+    private conversationHistory;
+    private readonly otelHooks;
+    private readonly instrumentToolCall;
+    private readonly instrumentMcpCall;
+    constructor(config: AgentConfig<V>, options: InitOptions<V>, dependencies?: AgentDependencies);
+    get status(): AgentStatus;
+    initialize(): Promise<void>;
+    respond(input: ResponseInput): Promise<ResponseOutput>;
+    respondStream(input: ResponseInput, options?: RespondStreamOptions): AsyncGenerator<import("../agent-loop/types.js").ResponseEvent, void, unknown>;
+    shutdown(): Promise<void>;
+    private createMcpManager;
+    private handleToolCall;
+    private executeToolCall;
+    private handleReadTool;
+    private handleWriteTool;
+    private handleBashTool;
+    private handleMcpTool;
+    private isStopped;
+}
+export declare function createInitializedAgent<V extends string>(config: AgentConfig<V>, options: InitOptions<V>): Promise<Agent>;

package/dist/agent/agent.js

@@ -0,0 +1,241 @@
+import { fillSystemPrompt, } from "../agent-loop/index.js";
+import { createAgentHooks, createMcpCallInstrumenter, createToolCallInstrumenter, } from "../observability/hooks.js";
+import { createDefaultDependencies, } from "./dependencies.js";
+import { disposeResources, extractOptionalChunkHandler, ensureRunnableStatus, extractOptionalNumber, extractOptionalString, extractRequiredNonEmptyString, extractRequiredString, formatExecResult, isMcpTool, parseMcpToolName, readFieldError, readFieldTypeError, toConversationInput, toErrorMessage, toNextConversationHistory, toToolError, validateModelApiKey, } from "./internals.js";
+export class AgentImpl {
+    config;
+    options;
+    dependencies;
+    name;
+    statusValue = "stopped";
+    sandbox = null;
+    loop = null;
+    mcpClientManager = null;
+    conversationHistory = [];
+    otelHooks;
+    instrumentToolCall;
+    instrumentMcpCall;
+    constructor(config, options, dependencies = createDefaultDependencies()) {
+        this.config = config;
+        this.options = options;
+        this.dependencies = dependencies;
+        this.name = config.name;
+        const otel = dependencies.observability ?? null;
+        this.otelHooks = otel ? createAgentHooks(otel, config.name) : null;
+        this.instrumentToolCall = otel ? createToolCallInstrumenter(otel) : null;
+        this.instrumentMcpCall = otel ? createMcpCallInstrumenter(otel) : null;
+    }
+    get status() {
+        return this.statusValue;
+    }
+    async initialize() {
+        const systemPrompt = fillSystemPrompt(this.config.systemPrompt, this.options.variables);
+        validateModelApiKey(this.config.model.provider);
+        const sandbox = this.dependencies.createSandbox(this.config.sandbox, this.options.hooks ?? {});
+        const loop = this.dependencies.createLoop();
+        this.sandbox = sandbox;
+        this.loop = loop;
+        this.conversationHistory = this.options.session?.conversationHistory ?? [];
+        try {
+            await sandbox.start();
+            this.mcpClientManager = await this.createMcpManager();
+            const externalTools = this.mcpClientManager?.tools ?? [];
+            await loop.init({
+                systemPrompt,
+                model: this.config.model,
+                toolHandler: async (call) => {
+                    return await this.handleToolCall(call);
+                },
+                ...(externalTools.length > 0 ? { externalTools } : {}),
+            });
+            this.statusValue = "ready";
+        }
+        catch (error) {
+            this.statusValue = "stopped";
+            await disposeResources(loop, this.mcpClientManager, sandbox);
+            throw error;
+        }
+    }
+    async respond(input) {
+        let responseOutput = null;
+        let responseError = null;
+        for await (const event of this.respondStream(input)) {
+            if (event.type === "response.completed") {
+                responseOutput = event.output;
+            }
+            if (event.type === "response.error") {
+                responseError = event.error;
+            }
+        }
+        if (responseError) {
+            throw new Error(responseError);
+        }
+        if (!responseOutput) {
+            throw new Error("Agent did not produce a completed response.");
+        }
+        return responseOutput;
+    }
+    async *respondStream(input, options) {
+        ensureRunnableStatus(this.statusValue);
+        const loop = this.loop;
+        if (!loop) {
+            throw new Error("Agent loop is not initialized.");
+        }
+        const signal = options?.signal;
+        const runInput = toConversationInput(this.conversationHistory, input);
+        this.statusValue = "running";
+        const startMs = this.otelHooks?.onRespondStart();
+        let completedOutput = null;
+        let respondError;
+        try {
+            for await (const event of loop.run(runInput, { signal })) {
+                if (signal?.aborted)
+                    break;
+                if (event.type === "response.completed") {
+                    completedOutput = event.output;
+                    if (event.output.usage && this.otelHooks) {
+                        this.otelHooks.onTokenUsage(event.output.usage);
+                    }
+                }
+                if (event.type === "response.error") {
+                    respondError = new Error(event.error);
+                }
+                yield event;
+            }
+        }
+        catch (error) {
+            respondError = error;
+            throw error;
+        }
+        finally {
+            if (!this.isStopped()) {
+                this.statusValue = "ready";
+            }
+            if (startMs !== undefined && this.otelHooks) {
+                this.otelHooks.onRespondEnd(startMs, respondError);
+            }
+        }
+        if (!respondError && completedOutput) {
+            this.conversationHistory = toNextConversationHistory(runInput, completedOutput);
+        }
+    }
+    async shutdown() {
+        if (this.statusValue === "stopped") {
+            return;
+        }
+        const loop = this.loop;
+        const mcpClientManager = this.mcpClientManager;
+        const sandbox = this.sandbox;
+        this.statusValue = "stopped";
+        this.loop = null;
+        this.mcpClientManager = null;
+        this.sandbox = null;
+        await disposeResources(loop, mcpClientManager, sandbox);
+    }
+    async createMcpManager() {
+        if (!this.config.mcp || this.config.mcp.length === 0) {
+            return null;
+        }
+        const mcpTokens = this.options.mcpTokens ?? {};
+        return await this.dependencies.createMcpClientManager(this.config.mcp, mcpTokens, this.sandbox);
+    }
+    async handleToolCall(call) {
+        if (this.instrumentToolCall) {
+            return this.instrumentToolCall(call, (c) => this.executeToolCall(c));
+        }
+        return this.executeToolCall(call);
+    }
+    async executeToolCall(call) {
+        const sandbox = this.sandbox;
+        if (!sandbox) {
+            return toToolError(call.id, "Sandbox is not available.");
+        }
+        try {
+            const normalizedName = call.name.trim().toLowerCase();
+            if (normalizedName === "read") {
+                return await this.handleReadTool(call, sandbox);
+            }
+            if (normalizedName === "write") {
+                return await this.handleWriteTool(call, sandbox);
+            }
+            if (normalizedName === "bash") {
+                return await this.handleBashTool(call, sandbox);
+            }
+            if (isMcpTool(call.name)) {
+                return await this.handleMcpTool(call);
+            }
+            return toToolError(call.id, `Unsupported tool \"${call.name}\".`);
+        }
+        catch (error) {
+            return toToolError(call.id, toErrorMessage(error));
+        }
+    }
+    async handleReadTool(call, sandbox) {
+        const path = extractRequiredNonEmptyString(call.input, "path");
+        if (!path) {
+            return readFieldError(call.id, "Read", "path");
+        }
+        const content = await sandbox.file.read(path);
+        return {
+            toolCallId: call.id,
+            output: content,
+        };
+    }
+    async handleWriteTool(call, sandbox) {
+        const path = extractRequiredNonEmptyString(call.input, "path");
+        if (!path) {
+            return readFieldError(call.id, "Write", "path");
+        }
+        const content = extractRequiredString(call.input, "content");
+        if (content === null) {
+            return readFieldTypeError(call.id, "Write", "content");
+        }
+        await sandbox.file.write(path, content);
+        return {
+            toolCallId: call.id,
+            output: `Wrote ${content.length} bytes to ${path}.`,
+        };
+    }
+    async handleBashTool(call, sandbox) {
+        const command = extractRequiredNonEmptyString(call.input, "command");
+        if (!command) {
+            return readFieldError(call.id, "Bash", "command");
+        }
+        const timeout = extractOptionalNumber(call.input, "timeout");
+        const cwd = extractOptionalString(call.input, "cwd");
+        const onChunk = extractOptionalChunkHandler(call.input, "onChunk");
+        const execOptions = {
+            timeout,
+            cwd,
+            ...(onChunk ? { onChunk } : {}),
+        };
+        const result = await sandbox.exec(command, execOptions);
+        return {
+            toolCallId: call.id,
+            output: formatExecResult(result),
+            isError: result.exitCode !== 0,
+        };
+    }
+    async handleMcpTool(call) {
+        const mcpClientManager = this.mcpClientManager;
+        if (!mcpClientManager) {
+            return toToolError(call.id, `MCP tool \"${call.name}\" is not available.`);
+        }
+        if (this.instrumentMcpCall) {
+            const parsed = parseMcpToolName(call.name);
+            const serverName = parsed?.serverName ?? "unknown";
+            const toolName = parsed?.toolName ?? call.name;
+            return this.instrumentMcpCall(serverName, toolName, () => mcpClientManager.callTool(call));
+        }
+        return await mcpClientManager.callTool(call);
+    }
+    isStopped() {
+        return this.statusValue === "stopped";
+    }
+}
+export async function createInitializedAgent(config, options) {
+    const agent = new AgentImpl(config, options);
+    await agent.initialize();
+    return agent;
+}
+//# sourceMappingURL=agent.js.map

package/dist/agent/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../../src/agent/agent.ts"],"names":[],"mappings":"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"}

package/dist/agent/agent.test-helpers.d.ts

@@ -0,0 +1,63 @@
+import type { AgentLoop, AgentLoopConfig, ResponseEvent, ResponseInput, RunOptions } from "../agent-loop/index.js";
+import type { ExecOptions, ExecResult, FileEntry, Sandbox, SpawnOptions, SpawnedProcess, SandboxStatus } from "../sandbox/index.js";
+import { AgentImpl } from "./agent.js";
+import type { AgentDependencies, McpClientManager } from "./dependencies.js";
+import type { AgentConfig, InitOptions } from "./types.js";
+export declare class FakeLoop implements AgentLoop {
+    readonly initConfigs: AgentLoopConfig[];
+    readonly runInputs: ResponseInput[];
+    disposeCount: number;
+    private initError;
+    private readonly queuedRuns;
+    setInitError(error: Error): void;
+    enqueueRun(events: ResponseEvent[]): void;
+    init(config: AgentLoopConfig): Promise<void>;
+    run(input: ResponseInput, options?: RunOptions): AsyncIterable<ResponseEvent>;
+    dispose(): Promise<void>;
+}
+export declare class FakeSandbox implements Sandbox {
+    readonly id = "sandbox-1";
+    status: SandboxStatus;
+    readonly execCalls: Array<{
+        command: string;
+        options?: ExecOptions;
+    }>;
+    readonly spawnCalls: Array<{
+        command: string;
+        args: string[];
+        options?: SpawnOptions;
+    }>;
+    readonly readCalls: string[];
+    readonly writeCalls: Array<{
+        path: string;
+        content: string | Buffer;
+    }>;
+    startCount: number;
+    shutdownCount: number;
+    nextReadResult: string;
+    nextExecResult: ExecResult;
+    nextSpawnedProcess: SpawnedProcess;
+    start(): Promise<void>;
+    shutdown(): Promise<void>;
+    exec(command: string, options?: ExecOptions): Promise<ExecResult>;
+    spawn(command: string, args?: string[], options?: SpawnOptions): Promise<SpawnedProcess>;
+    readonly file: {
+        read: (path: string) => Promise<string>;
+        write: (path: string, content: string | Buffer) => Promise<void>;
+        list: (path: string) => Promise<FileEntry[]>;
+        delete: (path: string) => Promise<void>;
+    };
+}
+export type Harness = {
+    agent: AgentImpl<"user_name">;
+    loop: FakeLoop;
+    sandbox: FakeSandbox;
+    dependencies: AgentDependencies;
+};
+export declare function createHarness(options?: {
+    configOverrides?: Partial<AgentConfig<"user_name">>;
+    initOverrides?: Partial<InitOptions<"user_name">>;
+    mcpClientManager?: McpClientManager | null;
+    order?: string[];
+}): Harness;
+export declare function collectEvents(iterable: AsyncIterable<ResponseEvent>): Promise<ResponseEvent[]>;