@opengeni/api-router 0.26.1 → 0.30.1

package/src/routes/computer-sessions.ts

@@ -2,7 +2,9 @@ import { randomUUID } from "node:crypto";
 import { resolveFirstPartyDelegationSecret, resolveStreamTokenSecret } from "@opengeni/config";
 import {
   BROWSER_CONTROL_WEBSOCKET_BEARER_PREFIX,
+  BROWSER_CONTROL_PORT,
   COMPUTER_CONTROL_WEBSOCKET_PROTOCOL,
+  COMPUTER_RFB_WEBSOCKET_PROTOCOL,
   ComputerActionCommand,
   ComputerActionRequest,
   ComputerSessionAttachment,
@@ -32,12 +34,16 @@ import {
   dispatchComputerSessionOperation,
   failComputerSessionOperation,
   findComputerSessionControlRecordByOperation,
+  getAttachedBrowserDevice,
   getComputerSessionControlRecord,
+  getEnrollment,
   getSession,
   listComputerSessions,
   prepareComputerSessionCreate,
   prepareComputerSessionEnd,
   releaseLeaseHolder,
+  readLease,
+  recordLeaseControllerDataPlaneUrl,
   touchComputerSessionController,
   type ComputerSessionControlRecord,
   type LeaseSnapshot,
@@ -45,21 +51,26 @@ import {
 import {
   requireAccessGrant,
   requireSessionAuthorization,
+  relayConfigFromSettings,
   SessionAuthorizationDeniedError,
   SessionAuthorizationUnavailableError,
   type ApiRouteDeps,
 } from "@opengeni/core";
 import {
+  BrowserControlClient,
   BrowserControlProtocolError,
   BrowserControlRequestError,
   BrowserControlServerError,
   BrowserControlServerUnsupportedError,
   BrowserControlTransportError,
   BrowserControlUnsupportedError,
+  buildSelfhostedBackendSession,
   buildStreamUrl,
+  exposedPortEndpointFromUrl,
   mintStreamToken,
+  NatsControlRpc,
+  NatsOpStreamTransport,
   provisionBrowserControlClient,
-  type BrowserControlClient,
   type BrowserControlPlacementSession,
 } from "@opengeni/runtime/sandbox";
 import type { Context, Hono } from "hono";
@@ -70,8 +81,11 @@ import {
   deriveComputerSessionControllerTokens,
   deriveComputerViewGrantToken,
 } from "../browser-controller-authority";
+import { withCachedController } from "../controller-data-plane";
+import { withInteractionHolderHeartbeat } from "../interaction-holder-heartbeat";
 import { allowedCorsOrigin } from "../http/cors";
-import { withChannelA, type ChannelAOperation } from "../sandbox/channel-a";
+import { observeComputerActionResult, observeLifecycleResult } from "../interaction-metrics";
+import { withChannelA, withChannelARead, type ChannelAOperation } from "../sandbox/channel-a";
 
 type ComputerPlacement = {
   placement: InteractionPlacement;
@@ -125,6 +139,7 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
     const workspaceId = context.req.param("workspaceId") ?? "";
     const grant = await requireAccessGrant(context, deps, workspaceId, "sessions:control");
     const request = await parseJsonBody(context, CreateComputerSessionRequest);
+    const startedAtMs = performance.now();
     await authorizeSourceSession(deps, grant, request.sessionId, "session.control");
     const origin = requestOrigin(context, deps.settings.corsAllowOriginRegex);
     const authority = controllerAuthorityRoot(deps);
@@ -148,7 +163,9 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
           )
         : null;
       if (prepared && isTerminalOperation(prepared.operation.state)) {
-        return context.json(ComputerSessionMutationResponse.parse(prepared), 200);
+        const parsed = ComputerSessionMutationResponse.parse(prepared);
+        observeLifecycleResult(deps.observability, startedAtMs, parsed);
+        return context.json(parsed, 200);
       }
 
       const sourceSession = await requireSourceSession(deps, workspaceId, request.sessionId);
@@ -181,7 +198,18 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
             prepared.session.id,
             request.operationId,
             placement.placementInstanceId,
-          );
+          ).catch(async (error: unknown) => {
+            if (interactionHeld) {
+              await releaseInteractionHolder(
+                grant,
+                workspaceId,
+                prepared!.session.id,
+                placement.placement,
+              ).catch(() => undefined);
+            }
+            throw error;
+          });
+          const preparedSession = prepared.session;
           const controllerGeneration = requireOperationGeneration(record);
           const adminToken = deriveBrowserControllerAdminToken({
             rootSecret: authority,
@@ -202,21 +230,45 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
           });
           let physical;
           try {
-            const { client } = await provisionBrowserControlClient(placement.session, {
+            physical = await withComputerCreationController(
+              grant,
+              workspaceId,
+              placement,
               adminToken,
-              nativeAuthority: nativeControllerAuthority(workspaceId, placement),
-              ...(origin ? { allowedOrigins: [origin] } : {}),
-            });
-            physical = await client.createComputerSession({
-              computerSessionId: prepared.session.id,
-              controllerGeneration,
-              tokenGeneration: record.tokenGeneration,
-              ...tokens,
-            });
+              origin,
+              async (client) =>
+                await withInteractionHolderHeartbeat(
+                  deps,
+                  {
+                    grant,
+                    workspaceId,
+                    sandboxGroupId:
+                      placement.placement.kind === "sandbox_group"
+                        ? placement.placement.sandboxGroupId
+                        : null,
+                    holderId: interactionHolderId(preparedSession.id),
+                    operationId: request.operationId,
+                    resourceId: preparedSession.id,
+                    controllerGeneration,
+                  },
+                  async () =>
+                    await client.createComputerSession({
+                      computerSessionId: preparedSession.id,
+                      controllerGeneration,
+                      tokenGeneration: record.tokenGeneration,
+                      ...tokens,
+                    }),
+                ),
+            );
+            await cacheComputerControllerPlacement(grant, workspaceId, placement).catch(
+              () => placement,
+            );
           } catch (error) {
             if (
               error instanceof BrowserControlTransportError ||
-              (error instanceof BrowserControlRequestError && error.retryable) ||
+              (error instanceof BrowserControlRequestError &&
+                error.retryable &&
+                error.error.code !== "machine_locked") ||
               isAbort(error)
             ) {
               throw error;
@@ -225,7 +277,7 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
               accountId: grant.accountId,
               workspaceId,
               operationId: request.operationId,
-              computerSessionId: prepared.session.id,
+              computerSessionId: preparedSession.id,
               ...(error instanceof BrowserControlProtocolError
                 ? { state: "outcome_unknown" as const }
                 : {}),
@@ -247,7 +299,7 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
             accountId: grant.accountId,
             workspaceId,
             operationId: request.operationId,
-            computerSessionId: prepared.session.id,
+            computerSessionId: preparedSession.id,
             controller: {
               controllerId: "opengeni-browserd",
               controllerGeneration,
@@ -262,6 +314,7 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
         },
       );
       const parsed = ComputerSessionMutationResponse.parse(response);
+      observeLifecycleResult(deps.observability, startedAtMs, parsed);
       return context.json(
         parsed,
         parsed.operation.state === "completed" && !parsed.operation.replayed ? 201 : 200,
@@ -317,6 +370,26 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
     },
   );
 
+  app.get(
+    "/v1/workspaces/:workspaceId/computer-sessions/:computerSessionId/clipboard",
+    async (context) => {
+      const { workspaceId, grant, computerSessionId } = await routePreamble(
+        context,
+        "sessions:read",
+      );
+      const result = await withActiveComputerController(
+        context,
+        grant,
+        workspaceId,
+        computerSessionId,
+        "session.read",
+        "computer.read",
+        async ({ sessionClient }) => await sessionClient.readClipboard(),
+      );
+      return context.json(result);
+    },
+  );
+
   app.post(
     "/v1/workspaces/:workspaceId/computer-sessions/:computerSessionId/actions",
     async (context) => {
@@ -325,13 +398,14 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
         "sessions:control",
       );
       const request = await parseJsonBody(context, ComputerActionRequest);
+      const startedAtMs = performance.now();
       const result = await withActiveComputerController(
         context,
         grant,
         workspaceId,
         computerSessionId,
         "session.control",
-        "computer.control",
+        "computer.action",
         async ({ sessionClient, binding }) =>
           await sessionClient.action(
             ComputerActionCommand.parse({
@@ -348,6 +422,7 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
             }),
           ),
       );
+      observeComputerActionResult(deps.observability, startedAtMs, request, result);
       return context.json(result);
     },
   );
