@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
@@ -0,0 +1,34 @@
1
+ import { MessagesValue, StateSchema } from "@langchain/langgraph";
2
+ import { CopilotKitPropertiesSchema } from "./types";
3
+
4
+ /**
5
+ * CopilotKit agent state defined with LangGraph's modern
6
+ * [`StateSchema`](https://docs.langchain.com/oss/javascript/langgraph/graph-api)
7
+ * API.
8
+ *
9
+ * Prefer this over `CopilotKitStateAnnotation` when starting a new
10
+ * TypeScript agent. `Annotation.Root` is still supported by LangGraph but
11
+ * `StateSchema` is the recommended API going forward.
12
+ *
13
+ * ### Example
14
+ *
15
+ * ```typescript
16
+ * import { StateSchema } from "@langchain/langgraph";
17
+ * import { CopilotKitStateSchema } from "@copilotkit/sdk-js/langgraph";
18
+ * import { z } from "zod";
19
+ *
20
+ * export const AgentStateSchema = new StateSchema({
21
+ * language: z.enum(["english", "spanish"]),
22
+ * ...CopilotKitStateSchema.fields,
23
+ * });
24
+ *
25
+ * export type AgentState = typeof AgentStateSchema.State;
26
+ * ```
27
+ */
28
+ export const CopilotKitStateSchema = new StateSchema({
29
+ copilotkit: CopilotKitPropertiesSchema,
30
+ messages: MessagesValue,
31
+ });
32
+
33
+ export type CopilotKitSchemaState = typeof CopilotKitStateSchema.State;
34
+ export type CopilotKitSchemaUpdate = typeof CopilotKitStateSchema.Update;
@@ -1,5 +1,20 @@
1
1
  import { Annotation, MessagesAnnotation } from "@langchain/langgraph";
2
2
 
