@opengeni/core 0.21.10 → 0.28.0

package/src/rigs/index.ts

@@ -36,6 +36,9 @@ import {
   type Database,
 } from "@opengeni/db";
 import { HTTPException } from "hono/http-exception";
+import { rigProviderImagesFromVerification } from "./provider-images";
+
+export * from "./provider-images";
 
 export const MAX_RIGS_PER_WORKSPACE = 50;
 export const MAX_CHECKS_PER_RIG = 100;
@@ -352,6 +355,13 @@ export async function promoteSetupAppendChange(
   if (typeof payload.command !== "string" || !payload.command.trim()) {
     throw new HTTPException(422, { message: "setup_append change is missing command" });
   }
+  const nextDefinition = {
+    image: base.image,
+    setupScript: appendRigSetupCommand(base.setupScript, payload.command),
+    checks: base.checks,
+    credentialHooks: base.credentialHooks,
+    defaultVariableSetIds: base.defaultVariableSetIds,
+  };
   const { version, change: updated } = await promoteChangeWithActiveCas(
     deps,
     grant.workspaceId,
@@ -359,16 +369,13 @@ export async function promoteSetupAppendChange(
     change.id,
     {
       expectedActiveVersionId: change.baseVersionId,
-      image: base.image,
-      setupScript: appendRigSetupCommand(base.setupScript, payload.command),
-      checks: base.checks,
-      credentialHooks: base.credentialHooks,
-      defaultVariableSetIds: base.defaultVariableSetIds,
+      ...nextDefinition,
       changelog:
         typeof payload.note === "string" && payload.note.trim()
           ? payload.note
           : "Verified setup append",
       createdBy: change.proposedBy ?? rigActorForGrant(grant),
+      providerImages: rigProviderImagesFromVerification(change.verification, nextDefinition),
     },
   );
   await recordRigAuditEvent(deps.db, {
@@ -418,6 +425,18 @@ export async function promoteVerifiedDefinitionEditChangeForApi(
     defaultVariableSetIds?: unknown;
     changelog?: unknown;
   };
+  const nextDefinition = {
+    image: payload.image === undefined ? base.image : (payload.image as string | null),
+    setupScript:
+      payload.setupScript === undefined ? base.setupScript : (payload.setupScript as string | null),
+    checks: Array.isArray(payload.checks) ? (payload.checks as RigVersion["checks"]) : base.checks,
+    credentialHooks: Array.isArray(payload.credentialHooks)
+      ? (payload.credentialHooks as string[])
+      : base.credentialHooks,
+    defaultVariableSetIds: Array.isArray(payload.defaultVariableSetIds)
+      ? (payload.defaultVariableSetIds as string[])
+      : base.defaultVariableSetIds,
+  };
   const { version, change: updated } = await promoteChangeWithActiveCas(
     deps,
     grant.workspaceId,
@@ -425,25 +444,13 @@ export async function promoteVerifiedDefinitionEditChangeForApi(
     change.id,
     {
       expectedActiveVersionId: change.baseVersionId,
-      image: payload.image === undefined ? base.image : (payload.image as string | null),
-      setupScript:
-        payload.setupScript === undefined
-          ? base.setupScript
-          : (payload.setupScript as string | null),
-      checks: Array.isArray(payload.checks)
-        ? (payload.checks as RigVersion["checks"])
-        : base.checks,
-      credentialHooks: Array.isArray(payload.credentialHooks)
-        ? (payload.credentialHooks as string[])
-        : base.credentialHooks,
-      defaultVariableSetIds: Array.isArray(payload.defaultVariableSetIds)
-        ? (payload.defaultVariableSetIds as string[])
-        : base.defaultVariableSetIds,
+      ...nextDefinition,
       changelog:
         typeof payload.changelog === "string" && payload.changelog.trim()
           ? payload.changelog
           : "Verified definition edit",
       createdBy: rigActorForGrant(grant),
+      providerImages: rigProviderImagesFromVerification(change.verification, nextDefinition),
     },
   );
   await recordRigAuditEvent(deps.db, {

package/src/rigs/provider-images.ts

@@ -0,0 +1,110 @@
+import { createHash } from "node:crypto";
+import {
+  RigProviderImage as RigProviderImageContract,
+  stableJson,
+  type RigChangeVerification,
+  type RigProviderImage,
+  type RigProviderImages,
+  type RigVersion,
+  type SandboxBackend,
+} from "@opengeni/contracts";
+
+export type RigProviderImageDefinition = Pick<
+  RigVersion,
+  "image" | "setupScript" | "checks" | "credentialHooks" | "defaultVariableSetIds"
+>;
+
+function sha256(value: string): string {
+  return `sha256:${createHash("sha256").update(value, "utf8").digest("hex")}`;
+}
+
+export function rigProviderImageProviderBindingKeyHash(bindingKey: string): string {
+  return sha256(bindingKey);
+}
+
+export function rigProviderImageSetupHash(
+  definition: Pick<RigProviderImageDefinition, "setupScript">,
+): string {
+  return sha256(definition.setupScript ?? "");
+}
+
+/**
+ * Hash every exact rig-definition input that can affect whether a provider
+ * image may be reused. Credential values and variable-set contents are
+ * intentionally absent: verification never injects them into the build box.
+ * Their declared hook/set identities still participate so a new rig version
+ * cannot silently inherit an older build record.
+ */
+export function rigProviderImageContentHash(input: {
+  backend: SandboxBackend;
+  sourceImage: string | null;
+  definition: RigProviderImageDefinition;
+}): string {
+  return sha256(
+    stableJson({
+      version: 1,
+      backend: input.backend,
+      sourceImage: input.sourceImage,
+      image: input.definition.image,
+      setupScript: input.definition.setupScript,
+      checks: input.definition.checks,
+      credentialHooks: input.definition.credentialHooks,
+      defaultVariableSetIds: input.definition.defaultVariableSetIds,
+    }),
+  );
+}
+
+/** Modal's patched snapshot API accepts a caller-owned UUID idempotency key.
+ * v2 denotes images proven by a separate cold boot before publication. */
+export function rigProviderImageBuildRequestId(input: {
+  targetId: string;
+  backend: SandboxBackend;
+  contentHash: string;
+}): string {
+  const bytes = createHash("sha256")
+    .update("opengeni-rig-provider-image-build-v2\0", "utf8")
+    .update(input.targetId, "utf8")
+    .update("\0", "utf8")
+    .update(input.backend, "utf8")
+    .update("\0", "utf8")
+    .update(input.contentHash, "utf8")
+    .digest()
+    .subarray(0, 16);
+  // RFC 4122 variant + deterministic version-5-shaped UUID. The digest, not a
+  // provider response, is the idempotency identity.
+  bytes[6] = (bytes[6]! & 0x0f) | 0x50;
+  bytes[8] = (bytes[8]! & 0x3f) | 0x80;
+  const hex = bytes.toString("hex");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+export function rigProviderImageMatchesDefinition(
+  image: RigProviderImage,
+  definition: RigProviderImageDefinition,
+): boolean {
+  return (
+    image.setupHash === rigProviderImageSetupHash(definition) &&
+    image.contentHash ===
+      rigProviderImageContentHash({
+        backend: image.backend,
+        sourceImage: image.sourceImage,
+        definition,
+      })
+  );
+}
+
+/**
+ * Promotion copies only a finalized, structurally valid build record whose
+ * hashes match the exact version definition being inserted. A malformed or
+ * stale optimization record is discarded; the version remains correct and
+ * falls back to runtime setup.
+ */
+export function rigProviderImagesFromVerification(
+  verification: RigChangeVerification | null,
+  definition: RigProviderImageDefinition,
+): RigProviderImages {
+  const parsed = RigProviderImageContract.safeParse(verification?.providerImage);
+  if (!parsed.success || parsed.data.status === "building") return {};
+  if (!rigProviderImageMatchesDefinition(parsed.data, definition)) return {};
+  return { [parsed.data.backend]: parsed.data };
+}

package/src/sandbox/fleet.ts

@@ -37,7 +37,6 @@ import {
   type SelfhostedRelayConfig,
   type SelfhostedOpStreamDeps,
 } from "@opengeni/runtime/sandbox";
-import { HTTPException } from "hono/http-exception";
 import { relayConfigFromSettings } from "./routing";
 
 export type FleetServices = {
@@ -69,8 +68,9 @@ export type FleetContext = {
 
 /**
  * Build a session-scoped {@link FleetContext}: load the session (workspace-
- * scoped), reject a session with no box (backend:none — the fleet is only
- * meaningful for a sandboxed session), and project its group backend/id. Shared
+ * scoped) and project its group backend/id. A backend:none session has no home
+ * box, but it may still discover, run on, and attach an owned Connected Machine.
+ * Shared
  * by the worker-signed MCP fleet tools and the user-authenticated swap REST
  * route so both resolve the SAME context (no drift). The `accountId`/`workspaceId`/
  * `sessionId` come from the trusted grant/route; the backend + group id come from
@@ -81,11 +81,6 @@ export async function buildFleetContextForSession(
   ctx: { accountId: string; workspaceId: string; sessionId: string },
 ): Promise<FleetContext> {
   const session = await requireSession(deps.db, ctx.workspaceId, ctx.sessionId);
-  if (session.sandboxBackend === "none") {
-    throw new HTTPException(422, {
-      message: "this session has no sandbox (backend: none); the fleet is unavailable",
-    });
-  }
   return {
     accountId: ctx.accountId,
     workspaceId: ctx.workspaceId,
@@ -229,9 +224,11 @@ async function probeEnrollment(
 }
 
 /**
- * List the fleet: the session's own Modal group box (a synthetic entry) + the
- * workspace's first-class selfhosted sandboxes (each probed for liveness), each
- * with an `active` marker derived from the session's active pointer.
+ * List the fleet: the session's own group box when it has one (a synthetic
+ * entry) + the workspace's first-class selfhosted sandboxes (each probed for
+ * liveness), each with an `active` marker derived from the session's active
+ * pointer. A backend:none session has no synthetic home entry; a null pointer
+ * then means no compute is attached.
  */
 export async function listFleet(
   services: FleetServices,
@@ -245,61 +242,63 @@ export async function listFleet(
 
   const entries: FleetSandboxEntry[] = [];
 
-  // The session's own group box (the default/home sandbox; null active pointer ==
-  // this box). A session/group row is not provider existence. Online requires a
-  // warm lease, observed provider existence, and verified workspace readiness.
-  const groupActive = pointer.activeSandboxId === null;
-  const groupLease = await readLease(db, ctx.workspaceId, ctx.sessionGroupId);
-  const groupOnline = Boolean(
-    groupLease?.liveness === "warm" &&
-    groupLease.recovery.provider.status === "exists" &&
-    groupLease.recovery.workspace.status === "ready",
-  );
-  const groupRecovering = Boolean(
-    groupLease &&
-    (groupLease.liveness === "warming" ||
-      groupLease.recovery.restore.status === "pending" ||
-      groupLease.recovery.restore.status === "restoring" ||
-      groupLease.recovery.restore.status === "verifying"),
-  );
-  const groupRecoveryUnavailable = Boolean(
-    groupLease &&
-    (groupLease.recovery.restore.status === "degraded" ||
-      groupLease.recovery.restore.status === "unrecoverable" ||
-      groupLease.recovery.workspace.status === "degraded" ||
-      groupLease.recovery.workspace.status === "unrecoverable"),
-  );
-  const groupOperationAvailability: FleetOperationAvailability = groupOnline
-    ? "ready"
-    : groupRecoveryUnavailable
-      ? "unavailable"
-      : groupRecovering
-        ? "recovering"
-        : ctx.sessionBackend === "selfhosted"
-          ? "unavailable"
-          : "wakeable";
-  entries.push({
-    id: ctx.sessionGroupId,
-    kind: ctx.sessionBackend === "selfhosted" ? "selfhosted" : "modal",
-    name: "session sandbox",
-    liveness: groupOnline ? "online" : groupRecovering ? "reconnecting" : "offline",
-    active: groupActive,
-    isSessionGroup: true,
-    enrollmentId: null,
-    attachable: groupOnline,
-    operationAvailability: groupOperationAvailability,
-    providerStatus: groupLease?.recovery.provider.status ?? "not_created",
-    leaseLiveness: groupLease?.liveness ?? null,
-    routeStatus: groupActive ? "attached" : "detached",
-    archiveStatus: groupLease?.recovery.archive.status ?? "none",
-    restoreStatus: groupLease?.recovery.restore.status ?? "not_required",
-    workspaceStatus: groupLease?.recovery.workspace.status ?? "unknown",
-    leaseEpoch: groupLease?.leaseEpoch ?? null,
-    routeEpoch: pointer.activeEpoch,
-    workspaceGeneration: groupLease?.workspaceGeneration ?? null,
-    archiveGeneration: groupLease?.archiveGeneration ?? null,
-    archiveComplete: groupLease?.archiveComplete ?? false,
-  });
+  if (ctx.sessionBackend !== "none") {
+    // The session's own group box (the default/home sandbox; null active pointer ==
+    // this box). A session/group row is not provider existence. Online requires a
+    // warm lease, observed provider existence, and verified workspace readiness.
+    const groupActive = pointer.activeSandboxId === null;
+    const groupLease = await readLease(db, ctx.workspaceId, ctx.sessionGroupId);
+    const groupOnline = Boolean(
+      groupLease?.liveness === "warm" &&
+      groupLease.recovery.provider.status === "exists" &&
+      groupLease.recovery.workspace.status === "ready",
+    );
+    const groupRecovering = Boolean(
+      groupLease &&
+      (groupLease.liveness === "warming" ||
+        groupLease.recovery.restore.status === "pending" ||
+        groupLease.recovery.restore.status === "restoring" ||
+        groupLease.recovery.restore.status === "verifying"),
+    );
+    const groupRecoveryUnavailable = Boolean(
+      groupLease &&
+      (groupLease.recovery.restore.status === "degraded" ||
+        groupLease.recovery.restore.status === "unrecoverable" ||
+        groupLease.recovery.workspace.status === "degraded" ||
+        groupLease.recovery.workspace.status === "unrecoverable"),
+    );
+    const groupOperationAvailability: FleetOperationAvailability = groupOnline
+      ? "ready"
+      : groupRecoveryUnavailable
+        ? "unavailable"
+        : groupRecovering
+          ? "recovering"
+          : ctx.sessionBackend === "selfhosted"
+            ? "unavailable"
+            : "wakeable";
+    entries.push({
+      id: ctx.sessionGroupId,
+      kind: ctx.sessionBackend === "selfhosted" ? "selfhosted" : "modal",
+      name: "session sandbox",
+      liveness: groupOnline ? "online" : groupRecovering ? "reconnecting" : "offline",
+      active: groupActive,
+      isSessionGroup: true,
+      enrollmentId: null,
+      attachable: groupOnline,
+      operationAvailability: groupOperationAvailability,
+      providerStatus: groupLease?.recovery.provider.status ?? "not_created",
+      leaseLiveness: groupLease?.liveness ?? null,
+      routeStatus: groupActive ? "attached" : "detached",
+      archiveStatus: groupLease?.recovery.archive.status ?? "none",
+      restoreStatus: groupLease?.recovery.restore.status ?? "not_required",
+      workspaceStatus: groupLease?.recovery.workspace.status ?? "unknown",
+      leaseEpoch: groupLease?.leaseEpoch ?? null,
+      routeEpoch: pointer.activeEpoch,
+      workspaceGeneration: groupLease?.workspaceGeneration ?? null,
+      archiveGeneration: groupLease?.archiveGeneration ?? null,
+      archiveComplete: groupLease?.archiveComplete ?? false,
+    });
+  }
 
   // The workspace's first-class selfhosted sandboxes (enrolled machines). Probe
   // each for liveness; a missing enrollment is offline.
@@ -374,6 +373,13 @@ async function resolveTarget(
 > {
   // The session's own group box → the default pointer (null).
   if (target === ctx.sessionGroupId || target === "session" || target === "default") {
+    if (ctx.sessionBackend === "none") {
+      return {
+        ok: false,
+        reason: "this session has no home sandbox; attach a Connected Machine",
+        code: "unsupported_backend_context",
+      };
+    }
     return { ok: true, targetSandboxId: null };
   }
   const sandbox = await getSandbox(services.db, ctx.workspaceId, target);

package/src/sandbox/routing.ts

@@ -11,7 +11,7 @@
 // The DB-coupled glue (readActiveSandbox / getSandbox / the selfhosted ControlRpc
 // over the events bus) lives here, not in the leaf (which stays db-free).
 
-import { sandboxArchiveCaptureTimeoutMs, type Settings } from "@opengeni/config";
+import { sandboxLifecycleTransitionWaitMs, type Settings } from "@opengeni/config";
 import {
   advanceWorkspaceGenerationForDirectRequest,
   advanceWorkspaceGenerationForRetainedProcess,
@@ -61,6 +61,7 @@ export type ChannelARoutingServices = {
   settings: Settings;
   bus?: EventBus;
   onSandboxOperation?: RoutingSandboxOperationObserver;
+  waitSignal?: AbortSignal;
 };
 
 /** Map the deployment relay URL to the leaf's `SelfhostedRelayConfig` shape. The
@@ -214,7 +215,8 @@ export function wrapChannelABoxWithRouting(
           routeTargetId: backend.sandboxId,
           routeEpoch: backend.activeEpoch,
           operation: op,
-          captureWaitMs: sandboxArchiveCaptureTimeoutMs(settings),
+          captureWaitMs: sandboxLifecycleTransitionWaitMs(settings),
+          ...(services.waitSignal ? { waitSignal: services.waitSignal } : {}),
         });
         return { admission, providerBinding };
       }
@@ -310,7 +312,8 @@ export function wrapChannelABoxWithRouting(
           sessionId: ids.sessionId,
           processId: process.id,
           operation: op,
-          captureWaitMs: sandboxArchiveCaptureTimeoutMs(settings),
+          captureWaitMs: sandboxLifecycleTransitionWaitMs(settings),
+          ...(services.waitSignal ? { waitSignal: services.waitSignal } : {}),
         })
     : undefined;
   const afterProcessMutation = homeLease