@copilotkitnext/core 0.0.11 → 0.0.13-alpha.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import { ToolCall, AbstractAgent, Message, Context, RunAgentResult, HttpAgentConfig, HttpAgent, RunAgentInput, BaseEvent } from '@ag-ui/client';
+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 { z } from 'zod';
 import { Observable } from 'rxjs';
 
@@ -22,37 +23,230 @@ type FrontendTool<T extends Record<string, unknown> = Record<string, unknown>> =
      */
     agentId?: string;
 };
+type Suggestion = {
+    title: string;
+    message: string;
+    /** Indicates whether this suggestion is still being generated. */
+    isLoading: boolean;
+};
+type SuggestionAvailability = "before-first-message" | "after-first-message" | "always" | "disabled";
+type DynamicSuggestionsConfig = {
+    /**
+     * A prompt or instructions for the GPT to generate suggestions.
+     */
+    instructions: string;
+    /**
+     * The minimum number of suggestions to generate. Defaults to `1`.
+     * @default 1
+     */
+    minSuggestions?: number;
+    /**
+     * The maximum number of suggestions to generate. Defaults to `3`.
+     * @default 1
+     */
+    maxSuggestions?: number;
+    /**
+     * When the suggestions are available. Defaults to "after-first-message".
+     */
+    available?: SuggestionAvailability;
+    /**
+     * The agent ID of the provider of the suggestions. Defaults to `"default"`.
+     */
+    providerAgentId?: string;
+    /**
+     * The agent ID of the consumer of the suggestions. Defaults to `"*"` (all agents).
+     */
+    consumerAgentId?: string;
+};
+type StaticSuggestionsConfig = {
+    /**
+     * The suggestions to display.
+     */
+    suggestions: Omit<Suggestion, "isLoading">[];
+    /**
+     * When the suggestions are available. Defaults to "before-first-message".
+     */
+    available?: SuggestionAvailability;
+    /**
+     * The agent ID of the consumer of the suggestions. Defaults to `"*"` (all agents).
+     */
+    consumerAgentId?: string;
+};
+type SuggestionsConfig = DynamicSuggestionsConfig | StaticSuggestionsConfig;
 
-/** Configuration options for `CopilotKitCore`. */
-interface CopilotKitCoreConfig {
-    /** The endpoint of the CopilotRuntime. */
-    runtimeUrl?: string;
-    /** Mapping from agent name to its `AbstractAgent` instance. */
-    agents?: Record<string, AbstractAgent>;
-    /** Headers appended to every HTTP request made by `CopilotKitCore`. */
-    headers?: Record<string, string>;
-    /** Properties sent as `forwardedProps` to the AG-UI agent. */
-    properties?: Record<string, unknown>;
-    /** Ordered collection of frontend tools available to the core. */
-    tools?: FrontendTool<any>[];
-}
 interface CopilotKitCoreAddAgentParams {
     id: string;
     agent: AbstractAgent;
 }
+/**
+ * Manages agent registration, lifecycle, and runtime connectivity for CopilotKitCore.
+ * Handles both local development agents and remote runtime agents.
+ */
+declare class AgentRegistry {
+    private core;
+    private _agents;
+    private localAgents;
+    private remoteAgents;
+    private _runtimeUrl?;
+    private _runtimeVersion?;
+    private _runtimeConnectionStatus;
+    constructor(core: CopilotKitCore);
+    /**
+     * Get all agents as a readonly record
+     */
+    get agents(): Readonly<Record<string, AbstractAgent>>;
+    get runtimeUrl(): string | undefined;
+    get runtimeVersion(): string | undefined;
+    get runtimeConnectionStatus(): CopilotKitCoreRuntimeConnectionStatus;
+    /**
+     * Initialize agents from configuration
+     */
+    initialize(agents: Record<string, AbstractAgent>): void;
+    /**
+     * Set the runtime URL and update connection
+     */
+    setRuntimeUrl(runtimeUrl: string | undefined): void;
+    /**
+     * Set all agents at once (for development use)
+     */
+    setAgents__unsafe_dev_only(agents: Record<string, AbstractAgent>): void;
+    /**
+     * Add a single agent (for development use)
+     */
+    addAgent__unsafe_dev_only({ id, agent }: CopilotKitCoreAddAgentParams): void;
+    /**
+     * Remove an agent by ID (for development use)
+     */
+    removeAgent__unsafe_dev_only(id: string): void;
+    /**
+     * Get an agent by ID
+     */
+    getAgent(id: string): AbstractAgent | undefined;
+    /**
+     * Apply current headers to an agent
+     */
+    applyHeadersToAgent(agent: AbstractAgent): void;
+    /**
+     * Apply current headers to all agents
+     */
+    applyHeadersToAgents(agents: Record<string, AbstractAgent>): void;
+    /**
+     * Update runtime connection and fetch remote agents
+     */
+    private updateRuntimeConnection;
+    /**
+     * Assign agent IDs to a record of agents
+     */
+    private assignAgentIds;
+    /**
+     * Validate and assign an agent ID
+     */
+    private validateAndAssignAgentId;
+    /**
+     * Notify subscribers of runtime status changes
+     */
+    private notifyRuntimeStatusChanged;
+    /**
+     * Notify subscribers of agent changes
+     */
+    private notifyAgentsChanged;
+}
+
 interface CopilotKitCoreRunAgentParams {
     agent: AbstractAgent;
     withMessages?: Message[];
-    agentId?: string;
 }
 interface CopilotKitCoreConnectAgentParams {
     agent: AbstractAgent;
-    agentId?: string;
 }
 interface CopilotKitCoreGetToolParams {
     toolName: string;
     agentId?: string;
 }
