@stigmer/server 3.14.0-dev.20260910084630

package/src/sandbox/lane.ts

@@ -0,0 +1,89 @@
+/**
+ * The composed sandbox lane — the explicit modeled state the invocation
+ * steps consume (never a nullable provisioner threaded through deps; the
+ * composition doctrine's "optional infrastructure is a modeled state").
+ * Disabled IS the OSS default: SANDBOX_PROVISIONER_TYPE unset means the
+ * external-runner posture (gate ruling Q1) and every step below
+ * short-circuits on its fast path — byte-identical wire behavior, pinned
+ * by the conformance rosters.
+ *
+ * Credential minting (gate ruling Q6): sandboxes authenticate on the ONE
+ * OSS credential lane — execution-scoped (runnerauth §6c). The token is
+ * minted per execution at ensure time, so the cloud's stale-token refresh
+ * arm degenerates to per-execution re-mint here; a disabled mint lane
+ * launches the sandbox with no token and ExecutionContext decrypt falls
+ * back to redaction (oss#535's posture), degraded but never dark.
+ *
+ * A provider with the mintSandboxCredential capability (C4, gate ruling
+ * Q1) owns the mint instead: the ensure steps hand it the full
+ * provisioning context and bake whatever it returns — the cloud's
+ * session/workflow-scoped tokens ride this without the steps knowing any
+ * lane vocabulary beyond their own identifiers.
+ */
+import type {
+  RunnerCredentialProvider,
+  SandboxCredentialRequest,
+} from "../runnerauth/runner-credential-provider.js";
+import { TOKEN_TYPE_EXECUTION_SCOPED } from "../runnerauth/runnerauth.js";
+import type { Logger } from "../boot/logger.js";
+import type { SandboxProvisioner } from "./provisioner.js";
+
+/**
+ * Sandbox credential TTL: 4 hours — the cloud edition's
+ * SandboxTokenService TTL, kept identical so a sandbox outliving its
+ * token behaves the same on both editions (the runner renews via
+ * getRunnerScopedToken either way).
+ */
+export const SANDBOX_TOKEN_TTL_SECONDS = 4 * 60 * 60;
+
+/** The lane: either disabled (the default) or a provisioner + its credential mint. */
+export type SandboxLane =
+  | { readonly enabled: false }
+  | {
+      readonly enabled: true;
+      readonly provisioner: SandboxProvisioner;
+      readonly credentials: RunnerCredentialProvider;
+    };
+
+export function newSandboxLane(
+  provisioner: SandboxProvisioner | undefined,
+  credentials: RunnerCredentialProvider,
+): SandboxLane {
+  if (provisioner === undefined) {
+    return { enabled: false };
+  }
+  return { enabled: true, provisioner, credentials };
+}
+
+/**
+ * Mints the sandbox's STIGMER_TOKEN, or "" to launch tokenless (module
+ * header). With the mintSandboxCredential capability composed, the
+ * provider owns the whole decision from the provisioning context;
+ * otherwise the OSS execution-scoped mint runs exactly as before. A mint
+ * FAILURE on an enabled lane is a real fault and propagates to the
+ * caller's failure posture — never swallowed into the no-token arm.
+ */
+export function mintSandboxToken(
+  lane: Extract<SandboxLane, { enabled: true }>,
+  request: SandboxCredentialRequest,
+  logger: Logger,
+): string {
+  const mintSandboxCredential = lane.credentials.mintSandboxCredential?.bind(
+    lane.credentials,
+  );
+  if (mintSandboxCredential !== undefined) {
+    return mintSandboxCredential(request);
+  }
+  if (!lane.credentials.isEnabled(TOKEN_TYPE_EXECUTION_SCOPED)) {
+    logger.warn(
+      "Sandbox launching without a runner token (credential lane disabled) — ExecutionContext reads will be redacted",
+      { executionId: request.executionId },
+    );
+    return "";
+  }
+  return lane.credentials.mint(
+    TOKEN_TYPE_EXECUTION_SCOPED,
+    request.executionId,
+    SANDBOX_TOKEN_TTL_SECONDS,
+  ).token;
+}

package/src/sandbox/local-process.ts

