@assistant-ui/core 0.2.18 → 0.2.20

package/src/model-context/interactable-composer-metadata.ts

@@ -0,0 +1,395 @@
+import { isJSONValueEqual } from "../utils/json/is-json-equal";
+import { isJSONValue, isRecord } from "../utils/json/is-json";
+
+/**
+ * Unstable / Experimental — the interactables API is still evolving and may change in any release.
+ * @deprecated Unstable / Experimental (not actually removed).
+ */
+export type Unstable_InteractableSnapshotEntry = {
+  id: string;
+  name: string;
+  state: unknown;
+  /**
+   * When true, `state` carries only the top-level fields that changed since
+   * the model's last known state; omitted fields are unchanged. The first
+   * snapshot of an instance is always full.
+   */
+  partial?: boolean | undefined;
+};
+
+/**
+ * Minimal message shape needed to read snapshots and `update_*` tool calls out
+ * of history. Structurally compatible with both `ThreadMessage` and the AI
+ * SDK's `UIMessage`.
+ */
+type SnapshotCarrierMessage = {
+  role: string;
+  metadata?: unknown;
+  content?: readonly unknown[] | undefined;
+};
+
+/**
+ * Reads the interactable snapshots stamped on a message's
+ * `metadata.custom.interactables`, or `undefined` if none. This is the read
+ * half of the snapshot channel — integrations use it to surface interactable
+ * state to the model (see `unstable_injectInteractableContext` in
+ * `@assistant-ui/react-ai-sdk` for the AI SDK implementation).
+ *
+ * @deprecated Unstable / Experimental (not actually removed).
+ */
+export function unstable_getInteractableSnapshots(message: {
+  metadata?: unknown;
+}): Unstable_InteractableSnapshotEntry[] | undefined {
+  const metadata = message.metadata;
+  if (!metadata || typeof metadata !== "object") return undefined;
+  const custom = (metadata as Record<string, unknown>).custom;
+  if (!custom || typeof custom !== "object") return undefined;
+  const items = (custom as Record<string, unknown>).interactables;
+  return Array.isArray(items)
+    ? (items as Unstable_InteractableSnapshotEntry[])
+    : undefined;
+}
+
+/**
+ * Canonical model-facing wording for one snapshot entry.
+ *
+ * @deprecated Unstable / Experimental (not actually removed).
+ */
+export function unstable_formatInteractableSnapshot(
+  entry: Unstable_InteractableSnapshotEntry,
+): string {
+  if (entry.partial) {
+    return `[State of "${entry.name}" (id: ${JSON.stringify(entry.id)}) changed — updated fields: ${JSON.stringify(entry.state)}; fields not listed are unchanged]`;
+  }
+  return `[Current state of "${entry.name}" (id: ${JSON.stringify(entry.id)}): ${JSON.stringify(entry.state)}]`;
+}
+
+/** The model-facing tool name for an interactable `name`. One tool per name. */
+export function interactableToolName(name: string): string {
+  return `update_${name.replace(/[^a-zA-Z0-9_-]/g, "_")}`;
+}
+
+const getArrayItemId = (item: unknown): string | number | undefined => {
+  if (!isRecord(item)) return undefined;
+  const id = item.id;
+  return typeof id === "string" || typeof id === "number" ? id : undefined;
+};
+
+function applyArrayUpdate(
+  prev: unknown[],
+  update: Record<string, unknown>,
+  mintId?: () => string | undefined,
+) {
+  let next = Array.isArray(update.set) ? [...update.set] : [...prev];
+
+  if (update.clear === true) next = [];
+
+  if (Array.isArray(update.remove) && update.remove.length > 0) {
+    const ids = new Set(update.remove);
+    next = next.filter((item) => {
+      const id = getArrayItemId(item);
+      return id !== undefined ? !ids.has(id) : !ids.has(item);
+    });
+  }
+
+  const patches = update.update;
+  if (Array.isArray(patches) && patches.length > 0) {
+    next = next.map((item) => {
+      const id = getArrayItemId(item);
+      if (id === undefined || !isRecord(item)) return item;
+      const patch = patches.find(
+        (candidate) => isRecord(candidate) && candidate.id === id,
+      );
+      return patch ? { ...item, ...patch } : item;
+    });
+  }
+
+  if (Array.isArray(update.add) && update.add.length > 0) {
+    const added = mintId
+      ? update.add.map((item) => {
+          if (!isRecord(item) || item.id !== undefined) return item;
+          const id = mintId();
+          return id === undefined ? item : { ...item, id };
+        })
+      : update.add;
+    next = [...next, ...added];
+  }
+
+  return next;
+}
+
+/**
+ * The merge `update_*` tools apply: top-level keys replace, rest preserved.
+ * Array fields also accept operation objects (`add`, `update`, `remove`,
+ * `clear`, `set`) so collection edits do not need a companion manage_* tool.
+ */
+export function shallowMergeInteractableState(
+  prev: unknown,
+  partial: unknown,
+  options?:
+    | {
+        arrayBaseline?: unknown;
+        /**
+         * Supplies ids for added items in id-keyed array fields. The live
+         * execute path mints fresh ids; history folds replay ids previously
+         * returned by execute.
+         */
+        idFactory?: (field: string) => string | undefined;
+        idKeyedFields?: ReadonlySet<string>;
+      }
+    | undefined,
+): unknown {
+  if (!isRecord(prev) || !isRecord(partial)) return partial;
+  const baseline = isRecord(options?.arrayBaseline)
+    ? options.arrayBaseline
+    : prev;
+  const next = { ...prev };
+  for (const [key, value] of Object.entries(partial)) {
+    const baseValue = baseline[key];
+    if (Array.isArray(baseValue) && isRecord(value)) {
+      const mintId =
+        options?.idFactory &&
+        (options.idKeyedFields === undefined || options.idKeyedFields.has(key))
+          ? () => options.idFactory?.(key)
+          : undefined;
+      next[key] = applyArrayUpdate(baseValue, value, mintId);
+    } else {
+      next[key] = value;
+    }
+  }
+  return next;
+}
+
+/**
+ * The top-level fields of `next` that differ from `known`, for stamping a
+ * partial snapshot. Returns `undefined` when a partial stamp has no benefit:
+ * the change is not expressible as a shallow merge (non-object states, or a
+ * top-level key was removed), or every field changed anyway — the caller
+ * falls back to a full snapshot.
+ */
+function shallowDiffInteractableState(
+  known: unknown,
+  next: unknown,
+): Record<string, unknown> | undefined {
+  if (!isRecord(known) || !isRecord(next)) return undefined;
+  for (const key of Object.keys(known)) {
+    if (!(key in next)) return undefined;
+  }
+  const diff: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(next)) {
+    if (!(key in known) || !isJSONValueEqual(known[key], value)) {
+      diff[key] = value;
+    }
+  }
+  const changed = Object.keys(diff).length;
+  if (changed === 0 || changed === Object.keys(next).length) return undefined;
+  return diff;
+}
+
+type ToolCallLikePart = {
+  type?: string;
+  toolCallId?: string;
+  toolName?: string;
+  args?: unknown;
+  result?: unknown;
+};
+
+const asToolCallPart = (part: unknown): ToolCallLikePart | undefined => {
+  if (!part || typeof part !== "object") return undefined;
+  const p = part as ToolCallLikePart;
+  return p.type === "tool-call" ? p : undefined;
+};
+
+/** Whether an accepted `update_*` call addressed instance `id`. */
+const updateCallTargets = (p: ToolCallLikePart, id: string): boolean => {
+  if (!p.args || typeof p.args !== "object") return false;
+  const result = isRecord(p.result) ? p.result : undefined;
+  if (result?.success === false) return false;
+  if (typeof result?.id === "string") return result.id === id;
+  const argsId = (p.args as Record<string, unknown>).id;
+  return argsId === id || argsId === undefined;
+};
+
+const createAddedItemIdFactory = (result: unknown) => {
+  const value = isRecord(result) ? result.addedItemIds : undefined;
+  if (!isRecord(value)) return undefined;
+
+  const idsByField = new Map<string, string[]>();
+  for (const [field, ids] of Object.entries(value)) {
+    if (!Array.isArray(ids)) continue;
+    const stringIds = ids.filter(
+      (item): item is string => typeof item === "string",
+    );
+    if (stringIds.length > 0) idsByField.set(field, stringIds);
+  }
+  if (idsByField.size === 0) return undefined;
+
+  return (field: string) => idsByField.get(field)?.shift();
+};
+
+/**
+ * Unstable / Experimental — the interactables API is still evolving and may change in any release.
+ * @deprecated Unstable / Experimental (not actually removed).
+ */
+export type Unstable_InteractableVersion = {
+  /** The full state as of this version. */
+  state: unknown;
+  origin: "create" | "update" | "user-edit";
+  /** For create/update versions, the tool call that produced this version. */
+  toolCallId?: string | undefined;
+};
+
+// Without this, every mounted anchor re-folds the whole thread on each streaming
+// token, since the repository hands out a new messages array per token.
+const versionsCache = new WeakMap<
+  readonly SnapshotCarrierMessage[],
+  Map<string, Map<string, Unstable_InteractableVersion[]>>
+>();
+
+/**
+ * Every version of interactable `id` recorded in the thread, oldest first,
+ * folded chronologically:
+ *
+ * - the tool call whose `toolCallId` equals `id` seeds the baseline with its
+ *   args (`origin: "create"`) — the `id: toolCallId` convention for
+ *   tool-created interactables,
+ * - a snapshot stamped on a user message is a `"user-edit"` version (a full
+ *   snapshot replaces the state; a partial one shallow-merges),
+ * - each accepted `update_*` call shallow-merges an `"update"` version.
+ *
+ * The last entry is the state the model knows. Partial snapshots and update
+ * calls with no baseline to merge into are skipped.
+ *
+ * @deprecated Unstable / Experimental (not actually removed).
+ */
+export function unstable_getInteractableVersions(
+  messages: readonly SnapshotCarrierMessage[],
+  id: string,
+  name: string,
+): Unstable_InteractableVersion[] {
+  let byName = versionsCache.get(messages);
+  if (!byName) {
+    byName = new Map();
+    versionsCache.set(messages, byName);
+  }
+  let byId = byName.get(name);
+  if (!byId) {
+    byId = new Map();
+    byName.set(name, byId);
+  }
+  const cached = byId.get(id);
+  if (cached) return cached;
+
+  const toolName = interactableToolName(name);
+  const versions: Unstable_InteractableVersion[] = [];
+  const current = () => versions[versions.length - 1];
+
+  for (const msg of messages) {
+    if (msg.role === "user") {
+      const entry = unstable_getInteractableSnapshots(msg)?.find(
+        (it) => it.id === id,
+      );
+      if (!entry) continue;
+      if (entry.partial) {
+        const prev = current();
+        if (prev) {
+          versions.push({
+            state: shallowMergeInteractableState(prev.state, entry.state),
+            origin: "user-edit",
+          });
+        }
+      } else {
+        versions.push({ state: entry.state, origin: "user-edit" });
+      }
+      continue;
+    }
+
+    if (msg.role !== "assistant") continue;
+    for (const part of msg.content ?? []) {
+      const p = asToolCallPart(part);
+      if (!p) continue;
+      if (p.toolCallId === id && p.toolName === name) {
+        if (p.args && typeof p.args === "object") {
+          versions.push({ state: p.args, origin: "create", toolCallId: id });
+        }
+      } else if (p.toolName === toolName && updateCallTargets(p, id)) {
+        const prev = current();
+        if (prev) {
+          const { id: _id, ...partial } = p.args as Record<string, unknown>;
+          const idFactory = createAddedItemIdFactory(p.result);
+          versions.push({
+            state: idFactory
+              ? shallowMergeInteractableState(prev.state, partial, {
+                  idFactory,
+                })
+              : shallowMergeInteractableState(prev.state, partial),
+            origin: "update",
+            toolCallId: p.toolCallId,
+          });
+        }
+      }
+    }
+  }
+  byId.set(id, versions);
+  return versions;
+}
+
+/**
+ * The state the model knows for interactable `id` — its latest recorded
+ * version, or `undefined` when no baseline exists yet.
+ */
+export function findModelKnownState(
+  messages: readonly SnapshotCarrierMessage[],
+  id: string,
+  name: string,
+): { state: unknown } | undefined {
+  const versions = unstable_getInteractableVersions(messages, id, name);
+  const last = versions[versions.length - 1];
+  return last ? { state: last.state } : undefined;
+}
+
+/**
+ * Snapshot gate. Stamps an interactable only when the model doesn't already
+ * know its state (no baseline yet, or the live state differs from the folded
+ * thread record). A change that fits a shallow merge is stamped as a partial
+ * snapshot carrying just the changed fields; otherwise the full state is
+ * stamped. Other metadata keys pass through untouched.
+ */
+export function gateInteractableComposerMetadata(
+  meta: Record<string, unknown> | undefined,
+  messages: readonly SnapshotCarrierMessage[],
+): Record<string, unknown> | undefined {
+  if (!meta) return undefined;
+  const { interactables, ...rest } = meta as {
+    interactables?: Unstable_InteractableSnapshotEntry[];
+  } & Record<string, unknown>;
+
+  const gated: Record<string, unknown> = { ...rest };
+  if (Array.isArray(interactables)) {
+    const pending: Unstable_InteractableSnapshotEntry[] = [];
+    for (const it of interactables) {
+      if (process.env.NODE_ENV !== "production" && !isJSONValue(it.state)) {
+        console.warn(
+          `[Interactables] state for "${it.name}" (${it.id}) is not JSON-equatable ` +
+            `(an undefined, NaN, Infinity, function, or symbol value?). It will be ` +
+            `re-snapshotted on every send, recreating per-message growth. Use plain ` +
+            `JSON values.`,
+        );
+      }
+      const known = findModelKnownState(messages, it.id, it.name);
+      if (!known) {
+        pending.push({ id: it.id, name: it.name, state: it.state });
+        continue;
+      }
+      if (isJSONValueEqual(it.state, known.state)) continue;
+      const diff = shallowDiffInteractableState(known.state, it.state);
+      pending.push(
+        diff
+          ? { id: it.id, name: it.name, state: diff, partial: true }
+          : { id: it.id, name: it.name, state: it.state },
+      );
+    }
+    if (pending.length) gated.interactables = pending;
+  }
+  return Object.keys(gated).length ? gated : undefined;
+}

