@opengeni/react 3.3.2 → 3.4.0

package/dist/timeline/turn-summary-model.d.ts

@@ -0,0 +1,95 @@
+import type { ReactNode } from "react";
+import type { ActivityItem, ToolCallItem, TurnOutcome } from "./types.js";
+export declare const BUILT_IN_TURN_SUMMARY_FACET_IDS: readonly ["steps", "files", "commands", "screenshots", "memories", "compacted", "duration"];
+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;
+    /**
+     * Adjacent compaction landmarks next to this fold. Landmark remains the
+     * primary UI; this is a secondary chip signal only.
+     */
+    contextCompactionCount: number;
+}>;
+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<{
+    /**
+     * Readable per-turn presentation. Assistant progress stays fully formatted;
+     * each turn has its own Working / Worked row and rolling latest step.
+     * Ordinary tip-follow and manual scrolling are unchanged.
+     */
+    rolling?: boolean;
+    facets?: TurnSummaryFacetConfiguration;
+}>;
+/**
+ * Exchange status shown in place of the plain facet line. `working` and
+ * `waiting` run a live clock from `since`; `worked` shows the settled span.
+ */
+export type TurnSummaryStatus = Readonly<{
+    kind: "working" | "waiting" | "worked";
+    /** Replaces the default "Working" / "Waiting" wording. */
+    label?: string | undefined;
+    /** Live clock start for `working` and `waiting`. */
+    since?: string | undefined;
+    /** Settled span for `worked`. */
+    durationMs?: number | undefined;
+    /** Live step preview under the row while it is collapsed. */
+    preview?: ReactNode;
+    /**
+     * Guidance under the row that stays visible whether the fold is open or
+     * closed, e.g. what a wait needs from the reader.
+     */
+    guidance?: ReactNode;
+}>;
+/** Elapsed wall time with seconds below an hour: "14s", "2m 14s", "1h 05m". */
+export declare function formatElapsed(durationMs: number): string;
+export declare function createTurnSummaryContext(items: ActivityItem[], outcome: TurnOutcome | undefined, failureText: string | undefined, durationMs: number | undefined, contextCompactionCount: number): TurnSummaryContext;
+export declare const BUILT_IN_TURN_SUMMARY_FACETS: readonly TurnSummaryFacet[];
+export declare function resolveTurnSummaryFacets(configuration: TurnSummaryFacetConfiguration | undefined): readonly TurnSummaryFacet[];
+export declare function formatDurationFacet(durationMs: number | undefined): string | null;
+/**
+ * The facets a turn header shows. With a readable status line, duration lives in
+ * the status, preparation-only turns drop the step count, and a live or waiting
+ * status keeps only the step count among the built-ins. A failing custom facet is
+ * skipped rather than breaking the header.
+ */
+export declare function selectTurnSummaryFacets(definitions: readonly TurnSummaryFacet[], context: TurnSummaryContext, statusKind: TurnSummaryStatus["kind"] | undefined): Array<{
+    facet: TurnSummaryFacet;
+    result: TurnSummaryFacetResult;
+}>;
+export {};

package/dist/timeline/turn-summary.d.ts

@@ -1,5 +1,8 @@
 import { type ReactNode } from "react";
-import type { ActivityItem, ToolCallItem, TurnOutcome } from "./types.js";
+import { BUILT_IN_TURN_SUMMARY_FACET_IDS, formatElapsed, type TurnSummaryFacetConfiguration, type TurnSummaryStatus } from "./turn-summary-model.js";
+import type { ActivityItem, TurnOutcome } from "./types.js";
+export { BUILT_IN_TURN_SUMMARY_FACET_IDS, formatElapsed };
+export type { BuiltInTurnSummaryFacetId, TurnSummaryContext, TurnSummaryFacet, TurnSummaryFacetConfiguration, TurnSummaryFacetResult, TurnSummaryOptions, TurnSummaryStatus, } from "./turn-summary-model.js";
 export type { TurnOutcome } from "./types.js";
 /**
  * True while settle chrome is active (open beat, slow collapse, or the short
@@ -8,63 +11,15 @@ export type { TurnOutcome } from "./types.js";
  * rails, and never remount closed nested chips mid-collapse (that yanked).
  */
 export declare function useTurnSettleOpen(): boolean;
