@copilotkit/react-core 0.0.0-0.0.0-max-changeset-10101010101010-20260109191632

package/dist/hooks/use-coagent-state-render-bridge.d.ts

@@ -0,0 +1,100 @@
+import * as React from 'react';
+import { ReactCustomMessageRendererPosition } from '@copilotkitnext/react';
+
+/**
+ * Bridge hook that connects agent state renders to chat messages.
+ *
+ * ## Purpose
+ * This hook finds matching state render configurations (registered via useCoAgentStateRender)
+ * and returns UI to render in chat.
+ * It ensures each state render appears bound to a specific message, preventing duplicates while
+ * allowing re-binding when the underlying state changes significantly.
+ *
+ * ## Message-ID-Based Claiming System
+ *
+ * ### The Problem
+ * Multiple bridge component instances render simultaneously (one per message). Without coordination,
+ * they would all try to render the same state render, causing duplicates.
+ *
+ * ### The Solution: Message-ID Claims with State Comparison
+ * Each state render is "claimed" by exactly one **message ID** (not runId):
+ *
+ * **Claim Structure**: `claimsRef.current[messageId] = { stateRenderId, runId, stateSnapshot, locked }`
+ *
+ * **Primary binding is by messageId because**:
+ * - runId is not always available immediately (starts as "pending")
+ * - messageId is the stable identifier throughout the message lifecycle
+ * - Claims persist across component remounts via context ref
+ *
+ * ### Claiming Logic Flow
+ *
+ * 1. **Message already has a claim**:
+ *    - Check if the claim matches the current stateRenderId
+ *    - If yes → render (this message owns this render)
+ *    - Update runId if it was "pending" and now available
+ *
+ * 2. **State render claimed by another message**:
+ *    - Compare state snapshots (ignoring constant keys: messages, tools, copilotkit)
+ *    - If states are identical → block rendering (duplicate)
+ *    - **If states are different → allow claiming** (new data, new message)
+ *    - This handles cases where the same render type shows different states in different messages
+ *
+ * 3. **Unclaimed state render**:
+ *    - Only allow claiming if runId is "pending" (initial render)
+ *    - If runId is real but no claim exists → block (edge case protection)
+ *    - Create new claim: `claimsRef.current[messageId] = { stateRenderId, runId }`
+ *
+ * ### State Snapshot Locking
+ *
+ * Once a state snapshot is captured and locked for a message:
+ * - The UI always renders with the locked snapshot (not live agent.state)
+ * - Prevents UI from appearing "wiped" during state transitions
+ * - Locked when: stateSnapshot prop is available (from message persistence)
+ * - Unlocked state: can still update from live agent.state
+ *
+ * ### Synchronous Claiming (Ref-based)
+ *
+ * Claims are stored in a context-level ref (not React state):
+ * - Multiple bridges render in the same tick
+ * - State updates are async - would allow duplicates before update completes
+ * - Ref provides immediate, synchronous claim checking
+ * - Survives component remounts (stored in context, not component)
+ *
+ * ## Flow Example
+ *
+ * ```
+ * Time 1: Message A renders, runId=undefined, state={progress: 50%}
+ *   → effectiveRunId = "pending"
+ *   → Claims: claimsRef["msgA"] = { stateRenderId: "tasks", runId: "pending", stateSnapshot: {progress: 50%} }
+ *   → Renders UI with 50% progress
+ *
+ * Time 2: Message B renders, runId=undefined, same state
+ *   → Checks: "tasks" already claimed by msgA with same state
+ *   → Returns null (blocked - duplicate)
+ *
+ * Time 3: Real runId appears (e.g., "run-123")
+ *   → Updates claim: claimsRef["msgA"].runId = "run-123"
+ *   → Message A continues rendering
+ *
+ * Time 4: Agent processes more, state={progress: 100%}
+ *   → Message A: locked to 50% (stateSnapshot locked)
+ *   → Message C renders with state={progress: 100%}
+ *   → Checks: "tasks" claimed by msgA but state is DIFFERENT (50% vs 100%)
+ *   → Allows new claim: claimsRef["msgC"] = { stateRenderId: "tasks", runId: "run-123", stateSnapshot: {progress: 100%} }
+ *   → Both messages render independently with their own snapshots
+ * ```
+ */
+interface CoAgentStateRenderBridgeProps {
+    message: any;
+    position: ReactCustomMessageRendererPosition;
+    runId: string;
+    messageIndex: number;
+    messageIndexInRun: number;
+    numberOfMessagesInRun: number;
+    agentId: string;
+    stateSnapshot: any;
+}
+declare function useCoagentStateRenderBridge(agentId: string, props: CoAgentStateRenderBridgeProps): string | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | null | undefined;
+declare function CoAgentStateRenderBridge(props: CoAgentStateRenderBridgeProps): string | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | null | undefined;
+
+export { CoAgentStateRenderBridge, CoAgentStateRenderBridgeProps, useCoagentStateRenderBridge };