@@ -0,0 +1,188 @@
+/**
+ * The local-process sandbox driver — DD-002's first isolation tier
+ * (process → Docker → Kubernetes), built by O6 (20260827.05, gate ruling
+ * Q1: a REAL driver, not a named no-op). Each sandbox is a managed
+ * runner child process polling exactly one task queue, with its own
+ * isolated workspace directory — today's implicit "the runner is a local
+ * process" posture made explicit and per-execution.
+ *
+ * The child's env is the runner's verified contract
+ * (backend/services/runner/src/config.ts): MODE=local,
+ * STIGMER_TASK_QUEUE (the one queue this sandbox serves),
+ * STIGMER_BACKEND_ENDPOINT / TEMPORAL_SERVICE_ADDRESS (empty values fall
+ * back to the runner's own local defaults and Temporal self-discovery),
+ * STIGMER_TOKEN when minted ("" stays unset — optional in local mode),
+ * and a per-sandbox WORKSPACE_ROOT_DIR so concurrent sandboxes never
+ * share a workspace.
+ *
+ * Process lifecycle facts this driver leans on deliberately:
+ *
+ *   - The check-spawn-record section of ensure has NO awaits, so
+ *     concurrent ensures for one id cannot double-spawn (single-threaded
+ *     atomicity — the same reason the map needs no lock).
+ *   - An exited child removes itself from the table, so the next ensure
+ *     observes "absent" and respawns — the state machine's repair arm
+ *     without stored state (gate ruling Q4: runtime-derived).
+ *   - Children are killed on server-process exit (the exit hook below):
+ *     a process-tier sandbox must not outlive the server that provisions
+ *     it — unlike the container tiers, nothing could ever re-adopt it.
+ */
+import { spawn } from "node:child_process";
+import type { ChildProcess } from "node:child_process";
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+
+import type { Logger } from "../boot/logger.js";
+import type {
+  SandboxEnvironment,
+  SandboxProbeState,
+  SandboxProvisioner,
+  SandboxProvisionerFactory,
+  SandboxScope,
+} from "./provisioner.js";
+
+/** SIGTERM-first teardown; the runner's Temporal worker drains on it. */
+const DEPROVISION_SIGNAL: NodeJS.Signals = "SIGTERM";
+
+export const newLocalProcessSandboxProvisioner: SandboxProvisionerFactory = ({
+  config,
+  logger,
+}) => {
+  const children = new Map<string, ChildProcess>();
+
+  // A process-tier sandbox dies with the server (module header). "exit"
+  // allows only synchronous work — kill() is.
+  process.once("exit", () => {
+    for (const child of children.values()) {
+      child.kill(DEPROVISION_SIGNAL);
+    }
+  });
+
+  function key(scope: SandboxScope, id: string): string {
+    return `${scope}:${id}`;
+  }
+
+  function ensure(
+    scope: SandboxScope,
+    id: string,
+    env: SandboxEnvironment,
+  ): void {
+    // No awaits from here to children.set — the double-spawn guard.
+    const existing = children.get(key(scope, id));
+    if (
+      existing !== undefined &&
+      existing.exitCode === null &&
+      !existing.killed
+    ) {
+      return; // Running — the fast path.
+    }
+
+    const workspaceRoot = path.join(
+      homedir(),
+      ".stigmer",
+      "sandboxes",
+      `${scope}-${id}`,
+    );
+    mkdirSync(workspaceRoot, { recursive: true });
+
+    const childEnv: NodeJS.ProcessEnv = {
+      ...process.env,
+      MODE: "local",
+      STIGMER_TASK_QUEUE: env.taskQueue,
+      WORKSPACE_ROOT_DIR: workspaceRoot,
+    };
+    if (config.backendEndpoint !== "") {
+      childEnv["STIGMER_BACKEND_ENDPOINT"] = config.backendEndpoint;
+    }
+    if (config.temporalAddress !== "") {
+      childEnv["TEMPORAL_SERVICE_ADDRESS"] = config.temporalAddress;
+    }
+    if (env.stigmerToken !== "") {
+      childEnv["STIGMER_TOKEN"] = env.stigmerToken;
+    }
+
+    // stdio inherits: the process tier's sandbox logs belong in the
+    // server's own stream (the container tiers get per-container logs).
+    const child = spawn(config.runnerCommand, [], {
+      env: childEnv,
+      stdio: "inherit",
+    });
+    children.set(key(scope, id), child);
+    logger.info("Local-process sandbox started", {
+      scope,
+      id,
+      pid: child.pid ?? -1,
+      taskQueue: env.taskQueue,
+    });
+    child.once("exit", (code, signal) => {
+      // Self-removal IS the repair arm: the next ensure sees absent.
+      // Guarded to THIS child — a deprovisioned child's late exit event
+      // must never clobber a replacement ensured under the same key.
+      if (children.get(key(scope, id)) === child) {
+        children.delete(key(scope, id));
+      }
+      logger.info("Local-process sandbox exited", {
+        scope,
+        id,
+        code: code ?? -1,
+        signal: signal ?? "",
+      });
+    });
+    child.once("error", (error) => {
+      // Spawn failures (command not found) surface here asynchronously;
+      // the exit handler above never fires for them. Same self-guard.
+      if (children.get(key(scope, id)) === child) {
+        children.delete(key(scope, id));
+      }
+      logger.error("Local-process sandbox failed to start", {
+        scope,
+        id,
+        command: config.runnerCommand,
+        error: error.message,
+      });
+    });
+  }
+
+  function deprovision(scope: SandboxScope, id: string): void {
+    const child = children.get(key(scope, id));
+    if (child === undefined) {
+      return; // Missing is success — idempotent teardown.
+    }
+    children.delete(key(scope, id));
+    child.kill(DEPROVISION_SIGNAL);
+    logger.info("Local-process sandbox deprovisioned", { scope, id });
+  }
+
+  const provisioner: SandboxProvisioner = {
+    async ensureSessionSandbox(sessionId, env) {
+      ensure("session", sessionId, env);
+    },
+    async deprovisionSessionSandbox(sessionId) {
+      deprovision("session", sessionId);
+    },
+    async ensureWorkflowSandbox(executionId, env) {
+      ensure("workflow", executionId, env);
+    },
+    async deprovisionWorkflowSandbox(executionId) {
+      deprovision("workflow", executionId);
+    },
+    async createConnectSandbox(connectRequestId, env) {
+      ensure("connect", connectRequestId, env);
+      return connectRequestId;
+    },
+    async deprovisionConnectSandbox(sandboxId) {
+      deprovision("connect", sandboxId);
+    },
+    async probe(scope, id): Promise<SandboxProbeState> {
+      const child = children.get(key(scope, id));
+      if (child === undefined || child.exitCode !== null || child.killed) {
+        // An exited child self-removed (or is mid-removal): a process has
+        // no "stopped but resumable" state — absent covers both.
+        return "absent";
+      }
+      return "running";
+    },
+  };
+  return provisioner;
+};

