@assistant-ui/core 0.3.19 → 0.3.21

package/src/runtime/utils/tool-interactions.test.ts

@@ -0,0 +1,193 @@
+import { describe, expect, it } from "vitest";
+import {
+  TOOL_INTERACTION_LIMITS,
+  appendToolInteraction,
+  createToolInteraction,
+  readToolInteractionLog,
+} from "./tool-interactions";
+
+describe("createToolInteraction", () => {
+  it("creates action and human-response interactions", () => {
+    expect(
+      createToolInteraction(
+        { type: "action", payload: { $input: "approved" } },
+        10,
+      ),
+    ).toEqual({
+      type: "action",
+      occurredAt: 10,
+      payload: { $input: "approved" },
+    });
+    expect(
+      createToolInteraction({ type: "human-response", payload: false }, 11),
+    ).toEqual({ type: "human-response", occurredAt: 11, payload: false });
+  });
+
+  it.each([false, 0, "", null])("keeps the human response %j", (payload) => {
+    expect(
+      createToolInteraction({ type: "human-response", payload }, 10),
+    ).toHaveProperty("payload", payload);
+  });
+
+  it("returns a JSON clone of the payload", () => {
+    const payload = { answer: { value: "yes" } };
+    const interaction = createToolInteraction({ type: "action", payload }, 10);
+
+    payload.answer.value = "no";
+
+    expect(interaction.payload).toEqual({ answer: { value: "yes" } });
+    expect(interaction.payload).not.toBe(payload);
+  });
+
+  it.each([
+    ["undefined", undefined],
+    ["a function", () => {}],
+    ["a bigint", 1n],
+    ["a symbol", Symbol("value")],
+    ["NaN", Number.NaN],
+    ["Infinity", Number.POSITIVE_INFINITY],
+    ["a date", new Date()],
+    ["a map", new Map()],
+    [
+      "a class instance",
+      new (class Payload {
+        readonly value = "x";
+      })(),
+    ],
+  ])("rejects %s", (_label, payload) => {
+    expect(() =>
+      createToolInteraction({ type: "human-response", payload }, 10),
+    ).toThrow("plain JSON");
+  });
+
+  it("rejects a cycle", () => {
+    const payload: { self?: unknown } = {};
+    payload.self = payload;
+
+    expect(() =>
+      createToolInteraction({ type: "human-response", payload }, 10),
+    ).toThrow("plain JSON");
+  });
+
+  it("rejects invalid action payloads, interaction types, and large payloads", () => {
+    expect(() =>
+      createToolInteraction({ type: "action", payload: ["not an object"] }, 10),
+    ).toThrow("JSON object");
+    expect(() =>
+      createToolInteraction({ type: "unknown", payload: null } as never, 10),
+    ).toThrow("Unknown tool interaction type");
+    expect(() =>
+      createToolInteraction(
+        {
+          type: "human-response",
+          payload: "x".repeat(TOOL_INTERACTION_LIMITS.payloadLength),
+        },
+        10,
+      ),
+    ).toThrow("limited");
+  });
+});
+
+describe("appendToolInteraction", () => {
+  const interaction = (occurredAt: number, payload: unknown = occurredAt) =>
+    ({
+      type: "human-response" as const,
+      occurredAt,
+      payload,
+    }) as ReturnType<typeof createToolInteraction>;
+
+  it("evicts the oldest entries past the entry limit", () => {
+    let log = appendToolInteraction(undefined, interaction(0));
+    for (let index = 1; index <= TOOL_INTERACTION_LIMITS.entries; index += 1) {
+      log = appendToolInteraction(log, interaction(index));
+    }
+
+    expect(log).toMatchObject({ omitted: 1 });
+    expect(log.entries).toHaveLength(TOOL_INTERACTION_LIMITS.entries);
+    expect(log.entries[0]).toHaveProperty("occurredAt", 1);
+    expect(log.entries.at(-1)).toHaveProperty(
+      "occurredAt",
+      TOOL_INTERACTION_LIMITS.entries,
+    );
+  });
+
+  it("evicts entries past the log length across calls", () => {
+    const payload = "x".repeat(16_000);
+    let log = appendToolInteraction(undefined, interaction(0, payload));
+    for (let index = 1; index < 5; index += 1) {
+      log = appendToolInteraction(log, interaction(index, payload));
+    }
+
+    expect(log).toMatchObject({ omitted: 1 });
+    expect(log.entries.map((entry) => entry.occurredAt)).toEqual([1, 2, 3, 4]);
+
+    log = appendToolInteraction(log, interaction(5, payload));
+
+    expect(log).toMatchObject({ omitted: 2 });
+    expect(log.entries.map((entry) => entry.occurredAt)).toEqual([2, 3, 4, 5]);
+  });
+});
+
+describe("readToolInteractionLog", () => {
+  const interaction = (occurredAt: number, payload: unknown = occurredAt) => ({
+    type: "human-response",
+    occurredAt,
+    payload,
+  });
+
+  it("keeps readable entries and a positive omitted count", () => {
+    const log = readToolInteractionLog({
+      entries: [
+        { type: "action", occurredAt: 1, payload: { $input: "yes" } },
+        { type: "human-response", occurredAt: 2, payload: false },
+        { type: "unknown", occurredAt: 3, payload: null },
+        { type: "action", occurredAt: Number.POSITIVE_INFINITY, payload: {} },
+        { type: "human-response", occurredAt: 4, payload: () => {} },
+        { type: "action", occurredAt: 5, payload: [] },
+      ],
+      omitted: 3,
+    });
+
+    expect(log).toEqual({
+      entries: [
+        { type: "action", occurredAt: 1, payload: { $input: "yes" } },
+        { type: "human-response", occurredAt: 2, payload: false },
+      ],
+      omitted: 3,
+    });
+  });
+
+  it("evicts the oldest readable entries past the entry limit", () => {
+    const log = readToolInteractionLog({
+      entries: Array.from(
+        { length: TOOL_INTERACTION_LIMITS.entries + 1 },
+        (_, index) => interaction(index),
+      ),
+      omitted: 2,
+    });
+
+    expect(log).toMatchObject({ omitted: 3 });
+    expect(log?.entries).toHaveLength(TOOL_INTERACTION_LIMITS.entries);
+    expect(log?.entries[0]).toHaveProperty("occurredAt", 1);
+  });
+
+  it("evicts the oldest readable entries past the log length", () => {
+    const payload = "x".repeat(16_000);
+    const log = readToolInteractionLog({
+      entries: Array.from({ length: 5 }, (_, index) =>
+        interaction(index, payload),
+      ),
+      omitted: 2,
+    });
+
+    expect(log).toMatchObject({ omitted: 3 });
+    expect(log?.entries.map((entry) => entry.occurredAt)).toEqual([1, 2, 3, 4]);
+  });
+
+  it.each([null, "log", [], {}, { entries: [] }])(
+    "returns undefined for unreadable logs: %j",
+    (value) => {
+      expect(readToolInteractionLog(value)).toBeUndefined();
+    },
+  );
+});

