@stigmer/server 3.18.0 → 3.19.0

package/src/extensions/__tests__/outbound-egress-points.test.ts

@@ -0,0 +1,58 @@
+/**
+ * Pins the outboundEgress driver point in the single-instance shape the
+ * registry already enforces for policyGrantScope and licenseStatus:
+ *
+ *   - `drivers.outboundEgress` — the address policy the composition root
+ *     builds the McpServer slice's one guarded fetch from; single instance;
+ *     absent = open source's relaxed posture installs at the compose.ts
+ *     consumption site.
+ *
+ * And the two exported postures: relaxed refuses only the link-local
+ * (cloud metadata) range, strict refuses loopback, private and unspecified
+ * too, and neither owns a copy of the ranges (both read the shared table).
+ */
+import { describe, expect, it } from "vitest";
+
+import { relaxedEgressPolicy, strictEgressPolicy } from "../outbound-egress.js";
+import { resolveExtensions } from "../registry.js";
+
+describe("the outboundEgress driver point", () => {
+  it("is undefined with no extensions — the relaxed posture installs at the consumption site", () => {
+    expect(resolveExtensions([]).drivers.outboundEgress).toBeUndefined();
+  });
+
+  it("carries the one registered instance through", () => {
+    const policy = strictEgressPolicy();
+    const resolved = resolveExtensions([{ name: "cloud-core", drivers: { outboundEgress: policy } }]);
+    expect(resolved.drivers.outboundEgress).toBe(policy);
+  });
+
+  it("throws on a second registration, naming both units", () => {
+    expect(() =>
+      resolveExtensions([
+        { name: "egress-a", drivers: { outboundEgress: strictEgressPolicy() } },
+        { name: "egress-b", drivers: { outboundEgress: relaxedEgressPolicy() } },
+      ]),
+    ).toThrowError(/extension 'egress-b' registers an OutboundEgressPolicy, but 'egress-a' already did/);
+  });
+});
+
+describe("the two postures", () => {
+  it("relaxed refuses only the link-local range, so a local MCP server stays reachable", () => {
+    const relaxed = relaxedEgressPolicy();
+    expect(relaxed.name).toBe("relaxed");
+    expect(relaxed.blockedReason("127.0.0.1")).toBeNull();
+    expect(relaxed.blockedReason("10.0.0.1")).toBeNull();
+    expect(relaxed.blockedReason("169.254.169.254")).toBe("link-local (cloud metadata)");
+  });
+
+  it("strict refuses loopback, private, link-local and unspecified addresses", () => {
+    const strict = strictEgressPolicy();
+    expect(strict.name).toBe("strict");
+    expect(strict.blockedReason("127.0.0.1")).toBe("loopback");
+    expect(strict.blockedReason("10.0.0.1")).toBe("private (RFC 1918)");
+    expect(strict.blockedReason("169.254.169.254")).toBe("link-local (cloud metadata)");
+    expect(strict.blockedReason("0.0.0.0")).toBe("unspecified");
+    expect(strict.blockedReason("104.16.0.1")).toBeNull();
+  });
+});

package/src/extensions/drivers.ts

@@ -31,6 +31,10 @@
  *     port, which kinds an edition grants on, and the tuple-half query
  *     engine only an authorization backend can answer) — landed with
  *     20260913.01, gate ruling Q-OR-10
+ *   - outbound egress (which addresses the control plane may dial when
+ *     it reaches a URL a user supplied: the MCP endpoint it probes at save
+ *     time and the login server it reaches on Sign in) — landed with the
+ *     save-time OAuth completion for URL-only MCP servers, 2026-09-19
  *
  * Merge rules (enforced by resolveExtensions, DD-006 §2b): the two
  * provider kinds are single-instance points — a second declaring unit is
@@ -54,6 +58,7 @@ import type { SandboxProvisionerFactory } from "../sandbox/provisioner.js";
 import type { AuthorizationQueryEngine } from "./authorization-queries.js";
 import type { IdentityFederation } from "./identity-federation.js";
 import type { LicenseStatusProvider } from "./license-status.js";
