@assistant-ui/core 0.3.16 → 0.3.18

package/src/runtimes/remote-thread-list/title-generation.ts

@@ -0,0 +1,329 @@
+export type ThreadTitleClaim = {
+  readonly title: string;
+  readonly order: number;
+  readonly settled: Promise<boolean>;
+  readonly settle: (renamed: boolean) => void;
+};
+
+type ThreadTitleGeneration = {
+  readonly automatic: boolean;
+  readonly order: number;
+  claim: ThreadTitleClaim | null;
+  beforeGenerationClaims: readonly ThreadTitleClaim[];
+  superseded: boolean;
+  readonly persisted: Promise<string | undefined>;
+  readonly settlePersisted: (title: string | undefined) => void;
+};
+
+export type ThreadTitleState = {
+  generations: Set<ThreadTitleGeneration>;
+  pendingClaim: ThreadTitleClaim | null;
+  inFlightClaims: Set<ThreadTitleClaim>;
+  manualTitle: string | undefined;
+  latestExplicit: ThreadTitleGeneration | null;
+  nextOrder: number;
+};
+
+export type ThreadTitleGenerationRun = {
+  states: Map<string, ThreadTitleState>;
+  threadId: string;
+  automatic: boolean;
+  generate: (
+    onTitle: (title: string | undefined) => Promise<void>,
+  ) => Promise<void>;
+  rename: (title: string) => Promise<void>;
+  applyTitle: (title: string | undefined) => Promise<void>;
+};
+
+function getThreadTitleState(
+  states: Map<string, ThreadTitleState>,
+  threadId: string,
+): ThreadTitleState {
+  let state = states.get(threadId);
+  if (state === undefined) {
+    state = {
+      generations: new Set(),
+      pendingClaim: null,
+      inFlightClaims: new Set(),
+      manualTitle: undefined,
+      latestExplicit: null,
+      nextOrder: 0,
+    };
+    states.set(threadId, state);
+  }
+  return state;
+}
+
+function pruneThreadTitleState(
+  states: Map<string, ThreadTitleState>,
+  threadId: string,
+  state: ThreadTitleState,
+): void {
+  if (
+    state.generations.size === 0 &&
+    state.pendingClaim === null &&
+    state.inFlightClaims.size === 0 &&
+    state.manualTitle === undefined &&
+    states.get(threadId) === state
+  ) {
+    states.delete(threadId);
+  }
+}
+
+function isCurrentGeneration(
+  state: ThreadTitleState,
+  generation: ThreadTitleGeneration,
+): boolean {
+  return (
+    !generation.superseded &&
+    (state.latestExplicit?.order ?? 0) <= generation.order
+  );
+}
+
+function isCurrentClaim(
+  state: ThreadTitleState,
+  claim: ThreadTitleClaim,
+): boolean {
+  return (state.latestExplicit?.order ?? 0) < claim.order;
+}
+
+export function startThreadTitleRename(
+  states: Map<string, ThreadTitleState>,
+  threadId: string,
+  title: string,
+): ThreadTitleClaim {
+  const state = getThreadTitleState(states, threadId);
+  let settle!: (renamed: boolean) => void;
+  const settled = new Promise<boolean>((resolve) => {
+    settle = resolve;
+  });
+  const claim: ThreadTitleClaim = {
+    title,
+    order: ++state.nextOrder,
+    settled,
+    settle,
+  };
+  state.pendingClaim = claim;
+  state.inFlightClaims.add(claim);
+  for (const generation of state.generations) {
+    if (generation.order < claim.order) generation.claim = claim;
+  }
+  return claim;
+}
+
+export function finishThreadTitleRename(
+  states: Map<string, ThreadTitleState>,
+  threadId: string,
+  claim: ThreadTitleClaim,
+  renamed: boolean,
+): void {
+  claim.settle(renamed);
+  const state = states.get(threadId);
+  if (state === undefined) return;
+  state.inFlightClaims.delete(claim);
+  if (state.pendingClaim === claim) {
+    state.pendingClaim = null;
+    if (renamed) {
+      state.manualTitle = claim.title;
+    }
+  }
+  pruneThreadTitleState(states, threadId, state);
+}
+
+function takeManualTitle(
+  states: Map<string, ThreadTitleState>,
+  threadId: string,
+  state: ThreadTitleState,
+): string | undefined {
+  const retained = state.manualTitle;
+  if (retained === undefined) return undefined;
+  state.manualTitle = undefined;
+  pruneThreadTitleState(states, threadId, state);
+  return retained;
+}
+
+export function clearThreadTitleState(
+  states: Map<string, ThreadTitleState>,
+  threadId: string,
+): void {
+  states.delete(threadId);
+}
+
+function startThreadTitleGeneration(
+  states: Map<string, ThreadTitleState>,
+  threadId: string,
+  automatic: boolean,
+): ThreadTitleGeneration | null {
+  const state = getThreadTitleState(states, threadId);
+  if (
+    automatic &&
+    state.pendingClaim === null &&
+    takeManualTitle(states, threadId, state) !== undefined
+  ) {
+    return null;
+  }
+
+  let settlePersisted!: (title: string | undefined) => void;
+  const persisted = new Promise<string | undefined>((resolve) => {
+    settlePersisted = resolve;
+  });
+  const generation: ThreadTitleGeneration = {
+    automatic,
+    order: ++state.nextOrder,
+    claim: automatic ? state.pendingClaim : null,
+    beforeGenerationClaims: automatic ? [] : [...state.inFlightClaims],
+    superseded: false,
+    persisted,
+    settlePersisted,
+  };
+  if (!automatic) {
+    state.pendingClaim = null;
+    state.manualTitle = undefined;
+    state.latestExplicit = generation;
+    for (const active of state.generations) {
+      if (active.automatic) active.superseded = true;
+    }
+  }
+  state.generations.add(generation);
+  return generation;
+}
+
+/**
+ * Runs one title generation under the per-thread rename claims and generation
+ * ordering, so the title that wins locally is also the title left on the
+ * server.
+ *
+ * A generated run persists the title itself, and the adapter exposes no
+ * compare-and-set, so the run that loses reasserts the winner through `rename`
+ * only after `generate` has resolved. Reasserting mid-stream would race the
+ * run's own write and lose the winning title on the server.
+ */
+export async function runThreadTitleGeneration({
+  states,
+  threadId,
+  automatic,
+  generate,
+  rename,
+  applyTitle,
+}: ThreadTitleGenerationRun): Promise<void> {
+  const state = getThreadTitleState(states, threadId);
+  const generation = startThreadTitleGeneration(states, threadId, automatic);
+  if (generation === null) return;
+
+  let persistedTitle: string | undefined;
+  let persistedOrder = generation.order;
+
+  const settleClaim = async (claim: ThreadTitleClaim) => {
+    const renamed = await claim.settled;
+    if (generation.claim !== claim) return undefined;
+    if (!renamed) {
+      generation.claim = null;
+      if (state.pendingClaim === claim) state.pendingClaim = null;
+    }
+    return renamed;
+  };
+
+  const retainManualTitle = () =>
+    automatic && takeManualTitle(states, threadId, state) !== undefined;
+
+  // `generate` resolves only once the run has persisted its title, so a run
+  // that lost the ordering race while it streamed has already overwritten the
+  // winner. It waits for the winning generation to persist its own title and
+  // writes that title back.
+  const repairLostRace = async () => {
+    if (persistedTitle === undefined) return;
+    while (true) {
+      const claim = generation.claim;
+      if (
+        claim !== null &&
+        claim.order > persistedOrder &&
+        isCurrentClaim(state, claim)
+      ) {
+        const renamed = await settleClaim(claim);
+        if (renamed === true) {
+          persistedTitle = claim.title;
+          persistedOrder = claim.order;
+          await rename(claim.title);
+        }
+        continue;
+      }
+      const winner = state.latestExplicit;
+      if (winner === null || winner.order <= persistedOrder) return;
+      const title = await winner.persisted;
+      if (state.latestExplicit !== winner) continue;
+      persistedOrder = winner.order;
+      if (title === undefined || title === persistedTitle) return;
+      persistedTitle = title;
+      await rename(title);
+    }
+  };
+
+  const runGeneration = async () => {
+    // An explicit generation waits for every earlier rename because any of
+    // those server writes may settle last.
+    if (generation.beforeGenerationClaims.length > 0) {
+      await Promise.all(
+        generation.beforeGenerationClaims.map((claim) => claim.settled),
+      );
+    }
+    if (generation.claim !== null) {
+      const renamed = await settleClaim(generation.claim);
+      if (renamed === true) {
+        generation.superseded = true;
+        return;
+      }
+      if (renamed === false && retainManualTitle()) return;
+    }
+    if (!isCurrentGeneration(state, generation)) return;
+
+    let sawTitle = false;
+    let lastTitle: string | undefined;
+    await generate(async (title) => {
+      sawTitle = true;
+      lastTitle = title;
+      if (title !== undefined) persistedTitle = title;
+      const claim = generation.claim;
+      if (claim !== null) {
+        const renamed = await settleClaim(claim);
+        if (renamed !== false) return;
+        if (retainManualTitle()) {
+          generation.superseded = true;
+          return;
+        }
+      }
+      if (isCurrentGeneration(state, generation)) await applyTitle(lastTitle);
+    });
+
+    while (true) {
+      const claim = generation.claim;
+      if (claim === null) return;
+      const renamed = await settleClaim(claim);
+      if (renamed === undefined) continue;
+      if (renamed === false) {
+        if (retainManualTitle()) return;
+        if (sawTitle && isCurrentGeneration(state, generation)) {
+          await applyTitle(lastTitle);
+        }
+        return;
+      }
+      if (!isCurrentClaim(state, claim)) return;
+      await rename(claim.title);
+      persistedTitle = claim.title;
+      persistedOrder = claim.order;
+      if (generation.claim !== claim) continue;
+      if (!isCurrentGeneration(state, generation)) return;
+      await applyTitle(claim.title);
+      generation.superseded = true;
+      return;
+    }
+  };
+
+  try {
+    await runGeneration();
+    await repairLostRace();
+  } finally {
+    generation.settlePersisted(persistedTitle);
+    state.generations.delete(generation);
+    pruneThreadTitleState(states, threadId, state);
+  }
+}