package/dist/hooks/use-coagent-state-render-bridge.js

@@ -0,0 +1,214 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropSymbols = Object.getOwnPropertySymbols;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __propIsEnum = Object.prototype.propertyIsEnumerable;
+var __objRest = (source, exclude) => {
+  var target = {};
+  for (var prop in source)
+    if (__hasOwnProp.call(source, prop) && exclude.indexOf(prop) < 0)
+      target[prop] = source[prop];
+  if (source != null && __getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(source)) {
+      if (exclude.indexOf(prop) < 0 && __propIsEnum.call(source, prop))
+        target[prop] = source[prop];
+    }
+  return target;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/hooks/use-coagent-state-render-bridge.tsx
+var use_coagent_state_render_bridge_exports = {};
+__export(use_coagent_state_render_bridge_exports, {
+  CoAgentStateRenderBridge: () => CoAgentStateRenderBridge,
+  useCoagentStateRenderBridge: () => useCoagentStateRenderBridge
+});
+module.exports = __toCommonJS(use_coagent_state_render_bridge_exports);
+var import_react2 = require("@copilotkitnext/react");
+var import_react3 = require("react");
+
+// src/context/coagent-state-renders-context.tsx
+var import_react = require("react");
+var import_jsx_runtime = require("react/jsx-runtime");
+var CoAgentStateRendersContext = (0, import_react.createContext)(
+  void 0
+);
+function useCoAgentStateRenders() {
+  const context = (0, import_react.useContext)(CoAgentStateRendersContext);
+  if (!context) {
+    throw new Error("useCoAgentStateRenders must be used within CoAgentStateRendersProvider");
+  }
+  return context;
+}
+
+// src/hooks/use-coagent-state-render-bridge.tsx
+var import_shared = require("@copilotkit/shared");
+function getStateWithoutConstantKeys(state) {
+  if (!state)
+    return {};
+  const _a = state, { messages, tools, copilotkit } = _a, stateWithoutConstantKeys = __objRest(_a, ["messages", "tools", "copilotkit"]);
+  return stateWithoutConstantKeys;
+}
+function areStatesEquals(a, b) {
+  if (a && !b || !a && b)
+    return false;
+  const _a = a, { messages, tools, copilotkit } = _a, aWithoutConstantKeys = __objRest(_a, ["messages", "tools", "copilotkit"]);
+  const _b = b, {
+    messages: bMessages,
+    tools: bTools,
+    copilotkit: bCopilotkit
+  } = _b, bWithoutConstantKeys = __objRest(_b, [
+    "messages",
+    "tools",
+    "copilotkit"
+  ]);
+  return JSON.stringify(aWithoutConstantKeys) === JSON.stringify(bWithoutConstantKeys);
+}
+function useCoagentStateRenderBridge(agentId, props) {
+  var _a;
+  const { stateSnapshot, messageIndexInRun, message } = props;
+  const { coAgentStateRenders, claimsRef } = useCoAgentStateRenders();
+  const { agent } = (0, import_react2.useAgent)({ agentId });
+  const [nodeName, setNodeName] = (0, import_react3.useState)(void 0);
+  const runId = (_a = props.runId) != null ? _a : message.runId;
+  const effectiveRunId = runId || "pending";
+  (0, import_react3.useEffect)(() => {
+    if (!agent)
+      return;
+    const subscriber = {
+      onStepStartedEvent: ({ event }) => {
+        if (event.stepName !== nodeName) {
+          setNodeName(event.stepName);
+        }
+      },
+      onStepFinishedEvent: ({ event }) => {
+        if (event.stepName === nodeName) {
+          setNodeName(void 0);
+        }
+      }
+    };
+    const { unsubscribe } = agent.subscribe(subscriber);
+    return () => {
+      unsubscribe();
+    };
+  }, [agentId, nodeName]);
+  const getStateRender = (0, import_react3.useCallback)(
+    (messageId) => {
+      return Object.entries(coAgentStateRenders).find(([stateRenderId, stateRender]) => {
+        if (claimsRef.current[messageId]) {
+          return stateRenderId === claimsRef.current[messageId].stateRenderId;
+        }
+        const matchingAgentName = stateRender.name === agentId;
+        const matchesNodeContext = stateRender.nodeName ? stateRender.nodeName === nodeName : true;
+        return matchingAgentName && matchesNodeContext;
+      });
+    },
+    [coAgentStateRenders, nodeName, agentId]
+  );
+  const handleRenderRequest = ({
+    stateRenderId,
+    messageId,
+    runId: runId2,
+    stateSnapshot: renderSnapshot
+  }) => {
+    if (claimsRef.current[messageId]) {
+      const canRender = claimsRef.current[messageId].stateRenderId === stateRenderId;
+      if (canRender && runId2 && (!claimsRef.current[messageId].runId || claimsRef.current[messageId].runId === "pending")) {
+        claimsRef.current[messageId].runId = runId2;
+      }
+      return canRender;
+    }
+    const renderClaimedByOtherMessage = Object.values(claimsRef.current).find(
+      (c) => c.stateRenderId === stateRenderId && (0, import_shared.dataToUUID)(getStateWithoutConstantKeys(c.stateSnapshot)) === (0, import_shared.dataToUUID)(getStateWithoutConstantKeys(renderSnapshot))
+    );
+    if (renderClaimedByOtherMessage) {
+      if (renderSnapshot && renderClaimedByOtherMessage.stateSnapshot && !areStatesEquals(renderClaimedByOtherMessage.stateSnapshot, renderSnapshot)) {
+        claimsRef.current[messageId] = { stateRenderId, runId: runId2 };
+        return true;
+      }
+      return false;
+    }
+    if (!runId2) {
+      return false;
+    }
+    claimsRef.current[messageId] = { stateRenderId, runId: runId2 };
+    return true;
+  };
+  return (0, import_react3.useMemo)(() => {
+    var _a2, _b, _c;
+    if (messageIndexInRun !== 0) {
+      return null;
+    }
+    const [stateRenderId, stateRender] = (_a2 = getStateRender(message.id)) != null ? _a2 : [];
+    if (!stateRender || !stateRenderId) {
+      return null;
+    }
+    const snapshot = stateSnapshot ? (0, import_shared.parseJson)(stateSnapshot, stateSnapshot) : agent == null ? void 0 : agent.state;
+    const canRender = handleRenderRequest({
+      stateRenderId,
+      messageId: message.id,
+      runId: effectiveRunId,
+      stateSnapshot: snapshot
+    });
+    if (!canRender) {
+      return null;
+    }
+    if (snapshot && !claimsRef.current[message.id].locked) {
+      if (stateSnapshot) {
+        claimsRef.current[message.id].stateSnapshot = snapshot;
+        claimsRef.current[message.id].locked = true;
+      } else {
+        claimsRef.current[message.id].stateSnapshot = snapshot;
+      }
+    }
+    if (stateRender.handler) {
+      stateRender.handler({
+        state: stateSnapshot ? (0, import_shared.parseJson)(stateSnapshot, stateSnapshot) : (_b = agent == null ? void 0 : agent.state) != null ? _b : {},
+        nodeName: nodeName != null ? nodeName : ""
+      });
+    }
+    if (stateRender.render) {
+      const status = (agent == null ? void 0 : agent.isRunning) ? "inProgress" : "complete";
+      if (typeof stateRender.render === "string")
+        return stateRender.render;
+      return stateRender.render({
+        status,
+        // Always use state from claim, to make sure the state does not seem "wiped" for a fraction of a second
+        state: (_c = claimsRef.current[message.id].stateSnapshot) != null ? _c : {},
+        nodeName: nodeName != null ? nodeName : ""
+      });
+    }
+  }, [
+    getStateRender,
+    stateSnapshot,
+    agent == null ? void 0 : agent.state,
+    agent == null ? void 0 : agent.isRunning,
+    nodeName,
+    effectiveRunId,
+    message.id,
+    messageIndexInRun
+  ]);
+}
+function CoAgentStateRenderBridge(props) {
+  return useCoagentStateRenderBridge(props.agentId, props);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CoAgentStateRenderBridge,
+  useCoagentStateRenderBridge
+});
+//# sourceMappingURL=use-coagent-state-render-bridge.js.map

