@opengeni/react 1.0.1 → 1.0.2-canary.37191796234001

package/src/device-authorization.tsx

@@ -0,0 +1,98 @@
+import { useEffect, useRef, useState, type ReactNode } from "react";
+import { copyTextToClipboard } from "./clipboard";
+
+export type DeviceAuthorizationProps = {
+  userCode: string;
+  verificationUri: string;
+  providerLabel?: string;
+  description?: string;
+  className?: string;
+  codeAttributes?: Record<`data-${string}`, string>;
+  loadClipboard?: () => Promise<{ copyTextToClipboard(text: string): Promise<boolean> }>;
+  onCopyResult?: (copied: boolean) => void;
+  /** Optional host presentation; clipboard state and URL validation remain shared. */
+  render?: (state: {
+    copied: boolean;
+    copyError: boolean;
+    copy: () => Promise<void>;
+    verificationHref: string | undefined;
+  }) => ReactNode;
+};
+
+/** Optional presentation for the existing model-account device APIs. It neither
+ * owns provider state nor assumes that opening a verification page completed it. */
+export function DeviceAuthorization(props: DeviceAuthorizationProps) {
+  const [copied, setCopied] = useState(false);
+  const [copyError, setCopyError] = useState(false);
+  const generation = useRef(0);
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  useEffect(() => {
+    generation.current++;
+    setCopied(false);
+    setCopyError(false);
+    return () => {
+      // This is a live async-operation counter, not a captured DOM ref.
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      generation.current++;
+      if (timer.current) clearTimeout(timer.current);
+    };
+  }, [props.userCode]);
+  async function copy() {
+    const revision = ++generation.current;
+    if (timer.current) clearTimeout(timer.current);
+    setCopied(false);
+    setCopyError(false);
+    try {
+      const clipboard = props.loadClipboard ? await props.loadClipboard() : { copyTextToClipboard };
+      if (revision !== generation.current) return;
+      const success = await clipboard.copyTextToClipboard(props.userCode);
+      if (revision !== generation.current) return;
+      setCopied(success);
+      setCopyError(!success);
+      props.onCopyResult?.(success);
+      if (success)
+        timer.current = setTimeout(() => {
+          if (revision === generation.current) setCopied(false);
+        }, 1600);
+    } catch {
+      if (revision !== generation.current) return;
+      setCopyError(true);
+      props.onCopyResult?.(false);
+    }
+  }
+  let href: string | undefined;
+  try {
+    const url = new URL(props.verificationUri);
+    if (["https:", "http:"].includes(url.protocol) && !url.username && !url.password)
+      href = props.verificationUri;
+  } catch {
+    /* A malformed provider URL must never become an executable link. */
+  }
+  if (props.render) return props.render({ copied, copyError, copy, verificationHref: href });
+  return (
+    <section className={`og-connect ${props.className ?? ""}`} aria-label="Device authorization">
+      <p>{props.description ?? `Enter this code at ${props.providerLabel ?? "the provider"}.`}</p>
+      <div style={{ display: "flex", flexWrap: "wrap", gap: "0.5rem", alignItems: "center" }}>
+        <code {...props.codeAttributes} style={{ overflowWrap: "anywhere" }}>
+          {props.userCode}
+        </code>
+        <button
+          type="button"
+          aria-label={copied ? "Code copied" : "Copy code"}
+          onClick={() => void copy()}
+        >
+          {copied ? "Copied" : "Copy code"}
+        </button>
+        {href ? (
+          <a href={href} target="_blank" rel="noopener noreferrer">
+            Open {props.providerLabel ?? "auth page"}
+          </a>
+        ) : (
+          <span role="alert">Authorization address unavailable.</span>
+        )}
+      </div>
+      {copyError ? <p role="alert">Couldn't copy the code. Copy it manually instead.</p> : null}
+      <p role="status">Waiting for authorization…</p>
+    </section>
+  );
+}

package/src/diffs.ts

@@ -0,0 +1,16 @@
+import { registerPierreDiffs } from "./lib/pierre-diffs-loader";
+
+export { registerPierreDiffs, type PierreDiffsLoader } from "./lib/pierre-diffs-loader";
+
+/**
+ * Enable Shiki-highlighted diffs and file views from the optional
+ * `@pierre/diffs` peer. Call once at startup, only when the host installs it.
+ * This is the only module in the package that names the peer, so hosts that
+ * skip it build without `@pierre/diffs` and render plain-text diffs.
+ */
+export function enablePierreDiffs(): void {
+  registerPierreDiffs(loadPierreDiffsModule);
+}
+
+// One stable loader identity, so repeated enable calls are no-ops.
+const loadPierreDiffsModule = () => import("@pierre/diffs/react");

package/src/discovery-cache.ts

@@ -0,0 +1,42 @@
+/** Short-lived presentation data only. Never cache installation or authorization state. */
+export function createDiscoveryCache<T>(ttlMs = 60_000, capacity = 64) {
+  const clients = new WeakMap<
+    object,
+    Map<string, { expires: number; value: T | undefined; pending: Promise<T> }>
+  >();
+  return {
+    peek(client: object, key: string): T | undefined {
+      const entry = clients.get(client)?.get(key);
+      return entry && entry.expires > Date.now() ? entry.value : undefined;
+    },
+    read(client: object, key: string, fetch: () => Promise<T>): Promise<T> {
+      let entries = clients.get(client);
+      if (!entries) {
+        entries = new Map();
+        clients.set(client, entries);
+      }
+      const existing = entries.get(key);
+      if (existing && existing.expires > Date.now()) return existing.pending;
+      entries.delete(key);
+      while (entries.size >= capacity) entries.delete(entries.keys().next().value!);
+      const entry = {
+        expires: Date.now() + ttlMs,
+        value: undefined as T | undefined,
+        pending: Promise.resolve().then(fetch),
+      };
+      entries.set(key, entry);
+      entry.pending = entry.pending.then(
+        (value) => {
+          entry.value = value;
+          entry.expires = Date.now() + ttlMs;
+          return value;
+        },
+        (error) => {
+          if (entries.get(key) === entry) entries.delete(key);
+          throw error;
+        },
+      );
+      return entry.pending;
+    },
+  };
+}

package/src/editor.ts

@@ -0,0 +1,13 @@
+import { registerCodeEditor, type CodeEditorLanguages } from "./lib/workbench-peers";
+
+export { CodeEditor, languageForPath } from "./components/code-editor";
+export type { CodeEditorProps } from "./components/code-editor";
+export { registerCodeEditor } from "./lib/workbench-peers";
+export type { CodeEditorLanguage, CodeEditorLanguages } from "./lib/workbench-peers";
+
+const loadEditor = async () => ({ module: await import("@uiw/react-codemirror") });
+
+/** Only name installed grammar peers in host-supplied language loaders. */
+export function enableCodeEditor(languages?: CodeEditorLanguages): void {
+  registerCodeEditor(languages ? async () => ({ ...(await loadEditor()), languages }) : loadEditor);
+}

package/src/embedded-session-client.ts

@@ -0,0 +1,104 @@
+import type { ComposerDraft } from "@opengeni/sdk";
+import type { EmbeddedSessionClientLike } from "./client";
+
+export type ComposerDraftMapContext = {
+  operation: "read" | "save" | "submit";
+  workspaceId: string;
+  sessionId: string;
+};
+
+export type CreateEmbeddedSessionClientOptions = {
+  /**
+   * Explicit host-owned method replacements. Methods inherited from `base`
+   * retain `base` as their receiver; overrides retain this object as theirs.
+   */
+  overrides?: Partial<EmbeddedSessionClientLike> | undefined;
+  /** Presentation/policy projection for every draft entering the React layer. */
+  mapComposerDraft?:
+    | ((draft: ComposerDraft, context: ComposerDraftMapContext) => ComposerDraft)
+    | undefined;
+};
+
+const requiredMethods = [
+  "getSession",
+  "listEvents",
+  "streamEvents",
+  "getComposerDraft",
+  "saveComposerDraft",
+  "submitComposerDraft",
+  "sendMessage",
+  "steerMessage",
+  "getQueue",
+  "moveQueueItem",
+  "editQueueItem",
+  "steerQueueItem",
+  "deleteQueueItem",
+  "pauseSession",
+  "resumeSession",
+  "sendApprovalDecision",
+] as const satisfies readonly (keyof EmbeddedSessionClientLike)[];
+
+/**
+ * Build the exact client required by `@opengeni/react/session` from a full SDK
+ * client or host proxy. The constructor binds every delegated method once,
+ * supports a host-owned atomic composer-submit override, and fails at creation
+ * time instead of waiting for a missing method to be exercised by a hook.
+ */
+export function createEmbeddedSessionClient(
+  base: EmbeddedSessionClientLike,
+  options: CreateEmbeddedSessionClientOptions = {},
+): EmbeddedSessionClientLike {
+  const overrides = options.overrides ?? {};
+  const client = {} as EmbeddedSessionClientLike;
+  for (const key of requiredMethods) {
+    const override = overrides[key];
+    const method = override ?? base[key];
+    if (typeof method !== "function") {
+      throw new TypeError(`Embedded session client method is required: ${key}`);
+    }
+    client[key] = method.bind(override === undefined ? base : overrides) as never;
+  }
+
+  const inferenceOverride = overrides.setWorkspaceInferenceState;
+  const inferenceBase = base.setWorkspaceInferenceState;
+  const inferenceMethod = inferenceOverride ?? inferenceBase;
+  if (typeof inferenceMethod === "function") {
+    client.setWorkspaceInferenceState = inferenceMethod.bind(
+      inferenceOverride === undefined ? base : overrides,
+    );
+  }
+
+  const mapDraft = options.mapComposerDraft;
+  if (!mapDraft) return client;
+
+  const getComposerDraft = client.getComposerDraft;
+  client.getComposerDraft = async (workspaceId, sessionId) =>
+    mapDraft(await getComposerDraft(workspaceId, sessionId), {
+      operation: "read",
+      workspaceId,
+      sessionId,
+    });
+
+  const saveComposerDraft = client.saveComposerDraft;
+  client.saveComposerDraft = async (workspaceId, sessionId, request) =>
+    mapDraft(await saveComposerDraft(workspaceId, sessionId, request), {
+      operation: "save",
+      workspaceId,
+      sessionId,
+    });
+
+  const submitComposerDraft = client.submitComposerDraft;
+  client.submitComposerDraft = async (workspaceId, sessionId, request) => {
+    const response = await submitComposerDraft(workspaceId, sessionId, request);
+    return {
+      ...response,
+      draft: mapDraft(response.draft, {
+        operation: "submit",
+        workspaceId,
+        sessionId,
+      }),
+    };
+  };
+
+  return client;
+}

package/src/file-node-visibility.ts

@@ -0,0 +1,66 @@
+import type { FileTreeNode } from "./hooks/use-sandbox-files";
+
+export type FileNodeVisibilityContext = {
+  depth: number;
+  parent: FileTreeNode | null;
+};
+
+/** Presentation-only predicate. It never changes filesystem authorization. */
+export type FileNodeVisibilityPredicate = (
+  node: FileTreeNode,
+  context: FileNodeVisibilityContext,
+) => boolean;
+
+export type FilePathVisibility = "visible" | "hidden" | "unknown";
+
+function pathIsInsideDirectory(path: string, directory: string): boolean {
+  if (!path.startsWith(directory) || path === directory) return false;
+  if (directory.endsWith("/") || directory.endsWith("\\")) return true;
+  const boundary = path[directory.length];
+  return boundary === "/" || boundary === "\\";
+}
+
+/**
+ * Filter an authoritative tree without promoting children of a hidden parent.
+ * Undefined children stay undefined so lazy-loading semantics are preserved.
+ */
+export function visibleFileTree(
+  nodes: FileTreeNode[],
+  predicate?: FileNodeVisibilityPredicate,
+  parent: FileTreeNode | null = null,
+  depth = 0,
+): FileTreeNode[] {
+  if (!predicate) return nodes;
+  const visible: FileTreeNode[] = [];
+  for (const node of nodes) {
+    if (!predicate(node, { depth, parent })) continue;
+    visible.push(
+      node.children === undefined
+        ? node
+        : {
+            ...node,
+            children: visibleFileTree(node.children, predicate, node, depth + 1),
+          },
+    );
+  }
+  return visible;
+}
+
+/** Resolve only what the currently loaded tree can prove. */
+export function filePathVisibility(
+  nodes: FileTreeNode[],
+  path: string,
+  predicate?: FileNodeVisibilityPredicate,
+  parent: FileTreeNode | null = null,
+  depth = 0,
+): FilePathVisibility {
+  if (!predicate) return "visible";
+  for (const node of nodes) {
+    if (node.path !== path && !pathIsInsideDirectory(path, node.path)) continue;
+    if (!predicate(node, { depth, parent })) return "hidden";
+    if (node.path === path) return "visible";
+    if (node.kind !== "dir" || node.children === undefined) return "unknown";
+    return filePathVisibility(node.children, path, predicate, node, depth + 1);
+  }
+  return "unknown";
+}

package/src/hooks/channel-cache.ts

@@ -0,0 +1,104 @@
+import type { Channel } from "@opengeni/sdk";
+import type { SessionClientLike } from "../client";
+
+type PendingChannel = { channel: Channel; committedAfterLoad: number };
+
+export type ChannelCacheSnapshot = Readonly<{
+  channels: readonly Channel[];
+  ready: boolean;
+}>;
+
+export type ChannelCacheStore = Readonly<{
+  getSnapshot: () => ChannelCacheSnapshot;
+  subscribe: (listener: () => void) => () => void;
+  beginLoad: () => number;
+  acceptLoad: (ticket: number, channels: readonly Channel[]) => void;
+  publishCreated: (channel: Channel) => void;
+}>;
+
+const EMPTY_CHANNELS: readonly Channel[] = [];
+const EMPTY_SNAPSHOT: ChannelCacheSnapshot = {
+  channels: EMPTY_CHANNELS,
+  ready: false,
+};
+const channelCaches = new WeakMap<object, Map<string, ChannelCacheStore>>();
+
+function compareChannels(left: Channel, right: Channel): number {
+  return (
+    Number(right.pinned) - Number(left.pinned) ||
+    left.sortOrder - right.sortOrder ||
+    left.id.localeCompare(right.id)
+  );
+}
+
+function orderedChannels(channels: readonly Channel[]): Channel[] {
+  return [...channels].sort(compareChannels);
+}
+
+function upsertChannel(channels: readonly Channel[], channel: Channel): Channel[] {
+  const next = channels.filter((candidate) => candidate.id !== channel.id);
+  next.push(channel);
+  return orderedChannels(next);
+}
+
+/**
+ * One client/workspace cache shared by every useChannels consumer.
+ *
+ * List reads are ticketed so an older request cannot erase a newer result.
+ * A successful create remains layered over the latest server snapshot until a
+ * list request that started after that success reconciles it. Requests already
+ * in flight cannot make the project disappear between create and session start.
+ */
+export function createChannelCacheStore(): ChannelCacheStore {
+  let base: readonly Channel[] | null = null;
+  let snapshot = EMPTY_SNAPSHOT;
+  let nextLoadTicket = 0;
+  let acceptedLoadTicket = 0;
+  const pending = new Map<string, PendingChannel>();
+  const listeners = new Set<() => void>();
+
+  const publish = () => {
+    let channels = base ?? EMPTY_CHANNELS;
+    for (const { channel } of pending.values()) {
+      channels = upsertChannel(channels, channel);
+    }
+    snapshot = { channels, ready: base !== null || pending.size > 0 };
+    for (const listener of listeners) listener();
+  };
+
+  return {
+    getSnapshot: () => snapshot,
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    beginLoad: () => ++nextLoadTicket,
+    acceptLoad: (ticket, channels) => {
+      if (ticket < acceptedLoadTicket) return;
+      acceptedLoadTicket = ticket;
+      base = orderedChannels(channels);
+      for (const [id, created] of pending) {
+        if (ticket > created.committedAfterLoad) pending.delete(id);
+      }
+      publish();
+    },
+    publishCreated: (channel) => {
+      pending.set(channel.id, { channel, committedAfterLoad: nextLoadTicket });
+      publish();
+    },
+  };
+}
+
+export function channelCacheFor(client: SessionClientLike, workspaceId: string): ChannelCacheStore {
+  let byWorkspace = channelCaches.get(client);
+  if (!byWorkspace) {
+    byWorkspace = new Map();
+    channelCaches.set(client, byWorkspace);
+  }
+  let cache = byWorkspace.get(workspaceId);
+  if (!cache) {
+    cache = createChannelCacheStore();
+    byWorkspace.set(workspaceId, cache);
+  }
+  return cache;
+}

package/src/hooks/internal.ts

@@ -1,6 +1,7 @@
 import type { SessionEvent } from "@opengeni/sdk";
 import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
 import type { EmbeddedSessionEventClientLike } from "../client";
+import { normalizeError } from "../lib/error-message";
 
 const HIDDEN_STREAM_GRACE_MS = 2_000;
 
@@ -116,7 +117,7 @@ export function usePolledValue<T>(
           activeLoadRef.current === load &&
           !requestAbort.signal.aborted
         ) {
-          setError(cause instanceof Error ? cause : new Error(String(cause)));
+          setError(normalizeError(cause));
           setLoading(false);
         }
       } finally {
@@ -258,7 +259,7 @@ export function useMutationRunner(identity: unknown = undefined): MutationState
           generation.current === ownedGeneration &&
           Object.is(identityRef.current, ownedIdentity)
         ) {
-          setMutationError(cause instanceof Error ? cause : new Error(String(cause)));
+          setMutationError(normalizeError(cause));
         }
         return null;
       } finally {

package/src/hooks/latest-question.ts

@@ -0,0 +1,164 @@
+import { SESSION_EVENT_TYPES, type SessionEvent, type SessionTurn } from "@opengeni/sdk";
+import type { EmbeddedSessionClientLike } from "../client";
+import {
+  isTimelineUserQuestion,
+  isTurnExecutionEvidence,
+  timelineQuestionPlacement,
+} from "../timeline/projection";
+
+export type LatestQuestionOptions = {
+  /** Check navigation.isCurrent() after awaits and immediately before UI effects. */
+  onQueuedQuestion?: (
+    turn: SessionTurn,
+    navigation: { isCurrent: () => boolean },
+  ) => void | Promise<void>;
+};
+
+/** Include every canonical execution fallback, not just turn.started. Derive
+ * this optional navigation index only when the user requests Latest question. */
+export const TIMELINE_TURN_ANCHOR_EVENT_TYPES = SESSION_EVENT_TYPES.filter(
+  (type) =>
+    isTurnExecutionEvidence(type) ||
+    type === "turn.queued" ||
+    type === "turn.started" ||
+    type === "turn.cancelled" ||
+    type === "session.queue.changed" ||
+    type === "session.control.steer_requested",
+);
+
+/** Resolve an optional navigation destination without owning the hook's window
+ * or React state. The caller guards errors and applies only a current result. */
+export async function resolveLatestQuestion({
+  client,
+  workspaceId,
+  sessionId,
+  isCurrent,
+  resumeSequence,
+  options,
+}: {
+  client: EmbeddedSessionClientLike;
+  workspaceId: string;
+  sessionId: string;
+  isCurrent: () => boolean;
+  resumeSequence: (events: readonly SessionEvent[]) => number;
+  options?: LatestQuestionOptions | undefined;
+}): Promise<{ questionSequence: number; anchor: number; events: SessionEvent[] } | null> {
+  let before: number | undefined;
+  while (true) {
+    const latest = await client.listEvents(workspaceId, sessionId, {
+      direction: "before",
+      includeTypes: ["user.message"],
+      // Historical worker completions also used user.message; page only this
+      // filtered index when they occupy the tail.
+      limit: before === undefined ? 1 : 64,
+      ...(before === undefined ? {} : { before }),
+      payloadMode: "full",
+      mode: "forensic",
+    });
+    if (!isCurrent()) return null;
+    // Keep legacy childCompletion classification aligned with the transcript.
+    const question = [...latest]
+      .sort((a, b) => b.sequence - a.sequence)
+      .find(isTimelineUserQuestion);
+    if (question) {
+      const queue = await client.getQueue(workspaceId, sessionId);
+      if (!isCurrent()) return null;
+      const pending = queue.items.find(
+        (turn) => turn.triggerEventId === question.id && turn.metadata.delivery !== "steer",
+      );
+      if (pending) {
+        if (!options?.onQueuedQuestion) {
+          const reason = new Error("The latest question is in the prompt queue.");
+          reason.name = "LatestQuestionQueuedError";
+          throw reason;
+        }
+        await options.onQueuedQuestion(pending, { isCurrent });
+        if (!isCurrent()) return null;
+        // Queue refresh/focus can race a claim or withdrawal. Resolve that
+        // transition below instead of settling on a row that just vanished.
+        const refreshedQueue = await client.getQueue(workspaceId, sessionId);
+        if (!isCurrent()) return null;
+        if (
+          refreshedQueue.items.some(
+            (turn) => turn.triggerEventId === question.id && turn.metadata.delivery !== "steer",
+          )
+        )
+          return null;
+      }
+      const evidence: SessionEvent[] = [];
+      const payload =
+        question.payload != null && typeof question.payload === "object"
+          ? (question.payload as Record<string, unknown>)
+          : {};
+      // Explicit direct admission needs no lifecycle lookup. Older ledgers and
+      // queued admission need their durable start/withdrawal witnesses.
+      if (
+        payload.routing !== "accepted_for_execution" &&
+        payload.routing !== "accepted_for_steering" &&
+        payload.delivery !== "steer"
+      ) {
+        let lifecycleAfter = question.sequence;
+        while (true) {
+          const page = await client.listEvents(workspaceId, sessionId, {
+            direction: "after",
+            after: lifecycleAfter,
+            limit: 128,
+            compact: true,
+            mode: "forensic",
+            payloadMode: "full",
+            includeTypes: TIMELINE_TURN_ANCHOR_EVENT_TYPES,
+          });
+          if (!isCurrent()) return null;
+          const next = Math.max(lifecycleAfter, resumeSequence(page));
+          if (next === lifecycleAfter) break;
+          const queued =
+            page.find(
+              (event) =>
+                event.type === "turn.queued" &&
+                ((event.payload ?? {}) as Record<string, unknown>).triggerEventId === question.id,
+            ) ?? evidence.find((event) => event.type === "turn.queued");
+          const turnId =
+            queued && (((queued.payload ?? {}) as Record<string, unknown>).turnId ?? queued.turnId);
+          evidence.push(
+            ...page.filter((event) => {
+              const data = (event.payload ?? {}) as Record<string, unknown>;
+              return (
+                data.triggerEventId === question.id ||
+                (turnId != null &&
+                  (event.turnId === turnId ||
+                    data.turnId === turnId ||
+                    data.targetTurnId === turnId))
+              );
+            }),
+          );
+          lifecycleAfter = next;
+          const placed = timelineQuestionPlacement(question, evidence);
+          if (placed.kind === "visible" && placed.sequence !== question.sequence) break;
+        }
+      }
+      const placement = timelineQuestionPlacement(question, evidence);
+      if (placement.kind === "withdrawn") {
+        before = question.sequence;
+        continue;
+      }
+      if (placement.kind === "pending")
+        throw new Error("The latest question is changing queue state. Try again.");
+      return {
+        questionSequence: question.sequence,
+        anchor: placement.sequence,
+        events: [
+          question,
+          ...evidence.filter(
+            (event) =>
+              event.type === "turn.queued" &&
+              ((event.payload ?? {}) as Record<string, unknown>).triggerEventId === question.id,
+          ),
+        ],
+      };
+    }
+    const oldest = Math.min(...latest.map((event) => event.sequence));
+    if (!Number.isSafeInteger(oldest) || oldest <= 1 || (before !== undefined && oldest >= before))
+      return null;
+    before = oldest;
+  }
+}