@theokit/sdk 1.6.1 → 1.7.0

package/dist/sandbox/index.cjs

@@ -0,0 +1,133 @@
+'use strict';
+
+var child_process = require('child_process');
+var promises = require('fs/promises');
+var path = require('path');
+
+// src/sandbox/local-sandbox.ts
+
+// src/sandbox/types.ts
+var SandboxSecurityError = class extends Error {
+  code = "sandbox_security";
+  constructor(message) {
+    super(message);
+    this.name = "SandboxSecurityError";
+  }
+};
+var SandboxNotAvailableError = class extends Error {
+  code = "sandbox_not_available";
+  constructor(message) {
+    super(message);
+    this.name = "SandboxNotAvailableError";
+  }
+};
+var SHELL_METACHARACTERS = /[;&|`$(){}]/;
+var SandboxBackend = class {
+  config;
+  constructor(config = {}) {
+    this.config = {
+      workDir: config.workDir ?? "/tmp",
+      timeoutMs: config.timeoutMs ?? 3e4,
+      maxOutputBytes: config.maxOutputBytes ?? 5 * 1024 * 1024
+    };
+  }
+  async readFile(path) {
+    const result = await this.execute(`cat ${this.shellEscape(path)}`);
+    if (result.exitCode !== 0) {
+      throw new Error(`readFile failed: ${result.stderr}`);
+    }
+    return result.stdout;
+  }
+  async writeFile(path, content) {
+    await this.uploadFile(path, content);
+  }
+  async glob(pattern, cwd) {
+    const dir = cwd ?? this.config.workDir ?? ".";
+    const result = await this.execute(
+      `find ${this.shellEscape(dir)} -name ${this.shellEscape(pattern)} -type f 2>/dev/null`
+    );
+    if (result.exitCode !== 0) return [];
+    return result.stdout.trim().split("\n").filter(Boolean);
+  }
+  async grep(pattern, path) {
+    const target = path ?? ".";
+    const result = await this.execute(
+      `grep -rn ${this.shellEscape(pattern)} ${this.shellEscape(target)} 2>/dev/null`
+    );
+    if (result.exitCode !== 0) return [];
+    return result.stdout.trim().split("\n").filter(Boolean);
+  }
+  async listDir(path) {
+    const result = await this.execute(`ls -1 ${this.shellEscape(path)}`);
+    if (result.exitCode !== 0) return [];
+    return result.stdout.trim().split("\n").filter(Boolean);
+  }
+  validateCommand(command) {
+    if (SHELL_METACHARACTERS.test(command)) {
+      throw new SandboxSecurityError(
+        `Command contains shell metacharacters: ${command.slice(0, 80)}`
+      );
+    }
+  }
+  truncateOutput(output) {
+    const max = this.config.maxOutputBytes ?? 5 * 1024 * 1024;
+    if (Buffer.byteLength(output) > max) {
+      return `${output.slice(0, max)}
+...(truncated)`;
+    }
+    return output;
+  }
+  shellEscape(arg) {
+    return `'${arg.replace(/'/g, "'\\''")}'`;
+  }
+};
+
+// src/sandbox/local-sandbox.ts
+var LocalSandbox = class extends SandboxBackend {
+  constructor(config = {}) {
+    super(config);
+  }
+  async execute(command, opts) {
+    const timeout = opts?.timeoutMs ?? this.config.timeoutMs ?? 3e4;
+    const max = this.config.maxOutputBytes ?? 5 * 1024 * 1024;
+    return new Promise((resolve) => {
+      const child = child_process.execFile(
+        "/bin/sh",
+        ["-c", command],
+        {
+          cwd: this.config.workDir,
+          timeout,
+          maxBuffer: max,
+          encoding: "utf-8"
+        },
+        (error, stdout, stderr) => {
+          resolve(this.buildResult(error, stdout ?? "", stderr ?? ""));
+        }
+      );
+      child.on("error", () => {
+        resolve({ stdout: "", stderr: "spawn error", exitCode: 1, timedOut: false });
+      });
+    });
+  }
+  buildResult(error, stdout, stderr) {
+    const timedOut = error !== null && "killed" in error && error.killed;
+    return {
+      stdout: this.truncateOutput(stdout),
+      stderr: this.truncateOutput(stderr),
+      exitCode: timedOut ? 124 : error ? 1 : 0,
+      timedOut
+    };
+  }
+  async uploadFile(path$1, content) {
+    const fullPath = path$1.startsWith("/") ? path$1 : `${this.config.workDir}/${path$1}`;
+    await promises.mkdir(path.dirname(fullPath), { recursive: true });
+    await promises.writeFile(fullPath, content, "utf-8");
+  }
+};
+
+exports.LocalSandbox = LocalSandbox;
+exports.SandboxBackend = SandboxBackend;
+exports.SandboxNotAvailableError = SandboxNotAvailableError;
+exports.SandboxSecurityError = SandboxSecurityError;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/sandbox/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/sandbox/types.ts","../../src/sandbox/local-sandbox.ts"],"names":["execFile","path","mkdir","dirname","fsWriteFile"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * Sandbox backend protocol — pluggable execution environment for agent tools.\n *\n * Per ADR D1: only 2 abstract methods (`execute` + `uploadFile`). All\n * higher-level operations are derived on the base class. New backends\n * (Docker, Firecracker, E2B) only implement those 2 methods.\n *\n * @public\n */\n\nexport interface ExecuteResult {\n  stdout: string;\n  stderr: string;\n  exitCode: number;\n  timedOut: boolean;\n}\n\nexport interface SandboxConfig {\n  workDir?: string;\n  timeoutMs?: number;\n  maxOutputBytes?: number;\n}\n\nexport class SandboxSecurityError extends Error {\n  readonly code = \"sandbox_security\" as const;\n  constructor(message: string) {\n    super(message);\n    this.name = \"SandboxSecurityError\";\n  }\n}\n\nexport class SandboxNotAvailableError extends Error {\n  readonly code = \"sandbox_not_available\" as const;\n  constructor(message: string) {\n    super(message);\n    this.name = \"SandboxNotAvailableError\";\n  }\n}\n\nconst SHELL_METACHARACTERS = /[;&|`$(){}]/;\n\nexport abstract class SandboxBackend {\n  protected config: SandboxConfig;\n\n  constructor(config: SandboxConfig = {}) {\n    this.config = {\n      workDir: config.workDir ?? \"/tmp\",\n      timeoutMs: config.timeoutMs ?? 30_000,\n      maxOutputBytes: config.maxOutputBytes ?? 5 * 1024 * 1024,\n    };\n  }\n\n  abstract execute(command: string, opts?: { timeoutMs?: number }): Promise<ExecuteResult>;\n\n  abstract uploadFile(path: string, content: string | Buffer): Promise<void>;\n\n  async readFile(path: string): Promise<string> {\n    const result = await this.execute(`cat ${this.shellEscape(path)}`);\n    if (result.exitCode !== 0) {\n      throw new Error(`readFile failed: ${result.stderr}`);\n    }\n    return result.stdout;\n  }\n\n  async writeFile(path: string, content: string): Promise<void> {\n    await this.uploadFile(path, content);\n  }\n\n  async glob(pattern: string, cwd?: string): Promise<string[]> {\n    const dir = cwd ?? this.config.workDir ?? \".\";\n    const result = await this.execute(\n      `find ${this.shellEscape(dir)} -name ${this.shellEscape(pattern)} -type f 2>/dev/null`,\n    );\n    if (result.exitCode !== 0) return [];\n    return result.stdout.trim().split(\"\\n\").filter(Boolean);\n  }\n\n  async grep(pattern: string, path?: string): Promise<string[]> {\n    const target = path ?? \".\";\n    const result = await this.execute(\n      `grep -rn ${this.shellEscape(pattern)} ${this.shellEscape(target)} 2>/dev/null`,\n    );\n    if (result.exitCode !== 0) return [];\n    return result.stdout.trim().split(\"\\n\").filter(Boolean);\n  }\n\n  async listDir(path: string): Promise<string[]> {\n    const result = await this.execute(`ls -1 ${this.shellEscape(path)}`);\n    if (result.exitCode !== 0) return [];\n    return result.stdout.trim().split(\"\\n\").filter(Boolean);\n  }\n\n  protected validateCommand(command: string): void {\n    if (SHELL_METACHARACTERS.test(command)) {\n      throw new SandboxSecurityError(\n        `Command contains shell metacharacters: ${command.slice(0, 80)}`,\n      );\n    }\n  }\n\n  protected truncateOutput(output: string): string {\n    const max = this.config.maxOutputBytes ?? 5 * 1024 * 1024;\n    if (Buffer.byteLength(output) > max) {\n      return `${output.slice(0, max)}\\n...(truncated)`;\n    }\n    return output;\n  }\n\n  private shellEscape(arg: string): string {\n    return `'${arg.replace(/'/g, \"'\\\\''\")}'`;\n  }\n}\n","/**\n * LocalSandbox — subprocess-based execution with NO isolation.\n *\n * Uses `execFile` with split args (NOT `exec` with string) per EC-1.\n * This is NOT a security boundary — only DockerSandbox provides isolation.\n *\n * @public\n */\n\nimport { execFile } from \"node:child_process\";\nimport { writeFile as fsWriteFile, mkdir } from \"node:fs/promises\";\nimport { dirname } from \"node:path\";\n\nimport { type ExecuteResult, SandboxBackend, type SandboxConfig } from \"./types.js\";\n\nexport class LocalSandbox extends SandboxBackend {\n  constructor(config: SandboxConfig = {}) {\n    super(config);\n  }\n\n  async execute(command: string, opts?: { timeoutMs?: number }): Promise<ExecuteResult> {\n    const timeout = opts?.timeoutMs ?? this.config.timeoutMs ?? 30_000;\n    const max = this.config.maxOutputBytes ?? 5 * 1024 * 1024;\n\n    return new Promise<ExecuteResult>((resolve) => {\n      const child = execFile(\n        \"/bin/sh\",\n        [\"-c\", command],\n        {\n          cwd: this.config.workDir,\n          timeout,\n          maxBuffer: max,\n          encoding: \"utf-8\",\n        },\n        (error, stdout, stderr) => {\n          resolve(this.buildResult(error, stdout ?? \"\", stderr ?? \"\"));\n        },\n      );\n\n      // Safety: if child somehow doesn't callback\n      child.on(\"error\", () => {\n        resolve({ stdout: \"\", stderr: \"spawn error\", exitCode: 1, timedOut: false });\n      });\n    });\n  }\n\n  private buildResult(error: Error | null, stdout: string, stderr: string): ExecuteResult {\n    const timedOut = error !== null && \"killed\" in error && (error as { killed: boolean }).killed;\n    return {\n      stdout: this.truncateOutput(stdout),\n      stderr: this.truncateOutput(stderr),\n      exitCode: timedOut ? 124 : error ? 1 : 0,\n      timedOut,\n    };\n  }\n\n  async uploadFile(path: string, content: string | Buffer): Promise<void> {\n    const fullPath = path.startsWith(\"/\") ? path : `${this.config.workDir}/${path}`;\n    await mkdir(dirname(fullPath), { recursive: true });\n    await fsWriteFile(fullPath, content, \"utf-8\");\n  }\n}\n"]}

