@descryy/runtime-controller 0.0.0

package/dist/capability-registry.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Capability registry (plan §16): assembles per-execution capabilities
+ * from the collectors actually present, so `distributedTrace: unavailable`
+ * is a first-class answer the AI planner can read rather than a silent
+ * gap. Does not know how to *produce* a `CollectorCapabilities` value —
+ * that's each collector's own `capabilities()` (Agents 2-4's concern) —
+ * only how to assemble and query what's been registered.
+ */
+import type { CapabilityStatus, CollectorCapabilities, EnvironmentTier, ExecutionCapabilities, FidelityLevel } from "@descryy/runtime-contracts";
+export interface RegisteredCollectorCapabilities {
+    readonly collectorId: string;
+    readonly capabilities: CollectorCapabilities;
+}
+export declare function buildExecutionCapabilities(environmentTier: EnvironmentTier, fidelityLevel: FidelityLevel, collectors: readonly RegisteredCollectorCapabilities[]): ExecutionCapabilities;
+export type CollectorCapabilityKey = keyof CollectorCapabilities;
+/**
+ * The best (most available) status for one capability across every
+ * registered collector — "is this observable *anywhere* in this
+ * execution," not per-collector. An execution with two network collectors
+ * where one degraded and one is fully available should read as available,
+ * not degraded.
+ */
+export declare function bestCapabilityStatus(capabilities: ExecutionCapabilities, key: CollectorCapabilityKey): CapabilityStatus;
+//# sourceMappingURL=capability-registry.d.ts.map

package/dist/capability-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-registry.d.ts","sourceRoot":"","sources":["../src/capability-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAEV,gBAAgB,EAChB,qBAAqB,EACrB,eAAe,EACf,qBAAqB,EACrB,aAAa,EACd,MAAM,4BAA4B,CAAC;AAEpC,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,YAAY,EAAE,qBAAqB,CAAC;CAC9C;AAED,wBAAgB,0BAA0B,CACxC,eAAe,EAAE,eAAe,EAChC,aAAa,EAAE,aAAa,EAC5B,UAAU,EAAE,SAAS,+BAA+B,EAAE,GACrD,qBAAqB,CAEvB;AAED,MAAM,MAAM,sBAAsB,GAAG,MAAM,qBAAqB,CAAC;AAajE;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,YAAY,EAAE,qBAAqB,EACnC,GAAG,EAAE,sBAAsB,GAC1B,gBAAgB,CAalB"}

package/dist/capability-registry.js

@@ -0,0 +1,42 @@
+/**
+ * Capability registry (plan §16): assembles per-execution capabilities
+ * from the collectors actually present, so `distributedTrace: unavailable`
+ * is a first-class answer the AI planner can read rather than a silent
+ * gap. Does not know how to *produce* a `CollectorCapabilities` value —
+ * that's each collector's own `capabilities()` (Agents 2-4's concern) —
+ * only how to assemble and query what's been registered.
+ */
+export function buildExecutionCapabilities(environmentTier, fidelityLevel, collectors) {
+    return { environmentTier, fidelityLevel, collectors };
+}
+const AVAILABILITY_RANK = {
+    unavailable: 0,
+    degraded: 1,
+    available: 2,
+};
+const NO_COLLECTOR_STATUS = {
+    availability: "unavailable",
+    reason: "no collector registered for this execution",
+};
+/**
+ * The best (most available) status for one capability across every
+ * registered collector — "is this observable *anywhere* in this
+ * execution," not per-collector. An execution with two network collectors
+ * where one degraded and one is fully available should read as available,
+ * not degraded.
+ */
+export function bestCapabilityStatus(capabilities, key) {
+    // Seeded from the first collector actually seen, not from
+    // NO_COLLECTOR_STATUS -- seeding from the placeholder would make a
+    // single collector's genuine "unavailable" tie the placeholder's rank
+    // and lose its specific reason to the generic one.
+    let best = null;
+    for (const collector of capabilities.collectors) {
+        const status = collector.capabilities[key];
+        if (best === null || AVAILABILITY_RANK[status.availability] > AVAILABILITY_RANK[best.availability]) {
+            best = status;
+        }
+    }
+    return best ?? NO_COLLECTOR_STATUS;
+}
+//# sourceMappingURL=capability-registry.js.map

package/dist/capability-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-registry.js","sourceRoot":"","sources":["../src/capability-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAgBH,MAAM,UAAU,0BAA0B,CACxC,eAAgC,EAChC,aAA4B,EAC5B,UAAsD;IAEtD,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,UAAU,EAAE,CAAC;AACxD,CAAC;AAID,MAAM,iBAAiB,GAAqD;IAC1E,WAAW,EAAE,CAAC;IACd,QAAQ,EAAE,CAAC;IACX,SAAS,EAAE,CAAC;CACb,CAAC;AAEF,MAAM,mBAAmB,GAAqB;IAC5C,YAAY,EAAE,aAAa;IAC3B,MAAM,EAAE,4CAA4C;CACrD,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAClC,YAAmC,EACnC,GAA2B;IAE3B,0DAA0D;IAC1D,mEAAmE;IACnE,sEAAsE;IACtE,mDAAmD;IACnD,IAAI,IAAI,GAA4B,IAAI,CAAC;IACzC,KAAK,MAAM,SAAS,IAAI,YAAY,CAAC,UAAU,EAAE,CAAC;QAChD,MAAM,MAAM,GAAG,SAAS,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;QAC3C,IAAI,IAAI,KAAK,IAAI,IAAI,iBAAiB,CAAC,MAAM,CAAC,YAAY,CAAC,GAAG,iBAAiB,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC;YACnG,IAAI,GAAG,MAAM,CAAC;QAChB,CAAC;IACH,CAAC;IACD,OAAO,IAAI,IAAI,mBAAmB,CAAC;AACrC,CAAC"}

package/dist/collector-version.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `Evidence.collectorVersion`'s source for `ProcessCollector`: this
+ * package's own `package.json` "version", read from the artifact itself
+ * rather than hand-duplicated into a second string that can drift from
+ * what actually shipped. Same idea as `nodeVersion` elsewhere in this repo
+ * (`process.version`, always known, never probed) applied to a package
+ * instead of the Node runtime.
+ */
+export declare const COLLECTOR_VERSION: string;
+//# sourceMappingURL=collector-version.d.ts.map

package/dist/collector-version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collector-version.d.ts","sourceRoot":"","sources":["../src/collector-version.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,eAAO,MAAM,iBAAiB,EAAE,MAA6E,CAAC"}

package/dist/collector-version.js

@@ -0,0 +1,12 @@
+/**
+ * `Evidence.collectorVersion`'s source for `ProcessCollector`: this
+ * package's own `package.json` "version", read from the artifact itself
+ * rather than hand-duplicated into a second string that can drift from
+ * what actually shipped. Same idea as `nodeVersion` elsewhere in this repo
+ * (`process.version`, always known, never probed) applied to a package
+ * instead of the Node runtime.
+ */
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+export const COLLECTOR_VERSION = require("../package.json").version;
+//# sourceMappingURL=collector-version.js.map

package/dist/collector-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collector-version.js","sourceRoot":"","sources":["../src/collector-version.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAE/C,MAAM,CAAC,MAAM,iBAAiB,GAAY,OAAO,CAAC,iBAAiB,CAAkC,CAAC,OAAO,CAAC"}

package/dist/container-sandbox.d.ts

@@ -0,0 +1,188 @@
+/**
+ * §21's execution boundary, container backend -- the macOS/Windows half of
+ * the sandbox-isolation lane. `sandbox.ts` closed this gap for Linux via
+ * bubblewrap; this module closes it for macOS and Windows, but NOT by
+ * building a second and third native OS sandbox. That path was researched
+ * (`sandbox.ts`'s own original module doc named `sandbox-exec`/Seatbelt on
+ * macOS and Job Objects/AppContainer on Windows as candidates) and
+ * explicitly rejected as an architecture decision: `sandbox-exec` is
+ * deprecated (no public API replacement), the Endpoint Security Framework
+ * needs a special Apple entitlement this project does not have, and
+ * hand-building Job Objects + AppContainer + WFP network enforcement on
+ * Windows is a second and third bespoke native sandbox to build and
+ * maintain for the same problem already solved once.
+ *
+ * **Mechanism: route the spawned process through a real container instead.**
+ * This runtime's actual targets -- JVM/Spring, Node, Python backends -- are
+ * already containerizable, so this reuses the *Linux* sandbox mechanism
+ * bwrap already proved, by running the target process inside a `docker run`
+ * invocation. The container's own rootfs IS the "outside allowedRoots is
+ * unreachable" boundary; nothing inside the container needs bwrap. On
+ * macOS, `docker run` targets Docker Desktop's Linux VM; on Windows, WSL2 /
+ * Docker Desktop's Windows backend. Both ultimately run the same Linux
+ * container runtime this module already drives directly.
+ *
+ * **What was actually verified, and what was not -- stated precisely,
+ * matching `sandbox.ts`'s own "researched and disclosed rather than
+ * guessed" discipline:**
+ *
+ * REAL-TESTED, on this Linux development machine, via a real installed
+ * Docker daemon (server 29.6.1) and real `docker run` invocations -- not
+ * mocked, not asserted from documentation: a file outside a container's
+ * bind-mounts is genuinely unreachable (`ENOENT` from inside the running
+ * container); a network call under `--network none` is genuinely refused
+ * against a real host listener; both together on one spawn; the same
+ * boundary through the full `ExecutionController.run()` path, not just this
+ * module's own function called directly. See `container-sandbox.test.ts`
+ * and `controller.test.ts`'s container-backend end-to-end test.
+ *
+ * **IMPLEMENTATION-NOT-DONE, not a "gap" and not a coverage caveat: the
+ * macOS-Docker-Desktop-VM-specific and Windows-WSL2-specific integration
+ * paths are UNVERIFIED on real macOS/Windows hardware.** No such hardware
+ * is available in this environment. Concretely unverified: detecting
+ * whether Docker Desktop is actually running before attempting a spawn;
+ * path translation across the Docker Desktop VM boundary on macOS; WSL2
+ * path translation on Windows (a Windows host path and the path Linux
+ * containers see are not the same string). This module's bind-mount
+ * strategy assumes the host path and the in-container path are identical
+ * (`-v hostPath:hostPath`, mirroring `sandbox.ts`'s own `--bind root root`
+ * convention) -- true on Linux, true for Docker Desktop's Linux VM when the
+ * path is already inside the VM's shared-drive mapping, but the exact
+ * translation rules for an arbitrary Windows path are not exercised here at
+ * all. This is "the container mechanism exists and is tested where it can
+ * be, but full cross-platform verification needs hardware nobody here has"
+ * -- a distinct category from a real bug or an intentionally out-of-scope
+ * capability, and this module does not claim otherwise.
+ *
+ * **Explicit scope boundary, same treatment attach-mode already gets in
+ * this codebase:** a target that cannot run containerized at all --deep
+ * native OS integration, GUI-dependent processes, OS-specific native
+ * dependencies that don't exist inside a Linux container image-- is out of
+ * scope for this approach, on any platform. There is no fallback to a
+ * native sandbox for such a target; it is simply not isolatable by this
+ * mechanism, and that is disclosed rather than silently unsupported.
+ *
+ * **Real escape testing on the container boundary is still required and
+ * was done** -- "the container starts successfully" is not treated as
+ * sufficient evidence here, the same bar `sandbox.ts`'s bwrap path was held
+ * to. A mutation check on the first version of that testing (temporarily
+ * removing `--network none`, rerunning) surfaced a genuine behavioral
+ * difference from bwrap worth stating precisely rather than glossing over:
+ * **Docker gives every container its own network namespace by default,
+ * with or without `--network none`** -- unlike bwrap, which shares the
+ * host's network unless `networkPolicy` is declared. A containerized
+ * process can therefore never reach the HOST's own loopback either way
+ * (that alone is not evidence `--network none` specifically did anything),
+ * but it CAN still reach the public internet via Docker's default bridge
+ * NAT when no `networkPolicy` is declared -- only `--network none`
+ * additionally blocks that. `container-sandbox.test.ts`'s dedicated
+ * mutation-sensitive test isolates exactly this variable (an external
+ * host, not the host's own loopback) to prove the flag itself is what is
+ * being tested, not mere containerization.
+ *
+ * **What this module does NOT attempt to solve, disclosed rather than
+ * silently dropped:** composition with `ResourceLimits` (`prlimit`) --
+ * `sandbox.ts` composes bwrap with `applyResourceLimits` by wrapping
+ * outside it; this module does not attempt the equivalent composition with
+ * Docker's own `--memory`/`--cpus`/`--pids-limit` flags in this pass. A
+ * `resourceLimits`-declared execution routed through the container backend
+ * runs without OS-enforced resource limits inside the container. Selective
+ * network allow-/deny-listing (`NetworkPolicy` shapes other than full
+ * denial) is unimplemented here for the same reason `sandbox.ts` doesn't
+ * implement it: it needs DNS interception and IP filtering this iteration
+ * does not build -- `unsupportedContainerNetworkPolicyReason` reports this
+ * the same way `sandbox.ts`'s own `unsupportedNetworkPolicyReason` does,
+ * deliberately matching posture rather than silently claiming broader
+ * support than the underlying mechanism has.
+ */
+import type { CapabilityStatus, FilesystemPolicy, NetworkPolicy } from "@descryy/runtime-contracts";
+/**
+ * Real capability check: is a working Docker CLI + reachable daemon
+ * actually present, not merely "does a `docker` binary exist on PATH."
+ * `docker version` talks to the daemon; a CLI with no running daemon behind
+ * it (Docker Desktop not started, dockerd not running) fails this the same
+ * way a missing binary does -- both are "cannot enforce," and the caller
+ * does not need to tell them apart to make the right decision (refuse).
+ */
+export declare function containerRuntimeCapability(env?: NodeJS.ProcessEnv): CapabilityStatus;
+/**
+ * Mirrors `sandbox.ts`'s `filesystemIsolationCapability`/
+ * `networkIsolationCapability` split: one real mechanism underneath
+ * (a container boundary), two named capabilities because the two policies
+ * are declared, refused, and reasoned about independently at the call
+ * site.
+ */
+export declare function containerFilesystemIsolationCapability(env?: NodeJS.ProcessEnv): CapabilityStatus;
+export declare function containerNetworkIsolationCapability(env?: NodeJS.ProcessEnv): CapabilityStatus;
+/**
+ * Same posture as `sandbox.ts`'s `unsupportedNetworkPolicyReason`, matched
+ * deliberately rather than reinvented: only full denial
+ * (`{ mode: "allow", hosts: [] }`, `docker run --network none`) is
+ * enforced. A shape bwrap already discloses as unsupported is not silently
+ * claimed as supported here just because the underlying mechanism changed.
+ */
+export declare function unsupportedContainerNetworkPolicyReason(policy: NetworkPolicy): string | null;
+export declare function resolveContainerImage(interpreterCommand: string): string | null;
+export interface ContainerSandboxOptions {
+    /** Used only to resolve a default base image via `resolveContainerImage` when `containerImage` is not given. */
+    readonly interpreterCommand: string;
+    /** The command to exec *inside* the container -- resolved against the image's own PATH, not the host's (see `processEnv`'s own comment for why `PATH` is never forwarded). */
+    readonly command: string;
+    readonly args: readonly string[];
+    /** Bind-mounted into the container at the identical path (`-v cwd:cwd`), always -- mirrors `sandbox.ts`'s "cwd always bound" default, and is the one directory the target process is guaranteed to need. */
+    readonly cwd: string;
+    readonly filesystemPolicy?: FilesystemPolicy;
+    readonly networkPolicy?: NetworkPolicy;
+    /**
+     * Env vars the CONTAINERIZED PROCESS itself needs (e.g. `PORT`, a
+     * service's declared `env`) -- forwarded into the container via `-e
+     * KEY=VALUE`. **`PATH` is deliberately never forwarded**: the container
+     * must resolve `command` against its own image's filesystem layout
+     * (`/usr/local/bin/node` in `node:22-slim`, not wherever the host's
+     * interpreter happens to live), and forwarding the host's `PATH` would
+     * silently break that resolution or -- if it named a path that happens to
+     * exist for a different binary inside the image -- run the wrong thing.
+     * Every other variable is forwarded unfiltered, matching the same
+     * unfiltered-inheritance precedent `process-manager.ts` already
+     * established for the bwrap path (bwrap does not `--clearenv` either).
+     */
+    readonly processEnv?: Readonly<Record<string, string | undefined>>;
+    /** Env used only to run the `docker` CLI itself (PATH lookup for `docker`, `DOCKER_HOST`, etc.) -- plays the same role `SandboxOptions.env` plays for bwrap's own capability check. Defaults to `process.env`. */
+    readonly env?: NodeJS.ProcessEnv;
+    /** Explicit override -- bypasses `resolveContainerImage`'s name-based guess entirely. */
+    readonly containerImage?: string;
+}
+/**
+ * Wraps `command`/`args` with `docker run` so a real container boundary
+ * enforces `filesystemPolicy`/`networkPolicy`. Neither declared returns
+ * `command`/`args` unchanged and never invokes docker at all -- the same
+ * non-regression contract `sandbox.ts`'s `applySandbox` established for
+ * bwrap, applied here too: a caller who never opts into a policy is
+ * completely unaffected by this module's existence.
+ *
+ * **Throws rather than silently spawning unconstrained** when a policy is
+ * requested and cannot actually be backed -- no working Docker, or a
+ * `networkPolicy` shape this mechanism doesn't implement -- matching
+ * `applySandbox`'s own refuse-rather-than-guess precedent exactly.
+ *
+ * **Returns a real, unique `containerName` whenever it wraps.** This was
+ * added after a genuine finding from this module's own real escape tests,
+ * not assumed up front: `process-manager.ts`'s existing group-kill
+ * (`process.kill(-pid, signal)`) targets the *local* `docker` CLI process's
+ * group -- exactly right for bwrap, which execs the sandboxed process
+ * directly and never creates a second process group. Docker is different:
+ * the container runs under `dockerd`, not as a child of the local `docker`
+ * CLI, so killing the CLI's process group does not reliably stop the
+ * container -- observed directly (a `kill()` call left a real orphaned
+ * `node:22-slim` container running after both the CLI process and its
+ * grace period were gone). `containerName` lets the caller
+ * (`process-manager.ts`) issue a real, explicit `docker stop <name>`
+ * against the container itself as the actual mechanism, not the CLI
+ * process, for the container backend.
+ */
+export declare function applyContainerSandbox(options: ContainerSandboxOptions): {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly containerName?: string;
+};
+//# sourceMappingURL=container-sandbox.d.ts.map

package/dist/container-sandbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"container-sandbox.d.ts","sourceRoot":"","sources":["../src/container-sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgGG;AAKH,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAEpG;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,gBAAgB,CAUjG;AAED;;;;;;GAMG;AACH,wBAAgB,sCAAsC,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,gBAAgB,CAE7G;AAED,wBAAgB,mCAAmC,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,gBAAgB,CAE1G;AAED;;;;;;GAMG;AACH,wBAAgB,uCAAuC,CAAC,MAAM,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAO5F;AAkBD,wBAAgB,qBAAqB,CAAC,kBAAkB,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE/E;AAED,MAAM,WAAW,uBAAuB;IACtC,gHAAgH;IAChH,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,8KAA8K;IAC9K,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,4MAA4M;IAC5M,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAC7C,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;IACvC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IACnE,kNAAkN;IAClN,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACjC,yFAAyF;IACzF,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,uBAAuB,GAC/B;IAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,CAkDjG"}

package/dist/container-sandbox.js

@@ -0,0 +1,233 @@
+/**
+ * §21's execution boundary, container backend -- the macOS/Windows half of
+ * the sandbox-isolation lane. `sandbox.ts` closed this gap for Linux via
+ * bubblewrap; this module closes it for macOS and Windows, but NOT by
+ * building a second and third native OS sandbox. That path was researched
+ * (`sandbox.ts`'s own original module doc named `sandbox-exec`/Seatbelt on
+ * macOS and Job Objects/AppContainer on Windows as candidates) and
+ * explicitly rejected as an architecture decision: `sandbox-exec` is
+ * deprecated (no public API replacement), the Endpoint Security Framework
+ * needs a special Apple entitlement this project does not have, and
+ * hand-building Job Objects + AppContainer + WFP network enforcement on
+ * Windows is a second and third bespoke native sandbox to build and
+ * maintain for the same problem already solved once.
+ *
+ * **Mechanism: route the spawned process through a real container instead.**
+ * This runtime's actual targets -- JVM/Spring, Node, Python backends -- are
+ * already containerizable, so this reuses the *Linux* sandbox mechanism
+ * bwrap already proved, by running the target process inside a `docker run`
+ * invocation. The container's own rootfs IS the "outside allowedRoots is
+ * unreachable" boundary; nothing inside the container needs bwrap. On
+ * macOS, `docker run` targets Docker Desktop's Linux VM; on Windows, WSL2 /
+ * Docker Desktop's Windows backend. Both ultimately run the same Linux
+ * container runtime this module already drives directly.
+ *
+ * **What was actually verified, and what was not -- stated precisely,
+ * matching `sandbox.ts`'s own "researched and disclosed rather than
+ * guessed" discipline:**
+ *
+ * REAL-TESTED, on this Linux development machine, via a real installed
+ * Docker daemon (server 29.6.1) and real `docker run` invocations -- not
+ * mocked, not asserted from documentation: a file outside a container's
+ * bind-mounts is genuinely unreachable (`ENOENT` from inside the running
+ * container); a network call under `--network none` is genuinely refused
+ * against a real host listener; both together on one spawn; the same
+ * boundary through the full `ExecutionController.run()` path, not just this
+ * module's own function called directly. See `container-sandbox.test.ts`
+ * and `controller.test.ts`'s container-backend end-to-end test.
+ *
+ * **IMPLEMENTATION-NOT-DONE, not a "gap" and not a coverage caveat: the
+ * macOS-Docker-Desktop-VM-specific and Windows-WSL2-specific integration
+ * paths are UNVERIFIED on real macOS/Windows hardware.** No such hardware
+ * is available in this environment. Concretely unverified: detecting
+ * whether Docker Desktop is actually running before attempting a spawn;
+ * path translation across the Docker Desktop VM boundary on macOS; WSL2
+ * path translation on Windows (a Windows host path and the path Linux
+ * containers see are not the same string). This module's bind-mount
+ * strategy assumes the host path and the in-container path are identical
+ * (`-v hostPath:hostPath`, mirroring `sandbox.ts`'s own `--bind root root`
+ * convention) -- true on Linux, true for Docker Desktop's Linux VM when the
+ * path is already inside the VM's shared-drive mapping, but the exact
+ * translation rules for an arbitrary Windows path are not exercised here at
+ * all. This is "the container mechanism exists and is tested where it can
+ * be, but full cross-platform verification needs hardware nobody here has"
+ * -- a distinct category from a real bug or an intentionally out-of-scope
+ * capability, and this module does not claim otherwise.
+ *
+ * **Explicit scope boundary, same treatment attach-mode already gets in
+ * this codebase:** a target that cannot run containerized at all --deep
+ * native OS integration, GUI-dependent processes, OS-specific native
+ * dependencies that don't exist inside a Linux container image-- is out of
+ * scope for this approach, on any platform. There is no fallback to a
+ * native sandbox for such a target; it is simply not isolatable by this
+ * mechanism, and that is disclosed rather than silently unsupported.
+ *
+ * **Real escape testing on the container boundary is still required and
+ * was done** -- "the container starts successfully" is not treated as
+ * sufficient evidence here, the same bar `sandbox.ts`'s bwrap path was held
+ * to. A mutation check on the first version of that testing (temporarily
+ * removing `--network none`, rerunning) surfaced a genuine behavioral
+ * difference from bwrap worth stating precisely rather than glossing over:
+ * **Docker gives every container its own network namespace by default,
+ * with or without `--network none`** -- unlike bwrap, which shares the
+ * host's network unless `networkPolicy` is declared. A containerized
+ * process can therefore never reach the HOST's own loopback either way
+ * (that alone is not evidence `--network none` specifically did anything),
+ * but it CAN still reach the public internet via Docker's default bridge
+ * NAT when no `networkPolicy` is declared -- only `--network none`
+ * additionally blocks that. `container-sandbox.test.ts`'s dedicated
+ * mutation-sensitive test isolates exactly this variable (an external
+ * host, not the host's own loopback) to prove the flag itself is what is
+ * being tested, not mere containerization.
+ *
+ * **What this module does NOT attempt to solve, disclosed rather than
+ * silently dropped:** composition with `ResourceLimits` (`prlimit`) --
+ * `sandbox.ts` composes bwrap with `applyResourceLimits` by wrapping
+ * outside it; this module does not attempt the equivalent composition with
+ * Docker's own `--memory`/`--cpus`/`--pids-limit` flags in this pass. A
+ * `resourceLimits`-declared execution routed through the container backend
+ * runs without OS-enforced resource limits inside the container. Selective
+ * network allow-/deny-listing (`NetworkPolicy` shapes other than full
+ * denial) is unimplemented here for the same reason `sandbox.ts` doesn't
+ * implement it: it needs DNS interception and IP filtering this iteration
+ * does not build -- `unsupportedContainerNetworkPolicyReason` reports this
+ * the same way `sandbox.ts`'s own `unsupportedNetworkPolicyReason` does,
+ * deliberately matching posture rather than silently claiming broader
+ * support than the underlying mechanism has.
+ */
+import { execFileSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { basename } from "node:path";
+/**
+ * Real capability check: is a working Docker CLI + reachable daemon
+ * actually present, not merely "does a `docker` binary exist on PATH."
+ * `docker version` talks to the daemon; a CLI with no running daemon behind
+ * it (Docker Desktop not started, dockerd not running) fails this the same
+ * way a missing binary does -- both are "cannot enforce," and the caller
+ * does not need to tell them apart to make the right decision (refuse).
+ */
+export function containerRuntimeCapability(env = process.env) {
+    try {
+        execFileSync("docker", ["version", "--format", "{{.Server.Version}}"], { env, stdio: "ignore" });
+    }
+    catch {
+        return {
+            availability: "unavailable",
+            reason: "docker is not on PATH, or no Docker daemon is reachable -- container-based isolation cannot be enforced without a real, running Docker",
+        };
+    }
+    return { availability: "available", reason: null };
+}
+/**
+ * Mirrors `sandbox.ts`'s `filesystemIsolationCapability`/
+ * `networkIsolationCapability` split: one real mechanism underneath
+ * (a container boundary), two named capabilities because the two policies
+ * are declared, refused, and reasoned about independently at the call
+ * site.
+ */
+export function containerFilesystemIsolationCapability(env = process.env) {
+    return containerRuntimeCapability(env);
+}
+export function containerNetworkIsolationCapability(env = process.env) {
+    return containerRuntimeCapability(env);
+}
+/**
+ * Same posture as `sandbox.ts`'s `unsupportedNetworkPolicyReason`, matched
+ * deliberately rather than reinvented: only full denial
+ * (`{ mode: "allow", hosts: [] }`, `docker run --network none`) is
+ * enforced. A shape bwrap already discloses as unsupported is not silently
+ * claimed as supported here just because the underlying mechanism changed.
+ */
+export function unsupportedContainerNetworkPolicyReason(policy) {
+    if (policy.mode === "allow" && policy.hosts.length === 0)
+        return null;
+    return ('only full network denial ({ mode: "allow", hosts: [] }) is enforced -- selective allow- or deny-listing of specific ' +
+        "hosts would need a custom docker network with DNS interception and IP filtering inside it, not built in this " +
+        "iteration (the same posture the bwrap backend already declares for the same shapes)");
+}
+/**
+ * Minimal, official, `-slim`/`-jre` base images for this runtime's actual
+ * fixture targets (JVM/Spring, Node, Python backends -- see
+ * `packages/orchestrator/test/fixtures`), keyed by the interpreter's
+ * basename so a full interpreter path (`/home/x/.nvm/versions/node/vX/bin/node`)
+ * still resolves. Not a general-purpose image registry -- a caller with a
+ * different runtime need passes `containerImage` explicitly instead of
+ * extending this table with more special cases.
+ */
+const KNOWN_RUNTIME_IMAGES = {
+    node: "node:22-slim",
+    python: "python:3.12-slim",
+    python3: "python:3.12-slim",
+    java: "eclipse-temurin:21-jre",
+};
+export function resolveContainerImage(interpreterCommand) {
+    return KNOWN_RUNTIME_IMAGES[basename(interpreterCommand)] ?? null;
+}
+/**
+ * Wraps `command`/`args` with `docker run` so a real container boundary
+ * enforces `filesystemPolicy`/`networkPolicy`. Neither declared returns
+ * `command`/`args` unchanged and never invokes docker at all -- the same
+ * non-regression contract `sandbox.ts`'s `applySandbox` established for
+ * bwrap, applied here too: a caller who never opts into a policy is
+ * completely unaffected by this module's existence.
+ *
+ * **Throws rather than silently spawning unconstrained** when a policy is
+ * requested and cannot actually be backed -- no working Docker, or a
+ * `networkPolicy` shape this mechanism doesn't implement -- matching
+ * `applySandbox`'s own refuse-rather-than-guess precedent exactly.
+ *
+ * **Returns a real, unique `containerName` whenever it wraps.** This was
+ * added after a genuine finding from this module's own real escape tests,
+ * not assumed up front: `process-manager.ts`'s existing group-kill
+ * (`process.kill(-pid, signal)`) targets the *local* `docker` CLI process's
+ * group -- exactly right for bwrap, which execs the sandboxed process
+ * directly and never creates a second process group. Docker is different:
+ * the container runs under `dockerd`, not as a child of the local `docker`
+ * CLI, so killing the CLI's process group does not reliably stop the
+ * container -- observed directly (a `kill()` call left a real orphaned
+ * `node:22-slim` container running after both the CLI process and its
+ * grace period were gone). `containerName` lets the caller
+ * (`process-manager.ts`) issue a real, explicit `docker stop <name>`
+ * against the container itself as the actual mechanism, not the CLI
+ * process, for the container backend.
+ */
+export function applyContainerSandbox(options) {
+    const { filesystemPolicy, networkPolicy } = options;
+    if (filesystemPolicy === undefined && networkPolicy === undefined) {
+        return { command: options.command, args: options.args };
+    }
+    const env = options.env ?? process.env;
+    if (networkPolicy !== undefined) {
+        const shapeReason = unsupportedContainerNetworkPolicyReason(networkPolicy);
+        if (shapeReason !== null) {
+            throw new Error(`networkPolicy was configured but cannot be enforced: ${shapeReason}`);
+        }
+    }
+    const capability = containerRuntimeCapability(env);
+    if (capability.availability !== "available") {
+        throw new Error(`container sandbox was requested but cannot be enforced: ${capability.reason}`);
+    }
+    const image = options.containerImage ?? resolveContainerImage(options.interpreterCommand);
+    if (image === null) {
+        throw new Error(`container sandbox was requested but no base image is known for interpreter "${options.interpreterCommand}" -- pass containerImage explicitly`);
+    }
+    const containerName = `descry-sandbox-${randomUUID()}`;
+    const dockerArgs = ["run", "--rm", "--name", containerName];
+    if (networkPolicy !== undefined) {
+        dockerArgs.push("--network", "none");
+    }
+    dockerArgs.push("-v", `${options.cwd}:${options.cwd}`, "-w", options.cwd);
+    if (filesystemPolicy !== undefined) {
+        for (const root of filesystemPolicy.allowedRoots) {
+            dockerArgs.push("-v", `${root}:${root}`);
+        }
+    }
+    for (const [key, value] of Object.entries(options.processEnv ?? {})) {
+        if (key === "PATH" || value === undefined)
+            continue;
+        dockerArgs.push("-e", `${key}=${value}`);
+    }
+    dockerArgs.push(image, options.command, ...options.args);
+    return { command: "docker", args: dockerArgs, containerName };
+}
+//# sourceMappingURL=container-sandbox.js.map

package/dist/container-sandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"container-sandbox.js","sourceRoot":"","sources":["../src/container-sandbox.ts"],"names":[],"mappings":"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"}