package/src/model-context/registry.ts

@@ -61,6 +61,11 @@ export class ModelContextRegistry implements ModelContextProvider {
       context.config = providerContexts.config;
     }
 
+    if (providerContexts.unstable_composerMetadata) {
+      context.unstable_composerMetadata =
+        providerContexts.unstable_composerMetadata;
+    }
+
     return context;
   }
 

package/src/model-context/types.ts

@@ -24,6 +24,12 @@ export type ModelContext = {
   tools?: Record<string, Tool<any, any>> | undefined;
   callSettings?: LanguageModelV1CallSettings | undefined;
   config?: LanguageModelConfig | undefined;
+  /**
+   * Persisted message metadata pulled at send time and merged into the outgoing
+   * user message's `metadata.custom` (not forwarded to the model directly).
+   * Ignored by the transport, which only reads system/tools/callSettings/config.
+   */
+  unstable_composerMetadata?: Record<string, unknown> | undefined;
 };
 
 export type ModelContextProvider = {
@@ -107,6 +113,12 @@ export const mergeModelContexts = (
         ...config.callSettings,
       };
     }
+    if (config.unstable_composerMetadata) {
+      acc.unstable_composerMetadata = {
+        ...acc.unstable_composerMetadata,
+        ...config.unstable_composerMetadata,
+      };
+    }
     return acc;
   }, {} as ModelContext);
 };