@opengeni/react 3.3.2 → 3.4.0

package/src/lib/provider-recovery.ts

@@ -0,0 +1,243 @@
+import type { SessionEvent, SessionStatus } from "@opengeni/sdk";
+
+/**
+ * Finite same-turn provider recovery, projected for people. Presentation only:
+ * the worker owns retry authority, pacing and the recovery budget. The worker
+ * (`apps/worker/src/activities/agent-turn/provider-recovery-copy.ts`) writes
+ * the same exhausted sentence into `turn.failed.error`; keep the two in step.
+ */
+export type ProviderRecoveryCondition =
+  | "overloaded"
+  | "unavailable"
+  | "unresponsive"
+  | "rate_limited";
+
+export type ProviderRecoveryFacts = {
+  /** Recorded worker failure code (`provider_unavailable`, `mcp_transport_timeout`, ...). */
+  code: string;
+  condition: ProviderRecoveryCondition | null;
+  /** Display label of the affected model, when the route was recorded. */
+  modelLabel: string | null;
+  /** Display label of the serving provider, when the route was recorded. */
+  providerLabel: string | null;
+  /** Automatic retries scheduled (live) or spent (exhausted). */
+  attempt: number | null;
+  /** Finite automatic retry budget. */
+  maxAttempts: number | null;
+  /** True when the model route itself is affected, so another model may help. */
+  modelRoute: boolean;
+  /** True while the turn waits for its sandbox to be saved and replaced. It
+   * has no retry budget: it resumes as soon as the successor box is ready. */
+  sandboxWait?: boolean;
+  /** Recorded lifecycle fence of a sandbox wait (`capture_in_progress`,
+   * `rotation_in_progress`, `provider_recovery_in_progress`), when known. */
+  sandboxTransition?: string | null;
+};
+
+const MODEL_CODES: ReadonlySet<string> = new Set([
+  "provider_unavailable",
+  "provider_rate_limited",
+  "provider_unknown_finish_reason",
+  "post_compaction_continuation_empty",
+]);
+
+/** A recovering turn parked behind a sandbox lifecycle transition (worker
+ * `failure-settlement.ts`). Before, this showed only "Recovering" with no
+ * reason. A superseded lease
+ * counts only when the worker recorded the pending transition it waits for. */
+const SANDBOX_WAIT_CODES: ReadonlySet<string> = new Set([
+  "sandbox_deadline_rotation",
+  "sandbox_lifecycle_transition",
+  "sandbox_lease_superseded",
+]);
+
+const RECOVERY_CODES: ReadonlySet<string> = new Set([
+  ...MODEL_CODES,
+  ...SANDBOX_WAIT_CODES,
+  "upstream_connectivity_unavailable",
+  "mcp_transport_timeout",
+  "mcp_transport_unavailable",
+  "sandbox_command_start_unavailable",
+  "retained_attachment_unavailable",
+  "turn_execution_policy_definition_mismatch",
+]);
+
+/** Matches the worker's default budget for legacy events that omit it. */
+const DEFAULT_MAX_ATTEMPTS = 5;
+
+function text(value: unknown, max = 120): string | null {
+  if (typeof value !== "string") return null;
+  const normalized = value.replace(/\s+/g, " ").trim();
+  return normalized ? normalized.slice(0, max) : null;
+}
+
+function count(value: unknown): number | null {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : null;
+}
+
+function condition(
+  payload: Record<string, unknown>,
+  code: string,
+): ProviderRecoveryCondition | null {
+  const recorded = payload.providerCondition;
+  if (
+    recorded === "overloaded" ||
+    recorded === "unavailable" ||
+    recorded === "unresponsive" ||
+    recorded === "rate_limited"
+  )
+    return recorded;
+  if (code === "provider_rate_limited") return "rate_limited";
+  if (code !== "provider_unavailable") return null;
+  // Older events predate the typed condition; their provider text still says so.
+  return [payload.lastRetryableError, payload.detail, payload.error].some(
+    (value) => typeof value === "string" && /\boverload(?:ed)?(?:_error)?\b/i.test(value),
+  )
+    ? "overloaded"
+    : null;
+}
+
+/**
+ * Read a retryable `turn.recovery.requested` payload or an exhausted
+ * `turn.failed` payload. Returns null for every other recovery reason (human
+ * Retry, worker shutdown, credential rotation, capacity waits, ...).
+ */
+export function parseProviderRecovery(payload: unknown): ProviderRecoveryFacts | null {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return null;
+  const record = payload as Record<string, unknown>;
+  const code = text(record.code) ?? text(record.reason);
+  if (!code || !RECOVERY_CODES.has(code)) return null;
+  const rotation = text(record.rotationReason);
+  const transition = text(record.transitionReason);
+  if (code === "sandbox_lease_superseded" && !rotation && !transition) return null;
+  // A live recovery request is retryable; a spent budget is explicitly marked.
+  if (record.recoveryExhausted !== true && record.retryable === false) return null;
+  const attempt = count(record.providerRecoveryCount);
+  return {
+    code,
+    condition: condition(record, code),
+    modelLabel: text(record.modelLabel),
+    providerLabel: text(record.providerLabel),
+    attempt,
+    maxAttempts: count(record.maxProviderRecoveryCount) ?? DEFAULT_MAX_ATTEMPTS,
+    modelRoute: MODEL_CODES.has(code),
+    ...(SANDBOX_WAIT_CODES.has(code)
+      ? {
+          sandboxWait: true,
+          sandboxTransition: transition ?? (rotation ? "rotation_in_progress" : null),
+        }
+      : {}),
+  };
+}
+
+/** One present-tense clause naming what is unavailable, without a trailing period. */
+export function providerRecoverySubject(facts: ProviderRecoveryFacts): string {
+  const model = facts.modelLabel ?? "The model";
+  const at = facts.providerLabel ? ` at the provider (${facts.providerLabel})` : " at the provider";
+  switch (facts.code) {
+    case "provider_rate_limited":
+      return `${model} is rate limited${at}`;
+    case "provider_unavailable":
+      return facts.condition === "overloaded"
+        ? `${model} is overloaded${at}`
+        : facts.condition === "unresponsive"
+          ? `${model} stopped responding${at}`
+          : `${model} is temporarily unavailable${at}`;
+    case "provider_unknown_finish_reason":
+      return `${model} ended its response unexpectedly`;
+    case "post_compaction_continuation_empty":
+      return `${model} stopped right after compacting the conversation`;
+    case "upstream_connectivity_unavailable":
+      return "Opengeni can't reach an upstream service";
+    case "mcp_transport_timeout":
+      return "A required MCP server isn't responding";
+    case "mcp_transport_unavailable":
+      return "A required MCP server is unreachable";
+    case "sandbox_command_start_unavailable":
+      return "The sandbox isn't ready yet";
+    case "retained_attachment_unavailable":
+      return "An image from earlier in this conversation can't be read from storage";
+    case "turn_execution_policy_definition_mismatch":
+      return "Opengeni is applying a configuration update";
+    case "sandbox_deadline_rotation":
+      return "The sandbox reached its maximum lifetime, so Opengeni is moving the workspace to a fresh sandbox";
+    case "sandbox_lifecycle_transition":
+    case "sandbox_lease_superseded":
+      return facts.sandboxTransition === "capture_in_progress"
+        ? "Opengeni is saving the sandbox workspace"
+        : facts.sandboxTransition === "provider_recovery_in_progress"
+          ? "Opengeni is recovering the sandbox"
+          : facts.sandboxTransition === "rotation_in_progress"
+            ? "Opengeni is moving the workspace to a fresh sandbox"
+            : "Opengeni is preparing the sandbox";
+    default:
+      return "A service this turn depends on is temporarily unavailable";
+  }
+}
+
+/** Live status while the same turn waits for its next automatic retry. */
+export function providerRecoveryRetryingText(facts: ProviderRecoveryFacts): string {
+  if (facts.sandboxWait) return `${providerRecoverySubject(facts)}…`;
+  const progress =
+    facts.attempt !== null && facts.maxAttempts !== null
+      ? ` (attempt ${Math.min(facts.attempt, facts.maxAttempts)} of ${facts.maxAttempts})`
+      : " automatically";
+  return `${providerRecoverySubject(facts)} — retrying${progress}…`;
+}
+
+/** Terminal sentence once the automatic budget is spent. */
+export function providerRecoveryExhaustedText(facts: ProviderRecoveryFacts): string {
+  const spent = facts.attempt ?? facts.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+  const retried = `Opengeni retried ${spent} ${spent === 1 ? "time" : "times"} without success.`;
+  const remedy = facts.modelRoute
+    ? "Try again in a few minutes, or switch to another model."
+    : "Try again in a few minutes.";
+  return `${providerRecoverySubject(facts)}. ${retried} ${remedy}`;
+}
+
+const BOUNDARY_TYPES: ReadonlySet<string> = new Set([
+  "turn.recovery.requested",
+  "turn.started",
+  "turn.completed",
+  "turn.failed",
+  "turn.cancelled",
+  "turn.superseded",
+]);
+
+/**
+ * The active turn's current automatic provider retry, or null. Only a
+ * `recovering`, unpaused session qualifies, and only the newest boundary of its
+ * exact active turn counts, so merged or replayed pages never borrow another
+ * turn's diagnosis.
+ */
+export function currentProviderRecovery(
+  session: {
+    id: string;
+    status: SessionStatus | null | undefined;
+    activeTurnId: string | null | undefined;
+    effectiveControl?: { state: string } | null | undefined;
+  },
+  events: readonly SessionEvent[],
+): ProviderRecoveryFacts | null {
+  if (
+    session.status !== "recovering" ||
+    (session.effectiveControl && session.effectiveControl.state !== "active") ||
+    !session.activeTurnId
+  )
+    return null;
+  let latest: SessionEvent | undefined;
+  for (const event of events) {
+    if (
+      event.sessionId !== session.id ||
+      event.turnId !== session.activeTurnId ||
+      event.duplicateOfEventId ||
+      (event.turnAssociation && event.turnAssociation !== "current") ||
+      !BOUNDARY_TYPES.has(event.type)
+    )
+      continue;
+    if (!latest || event.sequence > latest.sequence) latest = event;
+  }
+  if (latest?.type !== "turn.recovery.requested") return null;
+  const payload = latest.payload as Record<string, unknown> | null | undefined;
+  return payload?.recoveryExhausted === true ? null : parseProviderRecovery(payload);
+}

