@agentforge-ai/core 0.1.0

package/README.md

@@ -0,0 +1,70 @@
+# @agentforge-ai/core
+
+Core agent primitives, secure sandbox execution, and MCP server for the AgentForge framework.
+
+## Installation
+
+```bash
+npm install @agentforge-ai/core
+```
+
+## Quick Start
+
+```typescript
+import { Agent, SandboxManager, MCPServer } from '@agentforge-ai/core';
+
+// Create an agent
+const agent = new Agent({
+  id: 'my-agent',
+  name: 'My Agent',
+  instructions: 'You are a helpful assistant.',
+  model: 'openai/gpt-4o-mini',
+});
+
+// Generate a response
+const response = await agent.generate('Hello, world!');
+
+// Execute code securely
+const sandbox = new SandboxManager({ timeout: 10000 });
+const result = await sandbox.runCode('console.log("Hello from sandbox!")');
+
+// Register tools with MCP
+const mcp = new MCPServer();
+mcp.registerTool({
+  name: 'calculator',
+  inputSchema: z.object({ expression: z.string() }),
+  outputSchema: z.string(),
+  handler: async ({ expression }) => eval(expression).toString(),
+});
+```
+
+## API Reference
+
+### Agent
+
+The core agent class wrapping Mastra for AI orchestration.
+
+- `new Agent(config)` - Create a new agent
+- `agent.generate(prompt)` - Generate a response
+- `agent.stream(prompt)` - Stream a response
+
+### SandboxManager
+
+Secure code execution via E2B sandboxes.
+
+- `new SandboxManager(config)` - Create a sandbox manager
+- `manager.runCode(code, options)` - Execute code securely
+- `manager.cleanup()` - Clean up resources
+
+### MCPServer
+
+Model Context Protocol server for tool communication.
+
+- `new MCPServer()` - Create an MCP server
+- `server.registerTool(tool)` - Register a tool
+- `server.listTools()` - List all tools
+- `server.callTool(name, input)` - Call a tool
+
+## License
+
+Apache-2.0

package/dist/agent.d.ts

@@ -0,0 +1,93 @@
+import { LanguageModelV1 } from 'ai';
+
+/**
+ * Configuration for creating an AgentForge Agent.
+ */
+interface AgentConfig {
+    /** A unique identifier for the agent. */
+    id: string;
+    /** A human-readable name for the agent. */
+    name: string;
+    /** The system prompt or instructions for the agent. */
+    instructions: string;
+    /**
+     * The language model to use. Pass a LanguageModelV1 instance
+     * (e.g., from `@ai-sdk/openai`, `@ai-sdk/anthropic`, etc.).
+     *
+     * @example
+     * ```typescript
+     * import { openai } from '@ai-sdk/openai';
+     * const agent = new Agent({
+     *   model: openai('gpt-4o-mini'),
+     *   // ...
+     * });
+     * ```
+     */
+    model: LanguageModelV1;
+    /** A dictionary of tools available to the agent. */
+    tools?: Record<string, unknown>;
+}
+/**
+ * Represents a structured response from an agent generation call.
+ */
+interface AgentResponse {
+    /** The text content of the response. */
+    text: string;
+    /** Optional tool call results. */
+    toolResults?: unknown[];
+}
+/**
+ * Represents a single chunk in a streaming response.
+ */
+interface StreamChunk {
+    /** The text content of this chunk. */
+    content: string;
+}
+/**
+ * The core Agent class for the AgentForge framework.
+ *
+ * Wraps the Mastra Agent to provide a simplified, curated API for
+ * creating and interacting with AI agents. Supports any AI SDK-compatible
+ * model provider (OpenAI, Anthropic, Google, etc.) via BYOK (Bring Your Own Key).
+ *
+ * @example
+ * ```typescript
+ * import { openai } from '@ai-sdk/openai';
+ *
+ * const agent = new Agent({
+ *   id: 'my-agent',
+ *   name: 'My Agent',
+ *   instructions: 'You are a helpful assistant.',
+ *   model: openai('gpt-4o-mini'),
+ * });
+ *
+ * const response = await agent.generate('Hello!');
+ * ```
+ */
+declare class Agent {
+    /** The agent's unique ID. */
+    readonly id: string;
+    /** The agent's human-readable name. */
+    readonly name: string;
+    /** The underlying Mastra agent instance. */
+    private mastraAgent;
+    /**
+     * Creates a new AgentForge Agent.
+     * @param config - The configuration for the agent.
+     */
+    constructor(config: AgentConfig);
+    /**
+     * Generates a structured response from the agent.
+     * @param prompt - The user's prompt or input.
+     * @returns A promise that resolves to the agent's response.
+     */
+    generate(prompt: string): Promise<AgentResponse>;
+    /**
+     * Generates a streaming response from the agent.
+     * @param prompt - The user's prompt or input.
+     * @returns An async iterable that yields response chunks.
+     */
+    stream(prompt: string): AsyncGenerator<StreamChunk>;
+}
+
+export { Agent, type AgentConfig, type AgentResponse, type StreamChunk };

package/dist/agent.js

@@ -0,0 +1,48 @@
+// src/agent.ts
+import { Agent as MastraAgent } from "@mastra/core/agent";
+var Agent = class {
+  /** The agent's unique ID. */
+  id;
+  /** The agent's human-readable name. */
+  name;
+  /** The underlying Mastra agent instance. */
+  mastraAgent;
+  /**
+   * Creates a new AgentForge Agent.
+   * @param config - The configuration for the agent.
+   */
+  constructor(config) {
+    this.id = config.id;
+    this.name = config.name;
+    this.mastraAgent = new MastraAgent({
+      name: config.name,
+      instructions: config.instructions,
+      model: config.model,
+      ...config.tools ? { tools: config.tools } : {}
+    });
+  }
+  /**
+   * Generates a structured response from the agent.
+   * @param prompt - The user's prompt or input.
+   * @returns A promise that resolves to the agent's response.
+   */
+  async generate(prompt) {
+    const result = await this.mastraAgent.generate(prompt);
+    return result;
+  }
+  /**
+   * Generates a streaming response from the agent.
+   * @param prompt - The user's prompt or input.
+   * @returns An async iterable that yields response chunks.
+   */
+  async *stream(prompt) {
+    const result = await this.mastraAgent.stream(prompt);
+    for await (const chunk of result.textStream) {
+      yield { content: typeof chunk === "string" ? chunk : String(chunk) };
+    }
+  }
+};
+export {
+  Agent
+};
+//# sourceMappingURL=agent.js.map

