@copilotkit/react-core 1.50.0-beta.1 → 1.50.0-beta.11

package/src/hooks/use-copilot-chat-suggestions.tsx

@@ -0,0 +1,124 @@
+/**
+ * <Callout type="warning">
+ *   useCopilotChatSuggestions is experimental. The interface is not final and
+ *   can change without notice.
+ * </Callout>
+ *
+ * `useCopilotReadable` is a React hook that provides app-state and other information
+ * to the Copilot. Optionally, the hook can also handle hierarchical state within your
+ * application, passing these parent-child relationships to the Copilot.
+ *
+ * <br/>
+ * <img src="https://cdn.copilotkit.ai/docs/copilotkit/images/use-copilot-chat-suggestions/use-copilot-chat-suggestions.gif" width="500" />
+ *
+ * ## Usage
+ *
+ * ### Install Dependencies
+ *
+ * This component is part of the [@copilotkit/react-ui](https://npmjs.com/package/@copilotkit/react-ui) package.
+ *
+ * ```shell npm2yarn \"@copilotkit/react-ui"\
+ * npm install @copilotkit/react-core @copilotkit/react-ui
+ * ```
+ *
+ * ### Simple Usage
+ *
+ * ```tsx
+ * import { useCopilotChatSuggestions } from "@copilotkit/react-ui";
+ *
+ * export function MyComponent() {
+ *   const [employees, setEmployees] = useState([]);
+ *
+ *   useCopilotChatSuggestions({
+ *     instructions: `The following employees are on duty: ${JSON.stringify(employees)}`,
+ *   });
+ * }
+ * ```
+ *
+ * ### Dependency Management
+ *
+ * ```tsx
+ * import { useCopilotChatSuggestions } from "@copilotkit/react-ui";
+ *
+ * export function MyComponent() {
+ *   useCopilotChatSuggestions(
+ *     {
+ *       instructions: "Suggest the most relevant next actions.",
+ *     },
+ *     [appState],
+ *   );
+ * }
+ * ```
+ *
+ * In the example above, the suggestions are generated based on the given instructions.
+ * The hook monitors `appState`, and updates suggestions accordingly whenever it changes.
+ *
+ * ### Behavior and Lifecycle
+ *
+ * The hook registers the configuration with the chat context upon component mount and
+ * removes it on unmount, ensuring a clean and efficient lifecycle management.
+ */
+import {
+  useConfigureSuggestions,
+  useCopilotChatConfiguration,
+  useCopilotKit,
+  useSuggestions,
+} from "@copilotkitnext/react";
+import { useEffect } from "react";
+import { StaticSuggestionsConfig, Suggestion } from "@copilotkitnext/core";
+
+type StaticSuggestionInput = Omit<Suggestion, "isLoading"> & Partial<Pick<Suggestion, "isLoading">>;
+
+type StaticSuggestionsConfigInput = Omit<StaticSuggestionsConfig, "suggestions"> & {
+  suggestions: StaticSuggestionInput[];
+};
+
+type DynamicSuggestionsConfigInput = {
+  /**
+   * A prompt or instructions for the GPT to generate suggestions.
+   */
+  instructions: string;
+  /**
+   * The minimum number of suggestions to generate. Defaults to `1`.
+   * @default 1
+   */
+  minSuggestions?: number;
+  /**
+   * The maximum number of suggestions to generate. Defaults to `3`.
+   * @default 1
+   */
+  maxSuggestions?: number;
+
+  /**
+   * Whether the suggestions are available. Defaults to `enabled`.
+   * @default enabled
+   */
+  available?: "enabled" | "disabled" | "always" | "before-first-message" | "after-first-message";
+
+  /**
+   * An optional class name to apply to the suggestions.
+   */
+  className?: string;
+};
+
+export type UseCopilotChatSuggestionsConfiguration =
+  | DynamicSuggestionsConfigInput
+  | StaticSuggestionsConfigInput;
+
+export function useCopilotChatSuggestions(
+  config: UseCopilotChatSuggestionsConfiguration,
+  dependencies: any[] = [],
+) {
+  const existingConfig = useCopilotChatConfiguration();
+  const resolvedAgentId = existingConfig?.agentId ?? "default";
+
+  const available =
+    (config.available === "enabled" ? "always" : config.available) ?? "before-first-message";
+
+  const finalSuggestionConfig = {
+    ...config,
+    available,
+    consumerAgentId: resolvedAgentId, // Use chatConfig.agentId here
+  };
+  useConfigureSuggestions(finalSuggestionConfig, dependencies);
+}

package/src/hooks/use-copilot-chat_internal.ts

@@ -14,10 +14,6 @@ import {
 } from "@copilotkitnext/react";
 import { Suggestion } from "@copilotkitnext/core";
 import { useLazyToolRenderer } from "./use-lazy-tool-renderer";
