@assistant-ui/core 0.3.15 → 0.3.17

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

@@ -2,6 +2,7 @@ import type {
   RemoteThreadInitializeResponse,
   RemoteThreadMetadata,
 } from "./types";
+import { generateId } from "../../utils/id";
 
 export type RemoteThreadData =
   | {
@@ -11,6 +12,7 @@ export type RemoteThreadData =
       readonly status: "new";
       readonly title: undefined;
       readonly custom: undefined;
+      readonly localOrigin?: true;
     }
   | {
       readonly id: string;
@@ -20,6 +22,7 @@ export type RemoteThreadData =
       readonly status: "regular" | "archived";
       readonly title?: string | undefined;
       readonly custom: undefined;
+      readonly localOrigin?: true;
     }
   | {
       readonly id: string;
@@ -30,6 +33,7 @@ export type RemoteThreadData =
       readonly title?: string | undefined;
       readonly lastMessageAt?: Date | undefined;
       readonly custom?: Record<string, unknown> | undefined;
+      readonly localOrigin?: true;
     };
 
 export type THREAD_MAPPING_ID = string & { __brand: "THREAD_MAPPING_ID" };
@@ -38,29 +42,34 @@ export function createThreadMappingId(id: string): THREAD_MAPPING_ID {
   return id as THREAD_MAPPING_ID;
 }
 
+export const LOCAL_THREAD_ID_PREFIX = "__LOCALID_";
+
 export const normalizeCursor = (c: string | undefined): string | undefined =>
   c || undefined;
 
