@assistant-ui/core 0.2.10 → 0.2.12

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

@@ -3,6 +3,7 @@ import { ExternalStoreThreadRuntimeCore } from "../runtimes/external-store/exter
 import type { ExternalStoreAdapter } from "../runtimes/external-store/external-store-adapter";
 import type { ModelContextProvider } from "../model-context/types";
 import type { ThreadMessageLike } from "../runtime/utils/thread-message-like";
+import type { AppendMessage } from "../types/message";
 
 const mockContextProvider: ModelContextProvider = {
   getModelContext: () => ({}),
@@ -379,3 +380,127 @@ describe("ExternalStoreThreadRuntimeCore - initialize event replay", () => {
     expect(callback).not.toHaveBeenCalled();
   });
 });
+
+describe("ExternalStoreThreadRuntimeCore - message queue", () => {
+  const makeQueue = () => ({
+    items: [] as never[],
+    enqueue: vi.fn(),
+    steer: vi.fn(),
+    remove: vi.fn(),
+    clear: vi.fn(),
+  });
+
+  const appendMessage = (
+    overrides?: Partial<AppendMessage>,
+  ): AppendMessage => ({
+    role: "user",
+    content: [{ type: "text", text: "hello" }],
+    attachments: [],
+    createdAt: new Date(0),
+    parentId: null,
+    sourceId: null,
+    runConfig: {},
+    metadata: { custom: {} },
+    ...overrides,
+  });
+
+  it("exposes capabilities.queue from adapter presence", () => {
+    const withQueue = new ExternalStoreThreadRuntimeCore(
+      mockContextProvider,
+      makeStore({ queue: makeQueue() }),
+    );
+    expect(withQueue.capabilities.queue).toBe(true);
+
+    const withoutQueue = new ExternalStoreThreadRuntimeCore(
+      mockContextProvider,
+      makeStore(),
+    );
+    expect(withoutQueue.capabilities.queue).toBe(false);
+  });
+
+  it("routes a tail append through queue.enqueue instead of onNew", async () => {
+    const queue = makeQueue();
+    const onNew = vi.fn();
+    const runtime = new ExternalStoreThreadRuntimeCore(
+      mockContextProvider,
+      makeStore({ queue, onNew }),
+    );
+
+    await runtime.append(appendMessage({ steer: true }));
+
+    expect(onNew).not.toHaveBeenCalled();
+    expect(queue.enqueue).toHaveBeenCalledTimes(1);
+    expect(queue.enqueue.mock.calls[0]![1]).toEqual({ steer: true });
+  });
+
+  it("does not abort in-flight tools when buffering a queued send", async () => {
+    const queue = makeQueue();
+    const runtime = new ExternalStoreThreadRuntimeCore(
+      mockContextProvider,
+      makeStore({ queue, onNew: vi.fn() }),
+    );
+    const abort = vi.fn();
+    (runtime as unknown as { _toolInvocations: unknown })._toolInvocations = {
+      abort,
+    };
+
+    await runtime.append(appendMessage());
+
+    expect(queue.enqueue).toHaveBeenCalledTimes(1);
+    expect(abort).not.toHaveBeenCalled();
+  });
+
+  it("aborts in-flight tools when a send actually starts a run", async () => {
+    const runtime = new ExternalStoreThreadRuntimeCore(
+      mockContextProvider,
+      makeStore({ onNew: vi.fn() }),
+    );
+    const abort = vi.fn();
+    (runtime as unknown as { _toolInvocations: unknown })._toolInvocations = {
+      abort,
+    };
+
+    await runtime.append(appendMessage());
+
+    expect(abort).toHaveBeenCalledTimes(1);
+  });
+
+  it("clears the queue on cancel, reload, and edit", async () => {
+    const queue = makeQueue();
+    const runtime = new ExternalStoreThreadRuntimeCore(
+      mockContextProvider,
+      makeStore({
+        queue,
+        onCancel: vi.fn(),
+        onReload: vi.fn(),
+        onEdit: vi.fn(),
+      }),
+    );
+
+    runtime.cancelRun();
+    expect(queue.clear).toHaveBeenCalledWith("cancel-run");
+
+    await runtime.startRun({ parentId: null, sourceId: null, runConfig: {} });
+    expect(queue.clear).toHaveBeenCalledWith("reload");
+
+    // a non-tail parentId routes to the edit branch
+    await runtime.append(appendMessage({ parentId: "not-the-tail" }));
+    expect(queue.clear).toHaveBeenCalledWith("edit");
+  });
+
+  it("delegates getQueueItems / steer / remove to the adapter", () => {
+    const queue = makeQueue();
+    const items = [{ id: "q1", prompt: "queued" }];
+    queue.items = items as never;
+    const runtime = new ExternalStoreThreadRuntimeCore(
+      mockContextProvider,
+      makeStore({ queue }),
+    );
+
+    expect(runtime.getQueueItems()).toBe(items);
+    runtime.steerQueueItem("q1");
+    runtime.removeQueueItem("q1");
+    expect(queue.steer).toHaveBeenCalledWith("q1");
+    expect(queue.remove).toHaveBeenCalledWith("q1");
+  });
+});

