@opengeni/react 0.13.0 → 0.20.0

package/src/hooks/use-workspace-edit.ts

@@ -2,8 +2,8 @@ import { useCallback, useEffect, useRef, useState } from "react";
 import { useOpenGeni, type ClientOverride } from "../provider";
 
 /**
- * The wake-on-edit state machine (dossier §3 #5 / §10.4 / §12-C). M3 OWNS this
- * logic; M5 renders it. States are explicit and exhaustive:
+ * The wake-on-edit state machine. This hook owns the logic and the UI renders
+ * its result. States are explicit and exhaustive:
  *
  *   viewing-cold      — cold snapshot open, no local edits (editable, cloud).
  *   buffering         — local edits buffered; the box is not warm and no warm is
@@ -80,11 +80,11 @@ function isLive(liveness: string | undefined): boolean {
  * Cold-editing without a spinner: the editor opens instantly from the capture,
  * the first keystroke buffers locally AND signals the host to warm the box, and on
  * warm the buffer flushes IF the live file still matches the captured base — else a
- * non-blocking conflict is surfaced and nothing is overwritten (dossier §12-C2).
+ * non-blocking conflict is surfaced and nothing is overwritten.
  *
  * The base guard compares the live content at flush time against `baseContent`
  * (the exact bytes the editor loaded). This is equivalent to the sha256 compare
- * the dossier describes — M1 leaves `baseHash` null, so the loaded content IS the
+ * the design specifies — M1 leaves `baseHash` null, so the loaded content IS the
  * authoritative base — and avoids async Web Crypto in the render path.
  */
 export function useWorkspaceEdit(
@@ -96,31 +96,48 @@ export function useWorkspaceEdit(
   const baseContent = options.baseContent ?? null;
   const live = isLive(options.liveness);
   const offline = options.offline === true;
+  const identityKey = `${workspaceId}\u0000${sessionId ?? ""}\u0000${path ?? ""}`;
 
   const [buffer, setBuffer] = useState<string | null>(null);
   const [wantsWarm, setWantsWarm] = useState(false);
   const [flush, setFlush] = useState<"idle" | "flushing" | "flushed" | "conflict">("idle");
   const [conflict, setConflict] = useState<WorkspaceEditConflict | null>(null);
   const [error, setError] = useState<Error | null>(null);
+  const [stateIdentity, setStateIdentity] = useState(identityKey);
 
   const onWarmRequested = options.onWarmRequested;
   const bufferRef = useRef<string | null>(null);
   bufferRef.current = buffer;
   // Guards a single in-flight flush against re-entry (liveness can re-render).
   const flushingRef = useRef(false);
+  const identityGenerationRef = useRef(0);
+  const flushAttemptRef = useRef(0);
+  const readAbortRef = useRef<AbortController | null>(null);
 
   // Reset the machine when the edited file (or session) changes.
   useEffect(() => {
+    identityGenerationRef.current += 1;
+    flushAttemptRef.current += 1;
+    readAbortRef.current?.abort();
+    readAbortRef.current = null;
+    setStateIdentity(identityKey);
     setBuffer(null);
     setWantsWarm(false);
     setFlush("idle");
     setConflict(null);
     setError(null);
     flushingRef.current = false;
-  }, [sessionId, path]);
+    return () => {
+      identityGenerationRef.current += 1;
+      flushAttemptRef.current += 1;
+      readAbortRef.current?.abort();
+      readAbortRef.current = null;
+    };
+  }, [identityKey]);
 
   const edit = useCallback(
     (content: string) => {
+      if (stateIdentity !== identityKey) return;
       if (offline) return; // read-only — no buffering, no wake.
       setBuffer((prev) => (prev === content ? prev : content));
       // Any new edit invalidates a prior flushed/conflict resolution.
@@ -134,15 +151,18 @@ export function useWorkspaceEdit(
         });
       }
     },
