@copilotkit/react-core 1.64.1 → 1.64.2-canary.1785346263

package/dist/v2/headless.d.cts

@@ -397,12 +397,7 @@ declare enum UseAgentUpdate {
   OnStateChanged = "OnStateChanged",
   OnRunStatusChanged = "OnRunStatusChanged"
 }
-interface UseAgentProps {
-  /**
-   * Agent to bind to. Resolution precedence: this property, then the surrounding
-   * chat configuration's agentId, then the global default.
-   */
-  agentId?: string;
+interface UseAgentPropsBase {
   updates?: UseAgentUpdate[];
   /**
    * Throttle interval (in milliseconds) for re-renders triggered by
@@ -428,8 +423,96 @@ interface UseAgentProps {
    */
   throttleMs?: number;
 }
+/**
+ * Thread-scoped variant. `agentId`, `runtimeAgentId`, and `threadId` are a
+ * matched set: together they give this hook a *private* agent — registered
+ * under the local `agentId`, routing outbound to `runtimeAgentId` — that is
+ * safe to pin a thread onto. None of the three is meaningful without the other
+ * two, so all are required here.
+ */
+interface UseAgentThreadScopedProps {
+  /**
+   * The name to register this hook's proxied agent under.
+   *
+   * Required, and must not already be taken. The usual fallbacks (the chat
+   * configuration's agentId, then `DEFAULT_AGENT_ID`) name agents that already
+   * exist, and registering over one either throws `already registered` or
+   * silently shadows it, depending on whether runtime discovery has landed — so
+   * the caller has to name it.
+   */
+  agentId: string;
+  /**
+   * Thread to scope the agent's run to. Written onto the underlying agent, so
+   * `/agent/run`, `/agent/connect`, and `/agent/stop` address this thread.
+   *
+   * REQUIRES `runtimeAgentId`. A runtime agent registered under a given id is a
+   * singleton, so writing a per-hook threadId directly onto it would let two
+   * `useAgent` calls that share an `agentId` clobber each other's thread.
+   * Passing a distinct local `agentId` plus the `runtimeAgentId` it routes to
+   * gives this hook a private proxied agent to pin the thread onto instead of a
+   * shared one.
+   */
+  threadId: string;
+  /**
+   * The id of the runtime agent to route outbound requests to, while this hook
+   * exposes a distinct local `agentId`. Registers a proxied agent via
+   * `CopilotKitCore.registerProxiedAgent`, letting several frontend agents
+   * (e.g. one per open thread) mount against a single runtime agent without a
+   * shared-singleton collision.
+   *
+   * When set, `agentId` is the *local* registry id (must not collide with an
+   * existing local or runtime-discovered agent) and `runtimeAgentId` is the
+   * runtime agent the proxy addresses on `/agent/run` etc.
+   *
+   * REQUIRES `threadId`. Registering a private agent is only worth doing to
+   * scope a thread to it; without a `threadId` the private agent would take its
+   * thread from the chat configuration, which is what binding to the shared
+   * agent via `agentId` alone already does — just with an extra registration
+   * and a local id to keep unique.
+   */
+  runtimeAgentId: string;
+}
+/**
+ * Default variant: neither `threadId` nor `runtimeAgentId`. The hook binds to
+ * the shared agent registered under `agentId` and leaves its threadId to the
+ * chat configuration (or to the agent's own auto-minted UUID).
+ *
+ * Both props are typed `undefined` here rather than omitted so that supplying
+ * either one on its own fails to match *both* branches — that is the
+ * type-level enforcement of the all-or-nothing rule.
+ */
+interface UseAgentUnscopedProps {
+  /**
+   * Agent to bind to. Resolution precedence: this property, then the surrounding
+   * chat configuration's agentId, then the global default.
+   */
+  agentId?: string;
+  /** Requires `runtimeAgentId`. See {@link UseAgentThreadScopedProps.threadId}. */
+  threadId?: undefined;
+  /** Requires `threadId`. See {@link UseAgentThreadScopedProps.runtimeAgentId}. */
+  runtimeAgentId?: undefined;
+}
+/**
+ * Props for {@link useAgent}.
+ *
+ * There are exactly two valid shapes, and the type admits nothing in between:
+ *
+ * - **Bind to an agent** — `useAgent()`, `useAgent({ agentId })`. The shared
+ *   instance from the registry; the thread comes from the chat configuration.
+ * - **Bind a private agent to a thread** —
+ *   `useAgent({ agentId, runtimeAgentId, threadId })`. All three required.
+ *
+ * So `useAgent({ agentId, threadId })`, `useAgent({ agentId, runtimeAgentId })`,
+ * and `useAgent({ runtimeAgentId, threadId })` are all compile errors. Each
+ * partial combination is either unsafe (a thread scoped onto a shared singleton)
+ * or pointless (a private agent with no thread, or one registered over an id
+ * that already belongs to a real agent).
+ */
+type UseAgentProps = UseAgentPropsBase & (UseAgentThreadScopedProps | UseAgentUnscopedProps);
 declare function useAgent({
   agentId,
+  threadId,
+  runtimeAgentId,
   updates,
   throttleMs
 }?: UseAgentProps): {

package/dist/v2/headless.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"headless.d.cts","names":[],"sources":["../../src/v2/types/react-tool-call-renderer.ts","../../src/v2/types/react-activity-message-renderer.ts","../../src/v2/types/react-custom-message-renderer.ts","../../src/v2/types/frontend-tool.ts","../../src/v2/types/human-in-the-loop.ts","../../src/v2/types/defineToolCallRenderer.ts","../../src/v2/types/interrupt.ts","../../src/v2/lib/react-core.ts","../../src/v2/context.ts","../../src/v2/providers/CopilotChatConfigurationProvider.tsx","../../src/v2/hooks/use-agent.tsx","../../src/v2/hooks/use-frontend-tool.tsx","../../src/v2/hooks/use-component.tsx","../../src/v2/hooks/use-human-in-the-loop.tsx","../../src/v2/hooks/use-interrupt.tsx","../../src/v2/hooks/use-suggestions.tsx","../../src/v2/hooks/use-configure-suggestions.tsx","../../src/v2/hooks/use-agent-context.tsx","../../src/v2/hooks/use-threads.tsx","../../src/v2/hooks/use-render-tool.tsx","../../src/v2/hooks/use-render-tool-call.tsx","../../src/v2/hooks/use-capabilities.tsx"],"mappings":"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"}
+{"version":3,"file":"headless.d.cts","names":[],"sources":["../../src/v2/types/react-tool-call-renderer.ts","../../src/v2/types/react-activity-message-renderer.ts","../../src/v2/types/react-custom-message-renderer.ts","../../src/v2/types/frontend-tool.ts","../../src/v2/types/human-in-the-loop.ts","../../src/v2/types/defineToolCallRenderer.ts","../../src/v2/types/interrupt.ts","../../src/v2/lib/react-core.ts","../../src/v2/context.ts","../../src/v2/providers/CopilotChatConfigurationProvider.tsx","../../src/v2/hooks/use-agent.tsx","../../src/v2/hooks/use-frontend-tool.tsx","../../src/v2/hooks/use-component.tsx","../../src/v2/hooks/use-human-in-the-loop.tsx","../../src/v2/hooks/use-interrupt.tsx","../../src/v2/hooks/use-suggestions.tsx","../../src/v2/hooks/use-configure-suggestions.tsx","../../src/v2/hooks/use-agent-context.tsx","../../src/v2/hooks/use-threads.tsx","../../src/v2/hooks/use-render-tool.tsx","../../src/v2/hooks/use-render-tool-call.tsx","../../src/v2/hooks/use-capabilities.tsx"],"mappings":"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"}

package/dist/v2/headless.d.mts

@@ -121,12 +121,7 @@ declare enum UseAgentUpdate {
   OnStateChanged = "OnStateChanged",
   OnRunStatusChanged = "OnRunStatusChanged"
 }
-interface UseAgentProps {
-  /**
-   * Agent to bind to. Resolution precedence: this property, then the surrounding
-   * chat configuration's agentId, then the global default.
-   */
-  agentId?: string;
+interface UseAgentPropsBase {
   updates?: UseAgentUpdate[];
   /**
    * Throttle interval (in milliseconds) for re-renders triggered by
@@ -152,8 +147,96 @@ interface UseAgentProps {
    */
   throttleMs?: number;
 }
+/**
+ * Thread-scoped variant. `agentId`, `runtimeAgentId`, and `threadId` are a
+ * matched set: together they give this hook a *private* agent — registered
+ * under the local `agentId`, routing outbound to `runtimeAgentId` — that is
+ * safe to pin a thread onto. None of the three is meaningful without the other
+ * two, so all are required here.
+ */
+interface UseAgentThreadScopedProps {
+  /**
+   * The name to register this hook's proxied agent under.
+   *
+   * Required, and must not already be taken. The usual fallbacks (the chat
+   * configuration's agentId, then `DEFAULT_AGENT_ID`) name agents that already
+   * exist, and registering over one either throws `already registered` or
+   * silently shadows it, depending on whether runtime discovery has landed — so
+   * the caller has to name it.
+   */
+  agentId: string;
+  /**
+   * Thread to scope the agent's run to. Written onto the underlying agent, so
+   * `/agent/run`, `/agent/connect`, and `/agent/stop` address this thread.
+   *
+   * REQUIRES `runtimeAgentId`. A runtime agent registered under a given id is a
+   * singleton, so writing a per-hook threadId directly onto it would let two
+   * `useAgent` calls that share an `agentId` clobber each other's thread.
+   * Passing a distinct local `agentId` plus the `runtimeAgentId` it routes to
+   * gives this hook a private proxied agent to pin the thread onto instead of a
+   * shared one.
+   */
+  threadId: string;
+  /**
+   * The id of the runtime agent to route outbound requests to, while this hook
+   * exposes a distinct local `agentId`. Registers a proxied agent via
+   * `CopilotKitCore.registerProxiedAgent`, letting several frontend agents
+   * (e.g. one per open thread) mount against a single runtime agent without a
+   * shared-singleton collision.
+   *
+   * When set, `agentId` is the *local* registry id (must not collide with an
+   * existing local or runtime-discovered agent) and `runtimeAgentId` is the
+   * runtime agent the proxy addresses on `/agent/run` etc.
+   *
+   * REQUIRES `threadId`. Registering a private agent is only worth doing to
+   * scope a thread to it; without a `threadId` the private agent would take its
+   * thread from the chat configuration, which is what binding to the shared
+   * agent via `agentId` alone already does — just with an extra registration
+   * and a local id to keep unique.
+   */
+  runtimeAgentId: string;
+}
+/**
+ * Default variant: neither `threadId` nor `runtimeAgentId`. The hook binds to
+ * the shared agent registered under `agentId` and leaves its threadId to the
+ * chat configuration (or to the agent's own auto-minted UUID).
+ *
+ * Both props are typed `undefined` here rather than omitted so that supplying
+ * either one on its own fails to match *both* branches — that is the
+ * type-level enforcement of the all-or-nothing rule.
+ */
+interface UseAgentUnscopedProps {
+  /**
+   * Agent to bind to. Resolution precedence: this property, then the surrounding
+   * chat configuration's agentId, then the global default.
+   */
+  agentId?: string;
+  /** Requires `runtimeAgentId`. See {@link UseAgentThreadScopedProps.threadId}. */
+  threadId?: undefined;
+  /** Requires `threadId`. See {@link UseAgentThreadScopedProps.runtimeAgentId}. */
+  runtimeAgentId?: undefined;
+}
+/**
+ * Props for {@link useAgent}.
+ *
+ * There are exactly two valid shapes, and the type admits nothing in between:
+ *
+ * - **Bind to an agent** — `useAgent()`, `useAgent({ agentId })`. The shared
+ *   instance from the registry; the thread comes from the chat configuration.
+ * - **Bind a private agent to a thread** —
+ *   `useAgent({ agentId, runtimeAgentId, threadId })`. All three required.
+ *
+ * So `useAgent({ agentId, threadId })`, `useAgent({ agentId, runtimeAgentId })`,
+ * and `useAgent({ runtimeAgentId, threadId })` are all compile errors. Each
+ * partial combination is either unsafe (a thread scoped onto a shared singleton)
+ * or pointless (a private agent with no thread, or one registered over an id
+ * that already belongs to a real agent).
+ */
+type UseAgentProps = UseAgentPropsBase & (UseAgentThreadScopedProps | UseAgentUnscopedProps);
 declare function useAgent({
   agentId,
+  threadId,
+  runtimeAgentId,
   updates,
   throttleMs
 }?: UseAgentProps): {

package/dist/v2/headless.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"headless.d.mts","names":[],"sources":["../../src/v2/providers/CopilotChatConfigurationProvider.tsx","../../src/v2/hooks/use-agent.tsx","../../src/v2/types/react-tool-call-renderer.ts","../../src/v2/types/frontend-tool.ts","../../src/v2/hooks/use-frontend-tool.tsx","../../src/v2/hooks/use-component.tsx","../../src/v2/types/human-in-the-loop.ts","../../src/v2/hooks/use-human-in-the-loop.tsx","../../src/v2/types/interrupt.ts","../../src/v2/hooks/use-interrupt.tsx","../../src/v2/hooks/use-suggestions.tsx","../../src/v2/hooks/use-configure-suggestions.tsx","../../src/v2/hooks/use-agent-context.tsx","../../src/v2/hooks/use-threads.tsx","../../src/v2/hooks/use-render-tool.tsx","../../src/v2/hooks/use-render-tool-call.tsx","../../src/v2/types/defineToolCallRenderer.ts","../../src/v2/hooks/use-capabilities.tsx"],"mappings":"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"}
+{"version":3,"file":"headless.d.mts","names":[],"sources":["../../src/v2/providers/CopilotChatConfigurationProvider.tsx","../../src/v2/hooks/use-agent.tsx","../../src/v2/types/react-tool-call-renderer.ts","../../src/v2/types/frontend-tool.ts","../../src/v2/hooks/use-frontend-tool.tsx","../../src/v2/hooks/use-component.tsx","../../src/v2/types/human-in-the-loop.ts","../../src/v2/hooks/use-human-in-the-loop.tsx","../../src/v2/types/interrupt.ts","../../src/v2/hooks/use-interrupt.tsx","../../src/v2/hooks/use-suggestions.tsx","../../src/v2/hooks/use-configure-suggestions.tsx","../../src/v2/hooks/use-agent-context.tsx","../../src/v2/hooks/use-threads.tsx","../../src/v2/hooks/use-render-tool.tsx","../../src/v2/hooks/use-render-tool-call.tsx","../../src/v2/types/defineToolCallRenderer.ts","../../src/v2/hooks/use-capabilities.tsx"],"mappings":";;;;;;;;cAgBa,wBAAA;;;;;;;;;;;;;;;;;;;;;;KAwBD,iBAAA,UAA2B,wBAAA;AAAA,UA6BtB,6BAAA;EACf,MAAA,EAAQ,iBAAA;EACR,OAAA;EACA,QAAA;EACA,WAAA;EACA,YAAA,GAAe,IAAA;;;;AAlCjB;;EAwCE,UAAA;EAxCqC;;AA6BvC;;;EAiBE,aAAA,GAAgB,IAAA;EAhBhB;;;;;EAsBA,gBAAA;EAlBe;;;;;;;EA0Bf,cAAA;EAWuB;;;;;;;;;AA4CzB;EA5CE,oBAAA,GAAuB,UAAA,GAAa,IAAA;EAKpC,mBAAA;EAwCU;;;;;;;;;;;;;;;;AAcZ;EApCE,iBAAA,GACE,QAAA,UACA,OAAA;IAAY,QAAA;EAAA;EAkC+B;;;;;AAoV/C;;;;EA3WE,cAAA;AAAA;AAAA,UAQe,qCAAA;EACf,QAAA,EAAU,SAAA;EACV,MAAA,GAAS,OAAA,CAAQ,iBAAA;EACjB,OAAA;EACA,QAAA;EAMA,mBAAA;EACA,kBAAA;AAAA;AAAA,cAIW,gCAAA,EAAkC,OAAA,CAAM,EAAA,CACnD,qCAAA;AAAA,cAmVW,2BAAA,QACP,6BAAA;;;aCnfM,cAAA;EACV,iBAAA;EACA,cAAA;EACA,kBAAA;AAAA;AAAA,UASQ,iBAAA;EACR,OAAA,GAAU,cAAA;EDTC;;;;;;;;;;;;;;;;;;;;;;ECgCX,UAAA;AAAA;;;ADRF;;;;;UCkBU,yBAAA;EDWoC;;;;;;;;;ECD5C,OAAA;EDYA;;;;;;;;;;;ECAA,QAAA;EDwDE;;;;AAmBJ;;;;;;;;;;;;;ECzDE,cAAA;AAAA;;;;;ADwEF;;;;;UC5DU,qBAAA;ED6DR;;;AAmVF;EC3YE,OAAA;;EAEA,QAAA;ED0YiC;ECxYjC,cAAA;AAAA;;AA3GF;;;;;;;;;AAIC;;;;;;KA0HW,aAAA,GAAgB,iBAAA,IACzB,yBAAA,GAA4B,qBAAA;AAAA,iBAEf,QAAA,CAAA;EACd,OAAA;EACA,QAAA;EACA,cAAA;EACA,OAAA;EACA;AAAA,IACC,aAAA;;EAzFO;;;;;;;;;AAwCM;;;;;;;;;UC/FC,qBAAA;EACf,IAAA;;;;;EAKA,IAAA,GAAO,gBAAA,MAAsB,CAAA;EF6B9B;;;;EExBC,OAAA;EACA,MAAA,EAAQ,KAAA,CAAM,aAAA;IAER,IAAA;IACA,UAAA;IACA,IAAA,EAAM,OAAA,CAAQ,CAAA;IACd,MAAA,EAAQ,cAAA,CAAe,UAAA;IACvB,MAAA;EAAA;IAGA,IAAA;IACA,UAAA;IACA,IAAA,EAAM,CAAA;IACN,MAAA,EAAQ,cAAA,CAAe,SAAA;IACvB,MAAA;EAAA;IAGA,IAAA;IACA,UAAA;IACA,IAAA,EAAM,CAAA;IACN,MAAA,EAAQ,cAAA,CAAe,QAAA;IACvB,MAAA;EAAA;AAAA;;;KChCI,iBAAA,WACA,MAAA,oBAA0B,MAAA,qBAClC,YAAA,CAAa,CAAA;EACf,MAAA,GAAS,qBAAA,CAAsB,CAAA;AAAA;;;iBCAjB,eAAA,WACJ,MAAA,oBAA0B,MAAA,kBAAA,CACpC,IAAA,EAAM,iBAAA,CAAkB,CAAA,GAAI,IAAA,GAAO,aAAA;;;KCJhC,gBAAA,MAAsB,CAAA,SAAU,gBAAA,GACjC,iBAAA,CAAkB,CAAA;;;;;;ALWtB;;;;;;;;;;;;;;;;;;;;;;;;;;AAwBA;;;;;AA6BA;;;;;;;;;;;;;;iBKXgB,YAAA,iBACE,gBAAA,MAAsB,MAAA,2CAAA,CAGtC,MAAA;EACE,IAAA;EACA,WAAA;EACA,UAAA,GAAa,OAAA;EACb,MAAA,EAAQ,aAAA,CAAc,OAAA,CAAQ,gBAAA,CAAiB,OAAA;EAC/C,OAAA;EACA,QAAA;AAAA,GAEF,IAAA,GAAO,aAAA;;;KCnEG,mBAAA,WACA,MAAA,oBAA0B,MAAA,qBAClC,IAAA,CAAK,YAAA,CAAa,CAAA;;;;;;ANWtB;;;;;;;;;;;EMME,MAAA,EAAQ,OAAA,CAAM,aAAA;IAER,IAAA;IACA,WAAA;IACA,UAAA;IACA,OAAA;IACA,IAAA,EAAM,OAAA,CAAQ,CAAA;IACd,MAAA,EAAQ,cAAA,CAAe,UAAA;IACvB,MAAA;IACA,OAAA;EAAA;IAGA,IAAA;IACA,WAAA;IACA,UAAA;IACA,OAAA;IACA,IAAA,EAAM,CAAA;IACN,MAAA,EAAQ,cAAA,CAAe,SAAA;IACvB,MAAA;IACA,OAAA,GAAU,MAAA,cAAoB,OAAA;EAAA;IAG9B,IAAA;IACA,WAAA;IACA,UAAA;IACA,OAAA;IACA,IAAA,EAAM,CAAA;IACN,MAAA,EAAQ,cAAA,CAAe,QAAA;IACvB,MAAA;IACA,OAAA;EAAA;AAAA;;;iBC1CQ,iBAAA,WACJ,MAAA,oBAA0B,MAAA,kBAAA,CACpC,IAAA,EAAM,mBAAA,CAAoB,CAAA,GAAI,IAAA,GAAO,aAAA;;;;UCNtB,cAAA;EACf,IAAA;EACA,KAAA,EAAO,MAAA;AAAA;;ARST;;;;;;;KQEY,kBAAA,IACV,OAAA,YACA,WAAA,cACG,OAAA,CAAQ,cAAA;;;;;;;;KASD,iBAAA,IACV,WAAA,cACG,OAAA,CAAQ,cAAA;AAAA,UAEI,qBAAA;;;;;;EAMf,KAAA,EAAO,cAAA,CAAe,MAAA;;EAEtB,SAAA,EAAW,SAAA;;EAEX,UAAA,EAAY,SAAA;EACZ,OAAA,EAAS,kBAAA;EACT,MAAA,EAAQ,iBAAA;AAAA;AAAA,UAGO,oBAAA;EACf,KAAA,EAAO,cAAA,CAAe,MAAA;EACtB,SAAA,EAAW,SAAA;EACX,UAAA,EAAY,SAAA;EACZ,MAAA,EAAQ,OAAA;EACR,OAAA,EAAS,kBAAA;EACT,MAAA,EAAQ,iBAAA;AAAA;;;KCnBL,kBAAA,qBACH,KAAA,EAAO,qBAAA,CAAsB,MAAA,MAC1B,OAAA,GAAU,WAAA,CAAY,OAAA;AAAA,KAEtB,0BAAA,aAAuC,QAAA,cACvC,IAAA,+BAED,OAAA,SAAgB,WAAA,oBACd,SAAA,UACA,OAAA;AAAA,KAGD,eAAA,oBAAmC,0BAAA,CACtC,kBAAA,CAAmB,MAAA,EAAQ,OAAA;AAAA,KAGxB,qBAAA;AAAA,KAEA,kBAAA,uBAAyC,qBAAA,IAC5C,aAAA,iBACI,OAAA,CAAM,YAAA,UACN,aAAA,mCAEE,OAAA,CAAM,YAAA;;;;UAqBJ,sBAAA;;;;;;;EAOR,MAAA,GACE,KAAA,EAAO,oBAAA,CAAqB,MAAA,EAAQ,eAAA,CAAgB,MAAA,EAAQ,OAAA,OACzD,OAAA,CAAM,YAAA;;;;;;EAMX,OAAA,GAAU,kBAAA,CAAmB,MAAA,EAAQ,OAAA;;;;;;EAMrC,OAAA,IAAW,KAAA,EAAO,cAAA,CAAe,MAAA;;EAEjC,OAAA;AAAA;AAAA,KA2BU,kBAAA,0DAGY,qBAAA,gBACpB,sBAAA,CAAuB,MAAA,EAAQ,OAAA;ET5DlB,0FS8Df,YAAA,GAAe,aAAA;AAAA;;;;;;;;;;;;;;;ATmBjB;;;;;;;;;;;;;iBSYgB,YAAA,wCAEQ,qBAAA,aAAA,CAEtB,MAAA,EAAQ,kBAAA,MAAwB,OAAA,EAAS,aAAA,IACxC,kBAAA,CAAmB,aAAA;;;UCtKL,qBAAA;EACf,OAAA;AAAA;AAAA,UAGe,oBAAA;EACf,WAAA,EAAa,UAAA;EACb,iBAAA;EACA,gBAAA;EACA,SAAA;AAAA;AAAA,iBAGc,cAAA,CAAA;EACd;AAAA,IACC,qBAAA,GAA6B,oBAAA;;;KCR3B,qBAAA,GAAwB,IAAA,CAAK,UAAA,iBAChC,OAAA,CAAQ,IAAA,CAAK,UAAA;AAAA,KAEV,4BAAA,GAA+B,IAAA,CAClC,uBAAA;EAGA,WAAA,EAAa,qBAAA;AAAA;AAAA,KAGV,sBAAA,GACD,wBAAA,GACA,4BAAA;AAAA,iBAEY,uBAAA,CACd,MAAA,EAAQ,sBAAA,qBACR,IAAA,GAAO,aAAA;;;;;;KCrBG,gBAAA,sCAKR,gBAAA;EAAA,CACG,GAAA,WAAc,gBAAA;AAAA;;;AZIrB;;UYEiB,iBAAA;EZoBhB;EYlBC,WAAA;;EAEA,KAAA,EAAO,gBAAA;AAAA;AAAA,iBAGO,eAAA,CAAgB,OAAA,EAAS,iBAAA;;;;;;;;;UCExB,MAAA;EACf,EAAA;EACA,OAAA;EACA,IAAA;EACA,QAAA;EACA,SAAA;EACA,SAAA;;;;;;;EAOA,SAAA;AAAA;;;;;;;UASe,eAAA;;EAEf,OAAA;;EAEA,eAAA;;EAEA,KAAA;EbfU;;;;;AA6BZ;;;;EaJE,OAAA;AAAA;;;;;;;;UAUe,gBAAA;EbiBf;;;;;EaXA,OAAA,EAAS,MAAA;EbqDT;;;;EahDA,SAAA;Eb6Dc;;AAQhB;;;;;;;;Ea1DE,KAAA,EAAO,KAAA;Eb2DG;;;;;;;EanDV,SAAA,EAAW,KAAA;Eb6DO;;AAIpB;;;;;EazDE,cAAA,EAAgB,KAAA;Eb0DhB;;;AAmVF;EaxYE,cAAA;;;;EAIA,qBAAA;;;AZ9GF;;;;EYqHE,UAAA;EZnHA;;;;EYwHA,gBAAA;EZ9GyB;;;;;EYoHzB,cAAA;EZ5FU;;AAAA;;;EYkGV,cAAA;EZ9EA;;;;EYmFA,YAAA,GAAe,QAAA,UAAkB,IAAA,aAAiB,OAAA;EZzC1C;;;;;EY+CR,aAAA,GAAgB,QAAA,aAAqB,OAAA;EZtCrC;;;AAmBF;;EYyBE,eAAA,GAAkB,QAAA,aAAqB,OAAA;EZzBb;;;;;EY+B1B,YAAA,GAAe,QAAA,aAAqB,OAAA;AAAA;;;;AZ5BtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AC1IA;;;;;;;iBWuOgB,UAAA,CAAA;EACd,OAAA;EACA,eAAA;EACA,KAAA;EACA;AAAA,GACC,eAAA,GAAkB,gBAAA;;;UCvOJ,yBAAA,WAAoC,gBAAA;EACnD,IAAA;EACA,UAAA;EACA,UAAA,EAAY,OAAA,CAAQ,iBAAA,CAAkB,CAAA;EACtC,MAAA;EACA,MAAA;AAAA;AAAA,UAGe,wBAAA,WAAmC,gBAAA;EAClD,IAAA;EACA,UAAA;EACA,UAAA,EAAY,iBAAA,CAAkB,CAAA;EAC9B,MAAA;EACA,MAAA;AAAA;AAAA,UAGe,uBAAA,WAAkC,gBAAA;EACjD,IAAA;EACA,UAAA;EACA,UAAA,EAAY,iBAAA,CAAkB,CAAA;EAC9B,MAAA;EACA,MAAA;AAAA;AAAA,KAGU,eAAA,WAA0B,gBAAA,IAClC,yBAAA,CAA0B,CAAA,IAC1B,wBAAA,CAAyB,CAAA,IACzB,uBAAA,CAAwB,CAAA;;;;;;;;;;;;AdK5B;;;;;AA6BA;;;;;;;;iBcDgB,aAAA,CACd,MAAA;EACE,IAAA;EACA,MAAA,GAAS,KAAA,UAAe,KAAA,CAAM,YAAA;EAC9B,OAAA;AAAA,GAEF,IAAA,GAAO,aAAA;;;;;;;;;;;;;;;AdiFT;;;;;;;;;;;;;iBcnDgB,aAAA,WAAwB,gBAAA,CAAA,CACtC,MAAA;EACE,IAAA;EACA,UAAA,EAAY,CAAA;EACZ,MAAA,GAAS,KAAA,EAAO,eAAA,CAAgB,CAAA,MAAO,KAAA,CAAM,YAAA;EAC7C,OAAA;AAAA,GAEF,IAAA,GAAO,aAAA;;;UCtGQ,sBAAA;EACf,QAAA,EAAU,QAAA;EACV,WAAA,GAAc,WAAA;AAAA;;;AfKhB;;;;iBe8FgB,iBAAA,CAAA;EAAiB,QAAA;EAAA;AAAA,GA2B1B,sBAAA,KAAyB,OAAA,CAAM,YAAA;;;;;;;AfzHtC;;;KgBHK,WAAA;EAEC,IAAA;EACA,UAAA;EACA,IAAA,EAAM,OAAA,CAAQ,CAAA;EACd,MAAA,EAAQ,cAAA,CAAe,UAAA;EACvB,MAAA;AAAA;EAGA,IAAA;EACA,UAAA;EACA,IAAA,EAAM,CAAA;EACN,MAAA,EAAQ,cAAA,CAAe,SAAA;EACvB,MAAA;AAAA;EAGA,IAAA;EACA,UAAA;EACA,IAAA,EAAM,CAAA;EACN,MAAA,EAAQ,cAAA,CAAe,QAAA;EACvB,MAAA;AAAA;AAAA,iBAIU,sBAAA,CAAuB,GAAA;EACrC,IAAA;EACA,MAAA,GAAS,KAAA,EAAO,WAAA,UAAqB,OAAA,CAAM,YAAA;EAC3C,OAAA;AAAA,IACE,qBAAA;AAAA,iBAGY,sBAAA,WAAiC,gBAAA,CAAA,CAAkB,GAAA;EACjE,IAAA;EACA,IAAA,EAAM,CAAA;EACN,MAAA,GAAS,KAAA,EAAO,WAAA,CAAY,iBAAA,CAAkB,CAAA,OAAQ,OAAA,CAAM,YAAA;EAC5D,OAAA;AAAA,IACE,qBAAA,CAAsB,iBAAA,CAAkB,CAAA;;;;;;;;;;AhBjC5C;;;;;;iBiBAgB,eAAA,CACd,OAAA,YACC,iBAAA"}

package/dist/v2/headless.mjs

@@ -264,7 +264,10 @@ const ALL_UPDATES = [
 	UseAgentUpdate.OnStateChanged,
 	UseAgentUpdate.OnRunStatusChanged
 ];
-function useAgent({ agentId, updates, throttleMs } = {}) {
+function useAgent({ agentId, threadId, runtimeAgentId, updates, throttleMs } = {}) {
+	if (threadId != null && runtimeAgentId == null) 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: "${agentId ?? "default"}", threadId }).`);
+	if (runtimeAgentId != null && threadId == null) 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, e.g. useAgent({ agentId: "${agentId ?? "chat-1"}", runtimeAgentId: "${runtimeAgentId}", threadId }), or bind to the agent directly with useAgent({ agentId: "${runtimeAgentId}" }).`);
+	if (runtimeAgentId != null && agentId == null) 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: "${runtimeAgentId}", threadId }).`);
 	const chatConfig = useCopilotChatConfiguration();
 	const resolvedAgentId = agentId ?? chatConfig?.agentId ?? DEFAULT_AGENT_ID;
 	const { copilotkit } = useCopilotKit$1();
@@ -272,7 +275,58 @@ function useAgent({ agentId, updates, throttleMs } = {}) {
 	const [, forceUpdate] = useReducer((x) => x + 1, 0);
 	const updateFlags = useMemo(() => updates ?? ALL_UPDATES, [JSON.stringify(updates)]);
 	const provisionalAgentCache = useRef(/* @__PURE__ */ new Map());
+	const [registeredProxyAgent, setRegisteredProxyAgent] = useState(null);
+	useEffect(() => {
+		if (runtimeAgentId == null) {
+			setRegisteredProxyAgent(null);
+			return;
+		}
+		const { agent: proxy, unregister } = copilotkit.registerProxiedAgent({
+			agentId: resolvedAgentId,
+			runtimeAgentId
+		});
+		provisionalAgentCache.current.delete(resolvedAgentId);
+		setRegisteredProxyAgent(proxy);
+		return () => {
+			unregister();
+			setRegisteredProxyAgent(null);
+		};
+	}, [
+		copilotkit,
+		resolvedAgentId,
+		runtimeAgentId
+	]);
 	const { agent, isReady } = useMemo(() => {
+		if (runtimeAgentId != null) {
+			if (registeredProxyAgent) {
+				provisionalAgentCache.current.delete(resolvedAgentId);
+				return {
+					agent: registeredProxyAgent,
+					isReady: true
+				};
+			}
+			const cached = provisionalAgentCache.current.get(resolvedAgentId);
+			if (cached) {
+				copilotkit.applyHeadersToAgent(cached);
+				return {
+					agent: cached,
+					isReady: false
+				};
+			}
+			const provisional = new ProxiedCopilotRuntimeAgent({
+				runtimeUrl: copilotkit.runtimeUrl,
+				agentId: resolvedAgentId,
+				runtimeAgentId,
+				transport: copilotkit.runtimeTransport,
+				runtimeMode: "pending"
+			});
+			copilotkit.applyHeadersToAgent(provisional);
+			provisionalAgentCache.current.set(resolvedAgentId, provisional);
+			return {
+				agent: provisional,
+				isReady: false
+			};
+		}
 		const existing = copilotkit.getAgent(resolvedAgentId);
 		if (existing) {
 			provisionalAgentCache.current.delete(resolvedAgentId);
@@ -328,6 +382,8 @@ function useAgent({ agentId, updates, throttleMs } = {}) {
 		throw new Error(`useAgent: Agent '${resolvedAgentId}' 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.");
 	}, [
 		resolvedAgentId,
+		runtimeAgentId,
+		registeredProxyAgent,
 		copilotkit.agents,
 		copilotkit.runtimeConnectionStatus,
 		copilotkit.runtimeUrl,
@@ -380,14 +436,11 @@ function useAgent({ agentId, updates, throttleMs } = {}) {
 	]);
 	const configThreadId = chatConfig?.threadId;
 	const configHasExplicitThreadId = chatConfig?.hasExplicitThreadId;
+	const resolvedThreadId = threadId ?? (configHasExplicitThreadId ? configThreadId : void 0);
 	useEffect(() => {
-		if (!configHasExplicitThreadId || !configThreadId) return;
-		agent.threadId = configThreadId;
-	}, [
-		agent,
-		configThreadId,
-		configHasExplicitThreadId
-	]);
+		if (!resolvedThreadId) return;
+		agent.threadId = resolvedThreadId;
+	}, [agent, resolvedThreadId]);
 	return {
 		agent,
 		isReady