package/src/sandbox/naming.ts

@@ -0,0 +1,38 @@
+/**
+ * Deterministic sandbox object naming — generalized from the cloud
+ * edition's SandboxObjectNaming.java so both container drivers (and the
+ * cloud's own provisioner) name sandboxes identically: an operator
+ * moving between tiers sees one vocabulary.
+ *
+ * Base name: sbx-<scope-code>-<first 12 hex chars of SHA-256(id)> —
+ * DNS-1123-safe regardless of the id's alphabet or length (resource ids
+ * carry prefixes like ses_ that DNS labels reject; hashing sidesteps
+ * every alphabet/length edge). The full id travels in a label so the
+ * mapping is recoverable from the runtime object alone (gate ruling Q4:
+ * runtime-derived state, no store tables).
+ */
+import { createHash } from "node:crypto";
+
+import type { SandboxScope } from "./provisioner.js";
+
+/** The Java SandboxScope codes, byte-identical. */
+const SCOPE_CODES: Record<SandboxScope, string> = {
+  session: "ses",
+  workflow: "wfx",
+  connect: "mcp",
+};
+
+/** Label carrying the owning driver ("stigmer-server") — the reap/list filter. */
+export const SANDBOX_MANAGED_BY_LABEL = "stigmer.ai/managed-by";
+/** Label carrying the scope ("session" | "workflow" | "connect"). */
+export const SANDBOX_SCOPE_LABEL = "stigmer.ai/scope";
+/** Label carrying the full owning resource id (the Q4 runtime-derived link). */
+export const SANDBOX_ID_LABEL = "stigmer.ai/sandbox-id";
+
+export const SANDBOX_MANAGED_BY_VALUE = "stigmer-server";
+
+/** sbx-<code>-<12-hex> (SandboxObjectNaming.java's derivation, kept exactly). */
+export function sandboxBaseName(scope: SandboxScope, id: string): string {
+  const digest = createHash("sha256").update(id).digest("hex").slice(0, 12);
+  return `sbx-${SCOPE_CODES[scope]}-${digest}`;
+}