package/src/tests/message-queue.test.ts

@@ -0,0 +1,168 @@
+import { describe, it, expect, vi } from "vitest";
+import { createMessageQueue } from "../runtime/queue/message-queue";
+import type { AppendMessage } from "../types/message";
+
+const msg = (text: string, extra?: Partial<AppendMessage>): AppendMessage => ({
+  role: "user",
+  content: [{ type: "text", text }],
+  attachments: [],
+  createdAt: new Date(0),
+  parentId: null,
+  sourceId: null,
+  runConfig: {},
+  metadata: { custom: {} },
+  ...extra,
+});
+
+describe("createMessageQueue", () => {
+  it("runs immediately when idle and holds while running", () => {
+    const run = vi.fn();
+    const { adapter, notifyIdle } = createMessageQueue({ run });
+
+    adapter.enqueue(msg("first"), { steer: false });
+    expect(run).toHaveBeenCalledTimes(1);
+    expect(adapter.items).toHaveLength(0);
+
+    adapter.enqueue(msg("second"), { steer: false });
+    expect(run).toHaveBeenCalledTimes(1);
+    expect(adapter.items.map((i) => i.prompt)).toEqual(["second"]);
+
+    notifyIdle();
+    expect(run).toHaveBeenCalledTimes(2);
+    expect(adapter.items).toHaveLength(0);
+  });
+
+  it("drains FIFO across multiple queued messages", () => {
+    const order: string[] = [];
+    const run = vi.fn((m: AppendMessage) =>
+      order.push((m.content[0] as { text: string }).text),
+    );
+    const { adapter, notifyIdle } = createMessageQueue({ run });
+
+    adapter.enqueue(msg("a"), { steer: false }); // runs now
+    adapter.enqueue(msg("b"), { steer: false });
+    adapter.enqueue(msg("c"), { steer: false });
+    expect(adapter.items.map((i) => i.prompt)).toEqual(["b", "c"]);
+
+    notifyIdle();
+    notifyIdle();
+    expect(order).toEqual(["a", "b", "c"]);
+  });
+
+  it("hands the full original AppendMessage to the driver", () => {
+    const run = vi.fn();
+    const { adapter, notifyIdle } = createMessageQueue({ run });
+    const attachments = [{ id: "x" }] as never;
+    const runConfig = { custom: { k: 1 } };
+
+    adapter.enqueue(msg("busy"), { steer: false });
+    adapter.enqueue(msg("queued", { attachments, runConfig }), {
+      steer: false,
+    });
+    notifyIdle();
+
+    expect(run).toHaveBeenLastCalledWith(
+      expect.objectContaining({ attachments, runConfig }),
+      { steer: false },
+    );
+  });
+
+  it("removes a queued message before it runs", () => {
+    const run = vi.fn();
+    const { adapter, notifyIdle } = createMessageQueue({ run });
+
+    adapter.enqueue(msg("a"), { steer: false }); // runs now
+    adapter.enqueue(msg("b"), { steer: false });
+    adapter.enqueue(msg("c"), { steer: false });
+
+    adapter.remove(adapter.items[0]!.id); // remove "b"
+    expect(adapter.items.map((i) => i.prompt)).toEqual(["c"]);
+
+    notifyIdle();
+    expect(run).toHaveBeenLastCalledWith(
+      expect.objectContaining({ content: [{ type: "text", text: "c" }] }),
+      { steer: false },
+    );
+  });
+
+  it("clear() empties pending items", () => {
+    const run = vi.fn();
+    const { adapter } = createMessageQueue({ run });
+    adapter.enqueue(msg("a"), { steer: false });
+    adapter.enqueue(msg("b"), { steer: false });
+    adapter.clear("cancel-run");
+    expect(adapter.items).toHaveLength(0);
+  });
+
+  it("steers via cancel and suppresses the cancelled run's idle (no double-dequeue)", () => {
+    const run = vi.fn();
+    const cancel = vi.fn();
+    const { adapter, notifyIdle } = createMessageQueue({ run, cancel });
+
+    adapter.enqueue(msg("a"), { steer: false }); // running
+    adapter.enqueue(msg("b"), { steer: false }); // queued
+    adapter.enqueue(msg("steer-me"), { steer: true });
+
+    expect(cancel).toHaveBeenCalledTimes(1);
+    expect(run).toHaveBeenLastCalledWith(
+      expect.objectContaining({
+        content: [{ type: "text", text: "steer-me" }],
+      }),
+      { steer: true },
+    );
+    const runsAfterSteer = run.mock.calls.length;
+
+    // the cancelled run's settle must NOT advance the queue
+    notifyIdle();
+    expect(run).toHaveBeenCalledTimes(runsAfterSteer);
+
+    // the steered run's real settle drains the rest
+    notifyIdle();
+    expect(run).toHaveBeenLastCalledWith(
+      expect.objectContaining({ content: [{ type: "text", text: "b" }] }),
+      { steer: false },
+    );
+  });
+
+  it("degrades steer to run-next when no cancel is available", () => {
+    const run = vi.fn();
+    const { adapter, notifyIdle } = createMessageQueue({ run }); // no cancel
+
+    adapter.enqueue(msg("a"), { steer: false }); // running
+    adapter.enqueue(msg("b"), { steer: false });
+    adapter.enqueue(msg("urgent"), { steer: true });
+
+    // no interrupt: "urgent" jumps the queue ahead of "b"
+    expect(adapter.items.map((i) => i.prompt)).toEqual(["urgent", "b"]);
+
+    notifyIdle();
+    expect(run).toHaveBeenLastCalledWith(
+      expect.objectContaining({ content: [{ type: "text", text: "urgent" }] }),
+      { steer: false },
+    );
+  });
+
+  it("notifies subscribers on item changes", () => {
+    const run = vi.fn();
+    const { adapter, subscribe } = createMessageQueue({ run });
+    const cb = vi.fn();
+    subscribe(cb);
+
+    adapter.enqueue(msg("a"), { steer: false }); // runs (1 setItems push + 1 pop)
+    expect(cb).toHaveBeenCalled();
+  });
+
+  it("buffers when a run started outside the queue is marked busy", () => {
+    const run = vi.fn();
+    const { adapter, notifyBusy, notifyIdle } = createMessageQueue({ run });
+
+    notifyBusy(); // e.g. a regenerate started without going through the queue
+    adapter.enqueue(msg("a"), { steer: false });
+    expect(run).not.toHaveBeenCalled();
+    expect(adapter.items.map((i) => i.prompt)).toEqual(["a"]);
+
+    notifyIdle(); // that run settled
+    expect(run).toHaveBeenCalledTimes(1);
+    expect(adapter.items).toHaveLength(0);
+  });
+});

