@copilotkit/sdk-js 2.0.0-next.1 → 2.0.0-rc.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (99) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +0 -1
  3. package/dist/_virtual/_rolldown/runtime.cjs +29 -0
  4. package/dist/header-propagation.cjs +37 -0
  5. package/dist/header-propagation.cjs.map +1 -0
  6. package/dist/header-propagation.d.cts +16 -0
  7. package/dist/header-propagation.d.cts.map +1 -0
  8. package/dist/header-propagation.d.mts +16 -0
  9. package/dist/header-propagation.d.mts.map +1 -0
  10. package/dist/header-propagation.mjs +35 -0
  11. package/dist/header-propagation.mjs.map +1 -0
  12. package/dist/index.cjs +5 -0
  13. package/dist/index.d.cts +18 -0
  14. package/dist/index.d.mts +18 -0
  15. package/dist/index.mjs +3 -1
  16. package/dist/langchain.cjs +21 -0
  17. package/dist/langchain.cjs.map +1 -0
  18. package/dist/langchain.d.cts +139 -0
  19. package/dist/langchain.d.mts +140 -0
  20. package/dist/langchain.mjs +7 -23
  21. package/dist/langchain.mjs.map +1 -1
  22. package/dist/langgraph/middleware.cjs +433 -0
  23. package/dist/langgraph/middleware.cjs.map +1 -0
  24. package/dist/langgraph/middleware.d.cts +86 -0
  25. package/dist/langgraph/middleware.d.cts.map +1 -0
  26. package/dist/langgraph/middleware.d.mts +86 -0
  27. package/dist/langgraph/middleware.d.mts.map +1 -0
  28. package/dist/langgraph/middleware.mjs +429 -0
  29. package/dist/langgraph/middleware.mjs.map +1 -0
  30. package/dist/langgraph/state-schema.cjs +37 -0
  31. package/dist/langgraph/state-schema.cjs.map +1 -0
  32. package/dist/langgraph/state-schema.d.cts +118 -0
  33. package/dist/langgraph/state-schema.d.cts.map +1 -0
  34. package/dist/langgraph/state-schema.d.mts +118 -0
  35. package/dist/langgraph/state-schema.d.mts.map +1 -0
  36. package/dist/langgraph/state-schema.mjs +36 -0
  37. package/dist/langgraph/state-schema.mjs.map +1 -0
  38. package/dist/langgraph/types.cjs +60 -0
  39. package/dist/langgraph/types.cjs.map +1 -0
  40. package/dist/langgraph/types.d.cts +335 -0
  41. package/dist/langgraph/types.d.cts.map +1 -0
  42. package/dist/langgraph/types.d.mts +335 -0
  43. package/dist/langgraph/types.d.mts.map +1 -0
  44. package/dist/langgraph/types.mjs +57 -0
  45. package/dist/langgraph/types.mjs.map +1 -0
  46. package/dist/langgraph/utils.cjs +297 -0
  47. package/dist/langgraph/utils.cjs.map +1 -0
  48. package/dist/langgraph/utils.d.cts +209 -0
  49. package/dist/langgraph/utils.d.cts.map +1 -0
  50. package/dist/langgraph/utils.d.mts +209 -0
  51. package/dist/langgraph/utils.d.mts.map +1 -0
  52. package/dist/langgraph/utils.mjs +289 -0
  53. package/dist/langgraph/utils.mjs.map +1 -0
  54. package/dist/langgraph-middlewares.cjs +22 -0
  55. package/dist/langgraph-middlewares.d.cts +30 -0
  56. package/dist/langgraph-middlewares.d.mts +30 -0
  57. package/dist/langgraph-middlewares.mjs +5 -0
  58. package/dist/langgraph.cjs +21 -0
  59. package/dist/langgraph.d.cts +5 -0
  60. package/dist/langgraph.d.mts +5 -0
  61. package/dist/langgraph.mjs +6 -27
  62. package/package.json +50 -47
  63. package/src/__tests__/error-handling.test.ts +54 -20
  64. package/src/__tests__/header-propagation.test.ts +131 -0
  65. package/src/header-propagation.ts +61 -0
  66. package/src/index.ts +41 -0
  67. package/src/langchain.ts +168 -8
  68. package/src/langgraph/__tests__/middleware.a2ui-params.test.ts +139 -0
  69. package/src/langgraph/__tests__/middleware.native-a2ui.test.ts +118 -0
  70. package/src/langgraph/__tests__/middleware.properties.test.ts +357 -0
  71. package/src/langgraph/__tests__/middleware.test.ts +1141 -0
  72. package/src/langgraph/__tests__/state-schema.test.ts +85 -0
  73. package/src/langgraph/__tests__/utils.test.ts +363 -0
  74. package/src/langgraph/index.ts +1 -0
  75. package/src/langgraph/middleware.ts +698 -95
  76. package/src/langgraph/state-schema.ts +34 -0
  77. package/src/langgraph/types.ts +57 -0
  78. package/src/langgraph/utils.ts +76 -19
  79. package/src/langgraph-middlewares.ts +55 -0
  80. package/tsconfig.json +11 -2
  81. package/tsdown.config.ts +18 -0
  82. package/vitest.config.mjs +11 -0
  83. package/CHANGELOG.md +0 -2169
  84. package/dist/chunk-JLGOQLGS.mjs +0 -433
  85. package/dist/chunk-JLGOQLGS.mjs.map +0 -1
  86. package/dist/index.d.ts +0 -2
  87. package/dist/index.js +0 -1
  88. package/dist/index.js.map +0 -1
  89. package/dist/index.mjs.map +0 -1
  90. package/dist/langchain-2645763d.d.ts +0 -427
  91. package/dist/langchain.d.ts +0 -6
  92. package/dist/langchain.js +0 -284
  93. package/dist/langchain.js.map +0 -1
  94. package/dist/langgraph/index.d.ts +0 -11
  95. package/dist/langgraph.js +0 -476
  96. package/dist/langgraph.js.map +0 -1
  97. package/dist/langgraph.mjs.map +0 -1
  98. package/jest.config.js +0 -5
  99. package/tsup.config.ts +0 -23