package/src/lib/scrollbars.ts

@@ -0,0 +1,30 @@
+/**
+ * Where a platform draws classic, always-visible scrollbars (Windows, and Linux
+ * or macOS when set to always show them), Chromium paints arrow buttons on the
+ * thin, colored scrollbars the stylesheet asks for with `scrollbar-width` and
+ * `scrollbar-color`. This marks such documents with
+ * `data-og-scrollbars="classic"` on <html> so the stylesheet can use a slim
+ * rounded thumb there instead. Overlay-scrollbar platforms keep their native
+ * scrollbars.
+ */
+export const CLASSIC_SCROLLBARS_ATTRIBUTE = "data-og-scrollbars";
+
+const marked = new WeakSet<Document>();
+
+export function markClassicScrollbars(doc: Document | undefined = globalThis.document): void {
+  if (!doc?.documentElement || marked.has(doc)) return;
+  marked.add(doc);
+  const root = doc.documentElement;
+  // Probe with the platform default: the page's own scrollbar styles must not
+  // decide what the platform draws.
+  root.removeAttribute(CLASSIC_SCROLLBARS_ATTRIBUTE);
+  const probe = doc.createElement("div");
+  probe.setAttribute("aria-hidden", "true");
+  probe.style.cssText =
+    "position:absolute;top:-9999px;left:-9999px;width:100px;height:100px;" +
+    "overflow:scroll;visibility:hidden;scrollbar-width:auto;scrollbar-color:auto";
+  root.append(probe);
+  const classic = probe.offsetWidth - probe.clientWidth > 0;
+  probe.remove();
+  if (classic) root.setAttribute(CLASSIC_SCROLLBARS_ATTRIBUTE, "classic");
+}