+/**
+ * Handles agent execution, tool calling, and agent connectivity for CopilotKitCore.
+ * Manages the complete lifecycle of agent runs including tool execution and follow-ups.
+ */
+declare class RunHandler {
+    private core;
+    private _tools;
+    constructor(core: CopilotKitCore);
+    /**
+     * Get all tools as a readonly array
+     */
+    get tools(): Readonly<FrontendTool<any>[]>;
+    /**
+     * Initialize with tools
+     */
+    initialize(tools: FrontendTool<any>[]): void;
+    /**
+     * Add a tool to the registry
+     */
+    addTool<T extends Record<string, unknown> = Record<string, unknown>>(tool: FrontendTool<T>): void;
+    /**
+     * Remove a tool by name and optionally by agentId
+     */
+    removeTool(id: string, agentId?: string): void;
+    /**
+     * Get a tool by name and optionally by agentId.
+     * If agentId is provided, it will first look for an agent-specific tool,
+     * then fall back to a global tool with the same name.
+     */
+    getTool(params: CopilotKitCoreGetToolParams): FrontendTool<any> | undefined;
+    /**
+     * Set all tools at once. Replaces existing tools.
+     */
+    setTools(tools: FrontendTool<any>[]): void;
+    /**
+     * Connect an agent (establish initial connection)
+     */
+    connectAgent({ agent }: CopilotKitCoreConnectAgentParams): Promise<RunAgentResult>;
+    /**
+     * Run an agent
+     */
+    runAgent({ agent, withMessages }: CopilotKitCoreRunAgentParams): Promise<RunAgentResult>;
+    /**
+     * Process agent result and execute tools
+     */
+    private processAgentResult;
+    /**
+     * Execute a specific tool
+     */
+    private executeSpecificTool;
+    /**
+     * Execute a wildcard tool
+     */
+    private executeWildcardTool;
+    /**
+     * Build frontend tools for an agent
+     */
+    buildFrontendTools(agentId?: string): Tool[];
+    /**
+     * Create an agent error subscriber
+     */
+    private createAgentErrorSubscriber;
+}
+
+/** Configuration options for `CopilotKitCore`. */
+interface CopilotKitCoreConfig {
+    /** The endpoint of the CopilotRuntime. */
+    runtimeUrl?: string;
+    /** Mapping from agent name to its `AbstractAgent` instance. For development only - production requires CopilotRuntime. */
+    agents__unsafe_dev_only?: Record<string, AbstractAgent>;
+    /** Headers appended to every HTTP request made by `CopilotKitCore`. */
+    headers?: Record<string, string>;
+    /** Properties sent as `forwardedProps` to the AG-UI agent. */
+    properties?: Record<string, unknown>;
+    /** Ordered collection of frontend tools available to the core. */
+    tools?: FrontendTool<any>[];
+    /** Suggestions config for the core. */
+    suggestionsConfig?: SuggestionsConfig[];
+}
+
+type CopilotKitCoreGetSuggestionsResult = {
+    suggestions: Suggestion[];
+    isLoading: boolean;
+};
 declare enum CopilotKitCoreErrorCode {
     RUNTIME_INFO_FETCH_FAILED = "runtime_info_fetch_failed",
     AGENT_CONNECT_FAILED = "agent_connect_failed",
@@ -90,6 +284,23 @@ interface CopilotKitCoreSubscriber {
         copilotkit: CopilotKitCore;
         context: Readonly<Record<string, Context>>;
     }) => void | Promise<void>;
