@opengeni/react 0.20.0 → 0.25.0

package/src/timeline/fleet-decision-row.tsx

@@ -0,0 +1,412 @@
+import type { FleetDecisionItem } from "./types";
+
+type RowJsx = typeof import("react/jsx-runtime").jsx;
+type RowJsxs = typeof import("react/jsx-runtime").jsxs;
+
+function GaugeMark({ className, j, s }: { className: string; j: RowJsx; s: RowJsxs }) {
+  return s("svg", {
+    "aria-hidden": "true",
+    className,
+    fill: "none",
+    height: "24",
+    stroke: "currentColor",
+    strokeLinecap: "round",
+    strokeLinejoin: "round",
+    strokeWidth: "2",
+    viewBox: "0 0 24 24",
+    width: "24",
+    children: [
+      j("path", { d: "m 12 14 4-4" }, "needle"),
+      j("path", { d: "M3.34 19a10 10 0 1 1 17.32 0" }, "arc"),
+    ],
+  });
+}
+
+const FLEET_ACTUAL_REASON_LABEL: Record<FleetDecisionItem["actualReason"], string> = {
+  lease_reused: "Reused the fenced lease",
+  pin: "Kept the session pin",
+  rotation: "Rotated for capacity",
+  active: "Used the active subscription",
+  all_capped: "All observed subscriptions were capped",
+  none: "No production candidate was selected",
+};
+
+const FLEET_SHADOW_REASON_LABEL: Record<FleetDecisionItem["shadowReason"], string> = {
+  fenced_in_flight: "Kept the fenced in-flight assignment",
+  fenced_candidate_missing: "The fenced assignment was missing from the snapshot",
+  admission_paced: "Admission would have been paced",
+  no_eligible_candidate: "No candidate passed the policy checks",
+  overlay_isolated_empty: "Explicit isolation left no eligible candidate",
+  best_score: "Selected the lowest-pressure candidate",
+  affinity_best: "Session affinity was already best",
+  hysteresis_hold: "Hysteresis avoided a low-value switch",
+};
+
+const FLEET_COMPARISON_LABEL: Record<FleetDecisionItem["comparison"], string> = {
+  match: "Production and shadow matched",
+  different_candidate: "Shadow preferred another candidate",
+  different_outcome: "Production and shadow outcomes differed",
+  not_comparable_truncated: "Comparison limited by bounded candidate data",
+};
+
+const FLEET_ADMISSION_REASON_LABEL: Record<FleetDecisionItem["admissionReason"], string> = {
+  fenced_in_flight: "In-flight assignment was fenced",
+  pacing_disabled: "Admission pacing was disabled",
+  capacity_unknown: "Capacity was unknown, so work remained admissible",
+  capacity_available: "Observed capacity was available",
+  work_conserving_borrow: "Idle capacity was borrowed for standard work",
+  manager_priority: "Standard work was paced for queued manager demand",
+  standard_starvation_bound: "The standard-work starvation bound was reached",
+  capacity_saturated: "Observed dynamic capacity was saturated",
+  emergency_fuse: "The emergency fuse blocked new work",
+};
+
+const FLEET_REJECTION_LABEL: Record<
+  Exclude<FleetDecisionItem["scores"][number]["rejectionReason"], null>,
+  string
+> = {
+  allocator_disabled: "Allocator disabled",
+  unavailable: "Unavailable",
+  cooling: "Cooling down",
+  quota_ceiling: "Quota ceiling reached",
+  overlay_isolation: "Outside explicit isolation",
+};
+
+const FLEET_CONFIDENCE_LABEL: Record<FleetDecisionItem["confidence"], string> = {
+  unknown: "Unknown confidence",
+  low: "Low confidence",
+  medium: "Medium confidence",
+  high: "High confidence",
+};
+
+export default function FleetDecisionRow({
+  item,
+  d: ActivityDisclosure,
+  b: BodyNote,
+  j,
+  s,
+}: {
+  item: FleetDecisionItem;
+  d: typeof import("./shared").ActivityDisclosure;
+  b: typeof import("./shared").BodyNote;
+  j: RowJsx;
+  s: RowJsxs;
+}) {
+  const scoreRowsHidden = item.scoreRowsTruncatedCount > 0;
+  const scores =
+    item.scores.length > 0
+      ? j(
+          "div",
+          {
+            className: "min-w-0",
+            children: [
+              j(
+                "h4",
+                {
+                  className: "text-og-sm font-medium text-og-fg",
+                  children: "Bounded candidate scores",
+                },
+                "heading",
+              ),
+              j(
+                "p",
+                {
+                  className: "mt-0.5 text-og-xs leading-5 text-og-fg-subtle",
+                  children:
+                    "Lower scores rank first. Candidate aliases are temporary and local to this event.",
+                },
+                "description",
+              ),
+              j(
+                "ul",
+                {
+                  className: "mt-2 flex min-w-0 flex-col gap-1.5",
+                  "aria-label": "Candidate scores",
+                  children: item.scores.map((score) =>
+                    s(
+                      "li",
+                      {
+                        className:
+                          "flex min-w-0 flex-col gap-1 rounded-og-sm bg-og-surface-1 px-2.5 py-2 text-og-sm sm:flex-row sm:items-center sm:gap-3",
+                        children: [
+                          j(
+                            "span",
+                            {
+                              className: "font-og-mono text-og-fg",
+                              children: score.candidateKey,
+                            },
+                            "candidate",
+                          ),
+                          j(
+                            "span",
+                            {
+                              className: "min-w-0 text-og-fg-muted sm:flex-1",
+                              children: score.eligible
+                                ? "Eligible"
+                                : score.rejectionReason
+                                  ? FLEET_REJECTION_LABEL[score.rejectionReason]
+                                  : "Unavailable",
+                            },
+                            "eligibility",
+                          ),
+                          s(
+                            "span",
+                            {
+                              className: "font-og-mono text-og-fg-subtle",
+                              children: [
+                                "score ",
+                                formatFleetScore(score.total),
+                                " ·",
+                                " ",
+                                FLEET_CONFIDENCE_LABEL[score.confidence],
+                              ],
+                            },
+                            "score",
+                          ),
+                        ],
+                      },
+                      score.candidateKey,
+                    ),
+                  ),
+                },
+                "rows",
+              ),
+            ],
+          },
+          "score-list",
+        )
+      : null;
+  const truncated =
+    item.truncatedCandidateCount > 0
+      ? j(
+          BodyNote,
+          {
+            tone: "muted",
+            children: [
+              item.truncatedCandidateCount,
+              " additional ",
+              item.truncatedCandidateCount === 1 ? "candidate was" : "candidates were",
+              " excluded from this bounded replay record.",
+            ],
+          },
+          "truncated",
+        )
+      : null;
+  const hidden = scoreRowsHidden
+    ? j(
+        BodyNote,
+        {
+          tone: "muted",
+          children: [
+            item.scoreRowsTruncatedCount,
+            " additional ",
+            item.scoreRowsTruncatedCount === 1 ? "score row was" : "score rows were",
+            " hidden by this view’s safety limit.",
+          ],
+        },
+        "hidden",
+      )
+    : null;
+  return j(ActivityDisclosure, {
+    icon: j(GaugeMark, { className: "size-3.5", j, s }),
+    iconTone: "muted",
+    title: "Fleet policy shadow",
+    preview: FLEET_COMPARISON_LABEL[item.comparison],
+    chip: {
+      tone: "muted",
+      text:
+        item.comparison === "match"
+          ? "matched"
+          : item.comparison === "not_comparable_truncated"
+            ? "limited"
+            : "different",
+    },
+    children: s("section", {
+      "aria-label": "Fleet policy shadow details",
+      className: "flex min-w-0 flex-col gap-3",
+      children: [
+        j(
+          BodyNote,
+          {
+            tone: "muted",
+            children:
+              "Shadow observation only — it did not change the subscription serving this turn.",
+          },
+          "observation",
+        ),
+        j(
+          "dl",
+          {
+            className: "grid min-w-0 grid-cols-1 gap-x-5 gap-y-3 sm:grid-cols-2",
+            children: [
+              j(
+                FleetDetail,
+                {
+                  term: "Production",
+                  value: fleetOutcomeLabel(item.actualOutcome, item.actualCandidateKey),
+                  note: FLEET_ACTUAL_REASON_LABEL[item.actualReason],
+                  j,
+                  s,
+                },
+                "production",
+              ),
+              j(
+                FleetDetail,
+                {
+                  term: "Shadow policy",
+                  value: fleetOutcomeLabel(item.shadowOutcome, item.shadowCandidateKey),
+                  note: FLEET_SHADOW_REASON_LABEL[item.shadowReason],
+                  j,
+                  s,
+                },
+                "shadow",
+              ),
+              j(
+                FleetDetail,
+                {
+                  term: "Comparison",
+                  value: FLEET_COMPARISON_LABEL[item.comparison],
+                  j,
+                  s,
+                },
+                "comparison",
+              ),
+              j(
+                FleetDetail,
+                {
+                  term: "Decision confidence",
+                  value: FLEET_CONFIDENCE_LABEL[item.confidence],
+                  j,
+                  s,
+                },
+                "confidence",
+              ),
+              j(
+                FleetDetail,
+                {
+                  term: "Admission",
+                  value:
+                    item.admissionOutcome === "admit"
+                      ? "Would admit new work"
+                      : "Would pace new work",
+                  note: FLEET_ADMISSION_REASON_LABEL[item.admissionReason],
+                  j,
+                  s,
+                },
+                "admission",
+              ),
+              j(
+                FleetDetail,
+                {
+                  term: "Observed candidates",
+                  value: `${item.candidateCount} in the bounded replay`,
+                  j,
+                  s,
+                },
+                "candidate-count",
+              ),
+              j(
+                FleetDetail,
+                {
+                  term: "Idle-capacity borrowing",
+                  value: item.borrowedIdleCapacity ? "Borrowed for standard work" : "Not borrowed",
+                  j,
+                  s,
+                },
+                "idle-capacity",
+              ),
+              j(
+                FleetDetail,
+                {
+                  term: "Named-policy borrowing",
+                  value: item.borrowedOverlayCapacity
+                    ? "Borrowed outside the preferred group"
+                    : "Not borrowed",
+                  j,
+                  s,
+                },
+                "named-policy",
+              ),
+              j(
+                FleetDetail,
+                {
+                  term: "Stranded capacity",
+                  value:
+                    item.strandedEligibleCount === 0
+                      ? "None"
+                      : `${item.strandedEligibleCount} eligible ${item.strandedEligibleCount === 1 ? "candidate" : "candidates"}`,
+                  note:
+                    item.strandedEligibleCount > 0
+                      ? "Capacity excluded by explicit isolation; existing fenced turns are unchanged."
+                      : undefined,
+                  j,
+                  s,
+                },
+                "stranded-capacity",
+              ),
+            ],
+          },
+          "details",
+        ),
+        scores,
+        truncated,
+        hidden,
+      ],
+    }),
+  });
+}
+
+function FleetDetail({
+  term,
+  value,
+  note,
+  j,
+  s,
+}: {
+  term: string;
+  value: string;
+  note?: string | undefined;
+  j: RowJsx;
+  s: RowJsxs;
+}) {
+  return j("div", {
+    className: "min-w-0",
+    children: [
+      j(
+        "dt",
+        {
+          className: "text-og-xs font-medium uppercase tracking-wide text-og-fg-subtle",
+          children: term,
+        },
+        "term",
+      ),
+      s(
+        "dd",
+        {
+          className: "mt-0.5 break-words text-og-sm text-og-fg-muted",
+          children: [
+            j("span", { className: "text-og-fg", children: value }, "value"),
+            note
+              ? j("span", { className: "mt-0.5 block leading-5", children: note }, "note")
+              : null,
+          ],
+        },
+        "description",
+      ),
+    ],
+  });
+}
+
+function fleetOutcomeLabel(
+  outcome: FleetDecisionItem["actualOutcome"] | FleetDecisionItem["shadowOutcome"],
+  candidateKey: string | null,
+): string {
+  if (outcome === "selected" && candidateKey) return `Selected ${candidateKey}`;
+  if (outcome === "waiting") return "Waiting for capacity";
+  if (outcome === "paced") return "Paced before placement";
+  return "No candidate selected";
+}
+
+function formatFleetScore(value: number): string {
+  return new Intl.NumberFormat("en-US", { maximumFractionDigits: 2 }).format(value);
+}

