@opengeni/react 1.0.1 → 1.0.2-canary.37191796234001

package/src/older-history.ts

@@ -0,0 +1,87 @@
+/**
+ * Await-compatible older-history result with a causal commit receipt.
+ *
+ * `committed` flips synchronously before the accepted older window is exposed
+ * to React. Returning this exact object preserves the receipt directly;
+ * synchronous wrappers that discard it remain supported through receipt
+ * capture, while replacing it asynchronously with a plain promise does not.
+ */
+export type OlderHistoryLoadReceipt = Promise<boolean> & {
+  readonly committed: boolean;
+  readonly tailPreserved?: boolean;
+};
+
+/**
+ * Source-compatible public callback accepted by MessageTimeline.
+ *
+ * The callback historically returned `void`, which permits consumers to
+ * return any synchronous value or promise. Receipt-aware loaders opt into the
+ * stronger runtime contract by returning (or synchronously creating through a
+ * wrapper) an {@link OlderHistoryLoadReceipt}.
+ */
+export type OlderHistoryLoader = () => unknown;
+
+type MutableOlderHistoryLoadReceipt = Promise<boolean> & {
+  committed: boolean;
+  tailPreserved: boolean;
+};
+
+type OlderHistoryReceiptCapture = (receipt: OlderHistoryLoadReceipt) => void;
+
+let activeReceiptCapture: OlderHistoryReceiptCapture | undefined;
+let preserveTailForAutomaticLoad = false;
+
+/** Bind a receipt before a synchronous forwarding stack can publish state. */
+export function invokeOlderHistoryLoaderWithReceiptCapture(
+  load: OlderHistoryLoader,
+  capture: OlderHistoryReceiptCapture,
+  preserveTail = false,
+): unknown {
+  const previousCapture = activeReceiptCapture;
+  const previousPreserveTail = preserveTailForAutomaticLoad;
+  activeReceiptCapture = capture;
+  preserveTailForAutomaticLoad = preserveTail;
+  try {
+    return load();
+  } finally {
+    activeReceiptCapture = previousCapture;
+    preserveTailForAutomaticLoad = previousPreserveTail;
+  }
+}
+
+/**
+ * Build an await-compatible older-history receipt for custom timeline hosts.
+ * Call `markCommitted` immediately before publishing an accepted older window.
+ */
+export function createOlderHistoryLoadReceipt(
+  load: (
+    markCommitted: () => void,
+    preserveTail: boolean,
+    markTailPreserved: () => void,
+  ) => boolean | Promise<boolean>,
+): OlderHistoryLoadReceipt {
+  let resolveResult!: (value: boolean | PromiseLike<boolean>) => void;
+  let rejectResult!: (reason?: unknown) => void;
+  const result = new Promise<boolean>((resolve, reject) => {
+    resolveResult = resolve;
+    rejectResult = reject;
+  }) as MutableOlderHistoryLoadReceipt;
+  result.committed = false;
+  result.tailPreserved = false;
+  activeReceiptCapture?.(result);
+  try {
+    const loaded = load(
+      () => {
+        result.committed = true;
+      },
+      preserveTailForAutomaticLoad,
+      () => {
+        result.tailPreserved = true;
+      },
+    );
+    Promise.resolve(loaded).then(resolveResult, rejectResult);
+  } catch (error) {
+    rejectResult(error);
+  }
+  return result;
+}

package/src/plugin-details.tsx