package/dist/sandbox/index.d.cts

@@ -0,0 +1,2 @@
+export { LocalSandbox } from "./local-sandbox.js";
+export { type ExecuteResult, SandboxBackend, type SandboxConfig, SandboxNotAvailableError, SandboxSecurityError, } from "./types.js";

package/dist/sandbox/index.d.ts

@@ -0,0 +1,2 @@
+export { LocalSandbox } from "./local-sandbox.js";
+export { type ExecuteResult, SandboxBackend, type SandboxConfig, SandboxNotAvailableError, SandboxSecurityError, } from "./types.js";

package/dist/sandbox/index.js

@@ -0,0 +1,128 @@
+import { execFile } from 'child_process';
+import { mkdir, writeFile } from 'fs/promises';
+import { dirname } from 'path';
+
+// src/sandbox/local-sandbox.ts
+
+// src/sandbox/types.ts
+var SandboxSecurityError = class extends Error {
+  code = "sandbox_security";
+  constructor(message) {
+    super(message);
+    this.name = "SandboxSecurityError";
+  }
+};
+var SandboxNotAvailableError = class extends Error {
+  code = "sandbox_not_available";
+  constructor(message) {
+    super(message);
+    this.name = "SandboxNotAvailableError";
+  }
+};
+var SHELL_METACHARACTERS = /[;&|`$(){}]/;
+var SandboxBackend = class {
+  config;
+  constructor(config = {}) {
+    this.config = {
+      workDir: config.workDir ?? "/tmp",
+      timeoutMs: config.timeoutMs ?? 3e4,
+      maxOutputBytes: config.maxOutputBytes ?? 5 * 1024 * 1024
+    };
+  }
+  async readFile(path) {
+    const result = await this.execute(`cat ${this.shellEscape(path)}`);
+    if (result.exitCode !== 0) {
+      throw new Error(`readFile failed: ${result.stderr}`);
+    }
+    return result.stdout;
+  }
+  async writeFile(path, content) {
+    await this.uploadFile(path, content);
+  }
+  async glob(pattern, cwd) {
+    const dir = cwd ?? this.config.workDir ?? ".";
+    const result = await this.execute(
+      `find ${this.shellEscape(dir)} -name ${this.shellEscape(pattern)} -type f 2>/dev/null`
+    );
+    if (result.exitCode !== 0) return [];
+    return result.stdout.trim().split("\n").filter(Boolean);
+  }
+  async grep(pattern, path) {
+    const target = path ?? ".";
+    const result = await this.execute(
+      `grep -rn ${this.shellEscape(pattern)} ${this.shellEscape(target)} 2>/dev/null`
+    );
+    if (result.exitCode !== 0) return [];
+    return result.stdout.trim().split("\n").filter(Boolean);
+  }
+  async listDir(path) {
+    const result = await this.execute(`ls -1 ${this.shellEscape(path)}`);
+    if (result.exitCode !== 0) return [];
+    return result.stdout.trim().split("\n").filter(Boolean);
+  }
+  validateCommand(command) {
+    if (SHELL_METACHARACTERS.test(command)) {
+      throw new SandboxSecurityError(
+        `Command contains shell metacharacters: ${command.slice(0, 80)}`
+      );
+    }
+  }
+  truncateOutput(output) {
+    const max = this.config.maxOutputBytes ?? 5 * 1024 * 1024;
+    if (Buffer.byteLength(output) > max) {
+      return `${output.slice(0, max)}
+...(truncated)`;
+    }
+    return output;
+  }
+  shellEscape(arg) {
+    return `'${arg.replace(/'/g, "'\\''")}'`;
+  }
+};
+
+// src/sandbox/local-sandbox.ts
+var LocalSandbox = class extends SandboxBackend {
+  constructor(config = {}) {
+    super(config);
+  }
+  async execute(command, opts) {
+    const timeout = opts?.timeoutMs ?? this.config.timeoutMs ?? 3e4;
+    const max = this.config.maxOutputBytes ?? 5 * 1024 * 1024;
+    return new Promise((resolve) => {
+      const child = execFile(
+        "/bin/sh",
+        ["-c", command],
+        {
+          cwd: this.config.workDir,
+          timeout,
+          maxBuffer: max,
+          encoding: "utf-8"
+        },
+        (error, stdout, stderr) => {
+          resolve(this.buildResult(error, stdout ?? "", stderr ?? ""));
+        }
+      );
+      child.on("error", () => {
+        resolve({ stdout: "", stderr: "spawn error", exitCode: 1, timedOut: false });
+      });
+    });
+  }
+  buildResult(error, stdout, stderr) {
+    const timedOut = error !== null && "killed" in error && error.killed;
+    return {
+      stdout: this.truncateOutput(stdout),
+      stderr: this.truncateOutput(stderr),
+      exitCode: timedOut ? 124 : error ? 1 : 0,
+      timedOut
+    };
+  }
+  async uploadFile(path, content) {
+    const fullPath = path.startsWith("/") ? path : `${this.config.workDir}/${path}`;
+    await mkdir(dirname(fullPath), { recursive: true });
+    await writeFile(fullPath, content, "utf-8");
+  }
+};
+
+export { LocalSandbox, SandboxBackend, SandboxNotAvailableError, SandboxSecurityError };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/sandbox/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/sandbox/types.ts","../../src/sandbox/local-sandbox.ts"],"names":["fsWriteFile"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Sandbox backend protocol — pluggable execution environment for agent tools.\n *\n * Per ADR D1: only 2 abstract methods (`execute` + `uploadFile`). All\n * higher-level operations are derived on the base class. New backends\n * (Docker, Firecracker, E2B) only implement those 2 methods.\n *\n * @public\n */\n\nexport interface ExecuteResult {\n  stdout: string;\n  stderr: string;\n  exitCode: number;\n  timedOut: boolean;\n}\n\nexport interface SandboxConfig {\n  workDir?: string;\n  timeoutMs?: number;\n  maxOutputBytes?: number;\n}\n\nexport class SandboxSecurityError extends Error {\n  readonly code = \"sandbox_security\" as const;\n  constructor(message: string) {\n    super(message);\n    this.name = \"SandboxSecurityError\";\n  }\n}\n\nexport class SandboxNotAvailableError extends Error {\n  readonly code = \"sandbox_not_available\" as const;\n  constructor(message: string) {\n    super(message);\n    this.name = \"SandboxNotAvailableError\";\n  }\n}\n\nconst SHELL_METACHARACTERS = /[;&|`$(){}]/;\n\nexport abstract class SandboxBackend {\n  protected config: SandboxConfig;\n\n  constructor(config: SandboxConfig = {}) {\n    this.config = {\n      workDir: config.workDir ?? \"/tmp\",\n      timeoutMs: config.timeoutMs ?? 30_000,\n      maxOutputBytes: config.maxOutputBytes ?? 5 * 1024 * 1024,\n    };\n  }\n\n  abstract execute(command: string, opts?: { timeoutMs?: number }): Promise<ExecuteResult>;\n\n  abstract uploadFile(path: string, content: string | Buffer): Promise<void>;\n\n  async readFile(path: string): Promise<string> {\n    const result = await this.execute(`cat ${this.shellEscape(path)}`);\n    if (result.exitCode !== 0) {\n      throw new Error(`readFile failed: ${result.stderr}`);\n    }\n    return result.stdout;\n  }\n\n  async writeFile(path: string, content: string): Promise<void> {\n    await this.uploadFile(path, content);\n  }\n\n  async glob(pattern: string, cwd?: string): Promise<string[]> {\n    const dir = cwd ?? this.config.workDir ?? \".\";\n    const result = await this.execute(\n      `find ${this.shellEscape(dir)} -name ${this.shellEscape(pattern)} -type f 2>/dev/null`,\n    );\n    if (result.exitCode !== 0) return [];\n    return result.stdout.trim().split(\"\\n\").filter(Boolean);\n  }\n\n  async grep(pattern: string, path?: string): Promise<string[]> {\n    const target = path ?? \".\";\n    const result = await this.execute(\n      `grep -rn ${this.shellEscape(pattern)} ${this.shellEscape(target)} 2>/dev/null`,\n    );\n    if (result.exitCode !== 0) return [];\n    return result.stdout.trim().split(\"\\n\").filter(Boolean);\n  }\n\n  async listDir(path: string): Promise<string[]> {\n    const result = await this.execute(`ls -1 ${this.shellEscape(path)}`);\n    if (result.exitCode !== 0) return [];\n    return result.stdout.trim().split(\"\\n\").filter(Boolean);\n  }\n\n  protected validateCommand(command: string): void {\n    if (SHELL_METACHARACTERS.test(command)) {\n      throw new SandboxSecurityError(\n        `Command contains shell metacharacters: ${command.slice(0, 80)}`,\n      );\n    }\n  }\n\n  protected truncateOutput(output: string): string {\n    const max = this.config.maxOutputBytes ?? 5 * 1024 * 1024;\n    if (Buffer.byteLength(output) > max) {\n      return `${output.slice(0, max)}\\n...(truncated)`;\n    }\n    return output;\n  }\n\n  private shellEscape(arg: string): string {\n    return `'${arg.replace(/'/g, \"'\\\\''\")}'`;\n  }\n}\n","/**\n * LocalSandbox — subprocess-based execution with NO isolation.\n *\n * Uses `execFile` with split args (NOT `exec` with string) per EC-1.\n * This is NOT a security boundary — only DockerSandbox provides isolation.\n *\n * @public\n */\n\nimport { execFile } from \"node:child_process\";\nimport { writeFile as fsWriteFile, mkdir } from \"node:fs/promises\";\nimport { dirname } from \"node:path\";\n\nimport { type ExecuteResult, SandboxBackend, type SandboxConfig } from \"./types.js\";\n\nexport class LocalSandbox extends SandboxBackend {\n  constructor(config: SandboxConfig = {}) {\n    super(config);\n  }\n\n  async execute(command: string, opts?: { timeoutMs?: number }): Promise<ExecuteResult> {\n    const timeout = opts?.timeoutMs ?? this.config.timeoutMs ?? 30_000;\n    const max = this.config.maxOutputBytes ?? 5 * 1024 * 1024;\n\n    return new Promise<ExecuteResult>((resolve) => {\n      const child = execFile(\n        \"/bin/sh\",\n        [\"-c\", command],\n        {\n          cwd: this.config.workDir,\n          timeout,\n          maxBuffer: max,\n          encoding: \"utf-8\",\n        },\n        (error, stdout, stderr) => {\n          resolve(this.buildResult(error, stdout ?? \"\", stderr ?? \"\"));\n        },\n      );\n\n      // Safety: if child somehow doesn't callback\n      child.on(\"error\", () => {\n        resolve({ stdout: \"\", stderr: \"spawn error\", exitCode: 1, timedOut: false });\n      });\n    });\n  }\n\n  private buildResult(error: Error | null, stdout: string, stderr: string): ExecuteResult {\n    const timedOut = error !== null && \"killed\" in error && (error as { killed: boolean }).killed;\n    return {\n      stdout: this.truncateOutput(stdout),\n      stderr: this.truncateOutput(stderr),\n      exitCode: timedOut ? 124 : error ? 1 : 0,\n      timedOut,\n    };\n  }\n\n  async uploadFile(path: string, content: string | Buffer): Promise<void> {\n    const fullPath = path.startsWith(\"/\") ? path : `${this.config.workDir}/${path}`;\n    await mkdir(dirname(fullPath), { recursive: true });\n    await fsWriteFile(fullPath, content, \"utf-8\");\n  }\n}\n"]}

