@copilotkit/sdk-js 1.56.2 → 1.56.4-canary.1777529757

package/src/langgraph/__tests__/utils.test.ts

@@ -0,0 +1,254 @@
+import {
+  copilotkitCustomizeConfig,
+  convertActionsToDynamicStructuredTools,
+  convertActionToDynamicStructuredTool,
+} from "../utils";
+
+describe("copilotkitCustomizeConfig", () => {
+  it("returns config unchanged when no options provided", () => {
+    const baseConfig = { metadata: { existing: true } };
+    const result = copilotkitCustomizeConfig(baseConfig);
+    expect(result.metadata).toEqual({ existing: true });
+  });
+
+  it("returns config unchanged when options is empty object", () => {
+    const baseConfig = { metadata: {} };
+    const result = copilotkitCustomizeConfig(baseConfig, {});
+    expect(result.metadata).toEqual({});
+  });
+
+  it("sets emit-messages metadata flag to false", () => {
+    const result = copilotkitCustomizeConfig({}, { emitMessages: false });
+    expect(result.metadata!["copilotkit:emit-messages"]).toBe(false);
+  });
+
+  it("sets emit-messages metadata flag to true", () => {
+    const result = copilotkitCustomizeConfig({}, { emitMessages: true });
+    expect(result.metadata!["copilotkit:emit-messages"]).toBe(true);
+  });
+
+  it("sets emit-tool-calls metadata flag to false", () => {
+    const result = copilotkitCustomizeConfig({}, { emitToolCalls: false });
+    expect(result.metadata!["copilotkit:emit-tool-calls"]).toBe(false);
+  });
+
+  it("sets emit-tool-calls to a specific tool name string", () => {
+    const result = copilotkitCustomizeConfig(
+      {},
+      { emitToolCalls: "SearchTool" },
+    );
+    expect(result.metadata!["copilotkit:emit-tool-calls"]).toBe("SearchTool");
+  });
+
+  it("sets emit-tool-calls to an array of tool names", () => {
+    const result = copilotkitCustomizeConfig(
+      {},
+      { emitToolCalls: ["SearchTool", "FetchTool"] },
+    );
+    expect(result.metadata!["copilotkit:emit-tool-calls"]).toEqual([
+      "SearchTool",
+      "FetchTool",
+    ]);
+  });
+
+  it("sets both emit flags together", () => {
+    const result = copilotkitCustomizeConfig(
+      {},
+      {
+        emitMessages: false,
+        emitToolCalls: false,
+      },
+    );
+    expect(result.metadata!["copilotkit:emit-messages"]).toBe(false);
+    expect(result.metadata!["copilotkit:emit-tool-calls"]).toBe(false);
+  });
+
+  it("emitAll sets both messages and tool-calls to true", () => {
+    const result = copilotkitCustomizeConfig({}, { emitAll: true });
+    expect(result.metadata!["copilotkit:emit-messages"]).toBe(true);
+    expect(result.metadata!["copilotkit:emit-tool-calls"]).toBe(true);
+  });
+
+  it("converts emitIntermediateState to snake_case in metadata", () => {
+    const result = copilotkitCustomizeConfig(
+      {},
+      {
+        emitIntermediateState: [
+          { stateKey: "steps", tool: "SearchTool", toolArgument: "steps" },
+        ],
+      },
+    );
+    const intermediateState =
+      result.metadata!["copilotkit:emit-intermediate-state"];
+    expect(intermediateState).toHaveLength(1);
+    expect(intermediateState[0]).toEqual({
+      state_key: "steps",
+      tool: "SearchTool",
+      tool_argument: "steps",
+    });
+  });
+
+  it("handles emitIntermediateState without toolArgument", () => {
+    const result = copilotkitCustomizeConfig(
+      {},
+      {
+        emitIntermediateState: [{ stateKey: "output", tool: "WriteTool" }],
+      },
+    );
+    const intermediateState =
+      result.metadata!["copilotkit:emit-intermediate-state"];
+    expect(intermediateState[0]).toEqual({
+      state_key: "output",
+      tool: "WriteTool",
+      tool_argument: undefined,
+    });
+  });
+
+  it("throws when emitIntermediateState item is missing stateKey", () => {
+    expect(() => {
+      copilotkitCustomizeConfig(
+        {},
+        {
+          emitIntermediateState: [{ tool: "SearchTool" } as any],
+        },
+      );
+    }).toThrow("stateKey");
+  });
+
+  it("throws when emitIntermediateState item is missing tool", () => {
+    expect(() => {
+      copilotkitCustomizeConfig(
+        {},
+        {
+          emitIntermediateState: [{ stateKey: "steps" } as any],
+        },
+      );
+    }).toThrow("tool");
+  });
+
+  it("preserves existing metadata from baseConfig", () => {
+    const result = copilotkitCustomizeConfig(
+      { metadata: { "custom-key": "custom-value" } },
+      { emitMessages: false },
+    );
+    expect(result.metadata!["custom-key"]).toBe("custom-value");
+    expect(result.metadata!["copilotkit:emit-messages"]).toBe(false);
+  });
+
+  it("handles null/undefined baseConfig gracefully", () => {
+    const result = copilotkitCustomizeConfig(null as any, {
+      emitMessages: false,
+    });
+    expect(result.metadata!["copilotkit:emit-messages"]).toBe(false);
+  });
+});
+
+describe("convertActionToDynamicStructuredTool", () => {
+  it("converts a valid action to DynamicStructuredTool", () => {
+    const action = {
+      name: "myTool",
+      description: "A test tool",
+      parameters: {
+        type: "object",
+        properties: {
+          query: { type: "string" },
+        },
+      },
+    };
+    const tool = convertActionToDynamicStructuredTool(action);
+    expect(tool.name).toBe("myTool");
+    expect(tool.description).toBe("A test tool");
+  });
+
+  it("throws when actionInput is null", () => {
+    expect(() => convertActionToDynamicStructuredTool(null)).toThrow(
+      "Action input is required",
+    );
+  });
+
+  it("throws when name is missing", () => {
+    expect(() =>
+      convertActionToDynamicStructuredTool({
+        description: "test",
+        parameters: {},
+      }),
+    ).toThrow("name");
+  });
+
+  it("throws when description is missing", () => {
+    expect(() =>
+      convertActionToDynamicStructuredTool({ name: "test", parameters: {} }),
+    ).toThrow("description");
+  });
+
+  it("throws when parameters is missing", () => {
+    expect(() =>
+      convertActionToDynamicStructuredTool({
+        name: "test",
+        description: "test",
+      }),
+    ).toThrow("parameters");
+  });
+});
+
+describe("convertActionsToDynamicStructuredTools", () => {
+  it("converts multiple actions", () => {
+    const actions = [
+      {
+        name: "tool1",
+        description: "First tool",
+        parameters: { type: "object", properties: {} },
+      },
+      {
+        name: "tool2",
+        description: "Second tool",
+        parameters: { type: "object", properties: {} },
+      },
+    ];
+    const tools = convertActionsToDynamicStructuredTools(actions);
+    expect(tools).toHaveLength(2);
+    expect(tools[0].name).toBe("tool1");
+    expect(tools[1].name).toBe("tool2");
+  });
+
+  it("returns empty array for empty input", () => {
+    const tools = convertActionsToDynamicStructuredTools([]);
+    expect(tools).toEqual([]);
+  });
+
+  it("handles { type: 'function', function: {...} } format", () => {
+    const actions = [
+      {
+        type: "function",
+        function: {
+          name: "wrappedTool",
+          description: "A wrapped tool",
+          parameters: { type: "object", properties: {} },
+        },
+      },
+    ];
+    const tools = convertActionsToDynamicStructuredTools(actions);
+    expect(tools).toHaveLength(1);
+    expect(tools[0].name).toBe("wrappedTool");
+  });
+
+  it("throws when input is not an array", () => {
+    expect(() =>
+      convertActionsToDynamicStructuredTools("not-array" as any),
+    ).toThrow("Actions must be an array");
+  });
+
+  it("wraps individual action errors with index info", () => {
+    const actions = [
+      {
+        name: "goodTool",
+        description: "works",
+        parameters: { type: "object", properties: {} },
+      },
+      { name: "badTool" }, // missing description and parameters
+    ];
+    expect(() => convertActionsToDynamicStructuredTools(actions)).toThrow(
+      "index 1",
+    );
+  });
+});

