@opengeni/react 0.27.0 → 0.29.0

package/src/timeline/projection.ts

@@ -11,6 +11,7 @@ import type {
   ActivityItem,
   AuthNeededItem,
   GoalItem,
+  MachineInputBatchItem,
   MemoryItem,
   SandboxItem,
   SessionStatusItem,
@@ -108,14 +109,14 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
             goalText: childCompletion.goalText,
             evidence: childCompletion.evidence,
             pausedReason: childCompletion.pausedReason,
-            text: typeof payload.text === "string" ? payload.text : "",
+            text: stringValue(payload.text),
           });
           break;
         }
         items.push({
           kind: "user-message",
           id: event.id,
-          text: typeof payload.text === "string" ? payload.text : "",
+          text: stringValue(payload.text),
           resources: resourceRefs(payload.resources),
           tools: toolRefs(payload.tools),
           occurredAt: event.occurredAt,
@@ -123,8 +124,22 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
         break;
       }
 
+      case "system.update.delivered": {
+        const inputs = machineInputMembers(payload.members);
+        if (inputs.length === 0) break;
+        closeStreamingTail();
+        items.push({
+          kind: "machine-input-batch",
+          id: event.id,
+          turnId,
+          members: inputs,
+          occurredAt: event.occurredAt,
+        });
+        break;
+      }
+
       case "agent.message.delta": {
-        const text = typeof payload.text === "string" ? payload.text : "";
+        const text = stringValue(payload.text);
         if (!text) {
           break;
         }
@@ -146,7 +161,7 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
       }
 
       case "agent.message.completed": {
-        const text = typeof payload.text === "string" ? payload.text : "";
+        const text = stringValue(payload.text);
         // Reconcile the most recent same-turn agent message — even when
         // activity (tool calls, reasoning) landed after its deltas — so the
         // completed text never duplicates the streamed one.
@@ -454,7 +469,7 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
           kind: "auth-needed",
           id: event.id,
           turnId,
-          providerDomain: typeof payload.providerDomain === "string" ? payload.providerDomain : "",
+          providerDomain: stringValue(payload.providerDomain),
           connectionId: typeof payload.connectionId === "string" ? payload.connectionId : null,
           reason: authNeededReason(payload.reason),
           scopes: stringList(payload.scopes),
@@ -968,7 +983,12 @@ function foldSettledTurn(groups: TimelineGroup[], turnEnd: TurnEndItem): void {
 }
 
 function isTurnBoundary(group: TimelineGroup | undefined): boolean {
-  return group?.kind === "turn" || (group?.kind === "item" && group.item.kind === "user-message");
+  return (
+    group?.kind === "turn" ||
+    (group?.kind === "item" &&
+      (group.item.kind === "user-message" ||
+        (group.item.kind === "notice" && group.item.tone === "input")))
+  );
 }
 
 function belongsToDifferentTurn(group: TimelineGroup | undefined, turnId: string | null): boolean {
@@ -1029,6 +1049,50 @@ function asRecord(value: unknown): Record<string, unknown> {
   return value !== null && typeof value === "object" ? (value as Record<string, unknown>) : {};
 }
 
+function stringValue(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+function machineInputMembers(value: unknown): MachineInputBatchItem["members"] {
+  const kinds = new Set<MachineInputBatchItem["members"][number]["kind"]>([
+    "scheduled_occurrence",
+    "goal_continuation",
+    "agent_message",
+    "agent_steer_instruction",
+    "child_terminal_result",
+  ]);
+  const classifications = new Set<MachineInputBatchItem["members"][number]["classification"]>([
+    "success",
+    "failure",
+    "action_required",
+    "info",
+  ]);
+  return Array.isArray(value)
+    ? value.flatMap((candidate) => {
+        const member = asRecord(candidate);
+        return typeof member.id === "string" &&
+          typeof member.kind === "string" &&
+          kinds.has(member.kind as MachineInputBatchItem["members"][number]["kind"]) &&
+          typeof member.classification === "string" &&
+          classifications.has(
+            member.classification as MachineInputBatchItem["members"][number]["classification"],
+          ) &&
+          typeof member.sourceId === "string"
+          ? [
+              {
+                id: member.id,
+                kind: member.kind as MachineInputBatchItem["members"][number]["kind"],
+                classification:
+                  member.classification as MachineInputBatchItem["members"][number]["classification"],
+                sourceId: member.sourceId,
+                summary: stringValue(member.summary),
+              },
+            ]
+          : [];
+      })
+    : [];
+}
+
 const SESSION_STATUSES: readonly SessionStatus[] = [
   "queued",
   "running",
@@ -1201,8 +1265,8 @@ function memoryItem(
     id,
     turnId,
     variant: type === "memory.corrected" ? "corrected" : "saved",
-    memoryKind: typeof payload.kind === "string" ? payload.kind : "",
-    preview: typeof payload.preview === "string" ? payload.preview : "",
+    memoryKind: stringValue(payload.kind),
+    preview: stringValue(payload.preview),
     ...(payload.deduped === true ? { deduped: true } : {}),
     ...(replacementPreview ? { replacementPreview } : {}),
     ...(action ? { action } : {}),
@@ -1245,7 +1309,7 @@ function reasoningText(payload: unknown): string {
   return content
     .map((part) => {
       const text = asRecord(part).text;
-      return typeof text === "string" ? text : "";
+      return stringValue(text);
     })
     .join("");
 }

package/src/timeline/turn-summary.tsx

@@ -1,12 +1,12 @@
 import { CheckIcon, ChevronRightIcon, CircleSlashIcon, TriangleAlertIcon } from "lucide-react";
-import { useState } from "react";
+import { Component, useMemo, useState, type ReactNode } from "react";
 import { Collapsible } from "radix-ui";
 import { cn } from "../lib/cn";
 import { useForcedDefaultOpen } from "./disclosure-context";
 import { useEntranceAnimation } from "./entrance";
 import { applyPatchOps, isApplyPatch, mediaPreviewFact, screenshotDataUrl } from "./parsers";
 import { rawTypeOf } from "./registry";
-import type { ActivityItem, TurnOutcome } from "./types";
+import type { ActivityItem, ToolCallItem, TurnOutcome } from "./types";
 export type { TurnOutcome } from "./types";
 
 /* ----------------------------------------------------------------------------
@@ -21,6 +21,67 @@ export type { TurnOutcome } from "./types";
    reader chooses to look inside it.
    -------------------------------------------------------------------------- */
 
+export const BUILT_IN_TURN_SUMMARY_FACET_IDS = [
+  "steps",
+  "files",
+  "commands",
+  "screenshots",
+  "memories",
+  "duration",
+] as const;
+
+export type BuiltInTurnSummaryFacetId = (typeof BUILT_IN_TURN_SUMMARY_FACET_IDS)[number];
+
+export type TurnSummaryContext = Readonly<{
+  /** Every normalized activity item folded into this summary. */
+  items: readonly ActivityItem[];
+  /** Tool calls from `items`, retained in timeline order for convenient aggregation. */
+  toolCalls: readonly ToolCallItem[];
+  /** The settled turn verdict, or absent for a neutral/incomplete cluster. */
+  outcome: TurnOutcome | undefined;
+  /** The bounded failure reason rendered by the enclosing summary, when present. */
+  failureText: string | undefined;
+  /** Total turn duration when the enclosing group has both valid timestamps. */
+  durationMs: number | undefined;
+  /** False when any projected activity is still running or streaming. */
+  settled: boolean;
+}>;
+
+export type TurnSummaryFacetResult = Readonly<{
+  icon?: ReactNode;
+  content: ReactNode;
+  ariaLabel?: string;
+  title?: string;
+}>;
+
+export type TurnSummaryFacet = Readonly<{
+  /** Stable identity used for removal and deterministic de-duplication. */
+  id: string;
+  /** Return null when this facet has nothing useful to show. */
+  summarize(context: TurnSummaryContext): TurnSummaryFacetResult | null;
+}>;
+
+type ModifyTurnSummaryFacets = Readonly<{
+  /** Appended after the remaining built-ins, in supplied order. */
+  add?: readonly TurnSummaryFacet[];
+  /** Built-ins to omit before custom facets are appended. */
+  remove?: readonly BuiltInTurnSummaryFacetId[];
+  replace?: never;
+}>;
+
+type ReplaceTurnSummaryFacets = Readonly<{
+  /** The complete ordered facet list. Mutually exclusive with add/remove. */
+  replace: readonly TurnSummaryFacet[];
+  add?: never;
+  remove?: never;
+}>;
+
+export type TurnSummaryFacetConfiguration = ModifyTurnSummaryFacets | ReplaceTurnSummaryFacets;
+
+export type TurnSummaryOptions = Readonly<{
+  facets?: TurnSummaryFacetConfiguration;
+}>;
+
 export type TurnSummaryProps = {
   /** The activity items in the turn (used only to compute the facet counts). */
   items: ActivityItem[];
@@ -43,8 +104,10 @@ export type TurnSummaryProps = {
    * of nodes, never a stack of boxes-in-boxes. The top-level fold stays a chip.
    */
   bare?: boolean | undefined;
+  /** Per-instance facet customization. Omit to preserve the built-in summary exactly. */
+  facets?: TurnSummaryFacetConfiguration | undefined;
   /** The rendered activity rail revealed on expand. */
-  children: React.ReactNode;
+  children: ReactNode;
 };
 
 export function TurnSummary({
@@ -54,6 +117,7 @@ export function TurnSummary({
   durationMs,
   defaultOpen,
   bare,
+  facets: facetConfiguration,
   children,
 }: TurnSummaryProps) {
   // An explicit `defaultOpen` always wins; otherwise an ancestor may seed it
@@ -61,7 +125,28 @@ export function TurnSummary({
   const forcedDefaultOpen = useForcedDefaultOpen();
   const [open, setOpen] = useState(defaultOpen ?? forcedDefaultOpen ?? false);
   const enter = useEntranceAnimation();
-  const facets = summarizeTurn(items, durationMs);
+  const context = useMemo(
+    () => createTurnSummaryContext(items, outcome, failureText, durationMs),
+    [items, outcome, failureText, durationMs],
+  );
+  const facetDefinitions = useMemo(
+    () => resolveTurnSummaryFacets(facetConfiguration),
+    [facetConfiguration],
+  );
+  const facets = useMemo(
+    () =>
+      facetDefinitions.flatMap((facet) => {
+        try {
+          const result = facet.summarize(context);
+          return result && hasFacetContent(result.content) ? [{ facet, result }] : [];
+        } catch {
+          // A host extension is presentation-only. It must never take down the
+          // durable timeline or hide the remaining built-in evidence.
+          return [];
+        }
+      }),
+    [context, facetDefinitions],
+  );
 
   return (
     <Collapsible.Root
@@ -117,7 +202,21 @@ export function TurnSummary({
           )}
         </span>
         <span className={cn("min-w-0 flex-1 truncate", bare ? "text-og-sm" : "text-og-fg-muted")}>
-          {facets}
+          {facets.map(({ facet, result }, index) => (
+            <FacetRenderBoundary key={facet.id}>
+              <>
+                {index > 0 ? " · " : null}
+                <span aria-label={result.ariaLabel} title={result.title}>
+                  {result.icon ? (
+                    <span aria-hidden className="mr-1 inline-flex align-[-0.125em]">
+                      {result.icon}
+                    </span>
+                  ) : null}
+                  {result.content}
+                </span>
+              </>
+            </FacetRenderBoundary>
+          ))}
           {outcome === "failed" && failureText ? (
             <span className="text-og-status-failed"> · {failureText}</span>
           ) : null}
@@ -150,63 +249,151 @@ export function TurnSummary({
   );
 }
 
-/** Compose the facet summary line ("14 steps · 3 files · 2 commands · 1 screenshot · 4m"). */
-function summarizeTurn(items: ActivityItem[], durationMs?: number): string {
-  let files = 0;
-  let commands = 0;
-  let screenshots = 0;
-  let memoriesSaved = 0;
-  let memoriesUpdated = 0;
-  for (const item of items) {
-    if (item.kind === "memory") {
-      // A memory write is a first-class facet — the "wrote 1 memory" signal the
-      // fold should make prominent — counted saved vs updated separately.
-      if (item.variant === "corrected") {
-        memoriesUpdated += 1;
-      } else {
-        memoriesSaved += 1;
-      }
-      continue;
+function createTurnSummaryContext(
+  items: ActivityItem[],
+  outcome: TurnOutcome | undefined,
+  failureText: string | undefined,
+  durationMs: number | undefined,
+): TurnSummaryContext {
+  const itemSnapshot = Object.freeze([...items]);
+  const toolCalls = Object.freeze(
+    itemSnapshot.filter((item): item is ToolCallItem => item.kind === "tool-call"),
+  );
+  const settled = itemSnapshot.every((item) => {
+    if (item.kind === "reasoning") {
+      return !item.streaming;
     }
-    if (item.kind !== "tool-call") {
-      continue;
+    if (item.kind === "tool-call" || item.kind === "worker" || item.kind === "sandbox") {
+      return item.status !== "running";
     }
-    // `item` is narrowed to ToolCallItem by the guard above — no cast needed.
-    if (isApplyPatch(item)) {
-      files += applyPatchOps(item.raw).length;
-    } else if (item.name === "exec_command") {
-      commands += 1;
-    } else if (
-      rawTypeOf(item) === "computer_call" ||
-      item.name === "computer_call" ||
-      item.name === "computer_screenshot"
-    ) {
-      if (screenshotDataUrl(item.output) !== null || mediaPreviewFact(item.output) !== null) {
-        screenshots += 1;
+    return true;
+  });
+  return Object.freeze({
+    items: itemSnapshot,
+    toolCalls,
+    outcome,
+    failureText,
+    durationMs,
+    settled,
+  });
+}
+
+const BUILT_IN_TURN_SUMMARY_FACETS: readonly TurnSummaryFacet[] = Object.freeze([
+  {
+    id: "steps",
+    summarize: ({ items }) => ({
+      content: `${items.length} ${items.length === 1 ? "step" : "steps"}`,
+    }),
+  },
+  {
+    id: "files",
+    summarize: ({ toolCalls }) => {
+      let files = 0;
+      for (const item of toolCalls) {
+        if (isApplyPatch(item)) {
+          files += applyPatchOps(item.raw).length;
+        }
       }
+      return files ? { content: `${files} ${files === 1 ? "file" : "files"} edited` } : null;
+    },
+  },
+  {
+    id: "commands",
+    summarize: ({ toolCalls }) => {
+      const commands = toolCalls.filter((item) => item.name === "exec_command").length;
+      return commands
+        ? { content: `${commands} ${commands === 1 ? "command" : "commands"}` }
+        : null;
+    },
+  },
+  {
+    id: "screenshots",
+    summarize: ({ toolCalls }) => {
+      let screenshots = 0;
+      for (const item of toolCalls) {
+        if (
+          (rawTypeOf(item) === "computer_call" ||
+            item.name === "computer_call" ||
+            item.name === "computer_screenshot") &&
+          (screenshotDataUrl(item.output) !== null || mediaPreviewFact(item.output) !== null)
+        ) {
+          screenshots += 1;
+        }
+      }
+      return screenshots
+        ? {
+            content: `${screenshots} ${screenshots === 1 ? "screenshot" : "screenshots"}`,
+          }
+        : null;
+    },
+  },
+  {
+    id: "memories",
+    summarize: ({ items }) => {
+      let saved = 0;
+      let updated = 0;
+      for (const item of items) {
+        if (item.kind !== "memory") {
+          continue;
+        }
+        if (item.variant === "corrected") {
+          updated += 1;
+        } else {
+          saved += 1;
+        }
+      }
+      const parts: string[] = [];
+      if (saved) {
+        parts.push(`${saved} ${saved === 1 ? "memory" : "memories"} saved`);
+      }
+      if (updated) {
+        parts.push(`${updated} ${updated === 1 ? "memory" : "memories"} updated`);
+      }
+      return parts.length > 0 ? { content: parts.join(" · ") } : null;
+    },
+  },
+  {
+    id: "duration",
+    summarize: ({ durationMs }) => {
+      const duration = formatDurationFacet(durationMs);
+      return duration ? { content: duration } : null;
+    },
+  },
+]);
+
+function resolveTurnSummaryFacets(
+  configuration: TurnSummaryFacetConfiguration | undefined,
+): readonly TurnSummaryFacet[] {
+  const requested: readonly TurnSummaryFacet[] = configuration?.replace ?? [
+    ...BUILT_IN_TURN_SUMMARY_FACETS.filter(
+      (facet) => !configuration?.remove?.includes(facet.id as BuiltInTurnSummaryFacetId),
+    ),
+    ...(configuration?.add ?? []),
+  ];
+  const seen = new Set<string>();
+  return requested.filter((facet) => {
+    if (!facet.id || seen.has(facet.id)) {
+      return false;
     }
+    seen.add(facet.id);
+    return true;
+  });
+}
+
+function hasFacetContent(content: ReactNode): boolean {
+  return content !== null && content !== undefined && content !== false && content !== "";
+}
+
+class FacetRenderBoundary extends Component<{ children: ReactNode }, { failed: boolean }> {
+  state = { failed: false };
+
+  static getDerivedStateFromError(): { failed: boolean } {
+    return { failed: true };
   }
-  const parts = [`${items.length} ${items.length === 1 ? "step" : "steps"}`];
-  if (files) {
-    parts.push(`${files} ${files === 1 ? "file" : "files"} edited`);
-  }
-  if (commands) {
-    parts.push(`${commands} ${commands === 1 ? "command" : "commands"}`);
-  }
-  if (screenshots) {
-    parts.push(`${screenshots} ${screenshots === 1 ? "screenshot" : "screenshots"}`);
-  }
-  if (memoriesSaved) {
-    parts.push(`${memoriesSaved} ${memoriesSaved === 1 ? "memory" : "memories"} saved`);
-  }
-  if (memoriesUpdated) {
-    parts.push(`${memoriesUpdated} ${memoriesUpdated === 1 ? "memory" : "memories"} updated`);
-  }
-  const duration = formatDurationFacet(durationMs);
-  if (duration) {
-    parts.push(duration);
+
+  render(): ReactNode {
+    return this.state.failed ? null : this.props.children;
   }
-  return parts.join(" · ");
 }
 
 function formatDurationFacet(durationMs: number | undefined): string | null {

package/src/timeline/types.ts

@@ -218,7 +218,7 @@ export type GoalItem = {
 export type NoticeItem = {
   kind: "notice";
   id: string;
-  tone: "waiting" | "cancelled" | "failed";
+  tone: "waiting" | "cancelled" | "failed" | "input";
   text: string;
   /** Optional evidence kept inspectable without overwhelming the main rail. */
   details?: { label: string; value: unknown };
@@ -226,6 +226,31 @@ export type NoticeItem = {
   occurredAt: string;
 };
 
+export type MachineInputMember = {
+  id: string;
+  kind:
+    | "scheduled_occurrence"
+    | "goal_continuation"
+    | "agent_message"
+    | "agent_steer_instruction"
+    | "child_terminal_result";
+  classification: "success" | "failure" | "action_required" | "info";
+  sourceId: string;
+  summary: string;
+};
+
+/**
+ * One or more durable non-human inputs that joined the following agent turn.
+ * This is communication, not a warning or a protocol-debug payload.
+ */
+export type MachineInputBatchItem = {
+  kind: "machine-input-batch";
+  id: string;
+  turnId: string | null;
+  members: MachineInputMember[];
+  occurredAt: string;
+};
+
 /**
  * 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
@@ -278,6 +303,7 @@ export type TimelineItem =
   | SessionStatusItem
   | GoalItem
   | NoticeItem
+  | MachineInputBatchItem
   | AuthNeededItem
   | MemoryItem
   | FleetDecisionItem