@opengeni/react 3.1.0 → 3.1.3-canary.38890816741001

package/src/timeline/types.ts

@@ -1,13 +1,17 @@
 import type {
+  AllowanceExhaustedRefusal,
   HumanInputQuestion,
   HumanInputResponse,
+  HumanInputSecretAnswerResult,
   MediaGenerationResult,
   ResourceRef,
   SessionStatus,
+  Session,
   TimelineAnnotation,
   TimelineAnnotationSource,
   ToolAuthNeededPayload,
   ToolRef,
+  ToolDisplayMetadata,
 } from "@opengeni/sdk";
 
 /* ----------------------------------------------------------------------------
@@ -19,6 +23,13 @@ import type {
    and the component demo.
    -------------------------------------------------------------------------- */
 
+/** The person who sent a message: their subject and the label frozen with it. */
+export type MessageSender = {
+  subjectId: string;
+  /** What the deployment knew them as when the message was accepted, such as an email. */
+  label: string | null;
+};
+
 export type TimelineAnnotationSourceDescriptor = Omit<
   TimelineAnnotationSource,
   "startOffset" | "endOffset" | "contextBefore" | "contextAfter"
@@ -48,6 +59,11 @@ export type UserMessageItem = {
   resources: ResourceRef[];
   /** Tools requested for the turn this message starts. */
   tools: ToolRef[];
+  /**
+   * The person who sent this message, as frozen when it was accepted. Absent
+   * for messages from agents, services and schedules, and for older messages.
+   */
+  sender?: MessageSender | undefined;
   occurredAt: string;
   /** Local-only delivery projection; absent for authoritative durable events. */
   delivery?:
@@ -55,6 +71,7 @@ export type UserMessageItem = {
         state: "sending" | "queued" | "failed";
         error?: string | undefined;
         onRetry?: (() => void) | undefined;
+        onEdit?: (() => void) | undefined;
         onRemove?: (() => void) | undefined;
       }
     | undefined;
@@ -65,6 +82,8 @@ export type HumanInputAnswerSummary = {
   label: string;
   prompt: string;
   values: string[];
+  /** A secret question's saved reference (never a value). */
+  secret?: HumanInputSecretAnswerResult | undefined;
 };
 
 /**
@@ -88,11 +107,21 @@ export type AgentMessageItem = {
   id: string;
   turnId: string | null;
   text: string;
-  /** Provider-declared assistant channel. Absent on legacy and non-Responses events. */
+  /**
+   * Assistant channel: provider-declared, or `commentary` when the model asked
+   * for tool work in the same response. Absent on legacy events and on
+   * undeclared final messages. Known from the first delta for Responses models.
+   */
   phase?: "commentary" | "final_answer" | undefined;
   /** Still receiving deltas (no completed/turn-end seen yet). */
   streaming: boolean;
   occurredAt: string;
+  /**
+   * When the first streamed text arrived, kept once completion moves
+   * `occurredAt` to the completion time. Absent for a message that never
+   * streamed.
+   */
+  startedAt?: string | undefined;
   /** Available only after the canonical completed event lands. */
   annotationSource?: TimelineAnnotationSourceDescriptor | undefined;
 };