@@ -0,0 +1,185 @@
+import { useState } from "react";
+import { pluginMcpUnavailableReason, type PluginDiscoveryItem } from "@opengeni/sdk";
+import { BoxesIcon } from "lucide-react";
+import { Markdown } from "./components/markdown";
+import { ConnectionLogo } from "./connection-logo";
+
+const componentLabels: Record<string, string> = {
+  skills: "Skills",
+  mcp: "MCP connections",
+  apps: "Hosted apps",
+  hooks: "Hooks",
+  agents: "Agents",
+  commands: "Commands",
+  lsp: "Language servers",
+};
+
+const EMPTY_CONNECTIONS: Record<string, boolean> = {};
+
+/** Embeddable plugin overview. Hosts own the dialog and installation actions. */
+export function PluginDetails({
+  item,
+  onInstall,
+  busy = false,
+  installed = false,
+  error,
+  connections = EMPTY_CONNECTIONS,
+  onConnect,
+}: {
+  item: PluginDiscoveryItem;
+  onInstall?: () => void;
+  busy?: boolean;
+  installed?: boolean;
+  error?: string | null;
+  connections?: Record<string, boolean>;
+  onConnect?: (server: { name: string; endpoint: string | null }) => void;
+}) {
+  const supported = (server: NonNullable<PluginDiscoveryItem["mcpServers"]>[number]) =>
+    pluginMcpUnavailableReason(server) === null;
+  const contentsUnknown = item.skills == null || item.mcpServers == null;
+  const installableCount =
+    (item.skills?.length ?? 0) + (item.mcpServers?.filter(supported).length ?? 0);
+  const exceedsInstallLimit = installableCount > 64;
+  const installable = !contentsUnknown && installableCount > 0 && !exceedsInstallLimit;
+  const [expanded, setExpanded] = useState(false);
+  const description = item.longDescription || item.description;
+  const lengthy = description.length > 700;
+  const registryLabel =
+    item.provider === "openai"
+      ? "OpenAI plugin registry"
+      : item.provider === "anthropic"
+        ? "Anthropic plugin registry"
+        : "Custom source";
+  return (
+    <article className="og-plugin-details">
+      <header className="og-plugin-details-header">
+        <ConnectionLogo
+          src={item.logoUrl}
+          name={item.displayName}
+          fallback={<BoxesIcon aria-hidden="true" />}
+        />
+        <div>
+          <h2>{item.displayName.replace(/-/g, " ")}</h2>
+          {item.author?.name ? <p>By {item.author.name}</p> : null}
+        </div>
+      </header>
+      <div className="og-plugin-details-meta">
+        <span>{registryLabel}</span>
+        {item.category ? <span>{item.category}</span> : null}
+        {item.version ? <span>v{item.version}</span> : null}
+      </div>
+      <section className="og-plugin-details-members">
+        <h3>
+          Skills <span>{item.skills?.length ?? "—"}</span>
+        </h3>
+        {item.skills?.length ? (
+          <ul>
+            {item.skills.map((skill) => (
+              <li key={skill.sourceUrl}>
+                <a href={skill.sourceUrl} target="_blank" rel="noopener noreferrer">
+                  <strong>{skill.name}</strong>
+                  <span aria-hidden="true">↗</span>
+                </a>
+              </li>
+            ))}
+          </ul>
+        ) : (
+          <p>
+            {item.skills
+              ? "No bundled skills."
+              : "Contents haven’t been indexed for this repository."}
+          </p>
+        )}
+        <h3>
+          MCP servers <span>{item.mcpServers?.length ?? "—"}</span>
+        </h3>
+        {item.mcpServers?.length ? (
+          <ul>
+            {item.mcpServers.map((server) => {
+              const connected = Boolean(server.endpoint && connections[server.endpoint]);
+              // Existing connections remain manageable regardless of the source manifest's setup requirements.
+              const unavailableReason = connected ? null : pluginMcpUnavailableReason(server);
+              return (
+                <li
+                  key={server.name}
+                  className={unavailableReason ? "og-plugin-member-disabled" : undefined}
+                >
+                  <div className="og-plugin-server-heading">
+                    <strong>{server.name}</strong>
+                    {!unavailableReason && onConnect ? (
+                      <button type="button" disabled={busy} onClick={() => onConnect(server)}>
+                        {connected ? "Manage" : "Connect"}
+                      </button>
+                    ) : null}
+                  </div>
+                  <small>
+                    {connected ? "Connected · " : ""}
+                    {unavailableReason ?? server.endpoint}
+                  </small>
+                </li>
+              );
+            })}
+          </ul>
+        ) : (
+          <p>
+            {item.mcpServers ? "No bundled MCP servers." : "Server details haven’t been indexed."}
+          </p>
+        )}
+        {item.components?.some((component) => !["skills", "mcp"].includes(component)) ? (
+          <div className="og-plugin-details-other">
+            Not installed here:{" "}
+            {item.components
+              .filter((component) => !["skills", "mcp"].includes(component))
+              .map((component) => componentLabels[component] ?? component)
+              .join(", ")}
+          </div>
+        ) : null}
+      </section>
+      <section className="og-plugin-details-overview" aria-label="Overview">
+        <div className={lengthy && !expanded ? "og-plugin-details-excerpt" : undefined}>
+          <Markdown>{description}</Markdown>
+        </div>
+        {lengthy ? (
+          <button
+            type="button"
+            className="og-plugin-details-more"
+            aria-expanded={expanded}
+            onClick={() => setExpanded((value) => !value)}
+          >
+            {expanded ? "Show less" : "Read more"}
+          </button>
+        ) : null}
+      </section>
+      <footer>
+        {item.sourceUrl ? (
+          <a href={item.sourceUrl} target="_blank" rel="noopener noreferrer">
+            View repository <span aria-hidden="true">↗</span>
+          </a>
+        ) : null}
+        {onInstall ? (
+          <button
+            className="og-plugin-install"
+            type="button"
+            disabled={!installable || busy || installed}
+            onClick={onInstall}
+          >
+            {installed ? "Installed" : busy ? "Installing…" : "Install plugin"}
+          </button>
+        ) : null}
+        {error ? <p role="alert">{error}</p> : null}
+        {exceedsInstallLimit ? (
+          <p>This plugin exceeds the current 64-component installation limit.</p>
+        ) : contentsUnknown ? (
+          <p>
+            Plugin contents are unavailable. Installation is disabled until the repository can be
+            inspected.
+          </p>
+        ) : !installable ? (
+          <p>No installable skills or remote MCP servers.</p>
+        ) : (
+          <p>Installs skills and adds connection references. Connect each server separately.</p>
+        )}
+      </footer>
+    </article>
+  );
+}