@@ -377,6 +452,7 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
     "/v1/workspaces/:workspaceId/computer-sessions/:computerSessionId/attachments",
     async (context) => {
       const { workspaceId, grant, computerSessionId } = await routePreamble(context, "stream:view");
+      const origin = requestOrigin(context, deps.settings.corsAllowOriginRegex);
       const request = await parseJsonBody(context, ComputerSessionAttachmentRequest);
       const result = await withActiveComputerController(
         context,
@@ -386,7 +462,7 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
         "session.viewer.read",
         "computer.attach",
         async ({ client, sessionClient, record, binding, placement }) => {
-          await sessionClient.observe(request.targetId);
+          if (origin) await client.addAllowedOrigins([origin]);
           const grantId = randomUUID();
           const expiresAt = new Date(Date.now() + request.expiresInSeconds * 1_000).toISOString();
           const token = deriveComputerViewGrantToken({
@@ -406,6 +482,16 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
             controllerGeneration: binding.controllerGeneration,
           };
           await client.createComputerViewGrant(reference, { grantId, token, expiresAt });
+          const target = (await sessionClient.listTargets()).find(
+            (candidate) => candidate.id === request.targetId,
+          );
+          if (!target) {
+            throw new BrowserControlRequestError(404, {
+              code: "target_not_found",
+              message: "computer target does not exist",
+              retryable: false,
+            });
+          }
           const relaySecret = placement.session.openComputerFrames
             ? resolveStreamTokenSecret(deps.settings)
             : null;
@@ -414,13 +500,23 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
               "computer frame relay authority is unavailable",
             );
           }
-          const relayed = await client.openRelayedComputerFrameStream({
-            reference,
-            targetId: request.targetId,
-            viewToken: token,
-            expiresAt,
-            ...(request.stream ? { stream: request.stream } : {}),
-          });
+          let relayed = null;
+          try {
+            relayed = await client.openRelayedComputerFrameStream({
+              reference,
+              targetId: request.targetId,
+              viewToken: token,
+              expiresAt,
+              ...(request.stream ? { stream: request.stream } : {}),
+            });
+          } catch (error) {
+            console.error("computer frame relay open failed", {
+              computerSessionId,
+              targetId: request.targetId,
+              failure: error instanceof Error ? error.message : String(error),
+            });
+            throw error;
+          }
           const stream = relayed
             ? await (async () => {
                 const relayToken = await mintStreamToken(relaySecret!, {
@@ -444,14 +540,30 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
                   },
                 };
               })()
-            : {
-                kind: "direct_websocket" as const,
-                url: await client.computerFrameStreamUrl(reference, request.targetId),
-                protocols: [
-                  COMPUTER_CONTROL_WEBSOCKET_PROTOCOL,
-                  `${BROWSER_CONTROL_WEBSOCKET_BEARER_PREFIX}${token}`,
-                ],
-              };
+            : record.session.placement.kind === "sandbox_group" &&
+                record.session.platform === "linux" &&
+                target.kind === "screen"
+              ? {
+                  kind: "direct_rfb" as const,
+                  url: await client.computerRfbStreamUrl(reference, request.targetId),
+                  protocols: [
+                    "binary",
+                    COMPUTER_RFB_WEBSOCKET_PROTOCOL,
+                    `${BROWSER_CONTROL_WEBSOCKET_BEARER_PREFIX}${token}`,
+                  ],
+                }
+              : {
+                  kind: "direct_websocket" as const,
+                  url: await client.computerFrameStreamUrl(
+                    reference,
+                    request.targetId,
+                    request.stream,
+                  ),
+                  protocols: [
+                    COMPUTER_CONTROL_WEBSOCKET_PROTOCOL,
+                    `${BROWSER_CONTROL_WEBSOCKET_BEARER_PREFIX}${token}`,
+                  ],
+                };
           return ComputerSessionAttachment.parse({
             computerSessionId,
             controllerGeneration: binding.controllerGeneration,
@@ -488,6 +600,7 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
             alive: true,
           });
         },
+        false,
       );
       return context.json(result);
     },
