@stigmer/server 3.14.0-dev.20260910084630

package/src/sandbox/__tests__/kubernetes.test.ts

@@ -0,0 +1,228 @@
+/**
+ * Pins the Kubernetes driver's ensure state machine and manifest shapes
+ * against the Java provisioner it generalizes (§6d, O6) — over a fake
+ * gateway, no cluster:
+ *
+ *   - absent → Secret first, PVC for persistent scopes, then Deployment;
+ *     no readiness wait (gate ruling Q5);
+ *   - replicas 0 → scale to 1, nothing re-applied;
+ *   - running → the fast path applies nothing (defer-restart, Q6);
+ *   - deprovision deletes Deployment + Secret (+ PVC when persistent);
+ *   - the manifests carry the Java shapes: Recreate, the runner command,
+ *     MODE=local, the secretKeyRef token env only when a token exists,
+ *     the empty Secret for token-less sandboxes.
+ */
+import { describe, expect, it } from "vitest";
+
+import type {
+  V1Deployment,
+  V1PersistentVolumeClaim,
+  V1Secret,
+} from "@kubernetes/client-node";
+
+import { sandboxBaseName } from "../naming.js";
+import type { SandboxDriverConfig } from "../provisioner.js";
+import type { KubernetesSandboxGateway } from "../kubernetes.js";
+import {
+  buildSandboxDeployment,
+  buildSandboxSecret,
+  newKubernetesSandboxProvisionerOverGateway,
+} from "../kubernetes.js";
+
+const silentLogger = { info: () => {} };
+
+const config: SandboxDriverConfig = {
+  backendEndpoint: "http://stigmer-server.stigmer.svc:7234",
+  temporalAddress: "temporal.stigmer.svc:7233",
+  runnerImage: "ghcr.io/stigmer/runner:latest",
+  runnerCommand: "stigmer-runner",
+  kubernetesNamespace: "stigmer-sandboxes",
+};
+
+function fakeGateway(
+  replicasByName: Map<string, number>,
+): KubernetesSandboxGateway & {
+  calls: string[];
+  applied: {
+    secrets: V1Secret[];
+    pvcs: V1PersistentVolumeClaim[];
+    deployments: V1Deployment[];
+  };
+} {
+  const calls: string[] = [];
+  const applied = {
+    secrets: [] as V1Secret[],
+    pvcs: [] as V1PersistentVolumeClaim[],
+    deployments: [] as V1Deployment[],
+  };
+  return {
+    calls,
+    applied,
+    async deploymentReplicas(name) {
+      calls.push(`replicas:${name}`);
+      return replicasByName.get(name);
+    },
+    async applySecret(secret) {
+      calls.push(`applySecret:${secret.metadata?.name ?? ""}`);
+      applied.secrets.push(secret);
+    },
+    async applyPvc(pvc) {
+      calls.push(`applyPvc:${pvc.metadata?.name ?? ""}`);
+      applied.pvcs.push(pvc);
+    },
+    async applyDeployment(deployment) {
+      calls.push(`applyDeployment:${deployment.metadata?.name ?? ""}`);
+      applied.deployments.push(deployment);
+    },
+    async scaleDeployment(name, replicas) {
+      calls.push(`scale:${name}:${replicas}`);
+    },
+    async deleteDeployment(name) {
+      calls.push(`deleteDeployment:${name}`);
+    },
+    async deleteSecret(name) {
+      calls.push(`deleteSecret:${name}`);
+    },
+    async deletePvc(name) {
+      calls.push(`deletePvc:${name}`);
+    },
+  };
+}
+
+const env = { taskQueue: "session:ses_1", stigmerToken: "tok-1" };
+
+describe("the ensure state machine", () => {
+  it("absent → Secret, PVC, Deployment — in that order, no readiness wait", async () => {
+    const gateway = fakeGateway(new Map());
+    const driver = newKubernetesSandboxProvisionerOverGateway(
+      gateway,
+      config,
+      silentLogger,
+    );
+    await driver.ensureSessionSandbox("ses_1", env);
+    const base = sandboxBaseName("session", "ses_1");
+    expect(gateway.calls).toEqual([
+      `replicas:${base}`,
+      `applySecret:${base}-env`,
+      `applyPvc:${base}-workspace`,
+      `applyDeployment:${base}`,
+    ]);
+  });
+
+  it("connect scope rides emptyDir — no PVC applied", async () => {
+    const gateway = fakeGateway(new Map());
+    const driver = newKubernetesSandboxProvisionerOverGateway(
+      gateway,
+      config,
+      silentLogger,
+    );
+    await driver.createConnectSandbox("mcp_1", env);
+    expect(gateway.calls.some((c) => c.startsWith("applyPvc"))).toBe(false);
+    const deployment = gateway.applied.deployments[0];
+    expect(
+      deployment?.spec?.template.spec?.volumes?.[0]?.emptyDir,
+    ).toBeDefined();
+  });
+
+  it("stopped (replicas 0) → scale to 1, nothing re-applied", async () => {
+    const base = sandboxBaseName("session", "ses_1");
+    const gateway = fakeGateway(new Map([[base, 0]]));
+    const driver = newKubernetesSandboxProvisionerOverGateway(
+      gateway,
+      config,
+      silentLogger,
+    );
+    await driver.ensureSessionSandbox("ses_1", env);
+    expect(gateway.calls).toEqual([`replicas:${base}`, `scale:${base}:1`]);
+  });
+
+  it("running → the fast path applies nothing (defer-restart)", async () => {
+    const base = sandboxBaseName("session", "ses_1");
+    const gateway = fakeGateway(new Map([[base, 1]]));
+    const driver = newKubernetesSandboxProvisionerOverGateway(
+      gateway,
+      config,
+      silentLogger,
+    );
+    await driver.ensureSessionSandbox("ses_1", env);
+    expect(gateway.calls).toEqual([`replicas:${base}`]);
+  });
+
+  it("deprovision deletes Deployment + Secret + PVC for persistent scopes", async () => {
+    const gateway = fakeGateway(new Map());
+    const driver = newKubernetesSandboxProvisionerOverGateway(
+      gateway,
+      config,
+      silentLogger,
+    );
+    await driver.deprovisionWorkflowSandbox("wfx_1");
+    const base = sandboxBaseName("workflow", "wfx_1");
+    expect(gateway.calls).toEqual([
+      `deleteDeployment:${base}`,
+      `deleteSecret:${base}-env`,
+      `deletePvc:${base}-workspace`,
+    ]);
+  });
+
+  it("probe maps replicas onto absent/stopped/running", async () => {
+    const base = sandboxBaseName("session", "ses_1");
+    for (const [replicas, expected] of [
+      [undefined, "absent"],
+      [0, "stopped"],
+      [1, "running"],
+    ] as const) {
+      const gateway = fakeGateway(
+        replicas === undefined ? new Map() : new Map([[base, replicas]]),
+      );
+      const driver = newKubernetesSandboxProvisionerOverGateway(
+        gateway,
+        config,
+        silentLogger,
+      );
+      expect(await driver.probe("session", "ses_1")).toBe(expected);
+    }
+  });
+});
+
+describe("the manifest shapes (the Java SandboxManifestFactory pins)", () => {
+  it("the Deployment carries Recreate, the runner command, and the env contract", () => {
+    const deployment = buildSandboxDeployment("session", "ses_1", env, config);
+    expect(deployment.spec?.strategy?.type).toBe("Recreate");
+    const container = deployment.spec?.template.spec?.containers[0];
+    expect(container?.command).toEqual(["node", "/runner/dist/main.js"]);
+    const envByName = new Map(
+      (container?.env ?? []).map((entry) => [entry.name, entry]),
+    );
+    expect(envByName.get("MODE")?.value).toBe("local");
+    expect(envByName.get("STIGMER_TASK_QUEUE")?.value).toBe("session:ses_1");
+    expect(envByName.get("STIGMER_BACKEND_ENDPOINT")?.value).toBe(
+      config.backendEndpoint,
+    );
+    expect(envByName.get("TEMPORAL_SERVICE_ADDRESS")?.value).toBe(
+      config.temporalAddress,
+    );
+    expect(envByName.get("WORKSPACE_ROOT_DIR")?.value).toBe("/workspace");
+    expect(envByName.get("STIGMER_TOKEN")?.valueFrom?.secretKeyRef?.name).toBe(
+      `${sandboxBaseName("session", "ses_1")}-env`,
+    );
+    expect(deployment.spec?.template.spec?.automountServiceAccountToken).toBe(
+      false,
+    );
+  });
+
+  it("a token-less sandbox omits the token env but keeps the (empty) Secret", () => {
+    const tokenless = { taskQueue: "session:ses_1", stigmerToken: "" };
+    const deployment = buildSandboxDeployment(
+      "session",
+      "ses_1",
+      tokenless,
+      config,
+    );
+    const names = (
+      deployment.spec?.template.spec?.containers[0]?.env ?? []
+    ).map((entry) => entry.name);
+    expect(names).not.toContain("STIGMER_TOKEN");
+    const secret = buildSandboxSecret("session", "ses_1", "");
+    expect(secret.stringData).toEqual({});
+  });
+});

