@assistant-ui/core 0.2.9 → 0.2.11

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

@@ -197,6 +197,19 @@ export class ExternalStoreThreadListRuntimeCore implements ThreadListRuntimeCore
     await onRename(threadId, newTitle);
   }
 
+  public async updateCustom(
+    threadId: string,
+    custom: Record<string, unknown> | undefined,
+  ): Promise<void> {
+    const onUpdateCustom = this.adapter.onUpdateCustom;
+    if (!onUpdateCustom)
+      throw new Error(
+        "External store adapter does not support updating custom metadata",
+      );
+
+    await onUpdateCustom(threadId, custom);
+  }
+
   public async detach(): Promise<void> {
     // no-op
   }

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

@@ -32,6 +32,7 @@ import {
 } from "../../runtime/utils/message-repository";
 import { generateId } from "../../utils/id";
 import { ToolInvocationTracker } from "../tool-invocations/ToolInvocationTracker";
+import { EMPTY_QUEUE_ITEMS } from "../../store/scopes/queue-item";
 
 const EMPTY_ARRAY: readonly ThreadSuggestion[] = Object.freeze([]);
 
@@ -155,7 +156,7 @@ export class ExternalStoreThreadRuntimeCore
       unstable_copy: this._store.unstable_capabilities?.copy !== false,
       attachments: !!this._store.adapters?.attachments,
       feedback: !!this._store.adapters?.feedback,
-      queue: false,
+      queue: this._store.queue !== undefined,
     };
     if (!shallowEqual(this._capabilities, newCapabilities)) {
       this._capabilities = newCapabilities;
@@ -389,6 +390,15 @@ export class ExternalStoreThreadRuntimeCore
   }
 
   public async append(message: AppendMessage): Promise<void> {
+    const isEdit = message.parentId !== (this.messages.at(-1)?.id ?? null);
+
+    // Buffering does not start a run, so the tool-abort below must wait until
+    // the queue flushes. By then the prior run (and its tools) has settled.
+    if (!isEdit && this._store.queue) {
+      this._store.queue.enqueue(message, { steer: message.steer ?? false });
+      return;
+    }
+
     // Auto-abort in-flight client-side tool executions when a new run is
     // about to start. Without this, a tool that finishes after the new turn
     // begins would feed a stale result into `onAddToolResult`, racing with
@@ -399,19 +409,36 @@ export class ExternalStoreThreadRuntimeCore
       await this._toolInvocations?.abort();
     }
 
-    if (message.parentId !== (this.messages.at(-1)?.id ?? null)) {
+    if (isEdit) {
       if (!this._store.onEdit)
         throw new Error("Runtime does not support editing messages.");
+      this._store.queue?.clear("edit");
       await this._store.onEdit(message);
     } else {
       await this._store.onNew(message);
     }
   }
 
