agentkernel 0.2.0

package/README.md

@@ -0,0 +1,114 @@
+# agentkernel
+
+Node.js SDK for [agentkernel](https://github.com/thrashr888/agentkernel) — run AI coding agents in secure, isolated microVMs.
+
+## Install
+
+```bash
+npm install agentkernel
+```
+
+Requires Node.js 20+. Zero HTTP dependencies (uses native `fetch`).
+
+## Quick Start
+
+```typescript
+import { AgentKernel } from "agentkernel";
+
+const client = new AgentKernel();
+
+// Run a command in a temporary sandbox
+const result = await client.run(["echo", "hello"]);
+console.log(result.output); // "hello\n"
+```
+
+## Sandbox Sessions
+
+Create a persistent sandbox with automatic cleanup:
+
+```typescript
+await using sb = await client.sandbox("my-project", {
+  image: "python:3.12-alpine",
+});
+
+await sb.run(["pip", "install", "numpy"]);
+const result = await sb.run(["python3", "-c", "import numpy; print(numpy.__version__)"]);
+console.log(result.output);
+// sandbox auto-removed when scope exits
+```
+
+## Streaming
+
+```typescript
+for await (const event of client.runStream(["python3", "script.py"])) {
+  if (event.type === "output") process.stdout.write(String(event.data.data));
+}
+```
+
+## Configuration
+
+```typescript
+const client = new AgentKernel({
+  baseUrl: "http://localhost:18888", // default
+  apiKey: "sk-...",                 // optional
+  timeout: 30000,                   // default: 30s
+});
+```
+
+Or use environment variables:
+
+```bash
+export AGENTKERNEL_BASE_URL=http://localhost:18888
+export AGENTKERNEL_API_KEY=sk-...
+```
+
+## API
+
+### `client.health()`
+
+Health check. Returns `"ok"`.
+
+### `client.run(command, options?)`
+
+Run a command in a temporary sandbox.
+
+```typescript
+await client.run(["echo", "hello"]);
+await client.run(["python3", "-c", "print(1)"], {
+  image: "python:3.12-alpine",
+  profile: "restrictive",
+  fast: false,
+});
+```
+
+### `client.runStream(command, options?)`
+
+Run a command with SSE streaming output. Returns an `AsyncGenerator<StreamEvent>`.
+
+### `client.listSandboxes()`
+
+List all sandboxes.
+
+### `client.createSandbox(name, options?)`
+
+Create a new sandbox.
+
+### `client.getSandbox(name)`
+
+Get sandbox info.
+
+### `client.removeSandbox(name)`
+
+Remove a sandbox.
+
+### `client.execInSandbox(name, command)`
+
+Run a command in an existing sandbox.
+
+### `client.sandbox(name, options?)`
+
+Create a sandbox session with automatic cleanup. Returns a `SandboxSession` that implements `AsyncDisposable`.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,384 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AgentKernel: () => AgentKernel,
+  AgentKernelError: () => AgentKernelError,
+  AuthError: () => AuthError,
+  NetworkError: () => NetworkError,
+  NotFoundError: () => NotFoundError,
+  SandboxSession: () => SandboxSession,
+  ServerError: () => ServerError,
+  StreamError: () => StreamError,
+  ValidationError: () => ValidationError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/config.ts
+var DEFAULT_BASE_URL = "http://localhost:18888";
+var DEFAULT_TIMEOUT = 3e4;
+function resolveConfig(opts) {
+  const baseUrl = opts?.baseUrl ?? process.env.AGENTKERNEL_BASE_URL ?? DEFAULT_BASE_URL;
+  const apiKey = opts?.apiKey ?? process.env.AGENTKERNEL_API_KEY ?? void 0;
+  const timeout = opts?.timeout ?? DEFAULT_TIMEOUT;
+  return {
+    baseUrl: baseUrl.replace(/\/+$/, ""),
+    apiKey,
+    timeout
+  };
+}
+
+// src/errors.ts
+var AgentKernelError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "AgentKernelError";
+  }
+};
+var AuthError = class extends AgentKernelError {
+  status = 401;
+  constructor(message = "Unauthorized") {
+    super(message);
+    this.name = "AuthError";
+  }
+};
+var NotFoundError = class extends AgentKernelError {
+  status = 404;
+  constructor(message = "Not found") {
+    super(message);
+    this.name = "NotFoundError";
+  }
+};
+var ValidationError = class extends AgentKernelError {
+  status = 400;
+  constructor(message = "Bad request") {
+    super(message);
+    this.name = "ValidationError";
+  }
+};
+var ServerError = class extends AgentKernelError {
+  status = 500;
+  constructor(message = "Internal server error") {
+    super(message);
+    this.name = "ServerError";
+  }
+};
+var NetworkError = class extends AgentKernelError {
+  constructor(message = "Network error") {
+    super(message);
+    this.name = "NetworkError";
+  }
+};
+var StreamError = class extends AgentKernelError {
+  constructor(message = "Stream error") {
+    super(message);
+    this.name = "StreamError";
+  }
+};
+function errorFromStatus(status, body) {
+  let message;
+  try {
+    const parsed = JSON.parse(body);
+    message = parsed.error ?? body;
+  } catch {
+    message = body;
+  }
+  switch (status) {
+    case 400:
+      return new ValidationError(message);
+    case 401:
+      return new AuthError(message);
+    case 404:
+      return new NotFoundError(message);
+    default:
+      return new ServerError(message);
+  }
+}
+
+// src/sandbox.ts
+var SandboxSession = class {
+  name;
+  _removed = false;
+  _execInSandbox;
+  _removeSandbox;
+  _getSandbox;
+  /** @internal */
+  constructor(name, execInSandbox, removeSandbox, getSandbox) {
+    this.name = name;
+    this._execInSandbox = execInSandbox;
+    this._removeSandbox = removeSandbox;
+    this._getSandbox = getSandbox;
+  }
+  /** Run a command in this sandbox. */
+  async run(command) {
+    return this._execInSandbox(this.name, command);
+  }
+  /** Get sandbox info. */
+  async info() {
+    return this._getSandbox(this.name);
+  }
+  /** Remove the sandbox. Idempotent. */
+  async remove() {
+    if (this._removed) return;
+    this._removed = true;
+    await this._removeSandbox(this.name);
+  }
+  /** Auto-cleanup for `await using`. */
+  async [Symbol.asyncDispose]() {
+    await this.remove();
+  }
+};
+
+// src/sse.ts
+var import_eventsource_parser = require("eventsource-parser");
+var KNOWN_EVENTS = /* @__PURE__ */ new Set(["started", "progress", "output", "done", "error"]);
+function pushEvent(state, event) {
+  state.events.push(event);
+  if (state.resolve) {
+    const cb = state.resolve;
+    state.resolve = null;
+    cb();
+  }
+}
+async function* parseSSE(body) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  const state = { events: [], resolve: null, done: false };
+  const parser = (0, import_eventsource_parser.createParser)({
+    onEvent(event) {
+      const type = event.event ?? "message";
+      if (!KNOWN_EVENTS.has(type)) return;
+      let data;
+      try {
+        data = JSON.parse(event.data);
+      } catch {
+        data = { raw: event.data };
+      }
+      pushEvent(state, { type, data });
+    }
+  });
+  const pump = (async () => {
+    try {
+      for (; ; ) {
+        const result = await reader.read();
+        if (result.done) break;
+        parser.feed(decoder.decode(result.value, { stream: true }));
+      }
+    } catch (err) {
+      pushEvent(state, {
+        type: "error",
+        data: { message: err instanceof Error ? err.message : String(err) }
+      });
+    } finally {
+      state.done = true;
+      if (state.resolve) {
+        const cb = state.resolve;
+        state.resolve = null;
+        cb();
+      }
+    }
+  })();
+  try {
+    for (; ; ) {
+      while (state.events.length > 0) {
+        const event = state.events.shift();
+        yield event;
+        if (event.type === "done" || event.type === "error") return;
+      }
+      if (state.done) return;
+      await new Promise((r) => {
+        state.resolve = r;
+      });
+    }
+  } finally {
+    reader.cancel().catch(() => {
+    });
+    await pump.catch(() => {
+    });
+  }
+}
+
+// src/client.ts
+var SDK_VERSION = "0.1.0";
+var AgentKernel = class {
+  baseUrl;
+  apiKey;
+  timeout;
+  constructor(opts) {
+    const config = resolveConfig(opts);
+    this.baseUrl = config.baseUrl;
+    this.apiKey = config.apiKey;
+    this.timeout = config.timeout;
+  }
+  // -- Core API methods --
+  /** Health check. Returns "ok" if the server is running. */
+  async health() {
+    const res = await this.request("GET", "/health");
+    return res;
+  }
+  /** Run a command in a temporary sandbox. */
+  async run(command, opts) {
+    return this.request("POST", "/run", {
+      command,
+      image: opts?.image,
+      profile: opts?.profile,
+      fast: opts?.fast ?? true
+    });
+  }
+  /**
+   * Run a command with SSE streaming output.
+   *
+   * @example
+   * ```ts
+   * for await (const event of client.runStream(["python3", "script.py"])) {
+   *   if (event.type === "output") process.stdout.write(String(event.data.data));
+   * }
+   * ```
+   */
+  async *runStream(command, opts) {
+    const body = JSON.stringify({
+      command,
+      image: opts?.image,
+      profile: opts?.profile,
+      fast: opts?.fast ?? true
+    });
+    const response = await this.fetch("/run/stream", {
+      method: "POST",
+      headers: this.headers("application/json"),
+      body
+    });
+    if (!response.ok) {
+      const text = await response.text();
+      throw errorFromStatus(response.status, text);
+    }
+    if (!response.body) {
+      throw new AgentKernelError("No response body for SSE stream");
+    }
+    yield* parseSSE(response.body);
+  }
+  /** List all sandboxes. */
+  async listSandboxes() {
+    return this.request("GET", "/sandboxes");
+  }
+  /** Create a new sandbox. */
+  async createSandbox(name, opts) {
+    return this.request("POST", "/sandboxes", {
+      name,
+      image: opts?.image
+    });
+  }
+  /** Get info about a sandbox. */
+  async getSandbox(name) {
+    return this.request("GET", `/sandboxes/${encodeURIComponent(name)}`);
+  }
+  /** Remove a sandbox. */
+  async removeSandbox(name) {
+    await this.request("DELETE", `/sandboxes/${encodeURIComponent(name)}`);
+  }
+  /** Run a command in an existing sandbox. */
+  async execInSandbox(name, command) {
+    return this.request(
+      "POST",
+      `/sandboxes/${encodeURIComponent(name)}/exec`,
+      { command }
+    );
+  }
+  /**
+   * Create a sandbox session with automatic cleanup.
+   *
+   * The returned SandboxSession implements AsyncDisposable,
+   * so it works with `await using` (TS 5.2+):
+   *
+   * @example
+   * ```ts
+   * await using sb = await client.sandbox("test", { image: "python:3.12-alpine" });
+   * await sb.run(["pip", "install", "numpy"]);
+   * // sandbox auto-removed when scope exits
+   * ```
+   */
+  async sandbox(name, opts) {
+    await this.createSandbox(name, opts);
+    return new SandboxSession(
+      name,
+      (n, cmd) => this.execInSandbox(n, cmd),
+      (n) => this.removeSandbox(n),
+      (n) => this.getSandbox(n)
+    );
+  }
+  // -- Internal helpers --
+  headers(contentType) {
+    const h = {
+      "User-Agent": `agentkernel-nodejs-sdk/${SDK_VERSION}`
+    };
+    if (contentType) h["Content-Type"] = contentType;
+    if (this.apiKey) h["Authorization"] = `Bearer ${this.apiKey}`;
+    return h;
+  }
+  async fetch(path, init) {
+    const url = `${this.baseUrl}${path}`;
+    try {
+      return await fetch(url, {
+        ...init,
+        signal: AbortSignal.timeout(this.timeout)
+      });
+    } catch (err) {
+      if (err instanceof DOMException && err.name === "TimeoutError") {
+        throw new NetworkError(`Request timed out after ${this.timeout}ms`);
+      }
+      if (err instanceof TypeError) {
+        throw new NetworkError(`Failed to connect to ${this.baseUrl}: ${err.message}`);
+      }
+      throw new NetworkError(
+        err instanceof Error ? err.message : String(err)
+      );
+    }
+  }
+  async request(method, path, body) {
+    const init = {
+      method,
+      headers: this.headers(body ? "application/json" : void 0)
+    };
+    if (body) init.body = JSON.stringify(body);
+    const response = await this.fetch(path, init);
+    const text = await response.text();
+    if (!response.ok) {
+      throw errorFromStatus(response.status, text);
+    }
+    const parsed = JSON.parse(text);
+    if (!parsed.success) {
+      throw new AgentKernelError(parsed.error ?? "Unknown error");
+    }
+    return parsed.data;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AgentKernel,
+  AgentKernelError,
+  AuthError,
+  NetworkError,
+  NotFoundError,
+  SandboxSession,
+  ServerError,
+  StreamError,
+  ValidationError
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/config.ts","../src/errors.ts","../src/sandbox.ts","../src/sse.ts","../src/client.ts"],"sourcesContent":["export { AgentKernel } from \"./client.js\";\nexport { SandboxSession } from \"./sandbox.js\";\nexport {\n  AgentKernelError,\n  AuthError,\n  NotFoundError,\n  ValidationError,\n  ServerError,\n  NetworkError,\n  StreamError,\n} from \"./errors.js\";\nexport type {\n  AgentKernelOptions,\n  RunOptions,\n  CreateSandboxOptions,\n  RunOutput,\n  SandboxInfo,\n  StreamEvent,\n  StreamEventType,\n  SecurityProfile,\n  SandboxStatus,\n  ApiResponse,\n} from \"./types.js\";\n","import type { AgentKernelOptions } from \"./types.js\";\n\nconst DEFAULT_BASE_URL = \"http://localhost:18888\";\nconst DEFAULT_TIMEOUT = 30_000;\n\n/** Resolve configuration from constructor args, env vars, and defaults. */\nexport function resolveConfig(opts?: AgentKernelOptions) {\n  const baseUrl =\n    opts?.baseUrl ??\n    process.env.AGENTKERNEL_BASE_URL ??\n    DEFAULT_BASE_URL;\n\n  const apiKey =\n    opts?.apiKey ??\n    process.env.AGENTKERNEL_API_KEY ??\n    undefined;\n\n  const timeout = opts?.timeout ?? DEFAULT_TIMEOUT;\n\n  return {\n    baseUrl: baseUrl.replace(/\\/+$/, \"\"),\n    apiKey,\n    timeout,\n  };\n}\n","/** Base error for all agentkernel SDK errors. */\nexport class AgentKernelError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"AgentKernelError\";\n  }\n}\n\n/** 401 Unauthorized. */\nexport class AuthError extends AgentKernelError {\n  readonly status = 401;\n  constructor(message = \"Unauthorized\") {\n    super(message);\n    this.name = \"AuthError\";\n  }\n}\n\n/** 404 Not Found. */\nexport class NotFoundError extends AgentKernelError {\n  readonly status = 404;\n  constructor(message = \"Not found\") {\n    super(message);\n    this.name = \"NotFoundError\";\n  }\n}\n\n/** 400 Bad Request. */\nexport class ValidationError extends AgentKernelError {\n  readonly status = 400;\n  constructor(message = \"Bad request\") {\n    super(message);\n    this.name = \"ValidationError\";\n  }\n}\n\n/** 500 Internal Server Error. */\nexport class ServerError extends AgentKernelError {\n  readonly status = 500;\n  constructor(message = \"Internal server error\") {\n    super(message);\n    this.name = \"ServerError\";\n  }\n}\n\n/** Network / connection error. */\nexport class NetworkError extends AgentKernelError {\n  constructor(message = \"Network error\") {\n    super(message);\n    this.name = \"NetworkError\";\n  }\n}\n\n/** SSE streaming error. */\nexport class StreamError extends AgentKernelError {\n  constructor(message = \"Stream error\") {\n    super(message);\n    this.name = \"StreamError\";\n  }\n}\n\n/** Map an HTTP status code + body to the appropriate error. */\nexport function errorFromStatus(status: number, body: string): AgentKernelError {\n  let message: string;\n  try {\n    const parsed = JSON.parse(body);\n    message = parsed.error ?? body;\n  } catch {\n    message = body;\n  }\n\n  switch (status) {\n    case 400:\n      return new ValidationError(message);\n    case 401:\n      return new AuthError(message);\n    case 404:\n      return new NotFoundError(message);\n    default:\n      return new ServerError(message);\n  }\n}\n","import type { RunOutput, SandboxInfo } from \"./types.js\";\n\ntype ExecFn = (name: string, command: string[]) => Promise<RunOutput>;\ntype RemoveFn = (name: string) => Promise<void>;\ntype GetFn = (name: string) => Promise<SandboxInfo>;\n\n/**\n * A sandbox session that auto-removes the sandbox on dispose.\n *\n * Supports both explicit cleanup via remove() and automatic cleanup via\n * Symbol.asyncDispose (TS 5.2+ `await using`).\n *\n * @example\n * ```ts\n * await using sb = await client.sandbox(\"test\");\n * await sb.exec([\"echo\", \"hello\"]);\n * // sandbox auto-removed when scope exits\n * ```\n */\nexport class SandboxSession implements AsyncDisposable {\n  readonly name: string;\n  private _removed = false;\n  private readonly _execInSandbox: ExecFn;\n  private readonly _removeSandbox: RemoveFn;\n  private readonly _getSandbox: GetFn;\n\n  /** @internal */\n  constructor(\n    name: string,\n    execInSandbox: ExecFn,\n    removeSandbox: RemoveFn,\n    getSandbox: GetFn,\n  ) {\n    this.name = name;\n    this._execInSandbox = execInSandbox;\n    this._removeSandbox = removeSandbox;\n    this._getSandbox = getSandbox;\n  }\n\n  /** Run a command in this sandbox. */\n  async run(command: string[]): Promise<RunOutput> {\n    return this._execInSandbox(this.name, command);\n  }\n\n  /** Get sandbox info. */\n  async info(): Promise<SandboxInfo> {\n    return this._getSandbox(this.name);\n  }\n\n  /** Remove the sandbox. Idempotent. */\n  async remove(): Promise<void> {\n    if (this._removed) return;\n    this._removed = true;\n    await this._removeSandbox(this.name);\n  }\n\n  /** Auto-cleanup for `await using`. */\n  async [Symbol.asyncDispose](): Promise<void> {\n    await this.remove();\n  }\n}\n","import { createParser, type EventSourceMessage } from \"eventsource-parser\";\nimport type { StreamEvent, StreamEventType } from \"./types.js\";\n\nconst KNOWN_EVENTS = new Set<string>([\"started\", \"progress\", \"output\", \"done\", \"error\"]);\n\n/** Shared mutable state between the pump and the generator. */\ninterface PumpState {\n  events: StreamEvent[];\n  resolve: (() => void) | null;\n  done: boolean;\n}\n\nfunction pushEvent(state: PumpState, event: StreamEvent): void {\n  state.events.push(event);\n  if (state.resolve) {\n    const cb = state.resolve;\n    state.resolve = null;\n    cb();\n  }\n}\n\n/**\n * Parse an SSE response body into an async generator of StreamEvents.\n *\n * Consumes a ReadableStream<Uint8Array> from fetch() and yields typed events\n * until the stream closes or a \"done\"/\"error\" event is received.\n */\nexport async function* parseSSE(\n  body: ReadableStream<Uint8Array>,\n): AsyncGenerator<StreamEvent> {\n  const reader = body.getReader();\n  const decoder = new TextDecoder();\n  const state: PumpState = { events: [], resolve: null, done: false };\n\n  const parser = createParser({\n    onEvent(event: EventSourceMessage) {\n      const type = event.event ?? \"message\";\n      if (!KNOWN_EVENTS.has(type)) return;\n\n      let data: Record<string, unknown>;\n      try {\n        data = JSON.parse(event.data);\n      } catch {\n        data = { raw: event.data };\n      }\n\n      pushEvent(state, { type: type as StreamEventType, data });\n    },\n  });\n\n  // Read the stream in the background\n  const pump = (async () => {\n    try {\n      for (;;) {\n        const result = await reader.read();\n        if (result.done) break;\n        parser.feed(decoder.decode(result.value, { stream: true }));\n      }\n    } catch (err) {\n      pushEvent(state, {\n        type: \"error\",\n        data: { message: err instanceof Error ? err.message : String(err) },\n      });\n    } finally {\n      state.done = true;\n      if (state.resolve) {\n        const cb = state.resolve;\n        state.resolve = null;\n        cb();\n      }\n    }\n  })();\n\n  try {\n    for (;;) {\n      // Yield all buffered events\n      while (state.events.length > 0) {\n        const event = state.events.shift()!;\n        yield event;\n        if (event.type === \"done\" || event.type === \"error\") return;\n      }\n\n      // If the stream is done and no more events, exit\n      if (state.done) return;\n\n      // Wait for the next event\n      await new Promise<void>((r) => {\n        state.resolve = r;\n      });\n    }\n  } finally {\n    reader.cancel().catch(() => {});\n    await pump.catch(() => {});\n  }\n}\n","import { resolveConfig } from \"./config.js\";\nimport {\n  AgentKernelError,\n  NetworkError,\n  errorFromStatus,\n} from \"./errors.js\";\nimport { SandboxSession } from \"./sandbox.js\";\nimport { parseSSE } from \"./sse.js\";\nimport type {\n  AgentKernelOptions,\n  ApiResponse,\n  CreateSandboxOptions,\n  RunOptions,\n  RunOutput,\n  SandboxInfo,\n  StreamEvent,\n} from \"./types.js\";\n\nconst SDK_VERSION = \"0.1.0\";\n\n/**\n * Client for the agentkernel HTTP API.\n *\n * @example\n * ```ts\n * const client = new AgentKernel();\n * const result = await client.run([\"echo\", \"hello\"]);\n * console.log(result.output); // \"hello\\n\"\n * ```\n */\nexport class AgentKernel {\n  private readonly baseUrl: string;\n  private readonly apiKey: string | undefined;\n  private readonly timeout: number;\n\n  constructor(opts?: AgentKernelOptions) {\n    const config = resolveConfig(opts);\n    this.baseUrl = config.baseUrl;\n    this.apiKey = config.apiKey;\n    this.timeout = config.timeout;\n  }\n\n  // -- Core API methods --\n\n  /** Health check. Returns \"ok\" if the server is running. */\n  async health(): Promise<string> {\n    const res = await this.request<string>(\"GET\", \"/health\");\n    return res;\n  }\n\n  /** Run a command in a temporary sandbox. */\n  async run(command: string[], opts?: RunOptions): Promise<RunOutput> {\n    return this.request<RunOutput>(\"POST\", \"/run\", {\n      command,\n      image: opts?.image,\n      profile: opts?.profile,\n      fast: opts?.fast ?? true,\n    });\n  }\n\n  /**\n   * Run a command with SSE streaming output.\n   *\n   * @example\n   * ```ts\n   * for await (const event of client.runStream([\"python3\", \"script.py\"])) {\n   *   if (event.type === \"output\") process.stdout.write(String(event.data.data));\n   * }\n   * ```\n   */\n  async *runStream(\n    command: string[],\n    opts?: RunOptions,\n  ): AsyncGenerator<StreamEvent> {\n    const body = JSON.stringify({\n      command,\n      image: opts?.image,\n      profile: opts?.profile,\n      fast: opts?.fast ?? true,\n    });\n\n    const response = await this.fetch(\"/run/stream\", {\n      method: \"POST\",\n      headers: this.headers(\"application/json\"),\n      body,\n    });\n\n    if (!response.ok) {\n      const text = await response.text();\n      throw errorFromStatus(response.status, text);\n    }\n\n    if (!response.body) {\n      throw new AgentKernelError(\"No response body for SSE stream\");\n    }\n\n    yield* parseSSE(response.body);\n  }\n\n  /** List all sandboxes. */\n  async listSandboxes(): Promise<SandboxInfo[]> {\n    return this.request<SandboxInfo[]>(\"GET\", \"/sandboxes\");\n  }\n\n  /** Create a new sandbox. */\n  async createSandbox(\n    name: string,\n    opts?: CreateSandboxOptions,\n  ): Promise<SandboxInfo> {\n    return this.request<SandboxInfo>(\"POST\", \"/sandboxes\", {\n      name,\n      image: opts?.image,\n    });\n  }\n\n  /** Get info about a sandbox. */\n  async getSandbox(name: string): Promise<SandboxInfo> {\n    return this.request<SandboxInfo>(\"GET\", `/sandboxes/${encodeURIComponent(name)}`);\n  }\n\n  /** Remove a sandbox. */\n  async removeSandbox(name: string): Promise<void> {\n    await this.request<string>(\"DELETE\", `/sandboxes/${encodeURIComponent(name)}`);\n  }\n\n  /** Run a command in an existing sandbox. */\n  async execInSandbox(name: string, command: string[]): Promise<RunOutput> {\n    return this.request<RunOutput>(\n      \"POST\",\n      `/sandboxes/${encodeURIComponent(name)}/exec`,\n      { command },\n    );\n  }\n\n  /**\n   * Create a sandbox session with automatic cleanup.\n   *\n   * The returned SandboxSession implements AsyncDisposable,\n   * so it works with `await using` (TS 5.2+):\n   *\n   * @example\n   * ```ts\n   * await using sb = await client.sandbox(\"test\", { image: \"python:3.12-alpine\" });\n   * await sb.run([\"pip\", \"install\", \"numpy\"]);\n   * // sandbox auto-removed when scope exits\n   * ```\n   */\n  async sandbox(\n    name: string,\n    opts?: CreateSandboxOptions,\n  ): Promise<SandboxSession> {\n    await this.createSandbox(name, opts);\n    return new SandboxSession(\n      name,\n      (n, cmd) => this.execInSandbox(n, cmd),\n      (n) => this.removeSandbox(n),\n      (n) => this.getSandbox(n),\n    );\n  }\n\n  // -- Internal helpers --\n\n  private headers(contentType?: string): Record<string, string> {\n    const h: Record<string, string> = {\n      \"User-Agent\": `agentkernel-nodejs-sdk/${SDK_VERSION}`,\n    };\n    if (contentType) h[\"Content-Type\"] = contentType;\n    if (this.apiKey) h[\"Authorization\"] = `Bearer ${this.apiKey}`;\n    return h;\n  }\n\n  private async fetch(path: string, init: RequestInit): Promise<Response> {\n    const url = `${this.baseUrl}${path}`;\n    try {\n      return await fetch(url, {\n        ...init,\n        signal: AbortSignal.timeout(this.timeout),\n      });\n    } catch (err) {\n      if (err instanceof DOMException && err.name === \"TimeoutError\") {\n        throw new NetworkError(`Request timed out after ${this.timeout}ms`);\n      }\n      if (err instanceof TypeError) {\n        throw new NetworkError(`Failed to connect to ${this.baseUrl}: ${err.message}`);\n      }\n      throw new NetworkError(\n        err instanceof Error ? err.message : String(err),\n      );\n    }\n  }\n\n  private async request<T>(\n    method: string,\n    path: string,\n    body?: unknown,\n  ): Promise<T> {\n    const init: RequestInit = {\n      method,\n      headers: this.headers(body ? \"application/json\" : undefined),\n    };\n    if (body) init.body = JSON.stringify(body);\n\n    const response = await this.fetch(path, init);\n\n    const text = await response.text();\n    if (!response.ok) {\n      throw errorFromStatus(response.status, text);\n    }\n\n    const parsed: ApiResponse<T> = JSON.parse(text);\n    if (!parsed.success) {\n      throw new AgentKernelError(parsed.error ?? \"Unknown error\");\n    }\n    return parsed.data as T;\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,178 @@
+/** Security profile for sandbox execution. */
+type SecurityProfile = "permissive" | "moderate" | "restrictive";
+/** Sandbox status. */
+type SandboxStatus = "running" | "stopped";
+/** SSE event types emitted by /run/stream. */
+type StreamEventType = "started" | "progress" | "output" | "done" | "error";
+/** Configuration options for the AgentKernel client. */
+interface AgentKernelOptions {
+    /** Base URL of the agentkernel HTTP API. Default: AGENTKERNEL_BASE_URL or http://localhost:18888 */
+    baseUrl?: string;
+    /** API key for Bearer authentication. Default: AGENTKERNEL_API_KEY env var */
+    apiKey?: string;
+    /** Request timeout in milliseconds. Default: 30000 */
+    timeout?: number;
+}
+/** Options for the run command. */
+interface RunOptions {
+    /** Docker image to use (auto-detected if not specified). */
+    image?: string;
+    /** Security profile. Default: moderate */
+    profile?: SecurityProfile;
+    /** Use container pool for faster execution. Default: true */
+    fast?: boolean;
+}
+/** Options for creating a sandbox. */
+interface CreateSandboxOptions {
+    /** Docker image to use. Default: alpine:3.20 */
+    image?: string;
+}
+/** Output from a command execution. */
+interface RunOutput {
+    output: string;
+}
+/** Information about a sandbox. */
+interface SandboxInfo {
+    name: string;
+    status: SandboxStatus;
+    backend: string;
+}
+/** SSE stream event. */
+interface StreamEvent {
+    type: StreamEventType;
+    data: Record<string, unknown>;
+}
+/** API response wrapper. */
+interface ApiResponse<T> {
+    success: boolean;
+    data?: T;
+    error?: string;
+}
+
+type ExecFn = (name: string, command: string[]) => Promise<RunOutput>;
+type RemoveFn = (name: string) => Promise<void>;
+type GetFn = (name: string) => Promise<SandboxInfo>;
+/**
+ * A sandbox session that auto-removes the sandbox on dispose.
+ *
+ * Supports both explicit cleanup via remove() and automatic cleanup via
+ * Symbol.asyncDispose (TS 5.2+ `await using`).
+ *
+ * @example
+ * ```ts
+ * await using sb = await client.sandbox("test");
+ * await sb.exec(["echo", "hello"]);
+ * // sandbox auto-removed when scope exits
+ * ```
+ */
+declare class SandboxSession implements AsyncDisposable {
+    readonly name: string;
+    private _removed;
+    private readonly _execInSandbox;
+    private readonly _removeSandbox;
+    private readonly _getSandbox;
+    /** @internal */
+    constructor(name: string, execInSandbox: ExecFn, removeSandbox: RemoveFn, getSandbox: GetFn);
+    /** Run a command in this sandbox. */
+    run(command: string[]): Promise<RunOutput>;
+    /** Get sandbox info. */
+    info(): Promise<SandboxInfo>;
+    /** Remove the sandbox. Idempotent. */
+    remove(): Promise<void>;
+    /** Auto-cleanup for `await using`. */
+    [Symbol.asyncDispose](): Promise<void>;
+}
+
+/**
+ * Client for the agentkernel HTTP API.
+ *
+ * @example
+ * ```ts
+ * const client = new AgentKernel();
+ * const result = await client.run(["echo", "hello"]);
+ * console.log(result.output); // "hello\n"
+ * ```
+ */
+declare class AgentKernel {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly timeout;
+    constructor(opts?: AgentKernelOptions);
+    /** Health check. Returns "ok" if the server is running. */
+    health(): Promise<string>;
+    /** Run a command in a temporary sandbox. */
+    run(command: string[], opts?: RunOptions): Promise<RunOutput>;
+    /**
+     * Run a command with SSE streaming output.
+     *
+     * @example
+     * ```ts
+     * for await (const event of client.runStream(["python3", "script.py"])) {
+     *   if (event.type === "output") process.stdout.write(String(event.data.data));
+     * }
+     * ```
+     */
+    runStream(command: string[], opts?: RunOptions): AsyncGenerator<StreamEvent>;
+    /** List all sandboxes. */
+    listSandboxes(): Promise<SandboxInfo[]>;
+    /** Create a new sandbox. */
+    createSandbox(name: string, opts?: CreateSandboxOptions): Promise<SandboxInfo>;
+    /** Get info about a sandbox. */
+    getSandbox(name: string): Promise<SandboxInfo>;
+    /** Remove a sandbox. */
+    removeSandbox(name: string): Promise<void>;
+    /** Run a command in an existing sandbox. */
+    execInSandbox(name: string, command: string[]): Promise<RunOutput>;
+    /**
+     * Create a sandbox session with automatic cleanup.
+     *
+     * The returned SandboxSession implements AsyncDisposable,
+     * so it works with `await using` (TS 5.2+):
+     *
+     * @example
+     * ```ts
+     * await using sb = await client.sandbox("test", { image: "python:3.12-alpine" });
+     * await sb.run(["pip", "install", "numpy"]);
+     * // sandbox auto-removed when scope exits
+     * ```
+     */
+    sandbox(name: string, opts?: CreateSandboxOptions): Promise<SandboxSession>;
+    private headers;
+    private fetch;
+    private request;
+}
+
+/** Base error for all agentkernel SDK errors. */
+declare class AgentKernelError extends Error {
+    constructor(message: string);
+}
+/** 401 Unauthorized. */
+declare class AuthError extends AgentKernelError {
+    readonly status = 401;
+    constructor(message?: string);
+}
+/** 404 Not Found. */
+declare class NotFoundError extends AgentKernelError {
+    readonly status = 404;
+    constructor(message?: string);
+}
+/** 400 Bad Request. */
+declare class ValidationError extends AgentKernelError {
+    readonly status = 400;
+    constructor(message?: string);
+}
+/** 500 Internal Server Error. */
+declare class ServerError extends AgentKernelError {
+    readonly status = 500;
+    constructor(message?: string);
+}
+/** Network / connection error. */
+declare class NetworkError extends AgentKernelError {
+    constructor(message?: string);
+}
+/** SSE streaming error. */
+declare class StreamError extends AgentKernelError {
+    constructor(message?: string);
+}
+
+export { AgentKernel, AgentKernelError, type AgentKernelOptions, type ApiResponse, AuthError, type CreateSandboxOptions, NetworkError, NotFoundError, type RunOptions, type RunOutput, type SandboxInfo, SandboxSession, type SandboxStatus, type SecurityProfile, ServerError, StreamError, type StreamEvent, type StreamEventType, ValidationError };

package/dist/index.d.ts

@@ -0,0 +1,178 @@
+/** Security profile for sandbox execution. */
+type SecurityProfile = "permissive" | "moderate" | "restrictive";
+/** Sandbox status. */
+type SandboxStatus = "running" | "stopped";
+/** SSE event types emitted by /run/stream. */
+type StreamEventType = "started" | "progress" | "output" | "done" | "error";
+/** Configuration options for the AgentKernel client. */
+interface AgentKernelOptions {
+    /** Base URL of the agentkernel HTTP API. Default: AGENTKERNEL_BASE_URL or http://localhost:18888 */
+    baseUrl?: string;
+    /** API key for Bearer authentication. Default: AGENTKERNEL_API_KEY env var */
+    apiKey?: string;
+    /** Request timeout in milliseconds. Default: 30000 */
+    timeout?: number;
+}
+/** Options for the run command. */
+interface RunOptions {
+    /** Docker image to use (auto-detected if not specified). */
+    image?: string;
+    /** Security profile. Default: moderate */
+    profile?: SecurityProfile;
+    /** Use container pool for faster execution. Default: true */
+    fast?: boolean;
+}
+/** Options for creating a sandbox. */
+interface CreateSandboxOptions {
+    /** Docker image to use. Default: alpine:3.20 */
+    image?: string;
+}
+/** Output from a command execution. */
+interface RunOutput {
+    output: string;
+}
+/** Information about a sandbox. */
+interface SandboxInfo {
+    name: string;
+    status: SandboxStatus;
+    backend: string;
+}
+/** SSE stream event. */
+interface StreamEvent {
+    type: StreamEventType;
+    data: Record<string, unknown>;
+}
+/** API response wrapper. */
+interface ApiResponse<T> {
+    success: boolean;
+    data?: T;
+    error?: string;
+}
+
+type ExecFn = (name: string, command: string[]) => Promise<RunOutput>;
+type RemoveFn = (name: string) => Promise<void>;
+type GetFn = (name: string) => Promise<SandboxInfo>;
+/**
+ * A sandbox session that auto-removes the sandbox on dispose.
+ *
+ * Supports both explicit cleanup via remove() and automatic cleanup via
+ * Symbol.asyncDispose (TS 5.2+ `await using`).
+ *
+ * @example
+ * ```ts
+ * await using sb = await client.sandbox("test");
+ * await sb.exec(["echo", "hello"]);
+ * // sandbox auto-removed when scope exits
+ * ```
+ */
+declare class SandboxSession implements AsyncDisposable {
+    readonly name: string;
+    private _removed;
+    private readonly _execInSandbox;
+    private readonly _removeSandbox;
+    private readonly _getSandbox;
+    /** @internal */
+    constructor(name: string, execInSandbox: ExecFn, removeSandbox: RemoveFn, getSandbox: GetFn);
+    /** Run a command in this sandbox. */
+    run(command: string[]): Promise<RunOutput>;
+    /** Get sandbox info. */
+    info(): Promise<SandboxInfo>;
+    /** Remove the sandbox. Idempotent. */
+    remove(): Promise<void>;
+    /** Auto-cleanup for `await using`. */
+    [Symbol.asyncDispose](): Promise<void>;
+}
+
+/**
+ * Client for the agentkernel HTTP API.
+ *
+ * @example
+ * ```ts
+ * const client = new AgentKernel();
+ * const result = await client.run(["echo", "hello"]);
+ * console.log(result.output); // "hello\n"
+ * ```
+ */
+declare class AgentKernel {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly timeout;
+    constructor(opts?: AgentKernelOptions);
+    /** Health check. Returns "ok" if the server is running. */
+    health(): Promise<string>;
+    /** Run a command in a temporary sandbox. */
+    run(command: string[], opts?: RunOptions): Promise<RunOutput>;
+    /**
+     * Run a command with SSE streaming output.
+     *
+     * @example
+     * ```ts
+     * for await (const event of client.runStream(["python3", "script.py"])) {
+     *   if (event.type === "output") process.stdout.write(String(event.data.data));
+     * }
+     * ```
+     */
+    runStream(command: string[], opts?: RunOptions): AsyncGenerator<StreamEvent>;
+    /** List all sandboxes. */
+    listSandboxes(): Promise<SandboxInfo[]>;
+    /** Create a new sandbox. */
+    createSandbox(name: string, opts?: CreateSandboxOptions): Promise<SandboxInfo>;
+    /** Get info about a sandbox. */
+    getSandbox(name: string): Promise<SandboxInfo>;
+    /** Remove a sandbox. */
+    removeSandbox(name: string): Promise<void>;
+    /** Run a command in an existing sandbox. */
+    execInSandbox(name: string, command: string[]): Promise<RunOutput>;
+    /**
+     * Create a sandbox session with automatic cleanup.
+     *
+     * The returned SandboxSession implements AsyncDisposable,
+     * so it works with `await using` (TS 5.2+):
+     *
+     * @example
+     * ```ts
+     * await using sb = await client.sandbox("test", { image: "python:3.12-alpine" });
+     * await sb.run(["pip", "install", "numpy"]);
+     * // sandbox auto-removed when scope exits
+     * ```
+     */
+    sandbox(name: string, opts?: CreateSandboxOptions): Promise<SandboxSession>;
+    private headers;
+    private fetch;
+    private request;
+}
+
+/** Base error for all agentkernel SDK errors. */
+declare class AgentKernelError extends Error {
+    constructor(message: string);
+}
+/** 401 Unauthorized. */
+declare class AuthError extends AgentKernelError {
+    readonly status = 401;
+    constructor(message?: string);
+}
+/** 404 Not Found. */
+declare class NotFoundError extends AgentKernelError {
+    readonly status = 404;
+    constructor(message?: string);
+}
+/** 400 Bad Request. */
+declare class ValidationError extends AgentKernelError {
+    readonly status = 400;
+    constructor(message?: string);
+}
+/** 500 Internal Server Error. */
+declare class ServerError extends AgentKernelError {
+    readonly status = 500;
+    constructor(message?: string);
+}
+/** Network / connection error. */
+declare class NetworkError extends AgentKernelError {
+    constructor(message?: string);
+}
+/** SSE streaming error. */
+declare class StreamError extends AgentKernelError {
+    constructor(message?: string);
+}
+
+export { AgentKernel, AgentKernelError, type AgentKernelOptions, type ApiResponse, AuthError, type CreateSandboxOptions, NetworkError, NotFoundError, type RunOptions, type RunOutput, type SandboxInfo, SandboxSession, type SandboxStatus, type SecurityProfile, ServerError, StreamError, type StreamEvent, type StreamEventType, ValidationError };

package/dist/index.js

@@ -0,0 +1,349 @@
+// src/config.ts
+var DEFAULT_BASE_URL = "http://localhost:18888";
+var DEFAULT_TIMEOUT = 3e4;
+function resolveConfig(opts) {
+  const baseUrl = opts?.baseUrl ?? process.env.AGENTKERNEL_BASE_URL ?? DEFAULT_BASE_URL;
+  const apiKey = opts?.apiKey ?? process.env.AGENTKERNEL_API_KEY ?? void 0;
+  const timeout = opts?.timeout ?? DEFAULT_TIMEOUT;
+  return {
+    baseUrl: baseUrl.replace(/\/+$/, ""),
+    apiKey,
+    timeout
+  };
+}
+
+// src/errors.ts
+var AgentKernelError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "AgentKernelError";
+  }
+};
+var AuthError = class extends AgentKernelError {
+  status = 401;
+  constructor(message = "Unauthorized") {
+    super(message);
+    this.name = "AuthError";
+  }
+};
+var NotFoundError = class extends AgentKernelError {
+  status = 404;
+  constructor(message = "Not found") {
+    super(message);
+    this.name = "NotFoundError";
+  }
+};
+var ValidationError = class extends AgentKernelError {
+  status = 400;
+  constructor(message = "Bad request") {
+    super(message);
+    this.name = "ValidationError";
+  }
+};
+var ServerError = class extends AgentKernelError {
+  status = 500;
+  constructor(message = "Internal server error") {
+    super(message);
+    this.name = "ServerError";
+  }
+};
+var NetworkError = class extends AgentKernelError {
+  constructor(message = "Network error") {
+    super(message);
+    this.name = "NetworkError";
+  }
+};
+var StreamError = class extends AgentKernelError {
+  constructor(message = "Stream error") {
+    super(message);
+    this.name = "StreamError";
+  }
+};
+function errorFromStatus(status, body) {
+  let message;
+  try {
+    const parsed = JSON.parse(body);
+    message = parsed.error ?? body;
+  } catch {
+    message = body;
+  }
+  switch (status) {
+    case 400:
+      return new ValidationError(message);
+    case 401:
+      return new AuthError(message);
+    case 404:
+      return new NotFoundError(message);
+    default:
+      return new ServerError(message);
+  }
+}
+
+// src/sandbox.ts
+var SandboxSession = class {
+  name;
+  _removed = false;
+  _execInSandbox;
+  _removeSandbox;
+  _getSandbox;
+  /** @internal */
+  constructor(name, execInSandbox, removeSandbox, getSandbox) {
+    this.name = name;
+    this._execInSandbox = execInSandbox;
+    this._removeSandbox = removeSandbox;
+    this._getSandbox = getSandbox;
+  }
+  /** Run a command in this sandbox. */
+  async run(command) {
+    return this._execInSandbox(this.name, command);
+  }
+  /** Get sandbox info. */
+  async info() {
+    return this._getSandbox(this.name);
+  }
+  /** Remove the sandbox. Idempotent. */
+  async remove() {
+    if (this._removed) return;
+    this._removed = true;
+    await this._removeSandbox(this.name);
+  }
+  /** Auto-cleanup for `await using`. */
+  async [Symbol.asyncDispose]() {
+    await this.remove();
+  }
+};
+
+// src/sse.ts
+import { createParser } from "eventsource-parser";
+var KNOWN_EVENTS = /* @__PURE__ */ new Set(["started", "progress", "output", "done", "error"]);
+function pushEvent(state, event) {
+  state.events.push(event);
+  if (state.resolve) {
+    const cb = state.resolve;
+    state.resolve = null;
+    cb();
+  }
+}
+async function* parseSSE(body) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  const state = { events: [], resolve: null, done: false };
+  const parser = createParser({
+    onEvent(event) {
+      const type = event.event ?? "message";
+      if (!KNOWN_EVENTS.has(type)) return;
+      let data;
+      try {
+        data = JSON.parse(event.data);
+      } catch {
+        data = { raw: event.data };
+      }
+      pushEvent(state, { type, data });
+    }
+  });
+  const pump = (async () => {
+    try {
+      for (; ; ) {
+        const result = await reader.read();
+        if (result.done) break;
+        parser.feed(decoder.decode(result.value, { stream: true }));
+      }
+    } catch (err) {
+      pushEvent(state, {
+        type: "error",
+        data: { message: err instanceof Error ? err.message : String(err) }
+      });
+    } finally {
+      state.done = true;
+      if (state.resolve) {
+        const cb = state.resolve;
+        state.resolve = null;
+        cb();
+      }
+    }
+  })();
+  try {
+    for (; ; ) {
+      while (state.events.length > 0) {
+        const event = state.events.shift();
+        yield event;
+        if (event.type === "done" || event.type === "error") return;
+      }
+      if (state.done) return;
+      await new Promise((r) => {
+        state.resolve = r;
+      });
+    }
+  } finally {
+    reader.cancel().catch(() => {
+    });
+    await pump.catch(() => {
+    });
+  }
+}
+
+// src/client.ts
+var SDK_VERSION = "0.1.0";
+var AgentKernel = class {
+  baseUrl;
+  apiKey;
+  timeout;
+  constructor(opts) {
+    const config = resolveConfig(opts);
+    this.baseUrl = config.baseUrl;
+    this.apiKey = config.apiKey;
+    this.timeout = config.timeout;
+  }
+  // -- Core API methods --
+  /** Health check. Returns "ok" if the server is running. */
+  async health() {
+    const res = await this.request("GET", "/health");
+    return res;
+  }
+  /** Run a command in a temporary sandbox. */
+  async run(command, opts) {
+    return this.request("POST", "/run", {
+      command,
+      image: opts?.image,
+      profile: opts?.profile,
+      fast: opts?.fast ?? true
+    });
+  }
+  /**
+   * Run a command with SSE streaming output.
+   *
+   * @example
+   * ```ts
+   * for await (const event of client.runStream(["python3", "script.py"])) {
+   *   if (event.type === "output") process.stdout.write(String(event.data.data));
+   * }
+   * ```
+   */
+  async *runStream(command, opts) {
+    const body = JSON.stringify({
+      command,
+      image: opts?.image,
+      profile: opts?.profile,
+      fast: opts?.fast ?? true
+    });
+    const response = await this.fetch("/run/stream", {
+      method: "POST",
+      headers: this.headers("application/json"),
+      body
+    });
+    if (!response.ok) {
+      const text = await response.text();
+      throw errorFromStatus(response.status, text);
+    }
+    if (!response.body) {
+      throw new AgentKernelError("No response body for SSE stream");
+    }
+    yield* parseSSE(response.body);
+  }
+  /** List all sandboxes. */
+  async listSandboxes() {
+    return this.request("GET", "/sandboxes");
+  }
+  /** Create a new sandbox. */
+  async createSandbox(name, opts) {
+    return this.request("POST", "/sandboxes", {
+      name,
+      image: opts?.image
+    });
+  }
+  /** Get info about a sandbox. */
+  async getSandbox(name) {
+    return this.request("GET", `/sandboxes/${encodeURIComponent(name)}`);
+  }
+  /** Remove a sandbox. */
+  async removeSandbox(name) {
+    await this.request("DELETE", `/sandboxes/${encodeURIComponent(name)}`);
+  }
+  /** Run a command in an existing sandbox. */
+  async execInSandbox(name, command) {
+    return this.request(
+      "POST",
+      `/sandboxes/${encodeURIComponent(name)}/exec`,
+      { command }
+    );
+  }
+  /**
+   * Create a sandbox session with automatic cleanup.
+   *
+   * The returned SandboxSession implements AsyncDisposable,
+   * so it works with `await using` (TS 5.2+):
+   *
+   * @example
+   * ```ts
+   * await using sb = await client.sandbox("test", { image: "python:3.12-alpine" });
+   * await sb.run(["pip", "install", "numpy"]);
+   * // sandbox auto-removed when scope exits
+   * ```
+   */
+  async sandbox(name, opts) {
+    await this.createSandbox(name, opts);
+    return new SandboxSession(
+      name,
+      (n, cmd) => this.execInSandbox(n, cmd),
+      (n) => this.removeSandbox(n),
+      (n) => this.getSandbox(n)
+    );
+  }
+  // -- Internal helpers --
+  headers(contentType) {
+    const h = {
+      "User-Agent": `agentkernel-nodejs-sdk/${SDK_VERSION}`
+    };
+    if (contentType) h["Content-Type"] = contentType;
+    if (this.apiKey) h["Authorization"] = `Bearer ${this.apiKey}`;
+    return h;
+  }
+  async fetch(path, init) {
+    const url = `${this.baseUrl}${path}`;
+    try {
+      return await fetch(url, {
+        ...init,
+        signal: AbortSignal.timeout(this.timeout)
+      });
+    } catch (err) {
+      if (err instanceof DOMException && err.name === "TimeoutError") {
+        throw new NetworkError(`Request timed out after ${this.timeout}ms`);
+      }
+      if (err instanceof TypeError) {
+        throw new NetworkError(`Failed to connect to ${this.baseUrl}: ${err.message}`);
+      }
+      throw new NetworkError(
+        err instanceof Error ? err.message : String(err)
+      );
+    }
+  }
+  async request(method, path, body) {
+    const init = {
+      method,
+      headers: this.headers(body ? "application/json" : void 0)
+    };
+    if (body) init.body = JSON.stringify(body);
+    const response = await this.fetch(path, init);
+    const text = await response.text();
+    if (!response.ok) {
+      throw errorFromStatus(response.status, text);
+    }
+    const parsed = JSON.parse(text);
+    if (!parsed.success) {
+      throw new AgentKernelError(parsed.error ?? "Unknown error");
+    }
+    return parsed.data;
+  }
+};
+export {
+  AgentKernel,
+  AgentKernelError,
+  AuthError,
+  NetworkError,
+  NotFoundError,
+  SandboxSession,
+  ServerError,
+  StreamError,
+  ValidationError
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/config.ts","../src/errors.ts","../src/sandbox.ts","../src/sse.ts","../src/client.ts"],"sourcesContent":["import type { AgentKernelOptions } from \"./types.js\";\n\nconst DEFAULT_BASE_URL = \"http://localhost:18888\";\nconst DEFAULT_TIMEOUT = 30_000;\n\n/** Resolve configuration from constructor args, env vars, and defaults. */\nexport function resolveConfig(opts?: AgentKernelOptions) {\n  const baseUrl =\n    opts?.baseUrl ??\n    process.env.AGENTKERNEL_BASE_URL ??\n    DEFAULT_BASE_URL;\n\n  const apiKey =\n    opts?.apiKey ??\n    process.env.AGENTKERNEL_API_KEY ??\n    undefined;\n\n  const timeout = opts?.timeout ?? DEFAULT_TIMEOUT;\n\n  return {\n    baseUrl: baseUrl.replace(/\\/+$/, \"\"),\n    apiKey,\n    timeout,\n  };\n}\n","/** Base error for all agentkernel SDK errors. */\nexport class AgentKernelError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"AgentKernelError\";\n  }\n}\n\n/** 401 Unauthorized. */\nexport class AuthError extends AgentKernelError {\n  readonly status = 401;\n  constructor(message = \"Unauthorized\") {\n    super(message);\n    this.name = \"AuthError\";\n  }\n}\n\n/** 404 Not Found. */\nexport class NotFoundError extends AgentKernelError {\n  readonly status = 404;\n  constructor(message = \"Not found\") {\n    super(message);\n    this.name = \"NotFoundError\";\n  }\n}\n\n/** 400 Bad Request. */\nexport class ValidationError extends AgentKernelError {\n  readonly status = 400;\n  constructor(message = \"Bad request\") {\n    super(message);\n    this.name = \"ValidationError\";\n  }\n}\n\n/** 500 Internal Server Error. */\nexport class ServerError extends AgentKernelError {\n  readonly status = 500;\n  constructor(message = \"Internal server error\") {\n    super(message);\n    this.name = \"ServerError\";\n  }\n}\n\n/** Network / connection error. */\nexport class NetworkError extends AgentKernelError {\n  constructor(message = \"Network error\") {\n    super(message);\n    this.name = \"NetworkError\";\n  }\n}\n\n/** SSE streaming error. */\nexport class StreamError extends AgentKernelError {\n  constructor(message = \"Stream error\") {\n    super(message);\n    this.name = \"StreamError\";\n  }\n}\n\n/** Map an HTTP status code + body to the appropriate error. */\nexport function errorFromStatus(status: number, body: string): AgentKernelError {\n  let message: string;\n  try {\n    const parsed = JSON.parse(body);\n    message = parsed.error ?? body;\n  } catch {\n    message = body;\n  }\n\n  switch (status) {\n    case 400:\n      return new ValidationError(message);\n    case 401:\n      return new AuthError(message);\n    case 404:\n      return new NotFoundError(message);\n    default:\n      return new ServerError(message);\n  }\n}\n","import type { RunOutput, SandboxInfo } from \"./types.js\";\n\ntype ExecFn = (name: string, command: string[]) => Promise<RunOutput>;\ntype RemoveFn = (name: string) => Promise<void>;\ntype GetFn = (name: string) => Promise<SandboxInfo>;\n\n/**\n * A sandbox session that auto-removes the sandbox on dispose.\n *\n * Supports both explicit cleanup via remove() and automatic cleanup via\n * Symbol.asyncDispose (TS 5.2+ `await using`).\n *\n * @example\n * ```ts\n * await using sb = await client.sandbox(\"test\");\n * await sb.exec([\"echo\", \"hello\"]);\n * // sandbox auto-removed when scope exits\n * ```\n */\nexport class SandboxSession implements AsyncDisposable {\n  readonly name: string;\n  private _removed = false;\n  private readonly _execInSandbox: ExecFn;\n  private readonly _removeSandbox: RemoveFn;\n  private readonly _getSandbox: GetFn;\n\n  /** @internal */\n  constructor(\n    name: string,\n    execInSandbox: ExecFn,\n    removeSandbox: RemoveFn,\n    getSandbox: GetFn,\n  ) {\n    this.name = name;\n    this._execInSandbox = execInSandbox;\n    this._removeSandbox = removeSandbox;\n    this._getSandbox = getSandbox;\n  }\n\n  /** Run a command in this sandbox. */\n  async run(command: string[]): Promise<RunOutput> {\n    return this._execInSandbox(this.name, command);\n  }\n\n  /** Get sandbox info. */\n  async info(): Promise<SandboxInfo> {\n    return this._getSandbox(this.name);\n  }\n\n  /** Remove the sandbox. Idempotent. */\n  async remove(): Promise<void> {\n    if (this._removed) return;\n    this._removed = true;\n    await this._removeSandbox(this.name);\n  }\n\n  /** Auto-cleanup for `await using`. */\n  async [Symbol.asyncDispose](): Promise<void> {\n    await this.remove();\n  }\n}\n","import { createParser, type EventSourceMessage } from \"eventsource-parser\";\nimport type { StreamEvent, StreamEventType } from \"./types.js\";\n\nconst KNOWN_EVENTS = new Set<string>([\"started\", \"progress\", \"output\", \"done\", \"error\"]);\n\n/** Shared mutable state between the pump and the generator. */\ninterface PumpState {\n  events: StreamEvent[];\n  resolve: (() => void) | null;\n  done: boolean;\n}\n\nfunction pushEvent(state: PumpState, event: StreamEvent): void {\n  state.events.push(event);\n  if (state.resolve) {\n    const cb = state.resolve;\n    state.resolve = null;\n    cb();\n  }\n}\n\n/**\n * Parse an SSE response body into an async generator of StreamEvents.\n *\n * Consumes a ReadableStream<Uint8Array> from fetch() and yields typed events\n * until the stream closes or a \"done\"/\"error\" event is received.\n */\nexport async function* parseSSE(\n  body: ReadableStream<Uint8Array>,\n): AsyncGenerator<StreamEvent> {\n  const reader = body.getReader();\n  const decoder = new TextDecoder();\n  const state: PumpState = { events: [], resolve: null, done: false };\n\n  const parser = createParser({\n    onEvent(event: EventSourceMessage) {\n      const type = event.event ?? \"message\";\n      if (!KNOWN_EVENTS.has(type)) return;\n\n      let data: Record<string, unknown>;\n      try {\n        data = JSON.parse(event.data);\n      } catch {\n        data = { raw: event.data };\n      }\n\n      pushEvent(state, { type: type as StreamEventType, data });\n    },\n  });\n\n  // Read the stream in the background\n  const pump = (async () => {\n    try {\n      for (;;) {\n        const result = await reader.read();\n        if (result.done) break;\n        parser.feed(decoder.decode(result.value, { stream: true }));\n      }\n    } catch (err) {\n      pushEvent(state, {\n        type: \"error\",\n        data: { message: err instanceof Error ? err.message : String(err) },\n      });\n    } finally {\n      state.done = true;\n      if (state.resolve) {\n        const cb = state.resolve;\n        state.resolve = null;\n        cb();\n      }\n    }\n  })();\n\n  try {\n    for (;;) {\n      // Yield all buffered events\n      while (state.events.length > 0) {\n        const event = state.events.shift()!;\n        yield event;\n        if (event.type === \"done\" || event.type === \"error\") return;\n      }\n\n      // If the stream is done and no more events, exit\n      if (state.done) return;\n\n      // Wait for the next event\n      await new Promise<void>((r) => {\n        state.resolve = r;\n      });\n    }\n  } finally {\n    reader.cancel().catch(() => {});\n    await pump.catch(() => {});\n  }\n}\n","import { resolveConfig } from \"./config.js\";\nimport {\n  AgentKernelError,\n  NetworkError,\n  errorFromStatus,\n} from \"./errors.js\";\nimport { SandboxSession } from \"./sandbox.js\";\nimport { parseSSE } from \"./sse.js\";\nimport type {\n  AgentKernelOptions,\n  ApiResponse,\n  CreateSandboxOptions,\n  RunOptions,\n  RunOutput,\n  SandboxInfo,\n  StreamEvent,\n} from \"./types.js\";\n\nconst SDK_VERSION = \"0.1.0\";\n\n/**\n * Client for the agentkernel HTTP API.\n *\n * @example\n * ```ts\n * const client = new AgentKernel();\n * const result = await client.run([\"echo\", \"hello\"]);\n * console.log(result.output); // \"hello\\n\"\n * ```\n */\nexport class AgentKernel {\n  private readonly baseUrl: string;\n  private readonly apiKey: string | undefined;\n  private readonly timeout: number;\n\n  constructor(opts?: AgentKernelOptions) {\n    const config = resolveConfig(opts);\n    this.baseUrl = config.baseUrl;\n    this.apiKey = config.apiKey;\n    this.timeout = config.timeout;\n  }\n\n  // -- Core API methods --\n\n  /** Health check. Returns \"ok\" if the server is running. */\n  async health(): Promise<string> {\n    const res = await this.request<string>(\"GET\", \"/health\");\n    return res;\n  }\n\n  /** Run a command in a temporary sandbox. */\n  async run(command: string[], opts?: RunOptions): Promise<RunOutput> {\n    return this.request<RunOutput>(\"POST\", \"/run\", {\n      command,\n      image: opts?.image,\n      profile: opts?.profile,\n      fast: opts?.fast ?? true,\n    });\n  }\n\n  /**\n   * Run a command with SSE streaming output.\n   *\n   * @example\n   * ```ts\n   * for await (const event of client.runStream([\"python3\", \"script.py\"])) {\n   *   if (event.type === \"output\") process.stdout.write(String(event.data.data));\n   * }\n   * ```\n   */\n  async *runStream(\n    command: string[],\n    opts?: RunOptions,\n  ): AsyncGenerator<StreamEvent> {\n    const body = JSON.stringify({\n      command,\n      image: opts?.image,\n      profile: opts?.profile,\n      fast: opts?.fast ?? true,\n    });\n\n    const response = await this.fetch(\"/run/stream\", {\n      method: \"POST\",\n      headers: this.headers(\"application/json\"),\n      body,\n    });\n\n    if (!response.ok) {\n      const text = await response.text();\n      throw errorFromStatus(response.status, text);\n    }\n\n    if (!response.body) {\n      throw new AgentKernelError(\"No response body for SSE stream\");\n    }\n\n    yield* parseSSE(response.body);\n  }\n\n  /** List all sandboxes. */\n  async listSandboxes(): Promise<SandboxInfo[]> {\n    return this.request<SandboxInfo[]>(\"GET\", \"/sandboxes\");\n  }\n\n  /** Create a new sandbox. */\n  async createSandbox(\n    name: string,\n    opts?: CreateSandboxOptions,\n  ): Promise<SandboxInfo> {\n    return this.request<SandboxInfo>(\"POST\", \"/sandboxes\", {\n      name,\n      image: opts?.image,\n    });\n  }\n\n  /** Get info about a sandbox. */\n  async getSandbox(name: string): Promise<SandboxInfo> {\n    return this.request<SandboxInfo>(\"GET\", `/sandboxes/${encodeURIComponent(name)}`);\n  }\n\n  /** Remove a sandbox. */\n  async removeSandbox(name: string): Promise<void> {\n    await this.request<string>(\"DELETE\", `/sandboxes/${encodeURIComponent(name)}`);\n  }\n\n  /** Run a command in an existing sandbox. */\n  async execInSandbox(name: string, command: string[]): Promise<RunOutput> {\n    return this.request<RunOutput>(\n      \"POST\",\n      `/sandboxes/${encodeURIComponent(name)}/exec`,\n      { command },\n    );\n  }\n\n  /**\n   * Create a sandbox session with automatic cleanup.\n   *\n   * The returned SandboxSession implements AsyncDisposable,\n   * so it works with `await using` (TS 5.2+):\n   *\n   * @example\n   * ```ts\n   * await using sb = await client.sandbox(\"test\", { image: \"python:3.12-alpine\" });\n   * await sb.run([\"pip\", \"install\", \"numpy\"]);\n   * // sandbox auto-removed when scope exits\n   * ```\n   */\n  async sandbox(\n    name: string,\n    opts?: CreateSandboxOptions,\n  ): Promise<SandboxSession> {\n    await this.createSandbox(name, opts);\n    return new SandboxSession(\n      name,\n      (n, cmd) => this.execInSandbox(n, cmd),\n      (n) => this.removeSandbox(n),\n      (n) => this.getSandbox(n),\n    );\n  }\n\n  // -- Internal helpers --\n\n  private headers(contentType?: string): Record<string, string> {\n    const h: Record<string, string> = {\n      \"User-Agent\": `agentkernel-nodejs-sdk/${SDK_VERSION}`,\n    };\n    if (contentType) h[\"Content-Type\"] = contentType;\n    if (this.apiKey) h[\"Authorization\"] = `Bearer ${this.apiKey}`;\n    return h;\n  }\n\n  private async fetch(path: string, init: RequestInit): Promise<Response> {\n    const url = `${this.baseUrl}${path}`;\n    try {\n      return await fetch(url, {\n        ...init,\n        signal: AbortSignal.timeout(this.timeout),\n      });\n    } catch (err) {\n      if (err instanceof DOMException && err.name === \"TimeoutError\") {\n        throw new NetworkError(`Request timed out after ${this.timeout}ms`);\n      }\n      if (err instanceof TypeError) {\n        throw new NetworkError(`Failed to connect to ${this.baseUrl}: ${err.message}`);\n      }\n      throw new NetworkError(\n        err instanceof Error ? err.message : String(err),\n      );\n    }\n  }\n\n  private async request<T>(\n    method: string,\n    path: string,\n    body?: unknown,\n  ): Promise<T> {\n    const init: RequestInit = {\n      method,\n      headers: this.headers(body ? \"application/json\" : undefined),\n    };\n    if (body) init.body = JSON.stringify(body);\n\n    const response = await this.fetch(path, init);\n\n    const text = await response.text();\n    if (!response.ok) {\n      throw errorFromStatus(response.status, text);\n    }\n\n    const parsed: ApiResponse<T> = JSON.parse(text);\n    if (!parsed.success) {\n      throw new AgentKernelError(parsed.error ?? \"Unknown error\");\n    }\n    return parsed.data as T;\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "agentkernel",
+  "version": "0.2.0",
+  "description": "Node.js SDK for agentkernel — run AI coding agents in secure, isolated microVMs",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "agentkernel",
+    "sandbox",
+    "microvm",
+    "ai",
+    "agent",
+    "firecracker",
+    "isolation"
+  ],
+  "author": "Paul Thrasher <thrashr888@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/thrashr888/agentkernel.git",
+    "directory": "sdk/nodejs"
+  },
+  "homepage": "https://thrashr888.github.io/agentkernel/",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "eventsource-parser": "^3.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.1.0",
+    "msw": "^2.7.0",
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}