@copilotkitnext/core 0.0.0-max-changeset-20260109174803

package/dist/index.d.ts

@@ -0,0 +1,644 @@
+import * as _ag_ui_client from '@ag-ui/client';
+import { ToolCall, AbstractAgent, RunAgentResult, Tool, Context, State, Message, HttpAgentConfig, HttpAgent, RunAgentInput, BaseEvent } from '@ag-ui/client';
+import { z } from 'zod';
+import { Observable } from 'rxjs';
+
+/**
+ * Status of a tool call execution
+ */
+declare enum ToolCallStatus {
+    InProgress = "inProgress",
+    Executing = "executing",
+    Complete = "complete"
+}
+type CopilotRuntimeTransport = "rest" | "single";
+type FrontendTool<T extends Record<string, unknown> = Record<string, unknown>> = {
+    name: string;
+    description?: string;
+    parameters?: z.ZodType<T>;
+    handler?: (args: T, toolCall: ToolCall) => Promise<unknown>;
+    followUp?: boolean;
+    /**
+     * Optional agent ID to constrain this tool to a specific agent.
+     * If specified, this tool will only be available to the specified agent.
+     */
+    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;
+
+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;
+    private _runtimeTransport;
+    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;
+    get runtimeTransport(): CopilotRuntimeTransport;
+    /**
+     * Initialize agents from configuration
+     */
+    initialize(agents: Record<string, AbstractAgent>): void;
+    /**
+     * Set the runtime URL and update connection
+     */
+    setRuntimeUrl(runtimeUrl: string | undefined): void;
+    setRuntimeTransport(runtimeTransport: CopilotRuntimeTransport): 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;
+    private fetchRuntimeInfo;
+    /**
+     * 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;
+}
+interface CopilotKitCoreConnectAgentParams {
+    agent: AbstractAgent;
+}
+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 }: 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;
+    /** Transport style for CopilotRuntime endpoints. Defaults to REST. */
+    runtimeTransport?: CopilotRuntimeTransport;
+    /** 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[];
+}
+
+interface CopilotKitCoreStopAgentParams {
+    agent: AbstractAgent;
+}
+type CopilotKitCoreGetSuggestionsResult = {
+    suggestions: Suggestion[];
+    isLoading: boolean;
+};
+declare enum CopilotKitCoreErrorCode {
+    RUNTIME_INFO_FETCH_FAILED = "runtime_info_fetch_failed",
+    AGENT_CONNECT_FAILED = "agent_connect_failed",
+    AGENT_RUN_FAILED = "agent_run_failed",
+    AGENT_RUN_FAILED_EVENT = "agent_run_failed_event",
+    AGENT_RUN_ERROR_EVENT = "agent_run_error_event",
+    TOOL_ARGUMENT_PARSE_FAILED = "tool_argument_parse_failed",
+    TOOL_HANDLER_FAILED = "tool_handler_failed"
+}
+interface CopilotKitCoreSubscriber {
+    onRuntimeConnectionStatusChanged?: (event: {
+        copilotkit: CopilotKitCore;
+        status: CopilotKitCoreRuntimeConnectionStatus;
+    }) => void | Promise<void>;
+    onToolExecutionStart?: (event: {
+        copilotkit: CopilotKitCore;
+        toolCallId: string;
+        agentId: string;
+        toolName: string;
+        args: unknown;
+    }) => void | Promise<void>;
+    onToolExecutionEnd?: (event: {
+        copilotkit: CopilotKitCore;
+        toolCallId: string;
+        agentId: string;
+        toolName: string;
+        result: string;
+        error?: string;
+    }) => void | Promise<void>;
+    onAgentsChanged?: (event: {
+        copilotkit: CopilotKitCore;
+        agents: Readonly<Record<string, AbstractAgent>>;
+    }) => void | Promise<void>;
+    onContextChanged?: (event: {
+        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>>;
+    }) => void | Promise<void>;
+    onHeadersChanged?: (event: {
+        copilotkit: CopilotKitCore;
+        headers: Readonly<Record<string, string>>;
+    }) => void | Promise<void>;
+    onError?: (event: {
+        copilotkit: CopilotKitCore;
+        error: Error;
+        code: CopilotKitCoreErrorCode;
+        context: Record<string, any>;
+    }) => void | Promise<void>;
+}
+interface CopilotKitCoreSubscription {
+    unsubscribe: () => void;
+}
+declare enum CopilotKitCoreRuntimeConnectionStatus {
+    Disconnected = "disconnected",
+    Connected = "connected",
+    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;
+    private subscribers;
+    private agentRegistry;
+    private contextStore;
+    private suggestionEngine;
+    private runHandler;
+    private stateManager;
+    constructor({ runtimeUrl, runtimeTransport, headers, properties, agents__unsafe_dev_only, tools, suggestionsConfig, }: CopilotKitCoreConfig);
+    /**
+     * Internal method used by delegate classes and subclasses to notify subscribers
+     */
+    protected notifySubscribers(handler: (subscriber: CopilotKitCoreSubscriber) => void | Promise<void>, errorMessage: string): Promise<void>;
+    /**
+     * Internal method used by delegate classes to emit errors
+     */
+    private emitError;
+    /**
+     * Snapshot accessors
+     */
+    get context(): Readonly<Record<string, Context>>;
+    get agents(): Readonly<Record<string, AbstractAgent>>;
+    get tools(): Readonly<FrontendTool<any>[]>;
+    get runtimeUrl(): string | undefined;
+    setRuntimeUrl(runtimeUrl: string | undefined): void;
+    get runtimeTransport(): CopilotRuntimeTransport;
+    setRuntimeTransport(runtimeTransport: CopilotRuntimeTransport): void;
+    get runtimeVersion(): string | undefined;
+    get headers(): Readonly<Record<string, string>>;
+    get properties(): Readonly<Record<string, unknown>>;
+    get runtimeConnectionStatus(): CopilotKitCoreRuntimeConnectionStatus;
+    /**
+     * Configuration updates
+     */
+    setHeaders(headers: Record<string, string>): void;
+    setProperties(properties: Record<string, unknown>): 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 (delegated to ContextStore)
+     */
+    addContext(context: Context): string;
+    removeContext(id: string): void;
+    /**
+     * Suggestions management (delegated to SuggestionEngine)
+     */
+    addSuggestionsConfig(config: SuggestionsConfig): string;
+    removeSuggestionsConfig(id: string): void;
+    reloadSuggestions(agentId: string): void;
+    clearSuggestions(agentId: string): void;
+    getSuggestions(agentId: string): CopilotKitCoreGetSuggestionsResult;
+    /**
+     * 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;
+    setTools(tools: FrontendTool<any>[]): void;
+    /**
+     * Subscription lifecycle
+     */
+    subscribe(subscriber: CopilotKitCoreSubscriber): CopilotKitCoreSubscription;
+    /**
+     * Agent connectivity (delegated to RunHandler)
+     */
+    connectAgent(params: CopilotKitCoreConnectAgentParams): Promise<_ag_ui_client.RunAgentResult>;
+    stopAgent(params: CopilotKitCoreStopAgentParams): void;
+    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
+     */
+    private buildFrontendTools;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+    transport?: CopilotRuntimeTransport;
+}
+declare class ProxiedCopilotRuntimeAgent extends HttpAgent {
+    runtimeUrl?: string;
+    private transport;
+    private singleEndpointUrl?;
+    constructor(config: ProxiedCopilotRuntimeAgentConfig);
+    abortRun(): void;
+    connect(input: RunAgentInput): Observable<BaseEvent>;
+    run(input: RunAgentInput): Observable<BaseEvent>;
+    clone(): ProxiedCopilotRuntimeAgent;
+    private createSingleRouteRequestInit;
+}
+
+declare function completePartialMarkdown(input: string): string;
+
+export { AgentRegistry, ContextStore, CopilotKitCore, type CopilotKitCoreAddAgentParams, type CopilotKitCoreConfig, type CopilotKitCoreConnectAgentParams, CopilotKitCoreErrorCode, type CopilotKitCoreFriendsAccess, type CopilotKitCoreGetSuggestionsResult, type CopilotKitCoreGetToolParams, type CopilotKitCoreRunAgentParams, CopilotKitCoreRuntimeConnectionStatus, type CopilotKitCoreStopAgentParams, type CopilotKitCoreSubscriber, type CopilotKitCoreSubscription, type CopilotRuntimeTransport, type DynamicSuggestionsConfig, type FrontendTool, ProxiedCopilotRuntimeAgent, type ProxiedCopilotRuntimeAgentConfig, RunHandler, StateManager, type StaticSuggestionsConfig, type Suggestion, type SuggestionAvailability, SuggestionEngine, type SuggestionsConfig, ToolCallStatus, completePartialMarkdown };