package/src/langgraph/index.ts

@@ -1,3 +1,4 @@
 export * from "./types";
 export * from "./utils";
 export * from "./middleware";
+export * from "./state-schema";

package/src/langgraph/middleware.ts

@@ -1,7 +1,175 @@
 import { createMiddleware, AIMessage, SystemMessage } from "langchain";
 import type { InteropZodObject } from "@langchain/core/utils/types";
+import type {
+  StandardJSONSchemaV1,
+  StandardSchemaV1,
+} from "@standard-schema/spec";
 import * as z from "zod";
 
+type WithJsonSchema<T> = T extends { "~standard": infer S }
+  ? Omit<T, "~standard"> & {
+      "~standard": S &
+        StandardJSONSchemaV1.Props<
+          S extends StandardSchemaV1.Props<infer I, any> ? I : unknown,
+          S extends StandardSchemaV1.Props<any, infer O> ? O : unknown
+        >;
+    }
+  : T;
+
+/**
+ * Augment a Standard-Schema–compatible schema (e.g. Zod) with a
+ * `~standard.jsonSchema.input` hook so LangGraph's
+ * `getJsonSchemaFromSchema` (called from `StateSchema.getJsonSchema`)
+ * can serialize the field.
+ *
+ * Without this, Zod v4 fields carry `~standard.validate` + `vendor` only,
+ * and `isStandardJSONSchema()` returns false, so the field is silently
+ * dropped from the graph's `output_schema`. That makes AG-UI
+ * `STATE_SNAPSHOT` events filter the field out of the payload sent to
+ * the frontend even though the underlying thread state has the value.
+ *
+ * Use this on any custom state field you want visible to the frontend
+ * via `useAgent().state.*`.
+ *
+ * @example
+ * ```ts
+ * import { zodState } from "@copilotkit/sdk-js/langgraph";
+ *
+ * const stateSchema = z.object({
+ *   todos: zodState(z.array(TodoSchema).default(() => [])),
+ * });
+ * ```
+ */
+export function zodState<T extends object>(schema: T): WithJsonSchema<T> {
+  const std = (schema as { "~standard"?: { jsonSchema?: unknown } })[
+    "~standard"
+  ];
+  if (std && typeof std === "object" && !("jsonSchema" in std)) {
+    let cached: Record<string, unknown> | undefined;
+    std.jsonSchema = {
+      input: () => {
+        if (cached) return cached;
+        // Prefer zod-v4's native `toJSONSchema` when available. Falls back to
+        // an empty object, which is sufficient for the field to appear in the
+        // graph's output_schema (langgraph-api treats it as an opaque field).
+        try {
+          const maybeV4ToJsonSchema = (
+            z as unknown as {
+              toJSONSchema?: (s: unknown) => Record<string, unknown>;
+            }
+          ).toJSONSchema;
+          cached =
+            typeof maybeV4ToJsonSchema === "function"
+              ? maybeV4ToJsonSchema(schema)
+              : {};
+        } catch {
+          cached = {};
+        }
+        return cached;
+      },
+    };
+  }
+  return schema as WithJsonSchema<T>;
+}
+
+/**
+ * Internal/framework state keys that should never be auto-surfaced to the
+ * LLM as user-facing state. These are reducer-managed message buckets,
+ * CopilotKit/AG-UI plumbing, or graph-internal scaffolding.
+ */
+const RESERVED_STATE_KEYS: ReadonlySet<string> = new Set([
+  "messages",
+  "copilotkit",
+  "ag-ui",
+  "tools",
+  "structured_response",
+  "thread_id",
+  "remaining_steps",
+]);
+
+/**
+ * Controls how user-defined state keys are surfaced into the LLM prompt
+ * on every model call. Off by default to avoid leaking arbitrary state
+ * into prompts; opt in explicitly.
+ *
+ * - `false` (default) — never surface state.
+ * - `true` — every state key not in the reserved internal set and not
+ *   prefixed with `_` is JSON-serialized into a "Current agent state:"
+ *   note appended to the system prompt.
+ * - `string[]` — only surface the named keys (use this when you want
+ *   explicit control over what the LLM sees, e.g. `["liked", "todos"]`).
+ */
+export type ExposeStateOption = boolean | readonly string[];
+
+const buildStateNote = (
+  state: Record<string, unknown>,
+  expose: ExposeStateOption,
+): string | null => {
+  if (expose === false) return null;
+
+  const allow: ReadonlySet<string> | null = Array.isArray(expose)
+    ? new Set(expose)
+    : null;
+
+  const snapshot: Record<string, unknown> = {};
+  for (const key of Object.keys(state)) {
+    if (
+      allow
+        ? !allow.has(key)
+        : RESERVED_STATE_KEYS.has(key) || key.startsWith("_")
+    ) {
+      continue;
+    }
+    const value = state[key];
+    if (
+      value === undefined ||
+      value === null ||
+      value === "" ||
+      (Array.isArray(value) && value.length === 0) ||
+      (typeof value === "object" &&
+        !Array.isArray(value) &&
+        Object.keys(value as Record<string, unknown>).length === 0)
+    ) {
+      continue;
+    }
+    snapshot[key] = value;
+  }
+
+  if (Object.keys(snapshot).length === 0) return null;
+
+  let body: string;
+  try {
+    body = JSON.stringify(snapshot, null, 2);
+  } catch {
+    body = String(snapshot);
+  }
+  return `Current agent state:\n${body}`;
+};
+
+const applyStateNote = (request: any, expose: ExposeStateOption): any => {
+  const note = buildStateNote(
+    (request.state ?? {}) as Record<string, unknown>,
+    expose,
+  );
+  if (!note) return request;
+
+  const existing = request.systemPrompt;
+  if (existing == null) {
+    return { ...request, systemPrompt: new SystemMessage({ content: note }) };
+  }
+  // existing may be a string OR a SystemMessage
+  const baseText =
+    typeof existing === "string"
+      ? existing
+      : typeof existing.content === "string"
+        ? existing.content
+        : String(existing.content);
+  return {
+    ...request,
+    systemPrompt: new SystemMessage({ content: `${baseText}\n\n${note}` }),
+  };
+};
+
 const createAppContextBeforeAgent = (state, runtime) => {
   const messages = state.messages;
 
@@ -117,23 +285,26 @@ const createAppContextBeforeAgent = (state, runtime) => {
  * ```
  */
 const copilotKitStateSchema = z.object({
-  copilotkit: z
-    .object({
-      actions: z.array(z.any()),
-      context: z.any().optional(),
-      interceptedToolCalls: z.array(z.any()).optional(),
-      originalAIMessageId: z.string().optional(),
-    })
-    .optional(),
+  copilotkit: zodState(
+    z
+      .object({
+        actions: z.array(z.any()),
+        context: z.any().optional(),
+        interceptedToolCalls: z.array(z.any()).optional(),
+        originalAIMessageId: z.string().optional(),
+      })
+      .optional(),
+  ),
 });
 
-const middlewareInput = {
+const buildMiddlewareInput = (exposeState: ExposeStateOption) => ({
   name: "CopilotKitMiddleware",
 
   stateSchema: copilotKitStateSchema as unknown as InteropZodObject,
 
-  // Inject frontend tools before model call
-  wrapModelCall: async (request, handler) => {
+  // Inject frontend tools and surface user state before model call
+  wrapModelCall: async (request: any, handler: (req: any) => Promise<any>) => {
+    request = applyStateNote(request, exposeState);
     const frontendTools = request.state["copilotkit"]?.actions ?? [];
 
     if (frontendTools.length === 0) {
@@ -234,9 +405,33 @@ const middlewareInput = {
       },
     };
   },
-} as any;
-const createCopilotKitMiddleware = () => {
-  return createMiddleware(middlewareInput);
+});
+
+/**
+ * Build a CopilotKit middleware instance with custom options.
+ *
+ * Use this when you want to override the default state-exposure behavior
+ * (for example to hide a sensitive key, or to use an explicit allowlist).
+ *
+ * @example
+ * ```typescript
+ * import { createCopilotkitMiddleware } from "@copilotkit/sdk-js/langgraph";
+ *
+ * const middleware = createCopilotkitMiddleware({
+ *   exposeState: ["liked", "todos"],
+ * });
+ * ```
+ */
+export const createCopilotkitMiddleware = (
+  options: { exposeState?: ExposeStateOption } = {},
+) => {
+  const exposeState = options.exposeState ?? false;
+  return createMiddleware(buildMiddlewareInput(exposeState) as any);
 };
 
-export const copilotkitMiddleware = createCopilotKitMiddleware();
+/**
+ * Default CopilotKit middleware singleton — does NOT surface user state
+ * to the LLM. Pass `exposeState: true` (or an allowlist) to
+ * {@link createCopilotkitMiddleware} to opt in.
+ */
+export const copilotkitMiddleware = createCopilotkitMiddleware();

package/src/langgraph/state-schema.ts

@@ -0,0 +1,34 @@
+import { MessagesValue, StateSchema } from "@langchain/langgraph";
+import { CopilotKitPropertiesSchema } from "./types";
+
+/**
+ * CopilotKit agent state defined with LangGraph's modern
+ * [`StateSchema`](https://docs.langchain.com/oss/javascript/langgraph/graph-api)
+ * API.
+ *
+ * Prefer this over `CopilotKitStateAnnotation` when starting a new
+ * TypeScript agent. `Annotation.Root` is still supported by LangGraph but
+ * `StateSchema` is the recommended API going forward.
+ *
+ * ### Example
+ *
+ * ```typescript
+ * import { StateSchema } from "@langchain/langgraph";
+ * import { CopilotKitStateSchema } from "@copilotkit/sdk-js/langgraph";
+ * import { z } from "zod";
+ *
+ * export const AgentStateSchema = new StateSchema({
+ *   language: z.enum(["english", "spanish"]),
+ *   ...CopilotKitStateSchema.fields,
+ * });
+ *
+ * export type AgentState = typeof AgentStateSchema.State;
+ * ```
+ */
+export const CopilotKitStateSchema = new StateSchema({
+  copilotkit: CopilotKitPropertiesSchema,
+  messages: MessagesValue,
+});
+
+export type CopilotKitSchemaState = typeof CopilotKitStateSchema.State;
+export type CopilotKitSchemaUpdate = typeof CopilotKitStateSchema.Update;

package/src/langgraph/types.ts

@@ -1,5 +1,20 @@
 import { Annotation, MessagesAnnotation } from "@langchain/langgraph";
 
+export interface StandardSerializableSchema<Input, Output = Input> {
+  readonly "~standard": {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (
+      value: unknown,
+    ) => { value: Output } | { issues: ReadonlyArray<{ message: string }> };
+    readonly types?: { readonly input: Input; readonly output: Output };
+    readonly jsonSchema: {
+      readonly input: (options: { target: string }) => Record<string, unknown>;
+      readonly output: (options: { target: string }) => Record<string, unknown>;
+    };
+  };
+}
+
 export const CopilotKitPropertiesAnnotation = Annotation.Root({
   actions: Annotation<any[]>,
   context: Annotation<{ description: string; value: string }[]>,
@@ -12,6 +27,48 @@ export const CopilotKitStateAnnotation = Annotation.Root({
   ...MessagesAnnotation.spec,
 });
 
+const COPILOTKIT_PROPERTIES_JSON_SCHEMA = {
+  type: "object",
+  properties: {
+    actions: { type: "array", items: {} },
+    context: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          description: { type: "string" },
+          value: { type: "string" },
+        },
+        required: ["description", "value"],
+      },
+    },
+    interceptedToolCalls: { type: "array", items: {} },
+    originalAIMessageId: { type: "string" },
+  },
+};
+
+/**
+ * Standard Schema describing the `copilotkit` field on agent state.
+ *
+ * CopilotKit populates these fields at runtime, so the schema accepts any
+ * input shape. Use it with `new StateSchema({ ...CopilotKitStateSchema.fields })`.
+ */
+export const CopilotKitPropertiesSchema: StandardSerializableSchema<
+  typeof CopilotKitPropertiesAnnotation.State
+> = {
+  "~standard": {
+    version: 1,
+    vendor: "@copilotkit/sdk-js",
+    validate: (value) => ({
+      value: value as typeof CopilotKitPropertiesAnnotation.State,
+    }),
+    jsonSchema: {
+      input: () => COPILOTKIT_PROPERTIES_JSON_SCHEMA,
+      output: () => COPILOTKIT_PROPERTIES_JSON_SCHEMA,
+    },
+  },
+};
+
 export interface IntermediateStateConfig {
   stateKey: string;
   tool: string;