package/dist/hooks/use-coagent-state-render-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/hooks/use-coagent-state-render-bridge.tsx","../../src/context/coagent-state-renders-context.tsx"],"sourcesContent":["import { ReactCustomMessageRendererPosition, useAgent } from \"@copilotkitnext/react\";\nimport { useCallback, useEffect, useMemo, useState } from \"react\";\nimport type { AgentSubscriber } from \"@ag-ui/client\";\nimport { useCoAgentStateRenders } from \"../context\";\nimport { dataToUUID, parseJson } from \"@copilotkit/shared\";\n\nfunction getStateWithoutConstantKeys(state: any) {\n  if (!state) return {};\n  const { messages, tools, copilotkit, ...stateWithoutConstantKeys } = state;\n  return stateWithoutConstantKeys;\n}\n\n// Function that compares states, without the constant keys\nfunction areStatesEquals(a: any, b: any) {\n  if ((a && !b) || (!a && b)) return false;\n  const { messages, tools, copilotkit, ...aWithoutConstantKeys } = a;\n  const {\n    messages: bMessages,\n    tools: bTools,\n    copilotkit: bCopilotkit,\n    ...bWithoutConstantKeys\n  } = b;\n\n  return JSON.stringify(aWithoutConstantKeys) === JSON.stringify(bWithoutConstantKeys);\n}\n\n/**\n * Bridge hook that connects agent state renders to chat messages.\n *\n * ## Purpose\n * This hook finds matching state render configurations (registered via useCoAgentStateRender)\n * and returns UI to render in chat.\n * It ensures each state render appears bound to a specific message, preventing duplicates while\n * allowing re-binding when the underlying state changes significantly.\n *\n * ## Message-ID-Based Claiming System\n *\n * ### The Problem\n * Multiple bridge component instances render simultaneously (one per message). Without coordination,\n * they would all try to render the same state render, causing duplicates.\n *\n * ### The Solution: Message-ID Claims with State Comparison\n * Each state render is \"claimed\" by exactly one **message ID** (not runId):\n *\n * **Claim Structure**: `claimsRef.current[messageId] = { stateRenderId, runId, stateSnapshot, locked }`\n *\n * **Primary binding is by messageId because**:\n * - runId is not always available immediately (starts as \"pending\")\n * - messageId is the stable identifier throughout the message lifecycle\n * - Claims persist across component remounts via context ref\n *\n * ### Claiming Logic Flow\n *\n * 1. **Message already has a claim**:\n *    - Check if the claim matches the current stateRenderId\n *    - If yes → render (this message owns this render)\n *    - Update runId if it was \"pending\" and now available\n *\n * 2. **State render claimed by another message**:\n *    - Compare state snapshots (ignoring constant keys: messages, tools, copilotkit)\n *    - If states are identical → block rendering (duplicate)\n *    - **If states are different → allow claiming** (new data, new message)\n *    - This handles cases where the same render type shows different states in different messages\n *\n * 3. **Unclaimed state render**:\n *    - Only allow claiming if runId is \"pending\" (initial render)\n *    - If runId is real but no claim exists → block (edge case protection)\n *    - Create new claim: `claimsRef.current[messageId] = { stateRenderId, runId }`\n *\n * ### State Snapshot Locking\n *\n * Once a state snapshot is captured and locked for a message:\n * - The UI always renders with the locked snapshot (not live agent.state)\n * - Prevents UI from appearing \"wiped\" during state transitions\n * - Locked when: stateSnapshot prop is available (from message persistence)\n * - Unlocked state: can still update from live agent.state\n *\n * ### Synchronous Claiming (Ref-based)\n *\n * Claims are stored in a context-level ref (not React state):\n * - Multiple bridges render in the same tick\n * - State updates are async - would allow duplicates before update completes\n * - Ref provides immediate, synchronous claim checking\n * - Survives component remounts (stored in context, not component)\n *\n * ## Flow Example\n *\n * ```\n * Time 1: Message A renders, runId=undefined, state={progress: 50%}\n *   → effectiveRunId = \"pending\"\n *   → Claims: claimsRef[\"msgA\"] = { stateRenderId: \"tasks\", runId: \"pending\", stateSnapshot: {progress: 50%} }\n *   → Renders UI with 50% progress\n *\n * Time 2: Message B renders, runId=undefined, same state\n *   → Checks: \"tasks\" already claimed by msgA with same state\n *   → Returns null (blocked - duplicate)\n *\n * Time 3: Real runId appears (e.g., \"run-123\")\n *   → Updates claim: claimsRef[\"msgA\"].runId = \"run-123\"\n *   → Message A continues rendering\n *\n * Time 4: Agent processes more, state={progress: 100%}\n *   → Message A: locked to 50% (stateSnapshot locked)\n *   → Message C renders with state={progress: 100%}\n *   → Checks: \"tasks\" claimed by msgA but state is DIFFERENT (50% vs 100%)\n *   → Allows new claim: claimsRef[\"msgC\"] = { stateRenderId: \"tasks\", runId: \"run-123\", stateSnapshot: {progress: 100%} }\n *   → Both messages render independently with their own snapshots\n * ```\n */\nexport interface CoAgentStateRenderBridgeProps {\n  message: any;\n  position: ReactCustomMessageRendererPosition;\n  runId: string;\n  messageIndex: number;\n  messageIndexInRun: number;\n  numberOfMessagesInRun: number;\n  agentId: string;\n  stateSnapshot: any;\n}\n\nexport function useCoagentStateRenderBridge(agentId: string, props: CoAgentStateRenderBridgeProps) {\n  const { stateSnapshot, messageIndexInRun, message } = props;\n  const { coAgentStateRenders, claimsRef } = useCoAgentStateRenders();\n  const { agent } = useAgent({ agentId });\n  const [nodeName, setNodeName] = useState<string | undefined>(undefined);\n\n  const runId = props.runId ?? message.runId;\n  const effectiveRunId = runId || \"pending\";\n\n  useEffect(() => {\n    if (!agent) return;\n    const subscriber: AgentSubscriber = {\n      onStepStartedEvent: ({ event }) => {\n        if (event.stepName !== nodeName) {\n          setNodeName(event.stepName);\n        }\n      },\n      onStepFinishedEvent: ({ event }) => {\n        if (event.stepName === nodeName) {\n          setNodeName(undefined);\n        }\n      },\n    };\n\n    const { unsubscribe } = agent.subscribe(subscriber);\n    return () => {\n      unsubscribe();\n    };\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, [agentId, nodeName]);\n\n  const getStateRender = useCallback(\n    (messageId: string) => {\n      return Object.entries(coAgentStateRenders).find(([stateRenderId, stateRender]) => {\n        if (claimsRef.current[messageId]) {\n          return stateRenderId === claimsRef.current[messageId].stateRenderId;\n        }\n        const matchingAgentName = stateRender.name === agentId;\n        const matchesNodeContext = stateRender.nodeName ? stateRender.nodeName === nodeName : true;\n        return matchingAgentName && matchesNodeContext;\n      });\n    },\n    [coAgentStateRenders, nodeName, agentId],\n  );\n\n  // Message ID-based claim system - A state render can only be claimed by one message ID\n  const handleRenderRequest = ({\n    stateRenderId,\n    messageId,\n    runId,\n    stateSnapshot: renderSnapshot,\n  }: {\n    stateRenderId: string;\n    messageId: string;\n    runId?: string;\n    stateSnapshot?: any;\n  }): boolean => {\n    // Check if this message has already claimed this state render\n    if (claimsRef.current[messageId]) {\n      const canRender = claimsRef.current[messageId].stateRenderId === stateRenderId;\n\n      // Update runId if it doesn't exist\n      if (\n        canRender &&\n        runId &&\n        (!claimsRef.current[messageId].runId || claimsRef.current[messageId].runId === \"pending\")\n      ) {\n        claimsRef.current[messageId].runId = runId;\n      }\n\n      return canRender;\n    }\n\n    // Do not allow render if any other message has claimed this state render\n    const renderClaimedByOtherMessage = Object.values(claimsRef.current).find(\n      (c) =>\n        c.stateRenderId === stateRenderId &&\n        dataToUUID(getStateWithoutConstantKeys(c.stateSnapshot)) ===\n          dataToUUID(getStateWithoutConstantKeys(renderSnapshot)),\n    );\n    if (renderClaimedByOtherMessage) {\n      // If:\n      //   - state render already claimed\n      //   - snapshot exists in the claiming object and is different from current,\n      if (\n        renderSnapshot &&\n        renderClaimedByOtherMessage.stateSnapshot &&\n        !areStatesEquals(renderClaimedByOtherMessage.stateSnapshot, renderSnapshot)\n      ) {\n        claimsRef.current[messageId] = { stateRenderId, runId };\n        return true;\n      }\n      return false;\n    }\n\n    // No existing claim anywhere yet – allow this message to claim even if we already know the runId.\n    if (!runId) {\n      return false;\n    }\n\n    claimsRef.current[messageId] = { stateRenderId, runId };\n    return true;\n  };\n\n  return useMemo(() => {\n    if (messageIndexInRun !== 0) {\n      return null;\n    }\n\n    const [stateRenderId, stateRender] = getStateRender(message.id) ?? [];\n\n    if (!stateRender || !stateRenderId) {\n      return null;\n    }\n\n    // Is there any state we can use?\n    const snapshot = stateSnapshot ? parseJson(stateSnapshot, stateSnapshot) : agent?.state;\n\n    // Synchronously check/claim - returns true if this message can render\n    const canRender = handleRenderRequest({\n      stateRenderId,\n      messageId: message.id,\n      runId: effectiveRunId,\n      stateSnapshot: snapshot,\n    });\n    if (!canRender) {\n      return null;\n    }\n\n    // If we found state, and given that now there's a claim for the current message, let's save it in the claim\n    if (snapshot && !claimsRef.current[message.id].locked) {\n      if (stateSnapshot) {\n        claimsRef.current[message.id].stateSnapshot = snapshot;\n        claimsRef.current[message.id].locked = true;\n      } else {\n        claimsRef.current[message.id].stateSnapshot = snapshot;\n      }\n    }\n\n    if (stateRender.handler) {\n      stateRender.handler({\n        state: stateSnapshot ? parseJson(stateSnapshot, stateSnapshot) : (agent?.state ?? {}),\n        nodeName: nodeName ?? \"\",\n      });\n    }\n\n    if (stateRender.render) {\n      const status = agent?.isRunning ? \"inProgress\" : \"complete\";\n\n      if (typeof stateRender.render === \"string\") return stateRender.render;\n\n      return stateRender.render({\n        status,\n        // Always use state from claim, to make sure the state does not seem \"wiped\" for a fraction of a second\n        state: claimsRef.current[message.id].stateSnapshot ?? {},\n        nodeName: nodeName ?? \"\",\n      });\n    }\n  }, [\n    getStateRender,\n    stateSnapshot,\n    agent?.state,\n    agent?.isRunning,\n    nodeName,\n    effectiveRunId,\n    message.id,\n    messageIndexInRun,\n  ]);\n}\n\nexport function CoAgentStateRenderBridge(props: CoAgentStateRenderBridgeProps) {\n  return useCoagentStateRenderBridge(props.agentId, props);\n}\n","import React, {\n  createContext,\n  useContext,\n  useCallback,\n  useState,\n  useRef,\n  ReactNode,\n  RefObject,\n} from \"react\";\nimport { CoAgentStateRender } from \"../types/coagent-action\";\n\ninterface StateRenderClaim {\n  stateRenderId: string;\n  stateSnapshot?: any;\n  runId?: string;\n  locked?: boolean;\n}\n\ntype ClaimsRef = Record<string, StateRenderClaim>;\n\nexport interface CoAgentStateRendersContextValue {\n  coAgentStateRenders: Record<string, CoAgentStateRender<any>>;\n  setCoAgentStateRender: (id: string, stateRender: CoAgentStateRender<any>) => void;\n  removeCoAgentStateRender: (id: string) => void;\n  claimsRef: RefObject<ClaimsRef>;\n}\n\nconst CoAgentStateRendersContext = createContext<CoAgentStateRendersContextValue | undefined>(\n  undefined,\n);\n\nexport function CoAgentStateRendersProvider({ children }: { children: ReactNode }) {\n  const [coAgentStateRenders, setCoAgentStateRenders] = useState<\n    Record<string, CoAgentStateRender<any>>\n  >({});\n\n  const setCoAgentStateRender = useCallback((id: string, stateRender: CoAgentStateRender<any>) => {\n    setCoAgentStateRenders((prevPoints) => ({\n      ...prevPoints,\n      [id]: stateRender,\n    }));\n  }, []);\n\n  const removeCoAgentStateRender = useCallback((id: string) => {\n    setCoAgentStateRenders((prevPoints) => {\n      const newPoints = { ...prevPoints };\n      delete newPoints[id];\n      return newPoints;\n    });\n  }, []);\n\n  const claimsRef = useRef<ClaimsRef>({});\n\n  return (\n    <CoAgentStateRendersContext.Provider\n      value={{\n        coAgentStateRenders,\n        setCoAgentStateRender,\n        removeCoAgentStateRender,\n        claimsRef,\n      }}\n    >\n      {children}\n    </CoAgentStateRendersContext.Provider>\n  );\n}\n\nexport function useCoAgentStateRenders() {\n  const context = useContext(CoAgentStateRendersContext);\n  if (!context) {\n    throw new Error(\"useCoAgentStateRenders must be used within CoAgentStateRendersProvider\");\n  }\n  return context;\n}\n\nexport { CoAgentStateRendersContext };\n"],"mappings":"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","names":["import_react","runId","_a"]}