@@ -500,6 +613,7 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
       const grant = await requireAccessGrant(context, deps, workspaceId, "sessions:control");
       const computerSessionId = requireUuidParam(context, "computerSessionId");
       const request = await parseJsonBody(context, ComputerSessionLifecycleRequest);
+      const startedAtMs = performance.now();
       const origin = requestOrigin(context, deps.settings.corsAllowOriginRegex);
       try {
         const before = await getComputerSessionControlRecord(deps.db, {
@@ -525,7 +639,9 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
               before.session.placement,
             ).catch(() => undefined);
           }
-          return context.json(ComputerSessionMutationResponse.parse(prepared), 200);
+          const parsed = ComputerSessionMutationResponse.parse(prepared);
+          observeLifecycleResult(deps.observability, startedAtMs, parsed);
+          return context.json(parsed, 200);
         }
 
         const record = await getComputerSessionControlRecord(deps.db, {
@@ -549,7 +665,9 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
             computerSessionId,
             record.session.placement,
           ).catch(() => undefined);
-          return context.json(ComputerSessionMutationResponse.parse(completed), 200);
+          const parsed = ComputerSessionMutationResponse.parse(completed);
+          observeLifecycleResult(deps.observability, startedAtMs, parsed);
+          return context.json(parsed, 200);
         }
 
         const sourceSession = await requireSourceSession(deps, workspaceId, record.sourceSessionId);