package/src/lib/terminal-input-readiness.ts

@@ -0,0 +1,51 @@
+/** Negotiated by the stock ttyd launcher, never inferred from ordinary output.
+ * The Bash Readline adapter emits this OSC only at its first input boundary.
+ * It is metadata (ignored by older xterm clients), not a prompt string. */
+export const TERMINAL_INPUT_READY_PREFERENCE = "opengeniInputReady";
+export const TERMINAL_INPUT_READY_PROTOCOL = "bash-readline-v1";
+const PREFIX = "\x1b]777;opengeni-input;";
+const FRAME = /^\x1b\]777;opengeni-input;(hello|ready);([a-f0-9]{32})\x07$/;
+const MAX_FRAME = PREFIX.length + "hello;".length + 32 + 1;
+
+/** One decoder per WebSocket/PTY generation. Retains at most a partial marker,
+ * rather than buffering terminal output while the shell initializes. */
+export function terminalInputReadyDecoder() {
+  let pending = "";
+  let received = false;
+  let identity: string | null = null;
+  return (data: string): { output: string; ready: boolean } => {
+    let input = pending + data;
+    let output = "";
+    let ready = false;
+    pending = "";
+    while (input.length > 0) {
+      const marker = input.indexOf(PREFIX);
+      if (marker < 0) break;
+      output += input.slice(0, marker);
+      input = input.slice(marker);
+      const end = input.indexOf("\x07", PREFIX.length);
+      if (end < 0 && input.length < MAX_FRAME) {
+        pending = input;
+        return { output, ready };
+      }
+      const match = end >= 0 && end < MAX_FRAME ? FRAME.exec(input.slice(0, end + 1)) : null;
+      if (!match) {
+        // Malformed/overlong metadata is ordinary output, never an unbounded
+        // parser buffer or permission to deliver input.
+        output += input[0];
+        input = input.slice(1);
+        continue;
+      }
+      input = input.slice(end + 1);
+      if (match[1] === "hello" && identity === null) identity = match[2]!;
+      if (match[1] === "ready" && match[2] === identity && !received) {
+        ready = true;
+        received = true;
+      }
+    }
+    let suffix = Math.min(input.length, PREFIX.length - 1);
+    while (suffix > 0 && !PREFIX.startsWith(input.slice(-suffix))) suffix--;
+    pending = suffix > 0 ? input.slice(-suffix) : "";
+    return { output: output + (suffix > 0 ? input.slice(0, -suffix) : input), ready };
+  };
+}