+import type { OutboundEgressPolicy } from "./outbound-egress.js";
 import type { ListReadScope } from "./list-read-scope.js";
 import type { OrganizationDirectory } from "./organization-directory.js";
 import type { PolicyGrantScope } from "./policy-grant-scope.js";
@@ -230,4 +235,16 @@ export interface ExtensionDrivers {
    * way (extensions/license-status.ts carries the contract).
    */
   readonly licenseStatus?: LicenseStatusProvider;
+  /**
+   * The outbound-egress policy (single-instance point): which addresses
+   * this edition's control plane may dial when it reaches a URL a user
+   * supplied. The composition root builds one guarded fetch from it and
+   * hands it to the McpServer connect slice, the only fetch its OAuth code
+   * and its save-time endpoint probe hold. When absent, open source's
+   * `relaxedEgressPolicy()` installs at the compose.ts consumption site:
+   * everything but the link-local (cloud metadata) range is allowed, so a
+   * server beside a self-hosted control plane keeps working
+   * (extensions/outbound-egress.ts carries the contract).
+   */
+  readonly outboundEgress?: OutboundEgressPolicy;
 }

package/src/extensions/outbound-egress.ts

@@ -0,0 +1,55 @@
+/**
+ * The outbound-egress driver point: WHICH addresses this edition's control
+ * plane may dial when it reaches a URL a user supplied. Single instance,
+ * registered as `drivers.outboundEgress` (the policyGrantScope shape: a
+ * driver point whose absence is open source's own behaviour). Absent, the
+ * composition root installs `relaxedEgressPolicy()`: everything but the
+ * link-local range is allowed, because a server beside a self-hosted
+ * control plane (`http://localhost:3000/mcp`, the proto's own example) is
+ * the normal case and the link-local range, which carries the cloud
+ * metadata endpoint, costs a local user nothing to refuse. The cloud
+ * registers `strictEgressPolicy()`: loopback, private, link-local and
+ * unspecified refused, because its control plane sits on infrastructure
+ * with reach to internal services.
+ *
+ * Who reads it: nobody in the domains directly. The composition root builds
+ * ONE guarded fetch from the policy (`@stigmer/outbound/egress`
+ * `guardedFetch`, which judges the first URL and every redirect hop) and
+ * hands it to the McpServer connect slice as `outboundFetch`, the only
+ * fetch the McpServer domain's OAuth code and its save-time endpoint probe
+ * hold. Before this point existed every OAuth fetch (discovery, dynamic
+ * client registration, the authorize preflight, token exchange and
+ * refresh) defaulted to the raw global `fetch` in every edition, which is
+ * the exposure the point closes.
+ *
+ * The contract every policy is held to:
+ *
+ *   - It judges ADDRESSES, not names: the check resolves a hostname and
+ *     asks about every address it has, so a name with one public and one
+ *     private record is refused. A policy that wanted a hostname allowlist
+ *     would be a different seam.
+ *   - It is TOTAL: an unparseable address is refused ("unrecognized"),
+ *     never a throw.
+ *   - It is SYNCHRONOUS: an edition's egress posture is a fact about where
+ *     it runs, never I/O.
+ *
+ * Both constructors are thin over the shared classification in
+ * `@stigmer/outbound/egress`, so a composition registers a posture and owns
+ * no copy of the ranges; the runner's `web_fetch` guard reads the same
+ * table, so the two processes refuse the same addresses under the same
+ * posture name.
+ */
+import { egressPolicyForPosture, type EgressPolicy } from "@stigmer/outbound/egress";
+
+/** The egress contract (single-instance point, ExtensionDrivers.outboundEgress). */
+export type OutboundEgressPolicy = EgressPolicy;
+
+/** Open source's own posture: only the link-local (cloud metadata) range is refused. */
+export function relaxedEgressPolicy(): OutboundEgressPolicy {
+  return egressPolicyForPosture("relaxed");
+}
+
+/** The managed-cloud posture: loopback, private, link-local and unspecified addresses refused. */
+export function strictEgressPolicy(): OutboundEgressPolicy {
+  return egressPolicyForPosture("strict");
+}