-import {
-  useConfigureChatSuggestions,
-  UseCopilotChatSuggestionsConfiguration,
-} from "./use-configure-chat-suggestions";
 import { AbstractAgent, AGUIConnectNotImplementedError } from "@ag-ui/client";
 import {
   CoAgentStateRenderBridge,
@@ -71,7 +67,23 @@ export interface UseCopilotChatOptions {
    * Disables inclusion of CopilotKit’s default system message. When true, no system message is sent (this also suppresses any custom message from <code>makeSystemMessage</code>).
    */
   disableSystemMessage?: boolean;
-
+  /**
+   * Controls the behavior of suggestions in the chat interface.
+   *
+   * `auto` (default) - Suggestions are generated automatically:
+   *   - When the chat is first opened (empty state)
+   *   - After each message exchange completes
+   *   - Uses configuration from `useCopilotChatSuggestions` hooks
+   *
+   * `manual` - Suggestions are controlled programmatically:
+   *   - Use `setSuggestions()` to set custom suggestions
+   *   - Use `generateSuggestions()` to trigger AI generation
+   *   - Access via `useCopilotChat` hook
+   *
+   * `SuggestionItem[]` - Static suggestions array:
+   *   - Always shows the same suggestions
+   *   - No AI generation involved
+   */
   suggestions?: ChatSuggestions;
 }
 
@@ -227,7 +239,7 @@ export interface UseCopilotChatReturn {
    * Manually set suggestions
    * Useful for manual mode or custom suggestion workflows
    */
-  setSuggestions: (suggestions: Suggestion[]) => void;
+  setSuggestions: (suggestions: Omit<Suggestion, "isLoading">[]) => void;
 
   /**
    * Trigger AI-powered suggestion generation
@@ -258,27 +270,6 @@ export interface UseCopilotChatReturn {
   threadId?: string;
 }
 
-function useConfigureSuggestions(suggestions?: UseCopilotChatOptions["suggestions"]) {
-  let suggestionsConfig: UseCopilotChatSuggestionsConfiguration;
-
-  if (Array.isArray(suggestions)) {
-    suggestionsConfig = {
-      suggestions,
-      available: "always",
-    };
-  } else if (suggestions === "auto") {
-    suggestionsConfig = {
-      available: suggestions === "auto" ? "always" : "disabled",
-      instructions:
-        "Suggest what the user could say next. Provide clear, highly relevant suggestions. Do not literally suggest function calls.",
-    };
-  } else {
-    suggestionsConfig = { available: "disabled" } as UseCopilotChatSuggestionsConfiguration;
-  }
-
-  useConfigureChatSuggestions(suggestionsConfig);
-}
-
 export function useCopilotChatInternal({
   suggestions,
 }: UseCopilotChatOptions = {}): UseCopilotChatReturn {
@@ -286,10 +277,9 @@ export function useCopilotChatInternal({
   const { threadId, agentSession } = useCopilotContext();
   const existingConfig = useCopilotChatConfiguration();
   const [agentAvailable, setAgentAvailable] = useState(false);
-  useConfigureSuggestions(suggestions);
 
   // Apply priority: props > existing config > defaults
-  const resolvedAgentId = agentSession?.agentName ?? existingConfig?.agentId ?? "default";
+  const resolvedAgentId = existingConfig?.agentId ?? "default";
   const { agent } = useAgent({ agentId: resolvedAgentId });
 
   useEffect(() => {
@@ -419,15 +409,14 @@ export function useCopilotChatInternal({
     [latestSendMessageFunc],
   );
 
-  const latestSetMessages = useUpdatedRef(agent?.setMessages);
   const latestSetMessagesFunc = useCallback(
     (messages: Message[] | DeprecatedGqlMessage[]) => {
       if (messages.every((message) => message instanceof DeprecatedGqlMessage)) {
-        return latestSetMessages.current?.(gqlToAGUI(messages));
+        return agent?.setMessages?.(gqlToAGUI(messages));
       }
-      return latestSetMessages.current?.(messages);
+      return agent?.setMessages?.(messages);
     },
-    [latestSetMessages, agent],
+    [agent?.setMessages, agent],
   );
 
   const latestReload = useUpdatedRef(reload);
@@ -438,10 +427,9 @@ export function useCopilotChatInternal({
     [latestReload],
   );
 
-  const latestStop = useUpdatedRef(agent?.abortRun);
   const latestStopFunc = useCallback(() => {
-    return latestStop.current?.();
-  }, [latestStop]);
+    return agent?.abortRun?.();
+  }, [agent?.abortRun]);
 
   const latestReset = useUpdatedRef(reset);
   const latestResetFunc = useCallback(() => {
@@ -471,18 +459,19 @@ export function useCopilotChatInternal({
         }
       }
 
-      const bridgeRenderer = legacyCustomMessageRenderer || renderCustomMessage
-        ? () => {
-            const customRender = renderCustomMessage?.({
-              message,
-              position: "before",
-            });
-            if (customRender) {
-              return customRender;
+      const bridgeRenderer =
+        legacyCustomMessageRenderer || renderCustomMessage
+          ? () => {
+              const customRender = renderCustomMessage?.({
+                message,
+                position: "before",
+              });
+              if (customRender) {
+                return customRender;
+              }
+              return legacyCustomMessageRenderer?.({ message, position: "before" });
             }
-            return legacyCustomMessageRenderer?.({ message, position: "before" });
-          }
-        : null;
+          : null;
 
       if (bridgeRenderer) {
         return { ...message, generativeUI: bridgeRenderer };
@@ -492,26 +481,27 @@ export function useCopilotChatInternal({
 
     const hasAssistantMessages = processedMessages.some((msg) => msg.role === "assistant");
 
-    if (legacyCustomMessageRenderer && !hasAssistantMessages) {
-      const placeholderId = `coagent-state-render-${resolvedAgentId}`;
-      const placeholderMessage: Message = {
-        id: placeholderId,
-        role: "assistant",
-        content: "",
-        name: "coagent-state-render",
-      };
-      processedMessages = [
-        ...processedMessages,
-        {
-          ...placeholderMessage,
-          generativeUI: () =>
-            legacyCustomMessageRenderer({
-              message: placeholderMessage,
-              position: "before",
-            }),
-        } as Message,
-      ];
-    }
+    // TODO: what is this?
+    // if (legacyCustomMessageRenderer && !hasAssistantMessages) {
+    //   const placeholderId = `coagent-state-render-${resolvedAgentId}`;
+    //   const placeholderMessage: Message = {
+    //     id: placeholderId,
+    //     role: "assistant",
+    //     content: "",
+    //     name: "coagent-state-render",
+    //   };
+    //   processedMessages = [
+    //     ...processedMessages,
+    //     {
+    //       ...placeholderMessage,
+    //       generativeUI: () =>
+    //         legacyCustomMessageRenderer({
+    //           message: placeholderMessage,
+    //           position: "before",
+    //         }),
+    //     } as Message,
+    //   ];
+    // }
 
     return processedMessages;
   }, [
@@ -519,10 +509,20 @@ export function useCopilotChatInternal({
     lazyToolRendered,
     allMessages,
     renderCustomMessage,
-    legacyCustomMessageRenderer,
+    // legacyCustomMessageRenderer,
     resolvedAgentId,
   ]);
 
+  const renderedSuggestions = useMemo(() => {
+    if (Array.isArray(suggestions)) {
+      return {
+        suggestions: suggestions.map((s) => ({ ...s, isLoading: false })),
+        isLoading: false,
+      };
+    }
+    return currentSuggestions;
+  }, [suggestions, currentSuggestions]);
+
   // @ts-ignore
   return {
     messages: resolvedMessages,
@@ -533,15 +533,16 @@ export function useCopilotChatInternal({
     stopGeneration: latestStopFunc,
     reset: latestResetFunc,
     deleteMessage: latestDeleteFunc,
-    isAvailable: !agentAvailable,
+    isAvailable: agentAvailable,
     isLoading: Boolean(agent?.isRunning),
     // mcpServers,
     // setMcpServers,
-    suggestions: currentSuggestions.suggestions,
-    setSuggestions: (suggestions: Suggestion[]) => copilotkit.addSuggestionsConfig({ suggestions }),
+    suggestions: renderedSuggestions.suggestions,
+    setSuggestions: (suggestions: Omit<Suggestion, "isLoading">[]) =>
+      copilotkit.addSuggestionsConfig({ suggestions }),
     generateSuggestions: async () => copilotkit.reloadSuggestions(resolvedAgentId),
     resetSuggestions: () => copilotkit.clearSuggestions(resolvedAgentId),
-    isLoadingSuggestions: currentSuggestions.isLoading,
+    isLoadingSuggestions: renderedSuggestions.isLoading,
     interrupt,
     agent,
     threadId,
@@ -585,13 +586,12 @@ function useLegacyCoagentRenderer({
 
     return ({ message, position }: LegacyRenderParams) => {
       const effectiveThreadId = threadId ?? agent.threadId ?? "default";
-      const existingRunId = copilotkit.getRunIdForMessage(
-        agentId,
-        effectiveThreadId,
-        message.id,
-      );
+      const existingRunId = copilotkit.getRunIdForMessage(agentId, effectiveThreadId, message.id);
       const runId = existingRunId || `pending:${message.id}`;
-      const messageIndex = Math.max(agent.messages.findIndex((msg) => msg.id === message.id), 0);
+      const messageIndex = Math.max(
+        agent.messages.findIndex((msg) => msg.id === message.id),
+        0,
+      );
 
       const bridgeProps: CoAgentStateRenderBridgeProps = {
         message: message as any,

package/src/hooks/use-copilot-readable.ts

@@ -61,9 +61,8 @@
  * }
  * ```
  */
+import { useCopilotKit } from "@copilotkitnext/react";
 import { useEffect, useRef } from "react";
-import { useCopilotContext } from "../context/copilot-context";
-import { useAgentContext } from "@copilotkitnext/react";
 
 /**
  * Options for the useCopilotReadable hook.
@@ -99,19 +98,38 @@ export interface UseCopilotReadableOptions {
   convert?: (description: string, value: any) => string;
 }
 
-function convertToJSON(description: string, value: any): string {
-  return `${description}: ${typeof value === "string" ? value : JSON.stringify(value)}`;
-}
-
 /**
  * Adds the given information to the Copilot context to make it readable by Copilot.
  */
 export function useCopilotReadable(
-  { description, value }: UseCopilotReadableOptions,
+  { description, value, convert, available }: UseCopilotReadableOptions,
   dependencies?: any[],
-): void {
-  useAgentContext({
-    description,
-    value,
-  });
+): string | undefined {
+  const { copilotkit } = useCopilotKit();
+  const ctxIdRef = useRef<string | undefined>(undefined);
+  useEffect(() => {
+    if (!copilotkit) return;
+
+    const found = Object.entries(copilotkit.context).find(([id, ctxItem]) => {
+      return JSON.stringify({ description, value }) == JSON.stringify(ctxItem);
+    });
+    if (found) {
+      ctxIdRef.current = found[0];
+      if (available === "disabled") copilotkit.removeContext(ctxIdRef.current);
+      return;
+    }
+    if (!found && available === "disabled") return;
+
+    ctxIdRef.current = copilotkit.addContext({
+      description,
+      value: (convert ?? JSON.stringify)(value),
+    });
+
+    return () => {
+      if (!ctxIdRef.current) return;
+      copilotkit.removeContext(ctxIdRef.current);
+    };
+  }, [description, value, convert]);
+
+  return ctxIdRef.current;
 }

package/src/hooks/use-frontend-tool.ts

@@ -3,7 +3,10 @@ import { ActionRenderProps, FrontendAction } from "../types/frontend-action";
 import { Parameter, getZodParameters, MappedParameterTypes } from "@copilotkit/shared";
 import { parseJson } from "@copilotkit/shared";
 import { ToolCallStatus } from "@copilotkitnext/core";
-import { type ReactFrontendTool, useFrontendTool as useFrontendToolVNext } from "@copilotkitnext/react";
+import {
+  type ReactFrontendTool,
+  useFrontendTool as useFrontendToolVNext,
+} from "@copilotkitnext/react";
 
 type FrontendToolOptions<T extends Parameter[] | []> = ReactFrontendTool<MappedParameterTypes<T>>;
 type FrontendToolRenderArgs<T extends Parameter[] | []> =
@@ -47,7 +50,12 @@ export function useFrontendTool<const T extends Parameter[] = []>(
 
     if (typeof render === "string") {
       const staticRender = render;
-      return (() => React.createElement(React.Fragment, null, staticRender)) as FrontendToolOptions<T>["render"];
+      return (() =>
+        React.createElement(
+          React.Fragment,
+          null,
+          staticRender,
+        )) as FrontendToolOptions<T>["render"];
     }
 
     return ((args: FrontendToolRenderArgs<T>) => {

package/src/hooks/use-langgraph-interrupt-render.ts

@@ -3,6 +3,8 @@ import React, { useCallback, useEffect, useMemo } from "react";
 import type { AbstractAgent, AgentSubscriber } from "@ag-ui/client";
 import { MetaEventName } from "@copilotkit/runtime-client-gql";
 import { dataToUUID, parseJson } from "@copilotkit/shared";
+import { useAgentNodeName } from "./use-agent-nodename";
+import { useCopilotChatConfiguration } from "@copilotkitnext/react";
 
 type InterruptProps = {
   event: any;
@@ -28,11 +30,15 @@ export function useLangGraphInterruptRender(
     threadId,
     interruptEventQueue,
     addInterruptEvent,
-    removeInterruptEvent,
+    resolveInterruptEvent,
   } = useCopilotContext();
+  const existingConfig = useCopilotChatConfiguration();
+  const resolvedAgentId = existingConfig?.agentId ?? "default";
+  const nodeName = useAgentNodeName(resolvedAgentId);
 
   useEffect(() => {
     if (!agent) return;
+    let localInterrupt: any = null;
     const subscriber: AgentSubscriber = {
       onCustomEvent: ({ event }) => {
         if (event.name === "on_interrupt") {
@@ -41,12 +47,21 @@ export function useLangGraphInterruptRender(
             type: event.type,
             value: parseJson(event.value, event.value),
           };
-          const eventId = dataToUUID(JSON.stringify(eventData), "interruptEvents");
-          addInterruptEvent({
+          const eventId = dataToUUID(eventData, "interruptEvents");
+          localInterrupt = {
             eventId,
             threadId,
             event: eventData,
-          });
+          };
+        }
+      },
+      onRunStartedEvent: () => {
+        localInterrupt = null;
+      },
+      onRunFinalized: () => {
+        if (localInterrupt) {
+          addInterruptEvent(localInterrupt);
+          localInterrupt = null;
         }
       },
     };
@@ -67,7 +82,7 @@ export function useLangGraphInterruptRender(
           },
         },
       });
-      removeInterruptEvent(threadId, eventId);
+      resolveInterruptEvent(threadId, eventId, response ?? "");
     },
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [agent, threadId],
@@ -78,7 +93,7 @@ export function useLangGraphInterruptRender(
     const eventQueue = interruptEventQueue[threadId] || [];
     const currentQueuedEvent = eventQueue.find((qe) => !qe.event.response);
 
-    if (!currentQueuedEvent) return null;
+    if (!currentQueuedEvent || !agentSession) return null;
 
     // Find the first matching action from all registered actions
     const allActions = Object.values(interruptActions);
@@ -86,7 +101,10 @@ export function useLangGraphInterruptRender(
       if (!action.enabled) return true; // No filter = match all
       return action.enabled({
         eventValue: currentQueuedEvent.event.value,
-        agentMetadata: agentSession,
+        agentMetadata: {
+          ...agentSession,
+          nodeName,
+        },
       });
     });
 

package/src/hooks/use-langgraph-interrupt.ts

@@ -1,7 +1,6 @@
 import { useContext, useEffect, useMemo } from "react";
 import { CopilotContext } from "../context/copilot-context";
 import { LangGraphInterruptRender } from "../types/interrupt-action";
-import { useCopilotChatInternal } from "./use-copilot-chat_internal";
 import { useToast } from "../components/toast/toast-provider";
 import { dataToUUID } from "@copilotkit/shared";
 
@@ -13,7 +12,7 @@ export function useLangGraphInterrupt<TEventValue = any>(
     useContext(CopilotContext);
   const { addToast } = useToast();
 
-  const actionId = dataToUUID(JSON.stringify(action), "lgAction");
+  const actionId = dataToUUID(action, "lgAction");
 
   useEffect(() => {
     if (!action) return;
@@ -27,7 +26,7 @@ export function useLangGraphInterrupt<TEventValue = any>(
     //   return;
     // }
 
-    setInterruptAction(threadId, { ...action, id: actionId });
+    setInterruptAction({ ...action, id: actionId });
 
     // Cleanup: remove action on unmount
     return () => {

package/src/types/interrupt-action.ts

@@ -26,7 +26,7 @@ export interface LangGraphInterruptRender<TEventValue = any> {
    * Method that returns a boolean, indicating if the interrupt action should run
    * Useful when using multiple interrupts
    */
-  enabled?: (args: { eventValue: TEventValue; agentMetadata: AgentSession | null }) => boolean;
+  enabled?: (args: { eventValue: TEventValue; agentMetadata: AgentSession }) => boolean;
 }
 
 export type LangGraphInterruptAction = LangGraphInterruptRender & {
@@ -34,10 +34,7 @@ export type LangGraphInterruptAction = LangGraphInterruptRender & {
 };
 
 export type LangGraphInterruptActionSetterArgs = Partial<LangGraphInterruptRender> | null;
-export type LangGraphInterruptActionSetter = (
-  threadId: string,
-  action: LangGraphInterruptActionSetterArgs,
-) => void;
+export type LangGraphInterruptActionSetter = (action: LangGraphInterruptActionSetterArgs) => void;
 
 export interface QueuedInterruptEvent {
   eventId: string; // Generated unique ID for tracking

package/src/v2/index.ts

@@ -1,2 +1,4 @@
+import "./index.css";
+
 export * from "@copilotkitnext/core";
 export * from "@copilotkitnext/react";

package/tsup.config.ts

@@ -10,7 +10,7 @@ export default defineConfig((options: Options) => ({
   format: ["esm", "cjs"],
   dts: true,
   minify: false,
-  external: ["react", "@copilotkitnext/core", "@copilotkitnext/react"],
+  external: ["react"],
   sourcemap: true,
   ...options,
 }));

package/dist/chunk-24SCZAB4.mjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/hooks/use-coagent.ts"],"sourcesContent":["/**\n * <Callout type=\"info\">\n *   Usage of this hook assumes some additional setup in your application, for more information\n *   on that see the CoAgents <span className=\"text-blue-500\">[getting started guide](/coagents/quickstart/langgraph)</span>.\n * </Callout>\n * <Frame className=\"my-12\">\n *   <img\n *     src=\"https://cdn.copilotkit.ai/docs/copilotkit/images/coagents/SharedStateCoAgents.gif\"\n *     alt=\"CoAgents demonstration\"\n *     className=\"w-auto\"\n *   />\n * </Frame>\n *\n * This hook is used to integrate an agent into your application. With its use, you can\n * render and update the state of an agent, allowing for a dynamic and interactive experience.\n * We call these shared state experiences agentic copilots, or CoAgents for short.\n *\n * ## Usage\n *\n * ### Simple Usage\n *\n * ```tsx\n * import { useCoAgent } from \"@copilotkit/react-core\";\n *\n * type AgentState = {\n *   count: number;\n * }\n *\n * const agent = useCoAgent<AgentState>({\n *   name: \"my-agent\",\n *   initialState: {\n *     count: 0,\n *   },\n * });\n *\n * ```\n *\n * `useCoAgent` returns an object with the following properties:\n *\n * ```tsx\n * const {\n *   name,     // The name of the agent currently being used.\n *   nodeName, // The name of the current LangGraph node.\n *   state,    // The current state of the agent.\n *   setState, // A function to update the state of the agent.\n *   running,  // A boolean indicating if the agent is currently running.\n *   start,    // A function to start the agent.\n *   stop,     // A function to stop the agent.\n *   run,      // A function to re-run the agent. Takes a HintFunction to inform the agent why it is being re-run.\n * } = agent;\n * ```\n *\n * Finally we can leverage these properties to create reactive experiences with the agent!\n *\n * ```tsx\n * const { state, setState } = useCoAgent<AgentState>({\n *   name: \"my-agent\",\n *   initialState: {\n *     count: 0,\n *   },\n * });\n *\n * return (\n *   <div>\n *     <p>Count: {state.count}</p>\n *     <button onClick={() => setState({ count: state.count + 1 })}>Increment</button>\n *   </div>\n * );\n * ```\n *\n * This reactivity is bidirectional, meaning that changes to the state from the agent will be reflected in the UI and vice versa.\n *\n * ## Parameters\n * <PropertyReference name=\"options\" type=\"UseCoagentOptions<T>\" required>\n *   The options to use when creating the coagent.\n *   <PropertyReference name=\"name\" type=\"string\" required>\n *     The name of the agent to use.\n *   </PropertyReference>\n *   <PropertyReference name=\"initialState\" type=\"T | any\">\n *     The initial state of the agent.\n *   </PropertyReference>\n *   <PropertyReference name=\"state\" type=\"T | any\">\n *     State to manage externally if you are using this hook with external state management.\n *   </PropertyReference>\n *   <PropertyReference name=\"setState\" type=\"(newState: T | ((prevState: T | undefined) => T)) => void\">\n *     A function to update the state of the agent if you are using this hook with external state management.\n *   </PropertyReference>\n * </PropertyReference>\n */\n\nimport { useCallback, useEffect, useMemo, useRef, useState } from \"react\";\nimport { Message } from \"@copilotkit/shared\";\nimport { useAgent } from \"@copilotkitnext/react\";\nimport { type AgentSubscriber } from \"@ag-ui/client\";\n\ninterface UseCoagentOptionsBase {\n  /**\n   * The name of the agent being used.\n   */\n  name: string;\n  /**\n   * @deprecated - use \"config.configurable\"\n   * Config to pass to a LangGraph Agent\n   */\n  configurable?: Record<string, any>;\n  /**\n   * Config to pass to a LangGraph Agent\n   */\n  config?: {\n    configurable?: Record<string, any>;\n    [key: string]: any;\n  };\n}\n\ninterface WithInternalStateManagementAndInitial<T> extends UseCoagentOptionsBase {\n  /**\n   * The initial state of the agent.\n   */\n  initialState: T;\n}\n\ninterface WithInternalStateManagement extends UseCoagentOptionsBase {\n  /**\n   * Optional initialState with default type any\n   */\n  initialState?: any;\n}\n\ninterface WithExternalStateManagement<T> extends UseCoagentOptionsBase {\n  /**\n   * The current state of the agent.\n   */\n  state: T;\n  /**\n   * A function to update the state of the agent.\n   */\n  setState: (newState: T | ((prevState: T | undefined) => T)) => void;\n}\n\ntype UseCoagentOptions<T> =\n  | WithInternalStateManagementAndInitial<T>\n  | WithInternalStateManagement\n  | WithExternalStateManagement<T>;\n\nexport interface UseCoagentReturnType<T> {\n  /**\n   * The name of the agent being used.\n   */\n  name: string;\n  /**\n   * The name of the current LangGraph node.\n   */\n  nodeName?: string;\n  /**\n   * The ID of the thread the agent is running in.\n   */\n  threadId?: string;\n  /**\n   * A boolean indicating if the agent is currently running.\n   */\n  running: boolean;\n  /**\n   * The current state of the agent.\n   */\n  state: T;\n  /**\n   * A function to update the state of the agent.\n   */\n  setState: (newState: T | ((prevState: T | undefined) => T)) => void;\n  /**\n   * A function to start the agent.\n   */\n  start: () => void;\n  /**\n   * A function to stop the agent.\n   */\n  stop: () => void;\n  /**\n   * A function to re-run the agent. The hint function can be used to provide a hint to the agent\n   * about why it is being re-run again.\n   */\n  run: (...args: any[]) => Promise<any>;\n}\n\nexport interface HintFunctionParams {\n  /**\n   * The previous state of the agent.\n   */\n  previousState: any;\n  /**\n   * The current state of the agent.\n   */\n  currentState: any;\n}\n\nexport type HintFunction = (params: HintFunctionParams) => Message | undefined;\n\n/**\n * This hook is used to integrate an agent into your application. With its use, you can\n * render and update the state of the agent, allowing for a dynamic and interactive experience.\n * We call these shared state experiences \"agentic copilots\". To get started using agentic copilots, which\n * we refer to as CoAgents, checkout the documentation at https://docs.copilotkit.ai/coagents/quickstart/langgraph.\n */\nexport function useCoAgent<T = any>(options: UseCoagentOptions<T>): UseCoagentReturnType<T> {\n  const { agent } = useAgent({ agentId: options.name });\n  const nodeNameRef = useRef<string>(\"start\");\n\n  const handleStateUpdate = useCallback(\n    (newState: T | ((prevState: T | undefined) => T)) => {\n      if (!agent) return;\n\n      if (typeof newState === \"function\") {\n        const updater = newState as (prevState: T | undefined) => T;\n        agent.setState(updater(agent.state));\n      } else {\n        agent.setState({ ...agent.state, ...newState });\n      }\n    },\n    [agent?.state, agent?.setState],\n  );\n\n  const externalStateStr = useMemo(\n    () => (isExternalStateManagement(options) ? JSON.stringify(options.state) : undefined),\n    [isExternalStateManagement(options) ? JSON.stringify(options.state) : undefined],\n  );\n\n  // Sync internal state with external state if state management is external\n  useEffect(() => {\n    if (\n      agent?.state &&\n      isExternalStateManagement(options) &&\n      JSON.stringify(options.state) !== JSON.stringify(agent.state)\n    ) {\n      handleStateUpdate(options.state);\n    }\n  }, [agent, externalStateStr, handleStateUpdate]);\n\n  const hasStateValues = useCallback((value?: Record<string, any>) => {\n    return Boolean(value && Object.keys(value).length);\n  }, []);\n\n  const initialStateRef = useRef<any>(\n    isExternalStateManagement(options)\n      ? options.state\n      : \"initialState\" in options\n        ? options.initialState\n        : undefined,\n  );\n\n  useEffect(() => {\n    if (isExternalStateManagement(options)) {\n      initialStateRef.current = options.state;\n    } else if (\"initialState\" in options) {\n      initialStateRef.current = options.initialState;\n    }\n  }, [\n    isExternalStateManagement(options)\n      ? JSON.stringify(options.state)\n      : \"initialState\" in options\n        ? JSON.stringify(options.initialState)\n        : undefined,\n  ]);\n\n  useEffect(() => {\n    if (!agent) return;\n    const subscriber: AgentSubscriber = {\n      onStateChanged: (args: any) => {\n        if (isExternalStateManagement(options)) {\n          options.setState(args.state);\n        }\n      },\n      onRunInitialized: (args: any) => {\n        const runHasState = hasStateValues(args.state);\n        if (runHasState) {\n          handleStateUpdate(args.state);\n          return;\n        }\n\n        if (hasStateValues(agent.state)) {\n          return;\n        }\n\n        if (initialStateRef.current !== undefined) {\n          handleStateUpdate(initialStateRef.current);\n        }\n      },\n      onStepStartedEvent: ({ event }) => {\n        nodeNameRef.current = event.stepName;\n      },\n      onRunStartedEvent: () => {\n        nodeNameRef.current = \"start\";\n      },\n      onRunFinishedEvent: () => {\n        nodeNameRef.current = \"end\";\n      },\n    };\n\n    const subscription = agent.subscribe(subscriber);\n    return () => {\n      subscription.unsubscribe();\n    };\n  }, [agent, handleStateUpdate, hasStateValues]);\n\n  // Return a consistent shape whether or not the agent is available\n  return useMemo<UseCoagentReturnType<T>>(() => {\n    if (!agent) {\n      const noop = () => {};\n      const noopAsync = async () => {};\n      const initialState =\n        // prefer externally provided state if available\n        (\"state\" in options && (options as any).state) ??\n        // then initialState if provided\n        (\"initialState\" in options && (options as any).initialState) ??\n        ({} as T);\n      return {\n        name: options.name,\n        nodeName: nodeNameRef.current,\n        threadId: undefined,\n        running: false,\n        state: initialState as T,\n        setState: noop,\n        start: noop,\n        stop: noop,\n        run: noopAsync,\n      };\n    }\n\n    return {\n      name: agent?.agentId ?? options.name,\n      nodeName: nodeNameRef.current,\n      threadId: agent.threadId,\n      running: agent.isRunning,\n      state: agent.state,\n      setState: handleStateUpdate,\n      // TODO: start and run both have same thing. need to figure out\n      start: agent.runAgent,\n      stop: agent.abortRun,\n      run: agent.runAgent,\n    };\n  }, [\n    agent?.state,\n    agent?.runAgent,\n    agent?.abortRun,\n    agent?.runAgent,\n    agent?.threadId,\n    agent?.isRunning,\n    agent?.agentId,\n    handleStateUpdate,\n    options.name,\n  ]);\n}\n\nconst isExternalStateManagement = <T>(\n  options: UseCoagentOptions<T>,\n): options is WithExternalStateManagement<T> => {\n  return \"state\" in options && \"setState\" in options;\n};\n"],"mappings":"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","names":[]}

package/dist/chunk-5X5DJRQQ.mjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/components/CopilotListeners.tsx"],"sourcesContent":["import { useCallback, useEffect, useMemo, useRef } from \"react\";\nimport { useAgent, useCopilotChatConfiguration, useCopilotKit } from \"@copilotkitnext/react\";\nimport { CopilotKitError, parseJson } from \"@copilotkit/shared\";\nimport { useCopilotContext } from \"../context\";\nimport { AbstractAgent, AgentSubscriber, AGUIConnectNotImplementedError } from \"@ag-ui/client\";\nimport { useErrorToast } from \"./error-boundary/error-utils\";\nimport { CopilotKitCoreSubscriber } from \"@copilotkitnext/core\";\nimport { useToast } from \"./toast/toast-provider\";\nimport { CopilotKitLowLevelError } from \"@copilotkit/shared\";\n\nconst usePredictStateSubscription = (agent?: AbstractAgent) => {\n  const predictStateToolsRef = useRef<\n    {\n      tool: string;\n      state_key: string;\n      tool_argument: string;\n    }[]\n  >([]);\n\n  const getSubscriber = useCallback(\n    (agent: AbstractAgent): AgentSubscriber => ({\n      onCustomEvent: ({ event }) => {\n        if (event.name === \"PredictState\") {\n          predictStateToolsRef.current = event.value;\n        }\n      },\n      onToolCallArgsEvent: ({ partialToolCallArgs, toolCallName }) => {\n        predictStateToolsRef.current.forEach((t) => {\n          if (t?.tool !== toolCallName) return;\n\n          const emittedState =\n            typeof partialToolCallArgs === \"string\"\n              ? parseJson(partialToolCallArgs as unknown as string, partialToolCallArgs)\n              : partialToolCallArgs;\n\n          agent.setState({\n            [t.state_key]: emittedState[t.state_key],\n          });\n        });\n      },\n    }),\n    [],\n  );\n\n  useEffect(() => {\n    if (!agent) return;\n\n    const subscriber = getSubscriber(agent);\n    const { unsubscribe } = agent.subscribe(subscriber);\n    return () => {\n      unsubscribe();\n    };\n  }, [agent, getSubscriber]);\n};\n\nexport function CopilotListeners() {\n  const { copilotkit } = useCopilotKit();\n  const { agentSession } = useCopilotContext();\n  const existingConfig = useCopilotChatConfiguration();\n  const resolvedAgentId = agentSession?.agentName ?? existingConfig?.agentId ?? \"default\";\n  const { setBannerError } = useToast();\n\n  const { agent } = useAgent({ agentId: resolvedAgentId });\n\n  usePredictStateSubscription(agent);\n\n  useEffect(() => {\n    const subscriber: CopilotKitCoreSubscriber = {\n      onError: ({ error }) => {\n        // @ts-expect-error -- for now, choose a random CPK error type to display the error toast\n        setBannerError(new CopilotKitLowLevelError({ error, message: error.message }));\n      },\n    };\n    const subscription = copilotkit.subscribe(subscriber);\n\n    return () => {\n      subscription.unsubscribe();\n    };\n  }, [copilotkit?.subscribe]);\n\n  return null;\n}\n"],"mappings":";;;;;;;;AAAA,SAAS,aAAa,WAAoB,cAAc;AACxD,SAAS,UAAU,6BAA6B,qBAAqB;AACrE,SAA0B,iBAAiB;AAM3C,SAAS,+BAA+B;AAExC,IAAM,8BAA8B,CAAC,UAA0B;AAC7D,QAAM,uBAAuB,OAM3B,CAAC,CAAC;AAEJ,QAAM,gBAAgB;AAAA,IACpB,CAACA,YAA2C;AAAA,MAC1C,eAAe,CAAC,EAAE,MAAM,MAAM;AAC5B,YAAI,MAAM,SAAS,gBAAgB;AACjC,+BAAqB,UAAU,MAAM;AAAA,QACvC;AAAA,MACF;AAAA,MACA,qBAAqB,CAAC,EAAE,qBAAqB,aAAa,MAAM;AAC9D,6BAAqB,QAAQ,QAAQ,CAAC,MAAM;AAC1C,eAAI,uBAAG,UAAS;AAAc;AAE9B,gBAAM,eACJ,OAAO,wBAAwB,WAC3B,UAAU,qBAA0C,mBAAmB,IACvE;AAEN,UAAAA,OAAM,SAAS;AAAA,YACb,CAAC,EAAE,SAAS,GAAG,aAAa,EAAE,SAAS;AAAA,UACzC,CAAC;AAAA,QACH,CAAC;AAAA,MACH;AAAA,IACF;AAAA,IACA,CAAC;AAAA,EACH;AAEA,YAAU,MAAM;AACd,QAAI,CAAC;AAAO;AAEZ,UAAM,aAAa,cAAc,KAAK;AACtC,UAAM,EAAE,YAAY,IAAI,MAAM,UAAU,UAAU;AAClD,WAAO,MAAM;AACX,kBAAY;AAAA,IACd;AAAA,EACF,GAAG,CAAC,OAAO,aAAa,CAAC;AAC3B;AAEO,SAAS,mBAAmB;AAvDnC;AAwDE,QAAM,EAAE,WAAW,IAAI,cAAc;AACrC,QAAM,EAAE,aAAa,IAAI,kBAAkB;AAC3C,QAAM,iBAAiB,4BAA4B;AACnD,QAAM,mBAAkB,wDAAc,cAAd,YAA2B,iDAAgB,YAA3C,YAAsD;AAC9E,QAAM,EAAE,eAAe,IAAI,SAAS;AAEpC,QAAM,EAAE,MAAM,IAAI,SAAS,EAAE,SAAS,gBAAgB,CAAC;AAEvD,8BAA4B,KAAK;AAEjC,YAAU,MAAM;AACd,UAAM,aAAuC;AAAA,MAC3C,SAAS,CAAC,EAAE,MAAM,MAAM;AAEtB,uBAAe,IAAI,wBAAwB,EAAE,OAAO,SAAS,MAAM,QAAQ,CAAC,CAAC;AAAA,MAC/E;AAAA,IACF;AACA,UAAM,eAAe,WAAW,UAAU,UAAU;AAEpD,WAAO,MAAM;AACX,mBAAa,YAAY;AAAA,IAC3B;AAAA,EACF,GAAG,CAAC,yCAAY,SAAS,CAAC;AAE1B,SAAO;AACT;","names":["agent"]}

package/dist/chunk-7BYHZLPL.mjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/hooks/use-langgraph-interrupt.ts"],"sourcesContent":["import { useContext, useEffect, useMemo } from \"react\";\nimport { CopilotContext } from \"../context/copilot-context\";\nimport { LangGraphInterruptRender } from \"../types/interrupt-action\";\nimport { useCopilotChatInternal } from \"./use-copilot-chat_internal\";\nimport { useToast } from \"../components/toast/toast-provider\";\nimport { dataToUUID } from \"@copilotkit/shared\";\n\nexport function useLangGraphInterrupt<TEventValue = any>(\n  action: Omit<LangGraphInterruptRender<TEventValue>, \"id\">,\n  dependencies?: any[],\n) {\n  const { setInterruptAction, removeInterruptAction, interruptActions, threadId } =\n    useContext(CopilotContext);\n  const { addToast } = useToast();\n\n  const actionId = dataToUUID(JSON.stringify(action), \"lgAction\");\n\n  useEffect(() => {\n    if (!action) return;\n\n    // if (!action.enabled) {\n    // TODO: if there are any other actions registered, we need to warn the user that a current action without \"enabled\" might render for everything\n    //   addToast({\n    //     type: \"warning\",\n    //     message: \"An action is already registered for the interrupt event\",\n    //   });\n    //   return;\n    // }\n\n    setInterruptAction(threadId, { ...action, id: actionId });\n\n    // Cleanup: remove action on unmount\n    return () => {\n      removeInterruptAction(actionId);\n    };\n  }, [setInterruptAction, removeInterruptAction, threadId, actionId, ...(dependencies || [])]);\n}\n"],"mappings":";;;;;;;;;;;;AAAA,SAAS,YAAY,iBAA0B;AAK/C,SAAS,kBAAkB;AAEpB,SAAS,sBACd,QACA,cACA;AACA,QAAM,EAAE,oBAAoB,uBAAuB,kBAAkB,SAAS,IAC5E,WAAW,cAAc;AAC3B,QAAM,EAAE,SAAS,IAAI,SAAS;AAE9B,QAAM,WAAW,WAAW,KAAK,UAAU,MAAM,GAAG,UAAU;AAE9D,YAAU,MAAM;AACd,QAAI,CAAC;AAAQ;AAWb,uBAAmB,UAAU,iCAAK,SAAL,EAAa,IAAI,SAAS,EAAC;AAGxD,WAAO,MAAM;AACX,4BAAsB,QAAQ;AAAA,IAChC;AAAA,EACF,GAAG,CAAC,oBAAoB,uBAAuB,UAAU,UAAU,GAAI,gBAAgB,CAAC,CAAE,CAAC;AAC7F;","names":[]}