package/src/sandbox/__tests__/local-process.integration.test.ts

@@ -0,0 +1,124 @@
+/**
+ * Integration smoke for the local-process driver (§6d, O6): real child
+ * processes, the full ensure → fast-path → probe → deprovision cycle,
+ * and the env contract the runner reads (config.ts's variables) —
+ * proven by a stand-in script that dumps its environment where the test
+ * can read it, so no real runner install is needed.
+ *
+ * Unix-only like the runner itself; deterministic (poll with timeout,
+ * never sleep).
+ */
+import {
+  chmodSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { afterAll, describe, expect, it, vi } from "vitest";
+
+import { createLogger } from "../../boot/logger.js";
+import { newLocalProcessSandboxProvisioner } from "../local-process.js";
+import type { SandboxDriverConfig } from "../provisioner.js";
+
+const silentLogger = createLogger({
+  level: "error",
+  pretty: false,
+  write: () => {},
+});
+
+describe.skipIf(process.platform === "win32")(
+  "local-process driver (integration)",
+  () => {
+    const dir = mkdtempSync(path.join(tmpdir(), "sbx-localproc-"));
+    // The stand-in runner: records its environment, then stays alive
+    // polling like a worker would (the driver kills it on deprovision).
+    const script = path.join(dir, "fake-runner.sh");
+    writeFileSync(
+      script,
+      `#!/bin/sh\nenv > "${dir}/env-$$.dump"\necho "$$" >> "${dir}/spawns.log"\nwhile true; do sleep 1; done\n`,
+    );
+    chmodSync(script, 0o755);
+
+    const config: SandboxDriverConfig = {
+      backendEndpoint: "http://127.0.0.1:7234",
+      temporalAddress: "127.0.0.1:7233",
+      runnerImage: "unused-by-this-driver",
+      runnerCommand: script,
+      kubernetesNamespace: "unused-by-this-driver",
+    };
+    const driver = newLocalProcessSandboxProvisioner({
+      config,
+      logger: silentLogger,
+    });
+
+    afterAll(async () => {
+      await driver.deprovisionSessionSandbox("ses_smoke");
+      rmSync(dir, { recursive: true, force: true });
+    });
+
+    function spawnCount(): number {
+      const log = path.join(dir, "spawns.log");
+      if (!existsSync(log)) {
+        return 0;
+      }
+      return readFileSync(log, "utf8").trim().split("\n").filter(Boolean)
+        .length;
+    }
+
+    it("ensure spawns once, injects the runner env contract, and is idempotent", async () => {
+      await driver.ensureSessionSandbox("ses_smoke", {
+        taskQueue: "session:ses_smoke",
+        stigmerToken: "tok-smoke",
+      });
+      await vi.waitFor(() => expect(spawnCount()).toBe(1));
+      expect(await driver.probe("session", "ses_smoke")).toBe("running");
+
+      // Fast path: a second ensure must not spawn a second process.
+      await driver.ensureSessionSandbox("ses_smoke", {
+        taskQueue: "session:ses_smoke",
+        stigmerToken: "tok-smoke",
+      });
+      expect(spawnCount()).toBe(1);
+
+      // The env dump carries the contract the runner's config.ts reads.
+      const dumpName = readFileSync(path.join(dir, "spawns.log"), "utf8")
+        .trim()
+        .split("\n")[0];
+      const dump = readFileSync(path.join(dir, `env-${dumpName}.dump`), "utf8");
+      expect(dump).toContain("MODE=local");
+      expect(dump).toContain("STIGMER_TASK_QUEUE=session:ses_smoke");
+      expect(dump).toContain("STIGMER_TOKEN=tok-smoke");
+      expect(dump).toContain(
+        `STIGMER_BACKEND_ENDPOINT=${config.backendEndpoint}`,
+      );
+      expect(dump).toContain(
+        `TEMPORAL_SERVICE_ADDRESS=${config.temporalAddress}`,
+      );
+      expect(dump).toMatch(/WORKSPACE_ROOT_DIR=.+session-ses_smoke/);
+    });
+
+    it("deprovision kills the child; probe reports absent; re-ensure respawns", async () => {
+      await driver.deprovisionSessionSandbox("ses_smoke");
+      await vi.waitFor(async () => {
+        expect(await driver.probe("session", "ses_smoke")).toBe("absent");
+      });
+
+      // The repair arm without stored state: a fresh ensure respawns.
+      await driver.ensureSessionSandbox("ses_smoke", {
+        taskQueue: "session:ses_smoke",
+        stigmerToken: "",
+      });
+      await vi.waitFor(() => expect(spawnCount()).toBe(2));
+      expect(await driver.probe("session", "ses_smoke")).toBe("running");
+    });
+
+    it("deprovision of an absent sandbox is success (idempotent)", async () => {
+      await driver.deprovisionWorkflowSandbox("wfx_never_existed");
+    });
+  },
+);

package/src/sandbox/__tests__/provisioner.test.ts

@@ -0,0 +1,145 @@
+/**
+ * Pins the sandbox driver seam's selection and naming contracts (§6d,
+ * O6):
+ *
+ *   - "" selects NO provisioner — the external-runner default whose
+ *     byte-identity the conformance rosters ride;
+ *   - unknown names are loud boot throws listing every known type;
+ *   - extension-registered factories are reachable behind the knob but
+ *     can never shadow a built-in name;
+ *   - sandboxBaseName is the Java SandboxObjectNaming derivation
+ *     (sbx-<code>-<12-hex-sha256>), deterministic and DNS-1123-safe for
+ *     resource-id alphabets.
+ */
+import { describe, expect, it } from "vitest";
+
+import { createLogger } from "../../boot/logger.js";
+import { sandboxBaseName } from "../naming.js";
+import type {
+  SandboxDriverConfig,
+  SandboxProvisioner,
+  SandboxProvisionerFactory,
+} from "../provisioner.js";
+import {
+  BUILT_IN_SANDBOX_PROVISIONER_TYPES,
+  newSandboxProvisioner,
+} from "../provisioner.js";
+
+const silentLogger = createLogger({
+  level: "error",
+  pretty: false,
+  write: () => {},
+});
+
+const driverConfig: SandboxDriverConfig = {
+  backendEndpoint: "http://host.docker.internal:7234",
+  temporalAddress: "host.docker.internal:7233",
+  runnerImage: "ghcr.io/stigmer/runner:latest",
+  runnerCommand: "stigmer-runner",
+  kubernetesNamespace: "stigmer-sandboxes",
+};
+
+function fakeFactory(marker: {
+  constructed: number;
+}): SandboxProvisionerFactory {
+  return () => {
+    marker.constructed += 1;
+    return {} as SandboxProvisioner;
+  };
+}
+
+describe("newSandboxProvisioner selection", () => {
+  it("empty type selects nothing — the external-runner default", () => {
+    const provisioner = newSandboxProvisioner(
+      "",
+      { config: driverConfig, logger: silentLogger },
+      new Map(),
+      new Map(),
+    );
+    expect(provisioner).toBeUndefined();
+  });
+
+  it("an unknown type is a loud boot throw naming the known set", () => {
+    const marker = { constructed: 0 };
+    expect(() =>
+      newSandboxProvisioner(
+        "daytona",
+        { config: driverConfig, logger: silentLogger },
+        new Map([["docker", fakeFactory(marker)]]),
+        new Map([["fly-machines", fakeFactory(marker)]]),
+      ),
+    ).toThrowError(
+      "unknown sandbox provisioner type 'daytona' — known types: 'docker', 'fly-machines'",
+    );
+    expect(marker.constructed, "no factory may run on a failed selection").toBe(
+      0,
+    );
+  });
+
+  it("selects a built-in factory and constructs it exactly once", () => {
+    const marker = { constructed: 0 };
+    const provisioner = newSandboxProvisioner(
+      "docker",
+      { config: driverConfig, logger: silentLogger },
+      new Map([["docker", fakeFactory(marker)]]),
+      new Map(),
+    );
+    expect(provisioner).toBeDefined();
+    expect(marker.constructed).toBe(1);
+  });
+
+  it("selects an extension-registered factory beyond the built-ins", () => {
+    const marker = { constructed: 0 };
+    const provisioner = newSandboxProvisioner(
+      "fly-machines",
+      { config: driverConfig, logger: silentLogger },
+      new Map(),
+      new Map([["fly-machines", fakeFactory(marker)]]),
+    );
+    expect(provisioner).toBeDefined();
+    expect(marker.constructed).toBe(1);
+  });
+
+  it("an unselected driver constructs nothing (§6b's factory discipline)", () => {
+    const selected = { constructed: 0 };
+    const bystander = { constructed: 0 };
+    newSandboxProvisioner(
+      "docker",
+      { config: driverConfig, logger: silentLogger },
+      new Map([
+        ["docker", fakeFactory(selected)],
+        ["kubernetes", fakeFactory(bystander)],
+      ]),
+      new Map(),
+    );
+    expect(bystander.constructed).toBe(0);
+  });
+
+  it("the built-in name set is DD-002's isolation ladder", () => {
+    expect([...BUILT_IN_SANDBOX_PROVISIONER_TYPES]).toEqual([
+      "local-process",
+      "docker",
+      "kubernetes",
+    ]);
+  });
+});
+
+describe("sandboxBaseName (the Java SandboxObjectNaming derivation)", () => {
+  it("is deterministic per scope+id and distinct across scopes", () => {
+    const a = sandboxBaseName("session", "ses_01ABC");
+    expect(a).toBe(sandboxBaseName("session", "ses_01ABC"));
+    expect(a).not.toBe(sandboxBaseName("workflow", "ses_01ABC"));
+    expect(a).not.toBe(sandboxBaseName("session", "ses_01ABD"));
+  });
+
+  it("emits the sbx-<code>-<12-hex> shape, DNS-safe for id alphabets", () => {
+    for (const [scope, code] of [
+      ["session", "ses"],
+      ["workflow", "wfx"],
+      ["connect", "mcp"],
+    ] as const) {
+      const name = sandboxBaseName(scope, "wfx_01J_UNDERSCORED.id");
+      expect(name).toMatch(new RegExp(`^sbx-${code}-[0-9a-f]{12}$`));
+    }
+  });
+});