@@ -570,12 +688,28 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
             });
             const client = await provisionController(grant, record, placement, origin);
             try {
-              await client.endComputerSession(
+              await withInteractionHolderHeartbeat(
+                deps,
                 {
-                  computerSessionId,
+                  grant,
+                  workspaceId,
+                  sandboxGroupId:
+                    placement.placement.kind === "sandbox_group"
+                      ? placement.placement.sandboxGroupId
+                      : null,
+                  holderId: interactionHolderId(computerSessionId),
+                  operationId: request.operationId,
+                  resourceId: computerSessionId,
                   controllerGeneration: binding.controllerGeneration,
                 },
-                { removeState: true },
+                async () =>
+                  await client.endComputerSession(
+                    {
+                      computerSessionId,
+                      controllerGeneration: binding.controllerGeneration,
+                    },
+                    { removeState: true },
+                  ),
               );
             } catch (error) {
               if (!(error instanceof BrowserControlRequestError && error.status === 404)) {
@@ -598,7 +732,9 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
             return completed;
           },
         );
-        return context.json(ComputerSessionMutationResponse.parse(response), 200);
+        const parsed = ComputerSessionMutationResponse.parse(response);
+        observeLifecycleResult(deps.observability, startedAtMs, parsed);
+        return context.json(parsed, 200);
       } catch (error) {
         throw computerRouteError(error);
       }