@@ -129,6 +158,7 @@ export type ToolCallItem = {
   turnId: string | null;
   callId: string | null;
   name: string;
+  display?: ToolDisplayMetadata;
   arguments: unknown;
   output: unknown;
   truncation?: ToolCallTruncation | null;
@@ -159,6 +189,12 @@ export type WorkerItem = {
   action: "spawn" | "message";
   /** The worker's initial message / the message sent to it, when parseable. */
   prompt: string | null;
+  /**
+   * The title the manager gave a spawned worker (`session_create` `title`),
+   * when present. Hosts can supply a live title for any session id; this is
+   * the timeline's own fallback so a spawn names its agent even offline.
+   */
+  title?: string | null | undefined;
   /** The target/spawned worker session id, when parseable from args/output. */
   workerSessionId: string | null;
   /** Bounded structured failure retained from session_create/session_send_message. */
@@ -209,12 +245,22 @@ export type StartupPhaseItem = {
   id: string;
   turnId: string | null;
   phase: StartupPhase;
+  /** Live presentation only: accepted work waiting for its first worker claim. */
+  dispatchWait?: Session["dispatchWait"];
+  /** Renderer-only elapsed anchor when acceptance preceded recorded startup spans. */
+  loadingStartedAt?: string | undefined;
   status: "running" | "complete" | "failed" | "cancelled";
   startedAt: string;
   completedAt: string | null;
   durationMs: number | null;
   /** Sandbox origin and rig marker outcomes refine the settled label only. */
   outcome: "created" | "restored" | "resumed" | "skipped" | null;
+  blockedReason?:
+    | "capture_in_progress"
+    | "rotation_in_progress"
+    | "provider_recovery_in_progress"
+    | "compaction_required"
+    | undefined;
   occurredAt: string;
 };
 
@@ -227,6 +273,18 @@ export type StartupPhaseItem = {
  * `onMemoryClick` handler the row also deep-links to the record in its memory
  * pane; without one it is non-interactive rich content.
  */
+export type KnowledgeItem = {
+  kind: "knowledge";
+  id: string;
+  turnId: string | null;
+  status: "complete" | "failed";
+  outcome: "published" | "pending" | "rejected" | "archived" | "failed";
+  fileId?: string | undefined;
+  filename?: string | undefined;
+  entryId?: string | undefined;
+  occurredAt: string;
+};
+
 export type MemoryItem = {
   kind: "memory";
   id: string;
@@ -279,7 +337,14 @@ export type FleetDecisionItem = {
   policyVersion: "adaptive-shadow-v1";
   actualOutcome: "selected" | "waiting" | "none";
   actualCandidateKey: string | null;
-  actualReason: "lease_reused" | "pin" | "rotation" | "active" | "all_capped" | "none";
+  actualReason:
+    | "lease_reused"
+    | "pin"
+    | "rotation"
+    | "active"
+    | "all_capped"
+    | "allocator_disabled"
+    | "none";
   shadowOutcome: "selected" | "paced" | "none";
   shadowCandidateKey: string | null;
   shadowReason:
@@ -318,6 +383,13 @@ export type SessionStatusItem = {
   kind: "session-status";
   id: string;
   status: SessionStatus;
+  /**
+   * The runtime refused to start the next turn (an admission block). Nothing
+   * is asked of the person, so it reads as stuck, not "waiting on you".
+   */
+  blocked?: true;
+  /** Presentation-only evidence that this historical attention state resumed. */
+  resolvedAt?: string;
   occurredAt: string;
 };
 
@@ -342,12 +414,50 @@ export type NoticeItem = {
   id: string;
   tone: "waiting" | "cancelled" | "failed" | "input";
   text: string;
+  /** Presentation-only evidence that a historical approval wait resumed. */
+  resolvedAt?: string;
+  /**
+   * A model-capacity wait (no subscription capacity for the turn). Live, the
+   * turn's work row carries it as `label` with `detail` as one quiet secondary
+   * line; once `resolvedAt` is set it leaves no row, and its span is excluded
+   * from the turn's worked duration.
+   */
+  capacityWait?: { turnId: string | null; label: string; detail: string };
+  /** A preserved turn-end outcome, not a claim about current session state. */
+  recordedOutcome?: true;
+  /**
+   * Recorded agent wait only: delegated worker sessions that had not reported
+   * back when the wait began. Best effort from the loaded history; absent when
+   * none are known.
+   */
+  waitingAgents?: number;
+  /** Recorded agent wait only: when later input ended the wait. */
+  waitEndedAt?: string;
   /** Optional evidence kept inspectable without overwhelming the main rail. */
   details?: { label: string; value: unknown };
   action?: { label: string; url: string };
+  /**
+   * A usage ceiling refused further work. `text` keeps the canonical sentence
+   * for plain-text consumers; `MessageTimeline` renders this structured row
+   * (customizable with `renderAllowanceExhausted` / `allowanceExhaustedLabels`).
+   */
+  allowance?: AllowanceExhaustedRefusal;
+  /**
+   * The task's own usage limit stopped further model requests: a calm,
+   * non-failure stop. Amounts are null when the marker carried none.
+   * `MessageTimeline` renders it as a "Usage limit reached" row.
+   */
+  sessionUsageLimit?: SessionUsageLimitStop;
   occurredAt: string;
 };
 
+/** What a timeline row knows about a task usage-limit stop. */
+export type SessionUsageLimitStop = {
+  rootSessionId: string | null;
+  limitMicros: number | null;
+  usedMicros: number | null;
+};
+
 /**
  * First-class conversation-memory checkpoint. Stays outside collapsed turns so
  * auto-compaction cannot vanish behind a chevron. Chat bubbles are unchanged.
@@ -361,16 +471,36 @@ export type ContextCompactionItem = {
   estimatedTokensBefore: number | null;
   estimatedTokensAfter: number | null;
   skipReason: string | null;
+  /**
+   * Present only for a `summarization_failed` skip where the provider
+   * definitively rejected the compaction request. Content-free identifiers.
+   */
+  providerRejection: ContextCompactionProviderRejection | null;
+  /**
+   * The same turn's recorded failure text, when that turn failed because this
+   * compaction did. Diagnostics shown behind Details only.
+   */
+  failureDetail?: string;
   /** Provider implementation id for debug disclosure only. */
   implementation: string | null;
   occurredAt: string;
 };
 
+export type ContextCompactionProviderRejection = {
+  httpStatus: number;
+  type: string | null;
+  code: string | null;
+  param: string | null;
+  requestId: string | null;
+};
+
 export type MachineInputMember = {
   id: string;
   kind:
     | "scheduled_occurrence"
     | "goal_continuation"
+    | "background_command_result"
+    | "session_wait_timeout"
     | "agent_message"
     | "agent_steer_instruction"
     | "child_terminal_result"
@@ -395,6 +525,8 @@ export type MachineInputBatchItem = {
   id: string;
   turnId: string | null;
   members: MachineInputMember[];
+  /** Readable-turn presentation keeps machine payload prose inside the disclosure. */
+  compact?: boolean;
   occurredAt: string;
 };
 
@@ -414,12 +546,17 @@ export type AuthNeededItem = {
   turnId: string | null;
   /** The runtime surface that requested recovery, when the event is an MCP auth signal. */
   serverId: string | null;
+  /** Explicit recovery identity; never inferred from an opaque execution alias. */
+  canonicalServerId?: string | null;
+  connectionSubjectScope?: "workspace" | "subject" | null;
   /** Durable event family that produced this notice. */
   source?: "tool" | "credential" | "capability" | undefined;
   /** The connection's registrable domain, e.g. "linear.app". */
   providerDomain: string;
   /** The lapsed connection to reconnect, when the row survived. */
   connectionId: string | null;
+  /** Host-owned bindings must never be routed into Opengeni's native reconnect flow. */
+  authoritySource?: ToolAuthNeededPayload["authoritySource"] | null | undefined;
   reason: ToolAuthNeededPayload["reason"] | null;
   /** Scopes the provider now needs; may inform the copy, never shown as a raw label. */
   scopes: string[];
@@ -431,6 +568,8 @@ export type AuthNeededItem = {
   authorizationUrl: string | null;
   /** Agent-selected catalog recommendation. The host still owns authorization. */
   capability?: NonNullable<ToolAuthNeededPayload["capability"]> | null | undefined;
+  /** Human-reviewed custom integration proposal. Never treated as catalog authority. */
+  setupRequest?: ToolAuthNeededPayload["setupRequest"] | null | undefined;
   occurredAt: string;
 };
 
@@ -438,6 +577,10 @@ export type TurnOutcome = "complete" | "failed" | "cancelled";
 
 export type TurnEndItem = {
   kind: "turn-end";
+  /** A durable Retry reopened this failed logical turn; its failure is history. */
+  resumedAt?: string;
+  /** Keep an existing answer visible when a recorded input wait ends without final output. */
+  preserveWaitResponse?: true;
   id: string;
   turnId: string | null;
   outcome: TurnOutcome;
@@ -445,7 +588,7 @@ export type TurnEndItem = {
   occurredAt: string;
 };
 
-export type TimelineItem =
+export type TimelineItem = (
   | UserMessageItem
   | HumanInputItem
   | AgentMessageItem
@@ -462,10 +605,18 @@ export type TimelineItem =
   | MachineInputBatchItem
   | AuthNeededItem
   | MemoryItem
+  | KnowledgeItem
   | FleetDecisionItem
-  | TurnEndItem;
+  | TurnEndItem
+) & {
+  /** Durable identities, independent of renderer/reconciliation keys. */
+  sourceEvents?: readonly { eventId: string; sequence: number }[] | undefined;
+};
 
-/** Activity items cluster between chat messages (reasoning, tools, workers, sandbox, memory). */
+/**
+ * Activity items cluster between chat messages (reasoning, tools, workers,
+ * sandbox, memory). Assistant prose is rendered separately.
+ */
 export type ActivityItem =
   | ReasoningItem
   | ToolCallItem
@@ -473,7 +624,9 @@ export type ActivityItem =
   | SandboxItem
   | StartupPhaseItem
   | MemoryItem
-  | FleetDecisionItem;
+  | KnowledgeItem
+  | FleetDecisionItem
+  | AgentMessageItem;
 
 export type TimelineGroup =
   | { kind: "item"; item: TimelineItem }
@@ -483,6 +636,36 @@ export type TimelineGroup =
       items: ActivityItem[];
       outcome?: TurnOutcome;
       failureText?: string;
+      /** One turn's chronological work history, including progress prose after settlement. */
+      work?: {
+        startedAt: string;
+        endedAt?: string;
+        responseStartedAt?: string;
+        /**
+         * A live wait. `untimed` marks a capacity wait, whose row shows no
+         * running clock: that span is not work and ends on a quota reset or
+         * a person's choice, not after a predictable time.
+         */
+        waiting?: { label: string; since: string; detail?: string; untimed?: true };
+        /**
+         * Settled capacity-wait time inside this work span. It is not work:
+         * the worked duration and the live working clock exclude it.
+         */
+        pausedMs?: number;
+        details: TimelineGroup[];
+        /**
+         * While the turn is live, its progress notes stay readable above the
+         * work row and are also listed in `details`. These are their item ids,
+         * so an expanded work disclosure can fold the outside copies away.
+         */
+        liveNoteIds?: string[];
+        /**
+         * Set when this row folds several quiet wake-work-wait cycles (routine
+         * input, work without a visible reply, a finished wait) into one row.
+         * `summary` is the latest wait reason, shown under the collapsed row.
+         */
+        cycles?: { count: number; summary?: string };
+      };
     }
   | {
       kind: "turn";

package/src/timeline/work-presentation.ts

@@ -0,0 +1,189 @@
+// Pure presentation decisions for a timeline turn's work, shared by the web and native
+// timelines. Every function here is extracted verbatim from the web MessageTimeline so both
+// renderers decide identically what a turn shows (preparing, working, waiting, worked).
+import { timelineGroupContainsPresentedImage } from "./presented-image";
+import type { TurnSummaryStatus } from "./turn-summary-model";
+import type { ActivityItem, TimelineGroup, ToolCallItem } from "./types";
+
+export type ActivityGroup = Extract<TimelineGroup, { kind: "activity" }>;
+export type TurnGroup = Extract<TimelineGroup, { kind: "turn" }>;
+
+export function durationBetween(startedAt: string, endedAt: string): number | undefined {
+  const started = Date.parse(startedAt);
+  const ended = Date.parse(endedAt);
+  if (!Number.isFinite(started) || !Number.isFinite(ended) || ended < started) {
+    return undefined;
+  }
+  return ended - started;
+}
+
+/** Compaction landmarks among a fold's groups (secondary summary facet). */
+export function compactedLandmarkCount(groups: readonly TimelineGroup[]): number {
+  return groups.filter(
+    (group) =>
+      group.kind === "item" &&
+      group.item.kind === "context-compaction" &&
+      group.item.phase === "compacted",
+  ).length;
+}
+
+export function clusterIsSettled(group: ActivityGroup): boolean {
+  return group.items.every((item) => {
+    if (item.kind === "reasoning" || item.kind === "agent-message") {
+      return !item.streaming;
+    }
+    // Memory writes and fleet observations are discrete, already-settled events.
+    if (item.kind === "memory" || item.kind === "fleet-decision") {
+      return true;
+    }
+    return item.status !== "running";
+  });
+}
+
+export function flattenActivityItems(groups: readonly TimelineGroup[]): ActivityItem[] {
+  const items: ActivityItem[] = [];
+  for (const group of groups) {
+    if (group.kind === "activity") {
+      items.push(...flattenActivityItems(group.work?.details ?? []), ...group.items);
+    } else if (group.kind === "turn") {
+      items.push(...flattenActivityItems(group.groups));
+    }
+  }
+  return items;
+}
+
+export type ReadableWorkOptions = {
+  /** Host shows startup phases as ordinary details (web: startup-details context). */
+  startupDetails: boolean;
+  /** Startup chrome was dismissed by the reader. */
+  startupDismissed: boolean;
+};
+
+/**
+ * A readable turn whose only work so far is environment preparation renders as one quiet
+ * preparation surface instead of a "Working" fold.
+ */
+export function isPreparingWork(group: ActivityGroup, options: ReadableWorkOptions): boolean {
+  if (!group.work) return false;
+  const phases = group.items.filter((item) => item.kind === "startup-phase");
+  return (
+    !options.startupDetails &&
+    !options.startupDismissed &&
+    !group.work.endedAt &&
+    !group.work.waiting &&
+    phases.length > 0 &&
+    group.items.every(
+      (item) => item.kind === "startup-phase" || (item.kind === "reasoning" && !item.text.trim()),
+    ) &&
+    !phases.some((item) => item.status === "failed" || item.status === "cancelled")
+  );
+}
+
+/**
+ * Whether a readable turn's work row has anything to reveal when expanded.
+ * Unless the host shows startup phases as details, the work row's rail only
+ * renders failed or cancelled preparation steps, so a detail made only of
+ * completed or still-running steps (for example the queue phase before a turn
+ * was parked on a usage limit) renders nothing and does not make the row
+ * expandable.
+ */
+export function readableWorkHasDetails(
+  group: ActivityGroup & { work: NonNullable<ActivityGroup["work"]> },
+  options: Pick<ReadableWorkOptions, "startupDetails">,
+): boolean {
+  return group.work.details.some(
+    (detail) =>
+      options.startupDetails ||
+      detail.kind !== "activity" ||
+      Boolean(detail.work) ||
+      !detail.items.every(
+        (item) =>
+          (item.kind === "startup-phase" &&
+            item.status !== "failed" &&
+            item.status !== "cancelled") ||
+          (item.kind === "reasoning" && !item.text.trim()),
+      ),
+  );
+}
+
+/**
+ * Status of a readable turn's work row, minus the host-rendered live preview.
+ * Time spent waiting for model capacity is not work: the worked duration and
+ * the live working clock exclude it, and the wait itself shows no clock. A
+ * wait's `detail` is its one quiet secondary line.
+ */
+export function readableWorkStatus(
+  group: ActivityGroup & { work: NonNullable<ActivityGroup["work"]> },
+): Omit<TurnSummaryStatus, "preview"> & { detail?: string | undefined } {
+  const end = group.work.endedAt;
+  const pausedMs = group.work.pausedMs ?? 0;
+  if (end) {
+    const durationMs = durationBetween(group.work.startedAt, end);
+    const cycles = group.work.cycles;
+    // Folded quiet cycles report their wall-clock span: waits are the point.
+    if (cycles) return { kind: "worked", label: `${cycles.count} updates over`, durationMs };
+    return {
+      kind: "worked",
+      durationMs: durationMs === undefined ? undefined : Math.max(0, durationMs - pausedMs),
+    };
+  }
+  if (group.work.waiting) {
+    const { untimed, since, ...waiting } = group.work.waiting;
+    return { kind: "waiting", ...waiting, ...(untimed ? {} : { since }) };
+  }
+  const started = Date.parse(group.work.startedAt);
+  return {
+    kind: "working",
+    since:
+      pausedMs > 0 && Number.isFinite(started)
+        ? new Date(started + pausedMs).toISOString()
+        : group.work.startedAt,
+  };
+}
+
+/** Whether a readable turn's work fold starts expanded. */
+export function readableWorkDefaultOpen(group: ActivityGroup): true | undefined {
+  const phases = group.items.filter((item) => item.kind === "startup-phase");
+  return timelineGroupContainsPresentedImage(group) ||
+    group.outcome === "failed" ||
+    phases.some((item) => item.status === "failed" || item.status === "cancelled")
+    ? true
+    : undefined;
+}
+
+/** Whether the live preview should show (images stay primary output instead). */
+export function readableWorkShowsPreview(group: ActivityGroup): boolean {
+  return !timelineGroupContainsPresentedImage(group);
+}
+
+/**
+ * The step a rolling preview shows: steps advance with event order (progress notes and
+ * startup phases have their own surfaces). Mirrors the web RollingActivity selection.
+ */
+export function rollingActivityItem(
+  items: readonly ActivityItem[],
+  previousItem?: ActivityItem,
+  mounted = true,
+): { item: ActivityItem; running: boolean; earlierCount: number } | null {
+  const work = items.filter(
+    (item) => item.kind !== "startup-phase" && item.kind !== "agent-message",
+  );
+  const active = work.filter((item) =>
+    item.kind === "reasoning" ? item.streaming : "status" in item && item.status === "running",
+  );
+  const item =
+    !mounted && previousItem && previousItem.kind !== "agent-message" ? previousItem : work.at(-1);
+  if (!item) return null;
+  return {
+    item,
+    running: active.some((entry) => entry.id === item.id),
+    earlierCount: Math.max(
+      0,
+      work.findIndex((entry) => entry.id === item.id),
+    ),
+  };
+}
+
+export function isToolCall(item: ActivityItem): item is ToolCallItem {
+  return item.kind === "tool-call";
+}