package/src/timeline/index.ts

@@ -30,6 +30,8 @@ export type {
   ActivityItem,
   AgentMessageItem,
   AuthNeededItem,
+  FleetDecisionItem,
+  FleetDecisionScoreItem,
   GoalItem,
   MemoryItem,
   NoticeItem,

package/src/timeline/projection.ts

@@ -1,4 +1,5 @@
 import type { SessionEvent, SessionStatus } from "@opengeni/sdk";
+const { default: fleetDecisionItem } = await import("./fleet-decision-projection");
 import {
   CREDIT_EXHAUSTION_MESSAGE,
   humanizeFailureReason,
@@ -19,6 +20,12 @@ import type {
   ToolCallItem,
   WorkerItem,
 } from "./types";
+/** Readable label for a tool call, without leaking an MCP server prefix. */
+export function toolDisplayName(name: string): string {
+  const boundary = name.indexOf("__");
+  const toolPart = boundary >= 0 ? name.slice(boundary + 2) : name;
+  return toolPart.replace(/[_-]+/g, " ").trim();
+}
 
 /* ----------------------------------------------------------------------------
    Timeline projection
@@ -554,6 +561,15 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
         break;
       }
 
+      case "codex.fleet.decision": {
+        const decision = fleetDecisionItem(event, payload);
+        if (decision) {
+          closeStreamingTail();
+          items.push(decision);
+        }
+        break;
+      }
+
       case "goal.set":
       case "goal.updated":
       case "goal.completed":
@@ -643,6 +659,7 @@ function isActivityItem(item: TimelineItem): item is ActivityItem {
     case "worker":
     case "sandbox":
     case "memory":
+    case "fleet-decision":
       return true;
     default:
       return false;
@@ -822,7 +839,8 @@ function isTurnExecutionEvidence(type: string): boolean {
     type === "credential.auth_needed" ||
     type.startsWith("rig.setup.") ||
     type === "codex.capacity.waiting" ||
-    type === "codex.capacity.resumed"
+    type === "codex.capacity.resumed" ||
+    type === "codex.fleet.decision"
   );
 }
 
@@ -1307,10 +1325,3 @@ function looksLikeId(value: string): boolean {
  * just the tool ("list organizations"). Names without the `__` boundary (plain
  * built-ins like "session_create") are unaffected.
  */
-export function toolDisplayName(name: string): string {
-  // The prefix is a single LEFT boundary (`registryId__toolName`), so split on
-  // the FIRST `__` — the tool name itself may contain `__` and must survive whole.
-  const boundary = name.indexOf("__");
-  const toolPart = boundary >= 0 ? name.slice(boundary + 2) : name;
-  return toolPart.replace(/[_-]+/g, " ").trim();
-}

package/src/timeline/tool-display-name.ts

@@ -0,0 +1,16 @@
+/**
+ * Readable label for a tool call ("session_create" -> "session create").
+ *
+ * MCP tools are namespaced `<serverId>__<toolName>` (see prefixedMcpToolName),
+ * and for catalog-imported servers that serverId is an opaque slug+hash.
+ * De-slugging the whole thing leaked that id into the timeline; strip the
+ * server prefix and show just the tool. Names without the `__` boundary (plain
+ * built-ins like "session_create") are unaffected.
+ */
+export function toolDisplayName(name: string): string {
+  // The prefix is a single LEFT boundary (`registryId__toolName`), so split on
+  // the FIRST `__` — the tool name itself may contain `__` and must survive whole.
+  const boundary = name.indexOf("__");
+  const toolPart = boundary >= 0 ? name.slice(boundary + 2) : name;
+  return toolPart.replace(/[_-]+/g, " ").trim();
+}

package/src/timeline/tool-renderers.tsx

@@ -52,7 +52,7 @@ import {
   type DisclosureChip,
 } from "./shared";
 import { RawPatch, ToolDiff } from "./tool-diff";
-import { toolDisplayName } from "./projection";
+import { toolDisplayName } from "./tool-display-name";
 
 /* ----------------------------------------------------------------------------
    Per-tool renderers

package/src/timeline/types.ts

@@ -1,4 +1,4 @@
-import type { ResourceRef, SessionStatus, ToolRef } from "@opengeni/sdk";
+import type { ResourceRef, SessionStatus, ToolAuthNeededPayload, ToolRef } from "@opengeni/sdk";
 
 /* ----------------------------------------------------------------------------
    Timeline item types
@@ -140,6 +140,66 @@ export type MemoryItem = {
   occurredAt: string;
 };
 
+export type FleetDecisionScoreItem = {
+  candidateKey: string;
+  eligible: boolean;
+  rejectionReason:
+    | "allocator_disabled"
+    | "unavailable"
+    | "cooling"
+    | "quota_ceiling"
+    | "overlay_isolation"
+    | null;
+  total: number;
+  confidence: "unknown" | "low" | "medium" | "high";
+};
+
+/**
+ * One production-vs-shadow placement explanation. Candidate keys are
+ * event-local aliases only; no credential/account identity reaches this item.
+ */
+export type FleetDecisionItem = {
+  kind: "fleet-decision";
+  id: string;
+  turnId: string | null;
+  policyVersion: "adaptive-shadow-v1";
+  actualOutcome: "selected" | "waiting" | "none";
+  actualCandidateKey: string | null;
+  actualReason: "lease_reused" | "pin" | "rotation" | "active" | "all_capped" | "none";
+  shadowOutcome: "selected" | "paced" | "none";
+  shadowCandidateKey: string | null;
+  shadowReason:
+    | "fenced_in_flight"
+    | "fenced_candidate_missing"
+    | "admission_paced"
+    | "no_eligible_candidate"
+    | "overlay_isolated_empty"
+    | "best_score"
+    | "affinity_best"
+    | "hysteresis_hold";
+  comparison: "match" | "different_candidate" | "different_outcome" | "not_comparable_truncated";
+  confidence: "unknown" | "low" | "medium" | "high";
+  admissionOutcome: "admit" | "pace";
+  admissionReason:
+    | "fenced_in_flight"
+    | "pacing_disabled"
+    | "capacity_unknown"
+    | "capacity_available"
+    | "work_conserving_borrow"
+    | "manager_priority"
+    | "standard_starvation_bound"
+    | "capacity_saturated"
+    | "emergency_fuse";
+  borrowedIdleCapacity: boolean;
+  borrowedOverlayCapacity: boolean;
+  strandedEligibleCount: number;
+  candidateCount: number;
+  truncatedCandidateCount: number;
+  scoreRowsTruncatedCount: number;
+  scores: FleetDecisionScoreItem[];
+  occurredAt: string;
+};
+
 export type SessionStatusItem = {
   kind: "session-status";
   id: string;
@@ -167,12 +227,12 @@ export type NoticeItem = {
 };
 
 /**
- * A tool call hit a connection that needs action or cannot satisfy the selected
- * endpoint/resource contract. Carries the
- * structured `tool.auth_needed` or `credential.auth_needed` payload so the renderer can draw a clean inline
- * reconnect affordance when recovery is possible, or a calm unavailable state
- * for incompatible auth/resource containment. The app can start the right
- * recovery flow (OAuth reconnect for the surviving connection, or credential
+ * A tool call hit a missing or lapsed connection. The broker reports that
+ * condition as a tool error and the turn continues; reconnecting never resumes
+ * or replays the original call. Carries the structured `tool.auth_needed`
+ * payload so the renderer can draw a clean inline recovery affordance (provider
+ * logo + one human line + a Connect/Reconnect button) and the app can start the
+ * right flow (OAuth reconnect for the surviving connection, or credential
  * re-entry for an api-key one). The `reason` shapes the human copy but is never
  * shown raw.
  */
@@ -184,14 +244,7 @@ export type AuthNeededItem = {
   providerDomain: string;
   /** The lapsed connection to reconnect, when the row survived. */
   connectionId: string | null;
-  reason:
-    | "missing_connection"
-    | "expired"
-    | "insufficient_scope"
-    | "refresh_failed"
-    | "unsupported_auth"
-    | "resource_scope_unavailable"
-    | null;
+  reason: ToolAuthNeededPayload["reason"] | null;
   /** Scopes the provider now needs; may inform the copy, never shown as a raw label. */
   scopes: string[];
   /** The OAuth `resource` (RFC 8707) the reconnect should target, when supplied. */
@@ -227,10 +280,17 @@ export type TimelineItem =
   | NoticeItem
   | AuthNeededItem
   | MemoryItem
+  | FleetDecisionItem
   | TurnEndItem;
 
 /** Activity items cluster between chat messages (reasoning, tools, workers, sandbox, memory). */
-export type ActivityItem = ReasoningItem | ToolCallItem | WorkerItem | SandboxItem | MemoryItem;
+export type ActivityItem =
+  | ReasoningItem
+  | ToolCallItem
+  | WorkerItem
+  | SandboxItem
+  | MemoryItem
+  | FleetDecisionItem;
 
 export type TimelineGroup =
   | { kind: "item"; item: TimelineItem }