package/dist/sandbox/local-sandbox.d.cts

@@ -0,0 +1,17 @@
+/**
+ * LocalSandbox — subprocess-based execution with NO isolation.
+ *
+ * Uses `execFile` with split args (NOT `exec` with string) per EC-1.
+ * This is NOT a security boundary — only DockerSandbox provides isolation.
+ *
+ * @public
+ */
+import { type ExecuteResult, SandboxBackend, type SandboxConfig } from "./types.js";
+export declare class LocalSandbox extends SandboxBackend {
+    constructor(config?: SandboxConfig);
+    execute(command: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<ExecuteResult>;
+    private buildResult;
+    uploadFile(path: string, content: string | Buffer): Promise<void>;
+}

package/dist/sandbox/local-sandbox.d.ts

@@ -0,0 +1,17 @@
+/**
+ * LocalSandbox — subprocess-based execution with NO isolation.
+ *
+ * Uses `execFile` with split args (NOT `exec` with string) per EC-1.
+ * This is NOT a security boundary — only DockerSandbox provides isolation.
+ *
+ * @public
+ */
+import { type ExecuteResult, SandboxBackend, type SandboxConfig } from "./types.js";
+export declare class LocalSandbox extends SandboxBackend {
+    constructor(config?: SandboxConfig);
+    execute(command: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<ExecuteResult>;
+    private buildResult;
+    uploadFile(path: string, content: string | Buffer): Promise<void>;
+}

package/dist/sandbox/types.d.cts

@@ -0,0 +1,44 @@
+/**
+ * Sandbox backend protocol — pluggable execution environment for agent tools.
+ *
+ * Per ADR D1: only 2 abstract methods (`execute` + `uploadFile`). All
+ * higher-level operations are derived on the base class. New backends
+ * (Docker, Firecracker, E2B) only implement those 2 methods.
+ *
+ * @public
+ */
+export interface ExecuteResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    timedOut: boolean;
+}
+export interface SandboxConfig {
+    workDir?: string;
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+}
+export declare class SandboxSecurityError extends Error {
+    readonly code: "sandbox_security";
+    constructor(message: string);
+}
+export declare class SandboxNotAvailableError extends Error {
+    readonly code: "sandbox_not_available";
+    constructor(message: string);
+}
+export declare abstract class SandboxBackend {
+    protected config: SandboxConfig;
+    constructor(config?: SandboxConfig);
+    abstract execute(command: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<ExecuteResult>;
+    abstract uploadFile(path: string, content: string | Buffer): Promise<void>;
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, content: string): Promise<void>;
+    glob(pattern: string, cwd?: string): Promise<string[]>;
+    grep(pattern: string, path?: string): Promise<string[]>;
+    listDir(path: string): Promise<string[]>;
+    protected validateCommand(command: string): void;
+    protected truncateOutput(output: string): string;
+    private shellEscape;
+}

package/dist/sandbox/types.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Sandbox backend protocol — pluggable execution environment for agent tools.
+ *
+ * Per ADR D1: only 2 abstract methods (`execute` + `uploadFile`). All
+ * higher-level operations are derived on the base class. New backends
+ * (Docker, Firecracker, E2B) only implement those 2 methods.
+ *
+ * @public
+ */
+export interface ExecuteResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    timedOut: boolean;
+}
+export interface SandboxConfig {
+    workDir?: string;
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+}
+export declare class SandboxSecurityError extends Error {
+    readonly code: "sandbox_security";
+    constructor(message: string);
+}
+export declare class SandboxNotAvailableError extends Error {
+    readonly code: "sandbox_not_available";
+    constructor(message: string);
+}
+export declare abstract class SandboxBackend {
+    protected config: SandboxConfig;
+    constructor(config?: SandboxConfig);
+    abstract execute(command: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<ExecuteResult>;
+    abstract uploadFile(path: string, content: string | Buffer): Promise<void>;
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, content: string): Promise<void>;
+    glob(pattern: string, cwd?: string): Promise<string[]>;
+    grep(pattern: string, path?: string): Promise<string[]>;
+    listDir(path: string): Promise<string[]>;
+    protected validateCommand(command: string): void;
+    protected truncateOutput(output: string): string;
+    private shellEscape;
+}

