@pillar-ai/sdk 0.1.14 → 0.1.15

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pillar, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/actions/types.d.ts

@@ -157,6 +157,18 @@ export interface ActionDefinition<TData = Record<string, unknown>> {
      * @default false
      */
     returns?: boolean;
+    /**
+     * Concrete examples of valid parameter objects for the AI to reference.
+     *
+     * Each example should have a `description` explaining the scenario
+     * and a `parameters` object matching the `dataSchema`.
+     * Useful for complex schemas where the AI benefits from seeing
+     * what a correct call looks like.
+     */
+    parameterExamples?: Array<{
+        description: string;
+        parameters: Record<string, unknown>;
+    }>;
     /**
      * Handler function executed when the action is triggered.
      *
@@ -189,6 +201,10 @@ export interface ActionManifestEntry {
     data_schema?: ActionDataSchema;
     default_data?: Record<string, unknown>;
     required_context?: Record<string, unknown>;
+    parameter_examples?: Array<{
+        description: string;
+        parameters: Record<string, unknown>;
+    }>;
 }
 /**
  * Action manifest - synced to server during CI/CD.
@@ -216,6 +232,11 @@ export interface ActionManifest {
      * Action definitions (without handlers).
      */
     actions: ActionManifestEntry[];
+    /**
+     * Custom agent guidance synced alongside actions.
+     * Injected into the AI agent's prompt as product_guidance.
+     */
+    agentGuidance?: string;
 }
 /**
  * Client info set during SDK initialization.
@@ -270,6 +291,15 @@ export interface SyncActionDefinition<TData = Record<string, unknown>> {
      * If true, the handler's return value is sent back to the agent.
      */
     returns?: boolean;
+    /**
+     * Concrete examples of valid parameter objects for the AI to reference.
+     * Each example should have a `description` and a `parameters` object
+     * matching the `dataSchema`.
+     */
+    parameterExamples?: Array<{
+        description: string;
+        parameters: Record<string, unknown>;
+    }>;
 }
 /**
  * Map of action name to sync definition (no handlers).

package/dist/api/client.d.ts

@@ -91,16 +91,44 @@ export interface ConversationSummary {
     lastMessageAt: string | null;
     messageCount: number;
 }
+/**
+ * Display step in the agent's timeline.
+ * This is a human-readable timeline that includes thinking, tool decisions, and tool results.
+ * Used for UI display of the agent's reasoning process.
+ */
+export interface DisplayStep {
+    step_type: 'thinking' | 'tool_decision' | 'parallel_tool_decision' | 'tool_result' | 'token_summary' | 'step_start' | 'generating' | 'narration';
+    iteration?: number;
+    timestamp_ms?: number;
+    content?: string;
+    tool?: string;
+    tools?: Array<{
+        tool: string;
+        arguments: Record<string, unknown>;
+    }>;
+    arguments?: Record<string, unknown>;
+    success?: boolean;
+    reasoning?: string;
+    label?: string;
+    [key: string]: unknown;
+}
+/**
+ * Message in conversation history.
+ * Contains display-oriented fields for UI rendering.
+ * LLM-native fields (llm_message) are kept server-side for conversation replay.
+ */
+export interface HistoryMessage {
+    id: string;
+    role: 'user' | 'assistant';
+    content: string;
+    timestamp: string | null;
+    display_trace?: DisplayStep[];
+}
 /**
  * Full conversation with messages.
  */
 export interface ConversationDetail extends ConversationSummary {
-    messages: Array<{
-        id: string;
-        role: 'user' | 'assistant';
-        content: string;
-        timestamp: string | null;
-    }>;
+    messages: HistoryMessage[];
 }
 export declare class APIClient {
     private config;
@@ -158,7 +186,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, userContext?: UserContextItem[], images?: ChatImage[], onProgress?: (progress: ProgressEvent) => void, onConversationStarted?: (conversationId: string, messageId?: string) => void, onActionRequest?: (request: ActionRequest) => Promise<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, assistantMessageId?: string) => void, onActionRequest?: (request: ActionRequest) => Promise<void>, signal?: AbortSignal, onRequestId?: (requestId: number) => void): Promise<ChatResponse>;
     /**
      * Legacy chat method using the old /ai/chat/ endpoint.
      * @deprecated Use chat() which uses the MCP protocol.

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

@@ -57,6 +57,27 @@ export interface ActionRequest {
     /** Unique ID for this specific tool invocation (for result correlation) */
     tool_call_id?: string;
 }