package/src/plugin-discovery.tsx

@@ -0,0 +1,196 @@
+import { createDiscoveryCache } from "./discovery-cache";
+import { useEffect, useRef, useState, type ReactNode } from "react";
+import type { PluginDiscoveryItem, PluginDiscoveryPage } from "@opengeni/sdk";
+import { BoxesIcon } from "lucide-react";
+import { CapabilityCatalogRow } from "./capability-catalog-row";
+import { ConnectionLogo } from "./connection-logo";
+
+const discoveryCache = createDiscoveryCache<PluginDiscoveryPage>();
+const spacedName = (name: string) => name.replace(/-/g, " ");
+const EMPTY_INSTALLED_IDS: ReadonlySet<string> = new Set();
+
+export type PluginDiscoveryProps = {
+  client: {
+    discoverPlugins(
+      workspaceId: string,
+      options?: { query?: string; provider?: string; offset?: number },
+    ): Promise<PluginDiscoveryPage>;
+  };
+  workspaceId: string;
+  query: string;
+  /** Initially selected registry. Users can still switch registries or browse all. */
+  defaultProvider?: "" | "openai" | "anthropic";
+  /** Discovery identities already installed in the current workspace. */
+  installedIds?: ReadonlySet<string>;
+  resultLimit?: number;
+  onShowMore?: () => void;
+  onOpen: (item: PluginDiscoveryItem) => void;
+  /** Display name for a registry slug. Defaults to the slug with dashes as spaces. */
+  formatName?: (name: string) => string;
+  /** The row tile. Defaults to the plugin logo with a glyph fallback. */
+  renderIcon?: (item: PluginDiscoveryItem) => ReactNode;
+};
+export function PluginDiscovery(props: PluginDiscoveryProps) {
+  const [provider, setProvider] = useState(props.defaultProvider ?? "");
+  return (
+    <section
+      className={`og-plugin-discovery ${props.resultLimit ? "og-catalog-overview" : ""}`}
+      aria-label="Discover plugins"
+    >
+      <header>
+        <h3>{props.resultLimit ? "Plugins" : "Browse plugins"}</h3>
+        {!props.resultLimit ? (
+          <div className="og-plugin-filters" role="group" aria-label="Plugin registry">
+            {(
+              [
+                { value: "", label: "All" },
+                { value: "openai", label: "OpenAI plugin registry" },
+                { value: "anthropic", label: "Anthropic plugin registry" },
+              ] as const
+            ).map((option) => (
+              <button
+                key={option.value}
+                type="button"
+                aria-pressed={provider === option.value}
+                onClick={() => setProvider(option.value)}
+              >
+                {option.label}
+              </button>
+            ))}
+          </div>
+        ) : null}
+      </header>
+      <Results
+        key={`${props.workspaceId}:${props.query}:${provider}`}
+        {...props}
+        provider={provider}
+      />
+    </section>
+  );
+}
+function Results({
+  client,
+  workspaceId,
+  query,
+  provider,
+  installedIds = EMPTY_INSTALLED_IDS,
+  onOpen,
+  resultLimit,
+  onShowMore,
+  formatName = spacedName,
+  renderIcon,
+}: PluginDiscoveryProps & { provider: string }) {
+  const initial = discoveryCache.peek(client, JSON.stringify([workspaceId, query, provider, 0]));
+  const [items, setItems] = useState<PluginDiscoveryItem[]>(initial?.items ?? []);
+  const [offset, setOffset] = useState(0);
+  const [next, setNext] = useState<number | null>(initial?.nextOffset ?? null);
+  const [total, setTotal] = useState(initial?.total ?? 0);
+  const [loading, setLoading] = useState(!initial);
+  const [error, setError] = useState(false);
+  const [retry, setRetry] = useState(0);
+  const sentinel = useRef<HTMLDivElement>(null);
+  useEffect(() => {
+    let active = true;
+    const cacheKey = JSON.stringify([workspaceId, query, provider, offset]);
+    const cached = discoveryCache.peek(client, cacheKey);
+    setLoading(!cached);
+    setError(false);
+    const timer = setTimeout(
+      () => {
+        void discoveryCache
+          .read(client, cacheKey, () =>
+            client.discoverPlugins(workspaceId, { query, provider, offset }),
+          )
+          .then(
+            (page) => {
+              if (!active) return;
+              setItems((previous) => (offset ? [...previous, ...page.items] : page.items));
+              setTotal(page.total);
+              setNext(page.nextOffset);
+              setLoading(false);
+            },
+            () => {
+              if (active) {
+                setError(true);
+                setLoading(false);
+              }
+            },
+          );
+      },
+      cached || offset ? 0 : 200,
+    );
+    return () => {
+      active = false;
+      clearTimeout(timer);
+    };
+  }, [client, workspaceId, query, provider, offset, retry]);
+  useEffect(() => {
+    if (resultLimit || loading || error || next === null || !sentinel.current) return;
+    const observer = new IntersectionObserver(
+      (entries) => {
+        if (entries.some((entry) => entry.isIntersecting)) setOffset(next);
+      },
+      { rootMargin: "200px" },
+    );
+    observer.observe(sentinel.current);
+    return () => observer.disconnect();
+  }, [loading, error, next, resultLimit]);
+  return (
+    <>
+      {!loading && !error ? (
+        <p role="status">
+          {total
+            ? "Bundles of skills and connections"
+            : query.trim()
+              ? `No matches for “${query.trim()}”.`
+              : "No plugins in this registry."}
+        </p>
+      ) : null}
+      <div className="og-plugin-discovery-grid">
+        {items.slice(0, resultLimit).map((item) => (
+          <CapabilityCatalogRow
+            key={item.id}
+            data-plugin-id={item.id}
+            name={formatName(item.displayName)}
+            description={item.description}
+            status={installedIds.has(item.id) ? "added" : "available"}
+            statusLabel={installedIds.has(item.id) ? "Installed" : "Available to install"}
+            onOpen={() => onOpen(item)}
+            icon={
+              renderIcon ? (
+                renderIcon(item)
+              ) : (
+                <ConnectionLogo
+                  src={item.logoUrl}
+                  name={item.displayName}
+                  fallback={<BoxesIcon aria-hidden="true" />}
+                />
+              )
+            }
+          />
+        ))}
+      </div>
+      {loading ? <p role="status">Loading plugins…</p> : null}
+      {error ? (
+        <p role="alert">
+          Couldn’t load plugins.{" "}
+          <button type="button" onClick={() => setRetry((value) => value + 1)}>
+            Retry
+          </button>
+        </p>
+      ) : null}
+      {resultLimit && !loading && !error && total > resultLimit ? (
+        <button className="og-catalog-more" type="button" onClick={onShowMore}>
+          View all plugins
+        </button>
+      ) : null}
+      <div ref={sentinel}>
+        {!resultLimit && next !== null && !loading && !error ? (
+          <button className="og-plugin-more" type="button" onClick={() => setOffset(next)}>
+            Show more plugins
+          </button>
+        ) : null}
+      </div>
+    </>
+  );
+}