package/src/lib/transient-retry.ts

@@ -0,0 +1,99 @@
+import { OpenGeniApiError } from "@opengeni/sdk";
+
+/*
+ * A deploy, failover or database restart makes the API answer 502/503/504 (or a
+ * retryable 500) for a few seconds, or drops the connection outright. Reads
+ * behind the new-chat composer retry those quietly before anything is shown;
+ * the person keeps typing and never sees a raw "service unavailable" line.
+ */
+
+/** Backoff between attempts: about ten seconds in all before anything is shown. */
+export const TRANSIENT_RETRY_DELAYS_MS: readonly number[] = [1_000, 2_000, 3_000, 4_000];
+
+/** After the quiet retries give up, try once at this pace until Opengeni answers. */
+export const TRANSIENT_RECONNECT_INTERVAL_MS = 3_000;
+
+/** The one line shown while Opengeni is briefly unreachable. */
+export const OPENGENI_UPDATING_NOTICE = "Opengeni is updating. We'll reconnect automatically.";
+
+const NETWORK_FAILURE =
+  /failed to fetch|fetch failed|networkerror|load failed|network request failed/iu;
+
+/**
+ * True for a failure that says the service is briefly unreachable, not that
+ * the request was wrong: a gateway or availability status, a 500 the API marks
+ * retryable, or a request that never got a response.
+ */
+export function isTransientServiceFailure(error: unknown): boolean {
+  if (isAbort(error)) return false;
+  if (error instanceof OpenGeniApiError) {
+    if (error.status === 502 || error.status === 503 || error.status === 504) return true;
+    if (error.status === 500) return error.retryable;
+    // The SDK reports a mutation whose response never arrived as status 0.
+    return error.status === 0 && error.code === "network_error";
+  }
+  return error instanceof TypeError && NETWORK_FAILURE.test(error.message);
+}
+
+export type RetryTransientOptions = {
+  /** Stop waiting (and rethrow the last failure) once this returns false. */
+  shouldContinue?: () => boolean;
+  signal?: AbortSignal;
+  delaysMs?: readonly number[];
+  sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+};
+
+/**
+ * Run a read, retrying only transient service failures with backoff. Never use
+ * this for a request whose repeat could apply twice: it is for reads and for
+ * writes that are idempotent by construction.
+ */
+export async function retryTransient<T>(
+  operation: () => Promise<T>,
+  options: RetryTransientOptions = {},
+): Promise<T> {
+  const delays = options.delaysMs ?? TRANSIENT_RETRY_DELAYS_MS;
+  const sleep = options.sleep ?? abortableSleep;
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      return await operation();
+    } catch (error) {
+      const delay = delays[attempt];
+      if (
+        delay === undefined ||
+        !isTransientServiceFailure(error) ||
+        options.signal?.aborted ||
+        options.shouldContinue?.() === false
+      ) {
+        throw error;
+      }
+      await sleep(delay, options.signal);
+      if (options.signal?.aborted || options.shouldContinue?.() === false) throw error;
+    }
+  }
+}
+
+function abortableSleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    if (signal?.aborted) {
+      resolve();
+      return;
+    }
+    const done = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", done);
+      resolve();
+    };
+    const timer = setTimeout(done, ms);
+    signal?.addEventListener("abort", done, { once: true });
+  });
+}
+
+function isAbort(error: unknown): boolean {
+  return (
+    (typeof DOMException !== "undefined" &&
+      error instanceof DOMException &&
+      error.name === "AbortError") ||
+    (error instanceof Error && error.name === "AbortError")
+  );
+}

