@opengeni/core 0.4.6 → 0.4.7

package/src/sandbox/fleet.ts

@@ -15,7 +15,6 @@ import type { Settings } from "@opengeni/config";
 import {
   getEnrollment,
   getSandbox,
-  listEnrollments,
   listSandboxes,
   readActiveSandbox,
   requireSession,
@@ -29,6 +28,8 @@ import {
   NatsControlRpc,
   selfhostedLiveness,
   SelfhostedSession,
+  swapTargetEstablishability,
+  type BackendUnresolvableCode,
   type ControlRpc,
   type NatsRequestConnection,
 } from "@opengeni/runtime/sandbox";
@@ -119,12 +120,14 @@ export type FleetListResult = {
   sandboxes: FleetSandboxEntry[];
 };
 
-/** A swap/attach outcome the tool returns. */
+/** A swap/attach outcome the tool returns. On a rejection, `code` carries the
+ *  typed reason (issue #341 typed diagnostics) alongside the human `reason`. */
 export type FleetSwapResult = {
   swapped: boolean;
   activeSandboxId: string | null;
   activeEpoch: number;
   reason?: string;
+  code?: BackendUnresolvableCode | "concurrent_swap";
 };
 
 const PROBE_TIMEOUT_MS = 5_000;
@@ -171,6 +174,8 @@ async function probeEnrollment(
       allowScreenControl: enrollment.allowScreenControl,
       hasDisplay: enrollment.hasDisplay,
       lastSeenAt: enrollment.lastSeenAt,
+      wentOfflineAt: enrollment.wentOfflineAt,
+      wentOfflineReason: enrollment.wentOfflineReason,
     },
     probeResponded,
   });
