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

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 }

package/src/useAgUiRuntime.ts

@@ -15,12 +15,23 @@ import type {
 } from "@assistant-ui/core";
 import type { ReadonlyJSONValue } from "assistant-stream/utils";
 import { makeLogger } from "./runtime/logger";
-import type { UseAgUiRuntimeOptions } from "./runtime/types";
+import type {
+  AgUiInterrupt,
+  AgUiResumeEntry,
+  UseAgUiRuntimeOptions,
+} from "./runtime/types";
 import { AgUiThreadRuntimeCore } from "./runtime/AgUiThreadRuntimeCore";
 
+export type AgUiAssistantRuntime = AssistantRuntime & {
+  unstable_getPendingInterrupts: () => readonly AgUiInterrupt[];
+  unstable_submitInterruptResponses: (
+    responses: readonly AgUiResumeEntry[],
+  ) => Promise<void>;
+};
+
 export function useAgUiRuntime(
   options: UseAgUiRuntimeOptions,
-): AssistantRuntime {
+): AgUiAssistantRuntime {
   const logger = useMemo(() => makeLogger(options.logger), [options.logger]);
   const [_version, setVersion] = useState(0);
   const notifyUpdate = useCallback(() => setVersion((v) => v + 1), []);
@@ -174,7 +185,16 @@ export function useAgUiRuntime(
     [adapterAdapters, core, _version, hasExecutingTools],
   );
 
-  const runtime = useExternalStoreRuntime(store);
+  const baseRuntime = useExternalStoreRuntime(store);
+
+  const runtime = useMemo<AgUiAssistantRuntime>(() => {
+    const wrapper = Object.create(baseRuntime) as AgUiAssistantRuntime;
+    wrapper.unstable_getPendingInterrupts = () =>
+      core.getPendingInterrupts()?.interrupts ?? [];
+    wrapper.unstable_submitInterruptResponses = (responses) =>
+      core.submitInterruptResponses(responses);
+    return wrapper;
+  }, [baseRuntime, core]);
 
   useEffect(() => {
     core.attachRuntime(runtime);