@opengeni/react 0.52.1 → 0.57.0

package/src/model-policy.ts

@@ -1,6 +1,10 @@
 import type { ClientModel, ReasoningEffort, WorkspaceModelCatalogModel } from "@opengeni/sdk";
 
-export type PickerBillingClass = "opengeni_credits" | "codex_subscription" | "byok";
+export type PickerBillingClass =
+  | "opengeni_credits"
+  | "codex_subscription"
+  | "supergrok_subscription"
+  | "byok";
 
 export type PickerModelRow<TCatalog extends ClientModel = WorkspaceModelCatalogModel> = {
   id: string;
@@ -21,12 +25,14 @@ export type LatencyModeId = "standard" | "priority" | "fast";
 const BILLING_CLASS_ORDER: PickerBillingClass[] = [
   "opengeni_credits",
   "codex_subscription",
+  "supergrok_subscription",
   "byok",
 ];
 
 const BILLING_CLASS_LABELS: Record<PickerBillingClass, string> = {
   opengeni_credits: "OpenGeni",
   codex_subscription: "Codex",
+  supergrok_subscription: "SuperGrok",
   byok: "Your Gateway",
 };
 
@@ -41,6 +47,9 @@ const AVAILABILITY_REASON_LABELS: Record<string, string> = {
 };
 
 export function billingClassForModel(model: ClientModel): PickerBillingClass {
+  if (model.source === "supergrok") {
+    return "supergrok_subscription";
+  }
   if (model.source === "codex") {
     return "codex_subscription";
   }
@@ -48,7 +57,9 @@ export function billingClassForModel(model: ClientModel): PickerBillingClass {
     return "byok";
   }
   if (model.credentialSource?.kind === "connected_subscription") {
-    return "codex_subscription";
+    return model.credentialSource.provider === "xai"
+      ? "supergrok_subscription"
+      : "codex_subscription";
   }
   if (model.credentialSource?.kind === "workspace_connection") {
     return "byok";
@@ -135,7 +146,9 @@ export function payerSummaryForModel(model: ClientModel): string {
     return "OpenGeni credits · automatic managed route";
   }
   if (billing.upstreamPayer === "connected_subscription") {
-    return "Codex subscription · external billing";
+    return model.source === "supergrok"
+      ? "SuperGrok subscription · external billing"
+      : "Codex subscription · external billing";
   }
   if (billing.upstreamPayer === "workspace") {
     return "Billed to your AI Gateway";
@@ -149,7 +162,9 @@ export function advancedSourceSummary(model: ClientModel): string | null {
     return null;
   }
   if (source.kind === "connected_subscription") {
-    return "Connected Codex subscription";
+    return source.provider === "xai"
+      ? "Connected SuperGrok subscription"
+      : "Connected Codex subscription";
   }
   if (source.kind === "workspace_connection") {
     return "Workspace AI Gateway";

package/src/provider.tsx

@@ -3,6 +3,7 @@ import {
   OPENGENI_API_CONTRACT_REVISION,
   type StreamConnectionState,
   type WorkspaceControlEvent,
+  type WorkspaceInteractionRevisionEvent,
 } from "@opengeni/sdk";
 import { useCallback, useEffect, useMemo, useRef, useState, type ReactNode } from "react";
 import type { SessionClientLike } from "./client";
@@ -17,6 +18,7 @@ export type OpenGeniProviderProps = {
   client: SessionClientLike;
   workspaceId: string;
   onWorkspaceControlEvent?: ((event: WorkspaceControlEvent) => void) | undefined;
+  onWorkspaceInteractionEvent?: ((event: WorkspaceInteractionRevisionEvent) => void) | undefined;
   children?: ReactNode;
 };
 
@@ -28,6 +30,7 @@ export function OpenGeniProvider({
   client,
   workspaceId,
   onWorkspaceControlEvent,
+  onWorkspaceInteractionEvent,
   children,
 }: OpenGeniProviderProps) {
   const [workspaceControlEvent, setWorkspaceControlEvent] = useState<WorkspaceControlEvent | null>(
@@ -36,15 +39,25 @@ export function OpenGeniProvider({
   const [workspaceControlConnectionState, setWorkspaceControlConnectionState] = useState<
     StreamConnectionState | "idle" | "error"
   >("idle");
+  const [workspaceInteractionEvent, setWorkspaceInteractionEvent] =
+    useState<WorkspaceInteractionRevisionEvent | null>(null);
+  const [workspaceInteractionConnectionState, setWorkspaceInteractionConnectionState] = useState<
+    StreamConnectionState | "idle" | "error"
+  >("idle");
   const [contractMismatch, setContractMismatch] = useState<OpenGeniApiContractMismatchError | null>(
     null,
   );
   const callbackRef = useRef(onWorkspaceControlEvent);
+  const interactionCallbackRef = useRef(onWorkspaceInteractionEvent);
   const reconcilersRef = useRef(new Map<string, Map<string, () => Promise<void>>>());
   const reconcileInFlightRef = useRef(new Map<string, Promise<void>>());
   const workspaceControlSequencesRef = useRef(new Map<string, number>());
+  const workspaceInteractionSequencesRef = useRef(new Map<string, number>());
   const pageLive = usePageLiveActivity();
+  const supportsWorkspaceLiveStream =
+    "streamWorkspaceLiveEvents" in client && typeof client.streamWorkspaceLiveEvents === "function";
   callbackRef.current = onWorkspaceControlEvent;
+  interactionCallbackRef.current = onWorkspaceInteractionEvent;
 
   const verifyApiContract = useCallback(async (): Promise<void> => {
     try {
@@ -105,6 +118,78 @@ export function OpenGeniProvider({
   );
 
   useEffect(() => {
+    if (!supportsWorkspaceLiveStream) return;
+    const openLiveStream = client.streamWorkspaceLiveEvents!;
+    setWorkspaceControlEvent(null);
+    setWorkspaceInteractionEvent(null);
+    if (!pageLive) {
+      setWorkspaceControlConnectionState("idle");
+      setWorkspaceInteractionConnectionState("idle");
+      return;
+    }
+    const controller = new AbortController();
+    const setConnectionState = (state: StreamConnectionState) => {
+      setWorkspaceControlConnectionState(state);
+      setWorkspaceInteractionConnectionState(state);
+    };
+    setConnectionState("connecting");
+    void (async () => {
+      try {
+        await verifyApiContract();
+        const workspace = await client.getWorkspace(workspaceId);
+        const controlAfter = Math.max(
+          workspaceControlSequencesRef.current.get(workspaceId) ?? 0,
+          workspace.inferenceControl.revision,
+        );
+        const interactionAfter = workspaceInteractionSequencesRef.current.get(workspaceId) ?? 0;
+        workspaceControlSequencesRef.current.set(workspaceId, controlAfter);
+        const stream = openLiveStream.call(client, workspaceId, {
+          controlAfter,
+          interactionAfter,
+          signal: controller.signal,
+          onStateChange: setConnectionState,
+        });
+        for await (const event of stream) {
+          if (controller.signal.aborted) return;
+          if (event.type === "workspace.control.changed") {
+            workspaceControlSequencesRef.current.set(
+              workspaceId,
+              Math.max(workspaceControlSequencesRef.current.get(workspaceId) ?? 0, event.sequence),
+            );
+            setWorkspaceControlEvent((current) =>
+              !current || event.sequence > current.sequence ? event : current,
+            );
+            callbackRef.current?.(event);
+          } else {
+            workspaceInteractionSequencesRef.current.set(
+              workspaceId,
+              Math.max(
+                workspaceInteractionSequencesRef.current.get(workspaceId) ?? 0,
+                event.sequence,
+              ),
+            );
+            setWorkspaceInteractionEvent((current) =>
+              !current || event.sequence > current.sequence ? event : current,
+            );
+            interactionCallbackRef.current?.(event);
+          }
+        }
+      } catch (error) {
+        if (error instanceof OpenGeniApiContractMismatchError) {
+          setContractMismatch(error);
+          reloadForContractMismatchOnce(error);
+        }
+        if (!controller.signal.aborted) {
+          setWorkspaceControlConnectionState("error");
+          setWorkspaceInteractionConnectionState("error");
+        }
+      }
+    })();
+    return () => controller.abort();
+  }, [client, pageLive, supportsWorkspaceLiveStream, verifyApiContract, workspaceId]);
+
+  useEffect(() => {
+    if (supportsWorkspaceLiveStream) return;
     if (!pageLive) {
       setWorkspaceControlConnectionState("idle");
       return;
@@ -145,7 +230,50 @@ export function OpenGeniProvider({
       }
     })();
     return () => controller.abort();
-  }, [client, pageLive, verifyApiContract, workspaceId]);
+  }, [client, pageLive, supportsWorkspaceLiveStream, verifyApiContract, workspaceId]);
+
+  useEffect(() => {
+    if (supportsWorkspaceLiveStream) return;
+    setWorkspaceInteractionEvent(null);
+    if (!pageLive) {
+      setWorkspaceInteractionConnectionState("idle");
+      return;
+    }
+    const controller = new AbortController();
+    setWorkspaceInteractionConnectionState("connecting");
+    void (async () => {
+      try {
+        await verifyApiContract();
+        const resumeAfter = workspaceInteractionSequencesRef.current.get(workspaceId) ?? 0;
+        const stream = client.streamWorkspaceInteractionRevisions(workspaceId, {
+          after: resumeAfter,
+          signal: controller.signal,
+          onStateChange: setWorkspaceInteractionConnectionState,
+        });
+        for await (const event of stream) {
+          if (controller.signal.aborted) return;
+          workspaceInteractionSequencesRef.current.set(
+            workspaceId,
+            Math.max(
+              workspaceInteractionSequencesRef.current.get(workspaceId) ?? 0,
+              event.sequence,
+            ),
+          );
+          setWorkspaceInteractionEvent((current) =>
+            !current || event.sequence > current.sequence ? event : current,
+          );
+          interactionCallbackRef.current?.(event);
+        }
+      } catch (error) {
+        if (error instanceof OpenGeniApiContractMismatchError) {
+          setContractMismatch(error);
+          reloadForContractMismatchOnce(error);
+        }
+        if (!controller.signal.aborted) setWorkspaceInteractionConnectionState("error");
+      }
+    })();
+    return () => controller.abort();
+  }, [client, pageLive, supportsWorkspaceLiveStream, verifyApiContract, workspaceId]);
 
   const value = useMemo(
     () => ({
@@ -153,6 +281,8 @@ export function OpenGeniProvider({
       workspaceId,
       workspaceControlEvent,
       workspaceControlConnectionState,
+      workspaceInteractionEvent,
+      workspaceInteractionConnectionState,
       registerSessionReconciler,
       reconcileSession,
     }),
@@ -161,6 +291,8 @@ export function OpenGeniProvider({
       workspaceId,
       workspaceControlEvent,
       workspaceControlConnectionState,
+      workspaceInteractionEvent,
+      workspaceInteractionConnectionState,
       registerSessionReconciler,
       reconcileSession,
     ],

package/src/realtime/realtime-control.tsx

@@ -57,7 +57,7 @@ import {
 export type RealtimeModelOption = {
   id: SessionRealtimeModel;
   label: string;
-  provider: "OpenGeni" | "Connected Codex" | "Your Gateway";
+  provider: "OpenGeni" | "Connected Codex" | "Connected SuperGrok" | "Your Gateway";
   description: string;
   available: boolean;
   unavailableReason: string | null;
@@ -74,7 +74,12 @@ const CODEX_LIVE_MODEL: RealtimeModelOption = {
   recommended: false,
 };
 
-const REALTIME_MODEL_PROVIDERS = ["OpenGeni", "Connected Codex", "Your Gateway"] as const;
+const REALTIME_MODEL_PROVIDERS = [
+  "OpenGeni",
+  "Connected Codex",
+  "Connected SuperGrok",
+  "Your Gateway",
+] as const;
 type RealtimeModelProvider = (typeof REALTIME_MODEL_PROVIDERS)[number];
 
 const REALTIME_PROVIDER_META: Record<
@@ -86,6 +91,10 @@ const REALTIME_PROVIDER_META: Record<
     billingClass: "codex_subscription",
     hint: "ChatGPT / Codex plan",
   },
+  "Connected SuperGrok": {
+    billingClass: "supergrok_subscription",
+    hint: "SuperGrok / xAI plan",
+  },
   "Your Gateway": { billingClass: "byok", hint: "Billed to your AI Gateway" },
 };
 const REALTIME_MODEL_STORAGE_PREFIX = "opengeni:realtime-model";
@@ -141,7 +150,11 @@ export function useSessionRealtime(options: {
   const controllerRef = useRef<SessionRealtimeController | null>(null);
   const controllerModelRef = useRef<SessionRealtimeModel | null>(null);
   const [snapshot, setSnapshot] = useState<SessionRealtimeControllerSnapshot>(() => ({
-    status: hasStoredSessionRealtimeOwnerProof({ workspaceId, sessionId: options.sessionId, model })
+    status: hasStoredSessionRealtimeOwnerProof({
+      workspaceId,
+      sessionId: options.sessionId,
+      model,
+    })
       ? "recovering"
       : "idle",
     realtimeId: null,
@@ -684,7 +697,13 @@ export function RealtimeVoiceControl(props: {
                 opacity: 1,
                 transition: reduceMotion
                   ? { duration: 0 }
-                  : { delay: 0.32, type: "spring", stiffness: 320, damping: 30, mass: 0.8 },
+                  : {
+                      delay: 0.32,
+                      type: "spring",
+                      stiffness: 320,
+                      damping: 30,
+                      mass: 0.8,
+                    },
               }}
               {...(reduceMotion
                 ? {}
@@ -1160,7 +1179,11 @@ function statusContent(
         };
       }
       if (!canStart && admissionBlocker) {
-        return { phase: "unavailable", label: "Voice unavailable", detail: admissionBlocker };
+        return {
+          phase: "unavailable",
+          label: "Voice unavailable",
+          detail: admissionBlocker,
+        };
       }
       return {
         phase: "idle",
@@ -1268,7 +1291,11 @@ function RealtimeStatusDot(props: { phase: RealtimeVisualPhase; reduceMotion: bo
         <motion.span
           className="absolute inset-0 rounded-full bg-og-status-running"
           animate={{ opacity: [0.45, 0], scale: [1, 2.2] }}
-          transition={{ duration: 1.4, ease: "easeOut", repeat: Number.POSITIVE_INFINITY }}
+          transition={{
+            duration: 1.4,
+            ease: "easeOut",
+            repeat: Number.POSITIVE_INFINITY,
+          }}
         />
       ) : null}
       <span
@@ -1343,6 +1370,7 @@ function isRealtimeModel(value: string | null): value is SessionRealtimeModel {
     value === "opengeni-gateway/openai/gpt-realtime-2.1" ||
     value === "opengeni-gateway/openai/gpt-realtime-mini" ||
     value === "opengeni-gateway/xai/grok-voice-think-fast-2.0" ||
+    value === "supergrok/grok-voice-think-fast-2.0" ||
     value === "workspace-gateway/openai/gpt-realtime-2.1" ||
     value === "workspace-gateway/openai/gpt-realtime-mini" ||
     value === "workspace-gateway/xai/grok-voice-think-fast-2.0"

package/src/session-context.ts

@@ -1,4 +1,8 @@
-import type { StreamConnectionState, WorkspaceControlEvent } from "@opengeni/sdk";
+import type {
+  StreamConnectionState,
+  WorkspaceControlEvent,
+  WorkspaceInteractionRevisionEvent,
+} from "@opengeni/sdk";
 import { createContext, useContext } from "react";
 import type {
   EmbeddedFileAttachmentClientLike,
@@ -7,6 +11,7 @@ import type {
   EmbeddedBrowserInteractionClientLike,
   EmbeddedComputerInteractionClientLike,
   EmbeddedInteractionClientLike,
+  EmbeddedInterventionClientLike,
   EmbeddedRealtimeSessionClientLike,
   EmbeddedSessionClientLike,
   EmbeddedSessionLineageClientLike,
@@ -20,6 +25,8 @@ export type OpenGeniContextValue = {
   workspaceId: string;
   workspaceControlEvent: WorkspaceControlEvent | null;
   workspaceControlConnectionState: StreamConnectionState | "idle" | "error";
+  workspaceInteractionEvent: WorkspaceInteractionRevisionEvent | null;
+  workspaceInteractionConnectionState: StreamConnectionState | "idle" | "error";
   registerSessionReconciler: (
     sessionId: string,
     key: string,
@@ -84,6 +91,11 @@ export type EmbeddedInteractionClientOverride = {
   workspaceId?: string | undefined;
 };
 
+export type EmbeddedInterventionClientOverride = {
+  client?: EmbeddedInterventionClientLike | undefined;
+  workspaceId?: string | undefined;
+};
+
 export type EmbeddedBrowserInteractionClientOverride = {
   client?: EmbeddedBrowserInteractionClientLike | undefined;
   workspaceId?: string | undefined;
@@ -132,6 +144,8 @@ function useEmbeddedClientRefinement<TClient extends object>(
     workspaceId,
     workspaceControlEvent: context?.workspaceControlEvent ?? null,
     workspaceControlConnectionState: context?.workspaceControlConnectionState ?? "idle",
+    workspaceInteractionEvent: context?.workspaceInteractionEvent ?? null,
+    workspaceInteractionConnectionState: context?.workspaceInteractionConnectionState ?? "idle",
     registerSessionReconciler: context?.registerSessionReconciler ?? NOOP_REGISTER_RECONCILER,
     reconcileSession: context?.reconcileSession ?? NOOP_RECONCILE_SESSION,
   };
@@ -158,20 +172,46 @@ export function useOpenGeni(override: ClientOverride = {}): OpenGeniContextValue
     workspaceId,
     workspaceControlEvent: context?.workspaceControlEvent ?? null,
     workspaceControlConnectionState: context?.workspaceControlConnectionState ?? "idle",
+    workspaceInteractionEvent: context?.workspaceInteractionEvent ?? null,
+    workspaceInteractionConnectionState: context?.workspaceInteractionConnectionState ?? "idle",
     registerSessionReconciler: context?.registerSessionReconciler ?? NOOP_REGISTER_RECONCILER,
     reconcileSession: context?.reconcileSession ?? NOOP_RECONCILE_SESSION,
   };
 }
 
 const BROWSER_INTERACTION_METHODS = [
+  "streamWorkspaceInteractionRevisions",
+  "listNetworkRoutes",
+  "getNetworkRoute",
+  "createNetworkRoute",
+  "updateNetworkRoute",
+  "listSiteAuthConnections",
+  "getSiteAuthConnection",
+  "createSiteAuthConnection",
+  "updateSiteAuthConnection",
+  "listAuthRuns",
+  "getAuthRun",
+  "startBrowserAuthRun",
+  "reportBrowserAuthRun",
+  "protectedBrowserAuthFill",
+  "verifyBrowserAuthRun",
+  "listInteractionInterventions",
+  "getInteractionIntervention",
+  "createInteractionIntervention",
+  "resolveInteractionIntervention",
   "listAttachedBrowsers",
   "getAttachedBrowser",
   "listBrowserIdentities",
   "getBrowserIdentity",
   "createBrowserIdentity",
+  "updateBrowserIdentity",
   "listBrowserRevisions",
   "listBrowserSessions",
   "getBrowserSession",
+  "readBrowserClipboard",
+  "listBrowserDownloads",
+  "getBrowserDownload",
+  "saveBrowserDownload",
   "createBrowserSession",
   "listBrowserTargets",
   "openBrowserTarget",
@@ -190,8 +230,14 @@ const BROWSER_INTERACTION_METHODS = [
 ] as const;
 
 const COMPUTER_INTERACTION_METHODS = [
+  "streamWorkspaceInteractionRevisions",
+  "listInteractionInterventions",
+  "getInteractionIntervention",
+  "createInteractionIntervention",
+  "resolveInteractionIntervention",
   "listComputerSessions",
   "getComputerSession",
+  "readComputerClipboard",
   "createComputerSession",
   "listComputerTargets",
   "observeComputerTarget",
@@ -202,6 +248,25 @@ const COMPUTER_INTERACTION_METHODS = [
   "endComputerSession",
 ] as const;
 
+const INTERVENTION_METHODS = [
+  "streamWorkspaceInteractionRevisions",
+  "listInteractionInterventions",
+  "getInteractionIntervention",
+  "createInteractionIntervention",
+  "resolveInteractionIntervention",
+] as const;
+
+/** Resolve only the workspace-wide Browser/Computer intervention surface. */
+export function useEmbeddedInterventions(
+  override: EmbeddedInterventionClientOverride = {},
+): EmbeddedClientContextValue<EmbeddedInterventionClientLike> {
+  return useEmbeddedClientRefinement(
+    override,
+    INTERVENTION_METHODS,
+    "interaction intervention hooks",
+  );
+}
+
 /** Resolve only BrowserSession methods for a standalone Browser embed. */
 export function useEmbeddedBrowserInteraction(
   override: EmbeddedBrowserInteractionClientOverride = {},

package/src/timeline/activity-rail.tsx

@@ -417,6 +417,12 @@ function WorkerRow({
             {truncate(item.prompt, 140)}
           </p>
         ) : null}
+        {failed && item.failure ? (
+          <div className="mt-1 min-w-0 text-og-sm text-og-status-failed">
+            <p className="font-og-mono text-og-xs">{item.failure.code}</p>
+            <p className="mt-0.5 break-words">{item.failure.message}</p>
+          </div>
+        ) : null}
       </div>
       {failed ? (
         <span className="inline-flex shrink-0 self-center items-center gap-1.5 font-og-mono text-og-xs leading-none text-og-status-failed">

package/src/timeline/projection.ts

@@ -49,6 +49,8 @@ export { toolDisplayName, mcpToolLeaf, toolMatchesLeaf } from "./tool-display-na
 /** Tool leaves 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_FAILURE_CODE_MAX_LENGTH = 128;
+const WORKER_FAILURE_MESSAGE_MAX_UTF8_BYTES = 1_024;
 
 /**
  * Tools whose durable side-effect events already own the timeline (MemoryRow).
@@ -359,6 +361,7 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
             action: toolMatchesLeaf(name, WORKER_SPAWN_TOOL) ? "spawn" : "message",
             prompt: workerPrompt(args),
             workerSessionId: extractSessionRef(args),
+            failure: null,
             status: "running",
             occurredAt: event.occurredAt,
           });
@@ -417,6 +420,7 @@ export function buildTimeline(events: SessionEvent[]): TimelineItem[] {
           // isError result) settles to "failed" too, so WorkerRow surfaces it.
           target.status = isErrorOutput(payload) ? "failed" : "complete";
           target.workerSessionId = target.workerSessionId ?? extractSessionRef(payload.output);
+          target.failure = target.status === "failed" ? workerFailure(payload.output) : null;
           break;
         }
         // An output carrying an explicit error flag (or an MCP isError result)
@@ -1300,6 +1304,8 @@ function isTurnBoundary(group: TimelineGroup | undefined): boolean {
     (group?.kind === "item" &&
       (group.item.kind === "user-message" ||
         group.item.kind === "context-compaction" ||
+        (group.item.kind === "machine-input-batch" &&
+          group.item.members.some((member) => member.kind === "media_generation_result")) ||
         (group.item.kind === "notice" && group.item.tone === "input")))
   );
 }
@@ -1795,6 +1801,58 @@ function workerPrompt(args: unknown): string | null {
   return null;
 }
 
+function boundedWorkerFailureMessage(value: string): string | null {
+  const normalized = value.replace(/[\u0000-\u001f\u007f]+/g, " ").trim();
+  if (!normalized) return null;
+  const encoded = new TextEncoder().encode(normalized);
+  if (encoded.byteLength <= WORKER_FAILURE_MESSAGE_MAX_UTF8_BYTES) return normalized;
+  let end = WORKER_FAILURE_MESSAGE_MAX_UTF8_BYTES;
+  while (end > 0 && (encoded[end]! & 0xc0) === 0x80) end -= 1;
+  return new TextDecoder().decode(encoded.slice(0, end)).trim();
+}
+
+function boundedWorkerFailure(value: unknown): WorkerItem["failure"] {
+  const record = asRecord(value);
+  const code = typeof record.code === "string" ? record.code.trim() : "";
+  const message =
+    typeof record.message === "string" ? boundedWorkerFailureMessage(record.message) : null;
+  if (!/^[A-Za-z0-9._:-]{1,128}$/.test(code) || !message) return null;
+  return { code: code.slice(0, WORKER_FAILURE_CODE_MAX_LENGTH), message };
+}
+
+/**
+ * Extract the API's structured orchestration failure from raw objects, JSON
+ * text, or retained MCP CallToolResult wrappers. Legacy flat strings remain
+ * unprojected rather than being mistaken for the trusted diagnostic contract.
+ */
+function workerFailure(value: unknown, depth = 0): WorkerItem["failure"] {
+  if (depth > 6 || value === null || value === undefined) return null;
+  if (typeof value === "string") {
+    const parsed = tryParseJson(value);
+    return parsed === value ? null : workerFailure(parsed, depth + 1);
+  }
+  if (Array.isArray(value)) {
+    for (const entry of value) {
+      const failure = workerFailure(entry, depth + 1);
+      if (failure) return failure;
+    }
+    return null;
+  }
+  if (typeof value !== "object") return null;
+  const record = value as Record<string, unknown>;
+  const direct = boundedWorkerFailure(record.error);
+  if (direct) return direct;
+  for (const key of ["structuredContent", "content", "result", "output"] as const) {
+    if (!(key in record)) continue;
+    const failure = workerFailure(record[key], depth + 1);
+    if (failure) return failure;
+  }
+  if (record.type === "text" && typeof record.text === "string") {
+    return workerFailure(record.text, depth + 1);
+  }
+  return null;
+}
+
 /**
  * Find a session id in orchestration tool arguments or output. Handles raw
  * objects, JSON strings, and MCP tool results (`{ content: [{ type: "text",

package/src/timeline/types.ts

@@ -127,6 +127,8 @@ export type WorkerItem = {
   prompt: string | null;
   /** The target/spawned worker session id, when parseable from args/output. */
   workerSessionId: string | null;
+  /** Bounded structured failure retained from session_create/session_send_message. */
+  failure: { code: string; message: string } | null;
   status: "running" | "complete" | "failed" | "cancelled";
   occurredAt: string;
 };