@copilotkit/sdk-js 2.0.0-next.1 → 2.0.0-rc.1
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.
- package/LICENSE +21 -0
- package/README.md +0 -1
- package/dist/_virtual/_rolldown/runtime.cjs +29 -0
- package/dist/header-propagation.cjs +37 -0
- package/dist/header-propagation.cjs.map +1 -0
- package/dist/header-propagation.d.cts +16 -0
- package/dist/header-propagation.d.cts.map +1 -0
- package/dist/header-propagation.d.mts +16 -0
- package/dist/header-propagation.d.mts.map +1 -0
- package/dist/header-propagation.mjs +35 -0
- package/dist/header-propagation.mjs.map +1 -0
- package/dist/index.cjs +5 -0
- package/dist/index.d.cts +18 -0
- package/dist/index.d.mts +18 -0
- package/dist/index.mjs +3 -1
- package/dist/langchain.cjs +21 -0
- package/dist/langchain.cjs.map +1 -0
- package/dist/langchain.d.cts +139 -0
- package/dist/langchain.d.mts +140 -0
- package/dist/langchain.mjs +7 -23
- package/dist/langchain.mjs.map +1 -1
- package/dist/langgraph/middleware.cjs +433 -0
- package/dist/langgraph/middleware.cjs.map +1 -0
- package/dist/langgraph/middleware.d.cts +86 -0
- package/dist/langgraph/middleware.d.cts.map +1 -0
- package/dist/langgraph/middleware.d.mts +86 -0
- package/dist/langgraph/middleware.d.mts.map +1 -0
- package/dist/langgraph/middleware.mjs +429 -0
- package/dist/langgraph/middleware.mjs.map +1 -0
- package/dist/langgraph/state-schema.cjs +37 -0
- package/dist/langgraph/state-schema.cjs.map +1 -0
- package/dist/langgraph/state-schema.d.cts +118 -0
- package/dist/langgraph/state-schema.d.cts.map +1 -0
- package/dist/langgraph/state-schema.d.mts +118 -0
- package/dist/langgraph/state-schema.d.mts.map +1 -0
- package/dist/langgraph/state-schema.mjs +36 -0
- package/dist/langgraph/state-schema.mjs.map +1 -0
- package/dist/langgraph/types.cjs +60 -0
- package/dist/langgraph/types.cjs.map +1 -0
- package/dist/langgraph/types.d.cts +335 -0
- package/dist/langgraph/types.d.cts.map +1 -0
- package/dist/langgraph/types.d.mts +335 -0
- package/dist/langgraph/types.d.mts.map +1 -0
- package/dist/langgraph/types.mjs +57 -0
- package/dist/langgraph/types.mjs.map +1 -0
- package/dist/langgraph/utils.cjs +297 -0
- package/dist/langgraph/utils.cjs.map +1 -0
- package/dist/langgraph/utils.d.cts +209 -0
- package/dist/langgraph/utils.d.cts.map +1 -0
- package/dist/langgraph/utils.d.mts +209 -0
- package/dist/langgraph/utils.d.mts.map +1 -0
- package/dist/langgraph/utils.mjs +289 -0
- package/dist/langgraph/utils.mjs.map +1 -0
- package/dist/langgraph-middlewares.cjs +22 -0
- package/dist/langgraph-middlewares.d.cts +30 -0
- package/dist/langgraph-middlewares.d.mts +30 -0
- package/dist/langgraph-middlewares.mjs +5 -0
- package/dist/langgraph.cjs +21 -0
- package/dist/langgraph.d.cts +5 -0
- package/dist/langgraph.d.mts +5 -0
- package/dist/langgraph.mjs +6 -27
- package/package.json +50 -47
- package/src/__tests__/error-handling.test.ts +54 -20
- package/src/__tests__/header-propagation.test.ts +131 -0
- package/src/header-propagation.ts +61 -0
- package/src/index.ts +41 -0
- package/src/langchain.ts +168 -8
- package/src/langgraph/__tests__/middleware.a2ui-params.test.ts +139 -0
- package/src/langgraph/__tests__/middleware.native-a2ui.test.ts +118 -0
- package/src/langgraph/__tests__/middleware.properties.test.ts +357 -0
- package/src/langgraph/__tests__/middleware.test.ts +1141 -0
- package/src/langgraph/__tests__/state-schema.test.ts +85 -0
- package/src/langgraph/__tests__/utils.test.ts +363 -0
- package/src/langgraph/index.ts +1 -0
- package/src/langgraph/middleware.ts +698 -95
- package/src/langgraph/state-schema.ts +34 -0
- package/src/langgraph/types.ts +57 -0
- package/src/langgraph/utils.ts +76 -19
- package/src/langgraph-middlewares.ts +55 -0
- package/tsconfig.json +11 -2
- package/tsdown.config.ts +18 -0
- package/vitest.config.mjs +11 -0
- package/CHANGELOG.md +0 -2169
- package/dist/chunk-JLGOQLGS.mjs +0 -433
- package/dist/chunk-JLGOQLGS.mjs.map +0 -1
- package/dist/index.d.ts +0 -2
- package/dist/index.js +0 -1
- package/dist/index.js.map +0 -1
- package/dist/index.mjs.map +0 -1
- package/dist/langchain-2645763d.d.ts +0 -427
- package/dist/langchain.d.ts +0 -6
- package/dist/langchain.js +0 -284
- package/dist/langchain.js.map +0 -1
- package/dist/langgraph/index.d.ts +0 -11
- package/dist/langgraph.js +0 -476
- package/dist/langgraph.js.map +0 -1
- package/dist/langgraph.mjs.map +0 -1
- package/jest.config.js +0 -5
- 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
|
|
27
|
-
|
|
28
|
-
.
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
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
|
|
38
|
-
|
|
39
|
-
|
|
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
|
-
|
|
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
|
-
|
|
44
|
-
|
|
45
|
-
|
|
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
|
-
|
|
48
|
-
|
|
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
|
-
|
|
52
|
-
|
|
481
|
+
const buildMiddlewareInput = (
|
|
482
|
+
exposeState: ExposeStateOption,
|
|
483
|
+
a2uiParams?: Omit<A2UIToolParams, "model">,
|
|
484
|
+
) => ({
|
|
485
|
+
name: "CopilotKitMiddleware",
|
|
53
486
|
|
|
54
|
-
|
|
55
|
-
...request,
|
|
56
|
-
tools: mergedTools,
|
|
57
|
-
});
|
|
58
|
-
},
|
|
487
|
+
stateSchema: copilotKitStateSchema as unknown as InteropZodObject,
|
|
59
488
|
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
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
|
-
|
|
66
|
-
|
|
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
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
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
|
-
|
|
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
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
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
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
599
|
+
return handler({
|
|
600
|
+
...request,
|
|
601
|
+
tools: mergedTools,
|
|
602
|
+
});
|
|
603
|
+
},
|
|
105
604
|
|
|
106
|
-
|
|
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
|
-
|
|
109
|
-
|
|
110
|
-
|
|
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
|
-
|
|
114
|
-
|
|
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
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
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
|
-
|
|
688
|
+
if (frontendToolCalls.length === 0) return;
|
|
125
689
|
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
});
|
|
690
|
+
const updatedAIMessage = rebuildAIMessageWithToolCalls(
|
|
691
|
+
lastMessage,
|
|
692
|
+
backendToolCalls,
|
|
693
|
+
);
|
|
131
694
|
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
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
|
-
|
|
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();
|