+  public getQueueItems() {
+    // The composer reads this during base-thread construction, before the
+    // constructor assigns `_store`, so guard against the unset field.
+    return this._store?.queue?.items ?? EMPTY_QUEUE_ITEMS;
+  }
+
+  public steerQueueItem(queueItemId: string) {
+    this._store?.queue?.steer(queueItemId);
+  }
+
+  public removeQueueItem(queueItemId: string) {
+    this._store?.queue?.remove(queueItemId);
+  }
+
   public async startRun(config: StartRunConfig): Promise<void> {
     if (!this._store.onReload)
       throw new Error("Runtime does not support reloading messages.");
 
+    this._store.queue?.clear("reload");
+
     // Auto-abort in-flight client-side tool executions when a run reloads;
     // any results that land afterward would target a turn that no longer
     // exists. See `append` above for full rationale.
@@ -457,6 +484,8 @@ export class ExternalStoreThreadRuntimeCore
     if (!this._store.onCancel)
       throw new Error("Runtime does not support cancelling runs.");
 
+    this._store.queue?.clear("cancel-run");
+
     // Abort any in-flight client-side tool executions. Fire-and-forget —
     // the abort resolves once executions settle, but we don't gate the
     // cancel on it.

package/src/runtimes/local/local-runtime-options.ts

@@ -26,4 +26,10 @@ export type LocalRuntimeOptionsBase = {
    * Names of tools that are allowed to interrupt the run in order to wait for human/external approval.
    */
   unstable_humanToolNames?: string[] | undefined;
+
+  /**
+   * Opt in to message queuing: a message sent during a run is held in
+   * `composer.queue` and sent once the run settles. Steering runs it next.
+   */
+  unstable_enableMessageQueue?: boolean | undefined;
 };

package/src/runtimes/local/local-thread-runtime-core.ts

@@ -22,6 +22,14 @@ import type {
 } from "../../types/message";
 import type { RunConfig } from "../../types/message";
 import type { ModelContextProvider } from "../../model-context/types";
+import {
+  createMessageQueue,
+  type MessageQueueController,
+} from "../../runtime/queue/message-queue";
+import {
+  EMPTY_QUEUE_ITEMS,
+  type QueueItemState,
+} from "../../store/scopes/queue-item";
 
 class AbortError extends Error {
   override name = "AbortError";
@@ -54,6 +62,9 @@ export class LocalThreadRuntimeCore
 
   private abortController: AbortController | null = null;
 
+  private _queue: MessageQueueController | null = null;
+  private _queueRunInFlight = false;
+
   public readonly isDisabled = false;
   public readonly isSendDisabled = false;
 
@@ -139,6 +150,31 @@ export class LocalThreadRuntimeCore
       hasUpdates = true;
     }
 
+    const canQueue = options.unstable_enableMessageQueue === true;
+    if (canQueue && !this._queue) {
+      this._queue = createMessageQueue({
+        run: (message) => {
+          // release the queue when the dispatch settles, even if it rejects
+          // before reaching startRun's finally, so a failure can't deadlock it
+          this._queueRunInFlight = true;
+          void this._runAppend(message)
+            .finally(() => {
+              this._queueRunInFlight = false;
+              this._queue?.notifyIdle();
+            })
+            .catch(() => {});
+        },
+      });
+      this._queue.subscribe(() => this._notifySubscribers());
+    } else if (!canQueue && this._queue) {
+      this._queue.adapter.clear("cancel-run");
+      this._queue = null;
+    }
+    if (this.capabilities.queue !== canQueue) {
+      this.capabilities.queue = canQueue;
+      hasUpdates = true;
+    }
+
     if (hasUpdates) this._notifySubscribers();
   }
 
@@ -183,6 +219,31 @@ export class LocalThreadRuntimeCore
   }
 
   public async append(message: AppendMessage): Promise<void> {
+    const isTail = message.parentId === (this.messages.at(-1)?.id ?? null);
+    const willRun = message.startRun ?? message.role === "user";
+    if (this._queue && willRun && isTail) {
+      this._queue.adapter.enqueue(message, { steer: message.steer ?? false });
+      return;
+    }
+    if (this._queue && !isTail) this._queue.adapter.clear("edit");
+    return this._runAppend(message);
+  }
+
+  public getQueueItems(): readonly QueueItemState[] {
+    // Reads can arrive during base-thread construction, before the queue field
+    // is assigned, so guard against the unset field.
+    return this._queue?.adapter.items ?? EMPTY_QUEUE_ITEMS;
+  }
+
+  public steerQueueItem(queueItemId: string): void {
+    this._queue?.adapter.steer(queueItemId);
+  }
+
+  public removeQueueItem(queueItemId: string): void {
+    this._queue?.adapter.remove(queueItemId);
+  }
+
+  private async _runAppend(message: AppendMessage): Promise<void> {
     this.ensureInitialized();
 
     const initPromise = this._getInitializePromise?.();
@@ -254,6 +315,8 @@ export class LocalThreadRuntimeCore
     this._notifyEventSubscribers("runStart", {});
 
     try {
+      // mark busy for runs not started through the queue (regenerate, resume)
+      this._queue?.notifyBusy();
       this._suggestions = [];
       this._suggestionsController?.abort();
       this._suggestionsController = null;
@@ -270,6 +333,11 @@ export class LocalThreadRuntimeCore
       } while (shouldContinue(message, this._options.unstable_humanToolNames));
     } finally {
       this._notifyEventSubscribers("runEnd", {});
+      // queue-driven runs release from the driver settle handler; a direct
+      // run (regenerate, resume) releases here
+      if (!this._queueRunInFlight) {
+        queueMicrotask(() => this._queue?.notifyIdle());
+      }
     }
 
     this._suggestionsController = new AbortController();
