@nebutra/sandbox-runtime 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebutra/sandbox-runtime",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Unified sandbox runtime router for local and remote execution providers",
   "private": false,
   "license": "MIT",
@@ -11,21 +11,30 @@
     "surface": "execution-router",
     "summary": "Sandbox trait, provider router, doctor, and debug tools"
   },
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "p-limit": "^7.3.0",
-    "@nebutra/errors": "0.1.2",
-    "@nebutra/capability-kit": "0.2.2"
+    "@nebutra/capability-kit": "workspace:*",
+    "@nebutra/errors": "workspace:*",
+    "p-limit": "^7.3.0"
   },
   "devDependencies": {
-    "@types/node": "^25.9.1",
-    "tsup": "^8.5.1",
-    "typescript": "^5.9.3",
-    "vitest": "^4.1.4"
+    "@types/node": "catalog:",
+    "tsup": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
   },
   "homepage": "https://github.com/Nebutra/Nebutra-Sailor/tree/main/packages/ai/sandbox-runtime#readme",
   "repository": {
@@ -39,9 +48,10 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "tsup",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit"
-  }
-}
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ]
+}

package/.nebutra/debug/sandbox-runtime.jsonl

@@ -1,6 +0,0 @@
-{"at":"2026-05-19T05:44:37.177Z","type":"exec","provider":"local_mac","command":"echo sandbox ok","result":{"exitCode":0,"aggregatedOutput":"sandbox ok\n","executedOn":"local_mac"}}
-{"at":"2026-05-30T20:41:47.727Z","type":"exec","provider":"local_mac","command":"echo sandbox ok","result":{"exitCode":0,"aggregatedOutput":"sandbox ok\n","executedOn":"local_mac"}}
-{"at":"2026-06-05T07:18:37.847Z","type":"exec","provider":"local_mac","command":"echo sandbox ok","result":{"exitCode":0,"aggregatedOutput":"sandbox ok\n","executedOn":"local_mac"}}
-{"at":"2026-06-05T07:19:23.017Z","type":"exec","provider":"local_mac","command":"echo sandbox ok","result":{"exitCode":0,"aggregatedOutput":"sandbox ok\n","executedOn":"local_mac"}}
-{"at":"2026-06-05T07:23:30.124Z","type":"exec","provider":"local_mac","command":"echo sandbox ok","result":{"exitCode":0,"aggregatedOutput":"sandbox ok\n","executedOn":"local_mac"}}
-{"at":"2026-07-01T01:38:32.446Z","type":"exec","provider":"local_mac","command":"echo sandbox ok","result":{"exitCode":0,"aggregatedOutput":"sandbox ok\n","executedOn":"local_mac"}}

package/.turbo/turbo-build.log

@@ -1,22 +0,0 @@
-
-> @nebutra/sandbox-runtime@0.1.2 build /Users/tseka_luk/Documents/Nebutra-SaaS-Lab/Nebutra-Sailor/packages/ai/sandbox-runtime
-> tsup
-
-CLI Building entry: src/cli.ts, src/index.ts
-CLI Using tsconfig: tsconfig.json
-CLI tsup v8.5.1
-CLI Using tsup config: /Users/tseka_luk/Documents/Nebutra-SaaS-Lab/Nebutra-Sailor/packages/ai/sandbox-runtime/tsup.config.ts
-CLI Target: es2022
-CLI Cleaning output folder
-ESM Build start
-ESM dist/cli.js                882.00 B
-ESM dist/index.js              302.00 B
-ESM dist/chunk-6UZA3GQP.js     4.80 KB
-ESM dist/cli.js.map            1.56 KB
-ESM dist/index.js.map          71.00 B
-ESM dist/chunk-6UZA3GQP.js.map 9.55 KB
-ESM ⚡️ Build success in 11ms
-DTS Build start
-DTS ⚡️ Build success in 2124ms
-DTS dist/cli.d.ts   13.00 B
-DTS dist/index.d.ts 1.83 KB

package/.turbo/turbo-test.log

@@ -1,14 +0,0 @@
-
-> @nebutra/sandbox-runtime@0.1.1 test /Users/tseka_luk/Documents/Nebutra-SaaS-Lab/Nebutra-Sailor/packages/ai/sandbox-runtime
-> vitest run
-
-
- RUN  v4.1.4 /Users/tseka_luk/Documents/Nebutra-SaaS-Lab/Nebutra-Sailor/packages/ai/sandbox-runtime
-
- ✓ src/index.test.ts (3 tests) 72ms
-
- Test Files  1 passed (1)
-      Tests  3 passed (3)
-   Start at  09:38:32
-   Duration  332ms (transform 55ms, setup 0ms, import 72ms, tests 72ms, environment 0ms)
-

package/.turbo/turbo-typecheck.log

@@ -1,4 +0,0 @@
-
-> @nebutra/sandbox-runtime@0.1.2 typecheck /Users/tseka_luk/Documents/Nebutra-SaaS-Lab/Nebutra-Sailor/packages/ai/sandbox-runtime
-> tsc --noEmit
-

package/examples/doctor.ts

@@ -1,6 +0,0 @@
-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

@@ -1,9 +0,0 @@
-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

@@ -1,11 +0,0 @@
-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/src/cli.ts

@@ -1,22 +0,0 @@
-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

@@ -1,69 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { createLocalMacSandbox, type Sandbox, 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",
-    });
-  });
-
-  it("caps provider doctor concurrency to avoid burst diagnostics", async () => {
-    let active = 0;
-    let maxActive = 0;
-    const providers = Array.from({ length: 12 }, (_, index): Sandbox => {
-      const id = `sandbox_${index}`;
-      return {
-        id,
-        exec: async () => ({
-          exitCode: 0,
-          aggregatedOutput: "ok",
-          executedOn: id,
-        }),
-        doctor: async () => {
-          active += 1;
-          maxActive = Math.max(maxActive, active);
-          await new Promise((resolve) => setTimeout(resolve, 0));
-          active -= 1;
-          return { provider: id, ok: true };
-        },
-      };
-    });
-
-    const runtime = SandboxRuntime.fromConfig({ providers });
-
-    await expect(runtime.doctor()).resolves.toHaveLength(12);
-    expect(maxActive).toBeLessThanOrEqual(4);
-  });
-});

package/src/index.ts

@@ -1,207 +0,0 @@
-import {
-  appendCapabilityDebug,
-  capabilityDebugPath,
-  readCapabilityDebug,
-} from "@nebutra/capability-kit/debug";
-import { CapabilityError } from "@nebutra/errors";
-import pLimit from "p-limit";
-
-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[];
-}
-
-const SANDBOX_DOCTOR_CONCURRENCY = 4;
-
-export function sandboxDebugPath(): string {
-  return capabilityDebugPath("sandbox-runtime");
-}
-
-async function appendSandboxDebug(entry: Record<string, unknown>): Promise<void> {
-  await appendCapabilityDebug("sandbox-runtime", entry);
-}
-
-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[]> {
-    const limit = pLimit(SANDBOX_DOCTOR_CONCURRENCY);
-    return Promise.all(
-      Array.from(this.#providers.values()).map((provider) => limit(() => provider.doctor())),
-    );
-  }
-}
-
-export async function readSandboxDebug(limit = 10): Promise<unknown[]> {
-  return readCapabilityDebug("sandbox-runtime", { limit });
-}

package/tsconfig.json

@@ -1,12 +0,0 @@
-{
-  "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

@@ -1,11 +0,0 @@
-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"],
-});