package/dist/hooks/use-coagent-state-render-bridge.mjs

@@ -0,0 +1,15 @@
+import {
+  CoAgentStateRenderBridge,
+  useCoagentStateRenderBridge
+} from "../chunk-QNUAXSDP.mjs";
+import "../chunk-NB2FKV2V.mjs";
+import "../chunk-DMLQZG75.mjs";
+import "../chunk-F555TVE4.mjs";
+import "../chunk-FDOMAPJY.mjs";
+import "../chunk-AFNWX62Q.mjs";
+import "../chunk-SKC7AJIV.mjs";
+export {
+  CoAgentStateRenderBridge,
+  useCoagentStateRenderBridge
+};
+//# sourceMappingURL=use-coagent-state-render-bridge.mjs.map

package/dist/hooks/use-coagent-state-render-bridge.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/hooks/use-coagent-state-render.d.ts

@@ -0,0 +1,55 @@
+import { CoAgentStateRender } from '../types/coagent-action.js';
+
+/**
+ * The useCoAgentStateRender hook allows you to render UI or text based components on a Agentic Copilot's state in the chat.
+ * This is particularly useful for showing intermediate state or progress during Agentic Copilot operations.
+ *
+ * ## Usage
+ *
+ * ### Simple Usage
+ *
+ * ```tsx
+ * import { useCoAgentStateRender } from "@copilotkit/react-core";
+ *
+ * type YourAgentState = {
+ *   agent_state_property: string;
+ * }
+ *
+ * useCoAgentStateRender<YourAgentState>({
+ *   name: "basic_agent",
+ *   nodeName: "optionally_specify_a_specific_node",
+ *   render: ({ status, state, nodeName }) => {
+ *     return (
+ *       <YourComponent
+ *         agentStateProperty={state.agent_state_property}
+ *         status={status}
+ *         nodeName={nodeName}
+ *       />
+ *     );
+ *   },
+ * });
+ * ```
+ *
+ * This allows for you to render UI components or text based on what is happening within the agent.
+ *
+ * ### Example
+ * A great example of this is in our Perplexity Clone where we render the progress of an agent's internet search as it is happening.
+ * You can play around with it below or learn how to build it with its [demo](/coagents/videos/perplexity-clone).
+ *
+ * <Callout type="info">
+ *   This example is hosted on Vercel and may take a few seconds to load.
+ * </Callout>
+ *
+ * <iframe src="https://examples-coagents-ai-researcher-ui.vercel.app/" className="w-full rounded-lg border h-[700px] my-4" />
+ */
+
+/**
+ * This hook is used to render agent state with custom UI components or text. This is particularly
+ * useful for showing intermediate state or progress during Agentic Copilot operations.
+ * To get started using rendering intermediate state through this hook, checkout the documentation.
+ *
+ * https://docs.copilotkit.ai/coagents/shared-state/predictive-state-updates
+ */
+declare function useCoAgentStateRender<T = any>(action: CoAgentStateRender<T>, dependencies?: any[]): void;
+
+export { useCoAgentStateRender };

