@assistant-ui/eve 0.0.13 → 0.0.15

package/src/convertEveMessages.ts

@@ -5,7 +5,9 @@ import {
   type CompleteAttachment,
   type DataMessagePart,
   type FileMessagePart,
+  type MessagePartStreamStatus,
   type MessageStatus,
+  type PartProviderMetadata,
   type RespondToToolApprovalOptions,
   type ThreadAssistantMessagePart,
   type ThreadMessage,
@@ -14,7 +16,10 @@ import {
   type ToolApprovalOption,
   type ToolCallMessagePart,
 } from "@assistant-ui/core";
-import { httpUrlPattern, parseDataUrl } from "@assistant-ui/core/internal";
+import {
+  httpUrlPattern,
+  resolveFilePartSource,
+} from "@assistant-ui/core/internal";
 import type {
   EveAuthorizationOutcome,
   EveAuthorizationPart,
@@ -24,7 +29,7 @@ import type {
   EveMessageInputRequest,
   EveMessagePart,
 } from "eve/react";
-import type { InputResponse, SendTurnPayload } from "eve/client";
+import type { InputResponse } from "eve/client";
 
 const ASSISTANT_COMPLETE_STATUS = {
   type: "complete",
@@ -148,7 +153,7 @@ const toolApprovalOptionsFromInputRequest = (
     kind:
       option.id === "approve"
         ? "allow-once"
-        : option.id === "deny"
+        : option.id === "cancel"
           ? "reject-once"
           : `_${option.id}`,
     ...(option.label && { label: option.label }),
@@ -186,10 +191,41 @@ const toApproval = (
   };
 };
 
+const toJsonSafeInputRequest = (
+  inputRequest: EveMessageInputRequest,
+): PartProviderMetadata[string] => ({
+  requestId: inputRequest.requestId,
+  prompt: inputRequest.prompt,
+  kind: inputRequest.kind,
+  ...(inputRequest.display !== undefined && { display: inputRequest.display }),
+  ...(inputRequest.allowFreeform !== undefined && {
+    allowFreeform: inputRequest.allowFreeform,
+  }),
+  ...(inputRequest.options && {
+    options: inputRequest.options.map((option) => ({
+      id: option.id,
+      label: option.label,
+      ...(option.description !== undefined && {
+        description: option.description,
+      }),
+      ...(option.style !== undefined && { style: option.style }),
+    })),
+  }),
+});
+
+const toToolProviderMetadata = (
+  part: EveDynamicToolPart,
+): PartProviderMetadata | undefined => {
+  const inputRequest = part.toolMetadata?.eve?.inputRequest;
+  if (!inputRequest) return undefined;
+  return { eve: { inputRequest: toJsonSafeInputRequest(inputRequest) } };
+};
+
 const convertDynamicToolPart = (
   part: EveDynamicToolPart,
 ): ToolCallMessagePart => {
   const approval = toApproval(part);
+  const providerMetadata = toToolProviderMetadata(part);
   const toolCall: ToolCallMessagePart = {
     type: "tool-call",
     toolCallId: part.toolCallId,
@@ -197,6 +233,7 @@ const convertDynamicToolPart = (
     args: toJsonObject(part.input),
     argsText: stringifyArgs(part.input),
     ...(approval && { approval }),
+    ...(providerMetadata && { providerMetadata }),
   };
 
   switch (part.state) {
@@ -287,13 +324,31 @@ const convertFilePart = (
   };
 };
 
+// Eve's `state` is a run marker: the reducer settles a part to "done" only on
+// `reasoning.completed`, `message.completed`, or `turn.cancelled`.
+// `emitStreamContent` does not flush leftover reasoning on a tool-call, so a
+// non-last reasoning part stays `streaming` until the model stream ends and the
+// leftover flush runs. Mapping `streaming` to running would pin that block
+// open. Only `done` is trustworthy; an unsettled part falls back to core's
+// last-part rule.
+const partStateToStatus = (
+  state: "done" | "streaming" | undefined,
+): MessagePartStreamStatus | undefined =>
+  state === "done" ? { type: "complete" } : undefined;
+
 const convertAssistantPart = (
   part: EveMessagePart,
 ): ThreadAssistantMessagePart | null => {
   switch (part.type) {
     case "text":
-    case "reasoning":
-      return { type: part.type, text: part.text };
+    case "reasoning": {
+      const status = partStateToStatus(part.state);
+      return {
+        type: part.type,
+        text: part.text,
+        ...(status && { status }),
+      };
+    }
 
     case "step-start":
       return null;
@@ -418,13 +473,30 @@ export const convertEveMessages = (
     convertEveMessage(message, index, messages, options),
   );
 
+/**
+ * Structural subset of the `string | UserContent` message content Eve's `send`
+ * API accepts. The helpers declare the shapes they produce and leave
+ * assignability to the send call site, checked against the installed version.
+ */
+export type EveMessageContent =
+  | string
+  | (
+      | { readonly type: "text"; readonly text: string }
+      | {
+          readonly type: "file";
+          readonly data: string;
+          readonly mediaType: string;
+          readonly filename?: string;
+        }
+    )[];
+
 /**
  * Converts an assistant-ui append message into the message payload accepted by
  * Eve's `send` API.
  */
 export const getEveMessageContent = (
   message: AppendMessage,
-): NonNullable<SendTurnPayload["message"]> => {
+): EveMessageContent => {
   const content = [
     ...message.content,
     ...(message.attachments?.flatMap((attachment) => attachment.content) ?? []),
@@ -457,11 +529,13 @@ export const getEveMessageContent = (
         // envelope is rebuilt from the typed format rather than forwarded.
         const mediaType = `audio/${part.audio.format}`;
         const data = part.audio.data;
+        const source = resolveFilePartSource({ data, mimeType: mediaType });
         return {
           type: "file" as const,
-          data: httpUrlPattern.test(data)
-            ? data
-            : `data:${mediaType};base64,${parseDataUrl(data)?.data ?? data}`,
+          data:
+            source.kind === "url"
+              ? source.url
+              : `data:${mediaType};base64,${source.data}`,
           mediaType,
         };
       }
@@ -489,13 +563,110 @@ export const getEveMessageContent = (
   return parts;
 };
 
+/**
+ * Finds the pending input request answered by the given approval id, so the
+ * response mapping can honor the request's display mode.
+ */
+export const findEveInputRequest = (
+  data: EveMessageData,
+  approvalId: string,
+): EveMessageInputRequest | undefined => {
+  for (const message of data.messages) {
+    for (const part of message.parts) {
+      if (part.type === "dynamic-tool" && part.approval?.id === approvalId) {
+        return part.toolMetadata?.eve?.inputRequest;
+      }
+    }
+  }
+  return undefined;
+};
+
 /**
  * Converts an assistant-ui tool approval response into an Eve input response.
+ *
+ * When `inputRequest` is known, every returned response carries either an
+ * option the request declares or a free-form answer. A literal option match
+ * wins, then the `"approve"` / `"cancel"` option the response's boolean decision
+ * names, then the response's `reason` text when the request takes a free-form
+ * answer (`display: "text"`, `allowFreeform`, or no options at all, and never
+ * `display: "confirmation"`) and the response is not a refusal.
+ * A one-argument call, or a part with no request, still forwards a caller
+ * `optionId` as it always has, including ids the request never declared.
+ *
+ * A response the known request cannot record as the answer it asked for throws
+ * instead of being submitted, because eve resolves a request the moment any
+ * response for it arrives, and an empty one is recorded as an answer with no
+ * content. Not sending leaves the request pending, so the caller can retry or
+ * the user can answer it as an ordinary message.
+ *
+ * With no request to map against — a one-argument call, or a part carrying no
+ * `toolMetadata.eve.inputRequest` — the response maps as it always has, to the
+ * literal `"approve"` / `"cancel"` option every eve approval declares. Guessing
+ * a display mode is what this mapper stopped doing; an unknown request is not
+ * a guess about one.
  */
 export const toEveInputResponse = (
   response: RespondToToolApprovalOptions,
-): InputResponse => ({
-  requestId: response.approvalId,
-  optionId: response.optionId ?? (response.approved ? "approve" : "deny"),
-  ...(response.reason && { text: response.reason }),
-});
+  inputRequest?: EveMessageInputRequest,
+): InputResponse => {
+  const requestId = response.approvalId;
+  const options = inputRequest?.options;
+  const text = response.reason;
+
+  if (response.optionId !== undefined) {
+    if (
+      !inputRequest ||
+      options?.some((option) => option.id === response.optionId)
+    ) {
+      return {
+        requestId,
+        optionId: response.optionId,
+        ...(text && { text }),
+      };
+    }
+    throw new Error(
+      `Eve input request "${requestId}" has no option with id "${response.optionId}"; respond with one of: ${
+        options?.length
+          ? options.map((option) => option.id).join(", ")
+          : "(the request carries no options)"
+      }`,
+    );
+  }
+
+  const decisionOptionId = response.approved ? "approve" : "cancel";
+  // Eve's harness always declares `approve`/`cancel` on a `tool-approval`
+  // request, so honoring the kind when the options were dropped keeps a
+  // non-spec approval payload answerable rather than stuck. A tool-approval
+  // that declares its own options still requires one of them.
+  if (
+    !inputRequest ||
+    (inputRequest.kind === "tool-approval" && !options?.length) ||
+    options?.some((option) => option.id === decisionOptionId)
+  ) {
+    return { requestId, optionId: decisionOptionId, ...(text && { text }) };
+  }
+
+  // Eve recognises an approval by its literal two-option `approve`/`cancel`
+  // shape, so past this point the request is a question and the boolean
+  // carries no decision eve would act on.
+  const acceptsText =
+    inputRequest.display !== "confirmation" &&
+    (inputRequest.display === "text" ||
+      inputRequest.allowFreeform === true ||
+      !options?.length);
+  if (acceptsText && text && response.approved !== false) {
+    return { requestId, text };
+  }
+
+  throw new Error(
+    `Eve input request "${requestId}" (${inputRequest.prompt}) was not answered by this response; ${
+      options?.length
+        ? `respond with one of: ${options.map((option) => option.id).join(", ")}`
+        : !acceptsText
+          ? "the request declares no options to respond with"
+          : response.approved === false
+            ? "a refusal carries no answer for a free-form request; resend with `approved` unset or true and the answer in the response reason"
+            : "pass the answer as the response reason, because the request takes a free-form answer"
+    }`,
+  );
+};

package/src/eveExtras.ts

@@ -0,0 +1,10 @@
+import { createRuntimeExtras } from "@assistant-ui/core/react";
+import type { EveMessageData, UseEveAgentHelpers } from "eve/react";
+
+export type EveRuntimeExtras = Pick<
+  UseEveAgentHelpers<EveMessageData>,
+  "error" | "events" | "session" | "reset"
+>;
+
+export const eveExtras =
+  createRuntimeExtras<EveRuntimeExtras>("useEveAgentRuntime");

package/src/hooks.test.tsx

@@ -0,0 +1,84 @@
+// @vitest-environment jsdom
+
+import { renderHook } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+const { extrasRef } = vi.hoisted(() => ({
+  extrasRef: { current: undefined as unknown },
+}));
+
+vi.mock("@assistant-ui/store", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("@assistant-ui/store")>()),
+  useAui: (() => ({
+    thread: { getState: () => ({ extras: extrasRef.current }) },
+  })) as unknown as typeof import("@assistant-ui/store").useAui,
+  useAuiState: ((selector: (s: unknown) => unknown) =>
+    selector({
+      thread: { extras: extrasRef.current },
+    })) as typeof import("@assistant-ui/store").useAuiState,
+}));
+
+import { eveExtras, type EveRuntimeExtras } from "./eveExtras";
+import { useEveError, useEveEvents, useEveReset, useEveSession } from "./hooks";
+
+const provideExtras = (over: Partial<EveRuntimeExtras>) =>
+  eveExtras.provide({
+    error: undefined,
+    events: [],
+    session: {} as EveRuntimeExtras["session"],
+    reset: () => {},
+    ...over,
+  });
+
+afterEach(() => {
+  extrasRef.current = undefined;
+});
+
+describe("Eve accessor hooks", () => {
+  it("reads the session error from the runtime extras", () => {
+    const error = new Error("boom");
+    extrasRef.current = provideExtras({ error });
+
+    expect(renderHook(() => useEveError()).result.current).toBe(error);
+  });
+
+  it("reads the session cursor from the runtime extras", () => {
+    const session = {
+      sessionId: "s1",
+    } as unknown as EveRuntimeExtras["session"];
+    extrasRef.current = provideExtras({ session });
+
+    expect(renderHook(() => useEveSession()).result.current).toBe(session);
+  });
+
+  it("reads the server event stream from the runtime extras", () => {
+    const events = [
+      { type: "session.started" },
+    ] as unknown as EveRuntimeExtras["events"];
+    extrasRef.current = provideExtras({ events });
+
+    expect(renderHook(() => useEveEvents()).result.current).toBe(events);
+  });
+
+  it("reads reset from the runtime extras", () => {
+    const reset = vi.fn();
+    extrasRef.current = provideExtras({ reset });
+
+    renderHook(() => useEveReset()).result.current();
+
+    expect(reset).toHaveBeenCalledTimes(1);
+  });
+
+  it("supplies fallbacks outside an Eve runtime, and defers the reset throw to invocation", () => {
+    expect(renderHook(() => useEveError()).result.current).toBeUndefined();
+    expect(renderHook(() => useEveSession()).result.current).toBeUndefined();
+
+    const events = renderHook(() => useEveEvents()).result.current;
+    expect(events).toEqual([]);
+    expect(renderHook(() => useEveEvents()).result.current).toBe(events);
+    expect(Object.isFrozen(events)).toBe(true);
+
+    const reset = renderHook(() => useEveReset()).result.current;
+    expect(() => reset()).toThrow("useEveAgentRuntime");
+  });
+});

package/src/hooks.ts

@@ -0,0 +1,36 @@
+"use client";
+
+import { useAui } from "@assistant-ui/store";
+import { eveExtras } from "./eveExtras";
+import type { EveRuntimeExtras } from "./eveExtras";
+
+const EMPTY_EVENTS: EveRuntimeExtras["events"] = Object.freeze([]);
+
+/** Read the last Eve session error from the runtime extras. */
+export const useEveError = () => eveExtras.use((e) => e.error, undefined);
+
+/**
+ * Read the current Eve session cursor from the runtime extras. Persist it to
+ * resume the session later via `initialSession`. `undefined` when no session
+ * exists yet or outside an Eve runtime.
+ */
+export const useEveSession = (): EveRuntimeExtras["session"] | undefined =>
+  eveExtras.use((e) => e.session, undefined);
+
+/**
+ * Read the authoritative Eve server event stream from the runtime extras.
+ * Defaults to an empty array outside an Eve runtime.
+ */
+export const useEveEvents = (): EveRuntimeExtras["events"] =>
+  eveExtras.use((e) => e.events, EMPTY_EVENTS);
+
+/**
+ * Returns a function that resets the Eve session: aborts any in-flight turn,
+ * recreates the owned session, and clears events and projected data. Pending
+ * staged messages and tool execution state are discarded. Safe to render
+ * outside an Eve runtime; invoking the returned function there throws.
+ */
+export const useEveReset = () => {
+  const aui = useAui();
+  return () => eveExtras.get(aui).reset();
+};

package/src/index.ts

@@ -9,6 +9,9 @@ export {
 export type {
   ConvertEveMessagesOptions,
   EveAuthorizationData,
+  EveMessageContent,
 } from "./convertEveMessages";
 export { useEveAgentRuntime } from "./useEveAgentRuntime";
 export type { UseEveAgentRuntimeOptions } from "./useEveAgentRuntime";
+export { useEveError, useEveEvents, useEveReset, useEveSession } from "./hooks";
+export type { EveRuntimeExtras } from "./eveExtras";

package/src/useEveAgentRuntime.refetch.test.tsx

@@ -0,0 +1,89 @@
+// @vitest-environment jsdom
+
+import { act, renderHook } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import type { HandleMessageStreamEvent } from "eve/client";
+
+import { useEveAgentRuntime } from "./useEveAgentRuntime";
+
+const completedTurn = (
+  turnId: string,
+  text: string,
+  reply: string,
+  sequence: number,
+) =>
+  [
+    {
+      type: "turn.started",
+      data: { sequence, turnId },
+      meta: { at: "2026-01-02T10:00:00.000Z", id: `${turnId}-1` },
+    },
+    {
+      type: "message.received",
+      data: { message: text, sequence: sequence + 1, turnId },
+      meta: { at: "2026-01-02T10:00:01.000Z", id: `${turnId}-2` },
+    },
+    {
+      type: "step.started",
+      data: { modelId: "m", sequence: sequence + 2, stepIndex: 0, turnId },
+      meta: { at: "2026-01-02T10:00:02.000Z", id: `${turnId}-3` },
+    },
+    {
+      type: "message.completed",
+      data: {
+        finishReason: "stop",
+        message: reply,
+        sequence: sequence + 3,
+        stepIndex: 0,
+        turnId,
+      },
+      meta: { at: "2026-01-02T10:00:03.000Z", id: `${turnId}-4` },
+    },
+    {
+      type: "turn.completed",
+      data: { sequence: sequence + 4, turnId },
+      meta: { at: "2026-01-02T10:00:04.000Z", id: `${turnId}-5` },
+    },
+  ] as const satisfies readonly HandleMessageStreamEvent[];
+
+const knownTurn = completedTurn("t1", "hi", "hello", 1);
+const outOfBandTurn = completedTurn("t2", "answered elsewhere", "done", 6);
+
+describe("useEveAgentRuntime against a durable eve session", () => {
+  it("surfaces a turn the server appended out of band after reloadMainThread", async () => {
+    const stream = vi.fn(async function* () {
+      yield* [...knownTurn, ...outOfBandTurn];
+    });
+    const session = {
+      state: { sessionId: "s1" },
+      stream,
+      send: () => {
+        throw new Error("the refetch test must not send");
+      },
+    } as never;
+
+    const { result } = renderHook(() =>
+      useEveAgentRuntime({ initialEvents: knownTurn as never, session }),
+    );
+    expect(
+      result.current.thread.getState().messages.map((m) => m.role),
+    ).toEqual(["user", "assistant"]);
+
+    await act(async () => {
+      await result.current.threads.reloadMainThread();
+    });
+
+    expect(stream).toHaveBeenCalled();
+    const messages = result.current.thread.getState().messages;
+    expect(messages.map((m) => m.role)).toEqual([
+      "user",
+      "assistant",
+      "user",
+      "assistant",
+    ]);
+    expect(messages[3]?.content).toMatchObject([
+      { type: "text", text: "done" },
+    ]);
+    expect(result.current.thread.getState().isRunning).toBe(false);
+  });
+});