package/src/extensions/registry.ts

@@ -54,6 +54,7 @@ import { V1_VERSION } from "../encryption/v1-codec.js";
 import type { AuthorizationQueryEngine } from "./authorization-queries.js";
 import type { IdentityFederation } from "./identity-federation.js";
 import type { LicenseStatusProvider } from "./license-status.js";
+import type { OutboundEgressPolicy } from "./outbound-egress.js";
 import type { ListReadScope } from "./list-read-scope.js";
 import type { PolicyGrantScope } from "./policy-grant-scope.js";
 import type { ModelCatalogProvider } from "../domain/workflow/registry/model-catalog-provider.js";
@@ -278,6 +279,11 @@ export interface ResolvedExtensionDrivers {
    * built-in `absent` answer, so every edition serves getLicenseStatus.
    */
   readonly licenseStatus: LicenseStatusProvider | undefined;
+  /**
+   * The outbound-egress policy — undefined = compose.ts installs open
+   * source's relaxed posture (only the link-local range refused).
+   */
+  readonly outboundEgress: OutboundEgressPolicy | undefined;
 }
 
 /**
@@ -333,6 +339,8 @@ export function resolveExtensions(
   let authorizationQueriesDeclaredBy: string | undefined;
   let licenseStatus: LicenseStatusProvider | undefined;
   let licenseStatusDeclaredBy: string | undefined;
+  let outboundEgress: OutboundEgressPolicy | undefined;
+  let outboundEgressDeclaredBy: string | undefined;
   const artifactStorageDrivers = new Map<
     string,
     ArtifactStorageDriverFactory
@@ -534,6 +542,16 @@ export function resolveExtensions(
       licenseStatusDeclaredBy = unit.name;
     }
 
+    if (unit.drivers?.outboundEgress !== undefined) {
+      if (outboundEgressDeclaredBy !== undefined) {
+        throw new Error(
+          `extension '${unit.name}' registers an OutboundEgressPolicy, but '${outboundEgressDeclaredBy}' already did — exactly one may be composed`,
+        );
+      }
+      outboundEgress = unit.drivers.outboundEgress;
+      outboundEgressDeclaredBy = unit.name;
+    }
+
     if (unit.drivers?.artifactStorageDrivers !== undefined) {
       for (const [name, factory] of unit.drivers.artifactStorageDrivers) {
         if ((BUILT_IN_STORAGE_TYPES as ReadonlyArray<string>).includes(name)) {
@@ -660,6 +678,7 @@ export function resolveExtensions(
       policyGrantScope,
       authorizationQueries,
       licenseStatus,
+      outboundEgress,
     },
     services,
     workers,

package/src/index.ts

@@ -119,6 +119,16 @@ export type {
   LicenseStatusProvider,
   LicenseStatusReport,
 } from "./extensions/license-status.js";
+// The outbound-egress seam (drivers.outboundEgress): which addresses the
+// control plane may dial when it reaches a URL a user supplied. Both
+// postures are exported so a composition registers one line and owns no
+// copy of the address ranges (the classification lives in
+// @stigmer/outbound/egress, shared with the runner's web_fetch guard).
+export type { OutboundEgressPolicy } from "./extensions/outbound-egress.js";
+export {
+  relaxedEgressPolicy,
+  strictEgressPolicy,
+} from "./extensions/outbound-egress.js";
 // The 20260911.11 identity-account seams (Q-IA-9): the store PORT a
 // composition drives the domain through (drivers.identityAccountStore;
 // a driver throws DuplicateAccountError for a held id), the federation

package/src/pipeline/apiresource-labels.ts

@@ -82,6 +82,22 @@ export const PLUGIN_LABEL = `${RESERVED_LABEL_PREFIX}plugin`;
  */
 export const PLUGIN_VERSION_LABEL = `${RESERVED_LABEL_PREFIX}plugin-version`;
 
