@assistant-ui/core 0.2.20 → 0.2.21

package/src/types/message.ts

@@ -7,21 +7,25 @@ import type { CompleteAttachment } from "./attachment";
 
 export type { ToolCallTiming, ToolModelContentPart };
 
+export type PartProviderMetadata = {
+  readonly [providerName: string]: ReadonlyJSONObject;
+};
+
 export type TextMessagePart = {
   readonly type: "text";
   readonly text: string;
+  readonly providerMetadata?: PartProviderMetadata;
   readonly parentId?: string;
 };
 
 export type ReasoningMessagePart = {
   readonly type: "reasoning";
   readonly text: string;
+  readonly providerMetadata?: PartProviderMetadata;
   readonly parentId?: string;
 };
 
-export type SourceProviderMetadata = {
-  readonly [providerName: string]: ReadonlyJSONObject;
-};
+export type SourceProviderMetadata = PartProviderMetadata;
 
 export type SourceMessagePart =
   | {
@@ -124,6 +128,8 @@ export type McpAppMetadata = {
   readonly resourceUri: string;
   readonly mimeType?: string;
   readonly visibility?: readonly ("model" | "app")[];
+  /** Routable server identity emitted by the agent stack when multiple MCP servers back one agent; for @ag-ui/mcp-apps-middleware this is the configured serverId, falling back to its serverHash. */
+  readonly serverId?: string;
 };
 
 export const MCP_APP_URI_SCHEME = "ui://";
@@ -197,6 +203,8 @@ export type ToolCallMessagePart<
   readonly timing?: ToolCallTiming;
   /** MCP app metadata associated with this tool call, when present. */
   readonly mcp?: ToolCallMessagePartMcpMetadata;
+  /** Provider metadata associated with this tool call, when present. */
+  readonly providerMetadata?: PartProviderMetadata;
   /** Content returned to the model for this tool result. */
   readonly modelContent?: readonly ToolModelContentPart[] | undefined;
   /** Human-input request that must be resolved before the run can continue. */

package/src/utils/json/is-json-equal.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from "vitest";
+import { isJSONValueEqual } from "./is-json-equal";
+
+const wrapInArrays = (value: unknown, depth: number): unknown => {
+  let result = value;
+  for (let i = 0; i < depth; i++) result = [result];
+  return result;
+};
+
+describe("isJSONValueEqual", () => {
+  it("compares primitives", () => {
+    expect(isJSONValueEqual(1, 1)).toBe(true);
+    expect(isJSONValueEqual("a", "a")).toBe(true);
+    expect(isJSONValueEqual(null, null)).toBe(true);
+    expect(isJSONValueEqual(1, 2)).toBe(false);
+    expect(isJSONValueEqual(0, "0")).toBe(false);
+    expect(isJSONValueEqual(true, 1)).toBe(false);
+  });
+
+  it("rejects non-JSON inputs on either side", () => {
+    expect(isJSONValueEqual(NaN, NaN)).toBe(false);
+    expect(isJSONValueEqual(undefined, undefined)).toBe(false);
+    expect(
+      isJSONValueEqual(
+        () => {},
+        () => {},
+      ),
+    ).toBe(false);
+    expect(isJSONValueEqual({ a: 1 }, { a: NaN })).toBe(false);
+  });
+
+  it("compares objects independent of key insertion order", () => {
+    expect(isJSONValueEqual({ a: 1, b: 2 }, { b: 2, a: 1 })).toBe(true);
+  });
+
+  it("rejects differing key sets in both directions", () => {
+    expect(isJSONValueEqual({ a: 1 }, { a: 1, b: 2 })).toBe(false);
+    expect(isJSONValueEqual({ a: 1, b: 2 }, { a: 1 })).toBe(false);
+    expect(isJSONValueEqual({ a: 1 }, { b: 1 })).toBe(false);
+  });
+
+  it("compares arrays order-sensitively", () => {
+    expect(isJSONValueEqual([1, 2], [1, 2])).toBe(true);
+    expect(isJSONValueEqual([1, 2], [2, 1])).toBe(false);
+    expect(isJSONValueEqual([1, 2], [1, 2, 3])).toBe(false);
+  });
+
+  it("compares nested mixed structures", () => {
+    const make = () => ({ a: [1, { b: "c", d: [null, true] }], e: {} });
+    expect(isJSONValueEqual(make(), make())).toBe(true);
+    expect(
+      isJSONValueEqual(make(), {
+        a: [1, { b: "c", d: [null, false] }],
+        e: {},
+      }),
+    ).toBe(false);
+  });
+
+  it("rejects array vs object and null vs empty object", () => {
+    expect(isJSONValueEqual([], {})).toBe(false);
+    expect(isJSONValueEqual({}, [])).toBe(false);
+    expect(isJSONValueEqual(null, {})).toBe(false);
+  });
+
+  it("compares reference-identical structures within the depth limit", () => {
+    const value = wrapInArrays({ a: 1 }, 99);
+    expect(isJSONValueEqual(value, value)).toBe(true);
+  });
+
+  it("rejects inputs nested beyond depth 100 regardless of identity", () => {
+    const value = wrapInArrays(1, 101);
+    expect(isJSONValueEqual(value, value)).toBe(false);
+  });
+
+  it("compares structurally equal distinct structures at depth 100", () => {
+    expect(isJSONValueEqual(wrapInArrays(1, 100), wrapInArrays(1, 100))).toBe(
+      true,
+    );
+  });
+
+  it("treats distinct empty-record instances as equal", () => {
+    expect(isJSONValueEqual(new Date(0), new Date(0))).toBe(true);
+  });
+});

package/src/utils/json/is-json.test.ts

@@ -0,0 +1,123 @@
+import { describe, expect, it } from "vitest";
+import { isJSONArray, isJSONObject, isJSONValue, isRecord } from "./is-json";
+
+const wrapInArrays = (value: unknown, depth: number): unknown => {
+  let result = value;
+  for (let i = 0; i < depth; i++) result = [result];
+  return result;
+};
+
+describe("isRecord", () => {
+  it("accepts plain objects", () => {
+    expect(isRecord({})).toBe(true);
+    expect(isRecord({ a: 1 })).toBe(true);
+  });
+
+  it("accepts class instances", () => {
+    class Point {
+      x = 1;
+    }
+    expect(isRecord(new Point())).toBe(true);
+  });
+
+  it("rejects null, arrays, and primitives", () => {
+    expect(isRecord(null)).toBe(false);
+    expect(isRecord(undefined)).toBe(false);
+    expect(isRecord([])).toBe(false);
+    expect(isRecord("x")).toBe(false);
+    expect(isRecord(42)).toBe(false);
+    expect(isRecord(true)).toBe(false);
+  });
+});
+
+describe("isJSONValue", () => {
+  it("accepts JSON primitives", () => {
+    expect(isJSONValue(null)).toBe(true);
+    expect(isJSONValue("text")).toBe(true);
+    expect(isJSONValue(true)).toBe(true);
+    expect(isJSONValue(false)).toBe(true);
+    expect(isJSONValue(0)).toBe(true);
+    expect(isJSONValue(-1.5)).toBe(true);
+  });
+
+  it("rejects non-finite numbers", () => {
+    expect(isJSONValue(NaN)).toBe(false);
+    expect(isJSONValue(Infinity)).toBe(false);
+    expect(isJSONValue(-Infinity)).toBe(false);
+  });
+
+  it("rejects non-JSON primitives", () => {
+    expect(isJSONValue(undefined)).toBe(false);
+    expect(isJSONValue(() => {})).toBe(false);
+    expect(isJSONValue(Symbol("s"))).toBe(false);
+    expect(isJSONValue(10n)).toBe(false);
+  });
+
+  it("recurses through nested arrays and objects", () => {
+    expect(isJSONValue({ a: [1, { b: "c", d: [null, true] }] })).toBe(true);
+  });
+
+  it("rejects a non-JSON leaf nested deep inside", () => {
+    expect(isJSONValue({ a: [{ b: undefined }] })).toBe(false);
+    expect(isJSONValue({ a: [{ b: () => {} }] })).toBe(false);
+  });
+
+  it("accepts nesting up to depth 100 and rejects depth 101", () => {
+    expect(isJSONValue(wrapInArrays(1, 100))).toBe(true);
+    expect(isJSONValue(wrapInArrays(1, 101))).toBe(false);
+  });
+
+  it("accepts non-plain objects without own enumerable string keys", () => {
+    expect(isJSONValue(new Date())).toBe(true);
+    expect(isJSONValue(new Map([["a", 1]]))).toBe(true);
+    expect(isJSONValue(new Set([1]))).toBe(true);
+  });
+
+  it("accepts objects whose only keys are symbols", () => {
+    expect(isJSONValue({ [Symbol("s")]: () => {} })).toBe(true);
+  });
+});
+
+describe("isJSONArray", () => {
+  it("accepts arrays of JSON values", () => {
+    expect(isJSONArray([])).toBe(true);
+    expect(isJSONArray([1, "a", null, { b: true }])).toBe(true);
+  });
+
+  it("rejects arrays containing non-JSON values", () => {
+    expect(isJSONArray([NaN])).toBe(false);
+    expect(isJSONArray([() => {}])).toBe(false);
+    expect(isJSONArray([1, undefined])).toBe(false);
+  });
+
+  it("rejects non-arrays", () => {
+    expect(isJSONArray({})).toBe(false);
+    expect(isJSONArray("x")).toBe(false);
+    expect(isJSONArray(null)).toBe(false);
+  });
+
+  it("does not consume the element index as recursion depth", () => {
+    expect(isJSONArray(Array.from({ length: 150 }, () => 0))).toBe(true);
+    expect(
+      isJSONArray(Array.from({ length: 150 }, () => wrapInArrays(1, 50))),
+    ).toBe(true);
+  });
+});
+
+describe("isJSONObject", () => {
+  it("accepts objects of JSON values", () => {
+    expect(isJSONObject({})).toBe(true);
+    expect(isJSONObject({ a: 1, b: [true, null] })).toBe(true);
+  });
+
+  it("rejects arrays and null", () => {
+    expect(isJSONObject([])).toBe(false);
+    expect(isJSONObject(null)).toBe(false);
+  });
+
+  it("rejects objects containing non-JSON values", () => {
+    expect(isJSONObject({ a: NaN })).toBe(false);
+    expect(isJSONObject({ a: () => {} })).toBe(false);
+    expect(isJSONObject({ a: undefined })).toBe(false);
+  });
+});

package/src/utils/json/is-json.ts

@@ -45,7 +45,7 @@ export function isJSONValue(
 }
 
 export function isJSONArray(value: unknown): value is ReadonlyJSONArray {
-  return Array.isArray(value) && value.every(isJSONValue);
+  return Array.isArray(value) && value.every((item) => isJSONValue(item));
 }
 
 export function isJSONObject(value: unknown): value is ReadonlyJSONObject {

package/src/utils/json/stable-stringify-tool-args.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from "vitest";
+import {
+  stableStringifyToolArgs,
+  trackToolArgsKeyOrder,
+} from "./stable-stringify-tool-args";
+
+describe("stableStringifyToolArgs", () => {
+  it("stringifies without a cache", () => {
+    expect(stableStringifyToolArgs(undefined, "key", { a: 1, b: 2 })).toBe(
+      JSON.stringify({ a: 1, b: 2 }),
+    );
+  });
+
+  it("keeps first-seen key order across reordered updates", () => {
+    const cache = new Map<string, Map<string, string[]>>();
+    stableStringifyToolArgs(cache, "key", { a: 1, b: 2 });
+    expect(stableStringifyToolArgs(cache, "key", { b: 3, a: 4 })).toBe(
+      JSON.stringify({ a: 4, b: 3 }),
+    );
+  });
+
+  it("appends new keys after previously seen keys", () => {
+    const cache = new Map<string, Map<string, string[]>>();
+    stableStringifyToolArgs(cache, "key", { b: 1 });
+    expect(stableStringifyToolArgs(cache, "key", { c: 2, a: 3, b: 4 })).toBe(
+      JSON.stringify({ b: 4, c: 2, a: 3 }),
+    );
+  });
+
+  it("drops keys absent from the current value", () => {
+    const cache = new Map<string, Map<string, string[]>>();
+    stableStringifyToolArgs(cache, "key", { a: 1, b: 2 });
+    expect(stableStringifyToolArgs(cache, "key", { b: 3 })).toBe(
+      JSON.stringify({ b: 3 }),
+    );
+    expect(stableStringifyToolArgs(cache, "key", { a: 5, b: 6 })).toBe(
+      JSON.stringify({ b: 6, a: 5 }),
+    );
+  });
+
+  it("stabilizes nested objects and array elements independently", () => {
+    const cache = new Map<string, Map<string, string[]>>();
+    stableStringifyToolArgs(cache, "key", {
+      list: [{ x: 1, y: 2 }],
+      nested: { p: 1, q: 2 },
+    });
+    expect(
+      stableStringifyToolArgs(cache, "key", {
+        nested: { q: 3, p: 4 },
+        list: [{ y: 5, x: 6 }],
+      }),
+    ).toBe(
+      JSON.stringify({
+        list: [{ x: 6, y: 5 }],
+        nested: { p: 4, q: 3 },
+      }),
+    );
+  });
+
+  it("keeps caches per cacheKey independent", () => {
+    const cache = new Map<string, Map<string, string[]>>();
+    stableStringifyToolArgs(cache, "one", { a: 1, b: 2 });
+    expect(stableStringifyToolArgs(cache, "two", { b: 3, a: 4 })).toBe(
+      JSON.stringify({ b: 3, a: 4 }),
+    );
+  });
+
+  it("keeps dotted keys independent from nested paths", () => {
+    const cache = new Map<string, Map<string, string[]>>();
+    stableStringifyToolArgs(cache, "key", { a: { b: { p: 1, q: 2 } } });
+    expect(
+      stableStringifyToolArgs(cache, "key", { "a.b": { q: 3, p: 4 } }),
+    ).toBe(JSON.stringify({ "a.b": { q: 3, p: 4 } }));
+    expect(
+      stableStringifyToolArgs(cache, "key", { a: { b: { q: 9, p: 8 } } }),
+    ).toBe(JSON.stringify({ a: { b: { p: 8, q: 9 } } }));
+  });
+
+  it("keeps bracket-mimic keys independent from array paths", () => {
+    const cache = new Map<string, Map<string, string[]>>();
+    stableStringifyToolArgs(cache, "key", { x: [{ m: 1, n: 2 }] });
+    expect(
+      stableStringifyToolArgs(cache, "key", { "x[0]": { n: 3, m: 4 } }),
+    ).toBe(JSON.stringify({ "x[0]": { n: 3, m: 4 } }));
+    expect(stableStringifyToolArgs(cache, "key", { x: [{ n: 5, m: 6 }] })).toBe(
+      JSON.stringify({ x: [{ m: 6, n: 5 }] }),
+    );
+  });
+});
+
+describe("trackToolArgsKeyOrder", () => {
+  it("seeds the order a later stringify follows", () => {
+    const cache = new Map<string, Map<string, string[]>>();
+    trackToolArgsKeyOrder(cache, "key", { b: 1, a: 2 });
+    expect(stableStringifyToolArgs(cache, "key", { a: 3, b: 4 })).toBe(
+      JSON.stringify({ b: 4, a: 3 }),
+    );
+  });
+
+  it("is a no-op without a cache", () => {
+    expect(() =>
+      trackToolArgsKeyOrder(undefined, "key", { a: 1 }),
+    ).not.toThrow();
+  });
+});

package/src/utils/json/stable-stringify-tool-args.ts

@@ -0,0 +1,70 @@
+import type { ReadonlyJSONObject } from "assistant-stream/utils";
+
+const stabilizeToolArgsValue = (
+  value: unknown,
+  path: string,
+  keyOrderByPath: Map<string, string[]>,
+): unknown => {
+  if (Array.isArray(value)) {
+    return value.map((item, idx) =>
+      stabilizeToolArgsValue(item, `${path}[${idx}]`, keyOrderByPath),
+    );
+  }
+
+  if (value && typeof value === "object") {
+    const record = value as Record<string, unknown>;
+    const currentKeys = Object.keys(record);
+    const previousOrder = keyOrderByPath.get(path) ?? [];
+    const previousOrderSet = new Set(previousOrder);
+    const nextOrder = [
+      ...previousOrder.filter((key) => Object.hasOwn(record, key)),
+      ...currentKeys.filter((key) => !previousOrderSet.has(key)),
+    ];
+    keyOrderByPath.set(path, nextOrder);
+
+    return Object.fromEntries(
+      nextOrder.map((key) => [
+        key,
+        stabilizeToolArgsValue(
+          record[key],
+          `${path}.${JSON.stringify(key)}`,
+          keyOrderByPath,
+        ),
+      ]),
+    );
+  }
+
+  return value;
+};
+
+const getToolArgsKeyOrder = (
+  keyOrderCache: Map<string, Map<string, string[]>> | undefined,
+  cacheKey: string,
+): Map<string, string[]> => {
+  const keyOrderByPath = keyOrderCache?.get(cacheKey) ?? new Map();
+  keyOrderCache?.set(cacheKey, keyOrderByPath);
+  return keyOrderByPath;
+};
+
+export const trackToolArgsKeyOrder = (
+  keyOrderCache: Map<string, Map<string, string[]>> | undefined,
+  cacheKey: string,
+  args: ReadonlyJSONObject,
+) => {
+  const keyOrderByPath = getToolArgsKeyOrder(keyOrderCache, cacheKey);
+  stabilizeToolArgsValue(args, "$", keyOrderByPath);
+};
+
+export const stableStringifyToolArgs = (
+  keyOrderCache: Map<string, Map<string, string[]>> | undefined,
+  cacheKey: string,
+  args: ReadonlyJSONObject,
+): string => {
+  const keyOrderByPath = getToolArgsKeyOrder(keyOrderCache, cacheKey);
+  const stableArgs = stabilizeToolArgsValue(
+    args,
+    "$",
+    keyOrderByPath,
+  ) as ReadonlyJSONObject;
+  return JSON.stringify(stableArgs);
+};