package/src/types/message.ts

@@ -354,4 +354,6 @@ export type AppendMessage = Omit<ThreadMessage, "id"> & {
   sourceId: string | null;
   runConfig: RunConfig | undefined;
   startRun?: boolean | undefined;
+  /** Process this message next; only meaningful for queue-capable runtimes. */
+  steer?: boolean | undefined;
 };

package/src/utils/composite-context-provider.ts

@@ -31,6 +31,8 @@ export class CompositeContextProvider implements ModelContextProvider {
 
   subscribe(callback: () => void) {
     this._subscribers.add(callback);
-    return () => this._subscribers.delete(callback);
+    return () => {
+      this._subscribers.delete(callback);
+    };
   }
 }

package/dist/react/model-context/hitl.d.ts

@@ -1,23 +0,0 @@
-//#region src/react/model-context/hitl.d.ts
-/**
- * Marks a tool as **human-in-the-loop**: the agent pauses and the UI (`render`)
- * supplies the result instead of code. Use it as the tool's `execute`:
- *
- * ```tsx
- * confirm: { execute: hitlTool(), render: (props) => <Confirm {...props} /> }
- * ```
- *
- * Like {@link defineToolkit}, it has **no runtime implementation**: a
- * `"use generative"` compiler (e.g. `@assistant-ui/next` or `@assistant-ui/vite`)
- * detects `execute: hitlTool()`, drops it, and stamps the tool `type: "human"`.
- * Reaching it at runtime means the module wasn't compiled (used outside a
- * `"use generative"` file), so it throws.
- */
-declare function hitlTool(): never;
-/**
- * @deprecated Use {@link hitlTool}.
- */
-declare const hitl: typeof hitlTool;
-//#endregion
-export { hitl, hitlTool };
-//# sourceMappingURL=hitl.d.ts.map

