@stigmer/server 3.16.1-dev.20260917224426 → 3.18.0-dev.20260918103812

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). */

package/src/sandbox/steps.ts

@@ -50,6 +50,7 @@ import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/
 
 import type { Logger } from "../boot/logger.js";
 import type { AgentExecutionTemporalConfig } from "../domain/agentexecution/temporal/config.js";
+import type { CallerIdentity } from "../extensions/identity.js";
 import {
   WORKFLOW_ROUTING_EXECUTION,
   type WorkflowExecutionTemporalConfig,
@@ -72,6 +73,17 @@ import { mintSandboxToken, type SandboxLane } from "./lane.js";
 export const SANDBOX_PROVISIONING_FAILED_PREFIX =
   "Sandbox provisioning failed: ";
 
+/**
+ * The two facts about the requesting caller a sandbox ensure carries, cut
+ * from the chain's CallerIdentity (the domain/identityaccount/actor.ts
+ * shape): the id rides into the credential mint, so the session token is
+ * minted FOR the caller; the class rides onto the driver's environment,
+ * so a driver can decide the workspace's durability by who asked. A step
+ * hands `ctx.callerIdentity` in whole; the pick keeps a test's fixture to
+ * the two fields the body reads.
+ */
+export type SandboxCaller = Pick<CallerIdentity, "identityId" | "callerClass">;
+
 type AgentExecutionCreateDesc = typeof AgentExecutionSchema;
 
 export interface EnsureSessionSandboxDeps {
@@ -101,7 +113,7 @@ export function newEnsureSessionSandboxStep(
       await ensureSessionSandboxForExecution(
         deps,
         ctx.newState,
-        ctx.callerIdentity.identityId,
+        ctx.callerIdentity,
       );
     },
   };
@@ -114,15 +126,18 @@ export function newEnsureSessionSandboxStep(
  * chains' differing context shapes (newState vs loaded execution) meet
  * at this seam instead.
  *
- * `callerIdentityId` rides into the credential mint (lane.ts): the Java
- * ensure step mints session tokens FOR the requesting caller, so the
- * capability mint needs the identity the OSS execution-scoped mint never
- * did. Empty when the invoking site has no caller.
+ * The caller splits two ways (SandboxCaller): `identityId` rides into the
+ * credential mint (lane.ts) — the Java ensure step mints session tokens
+ * FOR the requesting caller, so the capability mint needs the identity
+ * the OSS execution-scoped mint never did — and `callerClass` rides onto
+ * the driver's environment as the one request fact a driver may decide
+ * durability by. The chain always has a caller: the in-process transport
+ * mints `internal` for the server's own calls.
  */
 export async function ensureSessionSandboxForExecution(
   deps: EnsureSessionSandboxDeps,
   execution: AgentExecution,
-  callerIdentityId: string,
+  caller: SandboxCaller,
 ): Promise<void> {
   if (!deps.lane.enabled) {
     return;
@@ -167,10 +182,11 @@ export async function ensureSessionSandboxForExecution(
           sessionId,
           executionId,
           org: execution.metadata?.org ?? "",
-          callerIdentityId,
+          callerIdentityId: caller.identityId,
         },
         deps.logger,
       ),
+      callerClass: caller.callerClass,
     });
   } catch (error) {
     // Non-critical: never fail the launch — but never silent either
@@ -247,7 +263,7 @@ export function newEnsureWorkflowSandboxStep(
       await ensureWorkflowSandboxForExecution(
         deps,
         ctx.newState,
-        ctx.callerIdentity.identityId,
+        ctx.callerIdentity,
       );
     },
   };
@@ -258,13 +274,13 @@ export function newEnsureWorkflowSandboxStep(
  * re-provision (lifecycle.ts — the previous sandbox was deprovisioned at
  * the terminal FAILED, so a recovered execution needs a fresh one before
  * its fresh workflow starts). Throws Unavailable on provisioning failure
- * — the critical posture in both chains. `callerIdentityId` rides into
- * the credential mint exactly as on the session body.
+ * — the critical posture in both chains. The caller splits exactly as on
+ * the session body: id to the mint, class to the environment.
  */
 export async function ensureWorkflowSandboxForExecution(
   deps: EnsureWorkflowSandboxDeps,
   execution: WorkflowExecution,
-  callerIdentityId: string,
+  caller: SandboxCaller,
 ): Promise<void> {
   if (!deps.lane.enabled) {
     return;
@@ -296,10 +312,11 @@ export async function ensureWorkflowSandboxForExecution(
           sessionId: "",
           executionId,
           org: execution.metadata?.org ?? "",
-          callerIdentityId,
+          callerIdentityId: caller.identityId,
         },
         deps.logger,
       ),
+      callerClass: caller.callerClass,
     });
   } catch (error) {
     deps.logger.error(