@pillar-ai/sdk 0.1.13 → 0.1.14

package/README.md

@@ -61,62 +61,61 @@ First, register your product in the [Pillar app](https://app.trypillar.com):
 ```javascript
 import { Pillar } from "@pillar-ai/sdk";
 
-await Pillar.init({
+// Initialize and get the instance
+const pillar = await Pillar.init({
   productKey: "your-product-key", // From Pillar app
 });
+
+// Now you can use instance methods
+pillar.setContext({ currentPage: "/dashboard" });
+pillar.open();
+```
+
+You can also get the instance later using `Pillar.getInstance()`:
+
+```javascript
+// Anywhere in your app after init
+const pillar = Pillar.getInstance();
+pillar?.setContext({ currentPage: "/settings" });
 ```
 
 ## Defining Actions
 
-Define what your co-pilot can do. When users make requests, Pillar matches intent to actions and executes them:
+Define what your co-pilot can do. When users make requests, Pillar matches intent to actions and executes them.
+
+### Register Task Handlers
+
+Use `onTask` to handle actions when the AI executes them:
 
 ```javascript
-Pillar.init({
+const pillar = await Pillar.init({
   productKey: "your-product-key",
-  actions: {
-    // Navigation actions
-    go_to_settings: {
-      type: "navigate",
-      label: "Open Settings",
-      description: "Navigate to the settings page",
-      path: "/settings",
-    },
+});
 
-    // Trigger actions that execute code
-    export_to_csv: {
-      type: "trigger",
-      label: "Export to CSV",
-      description: "Export current data to a CSV file",
-    },
+// Handle navigation
+pillar.onTask("go_to_settings", (data) => {
+  router.push("/settings");
+});
 
-    // Actions with data schemas
-    update_preferences: {
-      type: "trigger",
-      label: "Update Preferences",
-      description: "Update notification preferences",
-      dataSchema: {
-        emailAlerts: { type: "boolean" },
-        frequency: { type: "string", enum: ["daily", "weekly", "monthly"] },
-      },
-    },
-  },
+// Handle triggers
+pillar.onTask("export_to_csv", async (data) => {
+  await downloadCSV();
+});
 
-  onTask: (actionName, data) => {
-    // Your code executes here
-    if (actionName === "export_to_csv") {
-      downloadCSV();
-    }
-    if (actionName === "update_preferences") {
-      updateUserPreferences(data.emailAlerts, data.frequency);
-    }
-  },
+// Handle actions with data
+pillar.onTask("update_preferences", (data) => {
+  updateUserPreferences(data.emailAlerts, data.frequency);
 });
 ```
 
+### Code-First Action Definitions
+
+For production, define actions in code and sync them via the `pillar-sync` CLI during CI/CD. See [Setting Up Actions](https://trypillar.com/docs/guides/actions) for details.
+
 ## Configuration
 
 ```javascript
-Pillar.init({
+const pillar = await Pillar.init({
   productKey: "your-product-key",
 
   panel: {
@@ -141,12 +140,15 @@ Pillar.init({
 
 | Method | Description |
 |--------|-------------|
-| `Pillar.init(config)` | Initialize the SDK with your configuration |
-| `Pillar.open()` | Open the co-pilot panel |
-| `Pillar.close()` | Close the co-pilot panel |
-| `Pillar.toggle()` | Toggle the co-pilot panel |
-| `Pillar.setContext(context)` | Update the user/product context |
-| `Pillar.on(event, callback)` | Subscribe to SDK events |
+| `Pillar.init(config)` | Initialize the SDK, returns the instance |
+| `Pillar.getInstance()` | Get the initialized SDK instance |
+| `pillar.open()` | Open the co-pilot panel |
+| `pillar.close()` | Close the co-pilot panel |
+| `pillar.toggle()` | Toggle the co-pilot panel |
+| `pillar.setContext(context)` | Update the user/product context |
+| `pillar.on(event, callback)` | Subscribe to SDK events |
+
+> **Note:** `Pillar.init()` and `Pillar.getInstance()` are static methods on the class. All other methods (lowercase `pillar`) are instance methods - call them on the instance returned from `init()` or `getInstance()`.
 
 For complete API documentation, see the [API Reference](https://trypillar.com/docs/reference/core).
 

package/dist/actions/types.d.ts

@@ -31,12 +31,13 @@
  * - open_modal: Open a modal or dialog
  * - fill_form: Fill form fields with data
  * - trigger_action: Trigger a custom action
+ * - query: Fetch data from the client and return to the agent (implies returns: true)
  * - copy_text: Copy text to clipboard
  * - external_link: Open an external URL
  * - start_tutorial: Start a tutorial/walkthrough
  * - inline_ui: Display inline UI card in chat
  */
-export type ActionType = 'navigate' | 'open_modal' | 'fill_form' | 'trigger_action' | 'copy_text' | 'external_link' | 'start_tutorial' | 'inline_ui';
+export type ActionType = 'navigate' | 'open_modal' | 'fill_form' | 'trigger_action' | 'query' | 'copy_text' | 'external_link' | 'start_tutorial' | 'inline_ui';
 /**
  * Supported platforms for action deployments.
  */
@@ -169,7 +170,7 @@ export interface ActionDefinition<TData = Record<string, unknown>> {
  *
  * Action names should be snake_case identifiers.
  */
-export type ActionDefinitions = Record<string, ActionDefinition<any>>;
+export type ActionDefinitions = Record<string, ActionDefinition<unknown>>;
 /**
  * Metadata for a single action in the manifest (no handler).
  *
@@ -275,7 +276,7 @@ export interface SyncActionDefinition<TData = Record<string, unknown>> {
  *
  * Use this type for your actions file that gets synced via CI/CD.
  */
-export type SyncActionDefinitions = Record<string, SyncActionDefinition<any>>;
+export type SyncActionDefinitions = Record<string, SyncActionDefinition<unknown>>;
 /**
  * Base data types for each action type.
  * These are automatically inferred from the action's `type` field.
@@ -306,6 +307,10 @@ export interface CopyTextData {
     /** Text to copy to clipboard */
     text?: string;
 }
+export interface QueryActionData {
+    /** Query parameters passed to the handler */
+    [key: string]: unknown;
+}
 /**
  * Maps action types to their default data shapes.
  * Used for automatic type inference in onTask handlers.
@@ -313,6 +318,7 @@ export interface CopyTextData {
 export interface ActionTypeDataMap {
     navigate: NavigateActionData;
     trigger_action: TriggerActionData;
+    query: QueryActionData;
     inline_ui: InlineUIData;
     external_link: ExternalLinkData;
     copy_text: CopyTextData;

package/dist/api/client.d.ts

@@ -5,10 +5,10 @@
 import type { TaskButtonData } from '../components/Panel/TaskButton';
 import type { ResolvedConfig } from '../core/config';
 import type { Context, Suggestion, UserProfile } from '../core/context';
-import type { ExecutionPlan } from '../core/plan';
 import type { Workflow } from '../core/workflow';
 import type { UserContextItem } from '../types/user-context';
-import type { ChatImage, ImageUploadResponse } from './mcp-client';
+import type { ActionRequest, ChatImage, ImageUploadResponse } from './mcp-client';
+import { MCPClient } from './mcp-client';
 export interface ArticleSummary {
     id: string;
     title: string;
@@ -23,6 +23,8 @@ export interface ChatMessage {
 export interface SuggestedQuestion {
     id: string;
     text: string;
+    /** If true, this is an admin-configured suggestion that should rank first */
+    manual?: boolean;
 }
 export interface ChatResponse {
     message: string;
@@ -32,21 +34,31 @@ export interface ChatResponse {
     messageId?: string;
     actions?: TaskButtonData[];
 }
+/**
+ * Child item within a progress event (e.g., search source, plan step).
+ */
+export interface ProgressChild {
+    id: string;
+    label: string;
+    url?: string;
+}
+/**
+ * Progress event for tracking AI response generation steps.
+ * Uses a generic design where the server controls display text via `label`.
+ *
+ * The new schema uses `id` and `status` fields. Legacy fields are kept
+ * for backwards compatibility with older backend versions.
+ */
 export interface ProgressEvent {
-    kind: 'processing' | 'search' | 'search_complete' | 'query' | 'query_complete' | 'query_failed' | 'generating';
-    message?: string;
+    kind: string;
+    id?: string;
+    label?: string;
+    status?: 'active' | 'done' | 'error';
+    text?: string;
+    children?: ProgressChild[];
+    metadata?: Record<string, unknown>;
     progress_id?: string;
-    metadata?: {
-        sources?: Array<{
-            title: string;
-            url: string;
-            score?: number;
-        }>;
-        result_count?: number;
-        query?: string;
-        action_name?: string;
-        no_sources_used?: boolean;
-    };
+    message?: string;
 }
 /**
  * Server-side embed config response.
@@ -69,12 +81,48 @@ export interface ServerEmbedConfig {
         };
     };
 }
+/**
+ * Conversation summary in history list.
+ */
+export interface ConversationSummary {
+    id: string;
+    title: string;
+    startedAt: string | null;
+    lastMessageAt: string | null;
+    messageCount: number;
+}
+/**
+ * Full conversation with messages.
+ */
+export interface ConversationDetail extends ConversationSummary {
+    messages: Array<{
+        id: string;
+        role: 'user' | 'assistant';
+        content: string;
+        timestamp: string | null;
+    }>;
+}
 export declare class APIClient {
     private config;
     private abortControllers;
     private mcpClient;
+    private _externalUserId;
     constructor(config: ResolvedConfig);
+    /**
+     * Get the underlying MCP client.
+     * Used by Pillar for direct MCP operations like sendActionResult.
+     */
+    get mcp(): MCPClient;
     private get baseUrl();
+    /**
+     * Set the external user ID for authenticated users.
+     * This ID will be included in all subsequent requests.
+     */
+    setExternalUserId(userId: string): void;
+    /**
+     * Clear the external user ID (for logout).
+     */
+    clearExternalUserId(): void;
     /**
      * Get or create a persistent visitor ID.
      * Stored in localStorage to persist across sessions.
@@ -110,7 +158,7 @@ export declare class APIClient {
      * @returns Promise with signed URL and expiration
      */
     uploadImage(file: File): Promise<ImageUploadResponse>;
-    chat(message: string, history?: ChatMessage[], onChunk?: (chunk: string) => void, articleSlug?: string, existingConversationId?: string | null, onActions?: (actions: TaskButtonData[]) => void, onPlan?: (plan: ExecutionPlan) => void, userContext?: UserContextItem[], images?: ChatImage[], onProgress?: (progress: ProgressEvent) => void): Promise<ChatResponse>;
+    chat(message: string, history?: ChatMessage[], onChunk?: (chunk: string) => void, articleSlug?: string, existingConversationId?: string | null, onActions?: (actions: TaskButtonData[]) => void, userContext?: UserContextItem[], images?: ChatImage[], onProgress?: (progress: ProgressEvent) => void, onConversationStarted?: (conversationId: string, messageId?: string) => void, onActionRequest?: (request: ActionRequest) => Promise<void>): Promise<ChatResponse>;
     /**
      * Legacy chat method using the old /ai/chat/ endpoint.
      * @deprecated Use chat() which uses the MCP protocol.
@@ -154,5 +202,32 @@ export declare class APIClient {
      * Note: Context is passed to the MCP ask tool as additional arguments.
      */
     chatWithContext(message: string, history: ChatMessage[] | undefined, ctx: Context, userProfile: UserProfile, onChunk?: (chunk: string) => void, existingConversationId?: string | null, onActions?: (actions: TaskButtonData[]) => void): Promise<ChatResponse>;
+    /**
+     * Identify the current user after login.
+     * Links the anonymous visitor to the authenticated user ID, enabling
+     * cross-device conversation history.
+     *
+     * @param userId - Client's authenticated user ID
+     * @param profile - Optional user profile data
+     */
+    identify(userId: string, profile?: {
+        name?: string;
+        email?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<void>;
+    /**
+     * List past conversations for the current visitor.
+     *
+     * @param limit - Max number of conversations to return (default: 20, max: 50)
+     * @returns List of conversation summaries
+     */
+    listConversations(limit?: number): Promise<ConversationSummary[]>;
+    /**
+     * Get a single conversation with all messages.
+     *
+     * @param conversationId - UUID of the conversation
+     * @returns Conversation with messages
+     */
+    getConversation(conversationId: string): Promise<ConversationDetail | null>;
     cancelAllRequests(): void;
 }

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

@@ -6,8 +6,8 @@
  */
 import type { TaskButtonData } from '../components/Panel/TaskButton';
 import type { ResolvedConfig } from '../core/config';
-import type { ExecutionPlan } from '../core/plan';
 import type { UserContextItem } from '../types/user-context';
+import { type LogEntry } from '../utils/debug';
 import type { ArticleSummary } from './client';
 /** MCP Tool result content */
 interface ToolResultContent {
@@ -23,7 +23,8 @@ export interface ToolResult {
     structuredContent?: {
         sources?: ArticleSummary[];
         actions?: ActionData[];
-        plan?: ExecutionPlan;
+        /** Registered actions for dynamic action tools (persisted across turns) */
+        registered_actions?: Record<string, unknown>[];
     };
     _meta?: {
         conversation_id?: string;
@@ -45,6 +46,17 @@ export interface ActionData {
     score: number;
     data: Record<string, unknown>;
 }
+/** Action request from agent (unified for all action execution) */
+export interface ActionRequest {
+    /** Action name to execute */
+    action_name: string;
+    /** Parameters for the action */
+    parameters: Record<string, unknown>;
+    /** Full action definition (optional, for handler lookup) */
+    action?: ActionData;
+    /** Unique ID for this specific tool invocation (for result correlation) */
+    tool_call_id?: string;
+}
 /** Streaming callbacks for tool calls */
 export interface StreamCallbacks {
     /** Called for each text token */
@@ -53,29 +65,32 @@ export interface StreamCallbacks {
     onSources?: (sources: ArticleSummary[]) => void;
     /** Called when actions are available */
     onActions?: (actions: ActionData[]) => void;
-    /** Called when a plan is created (from plan.created event) */
-    onPlan?: (plan: ExecutionPlan) => void;
+    /** Called when registered actions are received (for dynamic action tools) */
+    onRegisteredActions?: (actions: Record<string, unknown>[]) => void;
     /** Called on error */
     onError?: (error: string) => void;
+    /** Called when conversation_started event is received (early conversation_id) */
+    onConversationStarted?: (conversationId: string, messageId?: string) => void;
     /** Called when stream is complete */
     onComplete?: (conversationId?: string, queryLogId?: string) => void;
-    /** Called for progress updates (search, query, generating, etc.) */
+    /** Called for progress updates (search, query, generating, thinking, etc.) */
     onProgress?: (progress: {
         kind: string;
-        message?: string;
+        id?: string;
+        label?: string;
+        status?: 'active' | 'done' | 'error';
+        text?: string;
+        children?: Array<{
+            id: string;
+            label: string;
+            url?: string;
+        }>;
+        metadata?: Record<string, unknown>;
         progress_id?: string;
-        metadata?: {
-            sources?: Array<{
-                title: string;
-                url: string;
-                score?: number;
-            }>;
-            result_count?: number;
-            query?: string;
-            action_name?: string;
-            no_sources_used?: boolean;
-        };
+        message?: string;
     }) => void;
+    /** Called when agent requests action execution (unified handler) */
+    onActionRequest?: (request: ActionRequest) => Promise<void>;
 }
 /** Image for chat requests (from upload-image endpoint) */
 export interface ChatImage {
@@ -92,7 +107,27 @@ export interface ImageUploadResponse {
 export declare class MCPClient {
     private config;
     private requestId;
+    private _externalUserId;
     constructor(config: ResolvedConfig);
+    /**
+     * Set the external user ID for authenticated users.
+     * Enables cross-device conversation history.
+     */
+    setExternalUserId(userId: string): void;
+    /**
+     * Get or create a persistent visitor ID.
+     * Stored in localStorage to persist across sessions.
+     */
+    private getVisitorId;
+    /**
+     * Get or create a session ID for MCP request correlation.
+     * Stored in sessionStorage to persist only for the current browser session.
+     */
+    private getSessionId;
+    /**
+     * Get the current page URL for analytics tracking.
+     */
+    private getPageUrl;
     private get baseUrl();
     private get headers();
     private nextId;
@@ -132,104 +167,83 @@ export declare class MCPClient {
         articleSlug?: string;
         userContext?: UserContextItem[];
         images?: ChatImage[];
+        history?: Array<{
+            role: 'user' | 'assistant';
+            content: string;
+        }>;
+        /** Registered actions from previous turns (for dynamic action tools) */
+        registeredActions?: Record<string, unknown>[];
         signal?: AbortSignal;
     }): Promise<ToolResult>;
     /**
-     * Continue plan execution after receiving step result.
+     * Send action result back to the agent.
      *
-     * Called by the SDK after executing a step that has
-     * requires_result_feedback=true. The server analyzes the result
-     * and updates subsequent steps if needed.
+     * Called after executing a query action (returns_data=true).
+     * The result is sent to the agent for further reasoning in the ReAct loop.
      *
-     * @param planId - UUID of the plan
-     * @param stepId - UUID of the completed step
-     * @param result - Step execution result
-     * @returns Updated plan with all steps
+     * @param actionName - The name of the action 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
      */
-    continuePlan(planId: string, stepId: string, result: unknown): Promise<{
-        plan: ExecutionPlan;
-    }>;
+    sendActionResult(actionName: string, result: unknown, toolCallId?: string): Promise<void>;
     /**
-     * Cancel an in-progress plan.
+     * Send a client-side log to the server for debugging.
      *
-     * Marks the plan as cancelled and skips any pending steps.
+     * Logs are correlated with agent sessions via the MCP session ID.
+     * Use this to forward important SDK events to server logs.
      *
-     * @param planId - UUID of the plan to cancel
-     * @returns Updated plan with cancelled status
+     * @param level - Log level: 'log', 'warn', or 'error'
+     * @param message - The log message
+     * @param data - Optional additional data to include
      */
-    cancelPlan(planId: string): Promise<{
-        plan: ExecutionPlan;
-    }>;
+    sendLog(level: 'log' | 'warn' | 'error', message: string, data?: unknown): Promise<void>;
     /**
-     * Get current state of a plan.
+     * Send a batch of client-side logs to the server.
      *
-     * Returns the plan and all its steps with current statuses.
+     * Logs are buffered and sent periodically (every 5 seconds by default)
+     * to reduce network requests. This method is called by the debug module.
      *
-     * @param planId - UUID of the plan
-     * @returns Plan with all steps
+     * @param logs - Array of log entries to send
      */
-    getPlan(planId: string): Promise<{
-        plan: ExecutionPlan;
-    }>;
+    sendLogBatch(logs: LogEntry[]): void;
     /**
-     * Start a plan that was waiting for user confirmation.
+     * Check if a conversation has a resumable interrupted session.
      *
-     * For plans with auto_execute=false, the user must explicitly
-     * start execution by calling this method.
-     *
-     * @param planId - UUID of the plan to start
-     * @returns Updated plan with executing status
+     * @param conversationId - The conversation UUID to check
+     * @returns Session status with resumption details, or null if not resumable
      */
-    startPlan(planId: string): Promise<{
-        plan: ExecutionPlan;
-    }>;
+    getConversationStatus(conversationId: string): Promise<ConversationStatus | null>;
     /**
-     * Retry a failed step.
+     * Resume an interrupted conversation.
      *
-     * Increments the retry count and resets the step to ready status.
-     * Only works if the step is retriable and hasn't exceeded max_retries.
+     * Returns a streaming response that continues the conversation
+     * from where it was interrupted.
      *
-     * @param planId - UUID of the plan
-     * @param stepId - UUID of the step to retry
-     * @returns Updated plan with step reset to ready
-     */
-    retryStep(planId: string, stepId: string): Promise<{
-        plan: ExecutionPlan;
-    }>;
-    /**
-     * Mark a step as failed.
-     *
-     * Records the error and determines if the plan should also fail
-     * (if step is not retriable or out of retries).
-     *
-     * @param planId - UUID of the plan
-     * @param stepId - UUID of the failed step
-     * @param errorMessage - Optional error message
-     * @returns Updated plan with failed step
+     * @param conversationId - The conversation to resume
+     * @param userContext - Optional current page context
+     * @param callbacks - Streaming callbacks
      */
-    failStep(planId: string, stepId: string, errorMessage?: string): Promise<{
-        plan: ExecutionPlan;
-    }>;
+    resumeConversation(conversationId: string, userContext: Record<string, unknown> | undefined, callbacks: StreamCallbacks): Promise<void>;
     /**
-     * Skip a step and advance to the next one.
-     *
-     * @param planId - UUID of the plan
-     * @param stepId - UUID of the step to skip
-     * @returns Updated plan with skipped step and next step ready
+     * Handle events from the resume stream.
      */
-    skipStep(planId: string, stepId: string): Promise<{
-        plan: ExecutionPlan;
+    private handleResumeStreamEvent;
+}
+/**
+ * Conversation status for session resumption.
+ */
+export interface ConversationStatus {
+    resumable: boolean;
+    message_id?: string;
+    elapsed_ms?: number;
+    user_message?: string;
+    partial_response?: string;
+    summary?: string;
+    accomplished?: Array<{
+        action: string;
+        result_summary: string;
     }>;
-    /**
-     * Send action result back to the agent.
-     *
-     * Called after executing a query action (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 result - The result data to send back to the agent
-     */
-    sendActionResult(actionName: string, result: unknown): void;
 }
 /**
  * Convert ActionData from MCP response to TaskButtonData for UI rendering.