@opengeni/react 0.15.0 → 0.20.0

package/src/hooks/use-human-input.ts

@@ -0,0 +1,131 @@
+import type {
+  SessionEvent,
+  SessionHumanInputRequest,
+  SubmitHumanInputResponseRequest,
+} from "@opengeni/sdk";
+import { useCallback, useEffect, useRef, useState } from "react";
+import {
+  useEmbeddedHumanInputSession,
+  type EmbeddedHumanInputClientOverride,
+} from "../session-context";
+import {
+  useDebouncedCallback,
+  useMutationRunner,
+  usePolledValue,
+  useSessionEventTrigger,
+  type SessionEventFeedOptions,
+} from "./internal";
+
+/** Events that can create, settle, or invalidate an actionable request. */
+export function isHumanInputEvent(event: Pick<SessionEvent, "type">): boolean {
+  return (
+    event.type === "session.humanInput.requested" ||
+    event.type === "user.humanInputResponse" ||
+    event.type === "turn.completed" ||
+    event.type === "turn.failed" ||
+    event.type === "turn.cancelled"
+  );
+}
+
+export type UseHumanInputRequestsOptions = EmbeddedHumanInputClientOverride &
+  SessionEventFeedOptions & {
+    /** Optional safety-net polling. Durable events drive refresh by default. */
+    pollIntervalMs?: number | undefined;
+  };
+
+export type UseHumanInputRequestsResult = {
+  requests: SessionHumanInputRequest[];
+  loading: boolean;
+  error: Error | null;
+  refresh: () => Promise<void>;
+  respond: (
+    requestId: string,
+    response: SubmitHumanInputResponseRequest,
+  ) => Promise<SessionEvent | null>;
+  respondingRequestId: string | null;
+  mutationError: Error | null;
+  clearMutationError: () => void;
+};
+
+/**
+ * Authoritative structured-human-input hook. The server's pending-request
+ * table is the read model; events only trigger reconciliation. This lets an
+ * embedded host use the same primitive with a shared event feed or its own SDK
+ * proxy without rebuilding request lifecycle logic.
+ */
+export function useHumanInputRequests(
+  sessionId: string | null | undefined,
+  options: UseHumanInputRequestsOptions = {},
+): UseHumanInputRequestsResult {
+  const { client, workspaceId, registerSessionReconciler } = useEmbeddedHumanInputSession(options);
+  const enabled = (options.enabled ?? true) && Boolean(sessionId);
+  const load = useCallback(
+    async (): Promise<SessionHumanInputRequest[]> =>
+      sessionId
+        ? await client.listHumanInputRequests(workspaceId, sessionId, { status: "pending" })
+        : [],
+    [client, sessionId, workspaceId],
+  );
+  const state = usePolledValue(load, {
+    enabled,
+    pollIntervalMs: options.pollIntervalMs,
+  });
+  const mutation = useMutationRunner(`${workspaceId}\u0000${sessionId ?? ""}`);
+  const [respondingRequestId, setRespondingRequestId] = useState<string | null>(null);
+  const respondingRequestRef = useRef<string | null>(null);
+
+  useEffect(() => {
+    respondingRequestRef.current = null;
+    setRespondingRequestId(null);
+  }, [sessionId, workspaceId]);
+  useEffect(() => {
+    if (!sessionId || !enabled) return;
+    return registerSessionReconciler(sessionId, "human-input", state.refresh);
+  }, [enabled, registerSessionReconciler, sessionId, state.refresh]);
+
+  const scheduleRefresh = useDebouncedCallback(() => void state.refresh());
+  useSessionEventTrigger(client, workspaceId, sessionId, isHumanInputEvent, scheduleRefresh, {
+    enabled,
+    ...(options.events !== undefined ? { events: options.events } : {}),
+  });
+
+  const respond = useCallback(
+    async (
+      requestId: string,
+      response: SubmitHumanInputResponseRequest,
+    ): Promise<SessionEvent | null> => {
+      if (!sessionId || respondingRequestRef.current !== null) return null;
+      respondingRequestRef.current = requestId;
+      setRespondingRequestId(requestId);
+      try {
+        const event = await mutation.run(() =>
+          client.submitHumanInputResponse(workspaceId, sessionId, requestId, response, {
+            clientEventId: globalThis.crypto.randomUUID(),
+          }),
+        );
+        if (event) await state.refresh();
+        return event;
+      } finally {
+        if (respondingRequestRef.current === requestId) {
+          respondingRequestRef.current = null;
+          setRespondingRequestId(null);
+        }
+      }
+    },
+    [client, mutation, sessionId, state, workspaceId],
+  );
+
+  return {
+    requests: [...(state.data ?? [])].sort(
+      (left, right) =>
+        left.createdAt.localeCompare(right.createdAt) || left.id.localeCompare(right.id),
+    ),
+    loading: state.loading,
+    error: state.error,
+    refresh: state.refresh,
+    respond,
+    respondingRequestId,
+    mutationError: mutation.mutationError,
+    clearMutationError: mutation.clearMutationError,
+  };
+}

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