+    onSuggestionsConfigChanged?: (event: {
+        copilotkit: CopilotKitCore;
+        suggestionsConfig: Readonly<Record<string, SuggestionsConfig>>;
+    }) => void | Promise<void>;
+    onSuggestionsChanged?: (event: {
+        copilotkit: CopilotKitCore;
+        agentId: string;
+        suggestions: Suggestion[];
+    }) => void | Promise<void>;
+    onSuggestionsStartedLoading?: (event: {
+        copilotkit: CopilotKitCore;
+        agentId: string;
+    }) => void | Promise<void>;
+    onSuggestionsFinishedLoading?: (event: {
+        copilotkit: CopilotKitCore;
+        agentId: string;
+    }) => void | Promise<void>;
     onPropertiesChanged?: (event: {
         copilotkit: CopilotKitCore;
         properties: Readonly<Record<string, unknown>>;
@@ -112,24 +323,22 @@ declare enum CopilotKitCoreRuntimeConnectionStatus {
     Error = "error"
 }
 declare class CopilotKitCore {
-    headers: Record<string, string>;
-    properties: Record<string, unknown>;
-    private _context;
-    private _agents;
-    private _tools;
-    private localAgents;
-    private remoteAgents;
+    private _headers;
+    private _properties;
     private subscribers;
-    private _runtimeUrl?;
-    private _runtimeVersion?;
-    private _runtimeConnectionStatus;
-    constructor({ runtimeUrl, headers, properties, agents, tools, }: CopilotKitCoreConfig);
-    private applyHeadersToAgent;
-    private applyHeadersToAgents;
-    private assignAgentIds;
+    private agentRegistry;
+    private contextStore;
+    private suggestionEngine;
+    private runHandler;
+    constructor({ runtimeUrl, headers, properties, agents__unsafe_dev_only, tools, suggestionsConfig, }: CopilotKitCoreConfig);
+    /**
+     * Internal method used by delegate classes to notify subscribers
+     */
     private notifySubscribers;
+    /**
+     * Internal method used by delegate classes to emit errors
+     */
     private emitError;
-    private resolveAgentId;
     /**
      * Snapshot accessors
      */
@@ -139,39 +348,40 @@ declare class CopilotKitCore {
     get runtimeUrl(): string | undefined;
     setRuntimeUrl(runtimeUrl: string | undefined): void;
     get runtimeVersion(): string | undefined;
+    get headers(): Readonly<Record<string, string>>;
+    get properties(): Readonly<Record<string, unknown>>;
     get runtimeConnectionStatus(): CopilotKitCoreRuntimeConnectionStatus;
-    /**
-     * Runtime connection
-     */
-    private updateRuntimeConnection;
     /**
      * Configuration updates
      */
     setHeaders(headers: Record<string, string>): void;
     setProperties(properties: Record<string, unknown>): void;
-    setAgents(agents: Record<string, AbstractAgent>): void;
-    addAgent({ id, agent }: CopilotKitCoreAddAgentParams): void;
-    removeAgent(id: string): void;
+    /**
+     * Agent management (delegated to AgentRegistry)
+     */
+    setAgents__unsafe_dev_only(agents: Record<string, AbstractAgent>): void;
+    addAgent__unsafe_dev_only(params: CopilotKitCoreAddAgentParams): void;
+    removeAgent__unsafe_dev_only(id: string): void;
     getAgent(id: string): AbstractAgent | undefined;
     /**
-     * Context management
+     * Context management (delegated to ContextStore)
      */
-    addContext({ description, value }: Context): string;
+    addContext(context: Context): string;
     removeContext(id: string): void;
     /**
-     * Tool management
+     * Suggestions management (delegated to SuggestionEngine)
      */
-    addTool<T extends Record<string, unknown> = Record<string, unknown>>(tool: FrontendTool<T>): void;
-    removeTool(id: string, agentId?: string): void;
+    addSuggestionsConfig(config: SuggestionsConfig): string;
+    removeSuggestionsConfig(id: string): void;
+    reloadSuggestions(agentId: string): void;
+    clearSuggestions(agentId: string): void;
+    getSuggestions(agentId: string): CopilotKitCoreGetSuggestionsResult;
     /**
-     * Get a tool by name and optionally by agentId.
-     * If agentId is provided, it will first look for an agent-specific tool,
-     * then fall back to a global tool with the same name.
+     * Tool management (delegated to RunHandler)
      */
+    addTool<T extends Record<string, unknown> = Record<string, unknown>>(tool: FrontendTool<T>): void;
+    removeTool(id: string, agentId?: string): void;
     getTool(params: CopilotKitCoreGetToolParams): FrontendTool<any> | undefined;
-    /**
-     * Set all tools at once. Replaces existing tools.
-     */
     setTools(tools: FrontendTool<any>[]): void;
     /**
      * Subscription lifecycle
@@ -179,13 +389,115 @@ declare class CopilotKitCore {
     subscribe(subscriber: CopilotKitCoreSubscriber): () => void;
     unsubscribe(subscriber: CopilotKitCoreSubscriber): void;
     /**
-     * Agent connectivity
+     * Agent connectivity (delegated to RunHandler)
+     */
+    connectAgent(params: CopilotKitCoreConnectAgentParams): Promise<_ag_ui_client.RunAgentResult>;
+    runAgent(params: CopilotKitCoreRunAgentParams): Promise<_ag_ui_client.RunAgentResult>;
+    /**
+     * Internal method used by RunHandler to build frontend tools
      */
-    connectAgent({ agent, agentId, }: CopilotKitCoreConnectAgentParams): Promise<RunAgentResult>;
-    runAgent({ agent, withMessages, agentId, }: CopilotKitCoreRunAgentParams): Promise<RunAgentResult>;
-    private processAgentResult;
     private buildFrontendTools;
-    private createAgentErrorSubscriber;
+}
+
+/**
+ * Manages context storage and lifecycle for CopilotKitCore.
+ * Context represents additional information available to agents during execution.
+ */
+declare class ContextStore {
+    private core;
+    private _context;
+    constructor(core: CopilotKitCore);
+    /**
+     * Get all context entries as a readonly record
+     */
+    get context(): Readonly<Record<string, Context>>;
+    /**
+     * Add a new context entry
+     * @returns The ID of the created context entry
+     */
+    addContext({ description, value }: Context): string;
+    /**
+     * Remove a context entry by ID
+     */
+    removeContext(id: string): void;
+    /**
+     * Notify all subscribers of context changes
+     */
+    private notifySubscribers;
+}
+
+/**
+ * Manages suggestion generation, streaming, and lifecycle for CopilotKitCore.
+ * Handles both dynamic (AI-generated) and static suggestions.
+ */
+declare class SuggestionEngine {
+    private core;
+    private _suggestionsConfig;
+    private _suggestions;
+    private _runningSuggestions;
+    constructor(core: CopilotKitCore);
+    /**
+     * Initialize with suggestion configs
+     */
+    initialize(suggestionsConfig: SuggestionsConfig[]): void;
+    /**
+     * Add a suggestion configuration
+     * @returns The ID of the created config
+     */
+    addSuggestionsConfig(config: SuggestionsConfig): string;
+    /**
+     * Remove a suggestion configuration by ID
+     */
+    removeSuggestionsConfig(id: string): void;
+    /**
+     * Reload suggestions for a specific agent
+     * This triggers generation of new suggestions based on current configs
+     */
+    reloadSuggestions(agentId: string): void;
+    /**
+     * Clear all suggestions for a specific agent
+     */
+    clearSuggestions(agentId: string): void;
+    /**
+     * Get current suggestions for an agent
+     */
+    getSuggestions(agentId: string): CopilotKitCoreGetSuggestionsResult;
+    /**
+     * Generate suggestions using a provider agent
+     */
+    private generateSuggestions;
+    /**
+     * Finalize suggestions by marking them as no longer loading
+     */
+    private finalizeSuggestions;
+    /**
+     * Extract suggestions from messages (called during streaming)
+     */
+    extractSuggestions(messages: Message[], suggestionId: string, consumerAgentId: string, isRunning: boolean): void;
+    /**
+     * Notify subscribers of suggestions config changes
+     */
+    private notifySuggestionsConfigChanged;
+    /**
+     * Notify subscribers of suggestions changes
+     */
+    private notifySuggestionsChanged;
+    /**
+     * Notify subscribers that suggestions started loading
+     */
+    private notifySuggestionsStartedLoading;
+    /**
+     * Notify subscribers that suggestions finished loading
+     */
+    private notifySuggestionsFinishedLoading;
+    /**
+     * Check if suggestions should be shown based on availability and message count
+     */
+    private shouldShowSuggestions;
+    /**
+     * Add static suggestions directly without AI generation
+     */
+    private addStaticSuggestions;
 }
 
 interface ProxiedCopilotRuntimeAgentConfig extends Omit<HttpAgentConfig, "url"> {
@@ -199,4 +511,4 @@ declare class ProxiedCopilotRuntimeAgent extends HttpAgent {
 
 declare function completePartialMarkdown(input: string): string;
 
-export { CopilotKitCore, type CopilotKitCoreAddAgentParams, type CopilotKitCoreConfig, type CopilotKitCoreConnectAgentParams, CopilotKitCoreErrorCode, type CopilotKitCoreGetToolParams, type CopilotKitCoreRunAgentParams, CopilotKitCoreRuntimeConnectionStatus, type CopilotKitCoreSubscriber, type FrontendTool, ProxiedCopilotRuntimeAgent, type ProxiedCopilotRuntimeAgentConfig, ToolCallStatus, completePartialMarkdown };
+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 };