@@ -614,15 +750,66 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
     waitSignal: AbortSignal,
     callback: (placement: ComputerPlacement) => Promise<T>,
   ): Promise<T> {
-    if (
-      expectedPlacement?.kind === "attached_device" ||
-      expectedPlacement?.kind === "external_provider"
-    ) {
+    if (expectedPlacement?.kind === "external_provider") {
       throw new BrowserControlUnsupportedError(
         `computer placement ${expectedPlacement.kind} is not executable`,
       );
     }
-    return await withChannelA(
+    if (expectedPlacement?.kind === "attached_device") {
+      waitSignal.throwIfAborted();
+      const device = await getAttachedBrowserDevice(deps.db, {
+        accountId: grant.accountId,
+        workspaceId: sourceSession.workspaceId,
+        deviceId: expectedPlacement.deviceId,
+      });
+      if (device.state !== "connected") {
+        throw new ComputerSessionStateError("Attached browser machine is disconnected");
+      }
+      const enrollment = await getEnrollment(
+        deps.db,
+        sourceSession.workspaceId,
+        device.enrollmentId,
+      );
+      if (!enrollment || enrollment.status !== "active") {
+        throw new ComputerSessionStateError("Attached browser machine is unavailable");
+      }
+      assertPlacementInstance(expectedPlacementInstanceId, device.connectionGeneration);
+      const built = await buildSelfhostedBackendSession({
+        workspaceId: sourceSession.workspaceId,
+        agentId: device.enrollmentId,
+        relay: relayConfigFromSettings(deps.settings),
+        controlRpcFactory: () => new NatsControlRpc(async () => deps.bus.getRequestConnection()),
+        epoch: 0,
+        timeoutMs: deps.settings.sandboxSelfhostedControlTimeoutMs,
+        execTimeoutMs: deps.settings.sandboxSelfhostedExecTimeoutMs,
+        ...(deps.settings.agentOpStreamEnabled === true &&
+        enrollment.opStream === true &&
+        deps.bus.getOpStreamConnection
+          ? {
+              opStream: {
+                transport: new NatsOpStreamTransport(
+                  async () => deps.bus.getOpStreamConnection?.() ?? null,
+                ),
+              },
+            }
+          : {}),
+      });
+      waitSignal.throwIfAborted();
+      return await callback({
+        placement: expectedPlacement,
+        placementInstanceId: device.connectionGeneration,
+        session: built.session as unknown as BrowserControlPlacementSession,
+        lease: null,
+      });
+    }
+    const runWithChannelA =
+      operation === "computer.read" ||
+      operation === "computer.action" ||
+      operation === "computer.control" ||
+      operation === "computer.attach"
+        ? withChannelARead
+        : withChannelA;
+    return await runWithChannelA(
       channelServices,
       {
         accountId: grant.accountId,
@@ -631,6 +818,7 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
         subjectId: grant.subjectId,
         waitSignal,
         operation,
+        retryControllerTransport: operation === "computer.read" || operation === "computer.action",
       },
       async (handle) => {
         if (expectedPlacement?.kind === "sandbox_group") {
@@ -703,6 +891,108 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
     );
   }
 
+  function controllerOnlySession(url: string): BrowserControlPlacementSession {
+    const endpoint = exposedPortEndpointFromUrl(url);
+    return {
+      resolveExposedPort: async (port: number) => {
+        if (port !== BROWSER_CONTROL_PORT) {
+          throw new BrowserControlUnsupportedError(`cached controller cannot expose port ${port}`);
+        }
+        return endpoint;
+      },
+    };
+  }
+
+  async function cachedComputerPlacement(
+    record: ComputerSessionControlRecord,
+  ): Promise<ComputerPlacement | null> {
+    const binding = record.session.controller;
+    if (!binding || record.session.placement.kind !== "sandbox_group") return null;
+    const sandboxGroupId = record.session.placement.sandboxGroupId;
+    const lease = await readLease(deps.db, record.session.workspaceId, sandboxGroupId);
+    if (
+      !lease ||
+      (lease.liveness !== "warm" && lease.liveness !== "draining") ||
+      lease.instanceId !== binding.placementInstanceId ||
+      !lease.controllerDataPlaneUrl
+    ) {
+      return null;
+    }
+    return {
+      placement: record.session.placement,
+      placementInstanceId: binding.placementInstanceId,
+      session: controllerOnlySession(lease.controllerDataPlaneUrl),
+      lease,
+    };
+  }
+
+  async function cacheComputerControllerPlacement(
+    grant: AccessGrant,
+    workspaceId: string,
+    placement: ComputerPlacement,
+  ): Promise<ComputerPlacement> {
+    if (
+      placement.placement.kind !== "sandbox_group" ||
+      !placement.lease?.instanceId ||
+      !placement.session.resolveExposedPort
+    ) {
+      return placement;
+    }
+    const endpoint = await placement.session.resolveExposedPort(BROWSER_CONTROL_PORT);
+    const url = buildStreamUrl(endpoint);
+    const lease = await recordLeaseControllerDataPlaneUrl(deps.db, {
+      accountId: grant.accountId,
+      workspaceId,
+      sandboxGroupId: placement.placement.sandboxGroupId,
+      expectedEpoch: placement.lease.leaseEpoch,
+      expectedInstanceId: placement.lease.instanceId,
+      controllerDataPlaneUrl: url,
+    });
+    if (!lease) return placement;
+    return { ...placement, session: controllerOnlySession(url), lease };
+  }
+
+  async function withComputerCreationController<T>(
+    grant: AccessGrant,
+    workspaceId: string,
+    placement: ComputerPlacement,
+    adminToken: string,
+    origin: string | null,
+    operation: (client: BrowserControlClient) => Promise<T>,
+  ): Promise<T> {
+    const cachedUrl = placement.lease?.controllerDataPlaneUrl;
+    const sandboxGroupId =
+      placement.placement.kind === "sandbox_group" ? placement.placement.sandboxGroupId : null;
+    return await withCachedController({
+      cachedUrl: sandboxGroupId ? (cachedUrl ?? null) : null,
+      createCachedClient: (url) =>
+        new BrowserControlClient(controllerOnlySession(url), { adminToken }),
+      prepareCachedClient: async (client) => {
+        if (origin) await client.addAllowedOrigins([origin]);
+      },
+      invalidateCachedUrl: async () => {
+        if (!sandboxGroupId || !placement.lease) return;
+        await recordLeaseControllerDataPlaneUrl(deps.db, {
+          accountId: grant.accountId,
+          workspaceId,
+          sandboxGroupId,
+          expectedEpoch: placement.lease.leaseEpoch,
+          expectedInstanceId: placement.placementInstanceId,
+          controllerDataPlaneUrl: null,
+        });
+      },
+      provisionClient: async () => {
+        const { client } = await provisionBrowserControlClient(placement.session, {
+          adminToken,
+          nativeAuthority: nativeControllerAuthority(workspaceId, placement),
+          ...(origin ? { allowedOrigins: [origin] } : {}),
+        });
+        return client;
+      },
+      use: operation,
+    });
+  }
+
   async function withActiveComputerController<T>(
     context: Context,
     grant: AccessGrant,
@@ -717,6 +1007,7 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
       binding: NonNullable<ComputerSessionControlRecord["session"]["controller"]>;
       placement: ComputerPlacement;
     }) => Promise<T>,
+    recoverMissing = true,
   ): Promise<T> {
     try {
       const record = await getComputerSessionControlRecord(deps.db, {
@@ -738,6 +1029,73 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
       if (!admitted) {
         throw new ComputerSessionStateError("ComputerSession controller authority changed");
       }
+      const run = async (placement: ComputerPlacement): Promise<T> => {
+        // The active controller binding is the provisioning fence. Live
+        // input connects to it directly instead of re-ensuring the sidecar.
+        const client = connectController(grant, record, placement);
+        const tokens = deriveComputerSessionControllerTokens({
+          rootSecret: controllerAuthorityRoot(deps),
+          accountId: grant.accountId,
+          workspaceId,
+          placement: record.session.placement,
+          placementInstanceId: placement.placementInstanceId,
+          computerSessionId,
+          controllerGeneration: binding.controllerGeneration,
+          tokenGeneration: record.tokenGeneration,
+        });
+        const controller = {
+          client,
+          sessionClient: client.computerSessionClient({
+            reference: {
+              computerSessionId,
+              controllerGeneration: binding.controllerGeneration,
+            },
+            ...tokens,
+          }),
+          record,
+          binding,
+          placement,
+        };
+        let result: T;
+        try {
+          result = await callback(controller);
+        } catch (error) {
+          if (!recoverMissing || !isMissingComputerControllerSession(error)) throw error;
+          await client.createComputerSession({
+            computerSessionId,
+            controllerGeneration: binding.controllerGeneration,
+            tokenGeneration: record.tokenGeneration,
+            ...tokens,
+          });
+          result = await callback(controller);
+        }
+        return result;
+      };
+      const cached = await cachedComputerPlacement(record);
+      if (cached) {
+        try {
+          return await run(cached);
+        } catch (error) {
+          const safelyReplayable =
+            channelOperation === "computer.read" || channelOperation === "computer.action";
+          if (
+            !safelyReplayable ||
+            (!(error instanceof BrowserControlTransportError) &&
+              !(error instanceof BrowserControlRequestError && error.retryable))
+          ) {
+            throw error;
+          }
+          await recordLeaseControllerDataPlaneUrl(deps.db, {
+            accountId: grant.accountId,
+            workspaceId,
+            sandboxGroupId: cached.lease!.sandboxGroupId,
+            expectedEpoch: cached.lease!.leaseEpoch,
+            expectedInstanceId: cached.placementInstanceId,
+            controllerDataPlaneUrl: null,
+          }).catch(() => null);
+        }
+      }
+
       const sourceSession = await requireSourceSession(deps, workspaceId, record.sourceSessionId);
       return await withComputerPlacement(
         sourceSession,
@@ -746,44 +1104,12 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
         binding.placementInstanceId,
         channelOperation,
         context.req.raw.signal,
-        async (placement) => {
-          const client = await provisionController(
-            grant,
-            record,
-            placement,
-            requestOrigin(context, deps.settings.corsAllowOriginRegex),
-          );
-          const tokens = deriveComputerSessionControllerTokens({
-            rootSecret: controllerAuthorityRoot(deps),
-            accountId: grant.accountId,
-            workspaceId,
-            placement: record.session.placement,
-            placementInstanceId: placement.placementInstanceId,
-            computerSessionId,
-            controllerGeneration: binding.controllerGeneration,
-            tokenGeneration: record.tokenGeneration,
-          });
-          const result = await callback({
-            client,
-            sessionClient: client.computerSessionClient({
-              reference: {
-                computerSessionId,
-                controllerGeneration: binding.controllerGeneration,
-              },
-              ...tokens,
-            }),
-            record,
-            binding,
-            placement,
-          });
-          await touchComputerSessionController(deps.db, {
-            accountId: grant.accountId,
-            workspaceId,
-            computerSessionId,
-            controllerGeneration: binding.controllerGeneration,
-          }).catch(() => false);
-          return result;
-        },
+        async (placement) =>
+          await run(
+            await cacheComputerControllerPlacement(grant, workspaceId, placement).catch(
+              () => placement,
+            ),
+          ),
       );
     } catch (error) {
       throw computerRouteError(error);
@@ -910,6 +1236,23 @@ export function registerComputerSessionRoutes(app: Hono, deps: ApiRouteDeps): vo
     ).client;
   }
 
+  function connectController(
+    grant: AccessGrant,
+    record: ComputerSessionControlRecord,
+    placement: ComputerPlacement,
+  ): BrowserControlClient {
+    return new BrowserControlClient(placement.session, {
+      adminToken: deriveBrowserControllerAdminToken({
+        rootSecret: controllerAuthorityRoot(deps),
+        accountId: grant.accountId,
+        workspaceId: record.session.workspaceId,
+        placement: record.session.placement,
+        placementInstanceId: placement.placementInstanceId,
+      }),
+      nativeAuthority: nativeControllerAuthority(record.session.workspaceId, placement),
+    });
+  }
+
   async function releaseInteractionHolder(
     grant: AccessGrant,
     workspaceId: string,
@@ -1005,9 +1348,11 @@ function nativeControllerAuthority(
   const placementId =
     placement.placement.kind === "connected_machine"
       ? placement.placement.sandboxId
-      : placement.placement.kind === "sandbox_group"
-        ? placement.placement.sandboxGroupId
-        : null;
+      : placement.placement.kind === "attached_device"
+        ? placement.placement.deviceId
+        : placement.placement.kind === "sandbox_group"
+          ? placement.placement.sandboxGroupId
+          : null;
   if (!placementId) {
     throw new BrowserControlUnsupportedError("computer controller placement is unsupported");
   }
@@ -1160,6 +1505,16 @@ function isTerminalOperation(state: string): boolean {
   return state === "completed" || state === "failed" || state === "outcome_unknown";
 }
 
+function isMissingComputerControllerSession(error: unknown): boolean {
+  if (!(error instanceof BrowserControlRequestError)) return false;
+  if (error.status === 401 && error.error.code === "permission_denied") return true;
+  return (
+    error.status === 404 &&
+    error.error.code === "resource_not_found" &&
+    ["computer session not found", "computer session is not active"].includes(error.error.message)
+  );
+}
+
 function interactionFailure(error: unknown) {
   if (error instanceof BrowserControlRequestError) return error.error;
   if (