package/src/provider.tsx

@@ -9,6 +9,9 @@ import { useCallback, useEffect, useMemo, useRef, useState, type ReactNode } fro
 import type { SessionClientLike } from "./client";
 import { usePageLiveActivity } from "./hooks/internal";
 import { OpenGeniContext } from "./session-context";
+import { ErrorMessageContext, type ErrorMessageFormatter } from "./lib/error-message";
+
+export type { ErrorMessageFormatter } from "./lib/error-message";
 
 export { useOpenGeni, useOpenGeniClient } from "./session-context";
 export type { ClientOverride, OpenGeniContextValue } from "./session-context";
@@ -19,6 +22,16 @@ export type OpenGeniProviderProps = {
   workspaceId: string;
   onWorkspaceControlEvent?: ((event: WorkspaceControlEvent) => void) | undefined;
   onWorkspaceInteractionEvent?: ((event: WorkspaceInteractionRevisionEvent) => void) | undefined;
+  /**
+   * Stale-tab protection for the stock OpenGeni web app: when the server's API
+   * contract revision differs from this bundle's, cover the page and reload it
+   * once. Off by default, because an embedded product's page must never be
+   * blocked or reloaded when OpenGeni deploys; there a mismatch is ignored and
+   * the SDK's tolerant-reader compatibility applies.
+   */
+  reloadOnApiContractChange?: boolean | undefined;
+  /** Host-owned error copy. Receives the original diagnostic error and neutral default copy. */
+  formatError?: ErrorMessageFormatter | undefined;
   children?: ReactNode;
 };
 
