@nebutra/sandbox-runtime 0.1.1 → 0.1.3

package/README.md

@@ -0,0 +1,78 @@
+# @nebutra/sandbox-runtime
+
+Unified sandbox runtime router for local and remote execution providers.
+
+This package defines the domain-neutral sandbox contract used by Nebutra
+execution packages. It routes requests to configured providers, exposes provider
+health checks, and records debug events for execution troubleshooting.
+
+## Installation
+
+```bash
+pnpm add @nebutra/sandbox-runtime
+```
+
+## Usage
+
+```ts
+import { SandboxRuntime } from "@nebutra/sandbox-runtime";
+
+const runtime = SandboxRuntime.fromConfig();
+
+const result = await runtime.exec({
+  cmd: "echo sandbox ok",
+  tenantId: "org_123",
+  threadId: "thread_123",
+  hints: {
+    networkAccess: false,
+    needsGpu: false,
+  },
+});
+```
+
+## Providers
+
+Default providers:
+
+| Provider | Behavior |
+| --- | --- |
+| `local_mac` | Calls the local sandbox service at `SANDBOX_RUNTIME_LOCAL_URL` or `http://127.0.0.1:8020/api/v1/sandbox/exec` |
+| `remote_code` | Placeholder provider gated by `SANDBOX_REMOTE_CODE_TOKEN` |
+| `remote_gpu` | Placeholder provider gated by `SANDBOX_REMOTE_GPU_TOKEN` |
+| `remote_workspace` | Placeholder provider gated by `SANDBOX_REMOTE_WORKSPACE_TOKEN` |
+
+Remote placeholders intentionally throw until a provider SDK is configured by
+the host application.
+
+## Routing
+
+```ts
+const runtime = SandboxRuntime.fromConfig({
+  routes: [
+    { when: { needsGpu: true }, provider: "remote_gpu" },
+    { when: { durationS: 30 }, provider: "remote_code" },
+    { when: { needsGpu: false }, provider: "local_mac" },
+  ],
+});
+
+const plan = runtime.plan({ cmd: "pnpm test", hints: { needsGpu: false } });
+```
+
+The first matching static route wins. If no route matches, the runtime falls
+back to `local_mac` when it is configured.
+
+## API
+
+| Export | Description |
+| --- | --- |
+| `SandboxRuntime` | Provider registry, planner, executor, and doctor |
+| `createLocalMacSandbox()` | Local sandbox-service adapter |
+| `createRemotePlaceholder(id, envKey)` | Explicit placeholder for remote providers |
+| `sandboxDebugPath()` | Debug path helper |
+| `readSandboxDebug(limit)` | Read sandbox debug events |
+| `ExecRequest` / `ExecResponse` | Execution request and response contracts |
+| `Sandbox` / `SandboxHealth` | Provider interface and health shape |
+
+## License
+
+MIT

package/dist/{chunk-5TXS6ZSQ.js → chunk-6UZA3GQP.js}

@@ -5,6 +5,8 @@ import {
   readCapabilityDebug
 } from "@nebutra/capability-kit/debug";
 import { CapabilityError } from "@nebutra/errors";
+import pLimit from "p-limit";
+var SANDBOX_DOCTOR_CONCURRENCY = 4;
 function sandboxDebugPath() {
   return capabilityDebugPath("sandbox-runtime");
 }