package/src/sandbox/provisioner.ts

@@ -0,0 +1,175 @@
+/**
+ * The sandbox-provisioner driver seam — convergence program 20260826.02,
+ * blueprint/03 §6d and DD-002, built by sub-project 20260827.05 (O6). The
+ * contract generalizes the cloud edition's production-proven Java
+ * strategy interface (stigmer-cloud
+ * domain/agentic/sandbox/SandboxProvisioner.java) so execution isolation
+ * is an OSS capability: a provisioner creates, repairs, and tears down
+ * the isolated runner that polls one execution-scoped Temporal task
+ * queue.
+ *
+ * Scope vocabulary (the Java interface's three variants, kept exactly):
+ *
+ *   - SESSION: long-lived, one sandbox per session, ensure is IDEMPOTENT
+ *     ensure-as-state-machine (absent → provision; stopped → start;
+ *     running → fast path). Invoked non-critically after the execution's
+ *     workflow starts (see steps.ts).
+ *   - WORKFLOW: ephemeral, one sandbox per workflow execution (shared by
+ *     the workflow AND its nested child agent executions via the wfexec:
+ *     queue-override lane — dispatch.ts). Ensured critically BEFORE the
+ *     execution persists; deprovisioned on the terminal phase transition.
+ *   - CONNECT: request-scoped, NOT idempotent; the caller must
+ *     deprovision in a finally block. Carried in the contract for the
+ *     cloud implementation (its MCP connect lane) — OSS does not invoke
+ *     it today because OSS connect runs on the shared runner queue (a
+ *     named non-goal, T01 gate ruling Q7).
+ *
+ * The probe is ensure-time LIVE-STATE inspection, never a boot-readiness
+ * wait (gate ruling Q5): the verified cloud design has NO readiness
+ * probes — a sandbox that never polls its queue surfaces as the
+ * activity's ScheduleToStartTimeout, with the ensure step's error
+ * pre-stamp naming the root cause.
+ *
+ * Selection follows the artifact-storage precedent (§6b): built-in
+ * drivers by name behind the SANDBOX_PROVISIONER_TYPE config knob,
+ * extension-registered names beyond them (extensions/drivers.ts), an
+ * unknown name a loud boot throw. The DEFAULT ("") is the external-runner
+ * posture — no provisioner constructed, ensure never invoked — which IS
+ * today's OSS behavior, named (gate ruling Q1): an operator-managed
+ * runner process polls the queues.
+ */
+import type { Logger } from "../boot/logger.js";
+
+/**
+ * The runtime handed to a provisioner for one sandbox: which queue the
+ * sandboxed runner must poll and the credential it authenticates with.
+ * Deliberately minimal (the Java SandboxEnvironment carries the same two
+ * load-bearing fields plus cloud-only accounting) — endpoints, images,
+ * and resource shapes are DRIVER configuration, not per-sandbox state.
+ */
+export interface SandboxEnvironment {
+  /** The Temporal task queue the sandboxed runner polls (session:{id} / wfexec:{id}). */
+  readonly taskQueue: string;
+  /**
+   * The runner credential injected as STIGMER_TOKEN. "" means none was
+   * minted (the provider's lane is disabled) — the sandbox still launches
+   * and EC decrypt falls back to redaction, the oss#535 posture.
+   */
+  readonly stigmerToken: string;
+}
+
+/** One sandbox's observed live state (the Q5 probe result). */
+export type SandboxProbeState = "absent" | "stopped" | "running";
+
+/** The scope discriminant, shared by probe and the drivers' naming. */
+export type SandboxScope = "session" | "workflow" | "connect";
+
+/**
+ * The driver contract. Implementations must be safe for concurrent use —
+ * ensure calls for the same id may race (the cloud accepts check-then-act
+ * overshoot, DD-002) and every arm must be idempotent except connect
+ * creation, which is documented one-shot.
+ */
+export interface SandboxProvisioner {
+  /**
+   * Ensure-as-state-machine for a session sandbox: absent → provision;
+   * stopped → start; running → fast path. Idempotent; safe to invoke on
+   * every execution create/recover for the session.
+   */
+  ensureSessionSandbox(
+    sessionId: string,
+    env: SandboxEnvironment,
+  ): Promise<void>;
+  /** Tears down the session sandbox; missing is success (idempotent). */
+  deprovisionSessionSandbox(sessionId: string): Promise<void>;
+  /**
+   * Ensures the per-execution workflow sandbox. Same state-machine
+   * semantics; the sandbox lives exactly as long as the execution runs.
+   */
+  ensureWorkflowSandbox(
+    executionId: string,
+    env: SandboxEnvironment,
+  ): Promise<void>;
+  /** Tears down the workflow sandbox; missing is success (idempotent). */
+  deprovisionWorkflowSandbox(executionId: string): Promise<void>;
+  /**
+   * Creates a request-scoped connect sandbox and returns the provider's
+   * sandbox id. NOT idempotent — the caller owns deprovision in a
+   * finally block. Unused by OSS wiring today (module header).
+   */
+  createConnectSandbox(
+    connectRequestId: string,
+    env: SandboxEnvironment,
+  ): Promise<string>;
+  /** Tears down a connect sandbox by provider id; missing is success. */
+  deprovisionConnectSandbox(sandboxId: string): Promise<void>;
+  /** Live-state inspection (Q5) — consumed by ensure arms and diagnostics. */
+  probe(scope: SandboxScope, id: string): Promise<SandboxProbeState>;
+}
+
+/**
+ * Driver configuration resolved from ServerConfig — what every built-in
+ * needs to launch a runner that can reach this server. Extension drivers
+ * receive the same bag and may read their own env beyond it.
+ */
+export interface SandboxDriverConfig {
+  /**
+   * The server endpoint AS REACHABLE FROM INSIDE a sandbox (a container
+   * cannot use this process's localhost). Injected as
+   * STIGMER_BACKEND_ENDPOINT.
+   */
+  readonly backendEndpoint: string;
+  /** Temporal address as reachable from inside a sandbox (TEMPORAL_SERVICE_ADDRESS). */
+  readonly temporalAddress: string;
+  /** The runner image for container-based drivers (docker/kubernetes). */
+  readonly runnerImage: string;
+  /** The runner executable for the local-process driver. */
+  readonly runnerCommand: string;
+  /** The namespace the kubernetes driver provisions into. */
+  readonly kubernetesNamespace: string;
+}
+
+/** Constructs a driver. Factories, not instances — an unselected driver constructs nothing (§6b). */
+export type SandboxProvisionerFactory = (options: {
+  readonly config: SandboxDriverConfig;
+  readonly logger: Logger;
+}) => SandboxProvisioner;
+
+/**
+ * The built-in driver names — reserved: an extension registering one of
+ * these is a boot throw (the registry's shadow rule, extensions/
+ * registry.ts). DD-002's isolation ladder: process → Docker → Kubernetes.
+ */
+export const BUILT_IN_SANDBOX_PROVISIONER_TYPES = [
+  "local-process",
+  "docker",
+  "kubernetes",
+] as const;
+
+/**
+ * Selects and constructs the configured provisioner, or undefined for
+ * the default external-runner posture (type ""). Unknown names are a
+ * loud boot throw — a typo'd knob must never silently run unisolated
+ * (the validateR2Config precedent).
+ */
+export function newSandboxProvisioner(
+  type: string,
+  options: { readonly config: SandboxDriverConfig; readonly logger: Logger },
+  builtInFactories: ReadonlyMap<string, SandboxProvisionerFactory>,
+  registeredFactories: ReadonlyMap<string, SandboxProvisionerFactory>,
+): SandboxProvisioner | undefined {
+  if (type === "") {
+    return undefined;
+  }
+  const factory = builtInFactories.get(type) ?? registeredFactories.get(type);
+  if (factory === undefined) {
+    const known = [
+      ...builtInFactories.keys(),
+      ...registeredFactories.keys(),
+    ].sort();
+    throw new Error(
+      `unknown sandbox provisioner type '${type}' — known types: '${known.join("', '")}'`,
+    );
+  }
+  return factory(options);
+}