package/dist/server/adapter/express.d.cts

@@ -0,0 +1,9 @@
+/**
+ * Express server adapter — mounts a TheoKit agent as Express middleware (T12.2).
+ *
+ * Optional peer dep: express@^4||^5
+ *
+ * @public
+ */
+import type { AgentHandlerOptions, AgentLike } from "./types.js";
+export declare function createAgentHandler(agent: AgentLike, opts?: AgentHandlerOptions): import("./types.js").AgentHandler;

package/dist/server/adapter/express.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Express server adapter — mounts a TheoKit agent as Express middleware (T12.2).
+ *
+ * Optional peer dep: express@^4||^5
+ *
+ * @public
+ */
+import type { AgentHandlerOptions, AgentLike } from "./types.js";
+export declare function createAgentHandler(agent: AgentLike, opts?: AgentHandlerOptions): import("./types.js").AgentHandler;

package/dist/server/adapter/fastify.d.cts

@@ -0,0 +1,9 @@
+/**
+ * Fastify server adapter — mounts a TheoKit agent as Fastify plugin (T12.2).
+ *
+ * Optional peer dep: fastify@^5
+ *
+ * @public
+ */
+import type { AgentHandlerOptions, AgentLike } from "./types.js";
+export declare function createAgentHandler(agent: AgentLike, opts?: AgentHandlerOptions): import("./types.js").AgentHandler;

