@nebutra/sandbox-runtime 0.1.0

package/dist/chunk-UGJKHUL3.js

@@ -0,0 +1,151 @@
+// src/index.ts
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { dirname, join } from "path";
+import { CapabilityError } from "@nebutra/errors";
+function sandboxDebugPath() {
+  return join(process.cwd(), ".nebutra", "debug", "sandbox-runtime.jsonl");
+}
+async function appendSandboxDebug(entry) {
+  const path = sandboxDebugPath();
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify({ at: (/* @__PURE__ */ new Date()).toISOString(), ...entry })}
+`, {
+    flag: "a"
+  });
+}
+function createLocalMacSandbox(options = {}) {
+  const endpoint = options.endpoint ?? process.env.SANDBOX_RUNTIME_LOCAL_URL ?? "http://127.0.0.1:8020/api/v1/sandbox/exec";
+  const fetchImpl = options.fetch ?? fetch;
+  return {
+    id: "local_mac",
+    async exec(request) {
+      const response = await fetchImpl(endpoint, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          tenantId: request.tenantId ?? "local",
+          threadId: request.threadId ?? "local",
+          command: request.cmd,
+          capabilityPolicy: {
+            kind: "external_sandbox",
+            network_access: request.hints?.networkAccess ?? false
+          }
+        })
+      });
+      if (!response.ok) {
+        const detail = await response.text().catch(() => "");
+        throw new CapabilityError(
+          "sandbox-runtime",
+          `Local sandbox refused execution (${response.status})`,
+          {
+            suggestion: "Start the Rust sandbox service or route this task to a configured remote provider.",
+            metadata: { detail },
+            statusCode: response.status
+          }
+        );
+      }
+      const result = await response.json();
+      await appendSandboxDebug({
+        type: "exec",
+        provider: "local_mac",
+        command: request.cmd,
+        result
+      });
+      return result;
+    },
+    async doctor() {
+      try {
+        const result = await this.exec({ cmd: "echo sandbox ok" });
+        return { provider: "local_mac", ok: result.exitCode === 0 };
+      } catch (error) {
+        return {
+          provider: "local_mac",
+          ok: false,
+          suggestion: error instanceof Error ? error.message : "Check local sandbox service reachability."
+        };
+      }
+    }
+  };
+}
+function createRemotePlaceholder(id, envKey) {
+  return {
+    id,
+    async exec() {
+      throw new CapabilityError("sandbox-runtime", `${id} adapter is not configured`, {
+        suggestion: `Set ${envKey} and wire the provider SDK before routing tasks to ${id}.`,
+        statusCode: 503
+      });
+    },
+    async doctor() {
+      return process.env[envKey] ? { provider: id, ok: true } : { provider: id, ok: false, suggestion: `Set ${envKey} to enable ${id}.` };
+    }
+  };
+}
+var SandboxRuntime = class _SandboxRuntime {
+  #providers = /* @__PURE__ */ new Map();
+  #routes;
+  constructor(config = {}) {
+    for (const provider of config.providers ?? [
+      createLocalMacSandbox(),
+      createRemotePlaceholder("remote_code", "SANDBOX_REMOTE_CODE_TOKEN"),
+      createRemotePlaceholder("remote_gpu", "SANDBOX_REMOTE_GPU_TOKEN"),
+      createRemotePlaceholder("remote_workspace", "SANDBOX_REMOTE_WORKSPACE_TOKEN")
+    ]) {
+      this.#providers.set(provider.id, provider);
+    }
+    this.#routes = config.routes ?? [
+      { when: { needsGpu: true }, provider: "remote_gpu" },
+      { when: { durationS: 30 }, provider: "remote_code" },
+      { when: { needsGpu: false }, provider: "local_mac" }
+    ];
+  }
+  static fromConfig(config = {}) {
+    return new _SandboxRuntime(config);
+  }
+  plan(request) {
+    const hints = request.hints ?? {};
+    for (const rule of this.#routes) {
+      const matches = Object.entries(rule.when).every(
+        ([key, value]) => hints[key] === value
+      );
+      if (matches && this.#providers.has(rule.provider)) {
+        return { provider: rule.provider, reason: "matched static routing rule" };
+      }
+    }
+    return {
+      provider: this.#providers.has("local_mac") ? "local_mac" : Array.from(this.#providers.keys())[0] ?? "",
+      reason: "default route"
+    };
+  }
+  async exec(request) {
+    const plan = this.plan(request);
+    const provider = this.#providers.get(plan.provider);
+    if (!provider) {
+      throw new CapabilityError("sandbox-runtime", "No sandbox provider available", {
+        suggestion: "Configure at least one sandbox provider before executing commands.",
+        metadata: plan
+      });
+    }
+    return provider.exec(request);
+  }
+  async doctor() {
+    return Promise.all(Array.from(this.#providers.values()).map((provider) => provider.doctor()));
+  }
+};
+async function readSandboxDebug(limit = 10) {
+  try {
+    const raw = await readFile(sandboxDebugPath(), "utf8");
+    return raw.trim().split("\n").filter(Boolean).slice(-limit).map((line) => JSON.parse(line));
+  } catch {
+    return [];
+  }
+}
+
+export {
+  sandboxDebugPath,
+  createLocalMacSandbox,
+  createRemotePlaceholder,
+  SandboxRuntime,
+  readSandboxDebug
+};
+//# sourceMappingURL=chunk-UGJKHUL3.js.map

package/dist/chunk-UGJKHUL3.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import { mkdir, readFile, writeFile } from \"node:fs/promises\";\nimport { dirname, join } from \"node:path\";\nimport { CapabilityError } from \"@nebutra/errors\";\n\nexport interface ExecHints {\n  readonly durationS?: number;\n  readonly needsGpu?: boolean;\n  readonly networkAccess?: boolean;\n}\n\nexport interface ExecRequest {\n  readonly cmd: string;\n  readonly filesIn?: Record<string, string>;\n  readonly hints?: ExecHints;\n  readonly tenantId?: string;\n  readonly threadId?: string;\n}\n\nexport interface ExecResponse {\n  readonly exitCode: number;\n  readonly aggregatedOutput: string;\n  readonly executedOn: string;\n}\n\nexport interface SandboxHealth {\n  readonly provider: string;\n  readonly ok: boolean;\n  readonly suggestion?: string;\n}\n\nexport interface Sandbox {\n  readonly id: string;\n  exec(request: ExecRequest): Promise<ExecResponse>;\n  doctor(): Promise<SandboxHealth>;\n}\n\nexport interface RouteRule {\n  readonly when: Partial<ExecHints>;\n  readonly provider: string;\n}\n\nexport interface SandboxRuntimeConfig {\n  readonly providers?: readonly Sandbox[];\n  readonly routes?: readonly RouteRule[];\n}\n\nexport function sandboxDebugPath(): string {\n  return join(process.cwd(), \".nebutra\", \"debug\", \"sandbox-runtime.jsonl\");\n}\n\nasync function appendSandboxDebug(entry: Record<string, unknown>): Promise<void> {\n  const path = sandboxDebugPath();\n  await mkdir(dirname(path), { recursive: true });\n  await writeFile(path, `${JSON.stringify({ at: new Date().toISOString(), ...entry })}\\n`, {\n    flag: \"a\",\n  });\n}\n\nexport function createLocalMacSandbox(\n  options: { endpoint?: string; fetch?: typeof fetch } = {},\n): Sandbox {\n  const endpoint =\n    options.endpoint ??\n    process.env.SANDBOX_RUNTIME_LOCAL_URL ??\n    \"http://127.0.0.1:8020/api/v1/sandbox/exec\";\n  const fetchImpl = options.fetch ?? fetch;\n  return {\n    id: \"local_mac\",\n    async exec(request) {\n      const response = await fetchImpl(endpoint, {\n        method: \"POST\",\n        headers: { \"content-type\": \"application/json\" },\n        body: JSON.stringify({\n          tenantId: request.tenantId ?? \"local\",\n          threadId: request.threadId ?? \"local\",\n          command: request.cmd,\n          capabilityPolicy: {\n            kind: \"external_sandbox\",\n            network_access: request.hints?.networkAccess ?? false,\n          },\n        }),\n      });\n      if (!response.ok) {\n        const detail = await response.text().catch(() => \"\");\n        throw new CapabilityError(\n          \"sandbox-runtime\",\n          `Local sandbox refused execution (${response.status})`,\n          {\n            suggestion:\n              \"Start the Rust sandbox service or route this task to a configured remote provider.\",\n            metadata: { detail },\n            statusCode: response.status,\n          },\n        );\n      }\n      const result = (await response.json()) as ExecResponse;\n      await appendSandboxDebug({\n        type: \"exec\",\n        provider: \"local_mac\",\n        command: request.cmd,\n        result,\n      });\n      return result;\n    },\n    async doctor() {\n      try {\n        const result = await this.exec({ cmd: \"echo sandbox ok\" });\n        return { provider: \"local_mac\", ok: result.exitCode === 0 };\n      } catch (error) {\n        return {\n          provider: \"local_mac\",\n          ok: false,\n          suggestion:\n            error instanceof Error ? error.message : \"Check local sandbox service reachability.\",\n        };\n      }\n    },\n  };\n}\n\nexport function createRemotePlaceholder(\n  id: \"remote_code\" | \"remote_gpu\" | \"remote_workspace\",\n  envKey: string,\n): Sandbox {\n  return {\n    id,\n    async exec() {\n      throw new CapabilityError(\"sandbox-runtime\", `${id} adapter is not configured`, {\n        suggestion: `Set ${envKey} and wire the provider SDK before routing tasks to ${id}.`,\n        statusCode: 503,\n      });\n    },\n    async doctor() {\n      return process.env[envKey]\n        ? { provider: id, ok: true }\n        : { provider: id, ok: false, suggestion: `Set ${envKey} to enable ${id}.` };\n    },\n  };\n}\n\nexport class SandboxRuntime {\n  readonly #providers = new Map<string, Sandbox>();\n  readonly #routes: readonly RouteRule[];\n\n  constructor(config: SandboxRuntimeConfig = {}) {\n    for (const provider of config.providers ?? [\n      createLocalMacSandbox(),\n      createRemotePlaceholder(\"remote_code\", \"SANDBOX_REMOTE_CODE_TOKEN\"),\n      createRemotePlaceholder(\"remote_gpu\", \"SANDBOX_REMOTE_GPU_TOKEN\"),\n      createRemotePlaceholder(\"remote_workspace\", \"SANDBOX_REMOTE_WORKSPACE_TOKEN\"),\n    ]) {\n      this.#providers.set(provider.id, provider);\n    }\n    this.#routes = config.routes ?? [\n      { when: { needsGpu: true }, provider: \"remote_gpu\" },\n      { when: { durationS: 30 }, provider: \"remote_code\" },\n      { when: { needsGpu: false }, provider: \"local_mac\" },\n    ];\n  }\n\n  static fromConfig(config: SandboxRuntimeConfig = {}): SandboxRuntime {\n    return new SandboxRuntime(config);\n  }\n\n  plan(request: ExecRequest): { provider: string; reason: string } {\n    const hints = request.hints ?? {};\n    for (const rule of this.#routes) {\n      const matches = Object.entries(rule.when).every(\n        ([key, value]) => hints[key as keyof ExecHints] === value,\n      );\n      if (matches && this.#providers.has(rule.provider)) {\n        return { provider: rule.provider, reason: \"matched static routing rule\" };\n      }\n    }\n    return {\n      provider: this.#providers.has(\"local_mac\")\n        ? \"local_mac\"\n        : (Array.from(this.#providers.keys())[0] ?? \"\"),\n      reason: \"default route\",\n    };\n  }\n\n  async exec(request: ExecRequest): Promise<ExecResponse> {\n    const plan = this.plan(request);\n    const provider = this.#providers.get(plan.provider);\n    if (!provider) {\n      throw new CapabilityError(\"sandbox-runtime\", \"No sandbox provider available\", {\n        suggestion: \"Configure at least one sandbox provider before executing commands.\",\n        metadata: plan,\n      });\n    }\n    return provider.exec(request);\n  }\n\n  async doctor(): Promise<SandboxHealth[]> {\n    return Promise.all(Array.from(this.#providers.values()).map((provider) => provider.doctor()));\n  }\n}\n\nexport async function readSandboxDebug(limit = 10): Promise<unknown[]> {\n  try {\n    const raw = await readFile(sandboxDebugPath(), \"utf8\");\n    return raw\n      .trim()\n      .split(\"\\n\")\n      .filter(Boolean)\n      .slice(-limit)\n      .map((line) => JSON.parse(line) as unknown);\n  } catch {\n    return [];\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/cli.js

@@ -0,0 +1,30 @@
+import {
+  SandboxRuntime,
+  readSandboxDebug
+} from "./chunk-UGJKHUL3.js";
+
+// src/cli.ts
+var command = process.argv[2] ?? "doctor";
+var runtime = SandboxRuntime.fromConfig();
+if (command === "doctor") {
+  process.stdout.write(
+    `${JSON.stringify({ capability: "sandbox-runtime", results: await runtime.doctor() }, null, 2)}
+`
+  );
+} else if (command === "debug") {
+  process.stdout.write(
+    `${JSON.stringify({ capability: "sandbox-runtime", entries: await readSandboxDebug() }, null, 2)}
+`
+  );
+} else if (command === "plan") {
+  const task = process.argv.slice(3).join(" ") || "echo sandbox ok";
+  process.stdout.write(
+    `${JSON.stringify({ capability: "sandbox-runtime", task, plan: runtime.plan({ cmd: task }) }, null, 2)}
+`
+  );
+} else {
+  process.stderr.write(`Unknown sandbox-runtime command: ${command}
+`);
+  process.exitCode = 1;
+}
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli.ts"],"sourcesContent":["import { readSandboxDebug, SandboxRuntime } from \"./index\";\n\nconst command = process.argv[2] ?? \"doctor\";\nconst runtime = SandboxRuntime.fromConfig();\n\nif (command === \"doctor\") {\n  process.stdout.write(\n    `${JSON.stringify({ capability: \"sandbox-runtime\", results: await runtime.doctor() }, null, 2)}\\n`,\n  );\n} else if (command === \"debug\") {\n  process.stdout.write(\n    `${JSON.stringify({ capability: \"sandbox-runtime\", entries: await readSandboxDebug() }, null, 2)}\\n`,\n  );\n} else if (command === \"plan\") {\n  const task = process.argv.slice(3).join(\" \") || \"echo sandbox ok\";\n  process.stdout.write(\n    `${JSON.stringify({ capability: \"sandbox-runtime\", task, plan: runtime.plan({ cmd: task }) }, null, 2)}\\n`,\n  );\n} else {\n  process.stderr.write(`Unknown sandbox-runtime command: ${command}\\n`);\n  process.exitCode = 1;\n}\n"],"mappings":";;;;;;AAEA,IAAM,UAAU,QAAQ,KAAK,CAAC,KAAK;AACnC,IAAM,UAAU,eAAe,WAAW;AAE1C,IAAI,YAAY,UAAU;AACxB,UAAQ,OAAO;AAAA,IACb,GAAG,KAAK,UAAU,EAAE,YAAY,mBAAmB,SAAS,MAAM,QAAQ,OAAO,EAAE,GAAG,MAAM,CAAC,CAAC;AAAA;AAAA,EAChG;AACF,WAAW,YAAY,SAAS;AAC9B,UAAQ,OAAO;AAAA,IACb,GAAG,KAAK,UAAU,EAAE,YAAY,mBAAmB,SAAS,MAAM,iBAAiB,EAAE,GAAG,MAAM,CAAC,CAAC;AAAA;AAAA,EAClG;AACF,WAAW,YAAY,QAAQ;AAC7B,QAAM,OAAO,QAAQ,KAAK,MAAM,CAAC,EAAE,KAAK,GAAG,KAAK;AAChD,UAAQ,OAAO;AAAA,IACb,GAAG,KAAK,UAAU,EAAE,YAAY,mBAAmB,MAAM,MAAM,QAAQ,KAAK,EAAE,KAAK,KAAK,CAAC,EAAE,GAAG,MAAM,CAAC,CAAC;AAAA;AAAA,EACxG;AACF,OAAO;AACL,UAAQ,OAAO,MAAM,oCAAoC,OAAO;AAAA,CAAI;AACpE,UAAQ,WAAW;AACrB;","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+interface ExecHints {
+    readonly durationS?: number;
+    readonly needsGpu?: boolean;
+    readonly networkAccess?: boolean;
+}
+interface ExecRequest {
+    readonly cmd: string;
+    readonly filesIn?: Record<string, string>;
+    readonly hints?: ExecHints;
+    readonly tenantId?: string;
+    readonly threadId?: string;
+}
+interface ExecResponse {
+    readonly exitCode: number;
+    readonly aggregatedOutput: string;
+    readonly executedOn: string;
+}
+interface SandboxHealth {
+    readonly provider: string;
+    readonly ok: boolean;
+    readonly suggestion?: string;
+}
+interface Sandbox {
+    readonly id: string;
+    exec(request: ExecRequest): Promise<ExecResponse>;
+    doctor(): Promise<SandboxHealth>;
+}
+interface RouteRule {
+    readonly when: Partial<ExecHints>;
+    readonly provider: string;
+}
+interface SandboxRuntimeConfig {
+    readonly providers?: readonly Sandbox[];
+    readonly routes?: readonly RouteRule[];
+}
+declare function sandboxDebugPath(): string;
+declare function createLocalMacSandbox(options?: {
+    endpoint?: string;
+    fetch?: typeof fetch;
+}): Sandbox;
+declare function createRemotePlaceholder(id: "remote_code" | "remote_gpu" | "remote_workspace", envKey: string): Sandbox;
+declare class SandboxRuntime {
+    #private;
+    constructor(config?: SandboxRuntimeConfig);
+    static fromConfig(config?: SandboxRuntimeConfig): SandboxRuntime;
+    plan(request: ExecRequest): {
+        provider: string;
+        reason: string;
+    };
+    exec(request: ExecRequest): Promise<ExecResponse>;
+    doctor(): Promise<SandboxHealth[]>;
+}
+declare function readSandboxDebug(limit?: number): Promise<unknown[]>;
+
+export { type ExecHints, type ExecRequest, type ExecResponse, type RouteRule, type Sandbox, type SandboxHealth, SandboxRuntime, type SandboxRuntimeConfig, createLocalMacSandbox, createRemotePlaceholder, readSandboxDebug, sandboxDebugPath };

package/dist/index.js

@@ -0,0 +1,15 @@
+import {
+  SandboxRuntime,
+  createLocalMacSandbox,
+  createRemotePlaceholder,
+  readSandboxDebug,
+  sandboxDebugPath
+} from "./chunk-UGJKHUL3.js";
+export {
+  SandboxRuntime,
+  createLocalMacSandbox,
+  createRemotePlaceholder,
+  readSandboxDebug,
+  sandboxDebugPath
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/examples/doctor.ts

@@ -0,0 +1,6 @@
+import { SandboxRuntime } from "../src/index";
+
+const runtime = SandboxRuntime.fromConfig();
+const health = await runtime.doctor();
+
+process.stdout.write(`${JSON.stringify(health, null, 2)}\n`);

package/examples/dry-run-plan.ts

@@ -0,0 +1,9 @@
+import { SandboxRuntime } from "../src/index";
+
+const runtime = SandboxRuntime.fromConfig();
+const plan = runtime.plan({
+  cmd: "echo sandbox ok",
+  hints: { needsGpu: false, durationS: 1 },
+});
+
+process.stdout.write(`${JSON.stringify(plan, null, 2)}\n`);

package/examples/local-echo.ts

@@ -0,0 +1,11 @@
+import { SandboxRuntime } from "../src/index";
+
+const runtime = SandboxRuntime.fromConfig();
+const result = await runtime.exec({
+  cmd: "echo sandbox ok",
+  hints: { needsGpu: false },
+  tenantId: "local",
+  threadId: "example",
+});
+
+process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@nebutra/sandbox-runtime",
+  "version": "0.1.0",
+  "description": "Unified sandbox runtime router for local and remote execution providers",
+  "private": false,
+  "license": "MIT",
+  "type": "module",
+  "nebutra": {
+    "featureId": "sandbox-runtime",
+    "category": "ai",
+    "summary": "Sandbox trait, provider router, doctor, and debug tools"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@nebutra/errors": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.15",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.4"
+  },
+  "homepage": "https://github.com/Nebutra/Nebutra-Sailor/tree/main/packages/ai/sandbox-runtime#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Nebutra/Nebutra-Sailor.git",
+    "directory": "packages/ai/sandbox-runtime"
+  },
+  "bugs": {
+    "url": "https://github.com/Nebutra/Nebutra-Sailor/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,22 @@
+import { readSandboxDebug, SandboxRuntime } from "./index";
+
+const command = process.argv[2] ?? "doctor";
+const runtime = SandboxRuntime.fromConfig();
+
+if (command === "doctor") {
+  process.stdout.write(
+    `${JSON.stringify({ capability: "sandbox-runtime", results: await runtime.doctor() }, null, 2)}\n`,
+  );
+} else if (command === "debug") {
+  process.stdout.write(
+    `${JSON.stringify({ capability: "sandbox-runtime", entries: await readSandboxDebug() }, null, 2)}\n`,
+  );
+} else if (command === "plan") {
+  const task = process.argv.slice(3).join(" ") || "echo sandbox ok";
+  process.stdout.write(
+    `${JSON.stringify({ capability: "sandbox-runtime", task, plan: runtime.plan({ cmd: task }) }, null, 2)}\n`,
+  );
+} else {
+  process.stderr.write(`Unknown sandbox-runtime command: ${command}\n`);
+  process.exitCode = 1;
+}

package/src/index.test.ts

@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vitest";
+import { createLocalMacSandbox, SandboxRuntime } from "./index";
+
+describe("SandboxRuntime", () => {
+  it("plans deterministic provider routing without asking a model", () => {
+    const runtime = SandboxRuntime.fromConfig({
+      providers: [createLocalMacSandbox({ fetch: fetch })],
+      routes: [{ when: { needsGpu: false }, provider: "local_mac" }],
+    });
+
+    expect(runtime.plan({ cmd: "echo sandbox ok", hints: { needsGpu: false } })).toMatchObject({
+      provider: "local_mac",
+      reason: expect.stringContaining("rule"),
+    });
+  });
+
+  it("delegates execution to the local isolator endpoint", async () => {
+    const runtime = SandboxRuntime.fromConfig({
+      providers: [
+        createLocalMacSandbox({
+          fetch: async () =>
+            new Response(
+              JSON.stringify({
+                exitCode: 0,
+                aggregatedOutput: "sandbox ok\n",
+                executedOn: "local_mac",
+              }),
+              {
+                status: 200,
+              },
+            ),
+        }),
+      ],
+    });
+
+    await expect(runtime.exec({ cmd: "echo sandbox ok" })).resolves.toMatchObject({
+      exitCode: 0,
+      executedOn: "local_mac",
+    });
+  });
+});

package/src/index.ts

@@ -0,0 +1,212 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { CapabilityError } from "@nebutra/errors";
+
+export interface ExecHints {
+  readonly durationS?: number;
+  readonly needsGpu?: boolean;
+  readonly networkAccess?: boolean;
+}
+
+export interface ExecRequest {
+  readonly cmd: string;
+  readonly filesIn?: Record<string, string>;
+  readonly hints?: ExecHints;
+  readonly tenantId?: string;
+  readonly threadId?: string;
+}
+
+export interface ExecResponse {
+  readonly exitCode: number;
+  readonly aggregatedOutput: string;
+  readonly executedOn: string;
+}
+
+export interface SandboxHealth {
+  readonly provider: string;
+  readonly ok: boolean;
+  readonly suggestion?: string;
+}
+
+export interface Sandbox {
+  readonly id: string;
+  exec(request: ExecRequest): Promise<ExecResponse>;
+  doctor(): Promise<SandboxHealth>;
+}
+
+export interface RouteRule {
+  readonly when: Partial<ExecHints>;
+  readonly provider: string;
+}
+
+export interface SandboxRuntimeConfig {
+  readonly providers?: readonly Sandbox[];
+  readonly routes?: readonly RouteRule[];
+}
+
+export function sandboxDebugPath(): string {
+  return join(process.cwd(), ".nebutra", "debug", "sandbox-runtime.jsonl");
+}
+
+async function appendSandboxDebug(entry: Record<string, unknown>): Promise<void> {
+  const path = sandboxDebugPath();
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify({ at: new Date().toISOString(), ...entry })}\n`, {
+    flag: "a",
+  });
+}
+
+export function createLocalMacSandbox(
+  options: { endpoint?: string; fetch?: typeof fetch } = {},
+): Sandbox {
+  const endpoint =
+    options.endpoint ??
+    process.env.SANDBOX_RUNTIME_LOCAL_URL ??
+    "http://127.0.0.1:8020/api/v1/sandbox/exec";
+  const fetchImpl = options.fetch ?? fetch;
+  return {
+    id: "local_mac",
+    async exec(request) {
+      const response = await fetchImpl(endpoint, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          tenantId: request.tenantId ?? "local",
+          threadId: request.threadId ?? "local",
+          command: request.cmd,
+          capabilityPolicy: {
+            kind: "external_sandbox",
+            network_access: request.hints?.networkAccess ?? false,
+          },
+        }),
+      });
+      if (!response.ok) {
+        const detail = await response.text().catch(() => "");
+        throw new CapabilityError(
+          "sandbox-runtime",
+          `Local sandbox refused execution (${response.status})`,
+          {
+            suggestion:
+              "Start the Rust sandbox service or route this task to a configured remote provider.",
+            metadata: { detail },
+            statusCode: response.status,
+          },
+        );
+      }
+      const result = (await response.json()) as ExecResponse;
+      await appendSandboxDebug({
+        type: "exec",
+        provider: "local_mac",
+        command: request.cmd,
+        result,
+      });
+      return result;
+    },
+    async doctor() {
+      try {
+        const result = await this.exec({ cmd: "echo sandbox ok" });
+        return { provider: "local_mac", ok: result.exitCode === 0 };
+      } catch (error) {
+        return {
+          provider: "local_mac",
+          ok: false,
+          suggestion:
+            error instanceof Error ? error.message : "Check local sandbox service reachability.",
+        };
+      }
+    },
+  };
+}
+
+export function createRemotePlaceholder(
+  id: "remote_code" | "remote_gpu" | "remote_workspace",
+  envKey: string,
+): Sandbox {
+  return {
+    id,
+    async exec() {
+      throw new CapabilityError("sandbox-runtime", `${id} adapter is not configured`, {
+        suggestion: `Set ${envKey} and wire the provider SDK before routing tasks to ${id}.`,
+        statusCode: 503,
+      });
+    },
+    async doctor() {
+      return process.env[envKey]
+        ? { provider: id, ok: true }
+        : { provider: id, ok: false, suggestion: `Set ${envKey} to enable ${id}.` };
+    },
+  };
+}
+
+export class SandboxRuntime {
+  readonly #providers = new Map<string, Sandbox>();
+  readonly #routes: readonly RouteRule[];
+
+  constructor(config: SandboxRuntimeConfig = {}) {
+    for (const provider of config.providers ?? [
+      createLocalMacSandbox(),
+      createRemotePlaceholder("remote_code", "SANDBOX_REMOTE_CODE_TOKEN"),
+      createRemotePlaceholder("remote_gpu", "SANDBOX_REMOTE_GPU_TOKEN"),
+      createRemotePlaceholder("remote_workspace", "SANDBOX_REMOTE_WORKSPACE_TOKEN"),
+    ]) {
+      this.#providers.set(provider.id, provider);
+    }
+    this.#routes = config.routes ?? [
+      { when: { needsGpu: true }, provider: "remote_gpu" },
+      { when: { durationS: 30 }, provider: "remote_code" },
+      { when: { needsGpu: false }, provider: "local_mac" },
+    ];
+  }
+
+  static fromConfig(config: SandboxRuntimeConfig = {}): SandboxRuntime {
+    return new SandboxRuntime(config);
+  }
+
+  plan(request: ExecRequest): { provider: string; reason: string } {
+    const hints = request.hints ?? {};
+    for (const rule of this.#routes) {
+      const matches = Object.entries(rule.when).every(
+        ([key, value]) => hints[key as keyof ExecHints] === value,
+      );
+      if (matches && this.#providers.has(rule.provider)) {
+        return { provider: rule.provider, reason: "matched static routing rule" };
+      }
+    }
+    return {
+      provider: this.#providers.has("local_mac")
+        ? "local_mac"
+        : (Array.from(this.#providers.keys())[0] ?? ""),
+      reason: "default route",
+    };
+  }
+
+  async exec(request: ExecRequest): Promise<ExecResponse> {
+    const plan = this.plan(request);
+    const provider = this.#providers.get(plan.provider);
+    if (!provider) {
+      throw new CapabilityError("sandbox-runtime", "No sandbox provider available", {
+        suggestion: "Configure at least one sandbox provider before executing commands.",
+        metadata: plan,
+      });
+    }
+    return provider.exec(request);
+  }
+
+  async doctor(): Promise<SandboxHealth[]> {
+    return Promise.all(Array.from(this.#providers.values()).map((provider) => provider.doctor()));
+  }
+}
+
+export async function readSandboxDebug(limit = 10): Promise<unknown[]> {
+  try {
+    const raw = await readFile(sandboxDebugPath(), "utf8");
+    return raw
+      .trim()
+      .split("\n")
+      .filter(Boolean)
+      .slice(-limit)
+      .map((line) => JSON.parse(line) as unknown);
+  } catch {
+    return [];
+  }
+}

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "target": "esnext",
+    "types": ["node"],
+    "incremental": false
+  },
+  "include": ["src", "examples"],
+  "exclude": ["node_modules", "dist"]
+}

package/tsup.config.ts

@@ -0,0 +1,11 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: ["src/index.ts", "src/cli.ts"],
+  format: ["esm"],
+  dts: true,
+  sourcemap: true,
+  clean: true,
+  target: "es2022",
+  external: ["@nebutra/errors"],
+});