@@ -1,6 +1,399 @@
1
1
  import { createMiddleware, AIMessage } from "langchain";
2
2
  import type { InteropZodObject } from "@langchain/core/utils/types";
3
+ import type {
4
+ StandardJSONSchemaV1,
5
+ StandardSchemaV1,
6
+ } from "@standard-schema/spec";
3
7
  import * as z from "zod";
8
+ import { getA2UITools } from "@ag-ui/langgraph";
9
+ import type { A2UIToolParams } from "@ag-ui/langgraph";
10
+ import { getForwardedHeaders } from "../header-propagation";
11
+
12
+ // ---------------------------------------------------------------------------
13
+ // Auto-A2UI: bridge the inferred model's generate_a2ui tool from wrapModelCall
14
+ // (the only hook that exposes the bound model) to wrapToolCall (where the tool
15
+ // actually executes but the model is absent). Keyed by the run's thread id so
16
+ // concurrent runs don't clobber each other.
17
+ // ---------------------------------------------------------------------------
18
+ const a2uiToolsByThread = new Map<string, any>();
19
+ const A2UI_DEFAULT_THREAD_KEY = "__copilotkit_a2ui_default__";
20
+ const a2uiThreadKey = (state: any): string =>
21
+ (state?.thread_id as string) || A2UI_DEFAULT_THREAD_KEY;
22
+
23
+ /**
24
+ * Merge AG-UI defaults with CopilotKit overrides. Dictionaries recurse; every
25
+ * conflicting leaf uses CopilotKit, including false, null and empty values.
26
+ * Arrays and serialized strings are atomic: no positional pairing or decoding.
27
+ */
28
+ const isPropertyBag = (value: unknown): value is Record<string, unknown> =>
29
+ value !== null && typeof value === "object" && !Array.isArray(value);
30
+
31
+ const mergeProperties = (
32
+ base: Record<string, unknown>,
33
+ overrides: Record<string, unknown>,
34
+ ): Record<string, unknown> =>
35
+ Object.fromEntries(
36
+ Array.from(new Set([...Object.keys(base), ...Object.keys(overrides)])).map(
37
+ (key) => {
38
+ const value = Object.prototype.hasOwnProperty.call(overrides, key)
39
+ ? isPropertyBag(base[key]) && isPropertyBag(overrides[key])
40
+ ? mergeProperties(base[key], overrides[key])
41
+ : overrides[key]
42
+ : base[key];
43
+ return [key, value];
44
+ },
45
+ ),
46
+ );
47
+
48
+ const effectiveProperties = (state: unknown): Record<string, unknown> => {
49
+ const source = isPropertyBag(state) ? state : {};
50
+ return mergeProperties(
51
+ isPropertyBag(source["ag-ui"]) ? source["ag-ui"] : {},
52
+ isPropertyBag(source.copilotkit) ? source.copilotkit : {},
53
+ );
54
+ };
55
+
56
+ const decodeCatalogValue = (value: unknown): unknown => {
57
+ if (typeof value !== "string") return value;
58
+ try {
59
+ return JSON.parse(value);
60
+ } catch {
61
+ return value;
62
+ }
63
+ };
64
+
65
+ /**
66
+ * Find the frontend-registered A2UI catalog wherever it was passed. Returns
67
+ * `{ compositionGuide?, catalogId? }` when a catalog is present, else `null`
68
+ * independently of the explicit tool-injection decision. Two
69
+ * delivery paths, depending on how the agent is served:
70
+ * - AG-UI native endpoint → `state["ag-ui"].a2ui_schema` (JSON
71
+ * `{ catalogId, components }`); the toolkit reads it from state itself.
72
+ * - Runtime proxy → an effective `context` entry describing
73
+ * the A2UI catalog (catalog id + component schemas as text), passed to the
74
+ * subagent via `compositionGuide`.
75
+ * `catalogId` binds generated surfaces to the frontend's catalog so BYOC
76
+ * custom catalogs render their own components (not the basic one).
77
+ */
78
+ const resolveA2uiCatalog = (
79
+ state: any,
80
+ ): { compositionGuide?: string; catalogId?: string } | null => {
81
+ const properties = effectiveProperties(state);
82
+ const a2uiSchema = properties.a2ui_schema;
83
+ if (a2uiSchema) {
84
+ let catalogId: string | undefined;
85
+ try {
86
+ const parsed =
87
+ typeof a2uiSchema === "string" ? JSON.parse(a2uiSchema) : a2uiSchema;
88
+ catalogId = parsed?.catalogId;
89
+ } catch {
90
+ // non-JSON schema — fall back to the toolkit's basic catalog
91
+ }
92
+ return { catalogId };
93
+ }
94
+ const context = decodeCatalogValue(properties.context);
95
+ for (const entry of Array.isArray(context) ? context : []) {
96
+ const description = entry?.description;
97
+ const value = decodeCatalogValue(entry?.value);
98
+ if (
99
+ typeof description !== "string" ||
100
+ typeof value !== "string" ||
101
+ !description.includes("A2UI catalog") ||
102
+ !value
103
+ )
104
+ continue;
105
+ const match = /^\s*-\s+(\S+)/m.exec(value);
106
+ return { compositionGuide: value, catalogId: match?.[1] };
107
+ }
108
+ return null;
109
+ };
110
+
111
+ /**
112
+ * The A2UI `injectA2UITool` decision. The `@ag-ui/a2ui-middleware` forwards it on
113
+ * `forwardedProps`, which `ag-ui-langgraph` surfaces into agent state at
114
+ * `state["ag-ui"].inject_a2ui_tool` — present only when the host turned the
115
+ * runtime A2UI tool on (truthy or a custom tool-name string). `undefined` means
116
+ * no signal (off, or no A2UI middleware in the pipeline) → no auto-injection.
117
+ */
118
+ const a2uiInjectDecision = (state: any): boolean | string | undefined =>
119
+ effectiveProperties(state).inject_a2ui_tool as boolean | string | undefined;
120
+
121
+ type WithJsonSchema<T> = T extends { "~standard": infer S }
122
+ ? Omit<T, "~standard"> & {
123
+ "~standard": S &
124
+ StandardJSONSchemaV1.Props<
125
+ S extends StandardSchemaV1.Props<infer I, any> ? I : unknown,
126
+ S extends StandardSchemaV1.Props<any, infer O> ? O : unknown
127
+ >;
128
+ }
129
+ : T;
130
+
131
+ /**
132
+ * Augment a Standard-Schema–compatible schema (e.g. Zod) with a
133
+ * `~standard.jsonSchema.input` hook so LangGraph's
134
+ * `getJsonSchemaFromSchema` (called from `StateSchema.getJsonSchema`)
135
+ * can serialize the field.
136
+ *
137
+ * Without this, Zod v4 fields carry `~standard.validate` + `vendor` only,
138
+ * and `isStandardJSONSchema()` returns false, so the field is silently
139
+ * dropped from the graph's `output_schema`. That makes AG-UI
140
+ * `STATE_SNAPSHOT` events filter the field out of the payload sent to
141
+ * the frontend even though the underlying thread state has the value.
142
+ *
143
+ * Use this on any custom state field you want visible to the frontend
144
+ * via `useAgent().state.*`.
145
+ *
146
+ * @example
147
+ * ```ts
148
+ * import { zodState } from "@copilotkit/sdk-js/langgraph";
149
+ *
150
+ * const stateSchema = z.object({
151
+ * todos: zodState(z.array(TodoSchema).default(() => [])),
152
+ * });
153
+ * ```
154
+ */
155
+ export function zodState<T extends object>(schema: T): WithJsonSchema<T> {
156
+ const std = (schema as { "~standard"?: { jsonSchema?: unknown } })[
157
+ "~standard"
158
+ ];
159
+ if (std && typeof std === "object" && !("jsonSchema" in std)) {
160
+ let cached: Record<string, unknown> | undefined;
161
+ std.jsonSchema = {
162
+ input: () => {
163
+ if (cached) return cached;
164
+ // Prefer zod-v4's native `toJSONSchema` when available. Falls back to
165
+ // an empty object, which is sufficient for the field to appear in the
166
+ // graph's output_schema (langgraph-api treats it as an opaque field).
167
+ try {
168
+ const maybeV4ToJsonSchema = (
169
+ z as unknown as {
170
+ toJSONSchema?: (s: unknown) => Record<string, unknown>;
171
+ }
172
+ ).toJSONSchema;
173
+ cached =
174
+ typeof maybeV4ToJsonSchema === "function"
175
+ ? maybeV4ToJsonSchema(schema)
176
+ : {};
177
+ } catch {
178
+ cached = {};
179
+ }
180
+ return cached;
181
+ },
182
+ };
183
+ }
184
+ return schema as WithJsonSchema<T>;
185
+ }
186
+
187
+ /**
188
+ * Internal/framework state keys that should never be auto-surfaced to the
189
+ * LLM as user-facing state. These are reducer-managed message buckets,
190
+ * CopilotKit/AG-UI plumbing, or graph-internal scaffolding.
191
+ */
192
+ const RESERVED_STATE_KEYS: ReadonlySet<string> = new Set([
193
+ "messages",
194
+ "copilotkit",
195
+ "ag-ui",
196
+ "tools",
197
+ "structured_response",
198
+ "thread_id",
199
+ "remaining_steps",
200
+ ]);
201
+
202
+ /**
203
+ * Controls how user-defined state keys are surfaced into the LLM prompt
204
+ * on every model call. Off by default to avoid leaking arbitrary state
205
+ * into prompts; opt in explicitly.
206
+ *
207
+ * - `false` (default) — never surface state.
208
+ * - `true` — every state key not in the reserved internal set and not
209
+ * prefixed with `_` is JSON-serialized into a "Current agent state:"
210
+ * note appended to the system prompt.
211
+ * - `string[]` — only surface the named keys (use this when you want
212
+ * explicit control over what the LLM sees, e.g. `["liked", "todos"]`).
213
+ */
214
+ export type ExposeStateOption = boolean | readonly string[];
215
+
216
+ const buildStateNote = (
217
+ state: Record<string, unknown>,
218
+ expose: ExposeStateOption,
219
+ ): string | null => {
220
+ if (expose === false) return null;
221
+
222
+ const allow: ReadonlySet<string> | null = Array.isArray(expose)
223
+ ? new Set(expose)
224
+ : null;
225
+
226
+ const snapshot: Record<string, unknown> = {};
227
+ for (const key of Object.keys(state)) {
228
+ if (
229
+ allow
230
+ ? !allow.has(key)
231
+ : RESERVED_STATE_KEYS.has(key) || key.startsWith("_")
232
+ ) {
233
+ continue;
234
+ }
235
+ const value = state[key];
236
+ if (
237
+ value === undefined ||
238
+ value === null ||
239
+ value === "" ||
240
+ (Array.isArray(value) && value.length === 0) ||
241
+ (typeof value === "object" &&
242
+ !Array.isArray(value) &&
243
+ Object.keys(value as Record<string, unknown>).length === 0)
244
+ ) {
245
+ continue;
246
+ }
247
+ snapshot[key] = value;
248
+ }
249
+
250
+ if (Object.keys(snapshot).length === 0) return null;
251
+
252
+ let body: string;
253
+ try {
254
+ body = JSON.stringify(snapshot, null, 2);
255
+ } catch {
256
+ body = String(snapshot);
257
+ }
258
+ return `Current agent state:\n${body}`;
259
+ };
260
+
261
+ const appendSystemNote = (request: any, note: string): any => {
262
+ const existingMessage = request.systemMessage;
263
+ if (existingMessage != null) {
264
+ const separator = existingMessage.text === "" ? "" : "\n\n";
265
+ return {
266
+ ...request,
267
+ systemMessage: existingMessage.concat(`${separator}${note}`),
268
+ };
269
+ }
270
+
271
+ const existing = request.systemPrompt;
272
+ if (existing == null) {
273
+ return { ...request, systemPrompt: note };
274
+ }
275
+ // existing may be a string OR a SystemMessage
276
+ const baseText =
277
+ typeof existing === "string"
278
+ ? existing
279
+ : typeof existing.content === "string"
280
+ ? existing.content
281
+ : String(existing.content);
282
+ return {
283
+ ...request,
284
+ systemPrompt: `${baseText}\n\n${note}`,
285
+ };
286
+ };
287
+
288
+ const applyStateNote = (request: any, expose: ExposeStateOption): any => {
289
+ const note = buildStateNote(
290
+ (request.state ?? {}) as Record<string, unknown>,
291
+ expose,
292
+ );
293
+ return note ? appendSystemNote(request, note) : request;
294
+ };
295
+
296
+ const APP_CONTEXT_PREFIX = "App Context:\n";
297
+
298
+ // LangGraph runtime context carries trusted run configuration (thread, tenant
299
+ // and user ids) that must never reach the model, so only a CopilotKit carrier
300
+ // inside it counts: an "ag-ui" or "copilotkit" namespace, or a legacy
301
+ // unnamespaced carrier with an actions or context key. See #7077.
302
+ const runtimeCarrierProperties = (
303
+ carrier: unknown,
304
+ namespace: "ag-ui" | "copilotkit",
305
+ ): Record<string, unknown> => {
306
+ if (!isPropertyBag(carrier)) return {};
307
+ const nested = carrier[namespace];
308
+ if (isPropertyBag(nested) && Object.keys(nested).length > 0) return nested;
309
+ if (
310
+ namespace === "copilotkit" &&
311
+ ("actions" in carrier || "context" in carrier)
312
+ )
313
+ return carrier;
314
+ return {};
315
+ };
316
+
317
+ // Interception bookkeeping alone does not make a state namespace present.
318
+ const BOOKKEEPING_KEYS = new Set([
319
+ "interceptedToolCalls",
320
+ "originalAIMessageId",
321
+ ]);
322
+
323
+ const definedProperties = (value: unknown): Record<string, unknown> =>
324
+ isPropertyBag(value)
325
+ ? Object.fromEntries(
326
+ Object.entries(value).filter(([, entry]) => entry !== undefined),
327
+ )
328
+ : {};
329
+
330
+ // Each namespace comes from state, or from its runtime carrier when state has
331
+ // none of it. CopilotKit then merges over AG-UI, as in the Python middleware.
332
+ const contextNamespace = (
333
+ state: unknown,
334
+ runtimeContext: unknown,
335
+ namespace: "ag-ui" | "copilotkit",
336
+ ): Record<string, unknown> => {
337
+ const fromState = definedProperties(
338
+ isPropertyBag(state) ? state[namespace] : undefined,
339
+ );
340
+ return Object.keys(fromState).some((key) => !BOOKKEEPING_KEYS.has(key))
341
+ ? fromState
342
+ : definedProperties(runtimeCarrierProperties(runtimeContext, namespace));
343
+ };
344
+
345
+ const buildAppContextNote = (
346
+ state: unknown,
347
+ runtimeContext: unknown,
348
+ ): string | null => {
349
+ const properties = mergeProperties(
350
+ contextNamespace(state, runtimeContext, "ag-ui"),
351
+ contextNamespace(state, runtimeContext, "copilotkit"),
352
+ );
353
+ // Forwarded request headers are transport data, never model context.
354
+ const appContext = isPropertyBag(properties.context)
355
+ ? Object.fromEntries(
356
+ Object.entries(properties.context).filter(
357
+ ([key]) => key !== "copilotkit_forwarded_headers",
358
+ ),
359
+ )
360
+ : properties.context;
361
+
362
+ const isEmptyContext =
363
+ !appContext ||
364
+ (typeof appContext === "string" && appContext.trim() === "") ||
365
+ (typeof appContext === "object" && Object.keys(appContext).length === 0);
366
+ if (isEmptyContext) return null;
367
+
368
+ const contextContent =
369
+ typeof appContext === "string"
370
+ ? appContext
371
+ : JSON.stringify(appContext, null, 2);
372
+ return `${APP_CONTEXT_PREFIX}${contextContent}`;
373
+ };
374
+
375
+ const isAppContextMessage = (msg: any): boolean => {
376
+ const type = msg?._getType?.();
377
+ if (type !== "system" && type !== "developer") return false;
378
+ const content =
379
+ typeof msg.content === "string" ? msg.content : msg.content?.[0]?.text;
380
+ return typeof content === "string" && content.startsWith(APP_CONTEXT_PREFIX);
381
+ };
382
+
383
+ // App context goes into the one leading system message, never a message of its
384
+ // own: Anthropic and Gemini reject a second system message. Older releases
385
+ // wrote an "App Context:" SystemMessage into the thread, so drop any such
386
+ // message from the model's input too.
387
+ const applyAppContextNote = (request: any): any => {
388
+ const messages = request.messages ?? [];
389
+ const keptMessages = messages.filter((msg: any) => !isAppContextMessage(msg));
390
+ if (keptMessages.length !== messages.length) {
391
+ request = { ...request, messages: keptMessages };
392
+ }
393
+
394
+ const note = buildAppContextNote(request.state, request.runtime?.context);
395
+ return note ? appendSystemNote(request, note) : request;
396
+ };
4
397
 