-type ClassifyAccumulator = {
+export type ClassifyAccumulator = {
   threadIds: string[];
   archivedThreadIds: string[];
   threadIdMap: Record<string, THREAD_MAPPING_ID>;
   threadData: Record<THREAD_MAPPING_ID, RemoteThreadData>;
 };
 
+// A slot's `id` is fixed when it is minted: the hook instance manager keys live
+// thread runtimes by it, so renaming a slot would detach the runtime the user is
+// chatting in. A listed thread whose `remoteId` already maps to a slot therefore
+// refreshes that slot instead of minting a second one, and a slot minted by a
+// list() that raced ahead of the remote id collapses when `initialize()` settles.
+// `threadIds`/`archivedThreadIds` carry slot ids, never remote ids.
 export const classifyThreads = (
   threads: readonly RemoteThreadMetadata[],
   acc: ClassifyAccumulator,
 ): ClassifyAccumulator => {
-  for (const thread of threads) {
-    if (acc.threadIdMap[thread.remoteId] !== undefined) continue;
+  const listed = new Set([...acc.threadIds, ...acc.archivedThreadIds]);
 
+  for (const thread of threads) {
     switch (thread.status) {
       case "regular":
-        acc.threadIds.push(thread.remoteId);
-        break;
       case "archived":
-        acc.archivedThreadIds.push(thread.remoteId);
         break;
       default: {
         const _exhaustiveCheck: never = thread.status;
@@ -68,20 +77,52 @@ export const classifyThreads = (
       }
     }
 
-    const mappingId = createThreadMappingId(thread.remoteId);
+    const existingMappingId = acc.threadIdMap[thread.remoteId];
+    const existing =
+      existingMappingId !== undefined
+        ? acc.threadData[existingMappingId]
+        : undefined;
+    const id = existing?.id ?? thread.remoteId;
+    const mappingId = existingMappingId ?? createThreadMappingId(id);
+    const existingTask =
+      existing !== undefined && existing.status !== "new"
+        ? existing.initializeTask
+        : undefined;
+
+    if (!listed.has(id)) {
+      listed.add(id);
+      if (thread.status === "regular") {
+        acc.threadIds.push(id);
+      } else {
+        acc.archivedThreadIds.push(id);
+      }
+    } else if (existing !== undefined && existing.status !== thread.status) {
+      if (thread.status === "regular") {
+        acc.archivedThreadIds = acc.archivedThreadIds.filter((t) => t !== id);
+        acc.threadIds.push(id);
+      } else {
+        acc.threadIds = acc.threadIds.filter((t) => t !== id);
+        acc.archivedThreadIds.push(id);
+      }
+    }
+
+    acc.threadIdMap[id] = mappingId;
     acc.threadIdMap[thread.remoteId] = mappingId;
     acc.threadData[mappingId] = {
-      id: thread.remoteId,
+      ...(existing?.localOrigin === true ? { localOrigin: true as const } : {}),
+      id,
       remoteId: thread.remoteId,
       externalId: thread.externalId,
       status: thread.status,
       title: thread.title,
       lastMessageAt: thread.lastMessageAt,
       custom: thread.custom,
-      initializeTask: Promise.resolve({
-        remoteId: thread.remoteId,
-        externalId: thread.externalId,
-      }),
+      initializeTask:
+        existingTask ??
+        Promise.resolve({
+          remoteId: thread.remoteId,
+          externalId: thread.externalId,
+        }),
     };
   }
   return acc;
@@ -98,6 +139,123 @@ export type RemoteThreadState = {
   readonly threadData: Readonly<Record<THREAD_MAPPING_ID, RemoteThreadData>>;
 };
 
+export const createEmptyRemoteThreadState = (): RemoteThreadState => ({
+  isLoading: true,
+  isLoadingMore: false,
+  cursor: undefined,
+  newThreadId: undefined,
+  threadIds: [],
+  archivedThreadIds: [],
+  threadIdMap: {},
+  threadData: {},
+});
+
+export const seedNewThread = (
+  state: RemoteThreadState,
+): { id: string; state: RemoteThreadState } => {
+  let id: string;
+  do {
+    id = `${LOCAL_THREAD_ID_PREFIX}${generateId()}`;
+  } while (state.threadIdMap[id]);
+  const mappingId = createThreadMappingId(id);
+  return {
+    id,
+    state: {
+      ...state,
+      newThreadId: id,
+      threadIdMap: {
+        ...state.threadIdMap,
+        [id]: mappingId,
+      },
+      threadData: {
+        ...state.threadData,
+        [mappingId]: {
+          status: "new",
+          id,
+          remoteId: undefined,
+          externalId: undefined,
+          title: undefined,
+          custom: undefined,
+          localOrigin: true,
+        } satisfies RemoteThreadData,
+      },
+    },
+  };
+};
+
+// A list() response predating a mid-flight local transition (a thread
+// initialized while the request was running) omits that thread, and the
+// completed-optimistic replay cannot re-add it because the merged threadData
+// already carries the final status. Threads whose status moved from new (or
+// nonexistent) at request time to regular/archived are re-inserted at the
+// top, in the order the pre-response lists carried them: updateStatusReducer
+// prepends as transitions happen, so the pre-response lists hold newest
+// first, which threadData insertion order need not match. Threads the server already knew stay governed by the response, so
+// a server-side deletion is not resurrected — and a thread unknown to the
+// snapshot is only rescued when it carries the localOrigin marker stamped at
+// draft creation, so a deep-linked thread the fetch path deliberately
+// appended at the tail is not hoisted, whatever its remote id looks like.
+export const preserveMidLoadTransitions = (
+  state: RemoteThreadState,
+  priorOrder: Pick<RemoteThreadState, "threadIds" | "archivedThreadIds">,
+  statusAtRequest: ReadonlyMap<string, RemoteThreadData["status"]>,
+): RemoteThreadState => {
+  const regular = new Set(state.threadIds);
+  const archived = new Set(state.archivedThreadIds);
+  const rescuedRegular: RemoteThreadData[] = [];
+  const rescuedArchived: RemoteThreadData[] = [];
+
+  const contains = (ids: ReadonlySet<string>, data: RemoteThreadData) =>
+    ids.has(data.id) || (data.remoteId !== undefined && ids.has(data.remoteId));
+
+  for (const data of Object.values(state.threadData)) {
+    const before = statusAtRequest.get(data.id);
+    if (before !== undefined && before !== "new") continue;
+    if (before === undefined && data.localOrigin !== true) continue;
+
+    if (data.status === "regular" && !contains(regular, data)) {
+      rescuedRegular.push(data);
+      regular.add(data.id);
+    } else if (data.status === "archived" && !contains(archived, data)) {
+      rescuedArchived.push(data);
+      archived.add(data.id);
+    }
+  }
+
+  if (rescuedRegular.length === 0 && rescuedArchived.length === 0) return state;
+
+  const position = (ids: readonly string[], data: RemoteThreadData) => {
+    const byId = ids.indexOf(data.id);
+    if (byId !== -1) return byId;
+    const byRemoteId =
+      data.remoteId !== undefined ? ids.indexOf(data.remoteId) : -1;
+    return byRemoteId !== -1 ? byRemoteId : Number.MAX_SAFE_INTEGER;
+  };
+  rescuedRegular.sort(
+    (a, b) =>
+      position(priorOrder.threadIds, a) - position(priorOrder.threadIds, b),
+  );
+  rescuedArchived.sort(
+    (a, b) =>
+      position(priorOrder.archivedThreadIds, a) -
+      position(priorOrder.archivedThreadIds, b),
+  );
+
+  return {
+    ...state,
+    threadIds: [...rescuedRegular.map((d) => d.id), ...state.threadIds],
+    archivedThreadIds: [
+      ...rescuedArchived.map((d) => d.id),
+      ...state.archivedThreadIds,
+    ],
+  };
+};
+
+export const statusSnapshot = (
+  state: RemoteThreadState,
+): ReadonlyMap<string, RemoteThreadData["status"]> =>
+  new Map(Object.values(state.threadData).map((d) => [d.id, d.status]));
+
 export const getThreadData = (
   state: RemoteThreadState,
   threadIdOrRemoteId: string,
@@ -115,7 +273,7 @@ export const updateStatusReducer = (
   const data = getThreadData(state, threadIdOrRemoteId);
   if (!data) return state;
 
-  const { id, remoteId, status: lastStatus } = data;
+  const { id, status: lastStatus } = data;
   if (lastStatus === newStatus) return state;
 
   const newState = { ...state };
@@ -150,16 +308,20 @@ export const updateStatusReducer = (
       newState.archivedThreadIds = [id, ...newState.archivedThreadIds];
       break;
 
-    case "deleted":
+    case "deleted": {
+      const mappingId = state.threadIdMap[threadIdOrRemoteId]!;
       newState.threadData = Object.fromEntries(
-        Object.entries(newState.threadData).filter(([key]) => key !== id),
+        Object.entries(newState.threadData).filter(
+          ([key]) => key !== mappingId,
+        ),
       );
       newState.threadIdMap = Object.fromEntries(
         Object.entries(newState.threadIdMap).filter(
-          ([key]) => key !== id && key !== remoteId,
+          ([, value]) => value !== mappingId,
         ),
       );
       break;
+    }
 
     default: {
       const _exhaustiveCheck: never = newStatus;

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

@@ -0,0 +1,3 @@
+export const isTitleSourceMessage = (message: {
+  status?: { type: string } | undefined;
+}) => message.status?.type !== "running";

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

@@ -78,11 +78,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
@@ -78,6 +79,117 @@ sees only the first result.
 ### A.7. Previously-resolved tool loses its `result` (back to undefined)
 Silently ignored. The entry stays in the resolved phase internally.
 
+### A.8. Tool call carries a provider `approval`
+The entry is marked `skipExecute`, exactly like a call observed with
+a `result`, whether the gate is present when the call is first observed
+or lands on an already-active entry. A gate belongs to the provider:
+`approved === true` means the provider is producing the result, `false`
+means it records the denial, so the frontend `execute` never fires for
+that `toolCallId` once the gate is present. `streamCall` still fires
+once and the backend result flows through A.5 when it lands.
+
+If the gate lands after the args stream has closed but before an
+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.
+
+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
 
 ### B.1. Tool call removed entirely (rollback, branch switch)
@@ -176,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