-    [offline, live, onWarmRequested],
+    [offline, live, onWarmRequested, stateIdentity, identityKey],
   );
 
   const doFlush = useCallback(
     async (force: boolean) => {
+      if (stateIdentity !== identityKey) return;
       if (!sessionId || !path) return;
       const content = bufferRef.current;
       if (content === null) return;
       if (flushingRef.current) return;
+      const identityGeneration = identityGenerationRef.current;
+      const flushAttempt = (flushAttemptRef.current += 1);
       flushingRef.current = true;
       setFlush("flushing");
       setError(null);
@@ -151,7 +171,17 @@ export function useWorkspaceEdit(
           // Base guard: re-read the live file and compare to the captured base. A
           // divergence means the box changed under us — surface a conflict, write
           // NOTHING (C2).
-          const liveRead = await client.fsRead(workspaceId, sessionId, { path });
+          const readAbort = new AbortController();
+          readAbortRef.current?.abort();
+          readAbortRef.current = readAbort;
+          const liveRead = await client.fsRead(
+            workspaceId,
+            sessionId,
+            { path },
+            { signal: readAbort.signal },
+          );
+          if (readAbortRef.current === readAbort) readAbortRef.current = null;
+          if (identityGenerationRef.current !== identityGeneration) return;
           const liveContent = liveRead.content;
           if (baseContent !== null && liveContent !== baseContent) {
             setConflict({ path, base: baseContent, live: liveContent });
@@ -160,18 +190,23 @@ export function useWorkspaceEdit(
           }
         }
         await client.fsWrite(workspaceId, sessionId, { path, content, overwrite: true });
+        if (identityGenerationRef.current !== identityGeneration) return;
         setConflict(null);
         setFlush("flushed");
         setWantsWarm(false);
       } catch (cause) {
+        if (identityGenerationRef.current !== identityGeneration) return;
         setError(cause instanceof Error ? cause : new Error(String(cause)));
         // Leave the buffer intact so the user can retry; fall back to buffering.
         setFlush("idle");
       } finally {
-        flushingRef.current = false;
+        if (flushAttemptRef.current === flushAttempt) {
+          flushingRef.current = false;
+          readAbortRef.current = null;
+        }
       }
     },
-    [client, workspaceId, sessionId, path, baseContent],
+    [client, workspaceId, sessionId, path, baseContent, stateIdentity, identityKey],
   );
 
   // Auto-flush once the box is warm and a buffer is pending (the wake completed).
@@ -217,15 +252,16 @@ export function useWorkspaceEdit(
     state = "buffering";
   }
 
+  const identityMatches = stateIdentity === identityKey;
   return {
-    state,
+    state: identityMatches ? state : offline ? "readonly-offline" : "viewing-cold",
     readOnly: offline,
-    buffer,
-    wantsWarm,
+    buffer: identityMatches ? buffer : null,
+    wantsWarm: identityMatches && wantsWarm,
     edit,
-    conflict,
+    conflict: identityMatches ? conflict : null,
     overwrite,
     discard,
-    error,
+    error: identityMatches ? error : null,
   };
 }

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