package/dist/server/adapter/fastify.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Fastify server adapter — mounts a TheoKit agent as Fastify plugin (T12.2).
+ *
+ * Optional peer dep: fastify@^5
+ *
+ * @public
+ */
+import type { AgentHandlerOptions, AgentLike } from "./types.js";
+export declare function createAgentHandler(agent: AgentLike, opts?: AgentHandlerOptions): import("./types.js").AgentHandler;

package/dist/server/adapter/hono.d.cts

@@ -0,0 +1,9 @@
+/**
+ * Hono server adapter — mounts a TheoKit agent as Hono middleware (T12.2).
+ *
+ * Optional peer dep: hono@^4
+ *
+ * @public
+ */
+import type { AgentHandlerOptions, AgentLike } from "./types.js";
+export declare function createAgentHandler(agent: AgentLike, opts?: AgentHandlerOptions): import("./types.js").AgentHandler;

package/dist/server/adapter/hono.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Hono server adapter — mounts a TheoKit agent as Hono middleware (T12.2).
+ *
+ * Optional peer dep: hono@^4
+ *
+ * @public
+ */
+import type { AgentHandlerOptions, AgentLike } from "./types.js";
+export declare function createAgentHandler(agent: AgentLike, opts?: AgentHandlerOptions): import("./types.js").AgentHandler;

