@opengeni/core 0.21.2 → 0.24.1

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

@@ -27,6 +27,7 @@ import {
 import type { EventBus } from "@opengeni/events";
 import {
   NatsControlRpc,
+  NatsOpStreamTransport,
   selfhostedLiveness,
   SelfhostedSession,
   swapTargetEstablishability,
@@ -34,6 +35,7 @@ import {
   type ControlRpc,
   type NatsRequestConnection,
   type SelfhostedRelayConfig,
+  type SelfhostedOpStreamDeps,
 } from "@opengeni/runtime/sandbox";
 import { HTTPException } from "hono/http-exception";
 import { relayConfigFromSettings } from "./routing";
@@ -95,6 +97,7 @@ export async function buildFleetContextForSession(
 
 /** The dominant liveness of a fleet member, surfaced to the dock + the agent. */
 export type FleetLiveness = "online" | "reconnecting" | "offline";
+export type FleetOperationAvailability = "ready" | "wakeable" | "recovering" | "unavailable";
 
 /**
  * A fleet member as the agent + the dock see it (the M8b/M9 UI seam — the
@@ -117,6 +120,11 @@ export type FleetSandboxEntry = {
   enrollmentId: string | null;
   /** Whether this target can be attached/swapped to right now (live + addressable). */
   attachable: boolean;
+  /** Whether an ordinary shell/files operation can use this target. This is
+   * deliberately separate from `attachable`: an idle managed home sandbox can
+   * be wakeable even while its holderless lease is cold/draining and therefore
+   * not an already-live swap target. */
+  operationAvailability: FleetOperationAvailability;
   /** Selfhosted only: whether whole-machine + screen-control consent is acked. */
   consented?: boolean;
   /** Selfhosted only: whether a display (real/Xvfb) is present. */
@@ -254,6 +262,22 @@ export async function listFleet(
       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",
@@ -263,6 +287,7 @@ export async function listFleet(
     isSessionGroup: true,
     enrollmentId: null,
     attachable: groupOnline,
+    operationAvailability: groupOperationAvailability,
     providerStatus: groupLease?.recovery.provider.status ?? "not_created",
     leaseLiveness: groupLease?.liveness ?? null,
     routeStatus: groupActive ? "attached" : "detached",
@@ -284,6 +309,11 @@ export async function listFleet(
       continue;
     }
     const enrollment = await getEnrollment(db, ctx.workspaceId, sandbox.enrollmentId);
+    if (!enrollment || enrollment.status !== "active") {
+      // Revoked enrollments remain durable audit/history records, but they are
+      // intentionally absent from the normal attach/run picker.
+      continue;
+    }
     const probe = enrollment
       ? await probeEnrollment(services, ctx.workspaceId, enrollment)
       : { liveness: "offline" as FleetLiveness, consented: false, hasDisplay: false };
@@ -296,6 +326,12 @@ export async function listFleet(
       isSessionGroup: false,
       enrollmentId: sandbox.enrollmentId,
       attachable: probe.liveness === "online",
+      operationAvailability:
+        probe.liveness === "online"
+          ? "ready"
+          : probe.liveness === "reconnecting"
+            ? "recovering"
+            : "unavailable",
       consented: probe.consented,
       hasDisplay: probe.hasDisplay,
       lastSeenAt: enrollment?.lastSeenAt ?? null,
@@ -533,6 +569,8 @@ export type RunOnSelfhostedMachine = {
   controlTimeoutMs: number;
   /** Longer agent-side process deadline for exec. */
   execTimeoutMs: number;
+  /** Streaming transport required when execTimeoutMs is 0 (unbounded). */
+  opStream?: SelfhostedOpStreamDeps;
 };
 
 /**
@@ -553,6 +591,7 @@ export async function executeRunOnSelfhostedMachine(
     relay: machine.relay,
     timeoutMs: machine.controlTimeoutMs,
     execTimeoutMs: machine.execTimeoutMs,
+    ...(machine.opStream !== undefined ? { opStream: machine.opStream } : {}),
   });
 
   try {
@@ -600,6 +639,11 @@ export async function executeRunOnSelfhostedMachine(
       // so leave `timedOut` absent while still reporting the enforced deadline.
       ...(op.kind === "exec" ? { deadlineMs: session.effectiveExecDeadlineMs } : {}),
     };
+  } finally {
+    // This one-off has no turn journal. Once its result has been accepted by
+    // this call, final-ack any settled stream so the runner can immediately
+    // release replay/output retention instead of waiting for TTL cleanup.
+    await session.finalizeOpStreamOps().catch(() => undefined);
   }
 }
 
@@ -655,6 +699,17 @@ export async function runOnSandbox(
       relay: relayConfigFromSettings(services.settings),
       controlTimeoutMs: services.settings.sandboxSelfhostedControlTimeoutMs,
       execTimeoutMs: services.settings.sandboxSelfhostedExecTimeoutMs,
+      ...(services.settings.agentOpStreamEnabled === true &&
+      enrollment.opStream === true &&
+      services.bus?.getOpStreamConnection
+        ? {
+            opStream: {
+              transport: new NatsOpStreamTransport(
+                async () => services.bus?.getOpStreamConnection?.() ?? null,
+              ),
+            },
+          }
+        : {}),
     },
     target,
     op,
@@ -692,7 +747,7 @@ export async function provisionSandbox(
     return {
       kind: "selfhosted",
       instructions:
-        "Share these instructions with a human operator. They install the OpenGeni agent on the machine, run `opengeni-agent enroll`, complete the device-flow at the verification URL (the loud whole-machine + screen-control consent), and the machine then appears here as an attachable selfhosted sandbox.",
+        "Share these instructions with a human operator. They install the OpenGeni agent on the machine, run `opengeni-agent connect`, complete the device-flow at the verification URL (the loud whole-machine + screen-control consent), and the machine then appears here as an attachable selfhosted sandbox. Existing connections to other OpenGeni workspaces or deployments are preserved.",
       // Install from THIS control plane's origin (not a hardcoded public CDN): the
       // served install script is rewritten to pull the per-SHA agent baked into
       // this exact deployment (see apps/api/src/routes/install.ts), so a deployed

package/src/sandbox/routing.ts

@@ -11,10 +11,11 @@
 // 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,
+  getEnrollment,
   getRetainedProcess,
   getSandbox,
   markWarmLeaseInstanceLost,
@@ -32,6 +33,7 @@ import {
   isProviderSandboxGoneDuringRoutedOperation,
   makeActiveBackendResolver,
   NatsControlRpc,
+  NatsOpStreamTransport,
   RoutingSandboxSession,
   resolveModalCheckpointProviderBindingForSession,
   type ControlRpc,
@@ -44,6 +46,7 @@ import {
   type RoutingRetainedProcessTerminalProof,
   type RoutingSandboxOperationObserver,
   type SelfhostedRelayConfig,
+  type SelfhostedOpStreamDeps,
 } from "@opengeni/runtime/sandbox";
 
 type PersistableMutationAdmission = {
@@ -58,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
@@ -114,6 +118,27 @@ function controlRpcFactory(bus: EventBus | undefined): () => ControlRpc {
     });
 }
 
+async function resolveSelfhostedOpStream(
+  services: ChannelARoutingServices,
+  workspaceId: string,
+  sandbox: RoutableSandbox,
+): Promise<SelfhostedOpStreamDeps | undefined> {
+  if (
+    services.settings.agentOpStreamEnabled !== true ||
+    !services.bus?.getOpStreamConnection ||
+    !sandbox.enrollmentId
+  ) {
+    return undefined;
+  }
+  const enrollment = await getEnrollment(services.db, workspaceId, sandbox.enrollmentId);
+  if (enrollment?.opStream !== true) return undefined;
+  return {
+    transport: new NatsOpStreamTransport(
+      async () => services.bus?.getOpStreamConnection?.() ?? null,
+    ),
+  };
+}
+
 /** Whether the routing proxy should wrap the Channel-A box: gated by the
  *  selfhosted flag (the active pointer + swap are only meaningful then). */
 export function routingEnabled(settings: Settings): boolean {
@@ -190,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 };
       }
@@ -286,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
@@ -389,6 +416,8 @@ export function wrapChannelABoxWithRouting(
         : null;
     },
     controlRpcFactory: controlRpcFactory(bus),
+    resolveSelfhostedOpStream: (sandbox) =>
+      resolveSelfhostedOpStream(services, ids.workspaceId, sandbox),
     relay: relayConfigFromSettings(settings),
     selfhostedTimeoutMs: settings.sandboxSelfhostedControlTimeoutMs,
     selfhostedExecTimeoutMs: settings.sandboxSelfhostedExecTimeoutMs,

package/src/session-authorization.ts

@@ -46,6 +46,23 @@ export type ResolvedSessionAuthorization = {
   reauthorizeAfterMs: number | null;
 };
 
+/**
+ * Prove that a first-party request belongs to the exact currently active
+ * attempt of the named caller session. Unlike the optional embedding-host ACL
+ * port, this database fence is mandatory for high-trust operations.
+ */
+export async function requireLiveAgentAttemptAuthorization(
+  db: Database,
+  grant: AccessGrant,
+  callerSessionId: string,
+): Promise<Extract<SessionAuthorizationActor, { kind: "agent_attempt" }>> {
+  const actor = await resolveSessionAuthorizationActor(db, grant);
+  if (actor.kind !== "agent_attempt" || actor.callerSessionId !== callerSessionId) {
+    throw new SessionAuthorizationDeniedError("caller_stale");
+  }
+  return actor;
+}
+
 /**
  * Resolve and enforce the host ACL for one session. The target and agent actor
  * are reconstructed from workspace-scoped durable state. A request can supply
@@ -221,5 +238,8 @@ async function resolveSessionAuthorizationActor(
     executionGeneration,
     initiator: turn.initiator,
     initiatorContext: turn.initiatorContext,
+    initiatingHumanSubjectId:
+      turn.initiatingHumanSubjectId ??
+      (turn.initiator.kind === "subject" ? turn.initiator.subjectId : null),
   });
 }

package/src/workflow-wake-contract.ts

@@ -4,3 +4,11 @@ export const SESSION_WORKFLOW_WAKE_DISPATCHER_SCHEDULE_ID =
 export const SESSION_WORKFLOW_WAKE_DISPATCHER_WORKFLOW_TYPE =
   "sessionWorkflowWakeDispatcherWorkflow";
 export const SESSION_WORKFLOW_WAKE_DISPATCHER_PERIOD_MS = 10_000;
+
+/**
+ * Temporal delivers activity cancellation through heartbeats. Keep both the
+ * activity's local heartbeat timer and the worker's SDK throttle at this bound
+ * so the end-to-end Pause/Steer physical-cancellation contract is not already
+ * exhausted before sandbox/tool quiescence and replacement admission begin.
+ */
+export const TURN_ACTIVITY_CANCELLATION_HEARTBEAT_INTERVAL_MS = 500;