+/** Token usage data from the agentic loop (sent after each LLM iteration) */
+export interface TokenUsage {
+    /** Input tokens for this iteration */
+    prompt_tokens: number;
+    /** Output tokens for this iteration */
+    completion_tokens: number;
+    /** Cumulative prompt tokens across all iterations */
+    total_prompt_tokens: number;
+    /** Cumulative completion tokens across all iterations */
+    total_completion_tokens: number;
+    /** Current total tokens in context */
+    total_used: number;
+    /** Maximum context window for the model */
+    context_window: number;
+    /** Current context occupancy percentage (0-100) */
+    occupancy_pct: number;
+    /** Name of the model in use */
+    model_name: string;
+    /** Current iteration number (0-indexed) */
+    iteration: number;
+}
 /** Streaming callbacks for tool calls */
 export interface StreamCallbacks {
     /** Called for each text token */
@@ -69,8 +90,8 @@ export interface StreamCallbacks {
     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 conversation_started event is received (confirms conversation tracking) */
+    onConversationStarted?: (conversationId: string, assistantMessageId?: string) => void;
     /** Called when stream is complete */
     onComplete?: (conversationId?: string, queryLogId?: string) => void;
     /** Called for progress updates (search, query, generating, thinking, etc.) */
@@ -89,8 +110,12 @@ export interface StreamCallbacks {
         progress_id?: string;
         message?: string;
     }) => 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 token usage is updated (after each LLM iteration) */
+    onTokenUsage?: (usage: TokenUsage) => void;
 }
 /** Image for chat requests (from upload-image endpoint) */
 export interface ChatImage {
@@ -174,7 +199,18 @@ export declare class MCPClient {
         /** Registered actions from previous turns (for dynamic action tools) */
         registeredActions?: Record<string, unknown>[];
         signal?: AbortSignal;
+        /** Conversation ID - generated client-side, always provided */
+        conversationId?: string;
     }): Promise<ToolResult>;
+    /**
+     * Cancel an active streaming request.
+     *
+     * Sends a notifications/cancel JSON-RPC request to the backend, which
+     * signals the StreamRegistry to stop the LLM stream and cease billing.
+     *
+     * @param requestId - The JSON-RPC request ID of the stream to cancel
+     */
+    cancelStream(requestId: number | string): Promise<void>;
     /**
      * Send action result back to the agent.
      *
@@ -221,10 +257,10 @@ export declare class MCPClient {
      * from where it was interrupted.
      *
      * @param conversationId - The conversation to resume
-     * @param userContext - Optional current page context
+     * @param userContext - Optional current page context (highlighted text, DOM snapshot, etc.)
      * @param callbacks - Streaming callbacks
      */
-    resumeConversation(conversationId: string, userContext: Record<string, unknown> | undefined, callbacks: StreamCallbacks): Promise<void>;
+    resumeConversation(conversationId: string, userContext: UserContextItem[] | undefined, callbacks: StreamCallbacks): Promise<void>;
     /**
      * Handle events from the resume stream.
      */

package/dist/cli/sync.js