@@ -21,6 +21,8 @@ export type UseWorkspaceSessionsResult = {
   sessions: Session[];
   /** The complete personal pinned section, also present in `sessions`. */
   pinned: Session[];
+  /** True when the server omitted older pins from its bounded pinned section. */
+  pinnedTruncated: boolean;
   nextCursor: string | null;
   loading: boolean;
   error: Error | null;
@@ -65,6 +67,7 @@ export function useWorkspaceSessions(
     // itself continues to paginate only `ordinary` rows via nextCursor.
     sessions: [...pinned, ...ordinary],
     pinned,
+    pinnedTruncated: page?.pinnedTruncated ?? false,
     nextCursor: page?.nextCursor ?? null,
     loading: state.loading,
     error: state.error,

package/src/human-input.ts

@@ -0,0 +1,72 @@
+import type { HumanInputQuestion, SessionEvent } from "@opengeni/sdk";
+
+/** Minimal actionable request shape available from the durable event log. */
+export type PendingHumanInputRequest = {
+  id: string;
+  turnId: string | null;
+  questions: HumanInputQuestion[];
+  allowSkip: boolean;
+  expiresAt: string | null;
+};
+
+/** Parse one generic `session.humanInput.requested` event defensively. */
+export function humanInputRequestFromEvent(
+  event: Pick<SessionEvent, "type" | "payload" | "turnId">,
+): PendingHumanInputRequest | null {
+  if (event.type !== "session.humanInput.requested" || !isRecord(event.payload)) return null;
+  const request = event.payload.request;
+  if (!isRecord(request) || typeof request.id !== "string" || !Array.isArray(request.questions)) {
+    return null;
+  }
+  return {
+    id: request.id,
+    turnId: event.turnId ?? null,
+    questions: request.questions as HumanInputQuestion[],
+    allowSkip: request.allowSkip === true,
+    expiresAt: typeof request.expiresAt === "string" ? request.expiresAt : null,
+  };
+}
+
+/**
+ * Fold a durable event log into the structured requests that are actionable
+ * now. Responses remove one request; a terminal owning turn clears any
+ * unresolved requests that died with it. Replaying history cannot resurrect a
+ * previously answered card.
+ */
+export function projectPendingHumanInputRequests(
+  events: SessionEvent[],
+): PendingHumanInputRequest[] {
+  const pending = new Map<string, PendingHumanInputRequest>();
+  for (const event of events) {
+    const requested = humanInputRequestFromEvent(event);
+    if (requested) {
+      pending.set(requested.id, requested);
+      continue;
+    }
+    if (event.type === "user.humanInputResponse" && isRecord(event.payload)) {
+      if (typeof event.payload.requestId === "string") pending.delete(event.payload.requestId);
+      continue;
+    }
+    if (
+      event.type === "turn.completed" ||
+      event.type === "turn.failed" ||
+      event.type === "turn.cancelled"
+    ) {
+      for (const [id, request] of pending) {
+        if (
+          request.turnId === null ||
+          event.turnId === null ||
+          event.turnId === undefined ||
+          request.turnId === event.turnId
+        ) {
+          pending.delete(id);
+        }
+      }
+    }
+  }
+  return [...pending.values()];
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}

package/src/index.ts

@@ -1,18 +1,36 @@
+// oxlint-disable-next-line typescript/triple-slash-reference -- package consumers must load the ambient type for this optional untyped peer without emitting a runtime import.
+/// <reference path="./types/external.d.ts" />
+
 // @opengeni/react — hooks + styled components on @opengeni/sdk.
 //
 // Import the styles once in your Tailwind entry CSS:
 //   @import "@opengeni/react/styles.css";
 //   @source "../node_modules/@opengeni/react/src";
 
-export type { SessionClientLike } from "./client";
-export { OpenGeniProvider, useOpenGeni, useOpenGeniClient } from "./provider";
-export type { ClientOverride, OpenGeniContextValue, OpenGeniProviderProps } from "./provider";
+export type {
+  EmbeddedHumanInputSessionClientLike,
+  EmbeddedSessionClientLike,
+  SessionClientLike,
+} from "./client";
+export { OpenGeniProvider } from "./provider";
+export type { OpenGeniProviderProps } from "./provider";
+export { useOpenGeni, useOpenGeniClient } from "./session-context";
+export type { ClientOverride, OpenGeniContextValue } from "./session-context";
 
 // Hooks
 export { useSession, isTitleEvent } from "./hooks/use-session";
 export type { UseSessionOptions, UseSessionResult } from "./hooks/use-session";
-export { useSessionEvents } from "./hooks/use-session-events";
+export {
+  SESSION_EVENT_BROWSER_MAX_BYTES,
+  SESSION_EVENT_BROWSER_MAX_COUNT,
+  SESSION_EVENT_BROWSER_PENDING_MAX_BYTES,
+  SESSION_EVENT_BROWSER_PENDING_MAX_COUNT,
+  SESSION_EVENT_BROWSER_SINGLE_EVENT_MAX_BYTES,
+  boundBrowserSessionEventWindow,
+  useSessionEvents,
+} from "./hooks/use-session-events";
 export type {
+  BrowserSessionEventWindow,
   SessionEventsConnectionState,
   UseSessionEventsOptions,
   UseSessionEventsResult,
@@ -20,15 +38,24 @@ export type {
 export {
   useComposer,
   composeSendInput,
+  shouldSteerOnKey,
   shouldSubmitOnKey,
   FILE_ONLY_MESSAGE_TEXT,
 } from "./hooks/use-composer";
+export type { ComposerSendExtras, ComposerState, UseComposerOptions } from "./hooks/use-composer";
+export {
+  INITIAL_TRANSCRIPTION_CONTROL_STATE,
+  appendFinalTranscript,
+  transitionTranscriptionControl,
+  useTranscription,
+} from "./hooks/use-transcription";
 export type {
-  ComposerMode,
-  ComposerSendExtras,
-  ComposerState,
-  UseComposerOptions,
-} from "./hooks/use-composer";
+  TranscriptionControlAction,
+  TranscriptionControlState,
+  TranscriptionControlTransition,
+  UseTranscriptionOptions,
+  UseTranscriptionResult,
+} from "./hooks/use-transcription";
 export { useFileAttachments } from "./hooks/use-file-attachments";
 export type {
   FileAttachment,
@@ -36,7 +63,14 @@ export type {
   UseFileAttachmentsResult,
 } from "./hooks/use-file-attachments";
 export { useTurnQueue, isTurnQueueEvent } from "./hooks/use-turn-queue";
-export type { UseTurnQueueOptions, UseTurnQueueResult } from "./hooks/use-turn-queue";
+export type {
+  QueueMutationKind,
+  UseTurnQueueOptions,
+  UseTurnQueueResult,
+} from "./hooks/use-turn-queue";
+export { QueueSurface } from "./components/queue-surface";
+export type { QueueSurfaceProps } from "./components/queue-surface";
+export { OPEN_WORKSTREAM_CONTROL_EVENT } from "./components/chat-composer";
 export { useGoal, isGoalEvent } from "./hooks/use-goal";
 export type { UseGoalOptions, UseGoalResult } from "./hooks/use-goal";
 export { useSessionControl } from "./hooks/use-session-control";
@@ -117,15 +151,25 @@ export type {
   UseSandboxTerminalOptions,
   UseSandboxTerminalResult,
 } from "./hooks/use-sandbox-terminal";
-export { useSandboxFiles } from "./hooks/use-sandbox-files";
+export {
+  CapturedFileUnavailableError,
+  FileWriteConflictError,
+  useSandboxFiles,
+} from "./hooks/use-sandbox-files";
 export type {
+  CapturedFileUnavailableReason,
   FileTreeNode,
   FileTreeStatus,
+  SandboxWriteFileOptions,
   UseSandboxFilesOptions,
   UseSandboxFilesResult,
 } from "./hooks/use-sandbox-files";
 export { useSandboxGit } from "./hooks/use-sandbox-git";
-export type { UseSandboxGitOptions, UseSandboxGitResult } from "./hooks/use-sandbox-git";
+export type {
+  SandboxGitFileDiff,
+  UseSandboxGitOptions,
+  UseSandboxGitResult,
+} from "./hooks/use-sandbox-git";
 
 // Workbench v2 turn-end capture (the cold-paint data layer)
 export { useWorkspaceCapture } from "./hooks/use-workspace-capture";
@@ -151,6 +195,27 @@ export type {
 // Pending-approvals projection
 export { approvalsFromRequiresAction, projectPendingApprovals } from "./approvals";
 export type { PendingApproval } from "./approvals";
+export { ApprovalSurface, defaultApprovalSurfaceMessages } from "./components/approval-surface";
+export type { ApprovalSurfaceMessages, ApprovalSurfaceProps } from "./components/approval-surface";
+
+// Structured human input: event projection, authoritative hook, and styled form.
+export { humanInputRequestFromEvent, projectPendingHumanInputRequests } from "./human-input";
+export type { PendingHumanInputRequest } from "./human-input";
+export { isHumanInputEvent, useHumanInputRequests } from "./hooks/use-human-input";
+export type {
+  UseHumanInputRequestsOptions,
+  UseHumanInputRequestsResult,
+} from "./hooks/use-human-input";
+export {
+  HumanInputForm,
+  answersFromDrafts,
+  defaultHumanInputFormMessages,
+} from "./components/human-input-form";
+export type {
+  HumanInputAnswerDraft,
+  HumanInputFormMessages,
+  HumanInputFormProps,
+} from "./components/human-input-form";
 
 // Timeline projection
 export {
@@ -269,6 +334,13 @@ export type { CommandPaletteProps } from "./components/command-palette";
 // Components
 export { ChatComposer } from "./components/chat-composer";
 export type { ChatComposerProps } from "./components/chat-composer";
+export { ComposerTranscriptionControl } from "./components/composer-transcription-control";
+export type {
+  ComposerTranscriptionControlProps,
+  ComposerTranscriptionMessages,
+} from "./components/composer-transcription-control";
+export { defaultChatComposerMessages } from "./components/composer";
+export type { ChatComposerMessages } from "./components/composer";
 export { ModelPicker } from "./components/model-picker";
 export type { ModelPickerProps } from "./components/model-picker";
 export { MessageTimeline, TimelineRow } from "./components/message-timeline";
@@ -312,8 +384,12 @@ export {
   initialWorkspaceTab,
   WORKBENCH_TAB_CHANGES,
   WORKBENCH_TAB_FILES,
+  WORKBENCH_TAB_TERMINAL,
+  WORKBENCH_TAB_DESKTOP,
+  WORKBENCH_SURFACES,
 } from "./components/sandbox-workspace";
 export type {
+  SandboxWorkspaceSurface,
   SandboxWorkspaceProps,
   UseSandboxWorkspaceTabsOptions,
   UseSandboxWorkspaceTabsResult,

package/src/lib/noto-sans-arabic-loader.ts

@@ -0,0 +1,21 @@
+import fontUrl from "@fontsource-variable/noto-sans-arabic/files/noto-sans-arabic-arabic-wght-normal.woff2";
+import unicodeRanges from "@fontsource-variable/noto-sans-arabic/unicode.json";
+
+let loading: Promise<void> | undefined;
+
+export function loadNotoSansArabic(): Promise<void> {
+  loading ??= new FontFace(
+    "Noto Sans Arabic Variable",
+    `url("${fontUrl}") format("woff2-variations")`,
+    { style: "normal", weight: "100 900", unicodeRange: unicodeRanges.arabic },
+  )
+    .load()
+    .then((font) => {
+      document.fonts.add(font);
+    })
+    .catch((error: unknown) => {
+      loading = undefined;
+      throw error;
+    });
+  return loading;
+}