@opengeni/runtime 0.2.0

package/src/sandbox/recording.ts

@@ -0,0 +1,286 @@
+// @opengeni/runtime/sandbox — the recording loop (P4.3).
+//
+// ffmpeg x11grab on :0 → mp4/webm artifact on the box → read bytes → PUT to
+// object storage → recording.available. The "agent films itself proving the fix"
+// loop: ffmpeg reads exactly the :0 framebuffer the agent's computer-use draws to
+// and the human watches over Channel B (zero projection).
+//
+// These are PLAIN functions over a live, externally-owned session handle — NO
+// Temporal, NO worker RPC, NO actor. They live in the agent-loop-free leaf so the
+// SAME process that already holds the resumed-by-id box (the agent turn's own
+// activity for an on-turn recording, or the API in-process for an off-turn/manual
+// finalize) reads the bytes and PUTs them straight to storage. The bytes go
+// box → process memory → storage PUT and are NEVER serialized as a Temporal
+// activity result — the 256 MB-vs-payload-limit concern dissolves (F10).
+//
+// ── Adversarial-review fixes folded in (module 05 §Adversarial) ──────────────
+//   F1  exec is OPTIONAL on Modal (only execCommand) — every command dual-paths.
+//   F3  exec/execCommand YIELDS — the SIGINT-and-wait loop is bounded well under
+//       the yield window; a direct `base64` exec does the byte transfer.
+//   F8  the byte read does NOT assume any over-limit behavior — we cap the ffmpeg
+//       file by size on the box first (stat) and fail `max-bytes-exceeded` rather
+//       than silently uploading a truncated video.
+//   FR  the byte transfer is a DIRECT exec (`base64 <abs-path>`), NOT readFile:
+//       the recording lives at an absolute /tmp path (never the user's workspace
+//       /git tree), and readFile rejects paths outside the manifest workspace
+//       root ("escapes the workspace root"). The base64 exec passes
+//       maxOutputTokens:null so a large recording is never truncated.
+//   F9  the box file is deleted ONLY after the storage PUT confirms — never
+//       before (so a failed upload leaves the bytes recoverable for a retry).
+//   F12 ffmpeg/x11vnc backgrounding does not block the yield (nohup … & echo $!).
+//   F14 duration is computed from wall-clock (stop − start), not assumed.
+
+import { DESKTOP_STREAM_PORT } from "@opengeni/contracts";
+
+export { DESKTOP_STREAM_PORT };
+
+export type RecordingCodec = "h264-mp4" | "vp9-webm";
+export type RecordingContentType = "video/mp4" | "video/webm";
+
+const DEFAULT_MAX_SECONDS = 600; // 10 min hard ceiling (the -t bound)
+const DEFAULT_FRAMERATE = 15;
+const DEFAULT_MAX_BYTES = 268_435_456; // 256 MB
+const DEFAULT_DIMENSIONS: [number, number] = [1280, 800];
+// The SIGINT-and-wait loop is bounded well under the command yield window (F3).
+const STOP_YIELD_MS = 20_000;
+const EXEC_YIELD_MS = 15_000;
+
+export function contentTypeForCodec(codec: RecordingCodec): RecordingContentType {
+  return codec === "vp9-webm" ? "video/webm" : "video/mp4";
+}
+export function extForCodec(codec: RecordingCodec): string {
+  return codec === "vp9-webm" ? "webm" : "mp4";
+}
+
+/** No exec/execCommand on the session — the box cannot run ffmpeg. */
+export class RecordingUnavailableError extends Error {
+  constructor(message: string) { super(message); this.name = "RecordingUnavailableError"; }
+}
+/** ffmpeg failed, the file is missing, or the byte read failed. */
+export class RecordingError extends Error {
+  constructor(message: string, readonly reason: "ffmpeg-error" | "box-death" | "max-bytes-exceeded" | "display-unavailable") {
+    super(message);
+    this.name = "RecordingError";
+  }
+}
+
+// The structural slice of a provider session the recording loop drives. exec and
+// execCommand are optional (Modal has only execCommand — F1); readFile present on
+// every desktop-capable provider.
+type ExecResultLike = { output?: string; stdout?: string; stderr?: string; exitCode?: number | null; sessionId?: number };
+type RecordingSession = {
+  exec?: (args: { cmd: string; runAs?: string; yieldTimeMs?: number; maxOutputTokens?: number }) => Promise<ExecResultLike>;
+  execCommand?: (args: { cmd: string; runAs?: string; yieldTimeMs?: number; maxOutputTokens?: number }) => Promise<string>;
+  readFile?: (args: { path: string; runAs?: string; maxBytes?: number }) => Promise<string | Uint8Array>;
+};
+
+function shq(s: string): string {
+  return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+
+function resultOutput(result: ExecResultLike | string): string {
+  if (typeof result === "string") return result;
+  return [result.output, result.stderr, result.stdout].filter((v): v is string => typeof v === "string" && v.length > 0).join("\n");
+}
+
+// Default per-command output cap (tokens). The byte-read path overrides this to
+// `null` (no truncation) so a base64-encoded recording is never clipped.
+const DEFAULT_MAX_OUTPUT_TOKENS = 4_000;
+
+async function run(
+  session: RecordingSession,
+  cmd: string,
+  runAs?: string,
+  yieldTimeMs = EXEC_YIELD_MS,
+  maxOutputTokens: number | null = DEFAULT_MAX_OUTPUT_TOKENS,
+): Promise<string> {
+  // `maxOutputTokens: null` disables the provider's output truncation entirely
+  // (SDK truncateOutput returns the raw text when the cap is nullish).
+  const args = { cmd, ...(runAs ? { runAs } : {}), yieldTimeMs, maxOutputTokens } as {
+    cmd: string; runAs?: string; yieldTimeMs?: number; maxOutputTokens?: number;
+  };
+  if (typeof session.exec === "function") {
+    return resultOutput(await session.exec(args));
+  }
+  if (typeof session.execCommand === "function") {
+    return resultOutput(await session.execCommand(args));
+  }
+  throw new RecordingUnavailableError("session cannot run commands (no exec/execCommand) — recording unavailable");
+}
+
+// Extract the command body from a provider exec banner. Modal's execCommand
+// returns "<chunk banner>\nProcess exited…\nOutput:\n<body>"; the body is what
+// follows the last "Output:\n" marker. Plain exec results (no banner) pass
+// through unchanged.
+function stripExecBanner(raw: string): string {
+  const marker = raw.lastIndexOf("\nOutput:\n");
+  if (marker >= 0) return raw.slice(marker + "\nOutput:\n".length);
+  if (raw.startsWith("Output:\n")) return raw.slice("Output:\n".length);
+  return raw;
+}
+
+export type StartRecordingInput = {
+  recordingId: string;
+  codec?: RecordingCodec;
+  framerate?: number;
+  maxSeconds?: number;
+  dimensions?: [number, number];
+  display?: string; // ":0"
+  runAs?: string;
+  tmpDir?: string; // "/tmp"
+};
+
+export type RecordingProcess = {
+  recordingId: string;
+  codec: RecordingCodec;
+  boxPath: string;
+  pidFile: string;
+  dimensions: [number, number];
+  framerate: number;
+  /** epoch-ms when ffmpeg was launched (for duration computation, F14). */
+  startedAt: number;
+  display: string;
+  runAs?: string;
+};
+
+/**
+ * Launch ffmpeg x11grab on :0 → an mp4/webm file on the box. Backgrounded with
+ * `nohup … & echo $!` so the launch returns immediately (F12 — the exec does not
+ * block on the recording). A hard `-t <maxSeconds>` ceiling bounds a runaway file
+ * across a multi-day turn. Returns the handle the caller carries to stop+finalize.
+ */
+export async function startRecording(session: unknown, input: StartRecordingInput): Promise<RecordingProcess> {
+  const s = session as RecordingSession;
+  const codec = input.codec ?? "h264-mp4";
+  const dimensions = input.dimensions ?? DEFAULT_DIMENSIONS;
+  const framerate = input.framerate ?? DEFAULT_FRAMERATE;
+  const maxSeconds = input.maxSeconds ?? DEFAULT_MAX_SECONDS;
+  const display = input.display ?? ":0";
+  const tmp = input.tmpDir ?? "/tmp";
+  const ext = extForCodec(codec);
+  const boxPath = `${tmp}/og-rec-${input.recordingId}.${ext}`;
+  const pidFile = `${tmp}/og-rec-${input.recordingId}.pid`;
+  const logFile = `${tmp}/og-rec-${input.recordingId}.log`;
+  const [w, h] = dimensions;
+  const enc = codec === "vp9-webm"
+    ? `-c:v libvpx-vp9 -b:v 0 -crf 32 -row-mt 1`
+    : `-c:v libx264 -preset veryfast -pix_fmt yuv420p -movflags +faststart`;
+  const ffmpeg =
+    `nohup ffmpeg -hide_banner -loglevel error -f x11grab -draw_mouse 1 -framerate ${framerate} ` +
+    `-video_size ${w}x${h} -i ${display}.0 -t ${maxSeconds} ${enc} ${boxPath} ` +
+    `</dev/null >${logFile} 2>&1 & echo $! > ${pidFile}`;
+  await run(s, `bash -lc ${shq(ffmpeg)}`, input.runAs);
+  return {
+    recordingId: input.recordingId,
+    codec,
+    boxPath,
+    pidFile,
+    dimensions,
+    framerate,
+    startedAt: Date.now(),
+    display,
+    ...(input.runAs ? { runAs: input.runAs } : {}),
+  };
+}
+
+/**
+ * SIGINT ffmpeg (so it writes a clean moov atom / webm trailer) and wait for the
+ * pid to exit. Bounded well under the yield window (F3). Idempotent: a missing
+ * pid file is a no-op.
+ */
+export async function stopRecording(session: unknown, proc: RecordingProcess): Promise<void> {
+  const s = session as RecordingSession;
+  const wait = `kill -INT "$(cat ${proc.pidFile})" 2>/dev/null; for i in $(seq 1 80); do kill -0 "$(cat ${proc.pidFile})" 2>/dev/null || break; sleep 0.1; done`;
+  await run(s, `bash -lc ${shq(wait)}`, proc.runAs, STOP_YIELD_MS).catch(() => undefined);
+}
+
+export type FinalizeRecordingResult = {
+  bytes: Uint8Array;
+  contentType: RecordingContentType;
+  sizeBytes: number;
+  durationSeconds: number;
+};
+
+/**
+ * Read the finalized recording bytes off the box.
+ *
+ * TRANSPORT: the bytes are read via a DIRECT exec (`base64 <path>` over stdout),
+ * NOT via session.readFile(). The recording artifact lives at an absolute /tmp
+ * path on purpose — recordings must never be written inside the user's workspace
+ * /git tree — but session.readFile() resolves every path against the manifest
+ * workspace root and rejects anything outside it ("Sandbox path … escapes the
+ * workspace root"), which fataled finalize. Raw exec runs unrestricted shell, so
+ * `base64` reads the /tmp file directly; we decode the base64 back to bytes here.
+ * The byte-read exec passes `maxOutputTokens: null` so the provider never
+ * truncates a large recording's base64.
+ *
+ * F8: we DO NOT assume any over-limit behavior. First `stat` the file size on the
+ * box; if it exceeds maxBytes, fail `max-bytes-exceeded` (never upload a truncated
+ * video). Otherwise read the raw bytes.
+ *
+ * F9: this does NOT delete the box file. The caller deletes it (deleteRecordingArtifacts)
+ * ONLY after the storage PUT + `available` commit — so a failed upload leaves the
+ * bytes recoverable on the box for a retry.
+ *
+ * F14: duration is wall-clock (now − startedAt), a close approximation of the
+ * SIGINT-flushed video length.
+ */
+export async function readRecordingBytes(session: unknown, proc: RecordingProcess, maxBytes = DEFAULT_MAX_BYTES): Promise<FinalizeRecordingResult> {
+  const s = session as RecordingSession;
+  if (typeof s.exec !== "function" && typeof s.execCommand !== "function") {
+    throw new RecordingUnavailableError("session cannot run commands (no exec/execCommand) — recording finalize unavailable");
+  }
+  // F8: size-gate on the box before reading into memory.
+  const sizeOut = (await run(s, `bash -lc ${shq(`stat -c %s ${proc.boxPath} 2>/dev/null || echo MISSING`)}`, proc.runAs)).trim();
+  const sizeLine = sizeOut.split("\n").map((l) => l.trim()).filter(Boolean).pop() ?? "MISSING";
+  if (sizeLine === "MISSING" || sizeLine === "") {
+    throw new RecordingError(`recording file missing on box: ${proc.boxPath}`, "box-death");
+  }
+  const size = Number(sizeLine);
+  if (!Number.isFinite(size) || size <= 0) {
+    throw new RecordingError(`recording file empty on box: ${proc.boxPath}`, "ffmpeg-error");
+  }
+  if (size > maxBytes) {
+    throw new RecordingError(`recording ${size}B exceeds max ${maxBytes}B`, "max-bytes-exceeded");
+  }
+  // Read the bytes via a DIRECT exec (base64, no output truncation), so the
+  // absolute /tmp path is NOT run through the workspace-root-scoped readFile guard.
+  const STOP_YIELD = 60_000; // a large recording's base64 read may take longer than the default exec yield.
+  const encoded = stripExecBanner(
+    await run(s, `bash -lc ${shq(`base64 ${proc.boxPath}`)}`, proc.runAs, STOP_YIELD, null),
+  );
+  const base64 = encoded.replace(/\s+/g, "");
+  if (base64.length === 0) {
+    throw new RecordingError(`recording read returned 0 bytes: ${proc.boxPath}`, "ffmpeg-error");
+  }
+  let bytes: Uint8Array;
+  try {
+    bytes = Uint8Array.from(Buffer.from(base64, "base64"));
+  } catch (error) {
+    throw new RecordingError(`recording base64 decode failed: ${error instanceof Error ? error.message : String(error)}`, "ffmpeg-error");
+  }
+  if (bytes.length === 0) {
+    throw new RecordingError(`recording read returned 0 bytes: ${proc.boxPath}`, "ffmpeg-error");
+  }
+  return {
+    bytes,
+    contentType: contentTypeForCodec(proc.codec),
+    sizeBytes: bytes.length,
+    durationSeconds: Math.max(0, Math.round((Date.now() - proc.startedAt) / 1000)),
+  };
+}
+
+/**
+ * Delete the box artifacts. F9: call this ONLY after the storage PUT confirmed
+ * and the `available` row committed — never before. Best-effort; never throws.
+ */
+export async function deleteRecordingArtifacts(session: unknown, proc: RecordingProcess): Promise<void> {
+  const s = session as RecordingSession;
+  const logFile = proc.boxPath.replace(/\.(mp4|webm)$/, ".log");
+  await run(s, `rm -f ${proc.boxPath} ${proc.pidFile} ${logFile}`, proc.runAs).catch(() => undefined);
+}
+
+/** The storage object key for a recording artifact (parallels the file-asset layout). */
+export function recordingStorageKey(workspaceId: string, sessionId: string, recordingId: string, codec: RecordingCodec): string {
+  return `recordings/${workspaceId}/${sessionId}/${recordingId}.${extForCodec(codec)}`;
+}

package/src/sandbox/routing/backend-resolver.ts

@@ -0,0 +1,189 @@
+// `makeActiveBackendResolver` — builds the `resolveActiveBackend` closure the
+// `RoutingSandboxSession` calls to turn an active pointer into a live backend
+// session (M7). It is the heterogeneous-dispatch core: a pointer's target is
+// EITHER the session's own group sandbox (the default, `activeSandboxId === null`)
+// OR a first-class named sandbox the session swapped to — a sibling Modal box or
+// a selfhosted machine.
+//
+// This lives in the agent-loop-free leaf and depends ONLY on injected closures +
+// the selfhosted session builder, so the API/worker wire it to the real DB
+// (`getSandbox`/`getEnrollment`/`readActiveSandbox`) + the live NATS ControlRpc
+// without coupling the leaf to `@opengeni/db`.
+//
+// The DEFAULT target (the group box) is supplied as an already-established
+// session (the turn box `resumeBoxForTurn` produced, or the Channel-A established
+// handle) — the proxy does NOT re-establish it (the lease owns its lifecycle). A
+// NON-DEFAULT selfhosted target builds a `SelfhostedSession` bound to the target's
+// enrollment agentId, fenced under the swap's active_epoch. A non-default MODAL
+// target is established via the injected `establishModalTarget` resolver (the
+// API/worker pass a resume-by-id closure for the sibling box's lease).
+
+import { buildSelfhostedBackendSession, type SelfhostedRelayConfig } from "../selfhosted/session";
+import type { ControlRpc } from "../selfhosted/control-rpc";
+import type {
+  ActivePointer,
+  RoutableBackendSession,
+  ResolvedActiveBackend,
+} from "./routing-session";
+
+/** The structural slice of a first-class sandbox the resolver reads (mirror of
+ *  `@opengeni/db`'s `SandboxRecord`; structural so the leaf does not import DB). */
+export interface RoutableSandbox {
+  id: string;
+  kind: "modal" | "selfhosted" | string;
+  name: string;
+  /** For a selfhosted sandbox this is its enrollment id (== the agent id the
+   *  control-plane subject `agent.<ws>.<id>.rpc` addresses). Null for modal. */
+  enrollmentId: string | null;
+}
+
+export interface ActiveBackendResolverDeps {
+  /** The workspace the session belongs to (the control-plane subject scope). */
+  workspaceId: string;
+  /** The session's own group sandbox session — the DEFAULT target
+   *  (`activeSandboxId === null`). Already established (lease-owned); the proxy
+   *  never re-establishes it. */
+  defaultBackend: RoutableBackendSession;
+  /** A label for the default backend (its backend id: "modal"/"selfhosted"/…). */
+  defaultKind: string;
+  /** Look up a first-class sandbox by id (the swap target). Returns null when the
+   *  id is unknown or not in this workspace (the caller 409s the swap). */
+  getSandbox(sandboxId: string): Promise<RoutableSandbox | null>;
+  /** Build a live `ControlRpc` for the selfhosted control plane (the request-
+   *  scoped NATS connection). Returns a ControlRpc whose offline/timeout maps to
+   *  agent_offline/agent_reconnecting (never a NotFound). */
+  controlRpcFactory(): ControlRpc;
+  /** The relay-URL shape config for selfhosted stream endpoints. */
+  relay: SelfhostedRelayConfig;
+  /** Establish (resume-by-id) a NON-DEFAULT modal target's box session for a swap.
+   *  Supplied by the API/worker (a closure over the sibling sandbox's lease). When
+   *  absent, a modal swap target surfaces as unsupported (the caller validated
+   *  liveness, so this is the "modal swap not wired in this context" guard). */
+  establishModalTarget?: (sandbox: RoutableSandbox) => Promise<RoutableBackendSession>;
+  /** Override the selfhosted control-op timeout (tests). */
+  selfhostedTimeoutMs?: number;
+  /**
+   * The run's declared sandbox environment — the SAME `Record<string,string>` the
+   * worker turn threads into the agent's TARGET manifest (and into the group box at
+   * create). Threaded into a selfhosted swap target's session so its
+   * `state.manifest.environment` EQUALS the turn's, making the SDK's per-turn
+   * provided-session manifest-env delta empty (validateNoEnvironmentDelta).
+   * WITHOUT this a pin-to-vm turn throws "Live sandbox sessions cannot change
+   * manifest environment variables". Omitted → `{}` (the test/negotiation path).
+   */
+  environment?: Record<string, string>;
+  /**
+   * A pre-established selfhosted session to PIN for the STEADY-STATE machine
+   * pointer (the worker turn's machine-primary path, Stage D). When the pointer
+   * targets THIS sandbox at THIS epoch, the resolver returns this SAME instance
+   * instead of building a fresh `SelfhostedSession`. This is the instance-identity
+   * pin: the SDK reads/writes `state.manifest` at turn START via the proxy's `state`
+   * getter (which reads the default/last-resolved backend's state) and then reads it
+   * per op via this resolver — those MUST land on ONE SelfhostedSession/manifest, or
+   * a turn-start manifest write is invisible to the per-op reads (two-instance
+   * divergence). A swap AWAY (a different sandbox id, or the same id at a moved epoch)
+   * falls through to a fresh build under the new epoch. Omitted for the API/live-swap
+   * path (which always builds fresh — it has no pre-established turn session).
+   */
+  pinnedSelfhosted?: { sandboxId: string; epoch: number; session: RoutableBackendSession };
+}
+
+/** Thrown when a swap target cannot be resolved (unknown sandbox, or a modal
+ *  target with no establisher in this context). The caller maps it to a 409. */
+export class ActiveBackendUnresolvableError extends Error {
+  readonly name = "ActiveBackendUnresolvableError";
+  constructor(message: string) {
+    super(message);
+  }
+}
+
+/**
+ * Build the `resolveActiveBackend(pointer)` closure for a `RoutingSandboxSession`.
+ * The returned closure is re-invoked by the proxy whenever the active_epoch moves
+ * (the per-epoch cache miss), so it must be cheap-and-correct for the steady-state
+ * (default pointer → the already-established group box) and build a fresh backend
+ * for a swap target.
+ *
+ *  - `activeSandboxId === null` → the default group backend (no re-establish).
+ *  - a selfhosted target → a `SelfhostedSession` bound to the enrollment agentId,
+ *    fenced under `pointer.activeEpoch` (echoed on every ControlRequest so the
+ *    agent can reject a stale op with ERROR_CODE_FENCED — the swap-race fence).
+ *  - a modal target → `establishModalTarget` (the resume-by-id closure), else
+ *    unresolvable.
+ */
+export function makeActiveBackendResolver(
+  deps: ActiveBackendResolverDeps,
+): (pointer: ActivePointer) => Promise<ResolvedActiveBackend> {
+  return async (pointer: ActivePointer): Promise<ResolvedActiveBackend> => {
+    // The DEFAULT target: the session's own group sandbox (backward-compat). The
+    // proxy routes to the already-established box; the lease owns its lifecycle.
+    if (pointer.activeSandboxId === null) {
+      return { session: deps.defaultBackend, sandboxId: null, kind: deps.defaultKind };
+    }
+
+    // INSTANCE PIN (Stage D machine-primary): the steady-state machine pointer
+    // returns the pre-established turn session BY REFERENCE — never a fresh build —
+    // so the turn-start manifest write + the per-op reads land on ONE
+    // SelfhostedSession/manifest. Matched on BOTH the sandbox id AND the epoch: a
+    // swap away (different id) or a swap-back (same id, higher epoch) falls through
+    // to a fresh build fenced under the CURRENT epoch (the stale pinned instance is
+    // fenced at the old epoch and must not be reused).
+    if (
+      deps.pinnedSelfhosted
+      && pointer.activeSandboxId === deps.pinnedSelfhosted.sandboxId
+      && pointer.activeEpoch === deps.pinnedSelfhosted.epoch
+    ) {
+      return { session: deps.pinnedSelfhosted.session, sandboxId: pointer.activeSandboxId, kind: "selfhosted" };
+    }
+
+    const sandbox = await deps.getSandbox(pointer.activeSandboxId);
+    if (!sandbox) {
+      throw new ActiveBackendUnresolvableError(
+        `active sandbox ${pointer.activeSandboxId} not found in workspace ${deps.workspaceId}`,
+      );
+    }
+
+    if (sandbox.kind === "selfhosted") {
+      if (!sandbox.enrollmentId) {
+        throw new ActiveBackendUnresolvableError(
+          `selfhosted sandbox ${sandbox.id} has no enrollment (agent id) to address`,
+        );
+      }
+      // Build a request-scoped selfhosted client bound to the target's workspace +
+      // enrollment agentId, fenced under the swap's active_epoch. The agent echoes
+      // the epoch and rejects a stale op with ERROR_CODE_FENCED → the proxy
+      // re-resolves + retries against the new active sandbox. The SAME factory the
+      // worker turn's machine-primary establish branch uses (one build shape).
+      const { session } = await buildSelfhostedBackendSession({
+        workspaceId: deps.workspaceId,
+        relay: deps.relay,
+        controlRpcFactory: deps.controlRpcFactory,
+        agentId: sandbox.enrollmentId,
+        epoch: pointer.activeEpoch,
+        ...(deps.selfhostedTimeoutMs !== undefined ? { timeoutMs: deps.selfhostedTimeoutMs } : {}),
+        // The turn's declared environment → the session's manifest.environment, so
+        // the SDK's per-turn manifest-env delta is empty (no "cannot change manifest
+        // environment variables" throw on a pin-to-vm turn).
+        ...(deps.environment !== undefined ? { environment: deps.environment } : {}),
+        // The session's working directory (per-session pointer) → the path/cwd base
+        // for this selfhosted backend. Absent/empty ⇒ the default workspace_root.
+        ...(pointer.workingDir ? { workingDir: pointer.workingDir } : {}),
+      });
+      return { session: session as RoutableBackendSession, sandboxId: sandbox.id, kind: "selfhosted" };
+    }
+
+    if (sandbox.kind === "modal") {
+      if (!deps.establishModalTarget) {
+        throw new ActiveBackendUnresolvableError(
+          `modal swap target ${sandbox.id} cannot be established in this context (no establisher wired)`,
+        );
+      }
+      const session = await deps.establishModalTarget(sandbox);
+      return { session, sandboxId: sandbox.id, kind: "modal" };
+    }
+
+    throw new ActiveBackendUnresolvableError(
+      `unsupported swap target kind "${sandbox.kind}" for sandbox ${sandbox.id}`,
+    );
+  };
+}