@nebutra/agent-runtime 0.2.2 → 3.0.0

package/README.md

@@ -1,13 +1,19 @@
 # @nebutra/agent-runtime
 
-Status: **WIP**
+Status: **WIP** — Track A live (grammar + gateway demo); Track B Phase 1 docked
 
-> Status: WIP — not yet integrated into a production app. Track-B kernel
-> transport and durable-turn queue binding are interface-only.
+| Layer | State |
+|-------|--------|
+| Track A grammar (`runTurn`, policy, rollout, tools) | Shipped; gateway demo route behind `agent-runtime-demo` |
+| Track B adapter (`createCarinaSandbox` → Carina JSON-RPC) | **Phase 1 done** ([#382](https://github.com/Nebutra/Nebutra-Sailor/pull/382)) |
+| Track B host wire (env, ensureSession, `command_exec`, gateway bundle) | **Phase 2a done** (#386) |
+| Track B ship (workspace map, approval resolve, auto-approve, status) | **Phase 2b done** |
+| Product HITL UI (beyond API) | Optional |
+| Default without Carina endpoint | **Fail-closed** (`REFUSING_SANDBOX`) |
 
 Multi-tenant **agent-runtime grammar**. A faithful re-expression of a terminal
 coding-agent's runtime *design* into Sailor's grammar — TypeScript,
-multi-tenant, zero infra changes, **no in-process untrusted-code execution**.
+multi-tenant, zero in-process untrusted-code execution.
 
 ## Why this exists
 
@@ -24,9 +30,26 @@ them.
 
 - **Track A (this package)** — policy, protocol contract, model, rollout. All
   tenant-scoped. Runs inside Sailor's TS web runtime.
-- **Track B (decoupled, not this repo)** — an optional self-hosted isolator /
-  kernel sidecar that implements `ExternalSandbox` over the `./protocol`
-  contract. The protocol is the only coupling seam.
+- **Track B (Carina upstream)** — the **Nebutra/carina** kernel is the sole
+  product isolator. Self-deployed, local-first. Sailor docks via
+  `createCarinaSandbox` / `ExternalSandbox` — **kernel protocol is maintained
+  in Carina**, not reimplemented here.
+
+```ts
+import {
+  createCarinaSandbox,
+  REFUSING_SANDBOX,
+  type ExternalSandbox,
+} from "@nebutra/agent-runtime";
+
+// Production: only when a reachable Carina JSON-RPC base URL is configured.
+// Same-host co-deploy (default): unix socket /var/carina/run/daemon.sock
+import { resolveCarinaSandboxFromEnv } from "@nebutra/agent-runtime";
+const sandbox = resolveCarinaSandboxFromEnv();
+// Opt out: CARINA_CODEPLOY=0  |  optional HTTP: CARINA_JSONRPC_URL=…
+```
+
+See `docs/architecture/2026-08-03-carina-track-b-upstream.md`.
 
 ## Modules
 
@@ -37,16 +60,16 @@ them.
 | `./protocol` | JSON-RPC contract | method registry, **tenant+thread serialization scope**, server-initiated approval requests, notifications |
 | `./tools` | uniform tool/MCP | `ToolRegistry` (registry→router→hooks), `adaptMcpTool` (MCP-as-adapter) |
 | `./rollout` | event-sourced trace | append-only typed log, replay-to-state, compaction marker, per-item persistence policy |
-| `./sandbox` | external-sandbox seam | `ExternalSandbox` delegation interface; fail-closed `REFUSING_SANDBOX` default |
+| `./sandbox` | external-sandbox seam | `ExternalSandbox`; `createCarinaSandbox` (Track B); `REFUSING_SANDBOX` default; `createHttpSandbox` generic helper |
 | `./adapters/*` | reusable concrete bindings | MCP catalog, Web-standard SSE transport, and Prisma rollout persistence without a separate package |
 
 ## Non-negotiables enforced here
 
 - **Multi-tenant**: every scope, store key, and dispatch carries `tenantId`;
   cross-tenant requests can never share a serialization scope.
-- **No infra change**: no sandbox runtime, no new datastore — only interfaces.
 - **No in-process untrusted exec**: the default executor refuses; real
-  execution is delegated to a decoupled isolator.
+  execution is delegated to self-deployed Carina (or another `ExternalSandbox`).
+- **No second kernel**: OS sandbox / capability enforcement stay in Carina.
 
 See `docs/capabilities/agent-runtime/` for the capability map and replication
 guide.

package/dist/{chunk-KCNN4QUQ.js → chunk-5UGIUYJR.js}

@@ -4,15 +4,15 @@ import {
 import {
   replay
 } from "./chunk-37BBB2P2.js";
-import {
-  RuntimeToolRegistry
-} from "./chunk-4Y25ZTKI.js";
 import {
   isTurnTerminal
 } from "./chunk-6EGG2OZC.js";
 import {
   DEFAULT_APPROVAL_POLICY
 } from "./chunk-CGRCUKGT.js";
+import {
+  RuntimeToolRegistry
+} from "./chunk-4Y25ZTKI.js";
 
 // src/pulsar.ts
 function newId(prefix) {
@@ -252,4 +252,4 @@ export {
   PulsarBuilder,
   Pulsar
 };
-//# sourceMappingURL=chunk-KCNN4QUQ.js.map
+//# sourceMappingURL=chunk-5UGIUYJR.js.map

package/dist/chunk-7ELA4SWE.js

@@ -0,0 +1,73 @@
+import {
+  isCarinaSandbox
+} from "./chunk-VXILZAXK.js";
+import {
+  DEFAULT_CAPABILITY_POLICY
+} from "./chunk-CGRCUKGT.js";
+import {
+  RuntimeToolRegistry
+} from "./chunk-4Y25ZTKI.js";
+
+// src/command-exec.ts
+import { z } from "zod";
+var COMMAND_EXEC_TOOL_NAME = "command_exec";
+var commandExecInputSchema = z.object({
+  command: z.string().min(1)
+});
+function registerCommandExecTool(registry, options) {
+  const {
+    sandbox,
+    workspaceRoot,
+    capabilityPolicy = DEFAULT_CAPABILITY_POLICY,
+    profile,
+    approvalMode
+  } = options;
+  registry.register(
+    {
+      name: COMMAND_EXEC_TOOL_NAME,
+      description: "Run a shell command in the external sandbox (Carina Track B). Never executes in the Sailor web process.",
+      inputSchema: commandExecInputSchema
+    },
+    async (input, ctx) => {
+      if (isCarinaSandbox(sandbox)) {
+        const root = workspaceRoot?.trim();
+        if (!root) {
+          throw new Error(
+            "command_exec: CARINA_WORKSPACE_ROOT / workspaceRoot required to create a Carina session before command.exec"
+          );
+        }
+        await sandbox.ensureSession({
+          threadId: ctx.threadId,
+          workspaceRoot: root,
+          tenantId: ctx.tenantId,
+          ...profile ? { profile } : {},
+          ...approvalMode ? { approvalMode } : {}
+        });
+      }
+      const result = await sandbox.exec({
+        tenantId: ctx.tenantId,
+        threadId: ctx.threadId,
+        command: input.command,
+        capabilityPolicy
+      });
+      return {
+        exitCode: result.exitCode,
+        aggregatedOutput: result.aggregatedOutput,
+        executedOn: result.executedOn,
+        ...result.decisionId !== void 0 ? { decisionId: result.decisionId } : {}
+      };
+    }
+  );
+}
+function buildSandboxToolRegistry(sandbox, options = {}) {
+  const registry = new RuntimeToolRegistry();
+  registerCommandExecTool(registry, { sandbox, ...options });
+  return registry;
+}
+
+export {
+  COMMAND_EXEC_TOOL_NAME,
+  registerCommandExecTool,
+  buildSandboxToolRegistry
+};
+//# sourceMappingURL=chunk-7ELA4SWE.js.map

package/dist/chunk-7ELA4SWE.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/command-exec.ts"],"sourcesContent":["/**\n * Native command-exec tool that delegates to {@link ExternalSandbox}.\n * Product Track B: pair with {@link createCarinaSandbox} + ensureSession.\n */\n\nimport { z } from \"zod\";\n\nimport { type CapabilityPolicy, DEFAULT_CAPABILITY_POLICY } from \"./policy\";\nimport { type ExternalSandbox, isCarinaSandbox, type SandboxExecResult } from \"./sandbox\";\nimport { RuntimeToolRegistry } from \"./tools\";\n\nexport const COMMAND_EXEC_TOOL_NAME = \"command_exec\" as const;\n\nconst commandExecInputSchema = z.object({\n  command: z.string().min(1),\n});\n\nexport type CommandExecToolInput = z.infer<typeof commandExecInputSchema>;\n\nexport type CommandExecToolOutput = {\n  readonly exitCode: number;\n  readonly aggregatedOutput: string;\n  readonly executedOn: string;\n  readonly decisionId?: string;\n};\n\nexport type RegisterCommandExecToolOptions = {\n  readonly sandbox: ExternalSandbox;\n  /**\n   * Absolute workspace on the Carina host. Required when sandbox is Carina\n   * (session.create). Gateway reads `CARINA_WORKSPACE_ROOT`.\n   */\n  readonly workspaceRoot?: string;\n  readonly capabilityPolicy?: CapabilityPolicy;\n  readonly profile?: string;\n  readonly approvalMode?: string;\n};\n\n/**\n * Register `command_exec` on a tool registry. For Carina sandboxes, ensures a\n * session for the turn thread before `command.exec`.\n */\nexport function registerCommandExecTool(\n  registry: RuntimeToolRegistry,\n  options: RegisterCommandExecToolOptions,\n): void {\n  const {\n    sandbox,\n    workspaceRoot,\n    capabilityPolicy = DEFAULT_CAPABILITY_POLICY,\n    profile,\n    approvalMode,\n  } = options;\n\n  registry.register(\n    {\n      name: COMMAND_EXEC_TOOL_NAME,\n      description:\n        \"Run a shell command in the external sandbox (Carina Track B). \" +\n        \"Never executes in the Sailor web process.\",\n      inputSchema: commandExecInputSchema,\n    },\n    async (input, ctx): Promise<CommandExecToolOutput> => {\n      if (isCarinaSandbox(sandbox)) {\n        const root = workspaceRoot?.trim();\n        if (!root) {\n          throw new Error(\n            \"command_exec: CARINA_WORKSPACE_ROOT / workspaceRoot required \" +\n              \"to create a Carina session before command.exec\",\n          );\n        }\n        await sandbox.ensureSession({\n          threadId: ctx.threadId,\n          workspaceRoot: root,\n          tenantId: ctx.tenantId,\n          ...(profile ? { profile } : {}),\n          ...(approvalMode ? { approvalMode } : {}),\n        });\n      }\n\n      const result: SandboxExecResult = await sandbox.exec({\n        tenantId: ctx.tenantId,\n        threadId: ctx.threadId,\n        command: input.command,\n        capabilityPolicy,\n      });\n\n      return {\n        exitCode: result.exitCode,\n        aggregatedOutput: result.aggregatedOutput,\n        executedOn: result.executedOn,\n        ...(result.decisionId !== undefined ? { decisionId: result.decisionId } : {}),\n      };\n    },\n  );\n}\n\n/**\n * Build a registry that includes `command_exec` delegated to the given sandbox.\n * Prefer this only when a real isolator is configured; with\n * {@link REFUSING_SANDBOX} the tool will throw NoExecutorConfiguredError on use.\n */\nexport function buildSandboxToolRegistry(\n  sandbox: ExternalSandbox,\n  options: Omit<RegisterCommandExecToolOptions, \"sandbox\"> = {},\n): RuntimeToolRegistry {\n  const registry = new RuntimeToolRegistry();\n  registerCommandExecTool(registry, { sandbox, ...options });\n  return registry;\n}\n"],"mappings":";;;;;;;;;;;AAKA,SAAS,SAAS;AAMX,IAAM,yBAAyB;AAEtC,IAAM,yBAAyB,EAAE,OAAO;AAAA,EACtC,SAAS,EAAE,OAAO,EAAE,IAAI,CAAC;AAC3B,CAAC;AA2BM,SAAS,wBACd,UACA,SACM;AACN,QAAM;AAAA,IACJ;AAAA,IACA;AAAA,IACA,mBAAmB;AAAA,IACnB;AAAA,IACA;AAAA,EACF,IAAI;AAEJ,WAAS;AAAA,IACP;AAAA,MACE,MAAM;AAAA,MACN,aACE;AAAA,MAEF,aAAa;AAAA,IACf;AAAA,IACA,OAAO,OAAO,QAAwC;AACpD,UAAI,gBAAgB,OAAO,GAAG;AAC5B,cAAM,OAAO,eAAe,KAAK;AACjC,YAAI,CAAC,MAAM;AACT,gBAAM,IAAI;AAAA,YACR;AAAA,UAEF;AAAA,QACF;AACA,cAAM,QAAQ,cAAc;AAAA,UAC1B,UAAU,IAAI;AAAA,UACd,eAAe;AAAA,UACf,UAAU,IAAI;AAAA,UACd,GAAI,UAAU,EAAE,QAAQ,IAAI,CAAC;AAAA,UAC7B,GAAI,eAAe,EAAE,aAAa,IAAI,CAAC;AAAA,QACzC,CAAC;AAAA,MACH;AAEA,YAAM,SAA4B,MAAM,QAAQ,KAAK;AAAA,QACnD,UAAU,IAAI;AAAA,QACd,UAAU,IAAI;AAAA,QACd,SAAS,MAAM;AAAA,QACf;AAAA,MACF,CAAC;AAED,aAAO;AAAA,QACL,UAAU,OAAO;AAAA,QACjB,kBAAkB,OAAO;AAAA,QACzB,YAAY,OAAO;AAAA,QACnB,GAAI,OAAO,eAAe,SAAY,EAAE,YAAY,OAAO,WAAW,IAAI,CAAC;AAAA,MAC7E;AAAA,IACF;AAAA,EACF;AACF;AAOO,SAAS,yBACd,SACA,UAA2D,CAAC,GACvC;AACrB,QAAM,WAAW,IAAI,oBAAoB;AACzC,0BAAwB,UAAU,EAAE,SAAS,GAAG,QAAQ,CAAC;AACzD,SAAO;AACT;","names":[]}