package/dist/server/adapter/index.d.cts

@@ -0,0 +1,8 @@
+/**
+ * Server adapter barrel — exports all framework adapters (T12.2).
+ * @public
+ */
+export { createAgentHandler as createExpressAgentHandler } from "./express.js";
+export { createAgentHandler as createFastifyAgentHandler } from "./fastify.js";
+export { createAgentHandler as createHonoAgentHandler } from "./hono.js";
+export type { AgentHandlerOptions, AgentLike } from "./types.js";

package/dist/server/adapter/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Server adapter barrel — exports all framework adapters (T12.2).
+ * @public
+ */
+export { createAgentHandler as createExpressAgentHandler } from "./express.js";
+export { createAgentHandler as createFastifyAgentHandler } from "./fastify.js";
+export { createAgentHandler as createHonoAgentHandler } from "./hono.js";
+export type { AgentHandlerOptions, AgentLike } from "./types.js";

package/dist/server/adapter/shared-handler.d.cts

@@ -0,0 +1,9 @@
+/**
+ * Shared agent handler factory — common logic used by all framework adapters (T12.2).
+ *
+ * Each adapter re-exports its own `createAgentHandler` for tree-shaking
+ * friendliness, but the actual implementation lives here.
+ *
+ * @internal
+ */
+export declare function createSharedAgentHandler(agent: AgentLike, opts?: AgentHandlerOptions): AgentHandler;