@@ -474,12 +542,14 @@ export class LocalThreadRuntimeCore
   }
 
   public detach() {
+    this._queue?.adapter.clear("cancel-run");
     const error = new AbortError(true);
     this.abortController?.abort(error);
     this.abortController = null;
   }
 
   public cancelRun() {
+    this._queue?.adapter.clear("cancel-run");
     const error = new AbortError(false);
     this.abortController?.abort(error);
     this.abortController = null;

package/src/runtimes/readonly/ReadonlyThreadRuntimeCore.ts

@@ -158,6 +158,10 @@ export class ReadonlyThreadRuntimeCore
       // noop
     },
 
+    queue: [] as never[],
+    steerQueueItem() {},
+    removeQueueItem() {},
+
     dictation: undefined,
 
     startDictation() {

package/src/runtimes/remote-thread-list/adapter/in-memory.ts

@@ -17,6 +17,10 @@ export class InMemoryThreadListAdapter implements RemoteThreadListAdapter {
     return Promise.resolve();
   }
 
+  updateCustom(): Promise<void> {
+    return Promise.resolve();
+  }
+
   archive(): Promise<void> {
     return Promise.resolve();
   }

package/src/runtimes/remote-thread-list/empty-thread-core.ts

@@ -139,6 +139,10 @@ export const EMPTY_THREAD_CORE: ThreadRuntimeCore = {
       // noop
     },
 
+    queue: [] as never[],
+    steerQueueItem() {},
+    removeQueueItem() {},
+
     dictation: undefined,
 
     startDictation() {

package/src/runtimes/remote-thread-list/types.ts

@@ -29,6 +29,10 @@ export type RemoteThreadListAdapter = {
   list(params?: RemoteThreadListPageOptions): Promise<RemoteThreadListResponse>;
 
   rename(remoteId: string, newTitle: string): Promise<void>;
+  updateCustom?(
+    remoteId: string,
+    custom: Record<string, unknown> | undefined,
+  ): Promise<void>;
   archive(remoteId: string): Promise<void>;
   unarchive(remoteId: string): Promise<void>;
   delete(remoteId: string): Promise<void>;

package/src/store/clients/chain-of-thought-client.ts

@@ -1,4 +1,5 @@
-import { resource, tapMemo, tapState } from "@assistant-ui/tap";
+import { useMemo, useState } from "react";
+import { resource } from "@assistant-ui/tap";
 import type { ClientOutput } from "@assistant-ui/store";
 import type {
   ChainOfThoughtState,
@@ -11,30 +12,28 @@ const COMPLETE_STATUS: MessagePartStatus = Object.freeze({
   type: "complete",
 });
 
-export const ChainOfThoughtClient = resource(
-  ({
-    parts,
-    getMessagePart,
-  }: {
-    parts: readonly ChainOfThoughtPart[];
-    getMessagePart: (selector: { index: number }) => PartMethods;
-  }): ClientOutput<"chainOfThought"> => {
-    const [collapsed, setCollapsed] = tapState(true);
+export const ChainOfThoughtClient = resource(function ChainOfThoughtClient({
+  parts,
+  getMessagePart,
+}: {
+  parts: readonly ChainOfThoughtPart[];
+  getMessagePart: (selector: { index: number }) => PartMethods;
+}): ClientOutput<"chainOfThought"> {
+  const [collapsed, setCollapsed] = useState(true);
 
-    const status = tapMemo(() => {
-      const lastPart = parts[parts.length - 1];
-      return lastPart?.status ?? COMPLETE_STATUS;
-    }, [parts]);
+  const status = useMemo(() => {
+    const lastPart = parts[parts.length - 1];
+    return lastPart?.status ?? COMPLETE_STATUS;
+  }, [parts]);
 
-    const state = tapMemo<ChainOfThoughtState>(
-      () => ({ parts, collapsed, status }),
-      [parts, collapsed, status],
-    );
+  const state = useMemo<ChainOfThoughtState>(
+    () => ({ parts, collapsed, status }),
+    [parts, collapsed, status],
+  );
 
-    return {
-      getState: () => state,
-      setCollapsed,
-      part: getMessagePart,
-    };
-  },
-);
+  return {
+    getState: () => state,
+    setCollapsed,
+    part: getMessagePart,
+  };
+});

package/src/store/clients/model-context-client.test.ts

@@ -6,6 +6,7 @@ import type {
   ModelContext as ModelContextValue,
   ModelContextProvider,
 } from "../../model-context/types";
+import { mergeModelContexts } from "../../model-context/types";
 
 const tick = () => new Promise<void>((resolve) => setTimeout(resolve, 0));
 
@@ -13,7 +14,7 @@ const provider = (ctx: ModelContextValue): ModelContextProvider => ({
   getModelContext: () => ctx,
 });
 
-const stubTool = (): Tool<any, any> =>
+const toolFixture = (): Tool<any, any> =>
   ({ description: "", parameters: {} as any }) as unknown as Tool<any, any>;
 
 const render = () => {
@@ -51,7 +52,9 @@ describe("ModelContext", () => {
     try {
       sub
         .getValue()
-        .register(provider({ tools: { foo: stubTool(), bar: stubTool() } }));
+        .register(
+          provider({ tools: { foo: toolFixture(), bar: toolFixture() } }),
+        );
       await tick();
 
       expect(sub.getValue().getState().toolNames).toEqual(["bar", "foo"]);
@@ -106,3 +109,85 @@ describe("ModelContext", () => {
     }
   });
 });
+
+describe("mergeModelContexts", () => {
+  it("merges a higher-priority tool override into an existing tool", () => {
+    const execute = async () => ({ ok: true });
+    const merged = mergeModelContexts(
+      new Set([
+        provider({
+          priority: 0,
+          tools: {
+            add_task: {
+              type: "frontend",
+              description: "Add a task",
+              parameters: { type: "object", properties: {} } as any,
+              renderText: { running: "Adding task" },
+            } as Tool<any, any>,
+          },
+        }),
+        provider({
+          priority: 1000,
+          tools: {
+            add_task: {
+              execute,
+            } as unknown as Tool<any, any>,
+          },
+        }),
+      ]),
+    );
+
+    expect(merged.tools?.add_task).toMatchObject({
+      type: "frontend",
+      description: "Add a task",
+    });
+    expect(merged.tools?.add_task?.execute).toBe(execute);
+    expect(merged.tools?.add_task?.parameters).toEqual({
+      type: "object",
+      properties: {},
+    });
+  });
+
+  it("still rejects duplicate tools at the same priority", () => {
+    expect(() =>
+      mergeModelContexts(
+        new Set([
+          provider({ tools: { duplicate: toolFixture() } }),
+          provider({ tools: { duplicate: toolFixture() } }),
+        ]),
+      ),
+    ).toThrow(/already exists/);
+  });
+
+  it("preserves the highest priority when a lower-priority provider reuses the same tool object", () => {
+    const shared = {
+      ...toolFixture(),
+      description: "high priority",
+    } as Tool<any, any>;
+    const execute = async () => ({ ok: true });
+    const merged = mergeModelContexts(
+      new Set([
+        provider({
+          priority: 1000,
+          tools: { shared },
+        }),
+        provider({
+          priority: 0,
+          tools: { shared },
+        }),
+        provider({
+          priority: 500,
+          tools: {
+            shared: {
+              description: "medium priority",
+              execute,
+            } as unknown as Tool<any, any>,
+          },
+        }),
+      ]),
+    );
+
+    expect(merged.tools?.shared?.description).toBe("high priority");
+    expect(merged.tools?.shared?.execute).toBe(execute);
+  });
+});

package/src/store/clients/model-context-client.ts

@@ -1,4 +1,5 @@
-import { resource, tapEffect, tapMemo, tapState } from "@assistant-ui/tap";
+import { useEffect, useMemo, useState } from "react";
+import { resource } from "@assistant-ui/tap";
 import type { ClientOutput } from "@assistant-ui/store";
 import { CompositeContextProvider } from "../../utils/composite-context-provider";
 import type { ModelContextState } from "../scopes/model-context";
@@ -28,23 +29,25 @@ const deriveState = (
   return { modelName, toolNames };
 };
 
-export const ModelContext = resource((): ClientOutput<"modelContext"> => {
-  const composite = tapMemo(() => new CompositeContextProvider(), []);
-  const [state, setState] = tapState<ModelContextState>(() =>
-    deriveState(composite, INITIAL_STATE),
-  );
+export const ModelContext = resource(
+  function ModelContext(): ClientOutput<"modelContext"> {
+    const composite = useMemo(() => new CompositeContextProvider(), []);
+    const [state, setState] = useState<ModelContextState>(() =>
+      deriveState(composite, INITIAL_STATE),
+    );
 
-  tapEffect(() => {
-    setState((prev) => deriveState(composite, prev));
-    return composite.subscribe(() => {
+    useEffect(() => {
       setState((prev) => deriveState(composite, prev));
-    });
-  }, [composite]);
-
-  return {
-    getState: () => deriveState(composite, state),
-    getModelContext: () => composite.getModelContext(),
-    subscribe: (callback) => composite.subscribe(callback),
-    register: (provider) => composite.registerModelContextProvider(provider),
-  };
-});
+      return composite.subscribe(() => {
+        setState((prev) => deriveState(composite, prev));
+      });
+    }, [composite]);
+
+    return {
+      getState: () => deriveState(composite, state),
+      getModelContext: () => composite.getModelContext(),
+      subscribe: (callback) => composite.subscribe(callback),
+      register: (provider) => composite.registerModelContextProvider(provider),
+    };
+  },
+);

package/src/store/clients/no-op-composer-client.ts

@@ -1,71 +1,74 @@
-import { resource, tapMemo } from "@assistant-ui/tap";
+import { useMemo } from "react";
+import { resource } from "@assistant-ui/tap";
 import type { ClientOutput } from "@assistant-ui/store";
 import type { ComposerState } from "../scopes/composer";
 
-export const NoOpComposerClient = resource(
-  ({ type }: { type: "edit" | "thread" }): ClientOutput<"composer"> => {
-    const state = tapMemo<ComposerState>(() => {
-      return {
-        isEditing: false,
-        isEmpty: true,
-        text: "",
-        attachmentAccept: "*",
-        attachments: [],
-        role: "user",
-        runConfig: {},
-        canCancel: false,
-        canSend: false,
-        type: type,
-        dictation: undefined,
-        quote: undefined,
-        queue: [],
-      };
-    }, [type]);
-
+export const NoOpComposerClient = resource(function NoOpComposerClient({
+  type,
+}: {
+  type: "edit" | "thread";
+}): ClientOutput<"composer"> {
+  const state = useMemo<ComposerState>(() => {
     return {
-      getState: () => state,
-      setText: () => {
-        throw new Error("Not supported");
-      },
-      setRole: () => {
-        throw new Error("Not supported");
-      },
-      setRunConfig: () => {
-        throw new Error("Not supported");
-      },
-      addAttachment: () => {
-        throw new Error("Not supported");
-      },
-      clearAttachments: () => {
-        throw new Error("Not supported");
-      },
-      attachment: () => {
-        throw new Error("Not supported");
-      },
-      reset: () => {
-        throw new Error("Not supported");
-      },
-      send: () => {
-        throw new Error("Not supported");
-      },
-      cancel: () => {
-        throw new Error("Not supported");
-      },
-      startDictation: () => {
-        throw new Error("Not supported");
-      },
-      stopDictation: () => {
-        throw new Error("Not supported");
-      },
-      beginEdit: () => {
-        throw new Error("Not supported");
-      },
-      setQuote: () => {
-        throw new Error("Not supported");
-      },
-      queueItem: () => {
-        throw new Error("Not supported");
-      },
+      isEditing: false,
+      isEmpty: true,
+      text: "",
+      attachmentAccept: "*",
+      attachments: [],
+      role: "user",
+      runConfig: {},
+      canCancel: false,
+      canSend: false,
+      type: type,
+      dictation: undefined,
+      quote: undefined,
+      queue: [],
     };
-  },
-);
+  }, [type]);
+
+  return {
+    getState: () => state,
+    setText: () => {
+      throw new Error("Not supported");
+    },
+    setRole: () => {
+      throw new Error("Not supported");
+    },
+    setRunConfig: () => {
+      throw new Error("Not supported");
+    },
+    addAttachment: () => {
+      throw new Error("Not supported");
+    },
+    clearAttachments: () => {
+      throw new Error("Not supported");
+    },
+    attachment: () => {
+      throw new Error("Not supported");
+    },
+    reset: () => {
+      throw new Error("Not supported");
+    },
+    send: () => {
+      throw new Error("Not supported");
+    },
+    cancel: () => {
+      throw new Error("Not supported");
+    },
+    startDictation: () => {
+      throw new Error("Not supported");
+    },
+    stopDictation: () => {
+      throw new Error("Not supported");
+    },
+    beginEdit: () => {
+      throw new Error("Not supported");
+    },
+    setQuote: () => {
+      throw new Error("Not supported");
+    },
+    queueItem: () => {
+      throw new Error("Not supported");
+    },
+  };
+});

package/src/store/clients/runtime-adapter.ts

@@ -1,8 +1,9 @@
-import { resource, tapEffect, tapResource } from "@assistant-ui/tap";
+import { useEffect } from "react";
+import { useResource, resource } from "@assistant-ui/tap";
 import type { AssistantRuntime } from "../../runtime/api/assistant-runtime";
 import { ThreadListClient } from "../runtime-clients/thread-list-runtime-client";
 import {
-  tapAssistantClientRef,
+  useAssistantClientRef,
   Derived,
   type ScopesConfig,
   type AssistantClient,
@@ -10,16 +11,18 @@ import {
 import { ModelContext } from "./model-context-client";
 import { Suggestions } from "./suggestions";
 
-export const RuntimeAdapterResource = resource((runtime: AssistantRuntime) => {
-  const clientRef = tapAssistantClientRef();
+export const RuntimeAdapterResource = resource(function RuntimeAdapterResource(
+  runtime: AssistantRuntime,
+) {
+  const clientRef = useAssistantClientRef();
 
-  tapEffect(() => {
+  useEffect(() => {
     return runtime.registerModelContextProvider(
       clientRef.current!.modelContext(),
     );
   }, [runtime, clientRef]);
 
-  return tapResource(
+  return useResource(
     ThreadListClient({
       runtime: runtime.threads,
       __internal_assistantRuntime: runtime,