5
398
  /**
6
399
  * CopilotKit Middleware for LangGraph agents.
@@ -23,122 +416,332 @@ import * as z from "zod";
23
416
  * });
24
417
  * ```
25
418
  */
26
- const copilotKitStateSchema = z.object({
27
- copilotkit: z
28
- .object({
29
- actions: z.array(z.any()),
30
- context: z.any().optional(),
31
- interceptedToolCalls: z.array(z.any()).optional(),
32
- originalAIMessageId: z.string().optional(),
33
- })
34
- .optional(),
35
- });
419
+ const copilotKitStateSchema = z
420
+ .object({
421
+ "ag-ui": zodState(z.record(z.string(), z.unknown()).optional()),
422
+ copilotkit: zodState(
423
+ z
424
+ .object({
425
+ actions: z
426
+ .union([z.array(z.any()), z.literal(false)])
427
+ .nullable()
428
+ .optional(),
429
+ context: z.any().optional(),
430
+ interceptedToolCalls: z.array(z.any()).optional(),
431
+ originalAIMessageId: z.string().optional(),
432
+ })
433
+ .passthrough()
434
+ .optional(),
435
+ ),
436
+ })
437
+ .passthrough();
36
438
 
37
- const createCopilotKitMiddleware = () => {
38
- return createMiddleware({
39
- name: "CopilotKitMiddleware",
439
+ const isToolCallContentBlock = (block: unknown) =>
440
+ typeof block === "object" &&
441
+ block !== null &&
442
+ "type" in block &&
443
+ (block.type === "tool_call" || block.type === "tool_call_chunk");
40
444
 
41
- stateSchema: copilotKitStateSchema as unknown as InteropZodObject,
445
+ const usesV1ContentBlocks = (responseMetadata: unknown) =>
446
+ typeof responseMetadata === "object" &&
447
+ responseMetadata !== null &&
448
+ "output_version" in responseMetadata &&
449
+ responseMetadata.output_version === "v1";
42
450
 
43
- // Inject frontend tools before model call
44
- wrapModelCall: async (request, handler) => {
45
- const frontendTools = request.state["copilotkit"]?.actions ?? [];
451
+ /**
452
+ * Rebuilds an AIMessage with `toolCalls` as the source of truth while
453
+ * preserving its non-tool content and metadata. For v1 content blocks, old
454
+ * tool blocks must be removed before construction so they cannot duplicate or
455
+ * override the supplied tool calls when AIMessage synchronizes both fields.
456
+ */
457
+ const rebuildAIMessageWithToolCalls = (
458
+ message: AIMessage,
459
+ toolCalls: AIMessage["tool_calls"],
460
+ ) => {
461
+ let content = message.content;
462
+ if (
463
+ usesV1ContentBlocks(message.response_metadata) &&
464
+ Array.isArray(content)
465
+ ) {
466
+ content = content.filter((block) => !isToolCallContentBlock(block));
467
+ }
46
468
 
47
- if (frontendTools.length === 0) {
48
- return handler(request);
49
- }
469
+ return new AIMessage({
470
+ content,
471
+ additional_kwargs: message.additional_kwargs,
472
+ response_metadata: message.response_metadata,
473
+ tool_calls: toolCalls,
474
+ invalid_tool_calls: message.invalid_tool_calls,
475
+ usage_metadata: message.usage_metadata,
476
+ id: message.id,
477
+ name: message.name,
478
+ });
479
+ };
50
480
 
51
- const existingTools = request.tools || [];
52
- const mergedTools = [...existingTools, ...frontendTools];
481
+ const buildMiddlewareInput = (
482
+ exposeState: ExposeStateOption,
483
+ a2uiParams?: Omit<A2UIToolParams, "model">,
484
+ ) => ({
485
+ name: "CopilotKitMiddleware",
53
486
 
54
- return handler({
55
- ...request,
56
- tools: mergedTools,
57
- });
58
- },
487
+ stateSchema: copilotKitStateSchema as unknown as InteropZodObject,
59
488
 
60
- // Restore frontend tool calls to AIMessage before agent exits
61
- afterAgent: (state) => {
62
- const interceptedToolCalls = state["copilotkit"]?.interceptedToolCalls;
63
- const originalMessageId = state["copilotkit"]?.originalAIMessageId;
489
+ // Inject frontend tools, surface user state and app context, and forward
490
+ // x-aimock-* headers
491
+ wrapModelCall: async (request: any, handler: (req: any) => Promise<any>) => {
492
+ request = applyStateNote(request, exposeState);
493
+ request = applyAppContextNote(request);
64
494
 
65
- if (!interceptedToolCalls?.length || !originalMessageId) {
66
- return;
67
- }
495
+ // Forward x-aimock-* headers from the incoming AG-UI request
496
+ const forwardedHeaders = getForwardedHeaders();
497
+ if (Object.keys(forwardedHeaders).length > 0) {
498
+ const existingSettings = request.modelSettings ?? {};
499
+ const existingHeaders =
500
+ (existingSettings.headers as Record<string, string>) ?? {};
501
+ request = {
502
+ ...request,
503
+ modelSettings: {
504
+ ...existingSettings,
505
+ headers: { ...existingHeaders, ...forwardedHeaders },
506
+ },
507
+ };
508
+ }
68
509
 
69
- let messageFound = false;
70
- const updatedMessages = state.messages.map((msg: any) => {
71
- if (AIMessage.isInstance(msg) && msg.id === originalMessageId) {
72
- messageFound = true;
73
- const existingToolCalls = msg.tool_calls || [];
74
- return new AIMessage({
75
- content: msg.content,
76
- tool_calls: [...existingToolCalls, ...interceptedToolCalls],
77
- id: msg.id,
510
+ // Opt-in auto-injection of generate_a2ui:
511
+ // (1) only inject when the A2UI injectA2UITool flag is truthy (forwarded by
512
+ // @ag-ui/a2ui-middleware and surfaced at state["ag-ui"].inject_a2ui_tool);
513
+ // (2) don't double-inject if the agent already defines this tool.
514
+ // The catalog (when present) only binds surfaces to the FE's catalog; it is
515
+ // not the gate. The model is inferred from request.model; the built tool is
516
+ // stashed for wrapToolCall to execute.
517
+ let a2uiTool: any = null;
518
+ const decision = a2uiInjectDecision(request.state);
519
+ if (typeof getA2UITools === "function" && decision) {
520
+ const catalog = resolveA2uiCatalog(request.state);
521
+ // Shared A2UIToolParams: a single params object owned by the toolkit.
522
+ // Start from the host overrides (guidelines / catalog id / tool name /
523
+ // recovery) so a host can steer the subagent, then layer in only what the
524
+ // host cannot know — the bound model, and the registered catalog id +
525
+ // compositionGuide — without clobbering any host-set value.
526
+ const params: A2UIToolParams = {
527
+ ...a2uiParams,
528
+ model: request.model,
529
+ };
530
+ if (catalog?.catalogId && params.defaultCatalogId == null)
531
+ params.defaultCatalogId = catalog.catalogId;
532
+ // Merge the registered catalog schema into any host `guidelines` bag; a
533
+ // host-set compositionGuide wins, host generation/design overrides stay.
534
+ if (catalog?.compositionGuide) {
535
+ const guidelines = { ...params.guidelines };
536
+ if (guidelines.compositionGuide == null)
537
+ guidelines.compositionGuide = catalog.compositionGuide;
538
+ params.guidelines = guidelines;
539
+ }
540
+ const candidate = getA2UITools(params);
541
+ const existingNames = new Set(
542
+ (request.tools || []).map((t: any) => t?.name),
543
+ );
544
+ if (!existingNames.has(candidate.name)) {
545
+ // ToolNode derives tool runtime state from its config, ignoring an
546
+ // overridden middleware request.state. Adapt the tool's invocation
547
+ // config so the toolkit sees the same effective properties.
548
+ const invoke = candidate.invoke.bind(candidate);
549
+ candidate.invoke = (input, config) => {
550
+ const state =
551
+ config && "state" in config && isPropertyBag(config.state)
552
+ ? config.state
553
+ : request.state;
554
+ const properties = effectiveProperties(state);
555
+ const schema = properties.a2ui_schema;
556
+ const context = decodeCatalogValue(properties.context);
557
+ return invoke(input, {
558
+ ...config,
559
+ state: {
560
+ ...state,
561
+ "ag-ui": {
562
+ ...properties,
563
+ context: Array.isArray(context) ? context : [],
564
+ // The toolkit interpolates the native schema into its prompt.
565
+ a2ui_schema: isPropertyBag(schema)
566
+ ? JSON.stringify(schema)
567
+ : schema,
568
+ },
569
+ },
78
570
  });
79
- }
80
- return msg;
81
- });
82
-
83
- // Only clear intercepted state if we successfully restored the tool calls
84
- if (!messageFound) {
85
- console.warn(
86
- `CopilotKit: Could not find message with id ${originalMessageId} to restore tool calls`,
87
- );
88
- return;
571
+ };
572
+ a2uiTool = candidate;
573
+ a2uiToolsByThread.set(a2uiThreadKey(request.state), a2uiTool);
89
574
  }
575
+ }
90
576
 
91
- return {
92
- messages: updatedMessages,
93
- copilotkit: {
94
- ...(state["copilotkit"] ?? {}),
95
- interceptedToolCalls: undefined,
96
- originalAIMessageId: undefined,
97
- },
98
- };
99
- },
577
+ const actions = effectiveProperties(request.state).actions;
578
+ let frontendTools = Array.isArray(actions) ? actions : [];
579
+ if (a2uiTool) {
580
+ // Our generate_a2ui replaces the runtime's render tool — don't advertise
581
+ // both. Drop the render tool the A2UI middleware injected.
582
+ const drop = typeof decision === "string" ? decision : "render_a2ui";
583
+ frontendTools = frontendTools.filter(
584
+ (t: any) => (t?.function?.name ?? t?.name) !== drop,
585
+ );
586
+ }
587
+
588
+ if (frontendTools.length === 0 && !a2uiTool) {
589
+ return handler(request);
590
+ }
591
+
592
+ const existingTools = request.tools || [];
593
+ const mergedTools = [
594
+ ...existingTools,
595
+ ...(a2uiTool ? [a2uiTool] : []),
596
+ ...frontendTools,
597
+ ];
100
598
 
101
- // Intercept frontend tool calls after model returns, before ToolNode executes
102
- afterModel: (state) => {
103
- const frontendTools = state["copilotkit"]?.actions ?? [];
104
- if (frontendTools.length === 0) return;
599
+ return handler({
600
+ ...request,
601
+ tools: mergedTools,
602
+ });
603
+ },
105
604
 
106
- const frontendToolNames = new Set(frontendTools.map((t: any) => t.function?.name || t.name));
605
+ // Execute the dynamically-advertised generate_a2ui tool. It is not in the
606
+ // agent's static tool registry, so the tool node cannot run it on its own;
607
+ // we supply the implementation (built with the inferred model) for that one
608
+ // tool. This hook's presence also disables createAgent's "unknown tool"
609
+ // guard for dynamically-advertised tools.
610
+ wrapToolCall: async (request: any, handler: (req: any) => Promise<any>) => {
611
+ const tool = a2uiToolsByThread.get(a2uiThreadKey(request.state));
612
+ if (tool && !request.tool && request.toolCall?.name === tool.name) {
613
+ return handler({ ...request, tool });
614
+ }
615
+ return handler(request);
616
+ },
107
617
 
108
- const lastMessage = state.messages[state.messages.length - 1];
109
- if (!AIMessage.isInstance(lastMessage) || !lastMessage.tool_calls?.length) {
110
- return;
618
+ // Restore frontend tool calls to AIMessage before agent exits
619
+ afterAgent: (state) => {
620
+ // Drop the bridged A2UI tool for this run — all tool calls for the turn
621
+ // have executed by now; the next model call re-stashes if needed.
622
+ a2uiToolsByThread.delete(a2uiThreadKey(state));
623
+
624
+ const interceptedToolCalls = state["copilotkit"]?.interceptedToolCalls;
625
+ const originalMessageId = state["copilotkit"]?.originalAIMessageId;
626
+
627
+ if (!interceptedToolCalls?.length || !originalMessageId) {
628
+ return;
629
+ }
630
+
631
+ let messageFound = false;
632
+ const updatedMessages = state.messages.map((msg: any) => {
633
+ if (AIMessage.isInstance(msg) && msg.id === originalMessageId) {
634
+ messageFound = true;
635
+ const existingToolCalls = msg.tool_calls || [];
636
+ return rebuildAIMessageWithToolCalls(msg, [
637
+ ...existingToolCalls,
638
+ ...interceptedToolCalls,
639
+ ]);
111
640
  }
641
+ return msg;
642
+ });
112
643
 
113
- const backendToolCalls: any[] = [];
114
- const frontendToolCalls: any[] = [];
644
+ // Only clear intercepted state if we successfully restored the tool calls
645
+ if (!messageFound) {
646
+ console.warn(
647
+ `CopilotKit: Could not find message with id ${originalMessageId} to restore tool calls`,
648
+ );
649
+ return;
650
+ }
115
651
 
116
- for (const call of lastMessage.tool_calls) {
117
- if (frontendToolNames.has(call.name)) {
118
- frontendToolCalls.push(call);
119
- } else {
120
- backendToolCalls.push(call);
121
- }
652
+ return {
653
+ messages: updatedMessages,
654
+ copilotkit: {
655
+ ...state["copilotkit"],
656
+ interceptedToolCalls: undefined,
657
+ originalAIMessageId: undefined,
658
+ },
659
+ };
660
+ },
661
+
662
+ // Intercept frontend tool calls after model returns, before ToolNode executes
663
+ afterModel: (state) => {
664
+ const actions = effectiveProperties(state).actions;
665
+ const frontendTools = Array.isArray(actions) ? actions : [];
666
+ if (frontendTools.length === 0) return;
667
+
668
+ const frontendToolNames = new Set(
669
+ frontendTools.map((t: any) => t.function?.name || t.name),
670
+ );
671
+
672
+ const lastMessage = state.messages[state.messages.length - 1];
673
+ if (!AIMessage.isInstance(lastMessage) || !lastMessage.tool_calls?.length) {
674
+ return;
675
+ }
676
+
677
+ const backendToolCalls: any[] = [];
678
+ const frontendToolCalls: any[] = [];
679
+
680
+ for (const call of lastMessage.tool_calls) {
681
+ if (frontendToolNames.has(call.name)) {
682
+ frontendToolCalls.push(call);
683
+ } else {
684
+ backendToolCalls.push(call);
122
685
  }
686
+ }
123
687
 
124
- if (frontendToolCalls.length === 0) return;
688
+ if (frontendToolCalls.length === 0) return;
125
689
 
126
- const updatedAIMessage = new AIMessage({
127
- content: lastMessage.content,
128
- tool_calls: backendToolCalls,
129
- id: lastMessage.id,
130
- });
690
+ const updatedAIMessage = rebuildAIMessageWithToolCalls(
691
+ lastMessage,
692
+ backendToolCalls,
693
+ );
131
694
 
132
- return {
133
- messages: [...state.messages.slice(0, -1), updatedAIMessage],
134
- copilotkit: {
135
- ...(state["copilotkit"] ?? {}),
136
- interceptedToolCalls: frontendToolCalls,
137
- originalAIMessageId: lastMessage.id,
138
- },
139
- };
140
- },
141
- });
695
+ return {
696
+ messages: [...state.messages.slice(0, -1), updatedAIMessage],
697
+ copilotkit: {
698
+ ...state["copilotkit"],
699
+ interceptedToolCalls: frontendToolCalls,
700
+ originalAIMessageId: lastMessage.id,
701
+ },
702
+ };
703
+ },
704
+ });
705
+
706
+ /**
707
+ * Build a CopilotKit middleware instance with custom options.
708
+ *
709
+ * Use this when you want to override the default state-exposure behavior
710
+ * (for example to hide a sensitive key, or to use an explicit allowlist), or
711
+ * to steer the auto-injected `generate_a2ui` subagent via `a2uiParams`.
712
+ *
713
+ * `a2uiParams` is an `A2UIToolParams` without `model` (the middleware always
714
+ * injects the bound model). Use it to override the subagent guidelines
715
+ * (`generationGuidelines` / `designGuidelines` / `compositionGuide`),
716
+ * `defaultCatalogId`, `toolName`, `recovery`, etc. on the auto-inject path —
717
+ * which otherwise only ever uses the toolkit defaults. The registered catalog
718
+ * is still folded in, but host-set values win.
719
+ *
720
+ * @example
721
+ * ```typescript
722
+ * import { createCopilotkitMiddleware } from "@copilotkit/sdk-js/langgraph";
723
+ *
724
+ * const middleware = createCopilotkitMiddleware({
725
+ * exposeState: ["liked", "todos"],
726
+ * a2uiParams: { guidelines: { designGuidelines: "...repeating-card layout..." } },
727
+ * });
728
+ * ```
729
+ */
730
+ export const createCopilotkitMiddleware = (
731
+ options: {
732
+ exposeState?: ExposeStateOption;
733
+ a2uiParams?: Omit<A2UIToolParams, "model">;
734
+ } = {},
735
+ ) => {
736
+ const exposeState = options.exposeState ?? false;
737
+ return createMiddleware(
738
+ buildMiddlewareInput(exposeState, options.a2uiParams) as any,
739
+ );
142
740
  };
143
741
 
144
- export const copilotkitMiddleware = createCopilotKitMiddleware();
742
+ /**
743
+ * Default CopilotKit middleware singleton — does NOT surface user state
744
+ * to the LLM. Pass `exposeState: true` (or an allowlist) to
745
+ * {@link createCopilotkitMiddleware} to opt in.
746
+ */
747
+ export const copilotkitMiddleware = createCopilotkitMiddleware();