@opengeni/react 0.11.0 → 0.13.0

package/src/timeline/projection.ts

@@ -1,9 +1,16 @@
 import type { SessionEvent, SessionStatus } from "@opengeni/sdk";
-import { humanizeFailureReason, tryParseJson } from "../lib/format";
+import {
+  CREDIT_EXHAUSTION_MESSAGE,
+  humanizeFailureReason,
+  isCreditExhaustion,
+  tryParseJson,
+} from "../lib/format";
 import type {
   AgentMessageItem,
   ActivityItem,
+  AuthNeededItem,
   GoalItem,
+  MemoryItem,
   SandboxItem,
   SessionStatusItem,
   TimelineGroup,
@@ -30,7 +37,6 @@ import type {
 /** Tool names on the first-party OpenGeni MCP server that operate on sessions. */
 const WORKER_SPAWN_TOOL = "session_create";
 const WORKER_MESSAGE_TOOL = "session_send_message";
-const WORKER_INTERRUPT_TOOL = "session_interrupt";
 
 export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
   const items: TimelineItem[] = [];
@@ -47,9 +53,18 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
     }
   };
 
-  const finalizeOpen = (turnId?: string | null, disposition: "complete" | "failed" | "cancelled" = "complete"): void => {
+  const finalizeOpen = (
+    turnId?: string | null,
+    disposition: "complete" | "failed" | "cancelled" = "complete",
+  ): void => {
     for (const item of items) {
-      if (turnId !== undefined && "turnId" in item && item.turnId && turnId && item.turnId !== turnId) {
+      if (
+        turnId !== undefined &&
+        "turnId" in item &&
+        item.turnId &&
+        turnId &&
+        item.turnId !== turnId
+      ) {
         continue;
       }
       if ((item.kind === "agent-message" || item.kind === "reasoning") && item.streaming) {
@@ -73,11 +88,27 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
         // A steering message must not mark in-flight tools complete; it only
         // ends whatever text was streaming. Turn lifecycle events finalize.
         closeStreamingTail();
+        const childCompletion = workerCompletionPayload(payload.childCompletion);
+        if (childCompletion) {
+          items.push({
+            kind: "worker-completion",
+            id: event.id,
+            turnId,
+            occurredAt: event.occurredAt,
+            childSessionId: childCompletion.childSessionId,
+            childStatus: childCompletion.childStatus,
+            goalStatus: childCompletion.goalStatus,
+            goalText: childCompletion.goalText,
+            evidence: childCompletion.evidence,
+            pausedReason: childCompletion.pausedReason,
+            text: typeof payload.text === "string" ? payload.text : "",
+          });
+          break;
+        }
         items.push({
           kind: "user-message",
           id: event.id,
           text: typeof payload.text === "string" ? payload.text : "",
-          ...(event.pendingUserMessage ? { pending: true } : {}),
           resources: resourceRefs(payload.resources),
           tools: toolRefs(payload.tools),
           occurredAt: event.occurredAt,
@@ -114,8 +145,14 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
         // completed text never duplicates the streamed one.
         const open = [...items]
           .reverse()
-          .find((item): item is AgentMessageItem => item.kind === "agent-message" && item.turnId === turnId);
-        if (open && (open.streaming || !open.text || text === open.text || text.startsWith(open.text))) {
+          .find(
+            (item): item is AgentMessageItem =>
+              item.kind === "agent-message" && item.turnId === turnId,
+          );
+        if (
+          open &&
+          (open.streaming || !open.text || text === open.text || text.startsWith(open.text))
+        ) {
           // The completed text is authoritative when it extends what streamed.
           if (!open.text || (text && text.startsWith(open.text))) {
             open.text = text || open.text;
@@ -163,23 +200,6 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
         const callId = typeof payload.id === "string" ? payload.id : null;
         const args = payload.arguments ?? null;
         closeStreamingTail();
-        if (name === WORKER_INTERRUPT_TOOL) {
-          // stop (default) vs steer — the target keeps its goal on steer and
-          // picks up its next queued turn (pair with session_send_message).
-          items.push({
-            kind: "worker",
-            id: event.id,
-            turnId,
-            callId,
-            action: "interrupt",
-            prompt: null,
-            workerSessionId: extractSessionRef(args),
-            mode: workerInterruptMode(args),
-            status: "running",
-            occurredAt: event.occurredAt,
-          });
-          break;
-        }
         if (name === WORKER_SPAWN_TOOL || name === WORKER_MESSAGE_TOOL) {
           items.push({
             kind: "worker",
@@ -235,10 +255,37 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
       case "sandbox.operation.completed":
       case "sandbox.operation.failed": {
         const name = typeof payload.name === "string" ? payload.name : "sandbox";
-        const status = event.type.endsWith(".failed") ? "failed" : event.type.endsWith(".completed") ? "complete" : "running";
+        const status = event.type.endsWith(".failed")
+          ? "failed"
+          : event.type.endsWith(".completed")
+            ? "complete"
+            : "running";
+        // Routine per-turn platform plumbing that runs before EVERY turn to
+        // guarantee box contents survive a re-warm — NOT the agent redoing work:
+        //   - repository-clone: idempotent clone check + off-manifest token re-seed;
+        //   - file-resource-download: idempotent `if [ ! -f ] then curl` (skips
+        //     when the attached file is already on the box — see
+        //     sandboxFileDownloadCommand), so an uploaded image is not re-fetched;
+        //     the operation still emits every turn even when it does nothing.
+        // Rendering either every turn reads as churn. Only FAILURES surface, and
+        // they surface loudly — the failed event below creates its own item even
+        // without a started row.
+        if (
+          (name === "repository-clone" || name === "file-resource-download") &&
+          status !== "failed"
+        ) {
+          break;
+        }
         const existing = findOpenSandbox(items, name);
         if (existing && status !== "running") {
           existing.status = status;
+          if (
+            payload.origin === "created" ||
+            payload.origin === "restored" ||
+            payload.origin === "resumed"
+          ) {
+            existing.origin = payload.origin;
+          }
           const message = failureMessage(payload);
           if (message) {
             existing.output = existing.output ? `${existing.output}\n${message}` : message;
@@ -254,6 +301,12 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
             name,
             command: typeof payload.command === "string" ? payload.command : null,
             output: failureMessage(payload) ?? "",
+            origin:
+              payload.origin === "created" ||
+              payload.origin === "restored" ||
+              payload.origin === "resumed"
+                ? payload.origin
+                : null,
             status,
             occurredAt: event.occurredAt,
           });
@@ -263,9 +316,14 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
 
       case "sandbox.command.output.delta": {
         // `chunk` is the canonical wire field; text/output are legacy shapes.
-        const text = typeof payload.chunk === "string"
-          ? payload.chunk
-          : typeof payload.text === "string" ? payload.text : typeof payload.output === "string" ? payload.output : "";
+        const text =
+          typeof payload.chunk === "string"
+            ? payload.chunk
+            : typeof payload.text === "string"
+              ? payload.text
+              : typeof payload.output === "string"
+                ? payload.output
+                : "";
         if (!text) {
           break;
         }
@@ -273,7 +331,11 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
         // otherwise the latest running operation is the best available owner.
         const open =
           (typeof payload.name === "string" ? findOpenSandbox(items, payload.name) : undefined) ??
-          [...items].reverse().find((item): item is SandboxItem => item.kind === "sandbox" && item.status === "running");
+          [...items]
+            .reverse()
+            .find(
+              (item): item is SandboxItem => item.kind === "sandbox" && item.status === "running",
+            );
         if (open) {
           open.output += text;
         }
@@ -293,7 +355,9 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
         if (!ATTENTION_STATUSES.has(status)) {
           break;
         }
-        const previous = [...items].reverse().find((item): item is SessionStatusItem => item.kind === "session-status");
+        const previous = [...items]
+          .reverse()
+          .find((item): item is SessionStatusItem => item.kind === "session-status");
         if (previous?.status === status) {
           break;
         }
@@ -313,21 +377,112 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
         break;
       }
 
-      case "tool.auth_needed": {
+      case "session.context.compacted": {
+        closeStreamingTail();
+        const before =
+          typeof payload.estimatedTokensBefore === "number"
+            ? Math.round(payload.estimatedTokensBefore).toLocaleString("en-US")
+            : null;
+        const after =
+          typeof payload.estimatedTokensAfter === "number"
+            ? Math.round(payload.estimatedTokensAfter).toLocaleString("en-US")
+            : null;
+        items.push({
+          kind: "notice",
+          id: event.id,
+          tone: "waiting",
+          text:
+            before && after
+              ? `Context compacted from approximately ${before} to ${after} tokens.`
+              : "Context compacted so the turn could continue.",
+          occurredAt: event.occurredAt,
+        });
+        break;
+      }
+
+      case "session.context.compaction.skipped": {
         closeStreamingTail();
-        const authorizationUrl = typeof payload.authorizationUrl === "string" ? payload.authorizationUrl : null;
+        const reason = typeof payload.reason === "string" ? payload.reason : null;
         items.push({
           kind: "notice",
           id: event.id,
           tone: "waiting",
-          text: authNeededNoticeText(payload),
-          ...(authorizationUrl ? { action: { label: "Connect", url: authorizationUrl } } : {}),
+          text:
+            reason === "no_history"
+              ? "Context compaction skipped because there is no active history to compact."
+              : reason === "replacement_not_smaller"
+                ? "Context compaction skipped because the generated checkpoint would not reduce the context."
+                : "Context compaction was not needed.",
+          occurredAt: event.occurredAt,
+        });
+        break;
+      }
+
+      case "turn.recovery.requested": {
+        // Recovery requests are durable control-plane evidence, not a user
+        // message or proof that recovery succeeded. Live state already exposes
+        // a genuinely recovering session; keep the raw event in Debug/audit.
+        break;
+      }
+
+      case "turn.event.rejected_late": {
+        // Attempt-fence rejections prove stale callbacks did not alter current
+        // truth. They are useful diagnostics but never actionable chat content,
+        // regardless of the rejected event type. Debug/audit retains the event.
+        break;
+      }
+
+      case "tool.auth_needed": {
+        // Keep the whole structured payload — the renderer turns it into a clean
+        // inline reconnect card, and the app starts the recovery flow off the
+        // connectionId/resource. Losing it to a plain-text notice was the ugly
+        // "linear.app needs to be reconnected." line users complained about.
+        closeStreamingTail();
+        items.push({
+          kind: "auth-needed",
+          id: event.id,
+          turnId,
+          providerDomain: typeof payload.providerDomain === "string" ? payload.providerDomain : "",
+          connectionId: typeof payload.connectionId === "string" ? payload.connectionId : null,
+          reason: authNeededReason(payload.reason),
+          scopes: stringList(payload.scopes),
+          resource: typeof payload.resource === "string" ? payload.resource : null,
+          toolName: typeof payload.toolName === "string" ? payload.toolName : null,
+          authorizationUrl:
+            typeof payload.authorizationUrl === "string" ? payload.authorizationUrl : null,
           occurredAt: event.occurredAt,
         });
         break;
       }
 
       case "turn.completed": {
+        // A standalone manual compaction uses the turn ledger for fencing and
+        // recovery, but it is maintenance rather than a conversational turn.
+        // The dedicated session.context.compacted notice is the complete UI
+        // truth; adding a generic turn chip would falsely make it look like an
+        // extra agent response.
+        if (payload.maintenance === "context_compaction") {
+          finalizeOpen(turnId);
+          break;
+        }
+        // Credit exhaustion arrives as a NOMINALLY completed turn (`detail:
+        // "insufficient OpenGeni credits"`, `segmentLimit: "budget_exhausted"`)
+        // — the engine ended the segment early, it did not finish the work.
+        // Rendering it as a clean "complete" turn is a lie that leaves the
+        // session looking healthy while every future turn silently dies, so it
+        // projects exactly like a failed turn plus an explicit notice.
+        if (isCreditExhaustionPayload(payload)) {
+          finalizeOpen(turnId);
+          items.push(turnEndItem(event, "failed", CREDIT_EXHAUSTION_MESSAGE));
+          items.push({
+            kind: "notice",
+            id: event.id,
+            tone: "failed",
+            text: CREDIT_EXHAUSTION_MESSAGE,
+            occurredAt: event.occurredAt,
+          });
+          break;
+        }
         finalizeOpen(turnId);
         items.push(turnEndItem(event, "complete", null));
         break;
@@ -335,7 +490,12 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
 
       case "turn.failed": {
         const hadActivity = hasTurnActivity(items, turnId);
-        const failureText = failureMessage(payload);
+        // Credit death can hide behind fields `failureMessage` doesn't read
+        // (detail/segmentLimit), so classify the whole payload before falling
+        // back to the generic error/message extraction.
+        const failureText = isCreditExhaustionPayload(payload)
+          ? CREDIT_EXHAUSTION_MESSAGE
+          : failureMessage(payload);
         // The TURN failed — the in-flight items did not. Chip doctrine: red is
         // spent once, on the turn-level outcome. Items caught mid-flight read
         // as calm "interrupted" (same as turn.cancelled); an item that itself
@@ -376,11 +536,25 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
         break;
       }
 
+      case "memory.saved":
+      case "memory.corrected": {
+        // A first-party memory write is a discrete step, not streamed text, so it
+        // ends whatever was streaming (mirrors tool/sandbox pushes). A payload
+        // missing the memory id is malformed and dropped rather than shown blank.
+        const memory = memoryItem(event.id, event.type, turnId, payload, event.occurredAt);
+        if (memory) {
+          closeStreamingTail();
+          items.push(memory);
+        }
+        break;
+      }
+
       case "goal.set":
       case "goal.updated":
       case "goal.completed":
       case "goal.paused":
       case "goal.resumed":
+      case "goal.cleared":
       case "goal.continuation": {
         items.push({
           kind: "goal",
@@ -400,6 +574,37 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
   return items;
 }
 
+/** The turn-end payload shape, as `isCreditExhaustion` wants it. */
+function isCreditExhaustionPayload(payload: Record<string, unknown>): boolean {
+  return isCreditExhaustion({
+    error: typeof payload.error === "string" ? payload.error : null,
+    detail: typeof payload.detail === "string" ? payload.detail : null,
+    segmentLimit: typeof payload.segmentLimit === "string" ? payload.segmentLimit : null,
+  });
+}
+
+/**
+ * Whether the session's most recent turn ended in credit exhaustion — the
+ * terminal credit state apps key their "add credits" affordances on. Derived
+ * from the LAST turn-end event (completed/failed/cancelled): a later turn that
+ * settles any other way (someone topped up and kept working) clears it.
+ */
+export function creditExhaustedFromEvents(events: SessionEvent[]): boolean {
+  const ordered = [...events].sort((a, b) => a.sequence - b.sequence);
+  for (let index = ordered.length - 1; index >= 0; index -= 1) {
+    const event = ordered[index];
+    if (
+      event?.type !== "turn.completed" &&
+      event?.type !== "turn.failed" &&
+      event?.type !== "turn.cancelled"
+    ) {
+      continue;
+    }
+    return isCreditExhaustionPayload(asRecord(event.payload));
+  }
+  return false;
+}
+
 /** The latest session status carried in the event log, if any. */
 export function sessionStatusFromEvents(events: SessionEvent[]): SessionStatus | null {
   for (let index = events.length - 1; index >= 0; index -= 1) {
@@ -432,6 +637,7 @@ function isActivityItem(item: TimelineItem): item is ActivityItem {
     case "tool-call":
     case "worker":
     case "sandbox":
+    case "memory":
       return true;
     default:
       return false;
@@ -462,8 +668,6 @@ export function groupTimeline(items: TimelineItem[]): TimelineGroup[] {
 
 /* --- helpers ---------------------------------------------------------------- */
 
-type TimelineEvent = SessionEvent & { pendingUserMessage?: true };
-
 type TurnAnchorPrescan = {
   queuedTurnByTrigger: Map<string, string>;
   startSeqByTrigger: Map<string, number>;
@@ -483,7 +687,8 @@ function prescanTurnAnchors(events: SessionEvent[]): TurnAnchorPrescan {
     const payload = asRecord(event.payload);
     const turnId = event.turnId ?? null;
     if (event.type === "turn.queued") {
-      const triggerEventId = typeof payload.triggerEventId === "string" ? payload.triggerEventId : null;
+      const triggerEventId =
+        typeof payload.triggerEventId === "string" ? payload.triggerEventId : null;
       const queuedTurnId = typeof payload.turnId === "string" ? payload.turnId : turnId;
       if (triggerEventId && queuedTurnId) {
         queuedTurnByTrigger.set(triggerEventId, queuedTurnId);
@@ -491,8 +696,9 @@ function prescanTurnAnchors(events: SessionEvent[]): TurnAnchorPrescan {
       continue;
     }
     if (event.type === "turn.started") {
-      const triggerEventId = typeof payload.triggerEventId === "string" ? payload.triggerEventId : null;
-      if (triggerEventId) {
+      const triggerEventId =
+        typeof payload.triggerEventId === "string" ? payload.triggerEventId : null;
+      if (triggerEventId && !startSeqByTrigger.has(triggerEventId)) {
         startSeqByTrigger.set(triggerEventId, event.sequence);
       }
       if (turnId) {
@@ -524,7 +730,11 @@ function prescanTurnAnchors(events: SessionEvent[]): TurnAnchorPrescan {
 
   const cancelledBeforeStartTriggers = new Set<string>();
   for (const [triggerEventId, turnId] of queuedTurnByTrigger) {
-    if (cancelledTurnIds.has(turnId) && !startSeqByTrigger.has(triggerEventId) && !fallbackSeqByTurn.has(turnId)) {
+    if (
+      cancelledTurnIds.has(turnId) &&
+      !startSeqByTrigger.has(triggerEventId) &&
+      !fallbackSeqByTurn.has(turnId)
+    ) {
       cancelledBeforeStartTriggers.add(triggerEventId);
     }
   }
@@ -532,10 +742,9 @@ function prescanTurnAnchors(events: SessionEvent[]): TurnAnchorPrescan {
   return { queuedTurnByTrigger, startSeqByTrigger, cancelledBeforeStartTriggers, startedTurnIds };
 }
 
-function orderTimelineEvents(events: SessionEvent[], prescan: TurnAnchorPrescan): TimelineEvent[] {
+function orderTimelineEvents(events: SessionEvent[], prescan: TurnAnchorPrescan): SessionEvent[] {
   const ordered = [...events].sort((a, b) => a.sequence - b.sequence);
-  const insertions = new Map<number, TimelineEvent[]>();
-  const pending: TimelineEvent[] = [];
+  const insertions = new Map<number, SessionEvent[]>();
 
   for (const event of ordered) {
     if (event.type !== "user.message") {
@@ -554,10 +763,12 @@ function orderTimelineEvents(events: SessionEvent[], prescan: TurnAnchorPrescan)
       pushInsertion(insertions, startSeq, event);
       continue;
     }
-    pending.push({ ...event, pendingUserMessage: true });
+    // A waiting prompt belongs only in the prompt queue. It enters the
+    // timeline at turn.started (or the first same-turn activity fallback),
+    // never as a second queued representation.
   }
 
-  const projected: TimelineEvent[] = [];
+  const projected: SessionEvent[] = [];
   for (const event of ordered) {
     const before = insertions.get(event.sequence);
     if (before) {
@@ -567,11 +778,14 @@ function orderTimelineEvents(events: SessionEvent[], prescan: TurnAnchorPrescan)
       projected.push(event);
     }
   }
-  projected.push(...pending);
   return projected;
 }
 
-function pushInsertion(insertions: Map<number, TimelineEvent[]>, sequence: number, event: SessionEvent): void {
+function pushInsertion(
+  insertions: Map<number, SessionEvent[]>,
+  sequence: number,
+  event: SessionEvent,
+): void {
   const bucket = insertions.get(sequence);
   if (bucket) {
     bucket.push(event);
@@ -633,7 +847,10 @@ function stampTurnOutcome(groups: TimelineGroup[], turnEnd: TurnEndItem): void {
   }
 }
 
-function applyTurnOutcome(group: Extract<TimelineGroup, { kind: "activity" }>, turnEnd: TurnEndItem): void {
+function applyTurnOutcome(
+  group: Extract<TimelineGroup, { kind: "activity" }>,
+  turnEnd: TurnEndItem,
+): void {
   // A sub-cluster reports ITS OWN outcome, not the turn's. When a turn fails
   // at step 7, clusters 1–6 completed — painting them all red says "everything
   // broke" when one thing did. The turn-level fold carries the turn outcome;
@@ -644,7 +861,9 @@ function applyTurnOutcome(group: Extract<TimelineGroup, { kind: "activity" }>, t
     return;
   }
   const hasFailed = group.items.some((item) => "status" in item && item.status === "failed");
-  const hasInterrupted = group.items.some((item) => "status" in item && item.status === "cancelled");
+  const hasInterrupted = group.items.some(
+    (item) => "status" in item && item.status === "cancelled",
+  );
   group.outcome = hasFailed ? "failed" : hasInterrupted ? "cancelled" : "complete";
   if (turnEnd.failureText && hasFailed) {
     group.failureText = turnEnd.failureText;
@@ -695,7 +914,11 @@ function foldSettledTurn(groups: TimelineGroup[], turnEnd: TurnEndItem): void {
     turnGroup.failureText = turnEnd.failureText;
   }
 
-  groups.splice(startIndex, collected.length, ...(finalMessage ? [turnGroup, finalMessage] : [turnGroup]));
+  groups.splice(
+    startIndex,
+    collected.length,
+    ...(finalMessage ? [turnGroup, finalMessage] : [turnGroup]),
+  );
 }
 
 function isTurnBoundary(group: TimelineGroup | undefined): boolean {
@@ -707,16 +930,31 @@ function belongsToDifferentTurn(group: TimelineGroup | undefined, turnId: string
     return false;
   }
   if (group.kind === "activity") {
-    return group.items.length > 0 && group.items.every((item) => item.turnId !== null && item.turnId !== turnId);
+    return (
+      group.items.length > 0 &&
+      group.items.every((item) => item.turnId !== null && item.turnId !== turnId)
+    );
   }
-  return group.kind === "item" && group.item.kind === "agent-message" && group.item.turnId !== null && group.item.turnId !== turnId;
+  return (
+    group.kind === "item" &&
+    group.item.kind === "agent-message" &&
+    group.item.turnId !== null &&
+    group.item.turnId !== turnId
+  );
 }
 
 function isBetweenTurnDivider(group: TimelineGroup | undefined): boolean {
-  return group?.kind === "item" && group.item.kind === "session-status" && group.item.status !== "running";
+  return (
+    group?.kind === "item" &&
+    group.item.kind === "session-status" &&
+    group.item.status !== "running"
+  );
 }
 
-function extractFinalAgentMessage(groups: TimelineGroup[], turnEnd: TurnEndItem): Extract<TimelineGroup, { kind: "item" }> | null {
+function extractFinalAgentMessage(
+  groups: TimelineGroup[],
+  turnEnd: TurnEndItem,
+): Extract<TimelineGroup, { kind: "item" }> | null {
   const tail = groups[groups.length - 1];
   if (tail?.kind !== "item" || tail.item.kind !== "agent-message" || tail.item.streaming) {
     return null;
@@ -745,10 +983,21 @@ function asRecord(value: unknown): Record<string, unknown> {
   return value !== null && typeof value === "object" ? (value as Record<string, unknown>) : {};
 }
 
-const SESSION_STATUSES: readonly SessionStatus[] = ["queued", "running", "idle", "requires_action", "failed", "cancelled"];
+const SESSION_STATUSES: readonly SessionStatus[] = [
+  "queued",
+  "running",
+  "idle",
+  "requires_action",
+  "failed",
+  "cancelled",
+];
 
 /** Statuses that demand the reader's attention and so earn a timeline divider. */
-const ATTENTION_STATUSES: ReadonlySet<SessionStatus> = new Set(["requires_action", "failed", "cancelled"]);
+const ATTENTION_STATUSES: ReadonlySet<SessionStatus> = new Set([
+  "requires_action",
+  "failed",
+  "cancelled",
+]);
 
 /** Keep only entries that match the wire shapes; user payloads are untyped. */
 function resourceRefs(value: unknown): import("@opengeni/sdk").ResourceRef[] {
@@ -774,6 +1023,43 @@ function toolRefs(value: unknown): import("@opengeni/sdk").ToolRef[] {
   });
 }
 
+function workerCompletionPayload(value: unknown): {
+  childSessionId: string;
+  childStatus: string;
+  goalStatus: string | null;
+  goalText: string | null;
+  evidence: string | null;
+  pausedReason: string | null;
+} | null {
+  const payload = asRecord(value);
+  const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+  if (
+    typeof payload.childSessionId !== "string" ||
+    !uuidPattern.test(payload.childSessionId) ||
+    typeof payload.status !== "string" ||
+    payload.status.trim() === ""
+  ) {
+    return null;
+  }
+  const goal = asRecord(payload.goal);
+  return {
+    childSessionId: payload.childSessionId,
+    childStatus: payload.status,
+    goalStatus: typeof goal.status === "string" ? goal.status : null,
+    goalText: typeof goal.text === "string" ? goal.text : null,
+    evidence: typeof goal.evidence === "string" ? goal.evidence : null,
+    // Console pauses and several server paths put the human explanation on
+    // `rationale`, not `pausedReason` — same fallback the goal pill uses, so a
+    // paused worker card never shows "Worker paused" with the reason missing.
+    pausedReason:
+      typeof goal.pausedReason === "string"
+        ? goal.pausedReason
+        : typeof goal.rationale === "string"
+          ? goal.rationale
+          : null,
+  };
+}
+
 function isSessionStatus(value: unknown): value is SessionStatus {
   return typeof value === "string" && (SESSION_STATUSES as readonly string[]).includes(value);
 }
@@ -784,23 +1070,36 @@ function isErrorOutput(payload: Record<string, unknown>): boolean {
     return true;
   }
   const output = payload.output;
-  return !!output && typeof output === "object" && (output as { isError?: unknown }).isError === true;
+  return (
+    !!output && typeof output === "object" && (output as { isError?: unknown }).isError === true
+  );
 }
 
-function findOpenCall(items: TimelineItem[], callId: string | null): ToolCallItem | WorkerItem | undefined {
+function findOpenCall(
+  items: TimelineItem[],
+  callId: string | null,
+): ToolCallItem | WorkerItem | undefined {
   const reversed = [...items].reverse();
-  const isCall = (item: TimelineItem): item is ToolCallItem | WorkerItem => item.kind === "tool-call" || item.kind === "worker";
+  const isCall = (item: TimelineItem): item is ToolCallItem | WorkerItem =>
+    item.kind === "tool-call" || item.kind === "worker";
   if (callId) {
     const byId = reversed.find((item) => isCall(item) && item.callId === callId);
     if (byId) {
       return byId as ToolCallItem | WorkerItem;
     }
   }
-  return reversed.find((item): item is ToolCallItem | WorkerItem => isCall(item) && item.status === "running");
+  return reversed.find(
+    (item): item is ToolCallItem | WorkerItem => isCall(item) && item.status === "running",
+  );
 }
 
 function findOpenSandbox(items: TimelineItem[], name: string): SandboxItem | undefined {
-  return [...items].reverse().find((item): item is SandboxItem => item.kind === "sandbox" && item.name === name && item.status === "running");
+  return [...items]
+    .reverse()
+    .find(
+      (item): item is SandboxItem =>
+        item.kind === "sandbox" && item.name === name && item.status === "running",
+    );
 }
 
 function failureMessage(payload: Record<string, unknown>): string | null {
@@ -829,20 +1128,61 @@ function goalText(payload: Record<string, unknown>): string | null {
   return null;
 }
 
-function authNeededNoticeText(payload: Record<string, unknown>): string {
-  const provider =
-    typeof payload.providerDomain === "string" && payload.providerDomain.trim().length > 0 ? payload.providerDomain.trim() : "This service";
-  const scopes = Array.isArray(payload.scopes)
-    ? payload.scopes.filter((scope): scope is string => typeof scope === "string" && scope.trim().length > 0)
-    : [];
-
-  if (payload.reason === "insufficient_scope") {
-    return scopes.length > 0 ? `${provider} needs additional access (${scopes.join(", ")}).` : `${provider} needs additional access.`;
-  }
-  if (payload.reason === "expired" || payload.reason === "refresh_failed") {
-    return `${provider} needs to be reconnected.`;
+/**
+ * Fold a `memory.saved` / `memory.corrected` event into a {@link MemoryItem}.
+ * Reads DEFENSIVELY (the payload is untyped `unknown`, no Zod schema): a missing
+ * memory id means a malformed event, so we return null and the case drops it.
+ */
+function memoryItem(
+  id: string,
+  type: string,
+  turnId: string | null,
+  payload: Record<string, unknown>,
+  occurredAt: string,
+): MemoryItem | null {
+  const memoryId =
+    typeof payload.memoryId === "string" && payload.memoryId ? payload.memoryId : null;
+  if (!memoryId) {
+    return null;
   }
-  return `${provider} needs a connection.`;
+  const replacementPreview =
+    typeof payload.replacementPreview === "string" ? payload.replacementPreview : undefined;
+  const replacementMemoryId =
+    typeof payload.replacementMemoryId === "string" ? payload.replacementMemoryId : undefined;
+  const action = typeof payload.action === "string" ? payload.action : undefined;
+  return {
+    kind: "memory",
+    id,
+    turnId,
+    variant: type === "memory.corrected" ? "corrected" : "saved",
+    memoryKind: typeof payload.kind === "string" ? payload.kind : "",
+    preview: typeof payload.preview === "string" ? payload.preview : "",
+    ...(payload.deduped === true ? { deduped: true } : {}),
+    ...(replacementPreview ? { replacementPreview } : {}),
+    ...(action ? { action } : {}),
+    memoryId,
+    ...(replacementMemoryId ? { replacementMemoryId } : {}),
+    occurredAt,
+  };
+}
+
+const AUTH_NEEDED_REASONS: ReadonlySet<string> = new Set([
+  "missing_connection",
+  "expired",
+  "insufficient_scope",
+  "refresh_failed",
+]);
+
+function authNeededReason(value: unknown): AuthNeededItem["reason"] {
+  return typeof value === "string" && AUTH_NEEDED_REASONS.has(value)
+    ? (value as AuthNeededItem["reason"])
+    : null;
+}
+
+function stringList(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((entry): entry is string => typeof entry === "string" && entry.trim().length > 0)
+    : [];
 }
 
 function reasoningText(payload: unknown): string {
@@ -874,12 +1214,6 @@ function workerPrompt(args: unknown): string | null {
   return null;
 }
 
-/** The interrupt mode from `session_interrupt` args; defaults to "stop". */
-function workerInterruptMode(args: unknown): "stop" | "steer" {
-  const record = asRecord(typeof args === "string" ? tryParseJson(args) : args);
-  return record.mode === "steer" ? "steer" : "stop";
-}
-
 /**
  * Find a session id in orchestration tool arguments or output. Handles raw
  * objects, JSON strings, and MCP tool results (`{ content: [{ type: "text",
@@ -908,7 +1242,11 @@ export function extractSessionRef(value: unknown, depth = 0): string | null {
   if (typeof record.sessionId === "string" && looksLikeId(record.sessionId)) {
     return record.sessionId;
   }
-  if (typeof record.id === "string" && looksLikeId(record.id) && ("status" in record || "workspaceId" in record || "initialMessage" in record)) {
+  if (
+    typeof record.id === "string" &&
+    looksLikeId(record.id) &&
+    ("status" in record || "workspaceId" in record || "initialMessage" in record)
+  ) {
     return record.id;
   }
   for (const key of ["structuredContent", "session", "result", "content"] as const) {
@@ -929,7 +1267,20 @@ function looksLikeId(value: string): boolean {
   return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value);
 }
 
-/** Readable label for a tool call ("session_create" -> "session create"). */
+/**
+ * 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
+ * ("mcp-integrations-sh-supabase-com-34ed9dcf1390-0i6tcf8"). De-slugging the
+ * whole thing leaked that id into the timeline; strip the server prefix and show
+ * just the tool ("list organizations"). Names without the `__` boundary (plain
+ * built-ins like "session_create") are unaffected.
+ */
 export function toolDisplayName(name: string): string {
-  return name.replace(/[_-]+/g, " ").trim();
+  // 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();
 }