package/dist/hooks/use-coagent-state-render.js

@@ -0,0 +1,255 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var __async = (__this, __arguments, generator) => {
+  return new Promise((resolve, reject) => {
+    var fulfilled = (value) => {
+      try {
+        step(generator.next(value));
+      } catch (e) {
+        reject(e);
+      }
+    };
+    var rejected = (value) => {
+      try {
+        step(generator.throw(value));
+      } catch (e) {
+        reject(e);
+      }
+    };
+    var step = (x) => x.done ? resolve(x.value) : Promise.resolve(x.value).then(fulfilled, rejected);
+    step((generator = generator.apply(__this, __arguments)).next());
+  });
+};
+
+// src/hooks/use-coagent-state-render.ts
+var use_coagent_state_render_exports = {};
+__export(use_coagent_state_render_exports, {
+  useCoAgentStateRender: () => useCoAgentStateRender
+});
+module.exports = __toCommonJS(use_coagent_state_render_exports);
+var import_react4 = require("react");
+
+// src/context/copilot-context.tsx
+var import_react = __toESM(require("react"));
+var emptyCopilotContext = {
+  actions: {},
+  setAction: () => {
+  },
+  removeAction: () => {
+  },
+  setRegisteredActions: () => "",
+  removeRegisteredAction: () => {
+  },
+  chatComponentsCache: { current: { actions: {}, coAgentStateRenders: {} } },
+  getContextString: (documents, categories) => returnAndThrowInDebug(""),
+  addContext: () => "",
+  removeContext: () => {
+  },
+  getAllContext: () => [],
+  getFunctionCallHandler: () => returnAndThrowInDebug(() => __async(void 0, null, function* () {
+  })),
+  isLoading: false,
+  setIsLoading: () => returnAndThrowInDebug(false),
+  chatInstructions: "",
+  setChatInstructions: () => returnAndThrowInDebug(""),
+  additionalInstructions: [],
+  setAdditionalInstructions: () => returnAndThrowInDebug([]),
+  getDocumentsContext: (categories) => returnAndThrowInDebug([]),
+  addDocumentContext: () => returnAndThrowInDebug(""),
+  removeDocumentContext: () => {
+  },
+  copilotApiConfig: new class {
+    get chatApiEndpoint() {
+      throw new Error("Remember to wrap your app in a `<CopilotKit> {...} </CopilotKit>` !!!");
+    }
+    get headers() {
+      return {};
+    }
+    get body() {
+      return {};
+    }
+  }(),
+  chatSuggestionConfiguration: {},
+  addChatSuggestionConfiguration: () => {
+  },
+  removeChatSuggestionConfiguration: () => {
+  },
+  showDevConsole: false,
+  coagentStates: {},
+  setCoagentStates: () => {
+  },
+  coagentStatesRef: { current: {} },
+  setCoagentStatesWithRef: () => {
+  },
+  agentSession: null,
+  setAgentSession: () => {
+  },
+  forwardedParameters: {},
+  agentLock: null,
+  threadId: "",
+  setThreadId: () => {
+  },
+  runId: null,
+  setRunId: () => {
+  },
+  chatAbortControllerRef: { current: null },
+  availableAgents: [],
+  extensions: {},
+  setExtensions: () => {
+  },
+  interruptActions: {},
+  setInterruptAction: () => {
+  },
+  removeInterruptAction: () => {
+  },
+  interruptEventQueue: {},
+  addInterruptEvent: () => {
+  },
+  resolveInterruptEvent: () => {
+  },
+  onError: () => {
+  },
+  bannerError: null,
+  setBannerError: () => {
+  },
+  internalErrorHandlers: {},
+  setInternalErrorHandler: () => {
+  },
+  removeInternalErrorHandler: () => {
+  }
+};
+var CopilotContext = import_react.default.createContext(emptyCopilotContext);
+function returnAndThrowInDebug(_value) {
+  throw new Error("Remember to wrap your app in a `<CopilotKit> {...} </CopilotKit>` !!!");
+}
+
+// src/hooks/use-coagent-state-render.ts
+var import_shared2 = require("@copilotkit/shared");
+
+// src/components/toast/toast-provider.tsx
+var import_react2 = require("react");
+var import_shared = require("@copilotkit/shared");
+var import_jsx_runtime = require("react/jsx-runtime");
+var ToastContext = (0, import_react2.createContext)(void 0);
+function useToast() {
+  const context = (0, import_react2.useContext)(ToastContext);
+  if (!context) {
+    throw new Error("useToast must be used within a ToastProvider");
+  }
+  return context;
+}
+
+// src/context/coagent-state-renders-context.tsx
+var import_react3 = require("react");
+var import_jsx_runtime2 = require("react/jsx-runtime");
+var CoAgentStateRendersContext = (0, import_react3.createContext)(
+  void 0
+);
+function useCoAgentStateRenders() {
+  const context = (0, import_react3.useContext)(CoAgentStateRendersContext);
+  if (!context) {
+    throw new Error("useCoAgentStateRenders must be used within CoAgentStateRendersProvider");
+  }
+  return context;
+}
+
+// src/hooks/use-coagent-state-render.ts
+function useCoAgentStateRender(action, dependencies) {
+  const { chatComponentsCache, availableAgents } = (0, import_react4.useContext)(CopilotContext);
+  const { setCoAgentStateRender, removeCoAgentStateRender, coAgentStateRenders } = useCoAgentStateRenders();
+  const idRef = (0, import_react4.useRef)((0, import_shared2.randomId)());
+  const { setBannerError, addToast } = useToast();
+  (0, import_react4.useEffect)(() => {
+    if ((availableAgents == null ? void 0 : availableAgents.length) && !availableAgents.some((a) => a.name === action.name)) {
+      const message = `(useCoAgentStateRender): Agent "${action.name}" not found. Make sure the agent exists and is properly configured.`;
+      const agentError = new import_shared2.CopilotKitAgentDiscoveryError({
+        agentName: action.name,
+        availableAgents: availableAgents.map((a) => ({ name: a.name, id: a.id }))
+      });
+      setBannerError(agentError);
+    }
+  }, [availableAgents]);
+  const key = `${action.name}-${action.nodeName || "global"}`;
+  if (dependencies === void 0) {
+    if (coAgentStateRenders[idRef.current]) {
+      coAgentStateRenders[idRef.current].handler = action.handler;
+      if (typeof action.render === "function") {
+        if (chatComponentsCache.current !== null) {
+          chatComponentsCache.current.coAgentStateRenders[key] = action.render;
+        }
+      }
+    }
+  }
+  (0, import_react4.useEffect)(() => {
+    const currentId = idRef.current;
+    const hasDuplicate = Object.entries(coAgentStateRenders).some(([id, otherAction]) => {
+      if (id === currentId)
+        return false;
+      if (otherAction.name !== action.name)
+        return false;
+      const hasNodeName = !!action.nodeName;
+      const hasOtherNodeName = !!otherAction.nodeName;
+      if (!hasNodeName && !hasOtherNodeName)
+        return true;
+      if (hasNodeName !== hasOtherNodeName)
+        return false;
+      return action.nodeName === otherAction.nodeName;
+    });
+    if (hasDuplicate) {
+      const message = action.nodeName ? `Found multiple state renders for agent ${action.name} and node ${action.nodeName}. State renders might get overridden` : `Found multiple state renders for agent ${action.name}. State renders might get overridden`;
+      addToast({
+        type: "warning",
+        message,
+        id: `dup-action-${action.name}`
+      });
+    }
+  }, [coAgentStateRenders]);
+  (0, import_react4.useEffect)(() => {
+    setCoAgentStateRender(idRef.current, action);
+    if (chatComponentsCache.current !== null && action.render !== void 0) {
+      chatComponentsCache.current.coAgentStateRenders[key] = action.render;
+    }
+    return () => {
+      removeCoAgentStateRender(idRef.current);
+    };
+  }, [
+    setCoAgentStateRender,
+    removeCoAgentStateRender,
+    action.name,
+    // include render only if it's a string
+    typeof action.render === "string" ? action.render : void 0,
+    // dependencies set by the developer
+    ...dependencies || []
+  ]);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  useCoAgentStateRender
+});
+//# sourceMappingURL=use-coagent-state-render.js.map