package/dist/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/agent.ts"],"sourcesContent":["import { Agent as MastraAgent } from '@mastra/core/agent';\nimport type { LanguageModelV1 } from 'ai';\n\n/**\n * Configuration for creating an AgentForge Agent.\n */\nexport interface AgentConfig {\n  /** A unique identifier for the agent. */\n  id: string;\n  /** A human-readable name for the agent. */\n  name: string;\n  /** The system prompt or instructions for the agent. */\n  instructions: string;\n  /**\n   * The language model to use. Pass a LanguageModelV1 instance\n   * (e.g., from `@ai-sdk/openai`, `@ai-sdk/anthropic`, etc.).\n   *\n   * @example\n   * ```typescript\n   * import { openai } from '@ai-sdk/openai';\n   * const agent = new Agent({\n   *   model: openai('gpt-4o-mini'),\n   *   // ...\n   * });\n   * ```\n   */\n  model: LanguageModelV1;\n  /** A dictionary of tools available to the agent. */\n  tools?: Record<string, unknown>;\n}\n\n/**\n * Represents a structured response from an agent generation call.\n */\nexport interface AgentResponse {\n  /** The text content of the response. */\n  text: string;\n  /** Optional tool call results. */\n  toolResults?: unknown[];\n}\n\n/**\n * Represents a single chunk in a streaming response.\n */\nexport interface StreamChunk {\n  /** The text content of this chunk. */\n  content: string;\n}\n\n/**\n * The core Agent class for the AgentForge framework.\n *\n * Wraps the Mastra Agent to provide a simplified, curated API for\n * creating and interacting with AI agents. Supports any AI SDK-compatible\n * model provider (OpenAI, Anthropic, Google, etc.) via BYOK (Bring Your Own Key).\n *\n * @example\n * ```typescript\n * import { openai } from '@ai-sdk/openai';\n *\n * const agent = new Agent({\n *   id: 'my-agent',\n *   name: 'My Agent',\n *   instructions: 'You are a helpful assistant.',\n *   model: openai('gpt-4o-mini'),\n * });\n *\n * const response = await agent.generate('Hello!');\n * ```\n */\nexport class Agent {\n  /** The agent's unique ID. */\n  public readonly id: string;\n\n  /** The agent's human-readable name. */\n  public readonly name: string;\n\n  /** The underlying Mastra agent instance. */\n  private mastraAgent: MastraAgent;\n\n  /**\n   * Creates a new AgentForge Agent.\n   * @param config - The configuration for the agent.\n   */\n  constructor(config: AgentConfig) {\n    this.id = config.id;\n    this.name = config.name;\n\n    this.mastraAgent = new MastraAgent({\n      name: config.name,\n      instructions: config.instructions,\n      model: config.model,\n      ...(config.tools ? { tools: config.tools as Record<string, never> } : {}),\n    });\n  }\n\n  /**\n   * Generates a structured response from the agent.\n   * @param prompt - The user's prompt or input.\n   * @returns A promise that resolves to the agent's response.\n   */\n  async generate(prompt: string): Promise<AgentResponse> {\n    const result = await this.mastraAgent.generate(prompt);\n    return result as unknown as AgentResponse;\n  }\n\n  /**\n   * Generates a streaming response from the agent.\n   * @param prompt - The user's prompt or input.\n   * @returns An async iterable that yields response chunks.\n   */\n  async *stream(prompt: string): AsyncGenerator<StreamChunk> {\n    const result = await this.mastraAgent.stream(prompt);\n    for await (const chunk of result.textStream) {\n      yield { content: typeof chunk === 'string' ? chunk : String(chunk) };\n    }\n  }\n}\n"],"mappings":";AAAA,SAAS,SAAS,mBAAmB;AAsE9B,IAAM,QAAN,MAAY;AAAA;AAAA,EAED;AAAA;AAAA,EAGA;AAAA;AAAA,EAGR;AAAA;AAAA;AAAA;AAAA;AAAA,EAMR,YAAY,QAAqB;AAC/B,SAAK,KAAK,OAAO;AACjB,SAAK,OAAO,OAAO;AAEnB,SAAK,cAAc,IAAI,YAAY;AAAA,MACjC,MAAM,OAAO;AAAA,MACb,cAAc,OAAO;AAAA,MACrB,OAAO,OAAO;AAAA,MACd,GAAI,OAAO,QAAQ,EAAE,OAAO,OAAO,MAA+B,IAAI,CAAC;AAAA,IACzE,CAAC;AAAA,EACH;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,SAAS,QAAwC;AACrD,UAAM,SAAS,MAAM,KAAK,YAAY,SAAS,MAAM;AACrD,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,OAAO,OAAO,QAA6C;AACzD,UAAM,SAAS,MAAM,KAAK,YAAY,OAAO,MAAM;AACnD,qBAAiB,SAAS,OAAO,YAAY;AAC3C,YAAM,EAAE,SAAS,OAAO,UAAU,WAAW,QAAQ,OAAO,KAAK,EAAE;AAAA,IACrE;AAAA,EACF;AACF;","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { Agent, AgentConfig, AgentResponse, StreamChunk } from './agent.js';
+export { SandboxConfig, SandboxExecutionError, SandboxManager, SandboxResult, SandboxRunOptions, TimeoutError } from './sandbox.js';
+export { MCPServer, Tool, ToolSchema } from './mcp-server.js';
+import 'ai';
+import 'zod';

package/dist/index.js