package/src/runtimes/remote-thread-list/title.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from "vitest";
+import { applyTitleStream } from "./title";
+
+const createTextStream = (text: string) =>
+  new ReadableStream({
+    start(controller) {
+      controller.enqueue({
+        type: "part-start",
+        path: [0],
+        part: { type: "text" },
+      });
+      controller.enqueue({
+        type: "text-delta",
+        path: [0],
+        textDelta: text,
+      });
+      controller.enqueue({ type: "part-finish", path: [0] });
+      controller.close();
+    },
+  }) as never;
+
+describe("applyTitleStream", () => {
+  it("ignores an empty stream", async () => {
+    const titles: (string | undefined)[] = [];
+
+    await applyTitleStream(
+      new ReadableStream({
+        start(controller) {
+          controller.close();
+        },
+      }) as never,
+      async (title) => {
+        titles.push(title);
+      },
+    );
+
+    expect(titles).toEqual([]);
+  });
+
+  it("ignores whitespace-only titles", async () => {
+    const titles: (string | undefined)[] = [];
+
+    await applyTitleStream(createTextStream("   "), async (title) => {
+      titles.push(title);
+    });
+
+    expect(titles).toEqual([]);
+  });
+
+  it("forwards titles containing text unchanged", async () => {
+    const titles: (string | undefined)[] = [];
+
+    await applyTitleStream(
+      createTextStream(" Generated title "),
+      async (title) => {
+        titles.push(title);
+      },
+    );
+
+    expect(titles).toContain(" Generated title ");
+  });
+});

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