+/**
+ * How an MCP server's `spec.auth` came to be. The one value, `endpoint`,
+ * says the server itself completed it: the author supplied a URL and
+ * nothing about authentication, the endpoint answered the save-time probe
+ * with an OAuth challenge, and the server wrote the token variable, its
+ * declaration and the Bearer header (domain/mcpserver/complete-endpoint-auth.ts).
+ * The label is provenance, not permission: it lets the next save tell a
+ * completion it may reuse from an author's own `auth` it must not touch.
+ * Stamped through the server-stamped mechanism; dropped when the author
+ * writes their own `auth`.
+ */
+export const MCP_AUTH_LABEL = `${RESERVED_LABEL_PREFIX}mcp-auth`;
+
+/** The MCP_AUTH_LABEL value for a completion the endpoint's own challenge produced. */
+export const MCP_AUTH_ENDPOINT = "endpoint";
+
 /** The plugin id a resource's labels claim, or undefined when unlabelled. */
 export function pluginIdOf(
   metadata: ApiResourceMetadata | undefined,

package/src/sandbox/__tests__/docker.integration.test.ts

@@ -68,6 +68,7 @@ describe.skipIf(!optedIn || !dockerAnswers())(
       await driver.ensureSessionSandbox(sessionId, {
         taskQueue: `session:${sessionId}`,
         stigmerToken: "tok-docker-smoke",
+        callerClass: "user",
       });
       expect(await driver.probe("session", sessionId)).toBe("running");
 
@@ -91,6 +92,7 @@ describe.skipIf(!optedIn || !dockerAnswers())(
       await driver.ensureSessionSandbox(sessionId, {
         taskQueue: `session:${sessionId}`,
         stigmerToken: "tok-docker-smoke",
+        callerClass: "user",
       });
       expect(await driver.probe("session", sessionId)).toBe("running");
 

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

@@ -89,7 +89,11 @@ function fakeGateway(
   };
 }
 
-const env = { taskQueue: "session:ses_1", stigmerToken: "tok-1" };
+const env = {
+  taskQueue: "session:ses_1",
+  stigmerToken: "tok-1",
+  callerClass: "user",
+};
 
 describe("the ensure state machine", () => {
   it("absent → Secret, PVC, Deployment — in that order, no readiness wait", async () => {
@@ -211,7 +215,11 @@ describe("the manifest shapes (the Java SandboxManifestFactory pins)", () => {
   });
 
   it("a token-less sandbox omits the token env but keeps the (empty) Secret", () => {
-    const tokenless = { taskQueue: "session:ses_1", stigmerToken: "" };
+    const tokenless = {
+      taskQueue: "session:ses_1",
+      stigmerToken: "",
+      callerClass: "user",
+    };
     const deployment = buildSandboxDeployment(
       "session",
       "ses_1",

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

@@ -81,6 +81,7 @@ describe.skipIf(process.platform === "win32")(
       await driver.ensureSessionSandbox("ses_smoke", {
         taskQueue: "session:ses_smoke",
         stigmerToken: "tok-smoke",
+        callerClass: "user",
       });
       await vi.waitFor(() => expect(spawnCount()).toBe(1), {
         timeout: CHILD_SETTLE_TIMEOUT_MS,
@@ -91,6 +92,7 @@ describe.skipIf(process.platform === "win32")(
       await driver.ensureSessionSandbox("ses_smoke", {
         taskQueue: "session:ses_smoke",
         stigmerToken: "tok-smoke",
+        callerClass: "user",
       });
       expect(spawnCount()).toBe(1);
 
@@ -124,6 +126,7 @@ describe.skipIf(process.platform === "win32")(
       await driver.ensureSessionSandbox("ses_smoke", {
         taskQueue: "session:ses_smoke",
         stigmerToken: "",
+        callerClass: "user",
       });
       await vi.waitFor(() => expect(spawnCount()).toBe(2), {
         timeout: CHILD_SETTLE_TIMEOUT_MS,

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

@@ -11,7 +11,10 @@
  *   - the terminal observer deprovisions exactly on transitions INTO a
  *     terminal phase, fire-and-forget, and swallows (logs) teardown
  *     failures;
- *   - a disabled mint lane launches token-less rather than failing.
+ *   - a disabled mint lane launches token-less rather than failing;
+ *   - the caller splits two ways on both lanes: the identity id reaches
+ *     the credential mint, the caller class reaches the driver's
+ *     environment unchanged (a composed lane such as `guest` included).
  */
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -53,14 +56,25 @@ import {
   ensureWorkflowSandboxForExecution,
   newWorkflowSandboxTerminalObserver,
   SANDBOX_PROVISIONING_FAILED_PREFIX,
+  type SandboxCaller,
 } from "../steps.js";
 
 /**
- * The caller identity the ensure bodies thread into the credential mint
- * (C4): the OSS execution-scoped mint ignores it, so these tests pass a
- * fixed value and the token assertions stay binding-shaped.
+ * The caller the ensure bodies split two ways: the identity id into the
+ * credential mint (C4 — the OSS execution-scoped mint ignores it, so the
+ * token assertions stay binding-shaped) and the class onto the driver's
+ * environment. `user` is the plain lane; the class-propagation cases hand
+ * in a composed lane's word to prove the body copies, never normalises.
  */
 const TEST_CALLER_IDENTITY_ID = "ida_test_caller";
+const TEST_CALLER: SandboxCaller = {
+  identityId: TEST_CALLER_IDENTITY_ID,
+  callerClass: "user",
+};
+const GUEST_CALLER: SandboxCaller = {
+  identityId: "ida_guest_caller",
+  callerClass: "guest",
+};
 
 const silentLogger = createLogger({
   level: "error",
@@ -235,7 +249,7 @@ describe("the session lane (ensureSessionSandboxForExecution)", () => {
         temporalConfig: sessionRoutingCloudDefault,
       },
       execution,
-      TEST_CALLER_IDENTITY_ID,
+      TEST_CALLER,
     );
     expect(provisioner.ensured).toEqual([
       {
@@ -244,11 +258,32 @@ describe("the session lane (ensureSessionSandboxForExecution)", () => {
         env: {
           taskQueue: `session:${sessionId}`,
           stigmerToken: `tok-${execution.metadata?.id ?? ""}`,
+          callerClass: "user",
         },
       },
     ]);
   });
 
+  it("hands the caller's class to the driver unchanged and the caller's id to the mint", async () => {
+    const provisioner = fakeProvisioner();
+    const credentials = capabilityCredentials();
+    const { execution } = await seed(ExecutionTarget.CLOUD);
+    await ensureSessionSandboxForExecution(
+      {
+        store,
+        logger: silentLogger,
+        lane: lane(provisioner, credentials),
+        temporalConfig: sessionRoutingCloudDefault,
+      },
+      execution,
+      GUEST_CALLER,
+    );
+    expect(provisioner.ensured[0]?.env.callerClass).toBe("guest");
+    expect(credentials.minted[0]?.callerIdentityId).toBe(
+      GUEST_CALLER.identityId,
+    );
+  });
+
   it("delegates the mint to the capability provider with the full provisioning context (C4)", async () => {
     const provisioner = fakeProvisioner();
     const credentials = capabilityCredentials();
@@ -277,7 +312,7 @@ describe("the session lane (ensureSessionSandboxForExecution)", () => {
         temporalConfig: sessionRoutingCloudDefault,
       },
       execution,
-      TEST_CALLER_IDENTITY_ID,
+      TEST_CALLER,
     );
 
     expect(credentials.minted).toEqual([
@@ -303,7 +338,7 @@ describe("the session lane (ensureSessionSandboxForExecution)", () => {
         temporalConfig: sessionRoutingCloudDefault,
       },
       execution,
-      TEST_CALLER_IDENTITY_ID,
+      TEST_CALLER,
     );
     expect(provisioner.ensured).toEqual([]);
   });
@@ -327,7 +362,7 @@ describe("the session lane (ensureSessionSandboxForExecution)", () => {
         temporalConfig: sessionRoutingCloudDefault,
       },
       execution,
-      TEST_CALLER_IDENTITY_ID,
+      TEST_CALLER,
     );
   });
 
@@ -345,7 +380,7 @@ describe("the session lane (ensureSessionSandboxForExecution)", () => {
         temporalConfig: sessionRoutingCloudDefault,
       },
       execution,
-      TEST_CALLER_IDENTITY_ID,
+      TEST_CALLER,
     );
     expect(provisioner.ensured).toEqual([]);
   });
@@ -366,7 +401,7 @@ describe("the session lane (ensureSessionSandboxForExecution)", () => {
         ),
       },
       execution,
-      TEST_CALLER_IDENTITY_ID,
+      TEST_CALLER,
     );
     expect(provisioner.ensured).toEqual([]);
   });
@@ -382,7 +417,7 @@ describe("the session lane (ensureSessionSandboxForExecution)", () => {
         temporalConfig: sessionRoutingCloudDefault,
       },
       execution,
-      TEST_CALLER_IDENTITY_ID,
+      TEST_CALLER,
     );
     expect(provisioner.ensured[0]?.env.stigmerToken).toBe("");
   });
@@ -401,7 +436,7 @@ describe("the session lane (ensureSessionSandboxForExecution)", () => {
         temporalConfig: sessionRoutingCloudDefault,
       },
       execution,
-      TEST_CALLER_IDENTITY_ID,
+      TEST_CALLER,
     );
     const stamped = await store.getResource(
       ApiResourceKind.agent_execution,
@@ -439,7 +474,7 @@ describe("the session lane (ensureSessionSandboxForExecution)", () => {
         temporalConfig: sessionRoutingCloudDefault,
       },
       execution,
-      TEST_CALLER_IDENTITY_ID,
+      TEST_CALLER,
     );
     const after = await store.getResource(
       ApiResourceKind.agent_execution,
@@ -467,17 +502,35 @@ describe("the workflow lane (ensureWorkflowSandboxForExecution)", () => {
         temporalConfig: executionRoutingConfig,
       },
       workflowExecution(ExecutionTarget.CLOUD),
-      TEST_CALLER_IDENTITY_ID,
+      TEST_CALLER,
     );
     expect(provisioner.ensured).toEqual([
       {
         scope: "workflow",
         id: "wfx_sbx_1",
-        env: { taskQueue: "wfexec:wfx_sbx_1", stigmerToken: "tok-wfx_sbx_1" },
+        env: {
+          taskQueue: "wfexec:wfx_sbx_1",
+          stigmerToken: "tok-wfx_sbx_1",
+          callerClass: "user",
+        },
       },
     ]);
   });
 
+  it("hands the caller's class to the driver unchanged on the workflow lane", async () => {
+    const provisioner = fakeProvisioner();
+    await ensureWorkflowSandboxForExecution(
+      {
+        logger: silentLogger,
+        lane: lane(provisioner),
+        temporalConfig: executionRoutingConfig,
+      },
+      workflowExecution(ExecutionTarget.CLOUD),
+      GUEST_CALLER,
+    );
+    expect(provisioner.ensured[0]?.env.callerClass).toBe("guest");
+  });
+
   it("delegates the mint to the capability provider on the workflow scope (C4)", async () => {
     const provisioner = fakeProvisioner();
     const credentials = capabilityCredentials();
@@ -491,7 +544,7 @@ describe("the workflow lane (ensureWorkflowSandboxForExecution)", () => {
         metadata: { id: "wfx_sbx_cap", name: "wfx_sbx_cap", org: "org-test" },
         spec: { executionTarget: ExecutionTarget.CLOUD },
       }),
-      TEST_CALLER_IDENTITY_ID,
+      TEST_CALLER,
     );
     expect(credentials.minted).toEqual([
       {
@@ -514,7 +567,7 @@ describe("the workflow lane (ensureWorkflowSandboxForExecution)", () => {
         temporalConfig: executionRoutingConfig,
       },
       workflowExecution(ExecutionTarget.LOCAL),
-      TEST_CALLER_IDENTITY_ID,
+      TEST_CALLER,
     );
     await ensureWorkflowSandboxForExecution(
       {
@@ -528,7 +581,7 @@ describe("the workflow lane (ensureWorkflowSandboxForExecution)", () => {
         ),
       },
       workflowExecution(ExecutionTarget.CLOUD),
-      TEST_CALLER_IDENTITY_ID,
+      TEST_CALLER,
     );
     expect(provisioner.ensured).toEqual([]);
   });
@@ -545,7 +598,7 @@ describe("the workflow lane (ensureWorkflowSandboxForExecution)", () => {
           temporalConfig: executionRoutingConfig,
         },
         workflowExecution(ExecutionTarget.CLOUD),
-        TEST_CALLER_IDENTITY_ID,
+        TEST_CALLER,
       );
       expect.unreachable("the workflow lane must throw on failure");
     } catch (error) {

package/src/sandbox/kubernetes.ts

@@ -85,7 +85,14 @@ const RUNNER_RESOURCES = {
   limits: { cpu: "2", memory: "2Gi" },
 } as const;
 
-/** The persistent-workspace scopes (SandboxScope.persistentWorkspace). */
+/**
+ * The persistent-workspace scopes (SandboxScope.persistentWorkspace).
+ * Durability here is decided by SCOPE alone: this driver reads neither the
+ * environment's caller class nor any per-session policy, so every session
+ * keeps its PVC whoever asked. A driver that gives some caller classes a
+ * workspace that dies with the conversation is a composition's choice
+ * built on SandboxEnvironment.callerClass, not a built-in behaviour.
+ */
 const PERSISTENT_SCOPES: ReadonlySet<SandboxScope> = new Set([
   "session",
   "workflow",

package/src/sandbox/provisioner.ts

@@ -39,13 +39,16 @@
  * runner process polls the queues.
  */
 import type { Logger } from "../boot/logger.js";
+import type { CallerClass } from "../extensions/identity.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.
+ * What is TRUE about one provisioning request, handed to a driver: which
+ * queue the sandboxed runner must poll, the credential it authenticates
+ * with, and the class of the caller whose request is being served. Facts
+ * only — what a driver DOES with them (the workspace's durability, the
+ * pod's shape, whether a warm pool is consulted) is driver policy and
+ * never travels here. 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}). */
@@ -56,6 +59,18 @@ export interface SandboxEnvironment {
    * and EC decrypt falls back to redaction, the oss#535 posture.
    */
   readonly stigmerToken: string;
+  /**
+   * The class of the caller whose request provisioned this sandbox — the
+   * identity interceptor's word for it (`user`, `internal`, a composed
+   * verifier's own lane such as a guest or a scheduled fire). A driver
+   * that gives some session classes a workspace that does not outlive the
+   * conversation reads it here; the built-in drivers (`local-process`,
+   * `docker`, `kubernetes`) ignore it and keep every session persistent.
+   * Required rather than optional so a construction site that forgets it
+   * fails to compile instead of silently reading as a persistent user
+   * session to every driver.
+   */
+  readonly callerClass: CallerClass;
 }
 
 /** One sandbox's observed live state (the Q5 probe result). */