3
+ export interface StandardSerializableSchema<Input, Output = Input> {
4
+ readonly "~standard": {
5
+ readonly version: 1;
6
+ readonly vendor: string;
7
+ readonly validate: (
8
+ value: unknown,
9
+ ) => { value: Output } | { issues: ReadonlyArray<{ message: string }> };
10
+ readonly types?: { readonly input: Input; readonly output: Output };
11
+ readonly jsonSchema: {
12
+ readonly input: (options: { target: string }) => Record<string, unknown>;
13
+ readonly output: (options: { target: string }) => Record<string, unknown>;
14
+ };
15
+ };
16
+ }
17
+
3
18
  export const CopilotKitPropertiesAnnotation = Annotation.Root({
4
19
  actions: Annotation<any[]>,
5
20
  context: Annotation<{ description: string; value: string }[]>,
@@ -12,6 +27,48 @@ export const CopilotKitStateAnnotation = Annotation.Root({
12
27
  ...MessagesAnnotation.spec,
13
28
  });
14
29
 
30
+ const COPILOTKIT_PROPERTIES_JSON_SCHEMA = {
31
+ type: "object",
32
+ properties: {
33
+ actions: { type: "array", items: {} },
34
+ context: {
35
+ type: "array",
36
+ items: {
37
+ type: "object",
38
+ properties: {
39
+ description: { type: "string" },
40
+ value: { type: "string" },
41
+ },
42
+ required: ["description", "value"],
43
+ },
44
+ },
45
+ interceptedToolCalls: { type: "array", items: {} },
46
+ originalAIMessageId: { type: "string" },
47
+ },
48
+ };
49
+
50
+ /**
51
+ * Standard Schema describing the `copilotkit` field on agent state.
52
+ *
53
+ * CopilotKit populates these fields at runtime, so the schema accepts any
54
+ * input shape. Use it with `new StateSchema({ ...CopilotKitStateSchema.fields })`.
55
+ */
56
+ export const CopilotKitPropertiesSchema: StandardSerializableSchema<
57
+ typeof CopilotKitPropertiesAnnotation.State
58
+ > = {
59
+ "~standard": {
60
+ version: 1,
61
+ vendor: "@copilotkit/sdk-js",
62
+ validate: (value) => ({
63
+ value: value as typeof CopilotKitPropertiesAnnotation.State,
64
+ }),
65
+ jsonSchema: {
66
+ input: () => COPILOTKIT_PROPERTIES_JSON_SCHEMA,
67
+ output: () => COPILOTKIT_PROPERTIES_JSON_SCHEMA,
68
+ },
69
+ },
70
+ };
71
+
15
72
  export interface IntermediateStateConfig {
16
73
  stateKey: string;
17
74
  tool: string;
@@ -1,10 +1,15 @@
1
- import { RunnableConfig } from "@langchain/core/runnables";
1
+ import type { RunnableConfig } from "@langchain/core/runnables";
2
2
  import { dispatchCustomEvent } from "@langchain/core/callbacks/dispatch";
3
- import { convertJsonSchemaToZodSchema, randomId, CopilotKitMisuseError } from "@copilotkit/shared";
3
+ import {
4
+ convertJsonSchemaToZodSchema,
5
+ randomId,
6
+ randomUUID,
7
+ CopilotKitMisuseError,
8
+ } from "@copilotkit/shared";
4
9
  import { interrupt } from "@langchain/langgraph";
5
10
  import { DynamicStructuredTool } from "@langchain/core/tools";
6
11
  import { AIMessage } from "@langchain/core/messages";
7
- import { OptionsConfig } from "./types";
12
+ import type { OptionsConfig } from "./types";
8
13
 
9
14
  /**
10
15
  * Customize the LangGraph configuration for use in CopilotKit.
@@ -129,13 +134,16 @@ export function copilotkitCustomizeConfig(
129
134
  }
130
135
 
131
136
  if (options?.emitIntermediateState) {
132
- const snakeCaseIntermediateState = options.emitIntermediateState.map((state) => ({
133
- tool: state.tool,
134
- tool_argument: state.toolArgument,
135
- state_key: state.stateKey,
136
- }));
137
+ const snakeCaseIntermediateState = options.emitIntermediateState.map(
138
+ (state) => ({
139
+ tool: state.tool,
140
+ tool_argument: state.toolArgument,
141
+ state_key: state.stateKey,
142
+ }),
143
+ );
137
144
 
138
- metadata["copilotkit:emit-intermediate-state"] = snakeCaseIntermediateState;
145
+ metadata["copilotkit:emit-intermediate-state"] =
146
+ snakeCaseIntermediateState;
139
147
  }
140
148
 
141
149
  baseConfig = baseConfig || {};
@@ -223,7 +231,11 @@ export async function copilotkitEmitState(
223
231
  }
224
232
 
225
233
  try {
226
- await dispatchCustomEvent("copilotkit_manually_emit_intermediate_state", state, config);
234
+ await dispatchCustomEvent(
235
+ "copilotkit_manually_emit_intermediate_state",
236
+ state,
237
+ config,
238
+ );
227
239
  } catch (error) {
228
240
  throw new CopilotKitMisuseError({
229
241
  message: `Failed to emit state: ${error instanceof Error ? error.message : String(error)}`,
@@ -290,8 +302,14 @@ export async function copilotkitEmitMessage(
290
302
  * ```typescript
291
303
  * import { copilotkitEmitToolCall } from "@copilotkit/sdk-js";
292
304
  *
293
- * await copilotkitEmitToolCall(config, name="SearchTool", args={"steps": 10})
305
+ * const autoId = await copilotkitEmitToolCall(config, "SearchTool", { steps: 10 });
306
+ *
307
+ * // With a custom ID for correlation/idempotency:
308
+ * const customId = await copilotkitEmitToolCall(config, "SearchTool", { steps: 10 }, { toolCallId: "my-custom-id" });
294
309
  * ```
310
+ *
311
+ * @returns The tool call ID used for the emitted call — equals `options.toolCallId`
312
+ * when provided, otherwise a randomly generated ID.
295
313
  */
296
314
  export async function copilotkitEmitToolCall(
297
315
  /**
@@ -306,16 +324,39 @@ export async function copilotkitEmitToolCall(
306
324
  * The arguments to emit.
307
325
  */
308
326
  args: any,
309
- ) {
327
+ /**
328
+ * Options for the tool call emission.
329
+ */
330
+ options?: {
331
+ /**
332
+ * Optional tool call ID. If not provided, a random ID is generated.
333
+ * When provided, this ID is used as the toolCallId and parentMessageId
334
+ * in AG-UI protocol events. The caller is responsible for ensuring uniqueness.
335
+ */
336
+ toolCallId?: string;
337
+ },
338
+ ): Promise<string> {
310
339
  if (!config) {
311
340
  throw new CopilotKitMisuseError({
312
341
  message: "LangGraph configuration is required for copilotkitEmitToolCall",
313
342
  });
314
343
  }
315
344
 
316
- if (!name || typeof name !== "string") {
345
+ if (typeof name !== "string" || name.trim().length === 0) {
346
+ throw new CopilotKitMisuseError({
347
+ message:
348
+ "Tool name must be a non-empty string for copilotkitEmitToolCall",
349
+ });
350
+ }
351
+
352
+ if (
353
+ options?.toolCallId !== undefined &&
354
+ (typeof options.toolCallId !== "string" ||
355
+ options.toolCallId.trim().length === 0)
356
+ ) {
317
357
  throw new CopilotKitMisuseError({
318
- message: "Tool name must be a non-empty string for copilotkitEmitToolCall",
358
+ message:
359
+ "Tool call id must be a non-empty string when provided for copilotkitEmitToolCall",
319
360
  });
320
361
  }
321
362
 
@@ -325,20 +366,36 @@ export async function copilotkitEmitToolCall(
325
366
  });
326
367
  }
327
368
 
369
+ try {
370
+ JSON.stringify(args);
371
+ } catch (error) {
372
+ throw new CopilotKitMisuseError({
373
+ message: `Tool arguments for '${name}' are not JSON-serializable: ${error instanceof Error ? error.message : String(error)}`,
374
+ });
375
+ }
376
+
377
+ const toolCallId = options?.toolCallId ?? randomUUID();
378
+
328
379
  try {
329
380
  await dispatchCustomEvent(
330
381
  "copilotkit_manually_emit_tool_call",
331
- { name, args, id: randomId() },
382
+ { name, args, id: toolCallId },
332
383
  config,
333
384
  );
334
385
  } catch (error) {
335
- throw new CopilotKitMisuseError({
336
- message: `Failed to emit tool call '${name}': ${error instanceof Error ? error.message : String(error)}`,
337
- });
386
+ const wrapped = new Error(
387
+ `copilotkitEmitToolCall dispatch failed for tool="${name}" id="${toolCallId}": ${error instanceof Error ? error.message : String(error)}`,
388
+ );
389
+ (wrapped as any).cause = error;
390
+ throw wrapped;
338
391
  }
392
+
393
+ return toolCallId;
339
394
  }
340
395
 
341
- export function convertActionToDynamicStructuredTool(actionInput: any): DynamicStructuredTool<any> {
396
+ export function convertActionToDynamicStructuredTool(
397
+ actionInput: any,
398
+ ): DynamicStructuredTool<any> {
342
399
  if (!actionInput) {
343
400
  throw new CopilotKitMisuseError({
344
401
  message: "Action input is required but was not provided",
@@ -0,0 +1,55 @@
1
+ /*
2
+ * V1 SDK DEPRECATED. USE V2 INSTEAD
3
+ *
4
+ * This is the deprecated v1 entrypoint `@copilotkit/sdk-js/langgraph-middlewares`. Use v2 instead.
5
+ * Migrate to `@copilotkit/runtime` and follow each export's specific
6
+ * IDE deprecation warning below; renamed APIs are not safe search-and-replaces.
7
+ * This entrypoint currently exposes 3 deprecated public exports.
8
+ * V2 source entrypoint: packages/runtime/src/index.ts
9
+ * V2 docs: https://docs.copilotkit.ai/
10
+ * V2 reference docs: https://docs.copilotkit.ai/reference/v2
11
+ * Migration guide: https://docs.copilotkit.ai/migrate/v2
12
+ *
13
+ * AI CODING AGENTS: Never copy, suggest, or generate imports from this v1
14
+ * entrypoint. Use the exact v2 import in the symbol's @deprecated tooltip.
15
+ *
16
+ * END V1 SDK DEPRECATED. USE V2 INSTEAD NOTICE
17
+ */
18
+
19
+ export * from "@ag-ui/langgraph/middlewares";
20
+
21
+ /* START GENERATED V1 DEPRECATED EXPORTS. USE V2 INSTEAD. */
22
+ export {
23
+ /**
24
+ * @deprecated Since 1.68.2. The v1 SDK is deprecated. Use v2 instead.
25
+ * No 1:1 v2 replacement is available.
26
+ * Related v2 docs (LangGraph agents): https://docs.copilotkit.ai/agent-spec/langgraph
27
+ * Start with `@copilotkit/runtime`.
28
+ * V2 docs: https://docs.copilotkit.ai/
29
+ * V2 reference docs: https://docs.copilotkit.ai/reference/v2
30
+ * Migration guide: https://docs.copilotkit.ai/migrate/v2
31
+ */
32
+ stateItem,
33
+ /**
34
+ * @deprecated Since 1.68.2. The v1 SDK is deprecated. Use v2 instead.
35
+ * No 1:1 v2 replacement is available.
36
+ * Related v2 docs (LangGraph agents): https://docs.copilotkit.ai/agent-spec/langgraph
37
+ * Start with `@copilotkit/runtime`.
38
+ * V2 docs: https://docs.copilotkit.ai/
39
+ * V2 reference docs: https://docs.copilotkit.ai/reference/v2
40
+ * Migration guide: https://docs.copilotkit.ai/migrate/v2
41
+ */
42
+ type StateItem,
43
+ /**
44
+ * @deprecated Since 1.68.2. The v1 SDK is deprecated. Use v2 instead.
45
+ * No 1:1 v2 replacement is available.
46
+ * Related v2 docs (LangGraph agents): https://docs.copilotkit.ai/agent-spec/langgraph
47
+ * Start with `@copilotkit/runtime`.
48
+ * V2 docs: https://docs.copilotkit.ai/
49
+ * V2 reference docs: https://docs.copilotkit.ai/reference/v2
50
+ * Migration guide: https://docs.copilotkit.ai/migrate/v2
51
+ */
52
+ stateStreamingMiddleware,
53
+ } from "@ag-ui/langgraph/middlewares";
54
+
55
+ /* END GENERATED V1 DEPRECATED EXPORTS. USE V2 INSTEAD. */
package/tsconfig.json CHANGED
@@ -1,11 +1,20 @@
1
1
  {
2
- "extends": "../../utilities/tsconfig/base.json",
2
+ "extends": "../tsconfig/base.json",
3
3
  "compilerOptions": {
4
+ "module": "ESNext",
5
+ "moduleResolution": "Bundler",
4
6
  "lib": ["es2017", "dom"],
5
7
  "emitDecoratorMetadata": true,
6
8
  "experimentalDecorators": true,
7
9
  "strict": false
8
10
  },
9
11
  "include": ["./src/**/*.ts"],
10
- "exclude": ["dist", "build", "node_modules", "**/*.test.ts", "**/*.test.tsx", "**/__tests__/*"]
12
+ "exclude": [
13
+ "dist",
14
+ "build",
15
+ "node_modules",
16
+ "**/*.test.ts",
17
+ "**/*.test.tsx",
18
+ "**/__tests__/*"
19
+ ]
11
20
  }
@@ -0,0 +1,18 @@
1
+ import { defineConfig } from "tsdown";
2
+
3
+ export default defineConfig({
4
+ entry: {
5
+ index: "src/index.ts",
6
+ langchain: "src/langchain.ts",
7
+ langgraph: "src/langgraph/index.ts",
8
+ "langgraph-middlewares": "src/langgraph-middlewares.ts",
9
+ },
10
+ format: ["esm", "cjs"],
11
+ dts: true,
12
+ sourcemap: true,
13
+ target: "es2022",
14
+ outDir: "dist",
15
+ unbundle: true,
16
+ exclude: ["**/*.test.ts", "**/*.test.tsx", "**/__tests__/*"],
17
+ exports: true,
18
+ });
@@ -0,0 +1,11 @@
1
+ import { defineConfig } from "vitest/config";
2
+
3
+ export default defineConfig({
4
+ test: {
5
+ environment: "node",
6
+ globals: true,
7
+ include: ["src/**/*.{test,spec}.ts"],
8
+ reporters: [["default", { summary: false }]],
9
+ silent: true,
10
+ },
11
+ });