@@ -0,0 +1,16 @@
+import { AssistantMessageStream } from "assistant-stream";
+
+export const isTitleSourceMessage = (message: {
+  status?: { type: string } | undefined;
+}) => message.status?.type !== "running";
+
+export const applyTitleStream = async (
+  stream: Parameters<typeof AssistantMessageStream.fromAssistantStream>[0],
+  onTitle: (title: string | undefined) => Promise<void>,
+) => {
+  const messageStream = AssistantMessageStream.fromAssistantStream(stream);
+  for await (const result of messageStream) {
+    const title = result.parts.filter((part) => part.type === "text")[0]?.text;
+    if (title?.trim()) await onTitle(title);
+  }
+};

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

@@ -3,6 +3,7 @@ import type { AssistantRuntime } from "../../runtime/api/assistant-runtime";
 import type { AssistantStream } from "assistant-stream";
 import type { ThreadHistoryAdapter } from "../../adapters/thread-history";
 import type { AttachmentAdapter } from "../../adapters/attachment";
+import type { FeedbackAdapter } from "../../adapters/feedback";
 import type { ModelContextProvider } from "../../model-context/types";
 
 /* oxlint-disable typescript/no-explicit-any -- structural stand-in for ComponentType without depending on react types */
@@ -40,6 +41,7 @@ export type RuntimeAdapters = {
   modelContext?: ModelContextProvider | undefined;
   history?: ThreadHistoryAdapter | undefined;
   attachments?: AttachmentAdapter | undefined;
+  feedback?: FeedbackAdapter | undefined;
 };
 
 export type RemoteThreadListAdapter = {
@@ -54,6 +56,14 @@ export type RemoteThreadListAdapter = {
   unarchive(remoteId: string): Promise<void>;
   delete(remoteId: string): Promise<void>;
   initialize(threadId: string): Promise<RemoteThreadInitializeResponse>;
+  /**
+   * Generates a title for the thread and streams it back.
+   *
+   * When the generation persists the title itself, the returned stream must
+   * not complete before that write has landed. Concurrent generations are
+   * ordered by stream completion, and a run whose write outlives its stream
+   * can overwrite a newer title.
+   */
   generateTitle(
     remoteId: string,
     unstable_messages: readonly ThreadMessage[],
@@ -78,11 +88,12 @@ export type RemoteThreadListAdapter = {
   unstable_Provider?: RemoteThreadListProviderComponent | undefined;
 
   /**
-   * Hook the `RemoteThreadList` store entry calls once for the main-thread
-   * slot, then provides to the `thread` factory. This is not mounted per
-   * listed thread. `useRemoteThreadListRuntime` also calls it when
-   * `unstable_Provider` is omitted. Resolve `threadListItem` lazily on each
-   * adapter call; do not capture it at hook mount. The hook must keep a
+   * Hook the `RemoteThreadList` store entry calls once per mounted thread
+   * body (the main-thread slot by default; every started thread with
+   * `backgroundThreads`), then provides to the `thread` factory. This is not
+   * mounted per listed thread. `useRemoteThreadListRuntime` also calls it
+   * when `unstable_Provider` is omitted. Resolve `threadListItem` lazily on
+   * each adapter call; do not capture it at hook mount. The hook must keep a
    * stable hook count across adapter swaps; a different count throws.
    * Memoize the returned object.
    *

package/src/runtimes/tool-invocations/EDGE_CASES.md

@@ -11,8 +11,9 @@ observe via `setState(snapshot)` and what the current behavior is.
 > result is replaced, result is cleared, key order shuffles — the tracker
 > never invokes the host's tool callback a second time.
 >
-> `reset()` starts a new execution boundary. A reused `toolCallId` in the
-> next boundary gets a new execution identity and may fire once there.
+> `reset()` starts a new execution boundary, and so does the single
+> pipeline restart after a stream failure (F.4). A reused `toolCallId` in
+> the next boundary gets a new execution identity and may fire once there.
 
 This guarantees host-side side effects (the typical reason `streamCall` /
 `execute` exists at all) can't double-run. The cost: post-completion
@@ -92,8 +93,102 @@ in-flight `execute` resolves, the execute runs to completion (its side
 effects happen) but its result chunk is dropped: `onResult` never fires,
 and the `executing` status, plus any `human()` interrupt the execution
 parked, stays up until the promise settles. Only a gate that lands after
-the result chunk has already been emitted is fully too late; the adapter
-must project the gate before that (#6285).
+the result chunk has already been emitted is fully too late.
+
+A call the adapter reports as client-owned reaches that window while the
+run is still open; a call whose ownership is unknown reaches it when the
+run settles before the gate arrives (A.10). Either way the client was
+meant to run it, so nothing but the gate's arrival says otherwise and the
+gate is late by construction.
+
+### A.9. Adapter reports the tool call as provider-owned
+The entry is marked `skipExecute` at creation, exactly like a call
+observed with a `result`. `unstable_isClientToolCall` is read once, when
+the call is first observed live, and never re-read: ownership is fixed
+when the provider emits the call, so a later snapshot cannot revoke it
+and drop the result of an execute already in flight. `streamCall` still
+fires once, as under A.8; only the wrapped `execute` and its result
+chunk are withheld.
+
+Outside production, a provider-owned call whose name resolves to a tool
+with an `execute` logs a `console.warn`. The two together are a
+misconfiguration: the provider answers the call, so the registered
+`execute` would never run and the skip is otherwise silent.
+
+The predicate is also what licenses running a frontend tool before the
+provider's run ends, so an adapter that supplies it keeps the overlap
+between a client tool's work and the run tail (A.10).
+
+### A.10. Args complete while the provider's run is still open
+Closing the args stream hands the call to the client executor, so it may
+only happen once the provider can no longer speak about that call. A
+provider may still answer the call (A.5) or gate it (A.8) one or more
+snapshots after its arguments complete, and a protocol can carry the
+outcome no earlier: AG-UI projects an interrupt only from `RUN_FINISHED`.
+The run ending is the only universal signal, so a call whose ownership is
+unknown closes when the snapshot's `isRunning` goes false.
+
+`ExternalStoreThreadRuntimeCore` feeds the tracker
+`store.isRunning || _hasExecutingTools(store)`, so that condition also covers
+a client tool mid-`execute`. That defers an unknown-ownership sibling only
+while a client-owned call is actually executing, which no shipped adapter
+produces: every entry pending in a snapshot closes in the same
+`_processMessages` pass, an adapter that supplies the predicate classifies
+every call, and an execution parked on `human()` reports `interrupt` rather
+than `executing`, which `_hasExecutingTools` does not count.
+
+That holds even when `execute` opens with `await human()`. The stream
+fires `onExecutionStart` only after `execute` returns, because until then
+it cannot tell a frontend tool from one without an `execute`, so by the
+time the callback runs the body has already parked its resolver and set
+`interrupt`. `_onExecutionStart` still registers the execution for
+`_onExecutionEnd` but leaves the status alone when this execution's own
+request is pending. The check is keyed on the request's execution id,
+not on the status map: a pipeline restart (F.4) clears `_executing` but
+keeps the status map, and a stale `interrupt` must not stop the fresh
+execution from reporting `executing` (#6763).
+
+A call the adapter reports as client-owned (A.9) closes as soon as its
+arguments parse, because the adapter has already said the provider will
+not answer it. Ownership says who answers a call, not whether it is
+gated, so a gate on such a call is still late and A.8 governs it
+(#6677).
+
+### A.11. The turn is discarded while a call waits on the run
+`abort({ discardPending: true })` records every active entry that has
+neither closed its args stream nor holds a result in
+`_discardedToolCallIds`, and marks it `skipExecute`.
+
+The abort signal alone does not cover these. A call waiting on the run to
+settle (A.10) has not reached the executor, so there is nothing to signal,
+and `abort()` installs a fresh `AbortController` before the settled
+snapshot arrives; without the record, cancelling a run would be what
+starts the call it was meant to stop.
+
+`discardPending` is the caller's claim that the turn is over, not that it
+is being interrupted, so only the three callers that end it pass it: a new
+turn starting, a reload, and `cancelRun`. `deleteMessage` does not: its
+`setMessages` fallback aborts while the provider run continues, and
+discarding there would strand that run's remaining calls result-less,
+while its `onDelete` path never aborts at all. `reset()` is unaffected
+either way: it clears `_entries` and the recorded ids before aborting,
+because it opens a new execution boundary.
+
+An id is forgotten once a live snapshot observes the call with a result,
+which bounds the set to the open calls of a discarded turn. That is all
+it does: an id re-emitted inside the same execution boundary keeps its
+existing entry, so A.4 and A.7 govern it rather than this set, and a new
+boundary clears the set outright. The residual is a call that is
+discarded, answered, and then loses its result (A.7) across a pipeline
+restart; it is left to A.7 rather than pinned here, because holding the
+id past the answer would trade a five-step chain for a set that grows for
+the life of the tracker.
+
+The record lives on the tracker rather than the entry because it is the one
+reason to skip that no later snapshot carries: an `approval` is re-read at
+each snapshot and provider ownership is recomputed, while a rebuilt entry
+would otherwise come back clean. That is what lets F.4 drop a waiting entry
+without a special case.
 
 ## B. Tool call disappears from snapshot
 
@@ -193,7 +288,17 @@ The `.pipeTo(...).catch(...)` handler logs and flips `_pipelineDead`.
 The next `setState` call recreates the pipeline once per tracker
 lifetime: existing active entries are *demoted to restored* (so the
 rebuilt pipeline does not re-fire `streamCall` for them) and the
-snapshot is processed against the fresh pipeline. Repeated failures
+snapshot is processed against the fresh pipeline. An active entry that
+neither closed its args stream nor holds a result is dropped instead of
+demoted: a restored entry is promoted only when its signature changes,
+and a call waiting on the run to settle (A.10) already holds its final
+args, so demoting it would strand it unexecuted.
+
+Starting it over re-fires `streamCall`, which the restart path already
+does for any demoted entry whose signature later changes. The rebuilt
+pipeline holds no part for the call, so nothing can reach the executor
+without adding one; a restart is an execution boundary in the same sense
+`reset()` is. Repeated failures
 keep the tracker dead with a visible error to avoid restart loops.
 
 ### F.5. Reset followed by same-id reuse