@nebutra/code-execution 0.1.1 → 0.1.3

package/README.md

@@ -1,15 +1,78 @@
 # @nebutra/code-execution
 
-Status: WIP — Not yet integrated into any production app.
+Action and observation execution layer backed by `@nebutra/sandbox-runtime`.
 
-`@nebutra/code-execution` owns action/observation execution for shell, read,
-edit-by-diff, git, policy checks, replay, doctor output, and debug inspection.
-It routes process execution through sandbox contracts and returns structured
-observations with suggestions.
+This package turns shell, read, edit-by-diff, git, policy, replay, doctor, and
+debug actions into structured observations. It owns execution behavior, not
+thread state, prompts, model calls, sub-agent scheduling, or UI approval flows.
 
-It does not own Thread/Turn/Item state, prompt generation, model calls,
-sub-agent scheduling, or approval lifecycle. Approval requests are surfaced as
-observations for the runtime or UI to handle.
+## Status: WIP
+
+Experimental public package. The package metadata marks it as not production
+ready yet because:
+
+- notebook kernel execution is adapter-gated
+- remote workspace providers depend on sandbox-runtime configuration
+- approval UI is surfaced as observations and is not wired in this package
+
+Use it as a capability layer behind an application runtime that owns approval,
+tenant, and UI handoff.
+
+## Installation
+
+```bash
+pnpm add @nebutra/code-execution
+```
+
+## Usage
+
+```ts
+import { CodeExecutor } from "@nebutra/code-execution";
+
+const executor = new CodeExecutor({
+  tenantId: "org_123",
+  workspaceRoot: process.cwd(),
+});
+
+const observation = await executor.run({
+  type: "read",
+  path: "README.md",
+});
+```
+
+Shell actions route through `@nebutra/sandbox-runtime`:
+
+```ts
+const result = await executor.run({
+  type: "shell",
+  cmd: "pnpm test",
+  cwd: ".",
+  timeoutS: 30,
+});
+```
+
+## Action Types
+
+| Type | Purpose |
+| --- | --- |
+| `shell` | Execute a command through the configured sandbox runtime |
+| `read` | Read a workspace-relative file, optionally by line range |
+| `edit` | Apply an edit-by-diff request to a workspace-relative file |
+| `git` | Execute supported git operations through the sandbox path |
+| `ipython` | Return an adapter-unavailable observation until a notebook sidecar is configured |
+
+## Observations
+
+The executor returns structured observations instead of raw side effects:
+
+- `shell_output`
+- `file_content`
+- `edit_applied`
+- `error`
+
+Approval requirements are surfaced as `error` observations with the
+`ApprovalRequired` kind. The caller is responsible for asking the user and
+retrying with `approved: true`.
 
 ## Commands
 
