@copilotkit/react-core 1.57.3 → 1.58.0

package/src/hooks/use-coagent-state-render-bridge.tsx

@@ -1,222 +0,0 @@
-import { ReactCustomMessageRendererPosition, useAgent } from "../v2";
-import { useCallback, useEffect, useMemo, useState } from "react";
-import type { AgentSubscriber } from "@ag-ui/client";
-import { useCoAgentStateRenders } from "../context";
-import { parseJson } from "@copilotkit/shared";
-import { RenderStatus } from "./use-coagent-state-render-bridge.helpers";
-import { useStateRenderRegistry } from "./use-coagent-state-render-registry";
-
-/**
- * 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
- * ```
- */
-export interface CoAgentStateRenderBridgeProps {
-  message: any;
-  position: ReactCustomMessageRendererPosition;
-  runId: string;
-  messageIndex: number;
-  messageIndexInRun: number;
-  numberOfMessagesInRun: number;
-  agentId: string;
-  stateSnapshot: any;
-}
-
-export function useCoagentStateRenderBridge(
-  agentId: string,
-  props: CoAgentStateRenderBridgeProps,
-) {
-  const { stateSnapshot, message } = props;
-  const { coAgentStateRenders, claimsRef } = useCoAgentStateRenders();
-  const { agent } = useAgent({ agentId });
-  const [nodeName, setNodeName] = useState<string | undefined>(undefined);
-  const [, forceUpdate] = useState(0);
-
-  useEffect(() => {
-    if (!agent) return;
-    const subscriber: AgentSubscriber = {
-      onStateChanged: () => {
-        forceUpdate((value) => value + 1);
-      },
-      onStepStartedEvent: ({ event }) => {
-        if (event.stepName !== nodeName) {
-          setNodeName(event.stepName);
-        }
-      },
-      onStepFinishedEvent: ({ event }) => {
-        if (event.stepName === nodeName) {
-          setNodeName(undefined);
-        }
-      },
-    };
-
-    const { unsubscribe } = agent.subscribe(subscriber);
-    return () => {
-      unsubscribe();
-    };
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [agentId, nodeName]);
-
-  const getStateRender = useCallback(
-    (messageId: string) => {
-      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 stateRenderEntry = useMemo(
-    () => getStateRender(message.id),
-    [getStateRender, message.id],
-  );
-  const stateRenderId = stateRenderEntry?.[0];
-  const stateRender = stateRenderEntry?.[1];
-
-  const registryMessage = {
-    ...message,
-    runId: props.runId ?? message.runId,
-  };
-  const { canRender } = useStateRenderRegistry({
-    agentId,
-    stateRenderId,
-    message: registryMessage,
-    messageIndex: props.messageIndex,
-    stateSnapshot,
-    agentState: agent?.state,
-    agentMessages: agent?.messages,
-    claimsRef,
-  });
-
-  return useMemo(() => {
-    if (!stateRender || !stateRenderId) {
-      return null;
-    }
-    if (!canRender) {
-      return null;
-    }
-
-    if (stateRender.handler) {
-      stateRender.handler({
-        state: stateSnapshot
-          ? parseJson(stateSnapshot, stateSnapshot)
-          : (agent?.state ?? {}),
-        nodeName: nodeName ?? "",
-      });
-    }
-
-    if (stateRender.render) {
-      const status = agent?.isRunning
-        ? RenderStatus.InProgress
-        : RenderStatus.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: claimsRef.current[message.id].stateSnapshot ?? {},
-        nodeName: nodeName ?? "",
-      });
-    }
-  }, [
-    stateRender,
-    stateRenderId,
-    agent?.state,
-    agent?.isRunning,
-    nodeName,
-    message.id,
-    stateSnapshot,
-    canRender,
-  ]);
-}
-
-export function CoAgentStateRenderBridge(props: CoAgentStateRenderBridgeProps) {
-  return useCoagentStateRenderBridge(props.agentId, props);
-}

package/src/hooks/use-coagent-state-render-registry.ts

@@ -1,230 +0,0 @@
-import { useEffect } from "react";
-import {
-  areStatesEquals,
-  ClaimAction,
-  getEffectiveRunId,
-  isPlaceholderMessageId,
-  isPlaceholderMessageName,
-  readCachedMessageEntry,
-  resolveClaim,
-  selectSnapshot,
-  type Claim,
-  type ClaimsByMessageId,
-  type SnapshotCaches,
-  type StateRenderContext,
-} from "./use-coagent-state-render-bridge.helpers";
-
-export interface StateRenderRegistryInput {
-  agentId: string;
-  stateRenderId?: string;
-  message: { id: string; runId?: string; name?: string };
-  messageIndex?: number;
-  stateSnapshot?: any;
-  agentState?: any;
-  agentMessages?: Array<{ id: string; role?: string }>;
-  claimsRef: React.MutableRefObject<Record<string, Claim>>;
-}
-
-export interface StateRenderRegistryResult {
-  canRender: boolean;
-}
-
-const LAST_SNAPSHOTS_BY_RENDER_AND_RUN = "__lastSnapshotsByStateRenderIdAndRun";
-const LAST_SNAPSHOTS_BY_MESSAGE = "__lastSnapshotsByMessageId";
-
-type SnapshotByMessageEntry = { snapshot: any; runId?: string } | any;
-type ClaimsStore = Record<string, Claim> & {
-  [LAST_SNAPSHOTS_BY_RENDER_AND_RUN]?: Record<string, any>;
-  [LAST_SNAPSHOTS_BY_MESSAGE]?: Record<string, SnapshotByMessageEntry>;
-};
-
-function getClaimsStore(
-  claimsRef: React.MutableRefObject<Record<string, Claim>>,
-): ClaimsStore {
-  return claimsRef.current as ClaimsStore;
-}
-
-function getSnapshotCaches(
-  claimsRef: React.MutableRefObject<Record<string, Claim>>,
-): SnapshotCaches {
-  const store = getClaimsStore(claimsRef);
-  return {
-    byStateRenderAndRun: store[LAST_SNAPSHOTS_BY_RENDER_AND_RUN] ?? {},
-    byMessageId: store[LAST_SNAPSHOTS_BY_MESSAGE] ?? {},
-  };
-}
-
-export function useStateRenderRegistry({
-  agentId,
-  stateRenderId,
-  message,
-  messageIndex,
-  stateSnapshot,
-  agentState,
-  agentMessages,
-  claimsRef,
-}: StateRenderRegistryInput): StateRenderRegistryResult {
-  const store = getClaimsStore(claimsRef);
-  const runId = message.runId;
-  const cachedMessageEntry = store[LAST_SNAPSHOTS_BY_MESSAGE]?.[message.id];
-  const { runId: cachedMessageRunId } =
-    readCachedMessageEntry(cachedMessageEntry);
-  const existingClaimRunId = claimsRef.current[message.id]?.runId;
-  const effectiveRunId = getEffectiveRunId({
-    existingClaimRunId,
-    cachedMessageRunId,
-    runId,
-  });
-
-  useEffect(() => {
-    return () => {
-      const existingClaim = claimsRef.current[message.id];
-      if (
-        existingClaim?.stateSnapshot &&
-        Object.keys(existingClaim.stateSnapshot).length > 0
-      ) {
-        const snapshotCache = {
-          ...store[LAST_SNAPSHOTS_BY_RENDER_AND_RUN],
-        };
-        const cacheKey = `${existingClaim.stateRenderId}::${existingClaim.runId ?? "pending"}`;
-        snapshotCache[cacheKey] = existingClaim.stateSnapshot;
-        snapshotCache[`${existingClaim.stateRenderId}::latest`] =
-          existingClaim.stateSnapshot;
-        store[LAST_SNAPSHOTS_BY_RENDER_AND_RUN] = snapshotCache;
-
-        const messageCache = {
-          ...store[LAST_SNAPSHOTS_BY_MESSAGE],
-        };
-        messageCache[message.id] = {
-          snapshot: existingClaim.stateSnapshot,
-          runId: existingClaim.runId ?? effectiveRunId,
-        };
-        store[LAST_SNAPSHOTS_BY_MESSAGE] = messageCache;
-      }
-      delete claimsRef.current[message.id];
-    };
-  }, [claimsRef, effectiveRunId, message.id]);
-
-  if (!stateRenderId) {
-    return { canRender: false };
-  }
-
-  const caches = getSnapshotCaches(claimsRef);
-  const existingClaim = claimsRef.current[message.id] as Claim | undefined;
-
-  const { snapshot, hasSnapshotKeys, allowEmptySnapshot, snapshotForClaim } =
-    selectSnapshot({
-      messageId: message.id,
-      messageName: message.name,
-      allowLiveState:
-        isPlaceholderMessageName(message.name) ||
-        isPlaceholderMessageId(message.id),
-      skipLatestCache:
-        isPlaceholderMessageName(message.name) ||
-        isPlaceholderMessageId(message.id),
-      stateRenderId,
-      effectiveRunId,
-      stateSnapshotProp: stateSnapshot,
-      agentState,
-      agentMessages,
-      existingClaim,
-      caches,
-    });
-
-  const resolution = resolveClaim({
-    claims: claimsRef.current as ClaimsByMessageId,
-    context: {
-      agentId,
-      messageId: message.id,
-      stateRenderId,
-      runId: effectiveRunId,
-      messageIndex,
-    } satisfies StateRenderContext,
-    stateSnapshot: snapshotForClaim,
-  });
-
-  if (resolution.action === ClaimAction.Block) {
-    return { canRender: false };
-  }
-
-  if (resolution.updateRunId && claimsRef.current[message.id]) {
-    claimsRef.current[message.id].runId = resolution.updateRunId;
-  }
-
-  if (resolution.nextClaim) {
-    claimsRef.current[message.id] = resolution.nextClaim;
-  }
-
-  if (resolution.lockOthers) {
-    Object.entries(claimsRef.current).forEach(([id, claim]) => {
-      if (id !== message.id && claim.stateRenderId === stateRenderId) {
-        claim.locked = true;
-      }
-    });
-  }
-
-  if (existingClaim && !existingClaim.locked && agentMessages?.length) {
-    const indexInAgentMessages = agentMessages.findIndex(
-      (msg: any) => msg.id === message.id,
-    );
-    if (
-      indexInAgentMessages >= 0 &&
-      indexInAgentMessages < agentMessages.length - 1
-    ) {
-      existingClaim.locked = true;
-    }
-  }
-
-  const existingSnapshot = claimsRef.current[message.id].stateSnapshot;
-  const snapshotChanged =
-    stateSnapshot &&
-    existingSnapshot !== undefined &&
-    !areStatesEquals(existingSnapshot, snapshot);
-
-  if (
-    snapshot &&
-    (stateSnapshot || hasSnapshotKeys || allowEmptySnapshot) &&
-    (!claimsRef.current[message.id].locked || snapshotChanged)
-  ) {
-    if (!claimsRef.current[message.id].locked || snapshotChanged) {
-      claimsRef.current[message.id].stateSnapshot = snapshot;
-      const snapshotCache = {
-        ...store[LAST_SNAPSHOTS_BY_RENDER_AND_RUN],
-      };
-      const cacheKey = `${stateRenderId}::${effectiveRunId}`;
-      snapshotCache[cacheKey] = snapshot;
-      snapshotCache[`${stateRenderId}::latest`] = snapshot;
-      store[LAST_SNAPSHOTS_BY_RENDER_AND_RUN] = snapshotCache;
-      const messageCache = {
-        ...store[LAST_SNAPSHOTS_BY_MESSAGE],
-      };
-      messageCache[message.id] = { snapshot, runId: effectiveRunId };
-      store[LAST_SNAPSHOTS_BY_MESSAGE] = messageCache;
-      if (stateSnapshot) {
-        claimsRef.current[message.id].locked = true;
-      }
-    }
-  } else if (snapshotForClaim) {
-    const existingSnapshot = claimsRef.current[message.id].stateSnapshot;
-    if (!existingSnapshot) {
-      claimsRef.current[message.id].stateSnapshot = snapshotForClaim;
-      const snapshotCache = {
-        ...store[LAST_SNAPSHOTS_BY_RENDER_AND_RUN],
-      };
-      const cacheKey = `${stateRenderId}::${effectiveRunId}`;
-      snapshotCache[cacheKey] = snapshotForClaim;
-      snapshotCache[`${stateRenderId}::latest`] = snapshotForClaim;
-      store[LAST_SNAPSHOTS_BY_RENDER_AND_RUN] = snapshotCache;
-      const messageCache = {
-        ...store[LAST_SNAPSHOTS_BY_MESSAGE],
-      };
-      messageCache[message.id] = {
-        snapshot: snapshotForClaim,
-        runId: effectiveRunId,
-      };
-      store[LAST_SNAPSHOTS_BY_MESSAGE] = messageCache;
-    }
-  }
-
-  return { canRender: true };
-}

package/src/hooks/use-coagent-state-render.ts

@@ -1,163 +0,0 @@
-/**
- * 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" />
- */
-
-import { useRef, useContext, useEffect } from "react";
-import { CopilotContext } from "../context/copilot-context";
-import { randomId, CopilotKitAgentDiscoveryError } from "@copilotkit/shared";
-import { CoAgentStateRender } from "../types/coagent-action";
-import { useToast } from "../components/toast/toast-provider";
-import { useCoAgentStateRenders } from "../context/coagent-state-renders-context";
-
-/**
- * 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
- */
-
-// We implement useCoAgentStateRender dependency handling so that
-// the developer has the option to not provide any dependencies.
-// see useCopilotAction for more details about this approach.
-export function useCoAgentStateRender<T = any>(
-  action: CoAgentStateRender<T>,
-  dependencies?: any[],
-): void {
-  const { chatComponentsCache, availableAgents } = useContext(CopilotContext);
-  const {
-    setCoAgentStateRender,
-    removeCoAgentStateRender,
-    coAgentStateRenders,
-  } = useCoAgentStateRenders();
-  const idRef = useRef<string>(randomId());
-  const { setBannerError, addToast } = useToast();
-
-  useEffect(() => {
-    if (
-      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.`;
-
-      // Route to banner instead of toast for consistency
-      const agentError = new 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 === undefined) {
-    if (coAgentStateRenders[idRef.current]) {
-      coAgentStateRenders[idRef.current].handler = action.handler as any;
-      if (typeof action.render === "function") {
-        if (chatComponentsCache.current !== null) {
-          chatComponentsCache.current.coAgentStateRenders[key] = action.render;
-        }
-      }
-    }
-  }
-
-  useEffect(() => {
-    // Check for duplicates by comparing against all other actions
-    const currentId = idRef.current;
-    const hasDuplicate = Object.entries(coAgentStateRenders).some(
-      ([id, otherAction]) => {
-        // Skip comparing with self
-        if (id === currentId) return false;
-
-        // Different agent names are never duplicates
-        if (otherAction.name !== action.name) return false;
-
-        // Same agent names:
-        const hasNodeName = !!action.nodeName;
-        const hasOtherNodeName = !!otherAction.nodeName;
-
-        // If neither has nodeName, they're duplicates
-        if (!hasNodeName && !hasOtherNodeName) return true;
-
-        // If one has nodeName and other doesn't, they're not duplicates
-        if (hasNodeName !== hasOtherNodeName) return false;
-
-        // If both have nodeName, they're duplicates only if the names match
-        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]);
-
-  useEffect(() => {
-    setCoAgentStateRender(idRef.current, action as any);
-    if (chatComponentsCache.current !== null && action.render !== undefined) {
-      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 : undefined,
-    // dependencies set by the developer
-    ...(dependencies || []),
-  ]);
-}