@@ -127,7 +129,10 @@ var SandboxRuntime = class _SandboxRuntime {
     return provider.exec(request);
   }
   async doctor() {
-    return Promise.all(Array.from(this.#providers.values()).map((provider) => provider.doctor()));
+    const limit = pLimit(SANDBOX_DOCTOR_CONCURRENCY);
+    return Promise.all(
+      Array.from(this.#providers.values()).map((provider) => limit(() => provider.doctor()))
+    );
   }
 };
 async function readSandboxDebug(limit = 10) {
@@ -141,4 +146,4 @@ export {
   SandboxRuntime,
   readSandboxDebug
 };
-//# sourceMappingURL=chunk-5TXS6ZSQ.js.map
+//# sourceMappingURL=chunk-6UZA3GQP.js.map

package/dist/chunk-6UZA3GQP.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import {\n  appendCapabilityDebug,\n  capabilityDebugPath,\n  readCapabilityDebug,\n} from \"@nebutra/capability-kit/debug\";\nimport { CapabilityError } from \"@nebutra/errors\";\nimport pLimit from \"p-limit\";\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\nconst SANDBOX_DOCTOR_CONCURRENCY = 4;\n\nexport function sandboxDebugPath(): string {\n  return capabilityDebugPath(\"sandbox-runtime\");\n}\n\nasync function appendSandboxDebug(entry: Record<string, unknown>): Promise<void> {\n  await appendCapabilityDebug(\"sandbox-runtime\", entry);\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    const limit = pLimit(SANDBOX_DOCTOR_CONCURRENCY);\n    return Promise.all(\n      Array.from(this.#providers.values()).map((provider) => limit(() => provider.doctor())),\n    );\n  }\n}\n\nexport async function readSandboxDebug(limit = 10): Promise<unknown[]> {\n  return readCapabilityDebug(\"sandbox-runtime\", { limit });\n}\n"],"mappings":"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","names":[]}

package/dist/cli.js

@@ -1,7 +1,7 @@
 import {
   SandboxRuntime,
   readSandboxDebug
-} from "./chunk-5TXS6ZSQ.js";
+} from "./chunk-6UZA3GQP.js";
 
 // src/cli.ts
 var command = process.argv[2] ?? "doctor";

package/dist/index.js