@@ -0,0 +1,212 @@
+// src/agent.ts
+import { Agent as MastraAgent } from "@mastra/core/agent";
+var Agent = class {
+  /** The agent's unique ID. */
+  id;
+  /** The agent's human-readable name. */
+  name;
+  /** The underlying Mastra agent instance. */
+  mastraAgent;
+  /**
+   * Creates a new AgentForge Agent.
+   * @param config - The configuration for the agent.
+   */
+  constructor(config) {
+    this.id = config.id;
+    this.name = config.name;
+    this.mastraAgent = new MastraAgent({
+      name: config.name,
+      instructions: config.instructions,
+      model: config.model,
+      ...config.tools ? { tools: config.tools } : {}
+    });
+  }
+  /**
+   * Generates a structured response from the agent.
+   * @param prompt - The user's prompt or input.
+   * @returns A promise that resolves to the agent's response.
+   */
+  async generate(prompt) {
+    const result = await this.mastraAgent.generate(prompt);
+    return result;
+  }
+  /**
+   * Generates a streaming response from the agent.
+   * @param prompt - The user's prompt or input.
+   * @returns An async iterable that yields response chunks.
+   */
+  async *stream(prompt) {
+    const result = await this.mastraAgent.stream(prompt);
+    for await (const chunk of result.textStream) {
+      yield { content: typeof chunk === "string" ? chunk : String(chunk) };
+    }
+  }
+};
+
+// src/sandbox.ts
+import { Sandbox } from "@e2b/code-interpreter";
+var TimeoutError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TimeoutError";
+  }
+};
+var SandboxExecutionError = class extends Error {
+  /** The name of the execution error (e.g., 'SyntaxError'). */
+  errorName;
+  /** The raw traceback from the sandbox. */
+  traceback;
+  constructor(name, value, traceback) {
+    super(`${name}: ${value}`);
+    this.name = "SandboxExecutionError";
+    this.errorName = name;
+    this.traceback = traceback;
+  }
+};
+var SandboxManager = class {
+  sandbox = null;
+  defaultTimeout;
+  /**
+   * Creates a new SandboxManager.
+   * @param config - The configuration for the sandbox manager.
+   */
+  constructor(config = {}) {
+    this.defaultTimeout = config.timeout ?? 3e4;
+  }
+  /**
+   * Executes a snippet of code within a secure E2B sandbox.
+   *
+   * @param code - The code to execute.
+   * @param options - Options for this specific run.
+   * @returns A promise that resolves to the result of the code execution.
+   * @throws {SandboxExecutionError} If the code throws an error.
+   */
+  async runCode(code, options) {
+    const timeoutMs = options?.timeout ?? this.defaultTimeout;
+    try {
+      this.sandbox = await Sandbox.create();
+      const execution = await this.sandbox.runCode(code, { timeoutMs });
+      if (execution.error) {
+        throw new SandboxExecutionError(
+          execution.error.name,
+          execution.error.value,
+          execution.error.traceback
+        );
+      }
+      return {
+        output: execution.results,
+        stdout: execution.logs.stdout,
+        stderr: execution.logs.stderr
+      };
+    } finally {
+      if (this.sandbox) {
+        await this.sandbox.kill();
+        this.sandbox = null;
+      }
+    }
+  }
+  /**
+   * Terminates the sandbox and releases all associated resources.
+   * @returns A promise that resolves when the cleanup is complete.
+   */
+  async cleanup() {
+    if (this.sandbox) {
+      await this.sandbox.kill();
+      this.sandbox = null;
+    }
+  }
+};
+
+// src/mcp-server.ts
+import { z } from "zod";
+var MCPServer = class {
+  tools = /* @__PURE__ */ new Map();
+  /**
+   * Registers a new tool with the MCP server.
+   *
+   * @param tool - The tool definition to register.
+   * @throws {Error} If a tool with the same name is already registered.
+   */
+  registerTool(tool) {
+    if (this.tools.has(tool.name)) {
+      throw new Error(`Tool with name '${tool.name}' is already registered.`);
+    }
+    this.tools.set(tool.name, tool);
+  }
+  /**
+   * Retrieves a list of all registered tools and their schemas.
+   *
+   * @returns An array of tool schema descriptors.
+   */
+  listTools() {
+    return Array.from(this.tools.values()).map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      inputSchema: this.zodToJsonSchema(tool.inputSchema),
+      outputSchema: this.zodToJsonSchema(tool.outputSchema)
+    }));
+  }
+  /**
+   * Invokes a specified tool with the provided input.
+   *
+   * @param toolName - The name of the tool to invoke.
+   * @param input - The input to the tool (will be validated against the schema).
+   * @returns A promise that resolves with the validated result.
+   * @throws {Error} If the tool is not found or input/output validation fails.
+   */
+  async callTool(toolName, input) {
+    const tool = this.tools.get(toolName);
+    if (!tool) {
+      throw new Error(`Tool with name '${toolName}' not found.`);
+    }
+    const parsedInput = tool.inputSchema.safeParse(input);
+    if (!parsedInput.success) {
+      throw new Error(
+        `Invalid input for tool '${toolName}': ${parsedInput.error.message}`
+      );
+    }
+    const result = await tool.handler(parsedInput.data);
+    const parsedOutput = tool.outputSchema.safeParse(result);
+    if (!parsedOutput.success) {
+      throw new Error(
+        `Invalid output from tool '${toolName}': ${parsedOutput.error.message}`
+      );
+    }
+    return parsedOutput.data;
+  }
+  /**
+   * Converts a Zod schema to a simplified JSON Schema representation.
+   * @param schema - The Zod schema to convert.
+   * @returns A simplified JSON Schema object.
+   */
+  zodToJsonSchema(schema) {
+    if (schema instanceof z.ZodObject) {
+      const shape = schema.shape;
+      const properties = {};
+      for (const [key, value] of Object.entries(shape)) {
+        properties[key] = { type: this.getZodTypeName(value) };
+      }
+      return { type: "object", properties };
+    }
+    return { type: this.getZodTypeName(schema) };
+  }
+  /**
+   * Gets the type name for a Zod schema.
+   */
+  getZodTypeName(schema) {
+    if (schema instanceof z.ZodString) return "string";
+    if (schema instanceof z.ZodNumber) return "number";
+    if (schema instanceof z.ZodBoolean) return "boolean";
+    if (schema instanceof z.ZodArray) return "array";
+    if (schema instanceof z.ZodObject) return "object";
+    return "unknown";
+  }
+};
+export {
+  Agent,
+  MCPServer,
+  SandboxExecutionError,
+  SandboxManager,
+  TimeoutError
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/agent.ts","../src/sandbox.ts","../src/mcp-server.ts"],"sourcesContent":["import { Agent as MastraAgent } from '@mastra/core/agent';\nimport type { LanguageModelV1 } from 'ai';\n\n/**\n * Configuration for creating an AgentForge Agent.\n */\nexport interface AgentConfig {\n  /** A unique identifier for the agent. */\n  id: string;\n  /** A human-readable name for the agent. */\n  name: string;\n  /** The system prompt or instructions for the agent. */\n  instructions: string;\n  /**\n   * The language model to use. Pass a LanguageModelV1 instance\n   * (e.g., from `@ai-sdk/openai`, `@ai-sdk/anthropic`, etc.).\n   *\n   * @example\n   * ```typescript\n   * import { openai } from '@ai-sdk/openai';\n   * const agent = new Agent({\n   *   model: openai('gpt-4o-mini'),\n   *   // ...\n   * });\n   * ```\n   */\n  model: LanguageModelV1;\n  /** A dictionary of tools available to the agent. */\n  tools?: Record<string, unknown>;\n}\n\n/**\n * Represents a structured response from an agent generation call.\n */\nexport interface AgentResponse {\n  /** The text content of the response. */\n  text: string;\n  /** Optional tool call results. */\n  toolResults?: unknown[];\n}\n\n/**\n * Represents a single chunk in a streaming response.\n */\nexport interface StreamChunk {\n  /** The text content of this chunk. */\n  content: string;\n}\n\n/**\n * The core Agent class for the AgentForge framework.\n *\n * Wraps the Mastra Agent to provide a simplified, curated API for\n * creating and interacting with AI agents. Supports any AI SDK-compatible\n * model provider (OpenAI, Anthropic, Google, etc.) via BYOK (Bring Your Own Key).\n *\n * @example\n * ```typescript\n * import { openai } from '@ai-sdk/openai';\n *\n * const agent = new Agent({\n *   id: 'my-agent',\n *   name: 'My Agent',\n *   instructions: 'You are a helpful assistant.',\n *   model: openai('gpt-4o-mini'),\n * });\n *\n * const response = await agent.generate('Hello!');\n * ```\n */\nexport class Agent {\n  /** The agent's unique ID. */\n  public readonly id: string;\n\n  /** The agent's human-readable name. */\n  public readonly name: string;\n\n  /** The underlying Mastra agent instance. */\n  private mastraAgent: MastraAgent;\n\n  /**\n   * Creates a new AgentForge Agent.\n   * @param config - The configuration for the agent.\n   */\n  constructor(config: AgentConfig) {\n    this.id = config.id;\n    this.name = config.name;\n\n    this.mastraAgent = new MastraAgent({\n      name: config.name,\n      instructions: config.instructions,\n      model: config.model,\n      ...(config.tools ? { tools: config.tools as Record<string, never> } : {}),\n    });\n  }\n\n  /**\n   * Generates a structured response from the agent.\n   * @param prompt - The user's prompt or input.\n   * @returns A promise that resolves to the agent's response.\n   */\n  async generate(prompt: string): Promise<AgentResponse> {\n    const result = await this.mastraAgent.generate(prompt);\n    return result as unknown as AgentResponse;\n  }\n\n  /**\n   * Generates a streaming response from the agent.\n   * @param prompt - The user's prompt or input.\n   * @returns An async iterable that yields response chunks.\n   */\n  async *stream(prompt: string): AsyncGenerator<StreamChunk> {\n    const result = await this.mastraAgent.stream(prompt);\n    for await (const chunk of result.textStream) {\n      yield { content: typeof chunk === 'string' ? chunk : String(chunk) };\n    }\n  }\n}\n","import { Sandbox } from '@e2b/code-interpreter';\n\n/**\n * Configuration for the SandboxManager.\n */\nexport interface SandboxConfig {\n  /**\n   * The default execution timeout in milliseconds.\n   * @default 30000\n   */\n  timeout?: number;\n}\n\n/**\n * Options for a specific sandbox run.\n */\nexport interface SandboxRunOptions {\n  /**\n   * The execution timeout in milliseconds for this specific run.\n   */\n  timeout?: number;\n}\n\n/**\n * Represents the result of a sandbox code execution.\n */\nexport interface SandboxResult {\n  /** The output/results from the code execution. */\n  output: unknown;\n  /** Stdout logs produced during execution. */\n  stdout?: string[];\n  /** Stderr logs produced during execution. */\n  stderr?: string[];\n}\n\n/**\n * A custom error class for sandbox timeouts.\n */\nexport class TimeoutError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'TimeoutError';\n  }\n}\n\n/**\n * A custom error class for sandbox execution errors.\n */\nexport class SandboxExecutionError extends Error {\n  /** The name of the execution error (e.g., 'SyntaxError'). */\n  public readonly errorName: string;\n  /** The raw traceback from the sandbox. */\n  public readonly traceback: string;\n\n  constructor(name: string, value: string, traceback: string) {\n    super(`${name}: ${value}`);\n    this.name = 'SandboxExecutionError';\n    this.errorName = name;\n    this.traceback = traceback;\n  }\n}\n\n/**\n * Manages the lifecycle of E2B sandboxes for secure code execution.\n *\n * All tool code execution in AgentForge MUST occur within an E2B sandbox\n * to ensure security isolation and prevent malicious code from affecting\n * the host system.\n *\n * @example\n * ```typescript\n * const manager = new SandboxManager({ timeout: 10000 });\n * const result = await manager.runCode('1 + 1');\n * console.log(result); // { output: [...], stdout: [], stderr: [] }\n * ```\n */\nexport class SandboxManager {\n  private sandbox: Sandbox | null = null;\n  private defaultTimeout: number;\n\n  /**\n   * Creates a new SandboxManager.\n   * @param config - The configuration for the sandbox manager.\n   */\n  constructor(config: SandboxConfig = {}) {\n    this.defaultTimeout = config.timeout ?? 30000;\n  }\n\n  /**\n   * Executes a snippet of code within a secure E2B sandbox.\n   *\n   * @param code - The code to execute.\n   * @param options - Options for this specific run.\n   * @returns A promise that resolves to the result of the code execution.\n   * @throws {SandboxExecutionError} If the code throws an error.\n   */\n  async runCode(code: string, options?: SandboxRunOptions): Promise<SandboxResult> {\n    const timeoutMs = options?.timeout ?? this.defaultTimeout;\n\n    try {\n      this.sandbox = await Sandbox.create();\n      const execution = await this.sandbox.runCode(code, { timeoutMs });\n\n      if (execution.error) {\n        throw new SandboxExecutionError(\n          execution.error.name,\n          execution.error.value,\n          execution.error.traceback,\n        );\n      }\n\n      return {\n        output: execution.results,\n        stdout: execution.logs.stdout,\n        stderr: execution.logs.stderr,\n      };\n    } finally {\n      if (this.sandbox) {\n        await this.sandbox.kill();\n        this.sandbox = null;\n      }\n    }\n  }\n\n  /**\n   * Terminates the sandbox and releases all associated resources.\n   * @returns A promise that resolves when the cleanup is complete.\n   */\n  async cleanup(): Promise<void> {\n    if (this.sandbox) {\n      await this.sandbox.kill();\n      this.sandbox = null;\n    }\n  }\n}\n","import { z } from 'zod';\n\n/**\n * Schema descriptor for tool listing.\n */\nexport interface ToolSchema {\n  /** The unique name of the tool. */\n  name: string;\n  /** A human-readable description of the tool. */\n  description?: string;\n  /** JSON Schema representation of the input. */\n  inputSchema: Record<string, unknown>;\n  /** JSON Schema representation of the output. */\n  outputSchema: Record<string, unknown>;\n}\n\n/**\n * Represents a tool that can be registered and executed by the MCP server.\n *\n * @typeParam TInput - The Zod schema type for the tool's input.\n * @typeParam TOutput - The Zod schema type for the tool's output.\n */\nexport interface Tool<\n  TInput extends z.ZodTypeAny = z.ZodTypeAny,\n  TOutput extends z.ZodTypeAny = z.ZodTypeAny,\n> {\n  /** The unique name of the tool. */\n  name: string;\n  /** A human-readable description of the tool. */\n  description?: string;\n  /** The Zod schema for the tool's input. */\n  inputSchema: TInput;\n  /** The Zod schema for the tool's output. */\n  outputSchema: TOutput;\n  /**\n   * The function that implements the tool's logic.\n   * @param input - The validated input matching the input schema.\n   * @returns A promise that resolves with the tool's output.\n   */\n  handler: (input: z.infer<TInput>) => Promise<z.infer<TOutput>>;\n}\n\n/**\n * A server that implements the Model Context Protocol (MCP) for tool communication.\n *\n * Provides a central registry for tools that agents can discover and invoke.\n * All tool inputs and outputs are validated against their Zod schemas.\n *\n * @example\n * ```typescript\n * const server = new MCPServer();\n *\n * server.registerTool({\n *   name: 'add',\n *   description: 'Adds two numbers',\n *   inputSchema: z.object({ a: z.number(), b: z.number() }),\n *   outputSchema: z.number(),\n *   handler: async ({ a, b }) => a + b,\n * });\n *\n * const result = await server.callTool('add', { a: 5, b: 3 });\n * // result === 8\n * ```\n */\nexport class MCPServer {\n  private tools: Map<string, Tool> = new Map();\n\n  /**\n   * Registers a new tool with the MCP server.\n   *\n   * @param tool - The tool definition to register.\n   * @throws {Error} If a tool with the same name is already registered.\n   */\n  public registerTool<\n    TInput extends z.ZodTypeAny,\n    TOutput extends z.ZodTypeAny,\n  >(tool: Tool<TInput, TOutput>): void {\n    if (this.tools.has(tool.name)) {\n      throw new Error(`Tool with name '${tool.name}' is already registered.`);\n    }\n    this.tools.set(tool.name, tool as unknown as Tool);\n  }\n\n  /**\n   * Retrieves a list of all registered tools and their schemas.\n   *\n   * @returns An array of tool schema descriptors.\n   */\n  public listTools(): ToolSchema[] {\n    return Array.from(this.tools.values()).map((tool) => ({\n      name: tool.name,\n      description: tool.description,\n      inputSchema: this.zodToJsonSchema(tool.inputSchema),\n      outputSchema: this.zodToJsonSchema(tool.outputSchema),\n    }));\n  }\n\n  /**\n   * Invokes a specified tool with the provided input.\n   *\n   * @param toolName - The name of the tool to invoke.\n   * @param input - The input to the tool (will be validated against the schema).\n   * @returns A promise that resolves with the validated result.\n   * @throws {Error} If the tool is not found or input/output validation fails.\n   */\n  public async callTool(toolName: string, input: unknown): Promise<unknown> {\n    const tool = this.tools.get(toolName);\n    if (!tool) {\n      throw new Error(`Tool with name '${toolName}' not found.`);\n    }\n\n    const parsedInput = tool.inputSchema.safeParse(input);\n    if (!parsedInput.success) {\n      throw new Error(\n        `Invalid input for tool '${toolName}': ${parsedInput.error.message}`\n      );\n    }\n\n    const result = await tool.handler(parsedInput.data);\n\n    const parsedOutput = tool.outputSchema.safeParse(result);\n    if (!parsedOutput.success) {\n      throw new Error(\n        `Invalid output from tool '${toolName}': ${parsedOutput.error.message}`\n      );\n    }\n\n    return parsedOutput.data;\n  }\n\n  /**\n   * Converts a Zod schema to a simplified JSON Schema representation.\n   * @param schema - The Zod schema to convert.\n   * @returns A simplified JSON Schema object.\n   */\n  private zodToJsonSchema(schema: z.ZodTypeAny): Record<string, unknown> {\n    // Simple conversion - in production, use zod-to-json-schema\n    if (schema instanceof z.ZodObject) {\n      const shape = schema.shape;\n      const properties: Record<string, unknown> = {};\n      for (const [key, value] of Object.entries(shape)) {\n        properties[key] = { type: this.getZodTypeName(value as z.ZodTypeAny) };\n      }\n      return { type: 'object', properties };\n    }\n    return { type: this.getZodTypeName(schema) };\n  }\n\n  /**\n   * Gets the type name for a Zod schema.\n   */\n  private getZodTypeName(schema: z.ZodTypeAny): string {\n    if (schema instanceof z.ZodString) return 'string';\n    if (schema instanceof z.ZodNumber) return 'number';\n    if (schema instanceof z.ZodBoolean) return 'boolean';\n    if (schema instanceof z.ZodArray) return 'array';\n    if (schema instanceof z.ZodObject) return 'object';\n    return 'unknown';\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/mcp-server.d.ts

@@ -0,0 +1,96 @@
+import { z } from 'zod';
+
+/**
+ * Schema descriptor for tool listing.
+ */
+interface ToolSchema {
+    /** The unique name of the tool. */
+    name: string;
+    /** A human-readable description of the tool. */
+    description?: string;
+    /** JSON Schema representation of the input. */
+    inputSchema: Record<string, unknown>;
+    /** JSON Schema representation of the output. */
+    outputSchema: Record<string, unknown>;
+}
+/**
+ * Represents a tool that can be registered and executed by the MCP server.
+ *
+ * @typeParam TInput - The Zod schema type for the tool's input.
+ * @typeParam TOutput - The Zod schema type for the tool's output.
+ */
+interface Tool<TInput extends z.ZodTypeAny = z.ZodTypeAny, TOutput extends z.ZodTypeAny = z.ZodTypeAny> {
+    /** The unique name of the tool. */
+    name: string;
+    /** A human-readable description of the tool. */
+    description?: string;
+    /** The Zod schema for the tool's input. */
+    inputSchema: TInput;
+    /** The Zod schema for the tool's output. */
+    outputSchema: TOutput;
+    /**
+     * The function that implements the tool's logic.
+     * @param input - The validated input matching the input schema.
+     * @returns A promise that resolves with the tool's output.
+     */
+    handler: (input: z.infer<TInput>) => Promise<z.infer<TOutput>>;
+}
+/**
+ * A server that implements the Model Context Protocol (MCP) for tool communication.
+ *
+ * Provides a central registry for tools that agents can discover and invoke.
+ * All tool inputs and outputs are validated against their Zod schemas.
+ *
+ * @example
+ * ```typescript
+ * const server = new MCPServer();
+ *
+ * server.registerTool({
+ *   name: 'add',
+ *   description: 'Adds two numbers',
+ *   inputSchema: z.object({ a: z.number(), b: z.number() }),
+ *   outputSchema: z.number(),
+ *   handler: async ({ a, b }) => a + b,
+ * });
+ *
+ * const result = await server.callTool('add', { a: 5, b: 3 });
+ * // result === 8
+ * ```
+ */
+declare class MCPServer {
+    private tools;
+    /**
+     * Registers a new tool with the MCP server.
+     *
+     * @param tool - The tool definition to register.
+     * @throws {Error} If a tool with the same name is already registered.
+     */
+    registerTool<TInput extends z.ZodTypeAny, TOutput extends z.ZodTypeAny>(tool: Tool<TInput, TOutput>): void;
+    /**
+     * Retrieves a list of all registered tools and their schemas.
+     *
+     * @returns An array of tool schema descriptors.
+     */
+    listTools(): ToolSchema[];
+    /**
+     * Invokes a specified tool with the provided input.
+     *
+     * @param toolName - The name of the tool to invoke.
+     * @param input - The input to the tool (will be validated against the schema).
+     * @returns A promise that resolves with the validated result.
+     * @throws {Error} If the tool is not found or input/output validation fails.
+     */
+    callTool(toolName: string, input: unknown): Promise<unknown>;
+    /**
+     * Converts a Zod schema to a simplified JSON Schema representation.
+     * @param schema - The Zod schema to convert.
+     * @returns A simplified JSON Schema object.
+     */
+    private zodToJsonSchema;
+    /**
+     * Gets the type name for a Zod schema.
+     */
+    private getZodTypeName;
+}
+
+export { MCPServer, type Tool, type ToolSchema };

package/dist/mcp-server.js

@@ -0,0 +1,89 @@
+// src/mcp-server.ts
+import { z } from "zod";
+var MCPServer = class {
+  tools = /* @__PURE__ */ new Map();
+  /**
+   * Registers a new tool with the MCP server.
+   *
+   * @param tool - The tool definition to register.
+   * @throws {Error} If a tool with the same name is already registered.
+   */
+  registerTool(tool) {
+    if (this.tools.has(tool.name)) {
+      throw new Error(`Tool with name '${tool.name}' is already registered.`);
+    }
+    this.tools.set(tool.name, tool);
+  }
+  /**
+   * Retrieves a list of all registered tools and their schemas.
+   *
+   * @returns An array of tool schema descriptors.
+   */
+  listTools() {
+    return Array.from(this.tools.values()).map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      inputSchema: this.zodToJsonSchema(tool.inputSchema),
+      outputSchema: this.zodToJsonSchema(tool.outputSchema)
+    }));
+  }
+  /**
+   * Invokes a specified tool with the provided input.
+   *
+   * @param toolName - The name of the tool to invoke.
+   * @param input - The input to the tool (will be validated against the schema).
+   * @returns A promise that resolves with the validated result.
+   * @throws {Error} If the tool is not found or input/output validation fails.
+   */
+  async callTool(toolName, input) {
+    const tool = this.tools.get(toolName);
+    if (!tool) {
+      throw new Error(`Tool with name '${toolName}' not found.`);
+    }
+    const parsedInput = tool.inputSchema.safeParse(input);
+    if (!parsedInput.success) {
+      throw new Error(
+        `Invalid input for tool '${toolName}': ${parsedInput.error.message}`
+      );
+    }
+    const result = await tool.handler(parsedInput.data);
+    const parsedOutput = tool.outputSchema.safeParse(result);
+    if (!parsedOutput.success) {
+      throw new Error(
+        `Invalid output from tool '${toolName}': ${parsedOutput.error.message}`
+      );
+    }
+    return parsedOutput.data;
+  }
+  /**
+   * Converts a Zod schema to a simplified JSON Schema representation.
+   * @param schema - The Zod schema to convert.
+   * @returns A simplified JSON Schema object.
+   */
+  zodToJsonSchema(schema) {
+    if (schema instanceof z.ZodObject) {
+      const shape = schema.shape;
+      const properties = {};
+      for (const [key, value] of Object.entries(shape)) {
+        properties[key] = { type: this.getZodTypeName(value) };
+      }
+      return { type: "object", properties };
+    }
+    return { type: this.getZodTypeName(schema) };
+  }
+  /**
+   * Gets the type name for a Zod schema.
+   */
+  getZodTypeName(schema) {
+    if (schema instanceof z.ZodString) return "string";
+    if (schema instanceof z.ZodNumber) return "number";
+    if (schema instanceof z.ZodBoolean) return "boolean";
+    if (schema instanceof z.ZodArray) return "array";
+    if (schema instanceof z.ZodObject) return "object";
+    return "unknown";
+  }
+};
+export {
+  MCPServer
+};
+//# sourceMappingURL=mcp-server.js.map