@@ -181,6 +181,8 @@ function buildManifest(actions, platform, version, gitSha, agentGuidance) {
       entry.default_data = definition.defaultData;
     if (definition.requiredContext)
       entry.required_context = definition.requiredContext;
+    if (definition.parameterExamples?.length)
+      entry.parameter_examples = definition.parameterExamples;
     entries.push(entry);
   }
   const manifest = {

package/dist/components/PagePilot/PagePilotBanner.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Page Pilot Banner Component
+ * Shows "Page being piloted by Agent" with stop button during interact_with_page actions.
+ * When a destructive action is detected, shows a confirmation variant with Allow/Deny buttons.
+ */
+import { h } from 'preact';
+export declare function PagePilotBanner(): h.JSX.Element | null;

package/dist/components/PagePilot/PagePilotManager.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Page Pilot Manager
+ * Manages the "Page being piloted by Agent" banner, rendering it outside Shadow DOM
+ * so it appears above all other content on the page.
+ */
+export declare class PagePilotManager {
+    private container;
+    private stylesInjected;
+    private unsubscribe;
+    private themeObserver;
+    private primaryColor;
+    /**
+     * Detect the current theme from the document
+     * Checks for .dark class (next-themes) or data-theme attribute
+     */
+    private detectThemeFromDOM;
+    /**
+     * Apply theme mode to container element
+     */
+    private applyTheme;
+    /**
+     * Set up observer to watch for theme changes on documentElement
+     */
+    private setupThemeObserver;
+    /**
+     * Initialize the page pilot manager
+     * @param primaryColor - Optional primary color from theme config to override the default
+     */
+    init(primaryColor?: string): void;
+    /**
+     * Update the primary color used by the banner
+     */
+    setPrimaryColor(color: string): void;
+    /**
+     * Destroy the page pilot manager
+     */
+    destroy(): void;
+    /**
+     * Render the banner component
+     */
+    private render;
+}

package/dist/components/PagePilot/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Page Pilot Components
+ * Banner and manager for displaying "Page being piloted by Agent" indicator
+ */
+export { PagePilotBanner } from './PagePilotBanner';
+export { PagePilotManager } from './PagePilotManager';
+export { PAGE_PILOT_STYLES } from './styles';

package/dist/components/PagePilot/styles.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Page Pilot Banner CSS Styles
+ * Injected into the document head (outside Shadow DOM)
+ * Uses the same CSS variables as the Pillar panel for consistent theming
+ */
+export declare const PAGE_PILOT_STYLES = "\n/* Pillar Page Pilot Banner Styles */\n\n/* Define CSS variables at the container level (same as panel) */\n#pillar-page-pilot-container {\n  /* Core colors - Light mode (default) */\n  --pillar-primary: #2563eb;\n  --pillar-primary-hover: #1d4ed8;\n  --pillar-bg: #ffffff;\n  --pillar-bg-secondary: #f9fafb;\n  --pillar-text: #1a1a1a;\n  --pillar-text-secondary: #374151;\n  --pillar-border: #e5e7eb;\n  --pillar-shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1);\n  --pillar-font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;\n  --pillar-radius-lg: 8px;\n  --pillar-radius-md: 6px;\n  --pillar-transition-fast: 0.15s ease;\n}\n\n/* Dark mode - Auto-detect from system preference */\n@media (prefers-color-scheme: dark) {\n  #pillar-page-pilot-container:not([data-theme=\"light\"]) {\n    --pillar-primary: #3b82f6;\n    --pillar-primary-hover: #60a5fa;\n    --pillar-bg: #1a1a1a;\n    --pillar-bg-secondary: #262626;\n    --pillar-text: #f5f5f5;\n    --pillar-text-secondary: #e5e5e5;\n    --pillar-border: #404040;\n    --pillar-shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.4);\n  }\n}\n\n/* Dark mode - Manual override via html class or data attribute */\nhtml.dark #pillar-page-pilot-container,\n[data-theme=\"dark\"] #pillar-page-pilot-container,\n#pillar-page-pilot-container[data-theme=\"dark\"] {\n  --pillar-primary: #3b82f6;\n  --pillar-primary-hover: #60a5fa;\n  --pillar-bg: #1a1a1a;\n  --pillar-bg-secondary: #262626;\n  --pillar-text: #f5f5f5;\n  --pillar-text-secondary: #e5e5e5;\n  --pillar-border: #404040;\n  --pillar-shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.4);\n}\n\n@keyframes pillar-pulse {\n  0%, 100% {\n    opacity: 1;\n    transform: scale(1);\n  }\n  50% {\n    opacity: 0.6;\n    transform: scale(1.1);\n  }\n}\n\n@keyframes pillar-banner-fade-in {\n  from {\n    opacity: 0;\n    transform: translateY(-100%);\n  }\n  to {\n    opacity: 1;\n    transform: translateY(0);\n  }\n}\n\n._pillar-page-pilot-banner {\n  position: fixed;\n  top: 0;\n  left: 0;\n  right: 0;\n  z-index: 99999;\n  font-family: var(--pillar-font-family);\n  display: flex;\n  justify-content: center;\n  pointer-events: none;\n  animation: pillar-banner-fade-in 0.2s ease-out;\n}\n\n/* Viewport outline \u2014 3px border on left, right, bottom; top handled by tab shape */\n._pillar-page-pilot-banner::before {\n  content: '';\n  position: fixed;\n  inset: 0;\n  border: 3px solid var(--pillar-primary);\n  border-top: none;\n  pointer-events: none;\n  z-index: 99998;\n}\n\n/* Top border segments on either side of the tab */\n._pillar-page-pilot-banner::after {\n  content: '';\n  position: fixed;\n  top: 0;\n  left: 0;\n  right: 0;\n  height: 3px;\n  background: var(--pillar-primary);\n  pointer-events: none;\n  z-index: 99997;\n}\n\n._pillar-page-pilot-banner__content {\n  position: relative;\n  z-index: 99999;\n  display: flex;\n  align-items: center;\n  gap: 12px;\n  padding: 6px 20px;\n  background: var(--pillar-primary);\n  color: #ffffff;\n  border-bottom-left-radius: var(--pillar-radius-lg);\n  border-bottom-right-radius: var(--pillar-radius-lg);\n  pointer-events: auto;\n}\n\n._pillar-page-pilot-banner__indicator {\n  width: 8px;\n  height: 8px;\n  background: #ffffff;\n  border-radius: 50%;\n  animation: pillar-pulse 1.5s ease-in-out infinite;\n  flex-shrink: 0;\n}\n\n._pillar-page-pilot-banner__text {\n  font-size: 13px;\n  font-weight: 500;\n  color: #ffffff;\n  white-space: nowrap;\n}\n\n._pillar-page-pilot-banner__stop {\n  display: flex;\n  align-items: center;\n  gap: 4px;\n  padding: 5px 10px;\n  margin-left: 4px;\n  font-family: inherit;\n  font-size: 12px;\n  font-weight: 500;\n  color: #ffffff;\n  background: rgba(255, 255, 255, 0.15);\n  border: 1px solid rgba(255, 255, 255, 0.3);\n  border-radius: var(--pillar-radius-md);\n  cursor: pointer;\n  transition: all var(--pillar-transition-fast);\n}\n\n._pillar-page-pilot-banner__stop:hover {\n  background: rgba(255, 255, 255, 0.25);\n  border-color: rgba(255, 255, 255, 0.5);\n}\n\n._pillar-page-pilot-banner__stop:active {\n  transform: scale(0.97);\n}\n\n._pillar-page-pilot-banner__stop-icon {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  width: 14px;\n  height: 14px;\n}\n\n._pillar-page-pilot-banner__stop-icon svg {\n  width: 100%;\n  height: 100%;\n}\n\n/* Confirmation variant \u2014 amber/warning theme */\n._pillar-page-pilot-banner--confirm ._pillar-page-pilot-banner__content {\n  background: #d97706;\n}\n\n._pillar-page-pilot-banner--confirm::before {\n  border-color: #d97706;\n}\n\n._pillar-page-pilot-banner--confirm::after {\n  background: #d97706;\n}\n\n._pillar-page-pilot-banner__warning-icon {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  width: 14px;\n  height: 14px;\n  flex-shrink: 0;\n}\n\n._pillar-page-pilot-banner__warning-icon svg {\n  width: 100%;\n  height: 100%;\n}\n\n._pillar-page-pilot-banner__deny {\n  display: flex;\n  align-items: center;\n  padding: 5px 12px;\n  margin-left: 4px;\n  font-family: inherit;\n  font-size: 12px;\n  font-weight: 500;\n  color: #ffffff;\n  background: rgba(255, 255, 255, 0.15);\n  border: 1px solid rgba(255, 255, 255, 0.3);\n  border-radius: var(--pillar-radius-md);\n  cursor: pointer;\n  transition: all var(--pillar-transition-fast);\n}\n\n._pillar-page-pilot-banner__deny:hover {\n  background: rgba(255, 255, 255, 0.25);\n  border-color: rgba(255, 255, 255, 0.5);\n}\n\n._pillar-page-pilot-banner__deny:active {\n  transform: scale(0.97);\n}\n\n._pillar-page-pilot-banner__allow {\n  display: flex;\n  align-items: center;\n  padding: 5px 12px;\n  font-family: inherit;\n  font-size: 12px;\n  font-weight: 600;\n  color: #d97706;\n  background: #ffffff;\n  border: 1px solid rgba(255, 255, 255, 0.8);\n  border-radius: var(--pillar-radius-md);\n  cursor: pointer;\n  transition: all var(--pillar-transition-fast);\n}\n\n._pillar-page-pilot-banner__allow:hover {\n  background: #fef3c7;\n}\n\n._pillar-page-pilot-banner__allow:active {\n  transform: scale(0.97);\n}\n";

package/dist/components/Panel/Header.d.ts

@@ -2,13 +2,11 @@
  * Panel Header Component
  * Navigation header with back, home, history, and close buttons
  */
-import { h } from 'preact';
-import { type ViewType } from '../../store/router';
+import { type ViewType } from "../../store/router";
 interface HeaderProps {
     currentView: ViewType;
-    customTitle?: string;
     /** Hide back and home navigation buttons */
     hideNavigation?: boolean;
 }
-export declare function Header({ currentView, customTitle, hideNavigation }: HeaderProps): h.JSX.Element;
+export declare function Header({ currentView, hideNavigation }: HeaderProps): import("preact").JSX.Element;
 export {};

package/dist/components/Panel/PanelContent.d.ts

@@ -2,5 +2,4 @@
  * Panel Content Component
  * Main panel layout with header, content, and chat input
  */
-import { h } from 'preact';
-export declare function PanelContent(): h.JSX.Element;
+export declare function PanelContent(): import("preact").JSX.Element;

package/dist/components/Panel/UnifiedChatInput.d.ts

@@ -18,6 +18,10 @@ interface UnifiedChatInputProps {
     showImageUpload?: boolean;
     /** Additional CSS class for the wrapper */
     className?: string;
+    /** Whether a response is currently streaming (shows Stop button) */
+    isStreaming?: boolean;
+    /** Called when user clicks the Stop button to cancel streaming */
+    onStop?: () => void;
 }
-export declare function UnifiedChatInput({ placeholder, disabled, onSubmit, showContextTags, showImageUpload, className, }: UnifiedChatInputProps): import("preact").JSX.Element;
+export declare function UnifiedChatInput({ placeholder, disabled, onSubmit, showContextTags, showImageUpload, className, isStreaming, onStop, }: UnifiedChatInputProps): import("preact").JSX.Element;
 export {};