@@ -182,7 +187,10 @@ async function probeEnrollment(
  * workspace's first-class selfhosted sandboxes (each probed for liveness), each
  * with an `active` marker derived from the session's active pointer.
  */
-export async function listFleet(services: FleetServices, ctx: FleetContext): Promise<FleetListResult> {
+export async function listFleet(
+  services: FleetServices,
+  ctx: FleetContext,
+): Promise<FleetListResult> {
   const { db } = services;
   const pointer = (await readActiveSandbox(db, ctx.workspaceId, ctx.sessionId)) ?? {
     activeSandboxId: null,
@@ -231,7 +239,11 @@ export async function listFleet(services: FleetServices, ctx: FleetContext): Pro
     });
   }
 
-  return { activeSandboxId: pointer.activeSandboxId, activeEpoch: pointer.activeEpoch, sandboxes: entries };
+  return {
+    activeSandboxId: pointer.activeSandboxId,
+    activeEpoch: pointer.activeEpoch,
+    sandboxes: entries,
+  };
 }
 
 /** Resolve a swap target id → the value `setActiveSandbox` writes. The session's
@@ -241,26 +253,59 @@ async function resolveTarget(
   services: FleetServices,
   ctx: FleetContext,
   target: string,
-): Promise<{ ok: true; targetSandboxId: string | null } | { ok: false; reason: string }> {
+): Promise<
+  | { ok: true; targetSandboxId: string | null }
+  | { ok: false; reason: string; code: BackendUnresolvableCode }
+> {
   // The session's own group box → the default pointer (null).
   if (target === ctx.sessionGroupId || target === "session" || target === "default") {
     return { ok: true, targetSandboxId: null };
   }
   const sandbox = await getSandbox(services.db, ctx.workspaceId, target);
   if (!sandbox) {
-    return { ok: false, reason: `sandbox ${target} not found in this workspace` };
+    return {
+      ok: false,
+      reason: `sandbox ${target} not found in this workspace`,
+      code: "stale_pointer",
+    };
+  }
+  // ESTABLISHER-CAPABILITY GATE (issue #341 invariant A): a target must be
+  // establishable by a turn's routing context BEFORE the epoch-fenced CAS commits
+  // the pointer, or a "successful" swap strands every following op on a backend no
+  // turn can resume. `swapTargetEstablishability` is the SAME predicate the turn
+  // resolver consults, so admission and establishment never disagree. Any sandbox
+  // reaching here is NOT the session's own group box (handled above), so a Modal
+  // sibling is rejected pre-commit rather than admitted-then-stranded.
+  const establishable = swapTargetEstablishability({
+    kind: sandbox.kind,
+    isSessionGroup: false,
+  });
+  if (!establishable.ok) {
+    return { ok: false, reason: establishable.reason, code: establishable.code };
   }
   if (sandbox.kind === "selfhosted") {
     if (!sandbox.enrollmentId) {
-      return { ok: false, reason: `selfhosted sandbox ${target} has no enrollment` };
+      return {
+        ok: false,
+        reason: `selfhosted sandbox ${target} has no enrollment`,
+        code: "offline_enrollment",
+      };
     }
     const enrollment = await getEnrollment(services.db, ctx.workspaceId, sandbox.enrollmentId);
     if (!enrollment) {
-      return { ok: false, reason: `enrollment for sandbox ${target} not found` };
+      return {
+        ok: false,
+        reason: `enrollment for sandbox ${target} not found`,
+        code: "offline_enrollment",
+      };
     }
     const probe = await probeEnrollment(services, ctx.workspaceId, enrollment);
     if (probe.liveness !== "online") {
-      return { ok: false, reason: `sandbox ${target} is ${probe.liveness}; cannot attach to a non-online machine` };
+      return {
+        ok: false,
+        reason: `sandbox ${target} is ${probe.liveness}; cannot attach to a non-online machine`,
+        code: "offline_enrollment",
+      };
     }
   }
   return { ok: true, targetSandboxId: sandbox.id };
@@ -289,7 +334,15 @@ export async function swapActiveSandbox(
       activeSandboxId: null,
       activeEpoch: 0,
     };
-    return { swapped: false, activeSandboxId: pointer.activeSandboxId, activeEpoch: pointer.activeEpoch, reason: resolved.reason };
+    // Fail BEFORE the CAS: the pointer + epoch are read back unchanged and echoed,
+    // so an unestablishable target never mutates the session's routing state.
+    return {
+      swapped: false,
+      activeSandboxId: pointer.activeSandboxId,
+      activeEpoch: pointer.activeEpoch,
+      reason: resolved.reason,
+      code: resolved.code,
+    };
   }
 
   // Read the current epoch, then CAS on it (the fence). One retry on a lost race
@@ -301,7 +354,11 @@ export async function swapActiveSandbox(
     };
     // No-op swap (already pointed there) is a success without an epoch bump churn.
     if (pointer.activeSandboxId === resolved.targetSandboxId) {
-      return { swapped: true, activeSandboxId: pointer.activeSandboxId, activeEpoch: pointer.activeEpoch };
+      return {
+        swapped: true,
+        activeSandboxId: pointer.activeSandboxId,
+        activeEpoch: pointer.activeEpoch,
+      };
     }
     const result = await setActiveSandbox(services.db, {
       accountId: ctx.accountId,
@@ -312,7 +369,11 @@ export async function swapActiveSandbox(
       ...(workingDir !== undefined ? { workingDir } : {}),
     });
     if (result.swapped && result.pointer) {
-      return { swapped: true, activeSandboxId: result.pointer.activeSandboxId, activeEpoch: result.pointer.activeEpoch };
+      return {
+        swapped: true,
+        activeSandboxId: result.pointer.activeSandboxId,
+        activeEpoch: result.pointer.activeEpoch,
+      };
     }
     // CAS lost (a concurrent swap won) — re-read + retry once.
   }
@@ -325,6 +386,7 @@ export async function swapActiveSandbox(
     activeSandboxId: pointer.activeSandboxId,
     activeEpoch: pointer.activeEpoch,
     reason: "a concurrent swap won the epoch fence; re-read and retry",
+    code: "concurrent_swap",
   };
 }
 
@@ -362,7 +424,12 @@ export async function runOnSandbox(
 ): Promise<RunOnResult> {
   const sandbox = await getSandbox(services.db, ctx.workspaceId, target);
   if (!sandbox) {
-    return { target, kind: op.kind, ok: false, reason: `sandbox ${target} not found in this workspace` };
+    return {
+      target,
+      kind: op.kind,
+      ok: false,
+      reason: `sandbox ${target} not found in this workspace`,
+    };
   }
   if (sandbox.kind !== "selfhosted" || !sandbox.enrollmentId) {
     return {
@@ -386,8 +453,18 @@ export async function runOnSandbox(
 
   try {
     if (op.kind === "exec") {
-      const res = await session.exec({ cmd: op.cmd, ...(op.workdir ? { workdir: op.workdir } : {}) });
-      return { target, kind: "exec", ok: true, stdout: res.stdout, stderr: res.stderr, exitCode: res.exitCode };
+      const res = await session.exec({
+        cmd: op.cmd,
+        ...(op.workdir ? { workdir: op.workdir } : {}),
+      });
+      return {
+        target,
+        kind: "exec",
+        ok: true,
+        stdout: res.stdout,
+        stderr: res.stderr,
+        exitCode: res.exitCode,
+      };
     }
     if (op.kind === "read") {
       const bytes = await session.readFile({ path: op.path });
@@ -443,8 +520,10 @@ export async function provisionSandbox(
       note: "Whole-machine access requires explicit human consent in the device-flow web page; the agent cannot self-consent.",
     };
   }
-  // modal: create a first-class named modal sandbox record (a swap target). The
-  // box is materialized lazily on first swap (Modal lifecycle unchanged).
+  // modal: create a first-class named modal sandbox record. NOTE: a session cannot
+  // yet be swapped onto a second Modal box — cross-group Modal routing is not built,
+  // so `sandbox_swap` to this id is rejected (unsupported_backend_context). The
+  // response says so plainly rather than implying an attach that does not work.
   const { createSandbox } = await import("@opengeni/db");
   const sandbox = await createSandbox(services.db, {
     accountId: ctx.accountId,
@@ -455,6 +534,6 @@ export async function provisionSandbox(
   return {
     kind: "modal",
     sandbox,
-    note: "A named Modal sandbox record was created. Its box is materialized when first swapped-to; the session's own group box remains the default until then.",
+    note: "A named Modal sandbox record was created, but it is NOT yet attachable as a swap target: routing a session onto a second Modal box is not supported yet, so a sandbox_swap to this id is rejected. Use the session's own box (the default) or attach a Connected Machine instead.",
   };
 }

package/src/sandbox/routing.ts

@@ -108,7 +108,12 @@ export function wrapChannelABoxWithRouting(
     getSandbox: async (sandboxId): Promise<RoutableSandbox | null> => {
       const sandbox = await getSandbox(db, ids.workspaceId, sandboxId);
       return sandbox
-        ? { id: sandbox.id, kind: sandbox.kind, name: sandbox.name, enrollmentId: sandbox.enrollmentId }
+        ? {
+            id: sandbox.id,
+            kind: sandbox.kind,
+            name: sandbox.name,
+            enrollmentId: sandbox.enrollmentId,
+          }
         : null;
     },
     controlRpcFactory: controlRpcFactory(bus),

package/src/sandbox-types.ts

@@ -21,8 +21,20 @@
 export type ApiSandboxSession = {
   state?: Record<string, unknown> & { sandboxId?: string };
   running?(): Promise<boolean>;
-  exec?(args: { cmd: string; workdir?: string; runAs?: string; yieldTimeMs?: number; maxOutputTokens?: number }): Promise<unknown>;
-  execCommand?(args: { cmd: string; workdir?: string; runAs?: string; yieldTimeMs?: number; maxOutputTokens?: number }): Promise<string>;
+  exec?(args: {
+    cmd: string;
+    workdir?: string;
+    runAs?: string;
+    yieldTimeMs?: number;
+    maxOutputTokens?: number;
+  }): Promise<unknown>;
+  execCommand?(args: {
+    cmd: string;
+    workdir?: string;
+    runAs?: string;
+    yieldTimeMs?: number;
+    maxOutputTokens?: number;
+  }): Promise<string>;
   shutdown?(options?: unknown): Promise<void>;
   delete?(options?: unknown): Promise<void>;
   close?(): Promise<void>;
@@ -30,9 +42,9 @@ export type ApiSandboxSession = {
 
 export type ApiSandboxClient = {
   backendId: string;
-  deserializeSessionState?(state: Record<string, unknown>): Promise<unknown>;
-  resume?(state: unknown, options?: unknown): Promise<ApiSandboxSession>;
-  delete?(state: unknown): Promise<void>;
+  deserializeSessionState?(state: Record<string, unknown>): Promise<Record<string, unknown>>;
+  resume?(state: Record<string, unknown>, options?: unknown): Promise<ApiSandboxSession>;
+  delete?(state: Record<string, unknown>): Promise<void>;
 };
 
 export type ResumeBoxByIdInput = {