package/dist/react/model-context/hitl.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"hitl.d.ts","names":[],"sources":["../../../src/react/model-context/hitl.ts"],"mappings":";;AAcA;;;;AAAwB;AAYxB;;;;AAA4B;;;;iBAZZ,QAAA;;;;cAYH,IAAA,SAAI,QAAW"}

package/dist/react/model-context/hitl.js

@@ -1,26 +0,0 @@
-//#region src/react/model-context/hitl.ts
-/**
-* Marks a tool as **human-in-the-loop**: the agent pauses and the UI (`render`)
-* supplies the result instead of code. Use it as the tool's `execute`:
-*
-* ```tsx
-* confirm: { execute: hitlTool(), render: (props) => <Confirm {...props} /> }
-* ```
-*
-* Like {@link defineToolkit}, it has **no runtime implementation**: a
-* `"use generative"` compiler (e.g. `@assistant-ui/next` or `@assistant-ui/vite`)
-* detects `execute: hitlTool()`, drops it, and stamps the tool `type: "human"`.
-* Reaching it at runtime means the module wasn't compiled (used outside a
-* `"use generative"` file), so it throws.
-*/
-function hitlTool() {
-	throw new Error("[assistant-ui] hitlTool() has no runtime implementation — it marks a human-in-the-loop tool and is stripped at build time by the use-generative compiler. Reaching it means this module was not compiled (e.g. hitlTool() used outside a \"use generative\" file).");
-}
-/**
-* @deprecated Use {@link hitlTool}.
-*/
-const hitl = hitlTool;
-//#endregion
-export { hitl, hitlTool };
-
-//# sourceMappingURL=hitl.js.map