package/dist/server/adapter/shared-handler.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Shared agent handler factory — common logic used by all framework adapters (T12.2).
+ *
+ * Each adapter re-exports its own `createAgentHandler` for tree-shaking
+ * friendliness, but the actual implementation lives here.
+ *
+ * @internal
+ */
+export declare function createSharedAgentHandler(agent: AgentLike, opts?: AgentHandlerOptions): AgentHandler;

package/dist/server/adapter/types.d.cts

@@ -0,0 +1,33 @@
+/**
+ * AgentMiddleware — shared contract for server adapters (T12.2).
+ * @public
+ */
+export interface AgentHandlerOptions {
+    basePath?: string;
+    onError?: (err: Error) => void;
+}
+export interface AgentLike {
+    send(input: string, opts?: {
+        signal?: AbortSignal;
+    }): {
+        stream(): AsyncIterable<unknown>;
+        wait(): Promise<unknown>;
+    };
+    dispose(): void;
+}
+export interface AgentHandler {
+    routes: ReadonlyArray<{
+        method: string;
+        path: string;
+    }>;
+    handleRequest(req: {
+        method: string;
+        url: string;
+        body?: unknown;
+        signal?: AbortSignal;
+    }): Promise<{
+        status: number;
+        body?: unknown;
+        stream?: AsyncIterable<unknown>;
+    }>;
+}

package/dist/server/adapter/types.d.ts

@@ -0,0 +1,33 @@
+/**
+ * AgentMiddleware — shared contract for server adapters (T12.2).
+ * @public
+ */
+export interface AgentHandlerOptions {
+    basePath?: string;
+    onError?: (err: Error) => void;
+}
+export interface AgentLike {
+    send(input: string, opts?: {
+        signal?: AbortSignal;
+    }): {
+        stream(): AsyncIterable<unknown>;
+        wait(): Promise<unknown>;
+    };
+    dispose(): void;
+}
+export interface AgentHandler {
+    routes: ReadonlyArray<{
+        method: string;
+        path: string;
+    }>;
+    handleRequest(req: {
+        method: string;
+        url: string;
+        body?: unknown;
+        signal?: AbortSignal;
+    }): Promise<{
+        status: number;
+        body?: unknown;
+        stream?: AsyncIterable<unknown>;
+    }>;
+}