@assistant-ui/react-ag-ui 0.0.29 → 0.0.31

package/src/runtime/adapter/run-aggregator.ts

@@ -2,12 +2,19 @@
 
 import type {
   ChatModelRunResult,
+  MessageTiming,
   ThreadAssistantMessagePart,
   ToolCallMessagePart,
 } from "@assistant-ui/core";
-import type { AgUiEvent } from "../types";
+import type { AgUiEvent, AgUiInterrupt } from "../types";
 import type { Logger } from "../logger";
 
+export const AG_UI_METADATA_NAMESPACE = "agui";
+
+export type AgUiCustomMetadata = {
+  interrupts?: AgUiInterrupt[];
+};
+
 type Emit = (update: ChatModelRunResult) => void;
 
 type ToolCallState = {
@@ -18,12 +25,14 @@ type ToolCallState = {
   result: unknown;
   isError: boolean | undefined;
   parentMessageId?: string;
+  toolMessageId?: string;
 };
 
 export type RunAggregatorOptions = {
   showThinking: boolean;
   logger: Logger;
   emit: Emit;
+  onServerMessageId?: (messageId: string) => void;
 };
 
 /**
@@ -36,53 +45,75 @@ export class RunAggregator {
   private readonly emitUpdate: Emit;
   private readonly showThinking: boolean;
   private readonly logger: Logger;
+  private readonly onServerMessageId: ((messageId: string) => void) | undefined;
 
   private status: ChatModelRunResult["status"] | undefined;
+  private interrupts: AgUiInterrupt[] | undefined;
   private readonly textParts = new Map<
     string,
     { buffer: string; touched: boolean }
   >();
   private activeTextMessageId: string | undefined;
-  private reasoningBuffer = "";
-  private reasoningActive = false;
+  private readonly reasoningParts = new Map<string, string>(); // key → buffer
+  private activeReasoningKey: string | undefined;
+  private reasoningPartCounter = 0;
   private readonly toolCalls = new Map<string, ToolCallState>();
   private readonly partOrder: (
     | { kind: "text"; key: string }
-    | { kind: "reasoning" }
+    | { kind: "reasoning"; key: string }
     | { kind: "tool-call"; toolCallId: string }
   )[] = [];
-  private hasReasoningPart = false;
   private textPartCounter = 0;
+  private serverMessageIdReported = false;
+
+  private streamStartTime: number | undefined;
+  private firstTokenTime: number | undefined;
+  private totalChunks = 0;
 
   constructor(options: RunAggregatorOptions) {
     this.emitUpdate = options.emit;
     this.showThinking = options.showThinking;
     this.logger = options.logger;
+    this.onServerMessageId = options.onServerMessageId;
   }
 
   handle(event: AgUiEvent): void {
     switch (event.type) {
       case "RUN_STARTED": {
         this.clearTextParts();
-        this.reasoningBuffer = "";
-        this.reasoningActive = false;
+        this.reasoningParts.clear();
+        this.activeReasoningKey = undefined;
+        this.reasoningPartCounter = 0;
         this.toolCalls.clear();
         this.partOrder.length = 0;
-        this.hasReasoningPart = false;
         this.textPartCounter = 0;
         this.activeTextMessageId = undefined;
+        this.interrupts = undefined;
+        this.serverMessageIdReported = false;
+        this.streamStartTime = Date.now();
+        this.firstTokenTime = undefined;
+        this.totalChunks = 0;
         this.status = { type: "running" };
         this.emit();
         break;
       }
       case "RUN_FINISHED": {
+        if (event.outcome?.type === "interrupt") {
+          this.interrupts = event.outcome.interrupts;
+          this.status = { type: "requires-action", reason: "interrupt" };
+          this.emit();
+          break;
+        }
+
+        this.interrupts = undefined;
         const hasUnresolvedToolCalls = Array.from(this.toolCalls.values()).some(
           (tc) => tc.result === undefined,
         );
 
-        this.status = hasUnresolvedToolCalls
-          ? { type: "requires-action", reason: "tool-calls" }
-          : { type: "complete", reason: "unknown" };
+        this.status =
+          event.outcome?.type === "success" || !hasUnresolvedToolCalls
+            ? { type: "complete", reason: "unknown" }
+            : { type: "requires-action", reason: "tool-calls" };
         this.emit();
         break;
       }
@@ -102,6 +133,7 @@ export class RunAggregator {
       }
 
       case "TEXT_MESSAGE_START": {
+        this.reportServerMessageId(event.messageId);
         const id = this.startTextMessage(event.messageId);
         if (id) {
           this.markTextPartTouched(id);
@@ -111,15 +143,18 @@ export class RunAggregator {
       }
       case "TEXT_MESSAGE_CONTENT":
       case "TEXT_MESSAGE_CHUNK": {
+        const incomingId = "messageId" in event ? event.messageId : undefined;
+        this.reportServerMessageId(incomingId);
         if (!event.delta) break;
-        const id = this.resolveTextMessageId(
-          "messageId" in event ? event.messageId : undefined,
-        );
+        this.recordFirstToken();
+        const id = this.resolveTextMessageId(incomingId);
         this.appendText(id, event.delta);
+        this.totalChunks++;
         this.emit();
         break;
       }
       case "TEXT_MESSAGE_END": {
+        this.reportServerMessageId(event.messageId);
         if (event.messageId && this.activeTextMessageId === event.messageId) {
           this.activeTextMessageId = undefined;
         }
@@ -131,11 +166,22 @@ export class RunAggregator {
       case "THINKING_TEXT_MESSAGE_START":
       case "REASONING_START":
       case "REASONING_MESSAGE_START":
-        this.handleReasoningStart();
+        this.handleReasoningStart(
+          "messageId" in event ? event.messageId : undefined,
+        );
         break;
       case "THINKING_TEXT_MESSAGE_CONTENT":
-      case "REASONING_MESSAGE_CONTENT":
         this.handleReasoningContent(event.delta);
+        this.totalChunks++;
+        this.recordFirstToken();
+        break;
+      case "REASONING_MESSAGE_CONTENT":
+        this.handleReasoningContent(
+          event.delta,
+          "messageId" in event ? event.messageId : undefined,
+        );
+        this.totalChunks++;
+        this.recordFirstToken();
         break;
       case "THINKING_TEXT_MESSAGE_END":
       case "THINKING_END":
@@ -145,6 +191,7 @@ export class RunAggregator {
         break;
 
       case "TOOL_CALL_START": {
+        this.reportServerMessageId(event.parentMessageId);
         this.startToolCall(
           event.toolCallId,
           event.toolCallName,
@@ -155,6 +202,9 @@ export class RunAggregator {
       }
       case "TOOL_CALL_ARGS":
       case "TOOL_CALL_CHUNK": {
+        if (event.type === "TOOL_CALL_CHUNK") {
+          this.reportServerMessageId(event.parentMessageId);
+        }
         if (!event.delta) break;
         this.appendToolArgs(event.toolCallId, event.delta);
         this.emit();
@@ -169,6 +219,7 @@ export class RunAggregator {
           event.toolCallId,
           event.content ?? "",
           event.role === "tool" ? false : undefined,
+          event.messageId,
         );
         this.emit();
         break;
@@ -180,6 +231,12 @@ export class RunAggregator {
     }
   }
 
+  private reportServerMessageId(messageId: string | undefined): void {
+    if (this.serverMessageIdReported || !messageId) return;
+    this.serverMessageIdReported = true;
+    this.onServerMessageId?.(messageId);
+  }
+
   private clearTextParts(): void {
     this.textParts.clear();
   }
@@ -244,6 +301,9 @@ export class RunAggregator {
     parentMessageId?: string,
   ) {
     if (!id) return;
+    // A new tool call acts as a boundary: any anonymous text that arrives
+    // after it should be a new part, not appended to the pre-tool text.
+    this.activeTextMessageId = undefined;
     if (
       !this.partOrder.some(
         (part) => part.kind === "tool-call" && part.toolCallId === id,
@@ -281,7 +341,12 @@ export class RunAggregator {
     }
   }
 
-  private finishToolCall(id: string, content: string, isError?: boolean) {
+  private finishToolCall(
+    id: string,
+    content: string,
+    isError?: boolean,
+    toolMessageId?: string,
+  ) {
     if (!id) return;
     let entry = this.toolCalls.get(id);
     if (!entry) {
@@ -304,6 +369,9 @@ export class RunAggregator {
     }
     entry.result = this.tryParseJSON(content);
     entry.isError = isError;
+    if (toolMessageId) {
+      entry.toolMessageId = toolMessageId;
+    }
   }
 
   private tryParseJSON(value: string): unknown {
@@ -320,14 +388,11 @@ export class RunAggregator {
 
     for (const part of this.partOrder) {
       if (part.kind === "reasoning") {
-        if (
-          this.showThinking &&
-          (this.reasoningActive || this.reasoningBuffer.length > 0)
-        ) {
-          snapshot.push({
-            type: "reasoning",
-            text: this.reasoningBuffer,
-          } as const);
+        if (this.showThinking) {
+          const buffer = this.reasoningParts.get(part.key) ?? "";
+          if (buffer.length > 0 || this.activeReasoningKey === part.key) {
+            snapshot.push({ type: "reasoning", text: buffer } as const);
+          }
         }
         continue;
       }
@@ -351,45 +416,104 @@ export class RunAggregator {
         ...(entry.result !== undefined ? { result: entry.result } : {}),
         ...(entry.isError !== undefined ? { isError: entry.isError } : {}),
         ...(entry.parentMessageId ? { parentId: entry.parentMessageId } : {}),
-      } as ToolCallMessagePart;
+        ...(entry.toolMessageId
+          ? { unstable_toolMessageId: entry.toolMessageId }
+          : {}),
+      } as ToolCallMessagePart & { unstable_toolMessageId?: string };
       snapshot.push(toolPart);
     }
 
+    const timing = this.getTiming();
+    const metadata = {
+      ...(timing ? { timing } : {}),
+      ...(this.interrupts
+        ? {
+            custom: {
+              [AG_UI_METADATA_NAMESPACE]: {
+                interrupts: this.interrupts,
+              } satisfies AgUiCustomMetadata,
+            },
+          }
+        : {}),
+    };
     const result: ChatModelRunResult = {
       content: snapshot,
       ...(this.status ? { status: this.status } : undefined),
+      ...(Object.keys(metadata).length > 0 ? { metadata } : undefined),
     };
     this.emitUpdate(result);
   }
 
-  private handleReasoningStart(): void {
+  private recordFirstToken(): void {
+    if (
+      this.firstTokenTime === undefined &&
+      this.streamStartTime !== undefined
+    ) {
+      this.firstTokenTime = Date.now() - this.streamStartTime;
+    }
+  }
+
+  private getTiming(): MessageTiming | undefined {
+    if (this.streamStartTime === undefined) return undefined;
+
+    const now = Date.now();
+    const totalStreamTime = now - this.streamStartTime;
+    const tokenCount =
+      this.totalChunks > 0
+        ? Math.ceil(
+            Array.from(this.textParts.values()).reduce(
+              (sum, p) => sum + p.buffer.length,
+              0,
+            ) / 4,
+          )
+        : undefined;
+    const tokensPerSecond =
+      tokenCount && totalStreamTime > 0
+        ? (tokenCount / totalStreamTime) * 1000
+        : undefined;
+
+    return {
+      streamStartTime: this.streamStartTime,
+      ...(this.firstTokenTime !== undefined
+        ? { firstTokenTime: this.firstTokenTime }
+        : {}),
+      totalStreamTime,
+      ...(tokenCount !== undefined ? { tokenCount } : {}),
+      ...(tokensPerSecond !== undefined ? { tokensPerSecond } : {}),
+      totalChunks: this.totalChunks,
+      toolCallCount: this.toolCalls.size,
+    };
+  }
+
+  private handleReasoningStart(messageId?: string): void {
     if (!this.showThinking) return;
-    this.reasoningActive = true;
-    this.ensureReasoningPart();
+    // A reasoning block acts as a boundary: anonymous text arriving after it
+    // should be a new part, not appended to any pre-reasoning text.
+    this.activeTextMessageId = undefined;
+    const key = messageId ?? `__auto-reasoning-${++this.reasoningPartCounter}`;
+    if (!this.reasoningParts.has(key)) {
+      this.reasoningParts.set(key, "");
+      this.partOrder.push({ kind: "reasoning", key });
+    }
+    this.activeReasoningKey = key;
     this.emit();
   }
 
-  private handleReasoningContent(delta: string): void {
+  private handleReasoningContent(delta: string, messageId?: string): void {
     if (!this.showThinking || !delta) return;
-    this.reasoningBuffer += delta;
-    this.ensureReasoningPart();
+    if (!this.activeReasoningKey) {
+      // Content arrived without a preceding START — create the slot lazily.
+      this.handleReasoningStart(messageId);
+    }
+    const key = this.activeReasoningKey;
+    if (!key) return;
+    this.reasoningParts.set(key, (this.reasoningParts.get(key) ?? "") + delta);
     this.emit();
   }
 
   private handleReasoningEnd(): void {
     if (!this.showThinking) return;
+    this.activeReasoningKey = undefined;
     this.emit();
   }
-
-  private ensureReasoningPart(): void {
-    if (this.hasReasoningPart) return;
-    // ensure reasoning appears before the first text segment if possible
-    const textIndex = this.partOrder.findIndex((part) => part.kind === "text");
-    if (textIndex === -1) {
-      this.partOrder.push({ kind: "reasoning" });
-    } else {
-      this.partOrder.splice(textIndex, 0, { kind: "reasoning" });
-    }
-    this.hasReasoningPart = true;
-  }
 }

package/src/runtime/adapter/subscriber.ts

@@ -2,6 +2,7 @@
 
 import type { AgUiEvent } from "../types";
 import { parseAgUiEvent } from "../event-parser";
+import type { Logger } from "../logger";
 
 type Dispatch = (event: AgUiEvent) => void;
 
@@ -31,6 +32,7 @@ type Subscriber = {
   onMessagesSnapshotEvent?: (payload: { event: unknown }) => void;
   onCustomEvent?: (payload: { event: unknown }) => void;
   onRawEvent?: (payload: { event: unknown }) => void;
+  onRunFinishedEvent?: (payload: { event: unknown }) => void;
   onRunFinalized?: () => void;
   onRunFailed?: (payload: { error: Error }) => void;
 };
@@ -38,37 +40,40 @@ type Subscriber = {
 const ensureEvent = (
   raw: unknown,
   type: AgUiEvent["type"],
+  logger?: Logger,
 ): AgUiEvent | null => {
+  const parseOptions = logger ? { logger } : undefined;
+  let parsed: AgUiEvent | null;
   if (raw && typeof raw === "object") {
     const payload = raw as Record<string, unknown>;
     if (typeof payload.type === "string") {
-      return parseAgUiEvent(payload);
+      parsed = parseAgUiEvent(payload, parseOptions);
+    } else {
+      parsed = parseAgUiEvent({ type, ...payload }, parseOptions);
     }
-    return parseAgUiEvent({ type, ...payload });
+  } else {
+    parsed = parseAgUiEvent({ type }, parseOptions);
   }
-  return parseAgUiEvent({ type });
-};
-
-const dispatchIfValid = (
-  dispatch: Dispatch,
-  raw: unknown,
-  type: AgUiEvent["type"],
-) => {
-  const event = ensureEvent(raw, type);
-  if (!event) return;
-  dispatch(event);
+  return parsed && parsed.type === type ? parsed : null;
 };
 
 type SubscriberOptions = {
   dispatch: Dispatch;
   runId: string;
+  logger?: Logger;
   onRunFailed?: (error: Error) => void;
 };
 
 export const createAgUiSubscriber = (
   options: SubscriberOptions,
 ): Subscriber => {
-  const { dispatch, runId, onRunFailed } = options;
+  const { dispatch, runId, logger, onRunFailed } = options;
+  let runFinishedDispatched = false;
+  const dispatchIfValid = (raw: unknown, type: AgUiEvent["type"]) => {
+    const event = ensureEvent(raw, type, logger);
+    if (!event) return;
+    dispatch(event);
+  };
   return {
     onEvent: ({ event }) => {
       const typeCandidate =
@@ -83,52 +88,57 @@ export const createAgUiSubscriber = (
       if (parsed) dispatch(parsed);
     },
     onTextMessageStartEvent: ({ event }) =>
-      dispatchIfValid(dispatch, event, "TEXT_MESSAGE_START"),
+      dispatchIfValid(event, "TEXT_MESSAGE_START"),
     onTextMessageContentEvent: ({ event }) =>
-      dispatchIfValid(dispatch, event, "TEXT_MESSAGE_CONTENT"),
+      dispatchIfValid(event, "TEXT_MESSAGE_CONTENT"),
     onTextMessageEndEvent: ({ event }) =>
-      dispatchIfValid(dispatch, event, "TEXT_MESSAGE_END"),
+      dispatchIfValid(event, "TEXT_MESSAGE_END"),
     onTextMessageChunkEvent: ({ event }) =>
-      dispatchIfValid(dispatch, event, "TEXT_MESSAGE_CHUNK"),
+      dispatchIfValid(event, "TEXT_MESSAGE_CHUNK"),
     onThinkingStartEvent: ({ event }) =>
-      dispatchIfValid(dispatch, event, "THINKING_START"),
-    onThinkingEndEvent: ({ event }) =>
-      dispatchIfValid(dispatch, event, "THINKING_END"),
+      dispatchIfValid(event, "THINKING_START"),
+    onThinkingEndEvent: ({ event }) => dispatchIfValid(event, "THINKING_END"),
     onThinkingTextMessageStartEvent: ({ event }) =>
-      dispatchIfValid(dispatch, event, "THINKING_TEXT_MESSAGE_START"),
+      dispatchIfValid(event, "THINKING_TEXT_MESSAGE_START"),
     onThinkingTextMessageContentEvent: ({ event }) =>
-      dispatchIfValid(dispatch, event, "THINKING_TEXT_MESSAGE_CONTENT"),
+      dispatchIfValid(event, "THINKING_TEXT_MESSAGE_CONTENT"),
     onThinkingTextMessageEndEvent: ({ event }) =>
-      dispatchIfValid(dispatch, event, "THINKING_TEXT_MESSAGE_END"),
+      dispatchIfValid(event, "THINKING_TEXT_MESSAGE_END"),
     onReasoningStartEvent: ({ event }) =>
-      dispatchIfValid(dispatch, event, "REASONING_START"),
-    onReasoningEndEvent: ({ event }) =>
-      dispatchIfValid(dispatch, event, "REASONING_END"),
+      dispatchIfValid(event, "REASONING_START"),
+    onReasoningEndEvent: ({ event }) => dispatchIfValid(event, "REASONING_END"),
     onReasoningMessageStartEvent: ({ event }) =>
-      dispatchIfValid(dispatch, event, "REASONING_MESSAGE_START"),
+      dispatchIfValid(event, "REASONING_MESSAGE_START"),
     onReasoningMessageContentEvent: ({ event }) =>
-      dispatchIfValid(dispatch, event, "REASONING_MESSAGE_CONTENT"),
+      dispatchIfValid(event, "REASONING_MESSAGE_CONTENT"),
     onReasoningMessageEndEvent: ({ event }) =>
-      dispatchIfValid(dispatch, event, "REASONING_MESSAGE_END"),
+      dispatchIfValid(event, "REASONING_MESSAGE_END"),
     onToolCallStartEvent: ({ event }) =>
-      dispatchIfValid(dispatch, event, "TOOL_CALL_START"),
+      dispatchIfValid(event, "TOOL_CALL_START"),
     onToolCallArgsEvent: ({ event }) =>
-      dispatchIfValid(dispatch, event, "TOOL_CALL_ARGS"),
-    onToolCallEndEvent: ({ event }) =>
-      dispatchIfValid(dispatch, event, "TOOL_CALL_END"),
+      dispatchIfValid(event, "TOOL_CALL_ARGS"),
+    onToolCallEndEvent: ({ event }) => dispatchIfValid(event, "TOOL_CALL_END"),
     onToolCallChunkEvent: ({ event }) =>
-      dispatchIfValid(dispatch, event, "TOOL_CALL_CHUNK"),
+      dispatchIfValid(event, "TOOL_CALL_CHUNK"),
     onToolCallResultEvent: ({ event }) =>
-      dispatchIfValid(dispatch, event, "TOOL_CALL_RESULT"),
+      dispatchIfValid(event, "TOOL_CALL_RESULT"),
     onStateSnapshotEvent: ({ event }) =>
-      dispatchIfValid(dispatch, event, "STATE_SNAPSHOT"),
-    onStateDeltaEvent: ({ event }) =>
-      dispatchIfValid(dispatch, event, "STATE_DELTA"),
+      dispatchIfValid(event, "STATE_SNAPSHOT"),
+    onStateDeltaEvent: ({ event }) => dispatchIfValid(event, "STATE_DELTA"),
     onMessagesSnapshotEvent: ({ event }) =>
-      dispatchIfValid(dispatch, event, "MESSAGES_SNAPSHOT"),
-    onCustomEvent: ({ event }) => dispatchIfValid(dispatch, event, "CUSTOM"),
-    onRawEvent: ({ event }) => dispatchIfValid(dispatch, event, "RAW"),
-    onRunFinalized: () => dispatch({ type: "RUN_FINISHED", runId }),
+      dispatchIfValid(event, "MESSAGES_SNAPSHOT"),
+    onCustomEvent: ({ event }) => dispatchIfValid(event, "CUSTOM"),
+    onRawEvent: ({ event }) => dispatchIfValid(event, "RAW"),
+    onRunFinishedEvent: ({ event }) => {
+      const parsed = ensureEvent(event, "RUN_FINISHED", logger);
+      if (!parsed) return;
+      runFinishedDispatched = true;
+      dispatch(parsed);
+    },
+    onRunFinalized: () => {
+      if (runFinishedDispatched) return;
+      dispatch({ type: "RUN_FINISHED", runId });
+    },
     onRunFailed: ({ error }) => {
       onRunFailed?.(error);
       const message =

package/src/runtime/event-parser.ts

@@ -1,4 +1,9 @@
-import type { AgUiEvent } from "./types";
+import type { AgUiEvent, AgUiInterrupt, AgUiRunFinishedOutcome } from "./types";
+import type { Logger } from "./logger";
+
+export type ParseAgUiEventOptions = {
+  logger?: Logger;
+};
 
 const isString = (value: unknown): value is string => typeof value === "string";
 const isNonEmptyString = (value: unknown): value is string =>
@@ -16,7 +21,57 @@ const withOptional = <T extends object>(
     : ({ ...base, ...Object.fromEntries(definedEntries) } as T);
 };
 
-export const parseAgUiEvent = (event: unknown): AgUiEvent | null => {
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+  !!value && typeof value === "object" && !Array.isArray(value);
+
+const parseInterrupt = (raw: unknown): AgUiInterrupt | null => {
+  if (!isPlainObject(raw)) return null;
+  const id = raw.id;
+  const reason = raw.reason;
+  if (typeof id !== "string" || typeof reason !== "string") return null;
+  const interrupt: AgUiInterrupt = { id, reason };
+  if (typeof raw.message === "string") interrupt.message = raw.message;
+  if (typeof raw.toolCallId === "string") interrupt.toolCallId = raw.toolCallId;
+  if (typeof raw.expiresAt === "string") interrupt.expiresAt = raw.expiresAt;
+  if (isPlainObject(raw.responseSchema))
+    interrupt.responseSchema = raw.responseSchema;
+  if (isPlainObject(raw.metadata)) interrupt.metadata = raw.metadata;
+  return interrupt;
+};
+
+const parseRunFinishedOutcome = (
+  raw: unknown,
+  logger: Logger | undefined,
+): AgUiRunFinishedOutcome | undefined => {
+  if (!isPlainObject(raw)) return undefined;
+  if (raw.type === "success") return { type: "success" };
+  if (raw.type === "interrupt") {
+    if (!Array.isArray(raw.interrupts)) {
+      logger?.debug?.(
+        "[agui] RUN_FINISHED interrupt outcome missing interrupts array",
+        raw,
+      );
+      return undefined;
+    }
+    const parsed = raw.interrupts
+      .map((entry) => parseInterrupt(entry))
+      .filter((entry): entry is AgUiInterrupt => entry !== null);
+    if (parsed.length === 0) {
+      logger?.debug?.(
+        "[agui] RUN_FINISHED interrupt outcome has no valid interrupts",
+        raw.interrupts,
+      );
+      return undefined;
+    }
+    return { type: "interrupt", interrupts: parsed };
+  }
+  return undefined;
+};
+
+export const parseAgUiEvent = (
+  event: unknown,
+  options?: ParseAgUiEventOptions,
+): AgUiEvent | null => {
   if (!event || typeof event !== "object") return null;
   const payload = event as Record<string, unknown>;
   const typeValue = payload.type;
@@ -32,7 +87,13 @@ export const parseAgUiEvent = (event: unknown): AgUiEvent | null => {
     }
     case "RUN_FINISHED": {
       const runId = getString("runId");
-      return runId ? { type: "RUN_FINISHED", runId } : null;
+      if (!runId) return null;
+      return withOptional(
+        { type: "RUN_FINISHED" as const, runId },
+        {
+          outcome: parseRunFinishedOutcome(payload.outcome, options?.logger),
+        },
+      );
     }
     case "RUN_CANCELLED": {
       const runId = getString("runId");

package/src/runtime/types.ts

@@ -47,9 +47,39 @@ export type UseAgUiRuntimeOptions = {
   adapters?: UseAgUiRuntimeAdapters;
 };
 
+export type AgUiInterruptReason =
+  | "tool_call"
+  | "input_required"
+  | "confirmation"
+  | (string & {});
+
+export type AgUiInterrupt = {
+  id: string;
+  reason: AgUiInterruptReason;
+  message?: string;
+  toolCallId?: string;
+  responseSchema?: Record<string, unknown>;
+  expiresAt?: string;
+  metadata?: Record<string, unknown>;
+};
+
+export type AgUiResumeEntry = {
+  interruptId: string;
+  status: "resolved" | "cancelled";
+  payload?: unknown;
+};
+
+export type AgUiRunFinishedOutcome =
+  | { type: "success" }
+  | { type: "interrupt"; interrupts: AgUiInterrupt[] };
+
 export type AgUiEvent =
   | { type: "RUN_STARTED"; runId: string }
-  | { type: "RUN_FINISHED"; runId: string }
+  | {
+      type: "RUN_FINISHED";
+      runId: string;
+      outcome?: AgUiRunFinishedOutcome;
+    }
   | { type: "RUN_CANCELLED"; runId?: string }
   | { type: "RUN_ERROR"; message?: string; code?: string }
   | { type: "TEXT_MESSAGE_START"; messageId?: string }