-export declare const BUILT_IN_TURN_SUMMARY_FACET_IDS: readonly ["steps", "files", "commands", "screenshots", "memories", "compacted", "duration"];
-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;
-    /**
-     * Adjacent compaction landmarks next to this fold. Landmark remains the
-     * primary UI; this is a secondary chip signal only.
-     */
-    contextCompactionCount: number;
-}>;
-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 = {
+    /** Reports the disclosure's actual open state on mount and on every change. */
+    onOpenStateChange?: ((open: boolean) => void) | undefined;
     /** The activity items in the turn (used only to compute the facet counts). */
     items: ActivityItem[];
     /**
      * The settled verdict — or absent for a completed CLUSTER of a still-running
-     * turn, which folds neutrally: no verdict glyph (the turn has none yet), a
-     * quiet pulse dot in its place so alignment and the running feel both hold.
+     * turn, which folds neutrally. Only unfinished activity inside this summary
+     * animates; the parent turn may still be composing a response elsewhere.
      */
     outcome?: TurnOutcome | undefined;
     /** A short failure reason shown inline on a failed chip (never hidden). */
@@ -73,6 +28,7 @@ export type TurnSummaryProps = {
     durationMs?: number | undefined;
     /** Start expanded. */
     defaultOpen?: boolean | undefined;
+    liveHeader?: ReactNode;
     /**
      * A nested fold — a cluster or sub-turn INSIDE an already-expanded turn. It
      * drops the bordered/filled chip and renders as a plain disclosure node on the
@@ -110,7 +66,17 @@ export type TurnSummaryProps = {
     copyText?: string | undefined;
     /** Adjacent compaction landmark count for the secondary chip facet. */
     contextCompactionCount?: number | undefined;
+    /**
+     * Exchange status line (compact progress presentation). Replaces the state
+     * marker and the duration facet; a settled `worked` row reads as a separator.
+     */
+    status?: TurnSummaryStatus | undefined;
+    /**
+     * False when the fold has nothing to reveal: the row renders without a
+     * chevron and is not a disclosure control. Defaults to true.
+     */
+    expandable?: boolean | undefined;
     /** The rendered activity rail revealed on expand. */
     children: ReactNode;
 };
-export declare function TurnSummary({ items, outcome, failureText, durationMs, defaultOpen, bare, facets: facetConfiguration, settleFold, foldKey, copyText, contextCompactionCount, children, }: TurnSummaryProps): import("react").JSX.Element;
+export declare function TurnSummary({ items, outcome, failureText, durationMs, defaultOpen, liveHeader, bare, facets: facetConfiguration, settleFold, foldKey, copyText, contextCompactionCount, status, expandable, onOpenStateChange, children, }: TurnSummaryProps): import("react").JSX.Element;

package/dist/timeline/types.d.ts

@@ -1,4 +1,10 @@
-import type { HumanInputQuestion, HumanInputResponse, MediaGenerationResult, ResourceRef, SessionStatus, TimelineAnnotation, TimelineAnnotationSource, ToolAuthNeededPayload, ToolRef } from "@opengeni/sdk";
+import type { AllowanceExhaustedRefusal, HumanInputQuestion, HumanInputResponse, HumanInputSecretAnswerResult, MediaGenerationResult, ResourceRef, SessionStatus, Session, TimelineAnnotation, TimelineAnnotationSource, ToolAuthNeededPayload, ToolRef, ToolDisplayMetadata } from "@opengeni/sdk";
+/** 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"> & {
     text: string;
 };
@@ -24,12 +30,18 @@ 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?: {
         state: "sending" | "queued" | "failed";
         error?: string | undefined;
         onRetry?: (() => void) | undefined;
+        onEdit?: (() => void) | undefined;
         onRemove?: (() => void) | undefined;
     } | undefined;
 };
@@ -38,6 +50,8 @@ export type HumanInputAnswerSummary = {
     label: string;
     prompt: string;
     values: string[];
+    /** A secret question's saved reference (never a value). */
+    secret?: HumanInputSecretAnswerResult | undefined;
 };
 /**
  * One resolved structured question in the conversation. The live pending form
@@ -59,11 +73,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;
 };
@@ -97,6 +121,7 @@ export type ToolCallItem = {
     turnId: string | null;
     callId: string | null;
     name: string;
+    display?: ToolDisplayMetadata;
     arguments: unknown;
     output: unknown;
     truncation?: ToolCallTruncation | null;
@@ -126,6 +151,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. */
@@ -167,12 +198,17 @@ 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;
 };
 /**
@@ -184,6 +220,17 @@ 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;
@@ -228,7 +275,7 @@ 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: "fenced_in_flight" | "fenced_candidate_missing" | "admission_paced" | "no_eligible_candidate" | "overlay_isolated_empty" | "best_score" | "affinity_best" | "hysteresis_hold";
@@ -249,6 +296,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;
 };
 export type GoalItem = {
@@ -263,6 +317,29 @@ 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;
@@ -272,8 +349,26 @@ export type NoticeItem = {
         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.
@@ -287,13 +382,30 @@ 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" | "agent_message" | "agent_steer_instruction" | "child_terminal_result" | "media_generation_result" | "child_requires_action" | "child_requires_action_resolved" | "child_paused" | "child_waiting_capacity" | "child_progress";
+    kind: "scheduled_occurrence" | "goal_continuation" | "background_command_result" | "session_wait_timeout" | "agent_message" | "agent_steer_instruction" | "child_terminal_result" | "media_generation_result" | "child_requires_action" | "child_requires_action_resolved" | "child_paused" | "child_waiting_capacity" | "child_progress";
     classification: "success" | "failure" | "action_required" | "info";
     sourceId: string;
     summary: string;
@@ -308,6 +420,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;
 };
 /**
@@ -326,12 +440,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[];
@@ -343,20 +462,35 @@ 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;
 };
 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;
     failureText: string | null;
     occurredAt: string;
 };
-export type TimelineItem = UserMessageItem | HumanInputItem | AgentMessageItem | ReasoningItem | ToolCallItem | WorkerItem | WorkerCompletionItem | SandboxItem | StartupPhaseItem | SessionStatusItem | GoalItem | NoticeItem | ContextCompactionItem | MachineInputBatchItem | AuthNeededItem | MemoryItem | FleetDecisionItem | TurnEndItem;
-/** Activity items cluster between chat messages (reasoning, tools, workers, sandbox, memory). */
-export type ActivityItem = ReasoningItem | ToolCallItem | WorkerItem | SandboxItem | StartupPhaseItem | MemoryItem | FleetDecisionItem;
+export type TimelineItem = (UserMessageItem | HumanInputItem | AgentMessageItem | ReasoningItem | ToolCallItem | WorkerItem | WorkerCompletionItem | SandboxItem | StartupPhaseItem | SessionStatusItem | GoalItem | NoticeItem | ContextCompactionItem | MachineInputBatchItem | AuthNeededItem | MemoryItem | KnowledgeItem | FleetDecisionItem | 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). Assistant prose is rendered separately.
+ */
+export type ActivityItem = ReasoningItem | ToolCallItem | WorkerItem | SandboxItem | StartupPhaseItem | MemoryItem | KnowledgeItem | FleetDecisionItem | AgentMessageItem;
 export type TimelineGroup = {
     kind: "item";
     item: TimelineItem;
@@ -366,6 +500,44 @@ 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";
     id: string;

package/dist/timeline/work-presentation.d.ts

@@ -0,0 +1,60 @@
+import type { TurnSummaryStatus } from "./turn-summary-model.js";
+import type { ActivityItem, TimelineGroup, ToolCallItem } from "./types.js";
+export type ActivityGroup = Extract<TimelineGroup, {
+    kind: "activity";
+}>;
+export type TurnGroup = Extract<TimelineGroup, {
+    kind: "turn";
+}>;
+export declare function durationBetween(startedAt: string, endedAt: string): number | undefined;
+/** Compaction landmarks among a fold's groups (secondary summary facet). */
+export declare function compactedLandmarkCount(groups: readonly TimelineGroup[]): number;
+export declare function clusterIsSettled(group: ActivityGroup): boolean;
+export declare function flattenActivityItems(groups: readonly TimelineGroup[]): ActivityItem[];
+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 declare function isPreparingWork(group: ActivityGroup, options: ReadableWorkOptions): boolean;
+/**
+ * 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 declare function readableWorkHasDetails(group: ActivityGroup & {
+    work: NonNullable<ActivityGroup["work"]>;
+}, options: Pick<ReadableWorkOptions, "startupDetails">): boolean;
+/**
+ * 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 declare function readableWorkStatus(group: ActivityGroup & {
+    work: NonNullable<ActivityGroup["work"]>;
+}): Omit<TurnSummaryStatus, "preview"> & {
+    detail?: string | undefined;
+};
+/** Whether a readable turn's work fold starts expanded. */
+export declare function readableWorkDefaultOpen(group: ActivityGroup): true | undefined;
+/** Whether the live preview should show (images stay primary output instead). */
+export declare function readableWorkShowsPreview(group: ActivityGroup): boolean;
+/**
+ * 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 declare function rollingActivityItem(items: readonly ActivityItem[], previousItem?: ActivityItem, mounted?: boolean): {
+    item: ActivityItem;
+    running: boolean;
+    earlierCount: number;
+} | null;
+export declare function isToolCall(item: ActivityItem): item is ToolCallItem;