@copilotkitnext/core 0.0.8 → 0.0.9-alpha.0

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { AbstractAgent, Message, Context, HttpAgentConfig, HttpAgent, RunAgentInput, BaseEvent } from '@ag-ui/client';
+import { AbstractAgent, Message, Context, RunAgentResult, HttpAgentConfig, HttpAgent, RunAgentInput, BaseEvent } from '@ag-ui/client';
 import { z } from 'zod';
 import { Observable } from 'rxjs';
 
@@ -23,71 +23,178 @@ type FrontendTool<T extends Record<string, unknown> = Record<string, unknown>> =
     agentId?: string;
 };
 
+/** 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>;
-    tools?: Record<string, FrontendTool<any>>;
+    /** Ordered collection of frontend tools available to the core. */
+    tools?: FrontendTool<any>[];
 }
 interface CopilotKitCoreAddAgentParams {
     id: string;
     agent: AbstractAgent;
 }
-interface RunAgentParams {
+interface CopilotKitCoreRunAgentParams {
     agent: AbstractAgent;
     withMessages?: Message[];
     agentId?: string;
 }
+interface CopilotKitCoreConnectAgentParams {
+    agent: AbstractAgent;
+    agentId?: string;
+}
+interface CopilotKitCoreGetToolParams {
+    toolName: string;
+    agentId?: string;
+}
+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 {
-    onRuntimeLoaded?: (event: {
+    onRuntimeConnectionStatusChanged?: (event: {
         copilotkit: CopilotKitCore;
+        status: CopilotKitCoreRuntimeConnectionStatus;
     }) => void | Promise<void>;
-    onRuntimeLoadError?: (event: {
+    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>;
+    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>;
+}
+declare enum CopilotKitCoreRuntimeConnectionStatus {
+    Disconnected = "disconnected",
+    Connected = "connected",
+    Connecting = "connecting",
+    Error = "error"
 }
 declare class CopilotKitCore {
-    runtimeUrl?: string;
-    didLoadRuntime: boolean;
-    context: Record<string, Context>;
-    tools: Record<string, FrontendTool<any>>;
-    agents: Record<string, AbstractAgent>;
     headers: Record<string, string>;
     properties: Record<string, unknown>;
-    version?: string;
+    private _context;
+    private _agents;
+    private _tools;
     private localAgents;
     private remoteAgents;
     private subscribers;
+    private _runtimeUrl?;
+    private _runtimeVersion?;
+    private _runtimeConnectionStatus;
     constructor({ runtimeUrl, headers, properties, agents, tools, }: CopilotKitCoreConfig);
-    private getRuntimeInfo;
-    private fetchRemoteAgents;
+    private assignAgentIds;
+    private notifySubscribers;
+    private emitError;
+    private resolveAgentId;
+    /**
+     * 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 runtimeVersion(): string | undefined;
+    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;
     getAgent(id: string): AbstractAgent | undefined;
+    /**
+     * Context management
+     */
     addContext({ description, value }: Context): string;
     removeContext(id: string): void;
-    setRuntimeUrl(runtimeUrl?: string): void;
+    /**
+     * Tool management
+     */
     addTool<T extends Record<string, unknown> = Record<string, unknown>>(tool: FrontendTool<T>): void;
-    removeTool(id: string): void;
-    setHeaders(headers: Record<string, string>): void;
-    setProperties(properties: Record<string, unknown>): void;
+    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;
+    /**
+     * Subscription lifecycle
+     */
     subscribe(subscriber: CopilotKitCoreSubscriber): () => void;
     unsubscribe(subscriber: CopilotKitCoreSubscriber): void;
-    runAgent({ agent, withMessages, agentId, }: RunAgentParams): Promise<Awaited<ReturnType<typeof agent.runAgent>>>;
+    /**
+     * Agent connectivity
+     */
+    connectAgent({ agent, agentId, }: CopilotKitCoreConnectAgentParams): Promise<RunAgentResult>;
+    runAgent({ agent, withMessages, agentId, }: CopilotKitCoreRunAgentParams): Promise<RunAgentResult>;
+    private processAgentResult;
+    private buildFrontendTools;
+    private createAgentErrorSubscriber;
 }
 
-interface CopilotKitHttpAgentConfig extends Omit<HttpAgentConfig, "url"> {
+interface ProxiedCopilotRuntimeAgentConfig extends Omit<HttpAgentConfig, "url"> {
     runtimeUrl?: string;
 }
-declare class CopilotKitHttpAgent extends HttpAgent {
-    isCopilotKitAgent: boolean;
+declare class ProxiedCopilotRuntimeAgent extends HttpAgent {
     runtimeUrl?: string;
-    constructor(config: CopilotKitHttpAgentConfig);
-    run(input: RunAgentInput): Observable<BaseEvent>;
+    constructor(config: ProxiedCopilotRuntimeAgentConfig);
+    connect(input: RunAgentInput): Observable<BaseEvent>;
 }
 
 declare function completePartialMarkdown(input: string): string;
 
-export { CopilotKitCore, type CopilotKitCoreAddAgentParams, type CopilotKitCoreConfig, type CopilotKitCoreSubscriber, CopilotKitHttpAgent, type CopilotKitHttpAgentConfig, type FrontendTool, type RunAgentParams, ToolCallStatus, completePartialMarkdown };
+export { CopilotKitCore, type CopilotKitCoreAddAgentParams, type CopilotKitCoreConfig, type CopilotKitCoreConnectAgentParams, CopilotKitCoreErrorCode, type CopilotKitCoreGetToolParams, type CopilotKitCoreRunAgentParams, CopilotKitCoreRuntimeConnectionStatus, type CopilotKitCoreSubscriber, type FrontendTool, ProxiedCopilotRuntimeAgent, type ProxiedCopilotRuntimeAgentConfig, ToolCallStatus, completePartialMarkdown };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { AbstractAgent, Message, Context, HttpAgentConfig, HttpAgent, RunAgentInput, BaseEvent } from '@ag-ui/client';
+import { AbstractAgent, Message, Context, RunAgentResult, HttpAgentConfig, HttpAgent, RunAgentInput, BaseEvent } from '@ag-ui/client';
 import { z } from 'zod';
 import { Observable } from 'rxjs';
 
@@ -23,71 +23,178 @@ type FrontendTool<T extends Record<string, unknown> = Record<string, unknown>> =
     agentId?: string;
 };
 
+/** 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>;
-    tools?: Record<string, FrontendTool<any>>;
+    /** Ordered collection of frontend tools available to the core. */
+    tools?: FrontendTool<any>[];
 }
 interface CopilotKitCoreAddAgentParams {
     id: string;
     agent: AbstractAgent;
 }
-interface RunAgentParams {
+interface CopilotKitCoreRunAgentParams {
     agent: AbstractAgent;
     withMessages?: Message[];
     agentId?: string;
 }
+interface CopilotKitCoreConnectAgentParams {
+    agent: AbstractAgent;
+    agentId?: string;
+}
+interface CopilotKitCoreGetToolParams {
+    toolName: string;
+    agentId?: string;
+}
+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 {
-    onRuntimeLoaded?: (event: {
+    onRuntimeConnectionStatusChanged?: (event: {
         copilotkit: CopilotKitCore;
+        status: CopilotKitCoreRuntimeConnectionStatus;
     }) => void | Promise<void>;
-    onRuntimeLoadError?: (event: {
+    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>;
+    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>;
+}
+declare enum CopilotKitCoreRuntimeConnectionStatus {
+    Disconnected = "disconnected",
+    Connected = "connected",
+    Connecting = "connecting",
+    Error = "error"
 }
 declare class CopilotKitCore {
-    runtimeUrl?: string;
-    didLoadRuntime: boolean;
-    context: Record<string, Context>;
-    tools: Record<string, FrontendTool<any>>;
-    agents: Record<string, AbstractAgent>;
     headers: Record<string, string>;
     properties: Record<string, unknown>;
-    version?: string;
+    private _context;
+    private _agents;
+    private _tools;
     private localAgents;
     private remoteAgents;
     private subscribers;
+    private _runtimeUrl?;
+    private _runtimeVersion?;
+    private _runtimeConnectionStatus;
     constructor({ runtimeUrl, headers, properties, agents, tools, }: CopilotKitCoreConfig);
-    private getRuntimeInfo;
-    private fetchRemoteAgents;
+    private assignAgentIds;
+    private notifySubscribers;
+    private emitError;
+    private resolveAgentId;
+    /**
+     * 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 runtimeVersion(): string | undefined;
+    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;
     getAgent(id: string): AbstractAgent | undefined;
+    /**
+     * Context management
+     */
     addContext({ description, value }: Context): string;
     removeContext(id: string): void;
-    setRuntimeUrl(runtimeUrl?: string): void;
+    /**
+     * Tool management
+     */
     addTool<T extends Record<string, unknown> = Record<string, unknown>>(tool: FrontendTool<T>): void;
-    removeTool(id: string): void;
-    setHeaders(headers: Record<string, string>): void;
-    setProperties(properties: Record<string, unknown>): void;
+    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;
+    /**
+     * Subscription lifecycle
+     */
     subscribe(subscriber: CopilotKitCoreSubscriber): () => void;
     unsubscribe(subscriber: CopilotKitCoreSubscriber): void;
-    runAgent({ agent, withMessages, agentId, }: RunAgentParams): Promise<Awaited<ReturnType<typeof agent.runAgent>>>;
+    /**
+     * Agent connectivity
+     */
+    connectAgent({ agent, agentId, }: CopilotKitCoreConnectAgentParams): Promise<RunAgentResult>;
+    runAgent({ agent, withMessages, agentId, }: CopilotKitCoreRunAgentParams): Promise<RunAgentResult>;
+    private processAgentResult;
+    private buildFrontendTools;
+    private createAgentErrorSubscriber;
 }
 
-interface CopilotKitHttpAgentConfig extends Omit<HttpAgentConfig, "url"> {
+interface ProxiedCopilotRuntimeAgentConfig extends Omit<HttpAgentConfig, "url"> {
     runtimeUrl?: string;
 }
-declare class CopilotKitHttpAgent extends HttpAgent {
-    isCopilotKitAgent: boolean;
+declare class ProxiedCopilotRuntimeAgent extends HttpAgent {
     runtimeUrl?: string;
-    constructor(config: CopilotKitHttpAgentConfig);
-    run(input: RunAgentInput): Observable<BaseEvent>;
+    constructor(config: ProxiedCopilotRuntimeAgentConfig);
+    connect(input: RunAgentInput): Observable<BaseEvent>;
 }
 
 declare function completePartialMarkdown(input: string): string;
 
-export { CopilotKitCore, type CopilotKitCoreAddAgentParams, type CopilotKitCoreConfig, type CopilotKitCoreSubscriber, CopilotKitHttpAgent, type CopilotKitHttpAgentConfig, type FrontendTool, type RunAgentParams, ToolCallStatus, completePartialMarkdown };
+export { CopilotKitCore, type CopilotKitCoreAddAgentParams, type CopilotKitCoreConfig, type CopilotKitCoreConnectAgentParams, CopilotKitCoreErrorCode, type CopilotKitCoreGetToolParams, type CopilotKitCoreRunAgentParams, CopilotKitCoreRuntimeConnectionStatus, type CopilotKitCoreSubscriber, type FrontendTool, ProxiedCopilotRuntimeAgent, type ProxiedCopilotRuntimeAgentConfig, ToolCallStatus, completePartialMarkdown };