@@ -4,7 +4,7 @@ import {
   createRemotePlaceholder,
   readSandboxDebug,
   sandboxDebugPath
-} from "./chunk-5TXS6ZSQ.js";
+} from "./chunk-6UZA3GQP.js";
 export {
   SandboxRuntime,
   createLocalMacSandbox,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebutra/sandbox-runtime",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Unified sandbox runtime router for local and remote execution providers",
   "private": false,
   "license": "MIT",
@@ -11,20 +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": {
-    "@nebutra/capability-kit": "0.2.1",
-    "@nebutra/errors": "0.1.1"
+    "@nebutra/capability-kit": "workspace:*",
+    "@nebutra/errors": "workspace:*",
+    "p-limit": "^7.3.0"
   },
   "devDependencies": {
-    "@types/node": "^22.19.15",
-    "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": {
@@ -38,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 +0,0 @@
-{"at":"2026-05-19T08:15:00.536Z","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.1 build /home/runner/work/Nebutra-Sailor/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: /home/runner/work/Nebutra-Sailor/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-5TXS6ZSQ.js     4.66 KB
-ESM dist/cli.js.map            1.56 KB
-ESM dist/index.js.map          71.00 B
-ESM dist/chunk-5TXS6ZSQ.js.map 9.32 KB
-ESM ⚡️ Build success in 81ms
-DTS Build start
-DTS ⚡️ Build success in 10574ms
-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 /home/runner/work/Nebutra-Sailor/Nebutra-Sailor/packages/ai/sandbox-runtime
-> vitest run
-
-
- RUN  v4.1.4 /home/runner/work/Nebutra-Sailor/Nebutra-Sailor/packages/ai/sandbox-runtime
-
- ✓ src/index.test.ts (2 tests) 263ms
-
- Test Files  1 passed (1)
-      Tests  2 passed (2)
-   Start at  08:14:59
-   Duration  1.35s (transform 376ms, setup 0ms, import 442ms, tests 263ms, environment 0ms)
-

package/.turbo/turbo-typecheck.log

@@ -1,4 +0,0 @@
-
-> @nebutra/sandbox-runtime@0.1.1 typecheck /home/runner/work/Nebutra-Sailor/Nebutra-Sailor/packages/ai/sandbox-runtime
-> tsc --noEmit
-

package/dist/chunk-5TXS6ZSQ.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import {\n  appendCapabilityDebug,\n  capabilityDebugPath,\n  readCapabilityDebug,\n} from \"@nebutra/capability-kit/debug\";\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 capabilityDebugPath(\"sandbox-runtime\");\n}\n\nasync function appendSandboxDebug(entry: Record<string, unknown>): Promise<void> {\n  await appendCapabilityDebug(\"sandbox-runtime\", entry);\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  return readCapabilityDebug(\"sandbox-runtime\", { limit });\n}\n"],"mappings":";AAAA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OACK;AACP,SAAS,uBAAuB;AA4CzB,SAAS,mBAA2B;AACzC,SAAO,oBAAoB,iBAAiB;AAC9C;AAEA,eAAe,mBAAmB,OAA+C;AAC/E,QAAM,sBAAsB,mBAAmB,KAAK;AACtD;AAEO,SAAS,sBACd,UAAuD,CAAC,GAC/C;AACT,QAAM,WACJ,QAAQ,YACR,QAAQ,IAAI,6BACZ;AACF,QAAM,YAAY,QAAQ,SAAS;AACnC,SAAO;AAAA,IACL,IAAI;AAAA,IACJ,MAAM,KAAK,SAAS;AAClB,YAAM,WAAW,MAAM,UAAU,UAAU;AAAA,QACzC,QAAQ;AAAA,QACR,SAAS,EAAE,gBAAgB,mBAAmB;AAAA,QAC9C,MAAM,KAAK,UAAU;AAAA,UACnB,UAAU,QAAQ,YAAY;AAAA,UAC9B,UAAU,QAAQ,YAAY;AAAA,UAC9B,SAAS,QAAQ;AAAA,UACjB,kBAAkB;AAAA,YAChB,MAAM;AAAA,YACN,gBAAgB,QAAQ,OAAO,iBAAiB;AAAA,UAClD;AAAA,QACF,CAAC;AAAA,MACH,CAAC;AACD,UAAI,CAAC,SAAS,IAAI;AAChB,cAAM,SAAS,MAAM,SAAS,KAAK,EAAE,MAAM,MAAM,EAAE;AACnD,cAAM,IAAI;AAAA,UACR;AAAA,UACA,oCAAoC,SAAS,MAAM;AAAA,UACnD;AAAA,YACE,YACE;AAAA,YACF,UAAU,EAAE,OAAO;AAAA,YACnB,YAAY,SAAS;AAAA,UACvB;AAAA,QACF;AAAA,MACF;AACA,YAAM,SAAU,MAAM,SAAS,KAAK;AACpC,YAAM,mBAAmB;AAAA,QACvB,MAAM;AAAA,QACN,UAAU;AAAA,QACV,SAAS,QAAQ;AAAA,QACjB;AAAA,MACF,CAAC;AACD,aAAO;AAAA,IACT;AAAA,IACA,MAAM,SAAS;AACb,UAAI;AACF,cAAM,SAAS,MAAM,KAAK,KAAK,EAAE,KAAK,kBAAkB,CAAC;AACzD,eAAO,EAAE,UAAU,aAAa,IAAI,OAAO,aAAa,EAAE;AAAA,MAC5D,SAAS,OAAO;AACd,eAAO;AAAA,UACL,UAAU;AAAA,UACV,IAAI;AAAA,UACJ,YACE,iBAAiB,QAAQ,MAAM,UAAU;AAAA,QAC7C;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACF;AAEO,SAAS,wBACd,IACA,QACS;AACT,SAAO;AAAA,IACL;AAAA,IACA,MAAM,OAAO;AACX,YAAM,IAAI,gBAAgB,mBAAmB,GAAG,EAAE,8BAA8B;AAAA,QAC9E,YAAY,OAAO,MAAM,sDAAsD,EAAE;AAAA,QACjF,YAAY;AAAA,MACd,CAAC;AAAA,IACH;AAAA,IACA,MAAM,SAAS;AACb,aAAO,QAAQ,IAAI,MAAM,IACrB,EAAE,UAAU,IAAI,IAAI,KAAK,IACzB,EAAE,UAAU,IAAI,IAAI,OAAO,YAAY,OAAO,MAAM,cAAc,EAAE,IAAI;AAAA,IAC9E;AAAA,EACF;AACF;AAEO,IAAM,iBAAN,MAAM,gBAAe;AAAA,EACjB,aAAa,oBAAI,IAAqB;AAAA,EACtC;AAAA,EAET,YAAY,SAA+B,CAAC,GAAG;AAC7C,eAAW,YAAY,OAAO,aAAa;AAAA,MACzC,sBAAsB;AAAA,MACtB,wBAAwB,eAAe,2BAA2B;AAAA,MAClE,wBAAwB,cAAc,0BAA0B;AAAA,MAChE,wBAAwB,oBAAoB,gCAAgC;AAAA,IAC9E,GAAG;AACD,WAAK,WAAW,IAAI,SAAS,IAAI,QAAQ;AAAA,IAC3C;AACA,SAAK,UAAU,OAAO,UAAU;AAAA,MAC9B,EAAE,MAAM,EAAE,UAAU,KAAK,GAAG,UAAU,aAAa;AAAA,MACnD,EAAE,MAAM,EAAE,WAAW,GAAG,GAAG,UAAU,cAAc;AAAA,MACnD,EAAE,MAAM,EAAE,UAAU,MAAM,GAAG,UAAU,YAAY;AAAA,IACrD;AAAA,EACF;AAAA,EAEA,OAAO,WAAW,SAA+B,CAAC,GAAmB;AACnE,WAAO,IAAI,gBAAe,MAAM;AAAA,EAClC;AAAA,EAEA,KAAK,SAA4D;AAC/D,UAAM,QAAQ,QAAQ,SAAS,CAAC;AAChC,eAAW,QAAQ,KAAK,SAAS;AAC/B,YAAM,UAAU,OAAO,QAAQ,KAAK,IAAI,EAAE;AAAA,QACxC,CAAC,CAAC,KAAK,KAAK,MAAM,MAAM,GAAsB,MAAM;AAAA,MACtD;AACA,UAAI,WAAW,KAAK,WAAW,IAAI,KAAK,QAAQ,GAAG;AACjD,eAAO,EAAE,UAAU,KAAK,UAAU,QAAQ,8BAA8B;AAAA,MAC1E;AAAA,IACF;AACA,WAAO;AAAA,MACL,UAAU,KAAK,WAAW,IAAI,WAAW,IACrC,cACC,MAAM,KAAK,KAAK,WAAW,KAAK,CAAC,EAAE,CAAC,KAAK;AAAA,MAC9C,QAAQ;AAAA,IACV;AAAA,EACF;AAAA,EAEA,MAAM,KAAK,SAA6C;AACtD,UAAM,OAAO,KAAK,KAAK,OAAO;AAC9B,UAAM,WAAW,KAAK,WAAW,IAAI,KAAK,QAAQ;AAClD,QAAI,CAAC,UAAU;AACb,YAAM,IAAI,gBAAgB,mBAAmB,iCAAiC;AAAA,QAC5E,YAAY;AAAA,QACZ,UAAU;AAAA,MACZ,CAAC;AAAA,IACH;AACA,WAAO,SAAS,KAAK,OAAO;AAAA,EAC9B;AAAA,EAEA,MAAM,SAAmC;AACvC,WAAO,QAAQ,IAAI,MAAM,KAAK,KAAK,WAAW,OAAO,CAAC,EAAE,IAAI,CAAC,aAAa,SAAS,OAAO,CAAC,CAAC;AAAA,EAC9F;AACF;AAEA,eAAsB,iBAAiB,QAAQ,IAAwB;AACrE,SAAO,oBAAoB,mBAAmB,EAAE,MAAM,CAAC;AACzD;","names":[]}

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

@@ -1,201 +0,0 @@
-import {
-  appendCapabilityDebug,
-  capabilityDebugPath,
-  readCapabilityDebug,
-} from "@nebutra/capability-kit/debug";
-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 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[]> {
-    return Promise.all(Array.from(this.#providers.values()).map((provider) => 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"],
-});