package/src/lib/workbench-peers.ts

@@ -0,0 +1,62 @@
+import type { DesktopRfbFactory } from "@opengeni/sdk";
+
+/** Host-owned imports keep optional peers outside the root's bundler graph. */
+export type WorkbenchPeerLoader<T = unknown> = () => Promise<T>;
+export type CodeEditorLanguage = "javascript" | "json" | "python" | "markdown" | "css" | "html";
+export type CodeEditorLanguages = Partial<Record<CodeEditorLanguage, WorkbenchPeerLoader>>;
+export type CodeEditorPeers = { module: unknown; languages?: CodeEditorLanguages | undefined };
+export type SandboxTerminalPeers = {
+  Terminal: unknown;
+  FitAddon: unknown;
+  WebLinksAddon: unknown;
+  loadWebgl?: WorkbenchPeerLoader | undefined;
+};
+
+function optionalPeer<T>(setup: string) {
+  let loader: WorkbenchPeerLoader<T> | null = null;
+  let loaded: Promise<T> | null = null;
+  let version = 0;
+  const listeners = new Set<() => void>();
+  return {
+    register(next: WorkbenchPeerLoader<T> | null): void {
+      if (next === loader) return;
+      loader = next;
+      loaded = null;
+      version += 1;
+      for (const listener of listeners) listener();
+    },
+    revision: () => version,
+    subscribe(listener: () => void): () => void {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    load(): Promise<T> {
+      if (!loader) return Promise.reject(new Error(`Call ${setup} to enable this surface`));
+      if (!loaded) {
+        // A synchronous host-loader failure is also a rejected, retryable load.
+        const pending = Promise.resolve()
+          .then(loader)
+          .catch((error: unknown) => {
+            if (loaded === pending) loaded = null;
+            throw error;
+          });
+        loaded = pending;
+      }
+      return loaded;
+    },
+  };
+}
+
+export const sandboxTerminalPeers = optionalPeer<SandboxTerminalPeers>(
+  "enableSandboxTerminal() from @opengeni/react/terminal",
+);
+export const codeEditorPeers = optionalPeer<CodeEditorPeers>(
+  "enableCodeEditor() from @opengeni/react/editor",
+);
+export const desktopViewerPeers = optionalPeer<DesktopRfbFactory>(
+  "enableDesktopViewer() from @opengeni/react/desktop",
+);
+
+export const registerSandboxTerminal = sandboxTerminalPeers.register;
+export const registerCodeEditor = codeEditorPeers.register;
+export const registerDesktopViewer = desktopViewerPeers.register;

package/src/lib/xterm-theme.ts

@@ -24,11 +24,13 @@ export type TokenReader = (name: string) => string | undefined;
  * The 16 ANSI colors + selection/cursor treatment, designed against the og
  * OKLCH palette. Hues are borrowed from the og status ramp so terminal color
  * reads as part of the same system: red≈status-failed(22), green≈status-idle
- * (155), yellow≈status-running(80), blue≈accent(255), magenta≈status-waiting
- * (305), cyan≈200. Dark uses lifted lightness on the dark slate ground; light
- * uses deeper, more saturated inks on the near-white ground. Bright variants
- * add lightness + a touch of chroma. `black`/`white` are neutral slate ramp
- * stops (never pure #000/#fff — that clashes with the calm neutral ground).
+ * (155), yellow≈status-running(80), magenta(305), cyan≈200. The ANSI blue and
+ * magenta slots stay chromatic because program output means them; the app
+ * chrome around the terminal is neutral. Dark uses lifted lightness on the
+ * dark neutral ground; light uses deeper, more saturated inks on the
+ * near-white ground. Bright variants add lightness + a touch of chroma.
+ * `black`/`white` and the selection are neutral grey ramp stops (never pure
+ * #000/#fff — that clashes with the calm neutral ground).
  */
 export type AnsiPalette = {
   black: string;
@@ -54,47 +56,47 @@ export type AnsiPalette = {
 };
 
 const DARK_ANSI: AnsiPalette = {
-  black: "oklch(0.3 0.014 260)",
+  black: "oklch(0.3 0 0)",
   red: "oklch(0.68 0.17 22)",
   green: "oklch(0.75 0.13 155)",
   yellow: "oklch(0.8 0.11 80)",
   blue: "oklch(0.7 0.14 255)",
   magenta: "oklch(0.72 0.13 305)",
   cyan: "oklch(0.75 0.1 210)",
-  white: "oklch(0.8 0.01 260)",
-  brightBlack: "oklch(0.45 0.014 260)",
+  white: "oklch(0.8 0 0)",
+  brightBlack: "oklch(0.45 0 0)",
   brightRed: "oklch(0.76 0.17 22)",
   brightGreen: "oklch(0.82 0.14 155)",
   brightYellow: "oklch(0.86 0.12 85)",
   brightBlue: "oklch(0.78 0.13 255)",
   brightMagenta: "oklch(0.8 0.13 305)",
   brightCyan: "oklch(0.83 0.1 200)",
-  brightWhite: "oklch(0.97 0.005 260)",
-  selectionBackground: "oklch(0.72 0.15 255 / 0.34)",
-  selectionForeground: "oklch(0.985 0.005 260)",
-  selectionInactiveBackground: "oklch(0.72 0.02 260 / 0.22)",
+  brightWhite: "oklch(0.97 0 0)",
+  selectionBackground: "oklch(0.8 0 0 / 0.3)",
+  selectionForeground: "oklch(0.985 0 0)",
+  selectionInactiveBackground: "oklch(0.72 0 0 / 0.2)",
 };
 
 const LIGHT_ANSI: AnsiPalette = {
-  black: "oklch(0.35 0.015 260)",
+  black: "oklch(0.35 0 0)",
   red: "oklch(0.52 0.19 22)",
   green: "oklch(0.5 0.13 155)",
   yellow: "oklch(0.56 0.13 80)",
   blue: "oklch(0.52 0.18 255)",
   magenta: "oklch(0.52 0.16 305)",
   cyan: "oklch(0.52 0.1 210)",
-  white: "oklch(0.7 0.01 260)",
-  brightBlack: "oklch(0.5 0.014 260)",
+  white: "oklch(0.7 0 0)",
+  brightBlack: "oklch(0.5 0 0)",
   brightRed: "oklch(0.55 0.2 22)",
   brightGreen: "oklch(0.54 0.14 155)",
   brightYellow: "oklch(0.6 0.14 80)",
   brightBlue: "oklch(0.48 0.19 255)",
   brightMagenta: "oklch(0.54 0.17 305)",
   brightCyan: "oklch(0.54 0.11 210)",
-  brightWhite: "oklch(0.3 0.015 260)",
-  selectionBackground: "oklch(0.55 0.18 255 / 0.24)",
-  selectionForeground: "oklch(0.21 0.015 260)",
-  selectionInactiveBackground: "oklch(0.6 0.02 260 / 0.16)",
+  brightWhite: "oklch(0.3 0 0)",
+  selectionBackground: "oklch(0.45 0 0 / 0.2)",
+  selectionForeground: "oklch(0.21 0 0)",
+  selectionInactiveBackground: "oklch(0.6 0 0 / 0.14)",
 };
 
 /** The designed ANSI-16 palette for a theme mode. Pure. */
@@ -110,8 +112,8 @@ export function ogAnsiPalette(mode: ThemeMode): AnsiPalette {
  */
 export function buildXtermTheme(read: TokenReader, mode: ThemeMode): XtermTheme {
   const ansi = ogAnsiPalette(mode);
-  const bgFallback = mode === "light" ? "oklch(0.978 0.003 260)" : "oklch(0.155 0.012 260)";
-  const fgFallback = mode === "light" ? "oklch(0.21 0.015 260)" : "oklch(0.955 0.005 260)";
+  const bgFallback = mode === "light" ? "#ffffff" : "#202020";
+  const fgFallback = mode === "light" ? "#242424" : "#e6e6e6";
   const bg = read("--og-color-bg") ?? bgFallback;
   const fg = read("--og-color-fg") ?? fgFallback;
   const accent = read("--og-color-accent") ?? ansi.brightBlue;

package/src/mcp-connection-status.ts

@@ -0,0 +1,35 @@
+import type { CapabilityCatalogItem, ConnectionMetadata } from "@opengeni/sdk";
+
+/** Status only; runtime use is authorized for the authenticated initiating user. */
+export function matchingActiveMcpConnections(
+  item: CapabilityCatalogItem,
+  connections: ConnectionMetadata[],
+) {
+  return matchingMcpConnections(item, connections).filter((entry) => entry.status === "active");
+}
+
+function matchingMcpConnections(item: CapabilityCatalogItem, connections: ConnectionMetadata[]) {
+  const ref = item.connectionRef;
+  if (!item.enabled || !ref) return [];
+  return connections.filter(
+    (entry) =>
+      entry.status !== "revoked" &&
+      entry.kind === "oauth2" &&
+      entry.metadata.mcpUrl === (item.mcpUrl ?? item.endpointUrl) &&
+      (ref.subjectScope !== "subject"
+        ? entry.id === ref.connectionId && entry.subjectId === null
+        : entry.subjectId !== null),
+  );
+}
+
+/** Installation availability is not account readiness. Revoked history is not actionable. */
+export function mcpConnectionDiscoveryState(
+  item: CapabilityCatalogItem,
+  connections: ConnectionMetadata[],
+) {
+  const matching = matchingMcpConnections(item, connections);
+  const active = matching.filter((entry) => entry.status === "active");
+  if (active.length === 1) return { status: "added", label: "Connected" } as const;
+  if (matching.length > 0) return { status: "attention", label: "Review connection" } as const;
+  return { status: "available", label: "Connect" } as const;
+}