@@ -2,7 +2,7 @@ import { useMemo } from "react";
 import type { MachineState } from "@opengeni/sdk";
 import type { SessionCapabilitiesState } from "./use-session-capabilities";
 
-/** The one truthful machine indicator (dossier §3 #10). Honest staleness beats
+/** The one truthful machine indicator. Honest staleness beats
  *  fake liveness: a cold/asleep box reads "offline — as of <time>", never "live". */
 export type MachineChipState = "live" | "waking" | "offline";
 
@@ -70,7 +70,7 @@ export function deriveMachineChip(input: DeriveMachineChipInput): MachineChip {
   }
 
   // A self-hosted machine that reports offline cannot be woken remotely — honest
-  // "offline", never "waking" (dossier §3 #5 / #10).
+  // "offline", never "waking".
   const selfhostedOffline =
     input.activeIsSelfhosted === true && input.activeMachineState === "offline";
 

package/src/hooks/use-machines.ts

@@ -1,4 +1,4 @@
-import { useCallback, useState } from "react";
+import { useCallback, useRef, useState } from "react";
 import { useOpenGeni, type ClientOverride } from "../provider";
 import { useMutationRunner, usePolledValue } from "./internal";
 import type { MachinesResponse, MachineView, MetricSample } from "../types/machines";
@@ -23,7 +23,7 @@ export type MachinesClientLike = {
   /** GET /v1/workspaces/:ws/machines — the dashboard list + active pointer. */
   listMachines: (
     workspaceId: string,
-    options?: { sessionId?: string },
+    options?: { sessionId?: string; signal?: AbortSignal },
   ) => Promise<MachinesResponse>;
   /** GET .../machines/:enrollmentId/metrics/series — the downsampled history. */
   machineMetricsSeries?: (
@@ -98,10 +98,19 @@ 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 identityRef = useRef(identityKey);
+  identityRef.current = identityKey;
 
-  const load = useCallback(async () => {
-    return await machinesClient.listMachines(workspaceId, sessionId ? { sessionId } : undefined);
-  }, [machinesClient, workspaceId, sessionId]);
+  const load = useCallback(
+    async (signal?: AbortSignal) => {
+      return await machinesClient.listMachines(workspaceId, {
+        ...(sessionId ? { sessionId } : {}),
+        ...(signal ? { signal } : {}),
+      });
+    },
+    [machinesClient, workspaceId, sessionId],
+  );
 
   const {
     data: loadedData,
@@ -112,9 +121,13 @@ export function useMachines(options: UseMachinesOptions = {}): UseMachinesResult
     pollIntervalMs: options.pollIntervalMs,
     enabled: options.enabled,
   });
-  const { run, mutating, mutationError, clearMutationError } = useMutationRunner();
+  const { run, mutating, mutationError, clearMutationError } = useMutationRunner(identityKey);
   // The sandbox id of the in-flight attach (drives the per-card spinner).
-  const [attachingSandboxId, setAttachingSandboxId] = useState<string | null>(null);
+  const [attachState, setAttachState] = useState<{
+    identity: string;
+    sandboxId: string | null;
+  }>(() => ({ identity: identityKey, sandboxId: null }));
+  const attachingSandboxId = attachState.identity === identityKey ? attachState.sandboxId : null;
 
   const data = loadedData ?? EMPTY;
   // The swap is session-scoped: a host adapter (`attachMachine`) wins; otherwise
@@ -134,16 +147,19 @@ export function useMachines(options: UseMachinesOptions = {}): UseMachinesResult
           ? () => machinesClient.swapActiveSandbox!(workspaceId, sessionId, { target: sandboxId })
           : null;
       if (!runSwap) return false;
-      setAttachingSandboxId(sandboxId);
+      const ownedIdentity = identityKey;
+      setAttachState({ identity: ownedIdentity, sandboxId });
       const result = await run(async () => {
         await runSwap();
         return true;
       });
-      setAttachingSandboxId(null);
-      if (result) await refresh();
+      if (identityRef.current === ownedIdentity) {
+        setAttachState({ identity: ownedIdentity, sandboxId: null });
+        if (result) await refresh();
+      }
       return result === true;
     },
-    [machinesClient, workspaceId, sessionId, run, refresh],
+    [machinesClient, workspaceId, sessionId, identityKey, run, refresh],
   );
 
   const fetchSeries = useCallback(