@copilotkitnext/core 0.0.13-alpha.1 → 0.0.14

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import * as _ag_ui_client from '@ag-ui/client';
-import { ToolCall, AbstractAgent, Message, RunAgentResult, Tool, Context, HttpAgentConfig, HttpAgent, RunAgentInput, BaseEvent } from '@ag-ui/client';
+import { ToolCall, AbstractAgent, Message, RunAgentResult, Tool, Context, State, HttpAgentConfig, HttpAgent, RunAgentInput, BaseEvent } from '@ag-ui/client';
 import { z } from 'zod';
 import { Observable } from 'rxjs';
 
@@ -322,6 +322,27 @@ declare enum CopilotKitCoreRuntimeConnectionStatus {
     Connecting = "connecting",
     Error = "error"
 }
+/**
+ * Internal interface for delegate classes to access CopilotKitCore methods.
+ * This provides type safety while allowing controlled access to private functionality.
+ */
+interface CopilotKitCoreFriendsAccess {
+    notifySubscribers(handler: (subscriber: CopilotKitCoreSubscriber) => void | Promise<void>, errorMessage: string): Promise<void>;
+    emitError(params: {
+        error: Error;
+        code: CopilotKitCoreErrorCode;
+        context?: Record<string, any>;
+    }): Promise<void>;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly properties: Readonly<Record<string, unknown>>;
+    readonly context: Readonly<Record<string, Context>>;
+    buildFrontendTools(agentId?: string): _ag_ui_client.Tool[];
+    getAgent(id: string): AbstractAgent | undefined;
+    readonly suggestionEngine: {
+        clearSuggestions(agentId: string): void;
+        reloadSuggestions(agentId: string): void;
+    };
+}
 declare class CopilotKitCore {
     private _headers;
     private _properties;
@@ -330,11 +351,12 @@ declare class CopilotKitCore {
     private contextStore;
     private suggestionEngine;
     private runHandler;
+    private stateManager;
     constructor({ runtimeUrl, headers, properties, agents__unsafe_dev_only, tools, suggestionsConfig, }: CopilotKitCoreConfig);
     /**
-     * Internal method used by delegate classes to notify subscribers
+     * Internal method used by delegate classes and subclasses to notify subscribers
      */
-    private notifySubscribers;
+    protected notifySubscribers(handler: (subscriber: CopilotKitCoreSubscriber) => void | Promise<void>, errorMessage: string): Promise<void>;
     /**
      * Internal method used by delegate classes to emit errors
      */
@@ -393,6 +415,12 @@ declare class CopilotKitCore {
      */
     connectAgent(params: CopilotKitCoreConnectAgentParams): Promise<_ag_ui_client.RunAgentResult>;
     runAgent(params: CopilotKitCoreRunAgentParams): Promise<_ag_ui_client.RunAgentResult>;
+    /**
+     * State management (delegated to StateManager)
+     */
+    getStateByRun(agentId: string, threadId: string, runId: string): State | undefined;
+    getRunIdForMessage(agentId: string, threadId: string, messageId: string): string | undefined;
+    getRunIdsForThread(agentId: string, threadId: string): string[];
     /**
      * Internal method used by RunHandler to build frontend tools
      */
@@ -500,6 +528,87 @@ declare class SuggestionEngine {
     private addStaticSuggestions;
 }
 
+/**
+ * Manages state and message tracking by run for CopilotKitCore.
+ * Tracks agent state snapshots and message-to-run associations.
+ */
+declare class StateManager {
+    private core;
+    private stateByRun;
+    private messageToRun;
+    private agentSubscriptions;
+    constructor(core: CopilotKitCore);
+    /**
+     * Initialize state tracking for an agent
+     */
+    initialize(): void;
+    /**
+     * Subscribe to an agent's events to track state and messages
+     */
+    subscribeToAgent(agent: AbstractAgent): void;
+    /**
+     * Unsubscribe from an agent's events
+     */
+    unsubscribeFromAgent(agentId: string): void;
+    /**
+     * Get state for a specific run
+     * Returns a deep copy to prevent external mutations
+     */
+    getStateByRun(agentId: string, threadId: string, runId: string): State | undefined;
+    /**
+     * Get runId associated with a message
+     */
+    getRunIdForMessage(agentId: string, threadId: string, messageId: string): string | undefined;
+    /**
+     * Get all states for an agent's thread
+     */
+    getStatesForThread(agentId: string, threadId: string): Map<string, State>;
+    /**
+     * Get all run IDs for an agent's thread
+     */
+    getRunIdsForThread(agentId: string, threadId: string): string[];
+    /**
+     * Handle run started event
+     */
+    private handleRunStarted;
+    /**
+     * Handle run finished event
+     */
+    private handleRunFinished;
+    /**
+     * Handle state snapshot event
+     */
+    private handleStateSnapshot;
+    /**
+     * Handle state delta event
+     */
+    private handleStateDelta;
+    /**
+     * Handle messages snapshot event
+     */
+    private handleMessagesSnapshot;
+    /**
+     * Handle new message event
+     */
+    private handleNewMessage;
+    /**
+     * Save state for a specific run
+     */
+    private saveState;
+    /**
+     * Associate a message with a run
+     */
+    private associateMessageWithRun;
+    /**
+     * Clear all state for an agent
+     */
+    clearAgentState(agentId: string): void;
+    /**
+     * Clear all state for a thread
+     */
+    clearThreadState(agentId: string, threadId: string): void;
+}
+
 interface ProxiedCopilotRuntimeAgentConfig extends Omit<HttpAgentConfig, "url"> {
     runtimeUrl?: string;
 }
@@ -511,4 +620,4 @@ declare class ProxiedCopilotRuntimeAgent extends HttpAgent {
 
 declare function completePartialMarkdown(input: string): string;
 
-export { AgentRegistry, ContextStore, CopilotKitCore, type CopilotKitCoreAddAgentParams, type CopilotKitCoreConfig, type CopilotKitCoreConnectAgentParams, CopilotKitCoreErrorCode, type CopilotKitCoreGetSuggestionsResult, type CopilotKitCoreGetToolParams, type CopilotKitCoreRunAgentParams, CopilotKitCoreRuntimeConnectionStatus, type CopilotKitCoreSubscriber, type DynamicSuggestionsConfig, type FrontendTool, ProxiedCopilotRuntimeAgent, type ProxiedCopilotRuntimeAgentConfig, RunHandler, type StaticSuggestionsConfig, type Suggestion, type SuggestionAvailability, SuggestionEngine, type SuggestionsConfig, ToolCallStatus, completePartialMarkdown };
+export { AgentRegistry, ContextStore, CopilotKitCore, type CopilotKitCoreAddAgentParams, type CopilotKitCoreConfig, type CopilotKitCoreConnectAgentParams, CopilotKitCoreErrorCode, type CopilotKitCoreFriendsAccess, type CopilotKitCoreGetSuggestionsResult, type CopilotKitCoreGetToolParams, type CopilotKitCoreRunAgentParams, CopilotKitCoreRuntimeConnectionStatus, type CopilotKitCoreSubscriber, type DynamicSuggestionsConfig, type FrontendTool, ProxiedCopilotRuntimeAgent, type ProxiedCopilotRuntimeAgentConfig, RunHandler, StateManager, type StaticSuggestionsConfig, type Suggestion, type SuggestionAvailability, SuggestionEngine, type SuggestionsConfig, ToolCallStatus, completePartialMarkdown };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _ag_ui_client from '@ag-ui/client';
-import { ToolCall, AbstractAgent, Message, RunAgentResult, Tool, Context, HttpAgentConfig, HttpAgent, RunAgentInput, BaseEvent } from '@ag-ui/client';
+import { ToolCall, AbstractAgent, Message, RunAgentResult, Tool, Context, State, HttpAgentConfig, HttpAgent, RunAgentInput, BaseEvent } from '@ag-ui/client';
 import { z } from 'zod';
 import { Observable } from 'rxjs';
 
@@ -322,6 +322,27 @@ declare enum CopilotKitCoreRuntimeConnectionStatus {
     Connecting = "connecting",
     Error = "error"
 }
+/**
+ * Internal interface for delegate classes to access CopilotKitCore methods.
+ * This provides type safety while allowing controlled access to private functionality.
+ */
+interface CopilotKitCoreFriendsAccess {
+    notifySubscribers(handler: (subscriber: CopilotKitCoreSubscriber) => void | Promise<void>, errorMessage: string): Promise<void>;
+    emitError(params: {
+        error: Error;
+        code: CopilotKitCoreErrorCode;
+        context?: Record<string, any>;
+    }): Promise<void>;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly properties: Readonly<Record<string, unknown>>;
+    readonly context: Readonly<Record<string, Context>>;
+    buildFrontendTools(agentId?: string): _ag_ui_client.Tool[];
+    getAgent(id: string): AbstractAgent | undefined;
+    readonly suggestionEngine: {
+        clearSuggestions(agentId: string): void;
+        reloadSuggestions(agentId: string): void;
+    };
+}
 declare class CopilotKitCore {
     private _headers;
     private _properties;
@@ -330,11 +351,12 @@ declare class CopilotKitCore {
     private contextStore;
     private suggestionEngine;
     private runHandler;
+    private stateManager;
     constructor({ runtimeUrl, headers, properties, agents__unsafe_dev_only, tools, suggestionsConfig, }: CopilotKitCoreConfig);
     /**
-     * Internal method used by delegate classes to notify subscribers
+     * Internal method used by delegate classes and subclasses to notify subscribers
      */
-    private notifySubscribers;
+    protected notifySubscribers(handler: (subscriber: CopilotKitCoreSubscriber) => void | Promise<void>, errorMessage: string): Promise<void>;
     /**
      * Internal method used by delegate classes to emit errors
      */
@@ -393,6 +415,12 @@ declare class CopilotKitCore {
      */
     connectAgent(params: CopilotKitCoreConnectAgentParams): Promise<_ag_ui_client.RunAgentResult>;
     runAgent(params: CopilotKitCoreRunAgentParams): Promise<_ag_ui_client.RunAgentResult>;
+    /**
+     * State management (delegated to StateManager)
+     */
+    getStateByRun(agentId: string, threadId: string, runId: string): State | undefined;
+    getRunIdForMessage(agentId: string, threadId: string, messageId: string): string | undefined;
+    getRunIdsForThread(agentId: string, threadId: string): string[];
     /**
      * Internal method used by RunHandler to build frontend tools
      */
@@ -500,6 +528,87 @@ declare class SuggestionEngine {
     private addStaticSuggestions;
 }
 
+/**
+ * Manages state and message tracking by run for CopilotKitCore.
+ * Tracks agent state snapshots and message-to-run associations.
+ */
+declare class StateManager {
+    private core;
+    private stateByRun;
+    private messageToRun;
+    private agentSubscriptions;
+    constructor(core: CopilotKitCore);
+    /**
+     * Initialize state tracking for an agent
+     */
+    initialize(): void;
+    /**
+     * Subscribe to an agent's events to track state and messages
+     */
+    subscribeToAgent(agent: AbstractAgent): void;
+    /**
+     * Unsubscribe from an agent's events
+     */
+    unsubscribeFromAgent(agentId: string): void;
+    /**
+     * Get state for a specific run
+     * Returns a deep copy to prevent external mutations
+     */
+    getStateByRun(agentId: string, threadId: string, runId: string): State | undefined;
+    /**
+     * Get runId associated with a message
+     */
+    getRunIdForMessage(agentId: string, threadId: string, messageId: string): string | undefined;
+    /**
+     * Get all states for an agent's thread
+     */
+    getStatesForThread(agentId: string, threadId: string): Map<string, State>;
+    /**
+     * Get all run IDs for an agent's thread
+     */
+    getRunIdsForThread(agentId: string, threadId: string): string[];
+    /**
+     * Handle run started event
+     */
+    private handleRunStarted;
+    /**
+     * Handle run finished event
+     */
+    private handleRunFinished;
+    /**
+     * Handle state snapshot event
+     */
+    private handleStateSnapshot;
+    /**
+     * Handle state delta event
+     */
+    private handleStateDelta;
+    /**
+     * Handle messages snapshot event
+     */
+    private handleMessagesSnapshot;
+    /**
+     * Handle new message event
+     */
+    private handleNewMessage;
+    /**
+     * Save state for a specific run
+     */
+    private saveState;
+    /**
+     * Associate a message with a run
+     */
+    private associateMessageWithRun;
+    /**
+     * Clear all state for an agent
+     */
+    clearAgentState(agentId: string): void;
+    /**
+     * Clear all state for a thread
+     */
+    clearThreadState(agentId: string, threadId: string): void;
+}
+
 interface ProxiedCopilotRuntimeAgentConfig extends Omit<HttpAgentConfig, "url"> {
     runtimeUrl?: string;
 }
@@ -511,4 +620,4 @@ declare class ProxiedCopilotRuntimeAgent extends HttpAgent {
 
 declare function completePartialMarkdown(input: string): string;
 
-export { AgentRegistry, ContextStore, CopilotKitCore, type CopilotKitCoreAddAgentParams, type CopilotKitCoreConfig, type CopilotKitCoreConnectAgentParams, CopilotKitCoreErrorCode, type CopilotKitCoreGetSuggestionsResult, type CopilotKitCoreGetToolParams, type CopilotKitCoreRunAgentParams, CopilotKitCoreRuntimeConnectionStatus, type CopilotKitCoreSubscriber, type DynamicSuggestionsConfig, type FrontendTool, ProxiedCopilotRuntimeAgent, type ProxiedCopilotRuntimeAgentConfig, RunHandler, type StaticSuggestionsConfig, type Suggestion, type SuggestionAvailability, SuggestionEngine, type SuggestionsConfig, ToolCallStatus, completePartialMarkdown };
+export { AgentRegistry, ContextStore, CopilotKitCore, type CopilotKitCoreAddAgentParams, type CopilotKitCoreConfig, type CopilotKitCoreConnectAgentParams, CopilotKitCoreErrorCode, type CopilotKitCoreFriendsAccess, type CopilotKitCoreGetSuggestionsResult, type CopilotKitCoreGetToolParams, type CopilotKitCoreRunAgentParams, CopilotKitCoreRuntimeConnectionStatus, type CopilotKitCoreSubscriber, type DynamicSuggestionsConfig, type FrontendTool, ProxiedCopilotRuntimeAgent, type ProxiedCopilotRuntimeAgentConfig, RunHandler, StateManager, type StaticSuggestionsConfig, type Suggestion, type SuggestionAvailability, SuggestionEngine, type SuggestionsConfig, ToolCallStatus, completePartialMarkdown };

package/dist/index.js

@@ -27,6 +27,7 @@ __export(index_exports, {
   CopilotKitCoreRuntimeConnectionStatus: () => CopilotKitCoreRuntimeConnectionStatus,
   ProxiedCopilotRuntimeAgent: () => ProxiedCopilotRuntimeAgent,
   RunHandler: () => RunHandler,
+  StateManager: () => StateManager,
   SuggestionEngine: () => SuggestionEngine,
   ToolCallStatus: () => ToolCallStatus,
   completePartialMarkdown: () => completePartialMarkdown
@@ -763,7 +764,9 @@ var RunHandler = class {
    * Run an agent
    */
   async runAgent({ agent, withMessages }) {
-    void this.core.suggestionEngine.clearSuggestions(agent.agentId);
+    if (agent.agentId) {
+      void this.core.suggestionEngine.clearSuggestions(agent.agentId);
+    }
     if (agent instanceof import_client3.HttpAgent) {
       agent.headers = { ...this.core.headers };
     }
@@ -1119,6 +1122,186 @@ function createToolSchema(tool) {
   return schema;
 }
 
+// src/core/state-manager.ts
+var StateManager = class {
+  constructor(core) {
+    this.core = core;
+  }
+  // State tracking: agentId -> threadId -> runId -> state
+  stateByRun = /* @__PURE__ */ new Map();
+  // Message tracking: agentId -> threadId -> messageId -> runId
+  messageToRun = /* @__PURE__ */ new Map();
+  // Agent subscriptions for cleanup
+  agentSubscriptions = /* @__PURE__ */ new Map();
+  /**
+   * Initialize state tracking for an agent
+   */
+  initialize() {
+  }
+  /**
+   * Subscribe to an agent's events to track state and messages
+   */
+  subscribeToAgent(agent) {
+    if (!agent.agentId) {
+      return;
+    }
+    const agentId = agent.agentId;
+    this.unsubscribeFromAgent(agentId);
+    const { unsubscribe } = agent.subscribe({
+      onRunStartedEvent: ({ event, state }) => {
+        this.handleRunStarted(agent, event, state);
+      },
+      onRunFinishedEvent: ({ event, state }) => {
+        this.handleRunFinished(agent, event, state);
+      },
+      onStateSnapshotEvent: ({ event, input, state }) => {
+        this.handleStateSnapshot(agent, event, input, state);
+      },
+      onStateDeltaEvent: ({ event, input, state }) => {
+        this.handleStateDelta(agent, event, input, state);
+      },
+      onMessagesSnapshotEvent: ({ event, input, messages }) => {
+        this.handleMessagesSnapshot(agent, event, input, messages);
+      },
+      onNewMessage: ({ message, input }) => {
+        this.handleNewMessage(agent, message, input);
+      }
+    });
+    this.agentSubscriptions.set(agentId, unsubscribe);
+  }
+  /**
+   * Unsubscribe from an agent's events
+   */
+  unsubscribeFromAgent(agentId) {
+    const unsubscribe = this.agentSubscriptions.get(agentId);
+    if (unsubscribe) {
+      unsubscribe();
+      this.agentSubscriptions.delete(agentId);
+    }
+  }
+  /**
+   * Get state for a specific run
+   * Returns a deep copy to prevent external mutations
+   */
+  getStateByRun(agentId, threadId, runId) {
+    const state = this.stateByRun.get(agentId)?.get(threadId)?.get(runId);
+    if (!state) return void 0;
+    return JSON.parse(JSON.stringify(state));
+  }
+  /**
+   * Get runId associated with a message
+   */
+  getRunIdForMessage(agentId, threadId, messageId) {
+    return this.messageToRun.get(agentId)?.get(threadId)?.get(messageId);
+  }
+  /**
+   * Get all states for an agent's thread
+   */
+  getStatesForThread(agentId, threadId) {
+    return this.stateByRun.get(agentId)?.get(threadId) ?? /* @__PURE__ */ new Map();
+  }
+  /**
+   * Get all run IDs for an agent's thread
+   */
+  getRunIdsForThread(agentId, threadId) {
+    const threadStates = this.stateByRun.get(agentId)?.get(threadId);
+    return threadStates ? Array.from(threadStates.keys()) : [];
+  }
+  /**
+   * Handle run started event
+   */
+  handleRunStarted(agent, event, state) {
+    if (!agent.agentId) return;
+    const { threadId, runId } = event;
+    this.saveState(agent.agentId, threadId, runId, state);
+  }
+  /**
+   * Handle run finished event
+   */
+  handleRunFinished(agent, event, state) {
+    if (!agent.agentId) return;
+    const { threadId, runId } = event;
+    this.saveState(agent.agentId, threadId, runId, state);
+  }
+  /**
+   * Handle state snapshot event
+   */
+  handleStateSnapshot(agent, event, input, state) {
+    if (!agent.agentId) return;
+    const { threadId, runId } = input;
+    const mergedState = { ...state, ...event.snapshot };
+    this.saveState(agent.agentId, threadId, runId, mergedState);
+  }
+  /**
+   * Handle state delta event
+   */
+  handleStateDelta(agent, event, input, state) {
+    if (!agent.agentId) return;
+    const { threadId, runId } = input;
+    this.saveState(agent.agentId, threadId, runId, state);
+  }
+  /**
+   * Handle messages snapshot event
+   */
+  handleMessagesSnapshot(agent, event, input, messages) {
+    if (!agent.agentId) return;
+    const { threadId, runId } = input;
+    for (const message of event.messages) {
+      this.associateMessageWithRun(agent.agentId, threadId, message.id, runId);
+    }
+  }
+  /**
+   * Handle new message event
+   */
+  handleNewMessage(agent, message, input) {
+    if (!agent.agentId || !input) return;
+    const { threadId, runId } = input;
+    this.associateMessageWithRun(agent.agentId, threadId, message.id, runId);
+  }
+  /**
+   * Save state for a specific run
+   */
+  saveState(agentId, threadId, runId, state) {
+    if (!this.stateByRun.has(agentId)) {
+      this.stateByRun.set(agentId, /* @__PURE__ */ new Map());
+    }
+    const agentStates = this.stateByRun.get(agentId);
+    if (!agentStates.has(threadId)) {
+      agentStates.set(threadId, /* @__PURE__ */ new Map());
+    }
+    const threadStates = agentStates.get(threadId);
+    threadStates.set(runId, JSON.parse(JSON.stringify(state)));
+  }
+  /**
+   * Associate a message with a run
+   */
+  associateMessageWithRun(agentId, threadId, messageId, runId) {
+    if (!this.messageToRun.has(agentId)) {
+      this.messageToRun.set(agentId, /* @__PURE__ */ new Map());
+    }
+    const agentMessages = this.messageToRun.get(agentId);
+    if (!agentMessages.has(threadId)) {
+      agentMessages.set(threadId, /* @__PURE__ */ new Map());
+    }
+    const threadMessages = agentMessages.get(threadId);
+    threadMessages.set(messageId, runId);
+  }
+  /**
+   * Clear all state for an agent
+   */
+  clearAgentState(agentId) {
+    this.stateByRun.delete(agentId);
+    this.messageToRun.delete(agentId);
+  }
+  /**
+   * Clear all state for a thread
+   */
+  clearThreadState(agentId, threadId) {
+    this.stateByRun.get(agentId)?.delete(threadId);
+    this.messageToRun.get(agentId)?.delete(threadId);
+  }
+};
+
 // src/core/core.ts
 var CopilotKitCoreErrorCode = /* @__PURE__ */ ((CopilotKitCoreErrorCode2) => {
   CopilotKitCoreErrorCode2["RUNTIME_INFO_FETCH_FAILED"] = "runtime_info_fetch_failed";
@@ -1146,6 +1329,7 @@ var CopilotKitCore = class {
   contextStore;
   suggestionEngine;
   runHandler;
+  stateManager;
   constructor({
     runtimeUrl,
     headers = {},
@@ -1160,13 +1344,24 @@ var CopilotKitCore = class {
     this.contextStore = new ContextStore(this);
     this.suggestionEngine = new SuggestionEngine(this);
     this.runHandler = new RunHandler(this);
+    this.stateManager = new StateManager(this);
     this.agentRegistry.initialize(agents__unsafe_dev_only);
     this.runHandler.initialize(tools);
     this.suggestionEngine.initialize(suggestionsConfig);
+    this.stateManager.initialize();
     this.agentRegistry.setRuntimeUrl(runtimeUrl);
+    this.subscribe({
+      onAgentsChanged: ({ agents }) => {
+        Object.values(agents).forEach((agent) => {
+          if (agent.agentId) {
+            this.stateManager.subscribeToAgent(agent);
+          }
+        });
+      }
+    });
   }
   /**
-   * Internal method used by delegate classes to notify subscribers
+   * Internal method used by delegate classes and subclasses to notify subscribers
    */
   async notifySubscribers(handler, errorMessage) {
     await Promise.all(
@@ -1329,6 +1524,18 @@ var CopilotKitCore = class {
   async runAgent(params) {
     return this.runHandler.runAgent(params);
   }
+  /**
+   * State management (delegated to StateManager)
+   */
+  getStateByRun(agentId, threadId, runId) {
+    return this.stateManager.getStateByRun(agentId, threadId, runId);
+  }
+  getRunIdForMessage(agentId, threadId, messageId) {
+    return this.stateManager.getRunIdForMessage(agentId, threadId, messageId);
+  }
+  getRunIdsForThread(agentId, threadId) {
+    return this.stateManager.getRunIdsForThread(agentId, threadId);
+  }
   /**
    * Internal method used by RunHandler to build frontend tools
    */
@@ -1569,6 +1776,7 @@ ${indent}${fence}`;
   CopilotKitCoreRuntimeConnectionStatus,
   ProxiedCopilotRuntimeAgent,
   RunHandler,
+  StateManager,
   SuggestionEngine,
   ToolCallStatus,
   completePartialMarkdown