package/dist/mcp-server.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/mcp-server.ts"],"sourcesContent":["import { z } from 'zod';\n\n/**\n * Schema descriptor for tool listing.\n */\nexport interface ToolSchema {\n  /** The unique name of the tool. */\n  name: string;\n  /** A human-readable description of the tool. */\n  description?: string;\n  /** JSON Schema representation of the input. */\n  inputSchema: Record<string, unknown>;\n  /** JSON Schema representation of the output. */\n  outputSchema: Record<string, unknown>;\n}\n\n/**\n * Represents a tool that can be registered and executed by the MCP server.\n *\n * @typeParam TInput - The Zod schema type for the tool's input.\n * @typeParam TOutput - The Zod schema type for the tool's output.\n */\nexport interface Tool<\n  TInput extends z.ZodTypeAny = z.ZodTypeAny,\n  TOutput extends z.ZodTypeAny = z.ZodTypeAny,\n> {\n  /** The unique name of the tool. */\n  name: string;\n  /** A human-readable description of the tool. */\n  description?: string;\n  /** The Zod schema for the tool's input. */\n  inputSchema: TInput;\n  /** The Zod schema for the tool's output. */\n  outputSchema: TOutput;\n  /**\n   * The function that implements the tool's logic.\n   * @param input - The validated input matching the input schema.\n   * @returns A promise that resolves with the tool's output.\n   */\n  handler: (input: z.infer<TInput>) => Promise<z.infer<TOutput>>;\n}\n\n/**\n * A server that implements the Model Context Protocol (MCP) for tool communication.\n *\n * Provides a central registry for tools that agents can discover and invoke.\n * All tool inputs and outputs are validated against their Zod schemas.\n *\n * @example\n * ```typescript\n * const server = new MCPServer();\n *\n * server.registerTool({\n *   name: 'add',\n *   description: 'Adds two numbers',\n *   inputSchema: z.object({ a: z.number(), b: z.number() }),\n *   outputSchema: z.number(),\n *   handler: async ({ a, b }) => a + b,\n * });\n *\n * const result = await server.callTool('add', { a: 5, b: 3 });\n * // result === 8\n * ```\n */\nexport class MCPServer {\n  private tools: Map<string, Tool> = new Map();\n\n  /**\n   * Registers a new tool with the MCP server.\n   *\n   * @param tool - The tool definition to register.\n   * @throws {Error} If a tool with the same name is already registered.\n   */\n  public registerTool<\n    TInput extends z.ZodTypeAny,\n    TOutput extends z.ZodTypeAny,\n  >(tool: Tool<TInput, TOutput>): void {\n    if (this.tools.has(tool.name)) {\n      throw new Error(`Tool with name '${tool.name}' is already registered.`);\n    }\n    this.tools.set(tool.name, tool as unknown as Tool);\n  }\n\n  /**\n   * Retrieves a list of all registered tools and their schemas.\n   *\n   * @returns An array of tool schema descriptors.\n   */\n  public listTools(): ToolSchema[] {\n    return Array.from(this.tools.values()).map((tool) => ({\n      name: tool.name,\n      description: tool.description,\n      inputSchema: this.zodToJsonSchema(tool.inputSchema),\n      outputSchema: this.zodToJsonSchema(tool.outputSchema),\n    }));\n  }\n\n  /**\n   * Invokes a specified tool with the provided input.\n   *\n   * @param toolName - The name of the tool to invoke.\n   * @param input - The input to the tool (will be validated against the schema).\n   * @returns A promise that resolves with the validated result.\n   * @throws {Error} If the tool is not found or input/output validation fails.\n   */\n  public async callTool(toolName: string, input: unknown): Promise<unknown> {\n    const tool = this.tools.get(toolName);\n    if (!tool) {\n      throw new Error(`Tool with name '${toolName}' not found.`);\n    }\n\n    const parsedInput = tool.inputSchema.safeParse(input);\n    if (!parsedInput.success) {\n      throw new Error(\n        `Invalid input for tool '${toolName}': ${parsedInput.error.message}`\n      );\n    }\n\n    const result = await tool.handler(parsedInput.data);\n\n    const parsedOutput = tool.outputSchema.safeParse(result);\n    if (!parsedOutput.success) {\n      throw new Error(\n        `Invalid output from tool '${toolName}': ${parsedOutput.error.message}`\n      );\n    }\n\n    return parsedOutput.data;\n  }\n\n  /**\n   * Converts a Zod schema to a simplified JSON Schema representation.\n   * @param schema - The Zod schema to convert.\n   * @returns A simplified JSON Schema object.\n   */\n  private zodToJsonSchema(schema: z.ZodTypeAny): Record<string, unknown> {\n    // Simple conversion - in production, use zod-to-json-schema\n    if (schema instanceof z.ZodObject) {\n      const shape = schema.shape;\n      const properties: Record<string, unknown> = {};\n      for (const [key, value] of Object.entries(shape)) {\n        properties[key] = { type: this.getZodTypeName(value as z.ZodTypeAny) };\n      }\n      return { type: 'object', properties };\n    }\n    return { type: this.getZodTypeName(schema) };\n  }\n\n  /**\n   * Gets the type name for a Zod schema.\n   */\n  private getZodTypeName(schema: z.ZodTypeAny): string {\n    if (schema instanceof z.ZodString) return 'string';\n    if (schema instanceof z.ZodNumber) return 'number';\n    if (schema instanceof z.ZodBoolean) return 'boolean';\n    if (schema instanceof z.ZodArray) return 'array';\n    if (schema instanceof z.ZodObject) return 'object';\n    return 'unknown';\n  }\n}\n"],"mappings":";AAAA,SAAS,SAAS;AAgEX,IAAM,YAAN,MAAgB;AAAA,EACb,QAA2B,oBAAI,IAAI;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQpC,aAGL,MAAmC;AACnC,QAAI,KAAK,MAAM,IAAI,KAAK,IAAI,GAAG;AAC7B,YAAM,IAAI,MAAM,mBAAmB,KAAK,IAAI,0BAA0B;AAAA,IACxE;AACA,SAAK,MAAM,IAAI,KAAK,MAAM,IAAuB;AAAA,EACnD;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOO,YAA0B;AAC/B,WAAO,MAAM,KAAK,KAAK,MAAM,OAAO,CAAC,EAAE,IAAI,CAAC,UAAU;AAAA,MACpD,MAAM,KAAK;AAAA,MACX,aAAa,KAAK;AAAA,MAClB,aAAa,KAAK,gBAAgB,KAAK,WAAW;AAAA,MAClD,cAAc,KAAK,gBAAgB,KAAK,YAAY;AAAA,IACtD,EAAE;AAAA,EACJ;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,MAAa,SAAS,UAAkB,OAAkC;AACxE,UAAM,OAAO,KAAK,MAAM,IAAI,QAAQ;AACpC,QAAI,CAAC,MAAM;AACT,YAAM,IAAI,MAAM,mBAAmB,QAAQ,cAAc;AAAA,IAC3D;AAEA,UAAM,cAAc,KAAK,YAAY,UAAU,KAAK;AACpD,QAAI,CAAC,YAAY,SAAS;AACxB,YAAM,IAAI;AAAA,QACR,2BAA2B,QAAQ,MAAM,YAAY,MAAM,OAAO;AAAA,MACpE;AAAA,IACF;AAEA,UAAM,SAAS,MAAM,KAAK,QAAQ,YAAY,IAAI;AAElD,UAAM,eAAe,KAAK,aAAa,UAAU,MAAM;AACvD,QAAI,CAAC,aAAa,SAAS;AACzB,YAAM,IAAI;AAAA,QACR,6BAA6B,QAAQ,MAAM,aAAa,MAAM,OAAO;AAAA,MACvE;AAAA,IACF;AAEA,WAAO,aAAa;AAAA,EACtB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOQ,gBAAgB,QAA+C;AAErE,QAAI,kBAAkB,EAAE,WAAW;AACjC,YAAM,QAAQ,OAAO;AACrB,YAAM,aAAsC,CAAC;AAC7C,iBAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,KAAK,GAAG;AAChD,mBAAW,GAAG,IAAI,EAAE,MAAM,KAAK,eAAe,KAAqB,EAAE;AAAA,MACvE;AACA,aAAO,EAAE,MAAM,UAAU,WAAW;AAAA,IACtC;AACA,WAAO,EAAE,MAAM,KAAK,eAAe,MAAM,EAAE;AAAA,EAC7C;AAAA;AAAA;AAAA;AAAA,EAKQ,eAAe,QAA8B;AACnD,QAAI,kBAAkB,EAAE,UAAW,QAAO;AAC1C,QAAI,kBAAkB,EAAE,UAAW,QAAO;AAC1C,QAAI,kBAAkB,EAAE,WAAY,QAAO;AAC3C,QAAI,kBAAkB,EAAE,SAAU,QAAO;AACzC,QAAI,kBAAkB,EAAE,UAAW,QAAO;AAC1C,WAAO;AAAA,EACT;AACF;","names":[]}

package/dist/sandbox.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Configuration for the SandboxManager.
+ */
+interface SandboxConfig {
+    /**
+     * The default execution timeout in milliseconds.
+     * @default 30000
+     */
+    timeout?: number;
+}
+/**
+ * Options for a specific sandbox run.
+ */
+interface SandboxRunOptions {
+    /**
+     * The execution timeout in milliseconds for this specific run.
+     */
+    timeout?: number;
+}
+/**
+ * Represents the result of a sandbox code execution.
+ */
+interface SandboxResult {
+    /** The output/results from the code execution. */
+    output: unknown;
+    /** Stdout logs produced during execution. */
+    stdout?: string[];
+    /** Stderr logs produced during execution. */
+    stderr?: string[];
+}
+/**
+ * A custom error class for sandbox timeouts.
+ */
+declare class TimeoutError extends Error {
+    constructor(message: string);
+}
+/**
+ * A custom error class for sandbox execution errors.
+ */
+declare class SandboxExecutionError extends Error {
+    /** The name of the execution error (e.g., 'SyntaxError'). */
+    readonly errorName: string;
+    /** The raw traceback from the sandbox. */
+    readonly traceback: string;
+    constructor(name: string, value: string, traceback: string);
+}
+/**
+ * Manages the lifecycle of E2B sandboxes for secure code execution.
+ *
+ * All tool code execution in AgentForge MUST occur within an E2B sandbox
+ * to ensure security isolation and prevent malicious code from affecting
+ * the host system.
+ *
+ * @example
+ * ```typescript
+ * const manager = new SandboxManager({ timeout: 10000 });
+ * const result = await manager.runCode('1 + 1');
+ * console.log(result); // { output: [...], stdout: [], stderr: [] }
+ * ```
+ */
+declare class SandboxManager {
+    private sandbox;
+    private defaultTimeout;
+    /**
+     * Creates a new SandboxManager.
+     * @param config - The configuration for the sandbox manager.
+     */
+    constructor(config?: SandboxConfig);
+    /**
+     * Executes a snippet of code within a secure E2B sandbox.
+     *
+     * @param code - The code to execute.
+     * @param options - Options for this specific run.
+     * @returns A promise that resolves to the result of the code execution.
+     * @throws {SandboxExecutionError} If the code throws an error.
+     */
+    runCode(code: string, options?: SandboxRunOptions): Promise<SandboxResult>;
+    /**
+     * Terminates the sandbox and releases all associated resources.
+     * @returns A promise that resolves when the cleanup is complete.
+     */
+    cleanup(): Promise<void>;
+}
+
+export { type SandboxConfig, SandboxExecutionError, SandboxManager, type SandboxResult, type SandboxRunOptions, TimeoutError };

package/dist/sandbox.js

@@ -0,0 +1,79 @@
+// src/sandbox.ts
+import { Sandbox } from "@e2b/code-interpreter";
+var TimeoutError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TimeoutError";
+  }
+};
+var SandboxExecutionError = class extends Error {
+  /** The name of the execution error (e.g., 'SyntaxError'). */
+  errorName;
+  /** The raw traceback from the sandbox. */
+  traceback;
+  constructor(name, value, traceback) {
+    super(`${name}: ${value}`);
+    this.name = "SandboxExecutionError";
+    this.errorName = name;
+    this.traceback = traceback;
+  }
+};
+var SandboxManager = class {
+  sandbox = null;
+  defaultTimeout;
+  /**
+   * Creates a new SandboxManager.
+   * @param config - The configuration for the sandbox manager.
+   */
+  constructor(config = {}) {
+    this.defaultTimeout = config.timeout ?? 3e4;
+  }
+  /**
+   * Executes a snippet of code within a secure E2B sandbox.
+   *
+   * @param code - The code to execute.
+   * @param options - Options for this specific run.
+   * @returns A promise that resolves to the result of the code execution.
+   * @throws {SandboxExecutionError} If the code throws an error.
+   */
+  async runCode(code, options) {
+    const timeoutMs = options?.timeout ?? this.defaultTimeout;
+    try {
+      this.sandbox = await Sandbox.create();
+      const execution = await this.sandbox.runCode(code, { timeoutMs });
+      if (execution.error) {
+        throw new SandboxExecutionError(
+          execution.error.name,
+          execution.error.value,
+          execution.error.traceback
+        );
+      }
+      return {
+        output: execution.results,
+        stdout: execution.logs.stdout,
+        stderr: execution.logs.stderr
+      };
+    } finally {
+      if (this.sandbox) {
+        await this.sandbox.kill();
+        this.sandbox = null;
+      }
+    }
+  }
+  /**
+   * Terminates the sandbox and releases all associated resources.
+   * @returns A promise that resolves when the cleanup is complete.
+   */
+  async cleanup() {
+    if (this.sandbox) {
+      await this.sandbox.kill();
+      this.sandbox = null;
+    }
+  }
+};
+export {
+  SandboxExecutionError,
+  SandboxManager,
+  TimeoutError
+};
+//# sourceMappingURL=sandbox.js.map