@@ -20,10 +83,8 @@ pnpm exec:replay <action_id>
 pnpm exec:policy
 ```
 
-## Examples
+Executable examples live under `examples/`.
 
-Executable examples live under `examples/`:
+## License
 
-- `edit-by-diff.ts`
-- `policy.ts`
-- `shell.ts`
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebutra/code-execution",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Action and observation execution layer backed by sandbox-runtime",
   "private": false,
   "license": "MIT",
@@ -22,20 +22,24 @@
     "category": "ai",
     "summary": "Shell, read, edit-by-diff, policy, replay, 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"
+    }
   },
   "dependencies": {
-    "@nebutra/capability-kit": "0.2.1",
-    "@nebutra/errors": "0.1.1",
-    "@nebutra/event-log": "0.1.1",
-    "@nebutra/execution-policy": "0.1.1",
-    "@nebutra/sandbox-runtime": "0.1.1"
+    "@nebutra/sandbox-runtime": "0.1.4",
+    "@nebutra/capability-kit": "0.2.4",
+    "@nebutra/errors": "0.1.2",
+    "@nebutra/event-log": "0.1.4",
+    "@nebutra/execution-policy": "0.1.4"
   },
   "devDependencies": {
-    "@types/node": "^22.19.15",
+    "@types/node": "^25.9.1",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^4.1.4"
@@ -52,6 +56,12 @@
   "publishConfig": {
     "access": "public"
   },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
   "scripts": {
     "build": "tsup",
     "test": "vitest run",

package/.nebutra/debug/code-execution.jsonl

@@ -1,3 +0,0 @@
-{"at":"2026-05-19T08:15:17.662Z","type":"action","tenantId":"tenant_a","action":{"type":"shell","cmd":"pnpm test","cwd":"/workspace","timeoutS":60,"tenantId":"tenant_a"},"observation":{"type":"shell_output","actionId":"shell_mpccyaa5","stdout":"ran pnpm test for tenant_a","stderr":"","exitCode":0,"durationMs":7,"executedOn":"test_sandbox"}}
-{"at":"2026-05-19T08:15:17.690Z","type":"action","tenantId":"tenant_a","action":{"type":"shell","cmd":"rm -rf build","cwd":"/workspace","tenantId":"tenant_a"},"observation":{"type":"error","actionId":"shell_mpccyab5","kind":"ApprovalRequired","message":"Command requires approval: destructive recursive removal","suggestion":"Ask the user for explicit approval, then retry the action with approved: true."}}
-{"at":"2026-05-19T08:15:17.717Z","type":"action","tenantId":"tenant_a","action":{"type":"edit","path":"main.ts","diff":"--- a/main.ts\n+++ b/main.ts\n@@ -1,2 +1,2 @@\n-const value = 1;\n+const value = 2;\n console.log(value);\n","tenantId":"tenant_a"},"observation":{"type":"edit_applied","actionId":"edit_mpccyaby","path":"main.ts","diff":"--- a/main.ts\n+++ b/main.ts\n@@ -1,2 +1,2 @@\n-const value = 1;\n+const value = 2;\n console.log(value);\n","conflicts":[]}}

package/.turbo/turbo-build.log

@@ -1,22 +0,0 @@
-
-> @nebutra/code-execution@0.1.1 build /home/runner/work/Nebutra-Sailor/Nebutra-Sailor/packages/ai/code-execution
-> 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/code-execution/tsup.config.ts
-CLI Target: es2022
-CLI Cleaning output folder
-ESM Build start
-ESM dist/cli.js                1.59 KB
-ESM dist/index.js              232.00 B
-ESM dist/chunk-LLPO5OG2.js     9.10 KB
-ESM dist/cli.js.map            2.87 KB
-ESM dist/index.js.map          71.00 B
-ESM dist/chunk-LLPO5OG2.js.map 19.58 KB
-ESM ⚡️ Build success in 100ms
-DTS Build start
-DTS ⚡️ Build success in 12500ms
-DTS dist/cli.d.ts   13.00 B
-DTS dist/index.d.ts 3.79 KB

package/.turbo/turbo-test.log

@@ -1,14 +0,0 @@
-
-> @nebutra/code-execution@0.1.1 test /home/runner/work/Nebutra-Sailor/Nebutra-Sailor/packages/ai/code-execution
-> vitest run
-
-
- RUN  v4.1.4 /home/runner/work/Nebutra-Sailor/Nebutra-Sailor/packages/ai/code-execution
-
- ✓ src/index.test.ts (5 tests) 131ms
-
- Test Files  1 passed (1)
-      Tests  5 passed (5)
-   Start at  08:15:16
-   Duration  1.50s (transform 681ms, setup 0ms, import 796ms, tests 131ms, environment 0ms)
-

package/.turbo/turbo-typecheck.log

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

package/examples/edit-by-diff.ts

@@ -1,17 +0,0 @@
-import { CodeExecutor } from "@nebutra/code-execution";
-
-const exec = new CodeExecutor({ tenantId: "local", workspaceRoot: process.cwd() });
-const observation = await exec.run({
-  type: "edit",
-  tenantId: "local",
-  path: "scratch/example.txt",
-  diff: [
-    "--- a/scratch/example.txt",
-    "+++ b/scratch/example.txt",
-    "@@ -1 +1 @@",
-    "-old",
-    "+new",
-    "",
-  ].join("\n"),
-});
-process.stdout.write(`${JSON.stringify(observation, null, 2)}\n`);

package/examples/policy.ts

@@ -1,10 +0,0 @@
-import { CodeExecutor } from "@nebutra/code-execution";
-
-const exec = new CodeExecutor({ tenantId: "local" });
-const observation = await exec.run({
-  type: "shell",
-  tenantId: "local",
-  cwd: process.cwd(),
-  cmd: "git push origin main",
-});
-process.stdout.write(`${JSON.stringify(observation, null, 2)}\n`);

package/examples/shell.ts

@@ -1,11 +0,0 @@
-import { CodeExecutor } from "@nebutra/code-execution";
-
-const exec = new CodeExecutor({ tenantId: "local" });
-const observation = await exec.run({
-  type: "shell",
-  tenantId: "local",
-  cwd: process.cwd(),
-  cmd: "echo sandbox ok",
-  timeoutS: 5,
-});
-process.stdout.write(`${JSON.stringify(observation, null, 2)}\n`);

package/src/cli.ts

@@ -1,44 +0,0 @@
-import { CodeExecutor, readExecutionDebug } from "./index";
-
-const command = process.argv[2] ?? "doctor";
-const exec = new CodeExecutor({ tenantId: process.env.NEBUTRA_TENANT_ID ?? "local" });
-
-if (command === "doctor") {
-  process.stdout.write(`${JSON.stringify(await exec.doctor(), null, 2)}\n`);
-} else if (command === "debug") {
-  process.stdout.write(
-    `${JSON.stringify({ capability: "code-execution", entries: await readExecutionDebug() }, null, 2)}\n`,
-  );
-} else if (command === "policy") {
-  const rules = exec.policy().map((rule) => ({
-    ...rule,
-    match: rule.match instanceof RegExp ? rule.match.source : rule.match,
-  }));
-  process.stdout.write(`${JSON.stringify({ capability: "code-execution", rules }, null, 2)}\n`);
-} else if (command === "replay") {
-  const actionId = process.argv[3];
-  const entries = await readExecutionDebug(process.cwd(), 100);
-  const entry = entries.find((item) => {
-    if (!item || typeof item !== "object") return false;
-    const value = item as { action?: { actionId?: string }; observation?: { actionId?: string } };
-    return value.action?.actionId === actionId || value.observation?.actionId === actionId;
-  });
-  process.stdout.write(
-    `${JSON.stringify(
-      {
-        capability: "code-execution",
-        actionId,
-        replayable: Boolean(entry),
-        entry,
-        suggestion: entry
-          ? "Use the stored action payload as the deterministic replay input."
-          : "Run `pnpm exec:debug` and choose an action id from the recent log.",
-      },
-      null,
-      2,
-    )}\n`,
-  );
-} else {
-  process.stderr.write(`Unknown code-execution command: ${command}\n`);
-  process.exitCode = 1;
-}

package/src/index.test.ts

@@ -1,110 +0,0 @@
-import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { afterEach, describe, expect, it } from "vitest";
-import { CodeExecutor, DefaultPolicy, readExecutionDebug } from "./index";
-
-let root: string | undefined;
-
-afterEach(async () => {
-  if (root) await rm(root, { recursive: true, force: true });
-  root = undefined;
-});
-
-describe("CodeExecutor", () => {
-  it("runs shell actions through sandbox-runtime with tenant context", async () => {
-    const exec = new CodeExecutor({
-      tenantId: "tenant_a",
-      sandboxRuntime: {
-        async exec(request) {
-          return {
-            exitCode: 0,
-            aggregatedOutput: `ran ${request.cmd} for ${request.tenantId}`,
-            executedOn: "test_sandbox",
-          };
-        },
-        async doctor() {
-          return [{ provider: "test_sandbox", ok: true }];
-        },
-      },
-    });
-
-    await expect(
-      exec.run({
-        type: "shell",
-        cmd: "pnpm test",
-        cwd: "/workspace",
-        timeoutS: 60,
-        tenantId: "tenant_a",
-      }),
-    ).resolves.toMatchObject({
-      type: "shell_output",
-      stdout: "ran pnpm test for tenant_a",
-      exitCode: 0,
-      executedOn: "test_sandbox",
-    });
-  });
-
-  it("blocks destructive shell commands until approval is explicit", async () => {
-    const exec = new CodeExecutor({
-      tenantId: "tenant_a",
-      sandboxRuntime: {
-        async exec() {
-          throw new Error("should not run");
-        },
-        async doctor() {
-          return [];
-        },
-      },
-      policy: DefaultPolicy,
-    });
-
-    await expect(
-      exec.run({ type: "shell", cmd: "rm -rf build", cwd: "/workspace", tenantId: "tenant_a" }),
-    ).resolves.toMatchObject({
-      type: "error",
-      kind: "ApprovalRequired",
-      suggestion: expect.stringContaining("approval"),
-    });
-  });
-
-  it("applies edits by unified diff instead of overwrite", async () => {
-    root = await mkdtemp(join(tmpdir(), "code-execution-"));
-    await writeFile(join(root, "main.ts"), "const value = 1;\nconsole.log(value);\n", "utf8");
-    const exec = new CodeExecutor({ tenantId: "tenant_a", workspaceRoot: root });
-
-    await expect(
-      exec.run({
-        type: "edit",
-        path: "main.ts",
-        diff: [
-          "--- a/main.ts",
-          "+++ b/main.ts",
-          "@@ -1,2 +1,2 @@",
-          "-const value = 1;",
-          "+const value = 2;",
-          " console.log(value);",
-          "",
-        ].join("\n"),
-        tenantId: "tenant_a",
-      }),
-    ).resolves.toMatchObject({ type: "edit_applied", path: "main.ts" });
-
-    await expect(readFile(join(root, "main.ts"), "utf8")).resolves.toContain("value = 2");
-  });
-
-  it("requires tenant context for every action", async () => {
-    const exec = new CodeExecutor();
-    await expect(exec.run({ type: "read", path: "main.ts" })).rejects.toMatchObject({
-      capability: "code-execution",
-      suggestion: expect.stringContaining("tenantId"),
-    });
-  });
-
-  it("writes replayable debug entries", async () => {
-    root = await mkdtemp(join(tmpdir(), "code-execution-"));
-    const exec = new CodeExecutor({ tenantId: "tenant_a", debugRoot: root });
-    await exec.run({ type: "read", path: "missing.ts", tenantId: "tenant_a" });
-    expect(await readExecutionDebug(root)).toEqual(expect.any(Array));
-  });
-});