package/src/runtime/utils/tool-interactions.ts

@@ -0,0 +1,147 @@
+import type {
+  ReadonlyJSONObject,
+  ReadonlyJSONValue,
+} from "assistant-stream/utils";
+import type {
+  Unstable_ToolInteraction,
+  Unstable_ToolInteractionInput,
+  Unstable_ToolInteractionLog,
+} from "../../types/message";
+
+export const TOOL_INTERACTION_LIMITS = {
+  entries: 32,
+  payloadLength: 16_384,
+  logLength: 65_536,
+} as const;
+
+const MAX_DEPTH = 64;
+
+const isPlainObject = (value: object): boolean => {
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+};
+
+const isPlainJSON = (
+  value: unknown,
+  ancestors: Set<object>,
+  depth: number,
+): value is ReadonlyJSONValue => {
+  if (value === null) return true;
+  switch (typeof value) {
+    case "string":
+    case "boolean":
+      return true;
+    case "number":
+      return Number.isFinite(value);
+    case "object":
+      break;
+    default:
+      return false;
+  }
+  if (depth > MAX_DEPTH || ancestors.has(value)) return false;
+  ancestors.add(value);
+  const valid = Array.isArray(value)
+    ? value.every((item) => isPlainJSON(item, ancestors, depth + 1))
+    : isPlainObject(value) &&
+      Object.values(value).every((item) =>
+        isPlainJSON(item, ancestors, depth + 1),
+      );
+  ancestors.delete(value);
+  return valid;
+};
+
+const isJSONObjectValue = (value: unknown) =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const isInteractionType = (
+  value: unknown,
+): value is Unstable_ToolInteraction["type"] =>
+  value === "action" || value === "human-response";
+
+export function createToolInteraction(
+  input: Unstable_ToolInteractionInput,
+  occurredAt: number = Date.now(),
+): Unstable_ToolInteraction {
+  const { type, payload } = input;
+  if (!isInteractionType(type)) {
+    throw new Error(`Unknown tool interaction type: ${String(type)}`);
+  }
+  if (!isPlainJSON(payload, new Set(), 0)) {
+    throw new Error("A tool interaction payload must be plain JSON.");
+  }
+  if (type === "action" && !isJSONObjectValue(payload)) {
+    throw new Error("An action interaction payload must be a JSON object.");
+  }
+  const serialized = JSON.stringify(payload);
+  if (serialized.length > TOOL_INTERACTION_LIMITS.payloadLength) {
+    throw new Error(
+      `A tool interaction payload is limited to ${TOOL_INTERACTION_LIMITS.payloadLength} characters of JSON.`,
+    );
+  }
+  return { type, occurredAt, payload: JSON.parse(serialized) };
+}
+
+export function appendToolInteraction(
+  log: Unstable_ToolInteractionLog | undefined,
+  interaction: Unstable_ToolInteraction,
+): Unstable_ToolInteractionLog {
+  const entries = [...(log?.entries ?? []), interaction];
+  let omitted = log?.omitted ?? 0;
+  while (
+    entries.length > 1 &&
+    (entries.length > TOOL_INTERACTION_LIMITS.entries ||
+      JSON.stringify(entries).length > TOOL_INTERACTION_LIMITS.logLength)
+  ) {
+    entries.shift();
+    omitted += 1;
+  }
+  return omitted > 0 ? { entries, omitted } : { entries };
+}
+
+const readInteraction = (
+  value: unknown,
+): Unstable_ToolInteraction | undefined => {
+  if (!isJSONObjectValue(value)) return undefined;
+  const { type, occurredAt, payload } = value as Record<string, unknown>;
+  if (!isInteractionType(type)) return undefined;
+  if (typeof occurredAt !== "number" || !Number.isFinite(occurredAt)) {
+    return undefined;
+  }
+  if (!isPlainJSON(payload, new Set(), 0)) return undefined;
+  if (type === "action") {
+    return isJSONObjectValue(payload)
+      ? { type, occurredAt, payload: payload as ReadonlyJSONObject }
+      : undefined;
+  }
+  return { type, occurredAt, payload };
+};
+
+export function readToolInteractionLog(
+  value: unknown,
+): Unstable_ToolInteractionLog | undefined {
+  if (!isJSONObjectValue(value)) return undefined;
+  const { entries, omitted } = value as Record<string, unknown>;
+  const readable = Array.isArray(entries)
+    ? entries.flatMap((entry) => {
+        const interaction = readInteraction(entry);
+        return interaction ? [interaction] : [];
+      })
+    : [];
+  const omittedCount =
+    typeof omitted === "number" && Number.isInteger(omitted) && omitted > 0
+      ? omitted
+      : 0;
+  let omittedEntries = omittedCount;
+  while (
+    readable.length > 1 &&
+    (readable.length > TOOL_INTERACTION_LIMITS.entries ||
+      JSON.stringify(readable).length > TOOL_INTERACTION_LIMITS.logLength)
+  ) {
+    readable.shift();
+    omittedEntries += 1;
+  }
+  if (readable.length === 0 && omittedEntries === 0) return undefined;
+  return omittedEntries > 0
+    ? { entries: readable, omitted: omittedEntries }
+    : { entries: readable };
+}