package/dist/sandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/sandbox.ts"],"sourcesContent":["import { Sandbox } from '@e2b/code-interpreter';\n\n/**\n * Configuration for the SandboxManager.\n */\nexport interface SandboxConfig {\n  /**\n   * The default execution timeout in milliseconds.\n   * @default 30000\n   */\n  timeout?: number;\n}\n\n/**\n * Options for a specific sandbox run.\n */\nexport interface SandboxRunOptions {\n  /**\n   * The execution timeout in milliseconds for this specific run.\n   */\n  timeout?: number;\n}\n\n/**\n * Represents the result of a sandbox code execution.\n */\nexport interface SandboxResult {\n  /** The output/results from the code execution. */\n  output: unknown;\n  /** Stdout logs produced during execution. */\n  stdout?: string[];\n  /** Stderr logs produced during execution. */\n  stderr?: string[];\n}\n\n/**\n * A custom error class for sandbox timeouts.\n */\nexport class TimeoutError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'TimeoutError';\n  }\n}\n\n/**\n * A custom error class for sandbox execution errors.\n */\nexport class SandboxExecutionError extends Error {\n  /** The name of the execution error (e.g., 'SyntaxError'). */\n  public readonly errorName: string;\n  /** The raw traceback from the sandbox. */\n  public readonly traceback: string;\n\n  constructor(name: string, value: string, traceback: string) {\n    super(`${name}: ${value}`);\n    this.name = 'SandboxExecutionError';\n    this.errorName = name;\n    this.traceback = traceback;\n  }\n}\n\n/**\n * Manages the lifecycle of E2B sandboxes for secure code execution.\n *\n * All tool code execution in AgentForge MUST occur within an E2B sandbox\n * to ensure security isolation and prevent malicious code from affecting\n * the host system.\n *\n * @example\n * ```typescript\n * const manager = new SandboxManager({ timeout: 10000 });\n * const result = await manager.runCode('1 + 1');\n * console.log(result); // { output: [...], stdout: [], stderr: [] }\n * ```\n */\nexport class SandboxManager {\n  private sandbox: Sandbox | null = null;\n  private defaultTimeout: number;\n\n  /**\n   * Creates a new SandboxManager.\n   * @param config - The configuration for the sandbox manager.\n   */\n  constructor(config: SandboxConfig = {}) {\n    this.defaultTimeout = config.timeout ?? 30000;\n  }\n\n  /**\n   * Executes a snippet of code within a secure E2B sandbox.\n   *\n   * @param code - The code to execute.\n   * @param options - Options for this specific run.\n   * @returns A promise that resolves to the result of the code execution.\n   * @throws {SandboxExecutionError} If the code throws an error.\n   */\n  async runCode(code: string, options?: SandboxRunOptions): Promise<SandboxResult> {\n    const timeoutMs = options?.timeout ?? this.defaultTimeout;\n\n    try {\n      this.sandbox = await Sandbox.create();\n      const execution = await this.sandbox.runCode(code, { timeoutMs });\n\n      if (execution.error) {\n        throw new SandboxExecutionError(\n          execution.error.name,\n          execution.error.value,\n          execution.error.traceback,\n        );\n      }\n\n      return {\n        output: execution.results,\n        stdout: execution.logs.stdout,\n        stderr: execution.logs.stderr,\n      };\n    } finally {\n      if (this.sandbox) {\n        await this.sandbox.kill();\n        this.sandbox = null;\n      }\n    }\n  }\n\n  /**\n   * Terminates the sandbox and releases all associated resources.\n   * @returns A promise that resolves when the cleanup is complete.\n   */\n  async cleanup(): Promise<void> {\n    if (this.sandbox) {\n      await this.sandbox.kill();\n      this.sandbox = null;\n    }\n  }\n}\n"],"mappings":";AAAA,SAAS,eAAe;AAsCjB,IAAM,eAAN,cAA2B,MAAM;AAAA,EACtC,YAAY,SAAiB;AAC3B,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;AAKO,IAAM,wBAAN,cAAoC,MAAM;AAAA;AAAA,EAE/B;AAAA;AAAA,EAEA;AAAA,EAEhB,YAAY,MAAc,OAAe,WAAmB;AAC1D,UAAM,GAAG,IAAI,KAAK,KAAK,EAAE;AACzB,SAAK,OAAO;AACZ,SAAK,YAAY;AACjB,SAAK,YAAY;AAAA,EACnB;AACF;AAgBO,IAAM,iBAAN,MAAqB;AAAA,EAClB,UAA0B;AAAA,EAC1B;AAAA;AAAA;AAAA;AAAA;AAAA,EAMR,YAAY,SAAwB,CAAC,GAAG;AACtC,SAAK,iBAAiB,OAAO,WAAW;AAAA,EAC1C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,MAAM,QAAQ,MAAc,SAAqD;AAC/E,UAAM,YAAY,SAAS,WAAW,KAAK;AAE3C,QAAI;AACF,WAAK,UAAU,MAAM,QAAQ,OAAO;AACpC,YAAM,YAAY,MAAM,KAAK,QAAQ,QAAQ,MAAM,EAAE,UAAU,CAAC;AAEhE,UAAI,UAAU,OAAO;AACnB,cAAM,IAAI;AAAA,UACR,UAAU,MAAM;AAAA,UAChB,UAAU,MAAM;AAAA,UAChB,UAAU,MAAM;AAAA,QAClB;AAAA,MACF;AAEA,aAAO;AAAA,QACL,QAAQ,UAAU;AAAA,QAClB,QAAQ,UAAU,KAAK;AAAA,QACvB,QAAQ,UAAU,KAAK;AAAA,MACzB;AAAA,IACF,UAAE;AACA,UAAI,KAAK,SAAS;AAChB,cAAM,KAAK,QAAQ,KAAK;AACxB,aAAK,UAAU;AAAA,MACjB;AAAA,IACF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,MAAM,UAAyB;AAC7B,QAAI,KAAK,SAAS;AAChB,YAAM,KAAK,QAAQ,KAAK;AACxB,WAAK,UAAU;AAAA,IACjB;AAAA,EACF;AACF;","names":[]}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@agentforge-ai/core",
+  "version": "0.1.0",
+  "description": "Core agent primitives, sandbox integration, and MCP server for AgentForge",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./agent": {
+      "types": "./dist/agent.d.ts",
+      "import": "./dist/agent.js"
+    },
+    "./sandbox": {
+      "types": "./dist/sandbox.d.ts",
+      "import": "./dist/sandbox.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp-server.d.ts",
+      "import": "./dist/mcp-server.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@mastra/core": "^0.5.0",
+    "ai": "^4.0.0",
+    "@e2b/code-interpreter": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "mastra",
+    "mcp",
+    "e2b",
+    "sandbox",
+    "multi-agent"
+  ],
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Agentic-Engineering-Agency/agentforge.git",
+    "directory": "packages/core"
+  }
+}