@copilotkit/vue 2.0.0-rc.2 → 2.0.0-rc.21

package/src/v2/hooks/__tests__/use-threads.test.ts

@@ -4,6 +4,19 @@ import type { Ref } from "vue";
 import { describe, expect, it, beforeEach, vi } from "vitest";
 import { useCopilotKit } from "../../providers/useCopilotKit";
 
+/** Core's `ɵruntimeInfo` snapshot, built from a fake core's runtime fields. */
+function runtimeInfoOf(core: {
+  runtimeConnectionStatus: CopilotKitCoreRuntimeConnectionStatus;
+  threadEndpoints?: unknown;
+  intelligence?: unknown;
+}) {
+  return {
+    status: core.runtimeConnectionStatus,
+    threadEndpoints: core.threadEndpoints,
+    intelligence: core.intelligence,
+  };
+}
+
 type ThreadRecord = {
   id: string;
   organizationId: string;
@@ -54,7 +67,8 @@ function compareThreadsByActivity(left: ThreadRecord, right: ThreadRecord) {
   return rightKey.localeCompare(leftKey);
 }
 
-vi.mock("@copilotkit/core", () => {
+vi.mock("@copilotkit/core", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("@copilotkit/core")>();
   class MockChannel {
     topic: string;
     left = false;
@@ -118,6 +132,16 @@ vi.mock("@copilotkit/core", () => {
     private listeners = new Set<() => void>();
     private socket: MockSocket | null = null;
 
+    readonly selectors = {
+      threads: (state: ThreadState) => state.threads,
+      isLoading: (state: ThreadState) => state.isLoading,
+      error: (state: ThreadState) => state.error,
+      fetchMoreError: (state: ThreadState) => state.fetchMoreError,
+      hasNextPage: (state: ThreadState) => state.hasNextPage,
+      isFetchingNextPage: (state: ThreadState) => state.isFetchingNextPage,
+      isMutating: (state: ThreadState) => state.isMutating,
+    };
+
     start(): void {}
 
     stop(): void {
@@ -317,6 +341,10 @@ vi.mock("@copilotkit/core", () => {
       return this.state;
     }
 
+    getServerState(): ThreadState {
+      return { ...this.state, threads: [] };
+    }
+
     select<T>(selector: (state: ThreadState) => T) {
       return {
         subscribe: (callback: () => void) => {
@@ -357,6 +385,8 @@ vi.mock("@copilotkit/core", () => {
     ɵselectHasNextPage: select((state) => state.hasNextPage),
     ɵselectIsFetchingNextPage: select((state) => state.isFetchingNextPage),
     ɵselectIsMutating: select((state) => state.isMutating),
+    // The real view model, driving the mock store above.
+    ɵThreadsController: actual.ɵThreadsController,
   };
 });
 
@@ -394,6 +424,7 @@ const supportedThreadEndpoints: ThreadEndpointRuntimeInfo = {
 
 type MockCopilotKit = {
   runtimeUrl: string | undefined;
+  readonly ɵruntimeInfo: unknown;
   runtimeConnectionStatus: CopilotKitCoreRuntimeConnectionStatus;
   headers: Record<string, string>;
   /**
@@ -417,6 +448,9 @@ function setupCopilotKit(
 ) {
   const copilotkit = ref<MockCopilotKit>({
     runtimeUrl,
+    get ɵruntimeInfo() {
+      return runtimeInfoOf(this);
+    },
     runtimeConnectionStatus,
     headers: { Authorization: "Bearer test-token" },
     ɵheadersGeneration: 0,
@@ -965,6 +999,9 @@ describe("useThreads", () => {
       // exactly one list fetch (+ one subscribe after it lands).
       copilotkit.value = {
         ...copilotkit.value,
+        get ɵruntimeInfo() {
+          return runtimeInfoOf(this);
+        },
         runtimeConnectionStatus:
           CopilotKitCoreRuntimeConnectionStatus.Connected,
         intelligence: { wsUrl: "ws://localhost:4000/client" },
@@ -1020,6 +1057,9 @@ describe("useThreads", () => {
 
       copilotkit.value = {
         ...copilotkit.value,
+        get ɵruntimeInfo() {
+          return runtimeInfoOf(this);
+        },
         runtimeConnectionStatus:
           CopilotKitCoreRuntimeConnectionStatus.Disconnected,
       };
@@ -1216,8 +1256,9 @@ describe("useThreads", () => {
 
       expect(fetchMock).not.toHaveBeenCalled();
       expect(getResult().threads.value).toEqual([]);
-      const lastDispatched = getDispatchedContexts().at(-1);
-      expect(lastDispatched).toBeNull();
+      // Nothing was ever sent, so nothing is cleared either (no extra
+      // queued list fetch).
+      expect(getDispatchedContexts()).toEqual([]);
       // A disabled consumer must not be stuck in a permanent loading state:
       // preConnectLoading must factor in `enabled`, otherwise isLoading would
       // stay true forever since hasDispatchedContext never gets set.
@@ -1240,7 +1281,7 @@ describe("useThreads", () => {
       // Disabled: inert, not loading, no fetch.
       expect(getResult().isLoading.value).toBe(false);
       expect(fetchMock).not.toHaveBeenCalled();
-      expect(getDispatchedContexts().at(-1)).toBeNull();
+      expect(getDispatchedContexts().filter(Boolean)).toEqual([]);
 
       // Re-enable: the pre-connect loading indicator must re-arm (i.e.
       // hasDispatchedContext was reset to false on disable) so consumers see
@@ -1343,8 +1384,9 @@ describe("useThreads", () => {
 
       expect(fetchMock).not.toHaveBeenCalled();
       expect(getResult().threads.value).toEqual([]);
-      const lastDispatched = getDispatchedContexts().at(-1);
-      expect(lastDispatched).toBeNull();
+      // Nothing was ever sent, so nothing is cleared either (no extra
+      // queued list fetch).
+      expect(getDispatchedContexts()).toEqual([]);
       expect(getResult().error.value?.message).toBe(
         "Thread endpoints are not available on this CopilotKit runtime",
       );

package/src/v2/hooks/__tests__/zod-regression.test.ts

@@ -4,7 +4,7 @@
  *
  * Covers:
  * 1. useRenderTool with complex Zod schemas
- * 2. defineToolCallRenderer with Zod (named + wildcard default z.any())
+ * 2. defineToolCallRenderer with Zod (named + wildcard default schema)
  * 3. useComponent with Zod schemas
  * 4. The registered schema object is the original Zod instance (identity check)
  */
@@ -134,7 +134,7 @@ describe("useRenderTool Zod regression", () => {
     const schema = z.object({
       action: z.discriminatedUnion("type", [
         z.object({ type: z.literal("search"), query: z.string() }),
-        z.object({ type: z.literal("navigate"), url: z.string().url() }),
+        z.object({ type: z.literal("navigate"), url: z.url() }),
       ]),
     });
 
@@ -196,14 +196,15 @@ describe("useRenderTool Zod regression", () => {
 });
 
 describe("defineToolCallRenderer Zod regression", () => {
-  it("wildcard tool defaults to z.any() for args", () => {
+  it("wildcard tool defaults to a schema that accepts any value", () => {
     const renderer = defineToolCallRenderer({
       name: "*",
       render: () => "wildcard",
     });
 
     expect(renderer.name).toBe("*");
-    expect((renderer.args as any)["~standard"].vendor).toBe("zod");
+    const result = renderer.args["~standard"].validate({ city: "Paris" });
+    expect(result).toEqual({ value: { city: "Paris" } });
   });
 
   it("named tool with Zod args preserves schema identity", () => {

package/src/v2/hooks/use-agent-context.ts

@@ -1,14 +1,10 @@
 import { computed, toValue, watch } from "vue";
 import type { MaybeRefOrGetter } from "vue";
+import { ɵserializeContextValue } from "@copilotkit/core";
+import type { ɵJsonSerializable } from "@copilotkit/core";
 import { useCopilotKit } from "../providers/useCopilotKit";
 
-export type JsonSerializable =
-  | string
-  | number
-  | boolean
-  | null
-  | JsonSerializable[]
-  | { [key: string]: JsonSerializable };
+export type JsonSerializable = ɵJsonSerializable;
 
 export interface AgentContextInput {
   description: MaybeRefOrGetter<string>;
@@ -35,9 +31,7 @@ export function useAgentContext(context: AgentContextInput): void {
   const resolvedValue = computed(() => toValue(context.value));
 
   const stringValue = computed(() =>
-    typeof resolvedValue.value === "string"
-      ? resolvedValue.value
-      : JSON.stringify(resolvedValue.value),
+    ɵserializeContextValue(resolvedValue.value),
   );
 
   watch(

package/src/v2/hooks/use-agent.ts

@@ -1,15 +1,12 @@
 import { computed, shallowRef, toValue, triggerRef, watch } from "vue";
 import type { MaybeRefOrGetter } from "vue";
-import { DEFAULT_AGENT_ID } from "@copilotkit/shared";
 import type { AbstractAgent } from "@ag-ui/client";
 import {
-  ProxiedCopilotRuntimeAgent,
-  CopilotKitCoreRuntimeConnectionStatus,
-  ɵisHttpAgent,
-} from "@copilotkit/core";
-import type {
-  CopilotRuntimeTransport,
-  SubscribeToAgentSubscriber,
+  ɵgetAgentResolver,
+  ɵresolveAgentId,
+  ɵresolveAgentThreadId,
+  ɵsubscribeToAgentUpdates,
+  ɵvalidateAgentBinding,
 } from "@copilotkit/core";
 import { useCopilotKit } from "../providers/useCopilotKit";
 import { useCopilotChatConfiguration } from "../providers/useCopilotChatConfiguration";
@@ -126,7 +123,9 @@ export type UseAgentProps = UseAgentPropsBase &
  *
  * It returns a reactive `agent` ref that updates when the selected agent
  * changes, when runtime connection state changes, or when subscribed update
- * events fire.
+ * events fire, and an `isReady` ref: `false` while `agent` is a provisional
+ * stand-in used before the runtime `/info` sync lands (or after it failed),
+ * `true` once it is the real agent.
  *
  * @example
  * ```ts
@@ -134,348 +133,145 @@ export type UseAgentProps = UseAgentPropsBase &
  * ```
  */
 export function useAgent(props: UseAgentProps = {}) {
-  // `threadId`, `runtimeAgentId` and an explicit `agentId` are all-or-nothing.
-  // UseAgentProps rejects a partial set at compile time; these are the runtime
-  // backstop for callers TypeScript doesn't reach (plain JS, `as any`). Same
-  // three checks, same messages, as React's useAgent.
-  const hasThreadId = props.threadId !== undefined;
-  const hasRuntimeAgentId = props.runtimeAgentId !== undefined;
-  const hasAgentId = props.agentId !== undefined;
-
-  if (hasThreadId && !hasRuntimeAgentId) {
-    throw new Error(
-      "useAgent: `threadId` requires `runtimeAgentId`. A threadId is written onto a " +
-        "single agent, but an agent resolved by agentId alone is shared, so scoping a " +
-        "thread to it would clobber other useAgent callers. Pass a distinct local `agentId` " +
-        'and the runtime agent to route to, e.g. useAgent({ agentId: "chat-1", ' +
-        'runtimeAgentId: "assistant", threadId }).',
-    );
-  }
-
-  if (hasRuntimeAgentId && !hasThreadId) {
-    throw new Error(
-      "useAgent: `runtimeAgentId` requires `threadId`. A proxied agent exists to scope a " +
-        "thread to a private instance; without a threadId it behaves like the shared agent " +
-        "while adding a registration and a local agentId to keep unique. Either pass the " +
-        "thread, or bind to the agent directly with useAgent({ agentId }).",
-    );
-  }
-
-  if (hasRuntimeAgentId && !hasAgentId) {
-    throw new Error(
-      "useAgent: `runtimeAgentId` requires an explicit `agentId`. The proxied agent is " +
-        "registered under `agentId`, and the usual fallbacks (chat configuration, then " +
-        `"${DEFAULT_AGENT_ID}") name agents that already exist — registering over one throws ` +
-        "or shadows it. Pick a local id for this hook, e.g. " +
-        'useAgent({ agentId: "chat-1", runtimeAgentId: "assistant", threadId }).',
-    );
-  }
-
-  // After the guards, all three are present or none are.
-  const isThreadScoped = hasRuntimeAgentId;
+  // Runtime backstop for the all-or-nothing rule UseAgentProps enforces at
+  // compile time (plain JS, `as any`). Same checks and messages as React.
+  ɵvalidateAgentBinding({
+    agentId: toValue(props.agentId),
+    threadId: toValue(props.threadId),
+    runtimeAgentId: toValue(props.runtimeAgentId),
+  });
+  const isThreadScoped = props.runtimeAgentId !== undefined;
 
   const chatConfig = useCopilotChatConfiguration();
-  const agentId = computed(
-    () =>
-      toValue(props.agentId) ?? chatConfig.value?.agentId ?? DEFAULT_AGENT_ID,
+  const agentId = computed(() =>
+    ɵresolveAgentId({
+      agentId: toValue(props.agentId),
+      chatAgentId: chatConfig.value?.agentId,
+    }),
   );
   const runtimeAgentId = computed(() =>
     isThreadScoped ? toValue(props.runtimeAgentId) : undefined,
   );
-  // Mirrors React: an explicit `threadId` prop wins, otherwise the chat
-  // configuration's thread, gated on `hasExplicitThreadId` so a
-  // ThreadsProvider-minted placeholder UUID doesn't overwrite the agent's own
-  // auto-minted one (both are random and useless to the backend).
-  const resolvedThreadId = computed(
-    () =>
-      toValue(props.threadId) ??
-      (chatConfig.value?.hasExplicitThreadId
-        ? chatConfig.value.threadId
-        : undefined),
+  const resolvedThreadId = computed(() =>
+    ɵresolveAgentThreadId({
+      threadId: toValue(props.threadId),
+      chatThreadId: chatConfig.value?.threadId,
+      chatHasExplicitThreadId: chatConfig.value?.hasExplicitThreadId,
+    }),
   );
   const { copilotkit } = useCopilotKit();
+  const resolver = computed(() => ɵgetAgentResolver(copilotkit.value));
   const updateFlags = computed(() => props.updates ?? ALL_UPDATES);
   // Read the provider-level default so it appears in the subscribe watcher
-  // deps. `subscribeToAgentWithOptions` reads it from the core instance, but
-  // Vue still needs the dep to know when to resubscribe (same role it plays
-  // in React's `useEffect` dep array).
+  // deps: core reads it, but Vue needs the dep to resubscribe.
   const providerThrottleMs = computed(() => copilotkit.value.defaultThrottleMs);
   const hookThrottleMs = computed(() => toValue(props.throttleMs));
 
   const agent = shallowRef<AbstractAgent | null>(null);
-  const subscriptionAgent = shallowRef<AbstractAgent | null>(null);
-  const provisionalAgentCache = new Map<string, ProxiedCopilotRuntimeAgent>();
-
-  const createProvisionalAgent = (
-    id: string,
-    runtimeUrl: string,
-    transport: CopilotRuntimeTransport,
-  ) => {
-    const provisional = new ProxiedCopilotRuntimeAgent({
-      runtimeUrl,
-      agentId: id,
-      transport,
-      runtimeMode: "pending",
-    });
-    // Never invokes the headers builder — installs `ɵruntimeFetch` and
-    // own-only headers on this proxied agent, so a request it actually sends
-    // resolves the current headers at send time (#1937).
-    copilotkit.value.applyHeadersToAgent(provisional);
-    return provisional;
-  };
+  const isReady = shallowRef(false);
+  const resolverRevision = shallowRef(0);
+  watch(
+    resolver,
+    (current, _old, onCleanup) => {
+      onCleanup(
+        current.subscribe(() => {
+          resolverRevision.value = current.getSnapshot();
+        }),
+      );
+    },
+    { immediate: true },
+  );
 
-  // On the thread-scoped path this hook owns an agent registered under
-  // `agentId` that routes to `runtimeAgentId`. Register/unregister as one
-  // balanced watcher — the cleanup runs both when the ids change and when the
-  // scope is disposed. Mirrors React's registration effect, including its dep
-  // set (core identity plus the two ids).
-  const registeredProxy = shallowRef<AbstractAgent | null>(null);
+  // Thread-scoped path: this hook owns a proxied agent registered under
+  // `agentId` that routes to `runtimeAgentId`. The cleanup unregisters both
+  // when the ids change and when the scope is disposed.
   if (isThreadScoped) {
     watch(
-      [agentId, runtimeAgentId, () => copilotkit.value],
-      ([id, rtId], _old, onCleanup) => {
-        const { agent: proxy, unregister } =
-          copilotkit.value.registerProxiedAgent({
-            agentId: id as string,
-            runtimeAgentId: rtId as string,
-          });
-        provisionalAgentCache.delete(id as string);
-        registeredProxy.value = proxy;
-        onCleanup(() => {
-          unregister();
-          registeredProxy.value = null;
-        });
+      [agentId, runtimeAgentId, resolver],
+      ([id, rtId, current], _old, onCleanup) => {
+        if (rtId === undefined) return;
+        onCleanup(current.bindProxy({ agentId: id, runtimeAgentId: rtId }));
       },
       { immediate: true },
     );
   }
 
   const resolveAgent = () => {
-    const id = agentId.value;
-    const core = copilotkit.value;
-
-    // Proxied path: this hook registered its own agent, so bypass the shared
-    // registry lookup. Until registration lands, hand back a provisional proxy
-    // so `agent` is never null and its identity stays stable.
-    if (isThreadScoped) {
-      const proxy = registeredProxy.value;
-      if (proxy) {
-        provisionalAgentCache.delete(id);
-        const shouldForceUpdate = agent.value === proxy;
-        agent.value = proxy;
-        subscriptionAgent.value = proxy;
-        if (shouldForceUpdate) triggerRef(agent);
-        return;
-      }
-
-      const cachedProxy = provisionalAgentCache.get(id);
-      if (cachedProxy) {
-        core.applyHeadersToAgent(cachedProxy);
-        agent.value = cachedProxy;
-        subscriptionAgent.value = cachedProxy;
-        return;
-      }
-
-      const provisionalProxy = new ProxiedCopilotRuntimeAgent({
-        runtimeUrl: core.runtimeUrl,
-        agentId: id,
-        runtimeAgentId: runtimeAgentId.value as string,
-        transport: core.runtimeTransport,
-        runtimeMode: "pending",
-      });
-      core.applyHeadersToAgent(provisionalProxy);
-      provisionalAgentCache.set(id, provisionalProxy);
-      agent.value = provisionalProxy;
-      subscriptionAgent.value = provisionalProxy;
-      return;
-    }
-
-    const existing = core.getAgent(id);
-    if (existing) {
-      provisionalAgentCache.delete(id);
-
-      const shouldForceUpdate = agent.value === existing;
-      agent.value = existing;
-      subscriptionAgent.value = existing;
-      if (shouldForceUpdate) {
-        triggerRef(agent);
-      }
-      return;
-    }
-
-    const isRuntimeConfigured = core.runtimeUrl !== undefined;
-    const status = core.runtimeConnectionStatus;
-
-    if (
-      isRuntimeConfigured &&
-      (status === CopilotKitCoreRuntimeConnectionStatus.Disconnected ||
-        status === CopilotKitCoreRuntimeConnectionStatus.Connecting ||
-        status === CopilotKitCoreRuntimeConnectionStatus.Error)
-    ) {
-      const cached = provisionalAgentCache.get(id);
-      if (cached) {
-        core.applyHeadersToAgent(cached);
-        agent.value = cached;
-        subscriptionAgent.value = cached;
-        return;
-      }
-
-      const provisional = createProvisionalAgent(
-        id,
-        core.runtimeUrl!,
-        core.runtimeTransport,
-      );
-      provisionalAgentCache.set(id, provisional);
-      agent.value = provisional;
-      subscriptionAgent.value = provisional;
+    const resolved = resolver.value.resolve({
+      agentId: agentId.value,
+      runtimeAgentId: runtimeAgentId.value,
+      caller: "useAgent",
+    });
+    isReady.value = resolved.isReady;
+    if (agent.value === resolved.agent) {
+      triggerRef(agent);
       return;
     }
-
-    const knownAgents = Object.keys(core.agents ?? {});
-    const runtimePart = isRuntimeConfigured
-      ? `runtimeUrl=${core.runtimeUrl}`
-      : "no runtimeUrl";
-    throw new Error(
-      `useAgent: Agent '${id}' not found after runtime sync (${runtimePart}). ` +
-        (knownAgents.length
-          ? `Known agents: [${knownAgents.join(", ")}]`
-          : "No agents registered.") +
-        " Verify your runtime /info and/or agents__unsafe_dev_only.",
-    );
+    agent.value = resolved.agent;
   };
 
   // Keyed on `ɵheadersGeneration`, not header VALUES: a builder's returned
   // token can change on every resolution without a new source ever being
-  // set (a run refreshing the snapshot), and this must not re-run
-  // `resolveAgent` (and force-trigger `agent`) on that (#1937).
-  // A genuine source change (a real `setHeaders()` call) still re-runs it,
-  // refreshing a cached provisional's headers via the branches above.
+  // set, and this must not re-run `resolveAgent` on that (#1937).
   //
-  // `registeredProxy` is wrapped as a getter (`() => registeredProxy.value`)
-  // rather than passed directly: Vue's multi-source `watch` sets
-  // `forceTrigger = true` for the WHOLE array whenever any raw element is
-  // itself a shallowRef/reactive object, which makes the callback run on
-  // ANY dependency dirtying regardless of whether a source's value actually
-  // changed — silently defeating the `ɵheadersGeneration` rekey above (and
-  // every other source's diffing) the moment `registeredProxy` is present.
-  // A getter reads the same value without contributing to that flag.
+  // Sources are getters, not refs: Vue's multi-source `watch` force-triggers
+  // the whole array when any raw element is a shallowRef, which would defeat
+  // the diffing of every other source.
   watch(
     [
       agentId,
-      () => registeredProxy.value,
+      () => resolverRevision.value,
       () => copilotkit.value.agents,
       () => copilotkit.value.runtimeConnectionStatus,
       () => copilotkit.value.runtimeUrl,
       () => copilotkit.value.runtimeTransport,
       () => copilotkit.value.ɵheadersGeneration,
+      () => copilotkit.value.credentials,
     ],
     resolveAgent,
     { immediate: true },
   );
 
-  // Pin the resolved thread onto the current agent. AbstractAgent auto-mints a
-  // UUID when none is given, so without this the agent would ship its own random
-  // id in /agent/run, /agent/connect and /agent/stop. Deps are deliberately just
-  // the agent and the thread — matching React — so status/header churn cannot
-  // re-fire this and overwrite a thread `CopilotChat` pinned for its own chat.
-  // `() => agent.value`, not `agent`: Vue sets `forceTrigger` when any array
-  // watch source is a shallow ref, which would re-run this on every
-  // `triggerRef(agent)` — i.e. every streamed message — and re-pin a thread that
-  // `CopilotChat` may have deliberately overridden for the chat it renders. A
-  // getter fires only when the identity actually changes.
+  // Pin the resolved thread onto the current agent. Deps are just the agent
+  // identity and the thread, so status or header churn cannot re-pin a thread
+  // `CopilotChat` set for the chat it renders.
   watch(
     [() => agent.value, resolvedThreadId],
     ([currentAgent, threadId]) => {
       if (!currentAgent || !threadId) return;
-      currentAgent.threadId = threadId as string;
+      currentAgent.threadId = threadId;
     },
     { immediate: true },
   );
 
-  // Keyed on `ɵheadersGeneration`, not header VALUES: a builder's returned
-  // token can change on every resolution without a new source ever being set,
-  // and this watcher must not re-fire on that (see #1937).
   watch(
-    [subscriptionAgent, () => copilotkit.value.ɵheadersGeneration],
+    [
+      () => agent.value,
+      () => copilotkit.value.ɵheadersGeneration,
+      () => copilotkit.value.credentials,
+    ],
     ([currentAgent]) => {
-      if (ɵisHttpAgent(currentAgent)) {
-        copilotkit.value.applyHeadersToAgent(currentAgent);
-      }
+      if (currentAgent) resolver.value.refreshRequestSettings(currentAgent);
     },
     { immediate: true },
   );
 
-  // Subscribe through the shared `CopilotKitCore.subscribeToAgentWithOptions`
-  // API. Core owns:
-  //   - shared leading+trailing throttle window across `onMessagesChanged`
-  //     and `onStateChanged` (parity with React)
-  //   - safeCall-guarded callbacks (errors in subscribers never poison the
-  //     agent notification loop)
-  //   - validation/fallback for invalid `throttleMs`
-  //   - `onRunErrorEvent` in the run-status callback set
-  //
-  // The hook only schedules a microtask-batched `triggerRef(agent)` so
-  // multiple synchronous notifications (e.g. state + run-status firing in
-  // the same tick) coalesce into a single Vue re-render — matching React's
-  // `queueMicrotask`-batched forceUpdate strategy.
+  // Core owns throttling, safe callbacks and `throttleMs` validation; the
+  // re-render is microtask-batched so notifications in one tick coalesce.
   watch(
-    [subscriptionAgent, updateFlags, hookThrottleMs, providerThrottleMs],
-    ([a, flags], _old, onCleanup) => {
-      const f = flags as UseAgentUpdate[];
-      if (!a || f.length === 0) return;
-
-      let active = true;
-      let batchScheduled = false;
-      const batchedRefresh = () => {
-        if (!active) return;
-        if (!batchScheduled) {
-          batchScheduled = true;
-          queueMicrotask(() => {
-            batchScheduled = false;
-            if (active) {
-              triggerRef(agent);
-            }
-          });
-        }
-      };
-
-      const handlers: SubscribeToAgentSubscriber = {};
-
-      if (f.includes(UseAgentUpdate.OnMessagesChanged)) {
-        // Messages fire immediately (no microtask indirection) so shared-
-        // window throttling in core sees an unadorned callback. Matches
-        // React's `handlers.onMessagesChanged = forceUpdate`.
-        handlers.onMessagesChanged = () => {
-          if (active) triggerRef(agent);
-        };
-      }
-
-      if (f.includes(UseAgentUpdate.OnStateChanged)) {
-        handlers.onStateChanged = batchedRefresh;
-      }
-
-      if (f.includes(UseAgentUpdate.OnRunStatusChanged)) {
-        handlers.onRunInitialized = batchedRefresh;
-        handlers.onRunFinalized = batchedRefresh;
-        handlers.onRunFailed = batchedRefresh;
-        // Protocol-level RUN_ERROR event (distinct from `onRunFailed`
-        // which handles local exceptions like network errors).
-        handlers.onRunErrorEvent = batchedRefresh;
-      }
-
-      const subscription = copilotkit.value.subscribeToAgentWithOptions(
-        a as AbstractAgent,
-        handlers,
-        { throttleMs: toValue(props.throttleMs) },
+    [() => agent.value, updateFlags, hookThrottleMs, providerThrottleMs],
+    ([currentAgent, flags], _old, onCleanup) => {
+      if (!currentAgent) return;
+      onCleanup(
+        ɵsubscribeToAgentUpdates(copilotkit.value, currentAgent, {
+          updates: flags,
+          throttleMs: toValue(props.throttleMs),
+          onUpdate: () => triggerRef(agent),
+        }),
       );
-
-      onCleanup(() => {
-        active = false;
-        subscription.unsubscribe();
-      });
     },
     { immediate: true },
   );
 
-  return { agent };
+  return { agent, isReady };
 }