package/src/runtimes/external-store/external-store-adapter.ts

@@ -14,6 +14,7 @@ import type { FeedbackAdapter } from "../../adapters/feedback";
 import type {
   AddToolResultOptions,
   RespondToToolApprovalOptions,
+  Unstable_RecordToolInteractionOptions,
   StartRunConfig,
   ResumeRunConfig,
   ThreadSuggestion,
@@ -84,6 +85,11 @@ type ExternalStoreMessageConverterAdapter<T> = {
 };
 
 type ExternalStoreAdapterBase<T> = {
+  /**
+   * The runtime writes its messages to the thread list's history adapter
+   * itself, so `useExternalStoreRuntime` does not copy them.
+   */
+  unstable_persistsHistory?: boolean | undefined;
   /**
    * Whether the entire thread is disabled. When `true`, the composer's input
    * is also disabled (the user cannot type, attach files, or submit). For a
@@ -133,6 +139,10 @@ type ExternalStoreAdapterBase<T> = {
    * back, because the runtime cannot see a removal it did not make.
    */
   setMessages?: ((messages: readonly T[]) => void) | undefined;
+  /**
+   * Called with each message a voice session adds to the thread: every finalized transcript, and every text message typed into a session that takes typed text (it carries no `metadata.modality`). The host appends it to its own messages under the same id, which is how the runtime knows the host carries it. A message that finalizes while `isLoading` is true is delivered once loading ends, to the callback on the adapter current at that moment, and is not delivered at all when the conversation changed while it waited. A host that routes conversations through one runtime is recognized by its `unstable_messageRepositoryInstance`; one that swaps only its `messages` cannot be told apart from a load finishing. A host that does not implement this callback keeps these messages for the session only.
+   */
+  onVoiceTranscript?: ((message: ThreadMessage) => void) | undefined;
   /**
    * Fires when the user explicitly switches branches via the runtime's
    * `switchToBranch` action (e.g. a BranchPicker click). It does not fire on
@@ -160,6 +170,13 @@ type ExternalStoreAdapterBase<T> = {
   /** Opt in to message queuing. Typically produced by `createMessageQueue`. */
   queue?: ExternalThreadQueueAdapter | undefined;
   onEdit?: ((message: AppendMessage) => Promise<void>) | undefined;
+  /**
+   * Removes a message from the host's store. The runtime drops the message
+   * from its branches when `messages` stops carrying the id, and reads a
+   * `messages` update that still carries it after every call for it has
+   * settled as a declined delete. A host that accepts the delete therefore
+   * publishes the removal before the returned promise settles.
+   */
   onDelete?: ((messageId: string) => Promise<void> | void) | undefined;
   onReload?: // TODO: remove parentId in 0.12.0
     | ((parentId: string | null, config: StartRunConfig) => Promise<void>)
@@ -184,6 +201,14 @@ type ExternalStoreAdapterBase<T> = {
   onRespondToToolApproval?:
     | ((options: RespondToToolApprovalOptions) => Promise<void> | void)
     | undefined;
+  /**
+   * Stores a user interaction on a tool call part of a message this store
+   * owns and exposes it on that part's `unstable_interactions`. Without it,
+   * recording an interaction rejects and nothing is kept.
+   */
+  unstable_onRecordToolInteraction?:
+    | ((options: Unstable_RecordToolInteractionOptions) => Promise<void> | void)
+    | undefined;
   convertMessage?: ExternalStoreMessageConverter<T> | undefined;
   adapters?:
     | {

package/src/runtimes/external-store/external-store-runtime-core.ts

@@ -9,17 +9,25 @@ const getThreadListAdapter = (store: ExternalStoreAdapter<any>) => {
 
 export class ExternalStoreRuntimeCore extends BaseAssistantRuntimeCore {
   public readonly threads;
+  private _adapter: ExternalStoreAdapter<any>;
 
   constructor(adapter: ExternalStoreAdapter<any>) {
     super();
+    this._adapter = adapter;
     this.threads = new ExternalStoreThreadListRuntimeCore(
       getThreadListAdapter(adapter),
-      () => new ExternalStoreThreadRuntimeCore(this._contextProvider, adapter),
+      () =>
+        new ExternalStoreThreadRuntimeCore(
+          this._contextProvider,
+          this._adapter,
+        ),
     );
   }
 
   public setAdapter(adapter: ExternalStoreAdapter<any>) {
-    // Update the thread list adapter and propagate store changes to the main thread
+    // Before the thread list, whose thread switch builds the new main thread
+    // from this adapter.
+    this._adapter = adapter;
     this.threads.__internal_setAdapter(getThreadListAdapter(adapter));
     this.threads.getMainThreadRuntimeCore().__internal_setAdapter(adapter);
   }

package/src/runtimes/external-store/external-store-thread-list-runtime-core.ts

@@ -4,7 +4,7 @@ import type {
   ThreadListRuntimeCore,
 } from "../../runtime/interfaces/thread-list-runtime-core";
 import type { ExternalStoreThreadListAdapter } from "./external-store-adapter";
-import { invalidateThreadRuntime } from "../../runtime/utils/thread-runtime-lifecycle";
+import { disposeThreadRuntime } from "../../runtime/utils/thread-runtime-lifecycle";
 import { BaseSubscribable } from "../../subscribable/subscribable";
 import { nullProtoRecord } from "../../utils/record";
 
@@ -161,7 +161,7 @@ export class ExternalStoreThreadListRuntimeCore
 
     // `initialLoad ||`: `_mainThread!` must be assigned on construction.
     if (initialLoad || previousThreadId !== newThreadId) {
-      if (!initialLoad) invalidateThreadRuntime(this._mainThread);
+      if (!initialLoad) disposeThreadRuntime(this._mainThread);
       this._mainThreadId = newThreadId;
       this._mainThread = this.threadFactory();
     }

package/src/runtimes/external-store/external-store-thread-runtime-core.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it, vi } from "vitest";
+import type { ModelContextProvider } from "../../model-context/types";
+import type { Unstable_RecordToolInteractionOptions } from "../../runtime/interfaces/thread-runtime-core";
+import type { ExternalStoreAdapter } from "./external-store-adapter";
+import { ExternalStoreThreadRuntimeCore } from "./external-store-thread-runtime-core";
+
+const modelContextProvider: ModelContextProvider = {
+  getModelContext: () => ({}),
+};
+
+const interaction: Unstable_RecordToolInteractionOptions = {
+  messageId: "message-1",
+  toolCallId: "call-1",
+  interaction: {
+    type: "action",
+    payload: { action: "toggle" },
+    occurredAt: 0,
+  },
+};
+
+const createRuntime = (overrides: Partial<ExternalStoreAdapter> = {}) =>
+  new ExternalStoreThreadRuntimeCore(modelContextProvider, {
+    messages: [],
+    onNew: async () => {},
+    ...overrides,
+  } as ExternalStoreAdapter);
+
+describe("ExternalStoreThreadRuntimeCore interaction recording", () => {
+  it("delegates interaction records to the adapter", async () => {
+    const onRecordToolInteraction = vi.fn(async () => {});
+    const runtime = createRuntime({
+      unstable_onRecordToolInteraction: onRecordToolInteraction,
+    });
+
+    await runtime.unstable_recordToolInteraction(interaction);
+
+    expect(onRecordToolInteraction).toHaveBeenCalledExactlyOnceWith(
+      interaction,
+    );
+  });
+
+  it("rejects when the adapter does not record interactions", async () => {
+    const runtime = createRuntime();
+
+    await expect(
+      runtime.unstable_recordToolInteraction(interaction),
+    ).rejects.toThrow("Runtime does not support recording tool interactions.");
+  });
+});