@copilotkit/shared 1.73.0 → 1.73.2-canary.1790068297

package/dist/utils/row-render-keys.mjs

@@ -0,0 +1,201 @@
+//#region src/utils/row-render-keys.ts
+/**
+* Stable per-row view keys for chat transcripts, across backends that re-key a
+* message mid-stream. Shared by every frontend package, because the defect and
+* the correlation signal are in the message stream, not in any one framework.
+*
+* ## The problem
+*
+* A message's canonical `id` is not stable within a turn. LangChain stamps a
+* placeholder id on the first streamed chunk when the provider didn't supply
+* one (`chat_models.py`: `if chunk.message.id is None: chunk.message.id =
+* "lc_run-" + "-" + run_id`), then prefers any provider-assigned id it sees
+* while merging chunks (`messages/ai.py`, "Ranks are defined by the order of
+* preference"). The `MESSAGES_SNAPSHOT` therefore carries the provider's final
+* id (e.g. `resp_…`) for a message the client already knows as `lc_run--…`.
+*
+* Every framework destroys and recreates a row whose key changes, so keying
+* rows by `id` turned that swap into the visible HITL chat flash, where a
+* rendered approval card appears to reset during a tool's
+* `executing → complete` transition.
+*
+* This is provider-conditional: providers that stamp an id on every chunk (so
+* `chunk.message.id is None` never holds) never trigger a rename.
+*
+* ## The approach
+*
+* Tool-call ids survive the rename, so they are used as *anchors*: the first
+* message seen carrying a given tool call records the key it was assigned, and
+* any later message carrying that same tool call reuses it. The store is an
+* override table consulted before falling back to `message.id`. Resolving only
+* reads it; each render that reaches the DOM then records what it rendered:
+*
+* ```text
+* render 1  id=lc_run--1  no tools    key = message.id = lc_run--1
+*   commit 1                                                           store {}
+* render 2  id=lc_run--1  tc call_A   key = message.id = lc_run--1
+*   commit 2                                           store { tc:call_A -> lc_run--1 }
+* render 3  id=resp_1     tc call_A   key = store[tc:call_A]
+*                                         = lc_run--1  (row survives)
+*   commit 3                                                    store unchanged
+* ```
+*
+* Recording the anchor at commit 2 — while the id is still stable — is what
+* makes render 3 resolvable. Note the fix does not depend on render 2
+* existing: a message born already carrying a tool call anchors on the first
+* render that commits it, under whatever id it holds then.
+*
+* ## Why an override table rather than keying rows by tool-call id
+*
+* Deriving the key from the tool call directly (`tc:<id>` whenever a tool call
+* is present) needs no state, but changes the key the moment a tool call
+* *appears* — so an assistant message that streams text and then calls a tool
+* is torn down on that transition, for every provider, whether or not it
+* renames. That trades a conditional flash for an unconditional one. Recording
+* an override keeps the key the row already had.
+*
+* ## Cost
+*
+* The store holds only `tc:<toolCallId>` entries, so a conversation with no
+* tool calls keeps an empty store and behaviour byte-identical to keying by
+* `id`. Size is bounded to the tool calls of the currently-rendered messages
+* (see `pruneRowKeyStore`), not the conversation length. Deleting the store
+* reverts to plain `id` keying.
+*
+* ## Known gaps
+*
+* - A text-only assistant message has no anchor, so it still re-keys. No
+*   client-side correlation signal exists for it; the fix is stable ids
+*   upstream.
+* - If the tool call's arrival and the id swap land in the same update, the
+*   intermediate state never renders, the anchor is never recorded, and the
+*   row is recreated as before. Correlating in the event-apply layer (i.e. in
+*   the AG-UI client, which observes every intermediate state) would be immune.
+*/
+const TOOL_ANCHOR_PREFIX = "tc:";
+function createRowKeyStore() {
+	return {
+		overrides: /* @__PURE__ */ new Map(),
+		ambiguous: /* @__PURE__ */ new Set()
+	};
+}
+/**
+* Anchors a message contributes. Only assistant tool calls qualify: LangChain's
+* id preference applies when merging `AIMessageChunk`s, so user message ids are
+* not renamed, and `role: "tool"` messages are not rendered as rows. Every tool
+* call is used (not just the first) so the anchor survives tool-call reordering
+* between snapshots.
+*/
+function toolAnchorsOf(message) {
+	if (message?.role !== "assistant") return [];
+	const toolCalls = message.toolCalls;
+	if (!toolCalls?.length) return [];
+	const anchors = [];
+	for (const toolCall of toolCalls) if (toolCall?.id) anchors.push(`${TOOL_ANCHOR_PREFIX}${toolCall.id}`);
+	return anchors;
+}
+/**
+* Resolves the row key for every message, returned by position.
+*
+* Pure: it reads `store` and never writes to it. Every framework here may
+* evaluate a render pass whose result never reaches the DOM — an abandoned
+* concurrent render in React, a discarded `computed` evaluation in Vue or
+* Angular. An anchor recorded by such a pass would vend its key to the pass
+* that does render, re-keying the row the user is looking at, which is the
+* teardown this module exists to prevent. Anchors are recorded by
+* `commitRowKeyStore`, from whichever phase each framework runs after the DOM
+* is updated.
+*
+* Uniqueness is structural rather than assumed: a caller that does not
+* deduplicate can pass two rows with the same id, and an override can vend a
+* key equal to a later message's own id.
+*/
+function resolveRowRenderKeys(store, messages) {
+	const keys = [];
+	const claimed = /* @__PURE__ */ new Set();
+	messages.forEach((message, index) => {
+		const anchors = toolAnchorsOf(message);
+		let key;
+		for (const anchor of anchors) {
+			if (store.ambiguous.has(anchor)) continue;
+			const recorded = store.overrides.get(anchor);
+			if (recorded !== void 0 && !claimed.has(recorded)) {
+				key = recorded;
+				break;
+			}
+		}
+		key ??= message?.id || `index-${index}`;
+		if (claimed.has(key)) {
+			let suffix = 2;
+			while (claimed.has(`${key}:${suffix}`)) suffix += 1;
+			key = `${key}:${suffix}`;
+		}
+		keys.push(key);
+		claimed.add(key);
+	});
+	return keys;
+}
+/**
+* `message.id` → row key, for callers that render by message rather than by
+* position. `messages` must be deduplicated: duplicate ids would overwrite
+* each other in the returned map.
+*/
+function resolveRowRenderKeysById(store, messages) {
+	const keys = resolveRowRenderKeys(store, messages);
+	const byId = /* @__PURE__ */ new Map();
+	messages.forEach((message, index) => {
+		const key = keys[index];
+		if (key !== void 0) byId.set(message.id, key);
+	});
+	return byId;
+}
+/**
+* Records the anchors of a rendered list, then bounds the store to it. Call
+* from the phase that runs after the DOM is updated, never while resolving —
+* see `resolveRowRenderKeys`.
+*
+* Re-resolving here reproduces the keys the rows were rendered with, because
+* the store cannot change between a render and its own post-render phase.
+*
+* An anchor carried by two rows in the same list is marked ambiguous rather
+* than recorded. Recording it would give the first row's key to whichever row
+* outlived the other, and with it that row's DOM and component state.
+*/
+function commitRowKeyStore(store, messages) {
+	const keys = resolveRowRenderKeys(store, messages);
+	const anchorCounts = /* @__PURE__ */ new Map();
+	for (const message of messages) for (const anchor of toolAnchorsOf(message)) anchorCounts.set(anchor, (anchorCounts.get(anchor) ?? 0) + 1);
+	store.ambiguous.clear();
+	for (const [anchor, count] of anchorCounts) if (count > 1) {
+		store.ambiguous.add(anchor);
+		store.overrides.delete(anchor);
+	}
+	messages.forEach((message, index) => {
+		const key = keys[index];
+		if (key === void 0) return;
+		for (const anchor of toolAnchorsOf(message)) {
+			if (store.ambiguous.has(anchor)) continue;
+			if (!store.overrides.has(anchor)) store.overrides.set(anchor, key);
+		}
+	});
+	pruneRowKeyStore(store, messages);
+}
+/**
+* Drops anchors no longer present in `messages`, bounding the store to the
+* tool calls of the currently-rendered messages. Called by
+* `commitRowKeyStore`; like it, this writes to the store and so belongs after
+* the DOM is updated, never while resolving.
+*
+* Pruned entries are unreachable by construction: `resolveRowRenderKeys` only
+* looks up anchors belonging to messages in the list it is given.
+*/
+function pruneRowKeyStore(store, messages) {
+	const live = /* @__PURE__ */ new Set();
+	for (const message of messages) for (const anchor of toolAnchorsOf(message)) live.add(anchor);
+	for (const anchor of store.overrides.keys()) if (!live.has(anchor)) store.overrides.delete(anchor);
+	for (const anchor of store.ambiguous) if (!live.has(anchor)) store.ambiguous.delete(anchor);
+}
+
+//#endregion
+export { commitRowKeyStore, createRowKeyStore, pruneRowKeyStore, resolveRowRenderKeys, resolveRowRenderKeysById };
+//# sourceMappingURL=row-render-keys.mjs.map