@@ -31,6 +44,8 @@ export function OpenGeniProvider({
   workspaceId,
   onWorkspaceControlEvent,
   onWorkspaceInteractionEvent,
+  reloadOnApiContractChange = false,
+  formatError,
   children,
 }: OpenGeniProviderProps) {
   const [workspaceControlEvent, setWorkspaceControlEvent] = useState<WorkspaceControlEvent | null>(
@@ -59,10 +74,11 @@ export function OpenGeniProvider({
   callbackRef.current = onWorkspaceControlEvent;
   interactionCallbackRef.current = onWorkspaceInteractionEvent;
 
+  const strictContract = reloadOnApiContractChange;
   const verifyApiContract = useCallback(async (): Promise<void> => {
     try {
       const config = await client.getClientConfig();
-      if (config.apiContractRevision !== OPENGENI_API_CONTRACT_REVISION) {
+      if (strictContract && config.apiContractRevision !== OPENGENI_API_CONTRACT_REVISION) {
         throw new OpenGeniApiContractMismatchError(
           OPENGENI_API_CONTRACT_REVISION,
           String(config.apiContractRevision || "(missing)"),
@@ -70,12 +86,14 @@ export function OpenGeniProvider({
       }
     } catch (error) {
       if (error instanceof OpenGeniApiContractMismatchError) {
+        // Embedded hosts: a revision difference is not a reason to block or reload the page.
+        if (!strictContract) return;
         setContractMismatch(error);
         reloadForContractMismatchOnce(error);
       }
       throw error;
     }
-  }, [client]);
+  }, [client, strictContract]);
 
   const registerSessionReconciler = useMemo(
     () =>
@@ -175,7 +193,7 @@ export function OpenGeniProvider({
           }
         }
       } catch (error) {
-        if (error instanceof OpenGeniApiContractMismatchError) {
+        if (strictContract && error instanceof OpenGeniApiContractMismatchError) {
           setContractMismatch(error);
           reloadForContractMismatchOnce(error);
         }
@@ -186,7 +204,14 @@ export function OpenGeniProvider({
       }
     })();
     return () => controller.abort();
-  }, [client, pageLive, supportsWorkspaceLiveStream, verifyApiContract, workspaceId]);
+  }, [
+    client,
+    pageLive,
+    strictContract,
+    supportsWorkspaceLiveStream,
+    verifyApiContract,
+    workspaceId,
+  ]);
 
   useEffect(() => {
     if (supportsWorkspaceLiveStream) return;
@@ -222,7 +247,7 @@ export function OpenGeniProvider({
           callbackRef.current?.(event);
         }
       } catch (error) {
-        if (error instanceof OpenGeniApiContractMismatchError) {
+        if (strictContract && error instanceof OpenGeniApiContractMismatchError) {
           setContractMismatch(error);
           reloadForContractMismatchOnce(error);
         }
@@ -230,7 +255,14 @@ export function OpenGeniProvider({
       }
     })();
     return () => controller.abort();
-  }, [client, pageLive, supportsWorkspaceLiveStream, verifyApiContract, workspaceId]);
+  }, [
+    client,
+    pageLive,
+    strictContract,
+    supportsWorkspaceLiveStream,
+    verifyApiContract,
+    workspaceId,
+  ]);
 
   useEffect(() => {
     if (supportsWorkspaceLiveStream) return;
@@ -265,7 +297,7 @@ export function OpenGeniProvider({
           interactionCallbackRef.current?.(event);
         }
       } catch (error) {
-        if (error instanceof OpenGeniApiContractMismatchError) {
+        if (strictContract && error instanceof OpenGeniApiContractMismatchError) {
           setContractMismatch(error);
           reloadForContractMismatchOnce(error);
         }
@@ -273,7 +305,14 @@ export function OpenGeniProvider({
       }
     })();
     return () => controller.abort();
-  }, [client, pageLive, supportsWorkspaceLiveStream, verifyApiContract, workspaceId]);
+  }, [
+    client,
+    pageLive,
+    strictContract,
+    supportsWorkspaceLiveStream,
+    verifyApiContract,
+    workspaceId,
+  ]);
 
   const value = useMemo(
     () => ({
@@ -298,10 +337,12 @@ export function OpenGeniProvider({
     ],
   );
   return (
-    <OpenGeniContext.Provider value={value}>
-      {children}
-      {contractMismatch ? <ApiContractMismatchScreen mismatch={contractMismatch} /> : null}
-    </OpenGeniContext.Provider>
+    <ErrorMessageContext.Provider value={formatError}>
+      <OpenGeniContext.Provider value={value}>
+        {children}
+        {contractMismatch ? <ApiContractMismatchScreen mismatch={contractMismatch} /> : null}
+      </OpenGeniContext.Provider>
+    </ErrorMessageContext.Provider>
   );
 }
 
@@ -329,7 +370,7 @@ function ApiContractMismatchScreen({ mismatch }: { mismatch: OpenGeniApiContract
       data-opengeni-api-contract-mismatch
     >
       <div className="w-full max-w-md rounded-xl border border-og-border bg-og-surface p-6 shadow-2xl">
-        <p className="text-og-menu font-semibold text-og-fg">OpenGeni updated</p>
+        <p className="text-og-menu font-semibold text-og-fg">Opengeni updated</p>
         <p className="mt-2 text-og-menu leading-6 text-og-muted">
           This tab cannot safely continue with the new server version. Reload it before sending or
           controlling work.
@@ -339,7 +380,7 @@ function ApiContractMismatchScreen({ mismatch }: { mismatch: OpenGeniApiContract
         </p>
         <button
           type="button"
-          className="mt-5 inline-flex h-9 items-center rounded-md bg-og-fg px-3 text-og-menu font-medium text-og-bg"
+          className="mt-5 inline-flex h-9 items-center rounded-md border border-og-primary-border bg-og-primary text-og-primary-fg hover:bg-og-primary-hover px-3 text-og-menu font-medium"
           onClick={() => window.location.reload()}
         >
           Reload now