@pillar-ai/sdk 0.1.19 → 0.1.22

package/dist/api/ag-ui-client.d.ts

@@ -0,0 +1,102 @@
+/**
+ * AG-UI Protocol Client for Pillar SDK
+ *
+ * Implements the AG-UI specification for streaming agent interactions.
+ * Uses the @ag-ui/client HttpAgent for transport.
+ *
+ * Copyright (C) 2025 Pillar Team
+ */
+import type { ResolvedConfig } from '../core/config';
+export interface AGUIStreamCallbacks {
+    /** Called when run starts */
+    onRunStarted?: (runId: string) => void;
+    /** Called when run completes successfully */
+    onRunFinished?: () => void;
+    /** Called on error */
+    onError?: (error: Error) => void;
+    /** Called when a step starts */
+    onStepStarted?: (stepName: string) => void;
+    /** Called when a step finishes */
+    onStepFinished?: (stepName: string) => void;
+    /** Called for text message streaming */
+    onTextContent?: (messageId: string, delta: string) => void;
+    /** Called when text message completes */
+    onTextComplete?: (messageId: string, fullContent: string) => void;
+    /** Called when tool call starts (for UI display) */
+    onToolCallStart?: (toolCallId: string, toolName: string) => void;
+    /** Called with tool call arguments */
+    onToolCallArgs?: (toolCallId: string, argsJson: string) => void;
+    /** Called when tool call completes */
+    onToolCallEnd?: (toolCallId: string) => void;
+    /** Called when tool result is available */
+    onToolCallResult?: (toolCallId: string, result: string) => void;
+    /** Called for state delta events (sources, actions, plan) */
+    onStateDelta?: (delta: unknown[]) => void;
+    /** Called for state snapshots */
+    onStateSnapshot?: (state: unknown) => void;
+}
+export interface ClientTool {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    /** Handler function - called when agent requests this tool */
+    handler?: (args: Record<string, unknown>) => Promise<unknown>;
+}
+export declare class AGUIClient {
+    private config;
+    private agent;
+    private currentRunId;
+    private currentThreadId;
+    private messageAccumulators;
+    private toolArgAccumulators;
+    private toolCallNames;
+    private registeredTools;
+    constructor(config: ResolvedConfig);
+    /**
+     * Get or create a persistent thread ID for this session.
+     */
+    private getOrCreateThreadId;
+    private getBrowserLanguage;
+    /**
+     * Register a client-side tool that can be called by the agent.
+     */
+    registerTool(tool: ClientTool): void;
+    /**
+     * Unregister a client-side tool.
+     */
+    unregisterTool(toolName: string): void;
+    /**
+     * Send a message and stream the agent's response.
+     */
+    chat(message: string, callbacks: AGUIStreamCallbacks, options?: {
+        history?: Array<{
+            role: 'user' | 'assistant';
+            content: string;
+        }>;
+        userContext?: Array<{
+            type: string;
+            [key: string]: unknown;
+        }>;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * Execute a client-side tool if registered.
+     */
+    private maybeExecuteClientTool;
+    /**
+     * Send tool execution result back to the server.
+     */
+    sendToolResult(toolCallId: string, result: unknown, error?: string): Promise<void>;
+    /**
+     * Start a new conversation thread.
+     */
+    newThread(): string;
+    /**
+     * Get current thread ID.
+     */
+    get threadId(): string;
+    /**
+     * Get current run ID.
+     */
+    get runId(): string | null;
+}

package/dist/api/ag-ui-handler.d.ts

@@ -0,0 +1,89 @@
+/**
+ * AG-UI Event Handler
+ *
+ * Processes AG-UI protocol events and maintains UI state.
+ * Replaces the complex JSON-RPC parsing in mcp-client.ts.
+ */
+import type { AGUIEvent } from '@ag-ui/core';
+/** A streaming text message being accumulated */
+export interface StreamingMessage {
+    id: string;
+    role: 'user' | 'assistant';
+    content: string;
+    complete: boolean;
+    /** Which step this message belongs to (for thinking vs response) */
+    stepName?: string;
+}
+/** A tool call being tracked */
+export interface ToolCallState {
+    id: string;
+    name: string;
+    args: string;
+    result?: unknown;
+    complete: boolean;
+    /** True if this tool executes on the client (query action) */
+    isClientSide?: boolean;
+}
+/** State delta data (sources, actions, plan, etc.) */
+export interface StateDeltaData {
+    type: string;
+    data: unknown;
+    timestamp: number;
+}
+/** Complete AG-UI state */
+export interface AGUIState {
+    /** Current run ID */
+    runId: string | null;
+    /** Thread ID (replaces conversation_id) */
+    threadId: string | null;
+    /** Current step name (e.g., "reasoning", "tool_execution") */
+    currentStep: string | null;
+    /** Streaming messages keyed by message ID */
+    messages: Map<string, StreamingMessage>;
+    /** Tool calls keyed by tool call ID */
+    toolCalls: Map<string, ToolCallState>;
+    /** State deltas received (sources, actions, plans) */
+    stateDeltas: StateDeltaData[];
+    /** Whether the run is complete */
+    isComplete: boolean;
+    /** Error if run failed */
+    error: Error | null;
+}
+export interface AGUIHandlerCallbacks {
+    /** Called whenever state changes */
+    onStateChange: (state: AGUIState) => void;
+    /** Called when an error occurs */
+    onError: (error: Error) => void;
+    /** Called when run completes successfully */
+    onComplete: () => void;
+    /** Called when a client-side tool needs execution */
+    onClientToolCall?: (toolCall: ToolCallState) => Promise<unknown>;
+}
+/**
+ * Create an AG-UI event handler.
+ *
+ * Returns an object with a handleEvent method that processes
+ * AG-UI events and updates internal state.
+ */
+export declare function createAGUIHandler(callbacks: AGUIHandlerCallbacks): {
+    handleEvent: (event: AGUIEvent) => Promise<void>;
+    reset: () => void;
+    getState: () => AGUIState;
+};
+/**
+ * Register a tool as client-side.
+ * Called when the SDK registers an action with returns: true.
+ */
+export declare function registerClientSideTool(toolName: string): void;
+/**
+ * Unregister a client-side tool.
+ */
+export declare function unregisterClientSideTool(toolName: string): void;
+/**
+ * Check if a tool executes on the client side.
+ */
+export declare function isClientSideTool(toolName: string): boolean;
+/**
+ * Get all registered client-side tools.
+ */
+export declare function getClientSideTools(): string[];

package/dist/api/mcp-client.d.ts

@@ -22,8 +22,12 @@ export interface ToolResult {
     isError?: boolean;
     structuredContent?: {
         sources?: ArticleSummary[];
-        actions?: ActionData[];
-        /** Registered actions for dynamic action tools (persisted across turns) */
+        tools?: ToolData[];
+        /** @deprecated Use tools instead */
+        actions?: ToolData[];
+        /** Registered tools for dynamic tool invocations (persisted across turns) */
+        registered_tools?: Record<string, unknown>[];
+        /** @deprecated Use registered_tools instead */
         registered_actions?: Record<string, unknown>[];
     };
     _meta?: {
@@ -31,32 +35,36 @@ export interface ToolResult {
         query_log_id?: string;
     };
 }
-/** Action data from MCP server */
-export interface ActionData {
+/** Tool data from MCP server */
+export interface ToolData {
     id: string;
     name: string;
     description: string;
     action_type: string;
-    /** If true, action executes immediately without user clicking */
+    /** If true, tool executes immediately without user clicking */
     auto_run: boolean;
-    /** If true, action completes without waiting for host confirmation */
+    /** If true, tool completes without waiting for host confirmation */
     auto_complete: boolean;
-    /** If true, action returns data for agent reasoning */
+    /** If true, tool returns data for agent reasoning */
     returns_data: boolean;
     score: number;
     data: Record<string, unknown>;
 }
-/** Action request from agent (unified for all action execution) */
-export interface ActionRequest {
-    /** Action name to execute */
+/** @deprecated Use ToolData instead */
+export type ActionData = ToolData;
+/** Tool request from agent (unified for all tool execution) */
+export interface ToolRequest {
+    /** Tool name to execute */
     action_name: string;
-    /** Parameters for the action */
+    /** Parameters for the tool */
     parameters: Record<string, unknown>;
-    /** Full action definition (optional, for handler lookup) */
-    action?: ActionData;
+    /** Full tool definition (optional, for handler lookup) */
+    action?: ToolData;
     /** Unique ID for this specific tool invocation (for result correlation) */
     tool_call_id?: string;
 }
+/** @deprecated Use ToolRequest instead */
+export type ActionRequest = ToolRequest;
 /** Token usage data from the agentic loop (sent after each LLM iteration) */
 export interface TokenUsage {
     /** Input tokens for this iteration */
@@ -84,9 +92,13 @@ export interface StreamCallbacks {
     onToken?: (token: string) => void;
     /** Called when sources are available */
     onSources?: (sources: ArticleSummary[]) => void;
-    /** Called when actions are available */
-    onActions?: (actions: ActionData[]) => void;
-    /** Called when registered actions are received (for dynamic action tools) */
+    /** Called when tools are available */
+    onTools?: (tools: ToolData[]) => void;
+    /** @deprecated Use onTools instead */
+    onActions?: (actions: ToolData[]) => void;
+    /** Called when registered tools are received (for dynamic tool invocations) */
+    onRegisteredTools?: (tools: Record<string, unknown>[]) => void;
+    /** @deprecated Use onRegisteredTools instead */
     onRegisteredActions?: (actions: Record<string, unknown>[]) => void;
     /** Called on error */
     onError?: (error: string) => void;
@@ -112,8 +124,10 @@ export interface StreamCallbacks {
     }) => void;
     /** Called immediately with the request ID (for cancellation support) */
     onRequestId?: (requestId: number) => void;
-    /** Called when agent requests action execution (unified handler) */
-    onActionRequest?: (request: ActionRequest) => Promise<void>;
+    /** Called when agent requests tool execution (unified handler) */
+    onToolRequest?: (request: ToolRequest) => Promise<void>;
+    /** @deprecated Use onToolRequest instead */
+    onActionRequest?: (request: ToolRequest) => Promise<void>;
     /** Called when token usage is updated (after each LLM iteration) */
     onTokenUsage?: (usage: TokenUsage) => void;
 }
@@ -199,7 +213,9 @@ export declare class MCPClient {
             role: 'user' | 'assistant';
             content: string;
         }>;
-        /** Registered actions from previous turns (for dynamic action tools) */
+        /** Registered tools from previous turns (for dynamic tool invocations) */
+        registeredTools?: Record<string, unknown>[];
+        /** @deprecated Use registeredTools instead */
         registeredActions?: Record<string, unknown>[];
         signal?: AbortSignal;
         /** Conversation ID - generated client-side, always provided */
@@ -217,16 +233,18 @@ export declare class MCPClient {
      */
     cancelStream(requestId: number | string): Promise<void>;
     /**
-     * Send action result back to the agent.
+     * Send tool result back to the agent.
      *
-     * Called after executing a query action (returns_data=true).
+     * Called after executing a query tool (returns_data=true).
      * The result is sent to the agent for further reasoning in the ReAct loop.
      *
-     * @param actionName - The name of the action that was executed
+     * @param toolName - The name of the tool that was executed
      * @param result - The result data to send back to the agent
      * @param toolCallId - Unique ID for this specific tool invocation (for result correlation)
      * @returns Promise that resolves when the result is delivered, or rejects on error
      */
+    sendToolResult(toolName: string, result: unknown, toolCallId?: string): Promise<void>;
+    /** @deprecated Use sendToolResult instead */
     sendActionResult(actionName: string, result: unknown, toolCallId?: string): Promise<void>;
     /**
      * Send a client-side log to the server for debugging.
@@ -266,10 +284,14 @@ export interface ConversationStatus {
     user_message?: string;
     partial_response?: string;
     display_trace?: DisplayStep[];
+    registered_tools?: Record<string, unknown>[];
+    /** @deprecated Use registered_tools instead */
     registered_actions?: Record<string, unknown>[];
 }
 /**
- * Convert ActionData from MCP response to TaskButtonData for UI rendering.
+ * Convert ToolData from MCP response to TaskButtonData for UI rendering.
  */
-export declare function actionToTaskButton(action: ActionData): TaskButtonData;
+export declare function toolToTaskButton(tool: ToolData): TaskButtonData;
+/** @deprecated Use toolToTaskButton instead */
+export declare const actionToTaskButton: typeof toolToTaskButton;
 export {};