package/dist/utils/row-render-keys.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"row-render-keys.mjs","names":[],"sources":["../../src/utils/row-render-keys.ts"],"sourcesContent":["import type { AssistantMessage, Message } from \"@ag-ui/core\";\n\n/**\n * Stable per-row view keys for chat transcripts, across backends that re-key a\n * message mid-stream. Shared by every frontend package, because the defect and\n * the correlation signal are in the message stream, not in any one framework.\n *\n * ## The problem\n *\n * A message's canonical `id` is not stable within a turn. LangChain stamps a\n * placeholder id on the first streamed chunk when the provider didn't supply\n * one (`chat_models.py`: `if chunk.message.id is None: chunk.message.id =\n * \"lc_run-\" + \"-\" + run_id`), then prefers any provider-assigned id it sees\n * while merging chunks (`messages/ai.py`, \"Ranks are defined by the order of\n * preference\"). The `MESSAGES_SNAPSHOT` therefore carries the provider's final\n * id (e.g. `resp_…`) for a message the client already knows as `lc_run--…`.\n *\n * Every framework destroys and recreates a row whose key changes, so keying\n * rows by `id` turned that swap into the visible HITL chat flash, where a\n * rendered approval card appears to reset during a tool's\n * `executing → complete` transition.\n *\n * This is provider-conditional: providers that stamp an id on every chunk (so\n * `chunk.message.id is None` never holds) never trigger a rename.\n *\n * ## The approach\n *\n * Tool-call ids survive the rename, so they are used as *anchors*: the first\n * message seen carrying a given tool call records the key it was assigned, and\n * any later message carrying that same tool call reuses it. The store is an\n * override table consulted before falling back to `message.id`. Resolving only\n * reads it; each render that reaches the DOM then records what it rendered:\n *\n * ```text\n * render 1  id=lc_run--1  no tools    key = message.id = lc_run--1\n *   commit 1                                                           store {}\n * render 2  id=lc_run--1  tc call_A   key = message.id = lc_run--1\n *   commit 2                                           store { tc:call_A -> lc_run--1 }\n * render 3  id=resp_1     tc call_A   key = store[tc:call_A]\n *                                         = lc_run--1  (row survives)\n *   commit 3                                                    store unchanged\n * ```\n *\n * Recording the anchor at commit 2 — while the id is still stable — is what\n * makes render 3 resolvable. Note the fix does not depend on render 2\n * existing: a message born already carrying a tool call anchors on the first\n * render that commits it, under whatever id it holds then.\n *\n * ## Why an override table rather than keying rows by tool-call id\n *\n * Deriving the key from the tool call directly (`tc:<id>` whenever a tool call\n * is present) needs no state, but changes the key the moment a tool call\n * *appears* — so an assistant message that streams text and then calls a tool\n * is torn down on that transition, for every provider, whether or not it\n * renames. That trades a conditional flash for an unconditional one. Recording\n * an override keeps the key the row already had.\n *\n * ## Cost\n *\n * The store holds only `tc:<toolCallId>` entries, so a conversation with no\n * tool calls keeps an empty store and behaviour byte-identical to keying by\n * `id`. Size is bounded to the tool calls of the currently-rendered messages\n * (see `pruneRowKeyStore`), not the conversation length. Deleting the store\n * reverts to plain `id` keying.\n *\n * ## Known gaps\n *\n * - A text-only assistant message has no anchor, so it still re-keys. No\n *   client-side correlation signal exists for it; the fix is stable ids\n *   upstream.\n * - If the tool call's arrival and the id swap land in the same update, the\n *   intermediate state never renders, the anchor is never recorded, and the\n *   row is recreated as before. Correlating in the event-apply layer (i.e. in\n *   the AG-UI client, which observes every intermediate state) would be immune.\n */\n\nconst TOOL_ANCHOR_PREFIX = \"tc:\";\n\nexport interface RowKeyStore {\n  /**\n   * `tc:<toolCallId>` → the row key first assigned to a message carrying that\n   * tool call. Populated only for assistant messages that carry tool calls.\n   */\n  overrides: Map<string, string>;\n  /**\n   * Anchors carried by more than one message in the last rendered list. Such\n   * an anchor identifies no single row, so it is never used to vend a key.\n   */\n  ambiguous: Set<string>;\n}\n\nexport function createRowKeyStore(): RowKeyStore {\n  return { overrides: new Map(), ambiguous: new Set() };\n}\n\n/**\n * Anchors a message contributes. Only assistant tool calls qualify: LangChain's\n * id preference applies when merging `AIMessageChunk`s, so user message ids are\n * not renamed, and `role: \"tool\"` messages are not rendered as rows. Every tool\n * call is used (not just the first) so the anchor survives tool-call reordering\n * between snapshots.\n */\nfunction toolAnchorsOf(message: Message | undefined): string[] {\n  if (message?.role !== \"assistant\") return [];\n  const toolCalls = (message as AssistantMessage).toolCalls;\n  if (!toolCalls?.length) return [];\n\n  const anchors: string[] = [];\n  for (const toolCall of toolCalls) {\n    if (toolCall?.id) anchors.push(`${TOOL_ANCHOR_PREFIX}${toolCall.id}`);\n  }\n  return anchors;\n}\n\n/**\n * Resolves the row key for every message, returned by position.\n *\n * Pure: it reads `store` and never writes to it. Every framework here may\n * evaluate a render pass whose result never reaches the DOM — an abandoned\n * concurrent render in React, a discarded `computed` evaluation in Vue or\n * Angular. An anchor recorded by such a pass would vend its key to the pass\n * that does render, re-keying the row the user is looking at, which is the\n * teardown this module exists to prevent. Anchors are recorded by\n * `commitRowKeyStore`, from whichever phase each framework runs after the DOM\n * is updated.\n *\n * Uniqueness is structural rather than assumed: a caller that does not\n * deduplicate can pass two rows with the same id, and an override can vend a\n * key equal to a later message's own id.\n */\nexport function resolveRowRenderKeys(\n  store: RowKeyStore,\n  messages: readonly (Message | undefined)[],\n): string[] {\n  const keys: string[] = [];\n  const claimed = new Set<string>();\n\n  messages.forEach((message, index) => {\n    const anchors = toolAnchorsOf(message);\n\n    // Reuse the key recorded for any of this message's anchors. An override\n    // pointing at a key another row already claimed this pass is skipped: two\n    // messages can share a tool-call id (upstream bug, or replayed state), and\n    // the later one falls back to its own id instead.\n    let key: string | undefined;\n    for (const anchor of anchors) {\n      if (store.ambiguous.has(anchor)) continue;\n      const recorded = store.overrides.get(anchor);\n      if (recorded !== undefined && !claimed.has(recorded)) {\n        key = recorded;\n        break;\n      }\n    }\n\n    // The index fallback covers a message with no usable id.\n    key ??= message?.id || `index-${index}`;\n\n    if (claimed.has(key)) {\n      let suffix = 2;\n      while (claimed.has(`${key}:${suffix}`)) suffix += 1;\n      key = `${key}:${suffix}`;\n    }\n\n    keys.push(key);\n    claimed.add(key);\n  });\n\n  return keys;\n}\n\n/**\n * `message.id` → row key, for callers that render by message rather than by\n * position. `messages` must be deduplicated: duplicate ids would overwrite\n * each other in the returned map.\n */\nexport function resolveRowRenderKeysById(\n  store: RowKeyStore,\n  messages: readonly Message[],\n): Map<string, string> {\n  const keys = resolveRowRenderKeys(store, messages);\n  const byId = new Map<string, string>();\n  messages.forEach((message, index) => {\n    const key = keys[index];\n    if (key !== undefined) byId.set(message.id, key);\n  });\n  return byId;\n}\n\n/**\n * Records the anchors of a rendered list, then bounds the store to it. Call\n * from the phase that runs after the DOM is updated, never while resolving —\n * see `resolveRowRenderKeys`.\n *\n * Re-resolving here reproduces the keys the rows were rendered with, because\n * the store cannot change between a render and its own post-render phase.\n *\n * An anchor carried by two rows in the same list is marked ambiguous rather\n * than recorded. Recording it would give the first row's key to whichever row\n * outlived the other, and with it that row's DOM and component state.\n */\nexport function commitRowKeyStore(\n  store: RowKeyStore,\n  messages: readonly (Message | undefined)[],\n): void {\n  const keys = resolveRowRenderKeys(store, messages);\n\n  const anchorCounts = new Map<string, number>();\n  for (const message of messages) {\n    for (const anchor of toolAnchorsOf(message)) {\n      anchorCounts.set(anchor, (anchorCounts.get(anchor) ?? 0) + 1);\n    }\n  }\n\n  // Ambiguity is a property of the rendered list, so it is recomputed rather\n  // than accumulated: an anchor left alone by the row that shadowed it becomes\n  // usable again.\n  store.ambiguous.clear();\n  for (const [anchor, count] of anchorCounts) {\n    if (count > 1) {\n      store.ambiguous.add(anchor);\n      store.overrides.delete(anchor);\n    }\n  }\n\n  // First claimant of an anchor owns it, so a re-keyed message resolves to the\n  // key the row already had rather than overwriting it.\n  messages.forEach((message, index) => {\n    const key = keys[index];\n    if (key === undefined) return;\n    for (const anchor of toolAnchorsOf(message)) {\n      if (store.ambiguous.has(anchor)) continue;\n      if (!store.overrides.has(anchor)) store.overrides.set(anchor, key);\n    }\n  });\n\n  pruneRowKeyStore(store, messages);\n}\n\n/**\n * Drops anchors no longer present in `messages`, bounding the store to the\n * tool calls of the currently-rendered messages. Called by\n * `commitRowKeyStore`; like it, this writes to the store and so belongs after\n * the DOM is updated, never while resolving.\n *\n * Pruned entries are unreachable by construction: `resolveRowRenderKeys` only\n * looks up anchors belonging to messages in the list it is given.\n */\nexport function pruneRowKeyStore(\n  store: RowKeyStore,\n  messages: readonly (Message | undefined)[],\n): void {\n  const live = new Set<string>();\n  for (const message of messages) {\n    for (const anchor of toolAnchorsOf(message)) live.add(anchor);\n  }\n\n  for (const anchor of store.overrides.keys()) {\n    if (!live.has(anchor)) store.overrides.delete(anchor);\n  }\n  for (const anchor of store.ambiguous) {\n    if (!live.has(anchor)) store.ambiguous.delete(anchor);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4EA,MAAM,qBAAqB;AAe3B,SAAgB,oBAAiC;AAC/C,QAAO;EAAE,2BAAW,IAAI,KAAK;EAAE,2BAAW,IAAI,KAAK;EAAE;;;;;;;;;AAUvD,SAAS,cAAc,SAAwC;AAC7D,KAAI,SAAS,SAAS,YAAa,QAAO,EAAE;CAC5C,MAAM,YAAa,QAA6B;AAChD,KAAI,CAAC,WAAW,OAAQ,QAAO,EAAE;CAEjC,MAAM,UAAoB,EAAE;AAC5B,MAAK,MAAM,YAAY,UACrB,KAAI,UAAU,GAAI,SAAQ,KAAK,GAAG,qBAAqB,SAAS,KAAK;AAEvE,QAAO;;;;;;;;;;;;;;;;;;AAmBT,SAAgB,qBACd,OACA,UACU;CACV,MAAM,OAAiB,EAAE;CACzB,MAAM,0BAAU,IAAI,KAAa;AAEjC,UAAS,SAAS,SAAS,UAAU;EACnC,MAAM,UAAU,cAAc,QAAQ;EAMtC,IAAI;AACJ,OAAK,MAAM,UAAU,SAAS;AAC5B,OAAI,MAAM,UAAU,IAAI,OAAO,CAAE;GACjC,MAAM,WAAW,MAAM,UAAU,IAAI,OAAO;AAC5C,OAAI,aAAa,UAAa,CAAC,QAAQ,IAAI,SAAS,EAAE;AACpD,UAAM;AACN;;;AAKJ,UAAQ,SAAS,MAAM,SAAS;AAEhC,MAAI,QAAQ,IAAI,IAAI,EAAE;GACpB,IAAI,SAAS;AACb,UAAO,QAAQ,IAAI,GAAG,IAAI,GAAG,SAAS,CAAE,WAAU;AAClD,SAAM,GAAG,IAAI,GAAG;;AAGlB,OAAK,KAAK,IAAI;AACd,UAAQ,IAAI,IAAI;GAChB;AAEF,QAAO;;;;;;;AAQT,SAAgB,yBACd,OACA,UACqB;CACrB,MAAM,OAAO,qBAAqB,OAAO,SAAS;CAClD,MAAM,uBAAO,IAAI,KAAqB;AACtC,UAAS,SAAS,SAAS,UAAU;EACnC,MAAM,MAAM,KAAK;AACjB,MAAI,QAAQ,OAAW,MAAK,IAAI,QAAQ,IAAI,IAAI;GAChD;AACF,QAAO;;;;;;;;;;;;;;AAeT,SAAgB,kBACd,OACA,UACM;CACN,MAAM,OAAO,qBAAqB,OAAO,SAAS;CAElD,MAAM,+BAAe,IAAI,KAAqB;AAC9C,MAAK,MAAM,WAAW,SACpB,MAAK,MAAM,UAAU,cAAc,QAAQ,CACzC,cAAa,IAAI,SAAS,aAAa,IAAI,OAAO,IAAI,KAAK,EAAE;AAOjE,OAAM,UAAU,OAAO;AACvB,MAAK,MAAM,CAAC,QAAQ,UAAU,aAC5B,KAAI,QAAQ,GAAG;AACb,QAAM,UAAU,IAAI,OAAO;AAC3B,QAAM,UAAU,OAAO,OAAO;;AAMlC,UAAS,SAAS,SAAS,UAAU;EACnC,MAAM,MAAM,KAAK;AACjB,MAAI,QAAQ,OAAW;AACvB,OAAK,MAAM,UAAU,cAAc,QAAQ,EAAE;AAC3C,OAAI,MAAM,UAAU,IAAI,OAAO,CAAE;AACjC,OAAI,CAAC,MAAM,UAAU,IAAI,OAAO,CAAE,OAAM,UAAU,IAAI,QAAQ,IAAI;;GAEpE;AAEF,kBAAiB,OAAO,SAAS;;;;;;;;;;;AAYnC,SAAgB,iBACd,OACA,UACM;CACN,MAAM,uBAAO,IAAI,KAAa;AAC9B,MAAK,MAAM,WAAW,SACpB,MAAK,MAAM,UAAU,cAAc,QAAQ,CAAE,MAAK,IAAI,OAAO;AAG/D,MAAK,MAAM,UAAU,MAAM,UAAU,MAAM,CACzC,KAAI,CAAC,KAAK,IAAI,OAAO,CAAE,OAAM,UAAU,OAAO,OAAO;AAEvD,MAAK,MAAM,UAAU,MAAM,UACzB,KAAI,CAAC,KAAK,IAAI,OAAO,CAAE,OAAM,UAAU,OAAO,OAAO"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@copilotkit/shared",
-  "version": "1.73.0",
+  "version": "1.73.2-canary.1790068297",
   "private": false,
   "keywords": [
     "ai",
@@ -32,6 +32,10 @@
       "import": "./dist/index.mjs",
       "require": "./dist/index.cjs"
     },
+    "./event-transforms": {
+      "import": "./dist/event-transforms/index.mjs",
+      "require": "./dist/event-transforms/index.cjs"
+    },
     "./telemetry": {
       "import": "./dist/telemetry/index.mjs",
       "require": "./dist/telemetry/index.cjs"
@@ -42,6 +46,9 @@
     "*": {
       "telemetry": [
         "./dist/telemetry/index.d.cts"
+      ],
+      "event-transforms": [
+        "./dist/event-transforms/index.d.cts"
       ]
     }
   },
@@ -49,18 +56,22 @@
     "access": "public"
   },
   "dependencies": {
+    "@ag-ui/a2ui-middleware": "0.0.10",
     "@ag-ui/client": "0.0.59",
     "@copilotkit/license-verifier": "~0.5.0",
     "@segment/analytics-node": "^2.1.2",
     "@standard-schema/spec": "^1.0.0",
     "chalk": "4.1.2",
+    "clarinet": "^0.12.4",
     "graphql": "^16.8.1",
     "partial-json": "^0.1.7",
+    "rxjs": "7.8.1",
     "uuid": "^11.1.0",
     "zod": "^3.23.3",
     "zod-to-json-schema": "^3.23.5"
   },
   "devDependencies": {
+    "@types/clarinet": "^0.12.3",
     "@types/uuid": "^10.0.0",
     "@valibot/to-json-schema": "^1.5.0",
     "arktype": "^2.1.29",

package/src/__tests__/root-entry-browser-safety.test.ts

@@ -16,7 +16,13 @@ import { describe, expect, it } from "vitest";
  * value-level graph from `src/index.ts` and fails if it reaches a Node-only
  * package. Type-only edges are erased at build time and are therefore fine.
  */
-const NODE_ONLY_PACKAGES = ["@segment/analytics-node", "node-fetch"];
+const NODE_ONLY_PACKAGES = [
+  "@segment/analytics-node",
+  "node-fetch",
+  "@ag-ui/a2ui-middleware",
+  "clarinet",
+  "rxjs",
+];
 
 const SRC = resolve(__dirname, "..");
 

package/src/attachments/content.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from "vitest";
+import { createAttachmentContent } from "./content";
+
+describe("createAttachmentContent", () => {
+  it.each(["image", "audio", "video", "document"] as const)(
+    "preserves %s bytes, source, and metadata precedence",
+    (type) => {
+      const source = {
+        type: "data",
+        value: "AAEC",
+        mimeType: "application/octet-stream",
+      } as const;
+      const part = createAttachmentContent({
+        type,
+        source,
+        filename: "upload.bin",
+        metadata: { filename: "custom.bin", custom: { value: 1 } },
+      });
+      expect(part).toEqual({
+        type,
+        source,
+        metadata: { filename: "custom.bin", custom: { value: 1 } },
+      });
+      expect("source" in part && part.source).toBe(source);
+    },
+  );
+
+  it("preserves URL sources and always includes metadata", () => {
+    const source = {
+      type: "url",
+      value: "https://example.test/image.png",
+    } as const;
+    expect(
+      createAttachmentContent({ type: "image", source, filename: "" }),
+    ).toEqual({
+      type: "image",
+      source,
+      metadata: {},
+    });
+    expect(
+      createAttachmentContent({ type: "image", source, filename: "image.png" }),
+    ).toEqual({
+      type: "image",
+      source,
+      metadata: { filename: "image.png" },
+    });
+  });
+});

package/src/attachments/content.ts

@@ -0,0 +1,16 @@
+import type { InputContent } from "@ag-ui/core";
+import type { Attachment } from "./types";
+
+/** Build the AG-UI content part used when sending a ready attachment. */
+export function createAttachmentContent(
+  attachment: Pick<Attachment, "type" | "source" | "filename" | "metadata">,
+): InputContent {
+  return {
+    type: attachment.type,
+    source: attachment.source,
+    metadata: {
+      ...(attachment.filename ? { filename: attachment.filename } : {}),
+      ...attachment.metadata,
+    },
+  };
+}

package/src/attachments/index.ts

@@ -7,6 +7,8 @@ export type {
   AttachmentModality,
 } from "./types";
 
+export { createAttachmentContent } from "./content";
+
 export {
   getModalityFromMimeType,
   formatFileSize,

package/src/event-transforms/index.ts

@@ -0,0 +1,5 @@
+// Server-only entry: A2UI depends on node:crypto. Do not re-export from the root.
+export { A2UIMiddleware } from "@ag-ui/a2ui-middleware";
+export type { A2UIMiddlewareConfig } from "@ag-ui/a2ui-middleware";
+export * from "./open-generative-ui-middleware";
+export * from "./recorded-events";