package/dist/react/model-context/hitl.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"hitl.js","names":[],"sources":["../../../src/react/model-context/hitl.ts"],"sourcesContent":["/**\n * Marks a tool as **human-in-the-loop**: the agent pauses and the UI (`render`)\n * supplies the result instead of code. Use it as the tool's `execute`:\n *\n * ```tsx\n * confirm: { execute: hitlTool(), render: (props) => <Confirm {...props} /> }\n * ```\n *\n * Like {@link defineToolkit}, it has **no runtime implementation**: a\n * `\"use generative\"` compiler (e.g. `@assistant-ui/next` or `@assistant-ui/vite`)\n * detects `execute: hitlTool()`, drops it, and stamps the tool `type: \"human\"`.\n * Reaching it at runtime means the module wasn't compiled (used outside a\n * `\"use generative\"` file), so it throws.\n */\nexport function hitlTool(): never {\n  throw new Error(\n    \"[assistant-ui] hitlTool() has no runtime implementation — it marks a \" +\n      \"human-in-the-loop tool and is stripped at build time by the \" +\n      \"use-generative compiler. Reaching it means this module was not compiled \" +\n      '(e.g. hitlTool() used outside a \"use generative\" file).',\n  );\n}\n\n/**\n * @deprecated Use {@link hitlTool}.\n */\nexport const hitl = hitlTool;\n"],"mappings":";;;;;;;;;;;;;;;AAcA,SAAgB,WAAkB;CAChC,MAAM,IAAI,MACR,oQAIF;AACF;;;;AAKA,MAAa,OAAO"}

package/dist/store/runtime-clients/tap-subscribable.d.ts

@@ -1,7 +0,0 @@
-import { SubscribableWithState } from "../../subscribable/subscribable.js";
-
-//#region src/store/runtime-clients/tap-subscribable.d.ts
-declare const tapSubscribable: <T>(subscribable: Omit<SubscribableWithState<T, any>, "path">) => T;
-//#endregion
-export { tapSubscribable };
-//# sourceMappingURL=tap-subscribable.d.ts.map

package/dist/store/runtime-clients/tap-subscribable.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"tap-subscribable.d.ts","names":[],"sources":["../../../src/store/runtime-clients/tap-subscribable.ts"],"mappings":";;;cAGa,eAAA,MACX,YAAA,EAAc,IAAA,CAAK,qBAAA,CAAsB,CAAA,oBAAgB,CAAA"}

package/dist/store/runtime-clients/tap-subscribable.js

@@ -1,16 +0,0 @@
-import { tapEffect, tapState } from "@assistant-ui/tap";
-//#region src/store/runtime-clients/tap-subscribable.ts
-const tapSubscribable = (subscribable) => {
-	const [, setState] = tapState(subscribable.getState);
-	tapEffect(() => {
-		setState(subscribable.getState());
-		return subscribable.subscribe(() => {
-			setState(subscribable.getState());
-		});
-	}, [subscribable]);
-	return subscribable.getState();
-};
-//#endregion
-export { tapSubscribable };
-
-//# sourceMappingURL=tap-subscribable.js.map

package/dist/store/runtime-clients/tap-subscribable.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"tap-subscribable.js","names":[],"sources":["../../../src/store/runtime-clients/tap-subscribable.ts"],"sourcesContent":["import { tapState, tapEffect } from \"@assistant-ui/tap\";\nimport type { SubscribableWithState } from \"../../subscribable/subscribable\";\n\nexport const tapSubscribable = <T>(\n  subscribable: Omit<SubscribableWithState<T, any>, \"path\">,\n) => {\n  const [, setState] = tapState(subscribable.getState);\n  tapEffect(() => {\n    setState(subscribable.getState());\n    return subscribable.subscribe(() => {\n      setState(subscribable.getState());\n    });\n  }, [subscribable]);\n\n  return subscribable.getState();\n};\n"],"mappings":";;AAGA,MAAa,mBACX,iBACG;CACH,MAAM,GAAG,YAAY,SAAS,aAAa,QAAQ;CACnD,gBAAgB;EACd,SAAS,aAAa,SAAS,CAAC;EAChC,OAAO,aAAa,gBAAgB;GAClC,SAAS,aAAa,SAAS,CAAC;EAClC,CAAC;CACH,GAAG,CAAC,YAAY,CAAC;CAEjB,OAAO,aAAa,SAAS;AAC/B"}