@opengeni/react 1.0.1 → 2.3.0-canary.0

package/src/hooks/use-computer-frame-stream.ts

@@ -211,10 +211,10 @@ export function useComputerFrameStream(
           const frame = await decodeComputerFrameMessage(bytes);
           if (disposed || source !== socket) continue;
           if (frame.computerSessionId !== computerSessionId || frame.targetId !== targetId) {
-            throw new Error("computer frame belongs to another resource");
+            throw new Error("desktop frame belongs to another resource");
           }
           if (!controllerGeneration || frame.controllerGeneration !== controllerGeneration) {
-            throw new Error("computer frame belongs to a stale controller");
+            throw new Error("desktop frame belongs to a stale controller");
           }
           const key = `${computerSessionId}:${targetId}:${frame.controllerGeneration}:${frame.targetGeneration}`;
           if (latestRef.current.key === key && frame.sequence <= latestRef.current.sequence)
@@ -246,7 +246,7 @@ export function useComputerFrameStream(
           if (disposed || source !== socket) return;
           let frameBytes = bytes;
           if (activeStream?.kind === "relay") {
-            if (bytes.length < 1) throw new Error("computer relay returned an empty message");
+            if (bytes.length < 1) throw new Error("desktop relay returned an empty message");
             const tag = bytes[0];
             const body = bytes.subarray(1);
             if (tag === RELAY_TAG_OPEN_ACK) {
@@ -255,7 +255,7 @@ export function useComputerFrameStream(
                 activeAttachment = null;
                 activeStream = null;
                 attachmentExpiresAt = 0;
-                throw new Error(ack.error?.message ?? "computer stream was rejected by the relay");
+                throw new Error(ack.error?.message ?? "desktop stream was rejected by the relay");
               }
               relayAccepted = true;
               return;
@@ -269,7 +269,7 @@ export function useComputerFrameStream(
               attachmentExpiresAt = 0;
               lastRelaySequence = null;
               relayAccepted = false;
-              fail(new Error("Computer frame source ended."), false);
+              fail(new Error("Desktop frame source ended."), false);
               return;
             }
             if (tag !== RELAY_TAG_FRAME || !relayAccepted) return;
@@ -290,7 +290,7 @@ export function useComputerFrameStream(
 
     const onError = (source: ComputerFrameWebSocket) => {
       if (source !== socket) return;
-      fail(new Error("Computer view lost connection."));
+      fail(new Error("Desktop view lost connection."));
     };
 
     const onClose = (source: ComputerFrameWebSocket) => {
@@ -363,7 +363,7 @@ export function useComputerFrameStream(
           attachment.computerSessionId !== computerSessionId ||
           attachment.targetId !== targetId
         ) {
-          throw new Error("computer attachment does not match the requested resource");
+          throw new Error("desktop attachment does not match the requested resource");
         }
         controllerGeneration = attachment.controllerGeneration;
         activeAttachment = attachment;
@@ -397,7 +397,7 @@ export function useComputerFrameStream(
         connectSocket();
       } catch (cause) {
         if (attachmentAbort.signal.aborted || disposed) return;
-        fail(cause);
+        fail(cause, !isPlacementGenerationLossError(cause));
       }
     };
 
@@ -430,5 +430,10 @@ async function messageBytes(value: unknown): Promise<Uint8Array> {
   if (typeof Blob !== "undefined" && value instanceof Blob) {
     return new Uint8Array(await value.arrayBuffer());
   }
-  throw new Error("computer frame stream returned a non-binary message");
+  throw new Error("desktop frame stream returned a non-binary message");
+}
+
+function isPlacementGenerationLossError(cause: unknown): boolean {
+  const message = cause instanceof Error ? cause.message : String(cause);
+  return /placement instance changed|controller authority changed/i.test(message);
 }

package/src/hooks/use-computer-session.ts

@@ -8,6 +8,7 @@ import type {
   ComputerTarget,
 } from "@opengeni/sdk/interaction";
 import { useCallback, useEffect, useRef, useState } from "react";
+import { isNonRetryableInteractionError } from "../lib/interaction-errors";
 import {
   type EmbeddedComputerInteractionClientOverride,
   useEmbeddedComputerInteraction,
@@ -55,6 +56,7 @@ export function useComputerSession(options: UseComputerSessionOptions): UseCompu
   );
   const visible =
     state.computerSessionId === computerSessionId ? state : emptyState(computerSessionId, enabled);
+  const refreshBlocked = isNonRetryableInteractionError(visible.error);
   const selectedTargetIdRef = useRef<string | null>(visible.selectedTargetId);
   selectedTargetIdRef.current = visible.selectedTargetId;
   const targetsRef = useRef<{
@@ -173,15 +175,15 @@ export function useComputerSession(options: UseComputerSessionOptions): UseCompu
   }, [computerSessionId, enabled, invalidateRefresh, refresh]);
 
   useEffect(() => {
-    if (!enabled || !pageLive || visible.mutating) return;
+    if (!enabled || !pageLive || visible.mutating || refreshBlocked) return;
     const timer = setInterval(() => {
       if (!requestRef.current.controller) void refresh();
     }, pollIntervalMs);
     return () => clearInterval(timer);
-  }, [enabled, pageLive, pollIntervalMs, refresh, visible.mutating]);
+  }, [enabled, pageLive, pollIntervalMs, refresh, refreshBlocked, visible.mutating]);
 
   useEffect(() => {
-    if (!enabled || !computerSessionId || !pageLive) return;
+    if (!enabled || !computerSessionId || !pageLive || refreshBlocked) return;
     let disposed = false;
     const timer = setInterval(() => {
       void client.heartbeatComputerSession(workspaceId, computerSessionId).catch(() => {
@@ -192,7 +194,7 @@ export function useComputerSession(options: UseComputerSessionOptions): UseCompu
       disposed = true;
       clearInterval(timer);
     };
-  }, [client, computerSessionId, enabled, pageLive, refresh, workspaceId]);
+  }, [client, computerSessionId, enabled, pageLive, refresh, refreshBlocked, workspaceId]);
 
   const runMutation = useCallback(
     async <T>(scopeComputerSessionId: string, operation: () => Promise<T>): Promise<T> => {
@@ -234,9 +236,9 @@ export function useComputerSession(options: UseComputerSessionOptions): UseCompu
 
   const selectTarget = useCallback(
     async (targetId: string): Promise<ComputerTarget> => {
-      if (!computerSessionId) throw new Error("No ComputerSession is selected.");
+      if (!computerSessionId) throw new Error("No desktop is selected.");
       const target = targetsRef.current.targets.find((candidate) => candidate.id === targetId);
-      if (!target) throw new Error("The selected computer target is no longer available.");
+      if (!target) throw new Error("The selected desktop target is no longer available.");
       invalidateRefresh();
       selectedTargetIdRef.current = target.id;
       observationRef.current = { computerSessionId, observation: null };
@@ -284,9 +286,9 @@ export function useComputerSession(options: UseComputerSessionOptions): UseCompu
       operationId: string,
       frame: ComputerFrame | null,
     ): Promise<ComputerActionReceipt> => {
-      if (!computerSessionId) throw new Error("No ComputerSession is selected.");
+      if (!computerSessionId) throw new Error("No desktop is selected.");
       if (frame && frame.computerSessionId !== computerSessionId) {
-        throw new Error("The displayed computer frame belongs to another ComputerSession.");
+        throw new Error("The displayed desktop frame belongs to another desktop session.");
       }
       const currentObservation =
         observationRef.current.computerSessionId === computerSessionId
@@ -302,18 +304,18 @@ export function useComputerSession(options: UseComputerSessionOptions): UseCompu
           (currentObservation?.target.id === frame.targetId ? currentObservation.target : null))
         : null;
       const target = frameTarget ?? focusTarget ?? currentObservation?.target ?? null;
-      if (!target) throw new Error("The computer target is not ready for input.");
+      if (!target) throw new Error("The desktop target is not ready for input.");
       if (frame && frame.targetId !== selectedTargetIdRef.current) {
-        throw new Error("The displayed computer frame is no longer selected.");
+        throw new Error("The displayed desktop frame is no longer selected.");
       }
       if (action.type === "pointer") {
         const expectedFrameId = frame?.frameId ?? currentObservation?.frameId ?? null;
         if (!expectedFrameId || action.frameId !== expectedFrameId) {
-          throw new Error("Pointer input must reference the exact displayed computer frame.");
+          throw new Error("Pointer input must reference the exact displayed desktop frame.");
         }
       }
       if (action.type === "semantic" && !currentObservation) {
-        throw new Error("The computer accessibility tree is not ready for input.");
+        throw new Error("The desktop accessibility tree is not ready for input.");
       }
 
       return await runMutation(computerSessionId, async () => {
@@ -367,7 +369,7 @@ export function useComputerSession(options: UseComputerSessionOptions): UseCompu
   );
 
   const readClipboard = useCallback(async (): Promise<ComputerClipboard> => {
-    if (!computerSessionId) throw new Error("No ComputerSession is selected.");
+    if (!computerSessionId) throw new Error("No desktop is selected.");
     return await client.readComputerClipboard(workspaceId, computerSessionId);
   }, [client, computerSessionId, workspaceId]);
 
@@ -432,9 +434,9 @@ function chooseTarget(
   return (
     targets.find((target) => target.focused && target.kind === "window") ??
     targets.find((target) => target.kind === "window") ??
+    targets.find((target) => target.kind === "screen") ??
     targets.find((target) => target.focused && target.kind === "app") ??
     targets.find((target) => target.kind === "app") ??
-    targets.find((target) => target.kind === "screen") ??
     targets[0] ??
     null
   );

package/src/hooks/use-computer-sessions.ts

@@ -74,6 +74,7 @@ export function useComputerSessions(
       requestRef.current = { id, controller };
       setState((current) => ({
         ...(current.workspaceId === workspaceId ? current : emptyState(workspaceId, true)),
+        active: true,
         loading: foreground,
         refreshing: !foreground,
         error: foreground || current.workspaceId !== workspaceId ? null : current.error,
@@ -85,6 +86,7 @@ export function useComputerSessions(
         if (!mountedRef.current || requestRef.current.id !== id) return;
         setState({
           workspaceId,
+          active: true,
           revision: response.revision,
           sessions: sortComputerSessions(response.sessions),
           loading: false,
@@ -187,7 +189,10 @@ export function useComputerSessions(
     revision: visible.revision,
     sessions: visible.sessions,
     relevantSessions,
-    loading: visible.loading,
+    // A disabled registry is deliberately empty. When its surface becomes
+    // visible again, expose that transition as loading in the same render so
+    // consumers cannot mistake the stale empty snapshot for a completed list.
+    loading: enabled ? !visible.active || visible.loading : false,
     refreshing: visible.refreshing,
     error: visible.error,
     refresh,
@@ -198,6 +203,7 @@ export function useComputerSessions(
 
 type ComputerRegistryState = {
   workspaceId: string;
+  active: boolean;
   revision: number;
   sessions: ComputerSession[];
   loading: boolean;
@@ -208,6 +214,7 @@ type ComputerRegistryState = {
 function emptyState(workspaceId: string, loading: boolean): ComputerRegistryState {
   return {
     workspaceId,
+    active: loading,
     revision: 0,
     sessions: [],
     loading,

package/src/hooks/use-last-started-turn-policy.ts

@@ -33,7 +33,7 @@ function policyFromTurn(turn: SessionTurn | null | undefined): LastStartedTurnPo
   return {
     model: turn.model,
     reasoningEffort: turn.reasoningEffort,
-    latencyMode: turn.latencyMode ?? "standard",
+    latencyMode: turn.latencyMode,
     turnId: turn.id,
   };
 }

package/src/hooks/use-machine-chip.ts

@@ -4,13 +4,13 @@ import type { SessionCapabilitiesState } from "./use-session-capabilities";
 import { sandboxAcceptsLiveIo } from "../lib/sandbox-liveness";
 import { connectionStatusForState } from "../types/machines";
 
-/** The one truthful machine indicator. Honest staleness beats
- *  fake liveness: a cold/asleep box reads "offline — as of <time>", never "live". */
+/** The one truthful machine indicator. Managed cold compute is sleeping; a
+ *  Connected Machine that is genuinely unreachable remains offline. */
 export type MachineChipState = "live" | "waking" | "offline";
 
 export type MachineChip = {
   state: MachineChipState;
-  /** A ready-to-render label ("Live" / "Waking…" / "Offline — as of 3m ago"). */
+  /** A ready-to-render label ("Live" / "Waking…" / "Sleeping · saved 3m ago"). */
   label: string;
   /** The capture time backing an offline/stale label (ISO), or null. M4 may
    *  reformat this; `label` already embeds a relative form. */
@@ -64,7 +64,8 @@ export function formatAsOf(capturedAt: string, now: number): string {
 export function deriveMachineChip(input: DeriveMachineChipInput): MachineChip {
   const now = input.now ?? Date.now();
   const asOf = input.capturedAt ?? null;
-  const offlineLabel = asOf ? `Offline — as of ${formatAsOf(asOf, now)}` : "Offline";
+  const managedRestingLabel = asOf ? `Sleeping · saved ${formatAsOf(asOf, now)}` : "Sleeping";
+  const offlineLabel = "Offline";
 
   // A connected machine has no Modal group lease, so capability negotiation
   // legitimately reports `cold` until a stream holder is minted. Its fleet
@@ -86,6 +87,16 @@ export function deriveMachineChip(input: DeriveMachineChipInput): MachineChip {
   const selfhostedOffline =
     input.activeIsSelfhosted === true && input.activeMachineState === "offline";
 
+  // Capability negotiation has definitively failed. A retained warm intent
+  // must not turn that error into the optimistic Waking state.
+  if (input.capabilitiesState === "error") {
+    return {
+      state: "offline",
+      label: input.activeIsSelfhosted === true ? offlineLabel : managedRestingLabel,
+      asOf,
+    };
+  }
+
   // 2. Actively coming up: negotiation in flight, an edit/terminal is warming, or
   //    the active machine is (re)connecting. Never when self-hosted is hard-offline.
   const machineWarming =
@@ -97,8 +108,14 @@ export function deriveMachineChip(input: DeriveMachineChipInput): MachineChip {
     return { state: "waking", label: "Waking…", asOf };
   }
 
-  // 3. Cold / asleep / offline / error → honest stale label.
-  return { state: "offline", label: offlineLabel, asOf };
+  // 3. Managed cold compute is sleeping with saved-workspace freshness. A
+  // Connected Machine is only described as Offline when its reachability is
+  // genuinely unavailable; capture time is not a heartbeat.
+  return {
+    state: "offline",
+    label: input.activeIsSelfhosted === true ? offlineLabel : managedRestingLabel,
+    asOf,
+  };
 }
 
 export type UseMachineChipOptions = DeriveMachineChipInput;

package/src/hooks/use-machines.ts

@@ -2,12 +2,34 @@ import { useCallback, useRef, useState } from "react";
 import type {
   RemoveEnrollmentRequest,
   RemoveEnrollmentResponse,
+  MachineOperationPolicy,
   SwapActiveSandboxResponse,
+  UpdateMachineOperationPolicyRequest,
+  UpdateMachineAgentResponse,
 } from "@opengeni/sdk";
 import { useOpenGeni, type ClientOverride } from "../provider";
-import { useMutationRunner, usePolledValue } from "./internal";
+import { useMutationRunner } from "./internal";
+import { EMPTY_MACHINES, useSharedMachinesList } from "./shared-machines-list";
 import type { MachinesResponse, MachineView, MetricSample } from "../types/machines";
 
+/** Dashboard list: cheap heartbeat read, keep the pill reasonably fresh. */
+export const MACHINES_DASHBOARD_POLL_MS = 10_000;
+/** Session surfaces share one poll for the same workspace+session. */
+export const MACHINES_SESSION_POLL_MS = 15_000;
+/** Composer polls after the first load shows a machine, or to retry a real error. */
+export const MACHINES_COMPOSER_POLL_MS = 30_000;
+
+const machinesClientIds = new WeakMap<object, number>();
+let nextMachinesClientId = 1;
+
+function machinesClientId(client: object): number {
+  const existing = machinesClientIds.get(client);
+  if (existing !== undefined) return existing;
+  const id = nextMachinesClientId++;
+  machinesClientIds.set(client, id);
+  return id;
+}
+
 /**
  * The slice of the SDK client the Machines surface needs. The method NAMES +
  * SIGNATURES match M10's `OpenGeniClient` (`listMachines`, `machineMetricsSeries`)
@@ -42,6 +64,17 @@ export type MachinesClientLike = {
     enrollmentId: string,
     request?: RemoveEnrollmentRequest,
   ) => Promise<RemoveEnrollmentResponse>;
+  /** POST .../machines/:enrollmentId/update — signed, generation-fenced update. */
+  updateMachineAgent?: (
+    workspaceId: string,
+    enrollmentId: string,
+  ) => Promise<UpdateMachineAgentResponse>;
+  /** PATCH .../machines/:enrollmentId/operation-policy — revision-fenced policy. */
+  updateMachineOperationPolicy?: (
+    workspaceId: string,
+    enrollmentId: string,
+    request: UpdateMachineOperationPolicyRequest,
+  ) => Promise<MachineOperationPolicy>;
   /**
    * POST .../sessions/:sessionId/active-sandbox — swap the session's active
    * sandbox to a machine. The default swap path; the real SDK client provides it.
@@ -87,6 +120,17 @@ export type UseMachinesResult = {
   ) => Promise<RemoveEnrollmentResponse | null>;
   canRemove: boolean;
   removingEnrollmentId: string | null;
+  /** Start/retry the signed self-update for one Connected Machine. */
+  updateAgent: (enrollmentId: string) => Promise<UpdateMachineAgentResponse | null>;
+  canUpdateAgent: boolean;
+  updatingEnrollmentId: string | null;
+  /** Update the optional per-enrollment command memory policy. */
+  updateOperationPolicy: (
+    enrollmentId: string,
+    request: UpdateMachineOperationPolicyRequest,
+  ) => Promise<MachineOperationPolicy | null>;
+  canUpdateOperationPolicy: boolean;
+  updatingOperationPolicyEnrollmentId: string | null;
   /** Whether the host wired an attach/swap path (drives the card affordance). */
   canAttach: boolean;
   /** Fetch a downsampled metric series for one enrolled machine. */
@@ -101,8 +145,6 @@ export type UseMachinesResult = {
   clearMutationError: () => void;
 };
 
-const EMPTY: MachinesResponse = { activeSandboxId: null, activeEpoch: 0, machines: [] };
-
 function swapFailureMessage(result: SwapActiveSandboxResponse): string {
   if (result.reason?.trim()) return result.reason;
   switch (result.code) {
@@ -134,7 +176,7 @@ export function useMachines(options: UseMachinesOptions = {}): UseMachinesResult
   const machinesClient = (options.machinesClient ??
     (client as unknown as MachinesClientLike)) satisfies MachinesClientLike;
   const sessionId = options.sessionId;
-  const identityKey = `${workspaceId}\u0000${sessionId ?? ""}`;
+  const identityKey = `${workspaceId}\u0000${sessionId ?? ""}\u0000${machinesClientId(machinesClient)}`;
   const identityRef = useRef(identityKey);
   identityRef.current = identityKey;
 
@@ -153,7 +195,7 @@ export function useMachines(options: UseMachinesOptions = {}): UseMachinesResult
     loading,
     error,
     refresh,
-  } = usePolledValue(load, {
+  } = useSharedMachinesList(identityKey, load, {
     pollIntervalMs: options.pollIntervalMs,
     enabled: options.enabled,
   });
@@ -170,8 +212,20 @@ export function useMachines(options: UseMachinesOptions = {}): UseMachinesResult
   }>(() => ({ identity: identityKey, enrollmentId: null }));
   const removingEnrollmentId =
     removeState.identity === identityKey ? removeState.enrollmentId : null;
+  const [updateState, setUpdateState] = useState<{
+    identity: string;
+    enrollmentId: string | null;
+  }>(() => ({ identity: identityKey, enrollmentId: null }));
+  const updatingEnrollmentId =
+    updateState.identity === identityKey ? updateState.enrollmentId : null;
+  const [operationPolicyState, setOperationPolicyState] = useState<{
+    identity: string;
+    enrollmentId: string | null;
+  }>(() => ({ identity: identityKey, enrollmentId: null }));
+  const updatingOperationPolicyEnrollmentId =
+    operationPolicyState.identity === identityKey ? operationPolicyState.enrollmentId : null;
 
-  const data = loadedData ?? EMPTY;
+  const data = loadedData ?? EMPTY_MACHINES;
   // The swap is session-scoped: a host adapter (`attachMachine`) wins; otherwise
   // the default `swapActiveSandbox` path is wired whenever a sessionId is in
   // scope. Either way attach needs a sessionId to point at.
@@ -180,6 +234,9 @@ export function useMachines(options: UseMachinesOptions = {}): UseMachinesResult
     (typeof machinesClient.attachMachine === "function" ||
       typeof machinesClient.swapActiveSandbox === "function");
   const canRemove = typeof machinesClient.removeEnrollment === "function";
+  const canUpdateAgent = typeof machinesClient.updateMachineAgent === "function";
+  const canUpdateOperationPolicy =
+    typeof machinesClient.updateMachineOperationPolicy === "function";
 
   const attach = useCallback(
     async (sandboxId: string): Promise<boolean> => {
@@ -246,6 +303,41 @@ export function useMachines(options: UseMachinesOptions = {}): UseMachinesResult
     [machinesClient, workspaceId, identityKey, run, refresh],
   );
 
+  const updateAgent = useCallback(
+    async (enrollmentId: string): Promise<UpdateMachineAgentResponse | null> => {
+      if (!machinesClient.updateMachineAgent) return null;
+      const ownedIdentity = identityKey;
+      setUpdateState({ identity: ownedIdentity, enrollmentId });
+      const result = await run(() => machinesClient.updateMachineAgent!(workspaceId, enrollmentId));
+      if (identityRef.current === ownedIdentity) {
+        setUpdateState({ identity: ownedIdentity, enrollmentId: null });
+        await refresh();
+      }
+      return result;
+    },
+    [machinesClient, workspaceId, identityKey, run, refresh],
+  );
+
+  const updateOperationPolicy = useCallback(
+    async (
+      enrollmentId: string,
+      request: UpdateMachineOperationPolicyRequest,
+    ): Promise<MachineOperationPolicy | null> => {
+      if (!machinesClient.updateMachineOperationPolicy) return null;
+      const ownedIdentity = identityKey;
+      setOperationPolicyState({ identity: ownedIdentity, enrollmentId });
+      const result = await run(() =>
+        machinesClient.updateMachineOperationPolicy!(workspaceId, enrollmentId, request),
+      );
+      if (identityRef.current === ownedIdentity) {
+        setOperationPolicyState({ identity: ownedIdentity, enrollmentId: null });
+        if (result) await refresh();
+      }
+      return result;
+    },
+    [machinesClient, workspaceId, identityKey, run, refresh],
+  );
+
   return {
     machines: data.machines,
     activeSandboxId: data.activeSandboxId,
@@ -261,6 +353,12 @@ export function useMachines(options: UseMachinesOptions = {}): UseMachinesResult
     remove,
     canRemove,
     removingEnrollmentId,
+    updateAgent,
+    canUpdateAgent,
+    updatingEnrollmentId,
+    updateOperationPolicy,
+    canUpdateOperationPolicy,
+    updatingOperationPolicyEnrollmentId,
     mutationError,
     clearMutationError,
   };