@pillar-ai/sdk 0.1.14 → 0.1.15

package/dist/store/chat.d.ts

@@ -2,31 +2,54 @@
  * Chat Store
  * Signal-based state for chat messages and interaction
  */
-import type { ArticleSummary, ChatMessage } from '../api/client';
-import type { ChatImage } from '../api/mcp-client';
-import type { TaskButtonData } from '../components/Panel/TaskButton';
-import type { UserContextItem } from '../types/user-context';
-export type { ChatImage } from '../api/mcp-client';
+import type { ArticleSummary, ChatMessage, ConversationSummary, HistoryMessage } from "../api/client";
+import type { ChatImage } from "../api/mcp-client";
+import type { TaskButtonData } from "../components/Panel/TaskButton";
+import type { UserContextItem } from "../types/user-context";
+export type { ChatImage } from "../api/mcp-client";
 export interface ActionStatus {
-    status: 'pending' | 'success' | 'failed';
+    status: "pending" | "success" | "failed";
     completedAt?: number;
     errorMessage?: string;
 }
+/**
+ * A segment in an assistant message's timeline.
+ * Segments maintain chronological order so text and tool blocks interleave correctly.
+ *
+ * - "text": Model-generated content tokens (narration or final response)
+ * - "progress": A group of progress events (thinking, search, tool calls)
+ */
+export type MessageSegment = {
+    type: "text";
+    content: string;
+} | {
+    type: "progress";
+    events: ProgressEvent[];
+};
 export interface StoredChatMessage extends ChatMessage {
     id?: string;
-    feedback?: 'up' | 'down' | null;
+    feedback?: "up" | "down" | null;
     actions?: TaskButtonData[];
     sources?: ArticleSummary[];
     actionStatus?: Record<string, ActionStatus>;
     userContext?: UserContextItem[];
     images?: ChatImage[];
     progressEvents?: ProgressEvent[];
+    segments?: MessageSegment[];
 }
 export declare const messages: import("@preact/signals-core").Signal<StoredChatMessage[]>;
 export declare const conversationId: import("@preact/signals-core").Signal<string | null>;
 export declare const registeredActions: import("@preact/signals-core").Signal<Record<string, unknown>[]>;
 export declare const historyInvalidationCounter: import("@preact/signals-core").Signal<number>;
+export declare const optimisticConversations: import("@preact/signals-core").Signal<ConversationSummary[]>;
+/**
+ * Read the persisted conversation ID from localStorage (e.g. for restore on refresh).
+ */
+export declare function getStoredConversationId(): string | null;
 export declare const isLoading: import("@preact/signals-core").Signal<boolean>;
+export declare const activeRequestId: import("@preact/signals-core").Signal<number | null>;
+export declare const setActiveRequestId: (id: number | null) => void;
+export declare const isLoadingHistory: import("@preact/signals-core").Signal<boolean>;
 export interface InterruptedSession {
     conversationId: string;
     userMessage: string;
@@ -35,6 +58,30 @@ export interface InterruptedSession {
     elapsedMs: number;
 }
 export declare const interruptedSession: import("@preact/signals-core").Signal<InterruptedSession | null>;
+export interface TokenUsageState {
+    /** Input tokens for the latest iteration */
+    promptTokens: number;
+    /** Output tokens for the latest iteration */
+    completionTokens: number;
+    /** Cumulative prompt tokens across all iterations */
+    totalPromptTokens: number;
+    /** Cumulative completion tokens across all iterations */
+    totalCompletionTokens: number;
+    /** Current total tokens in context */
+    totalUsed: number;
+    /** Maximum context window for the model */
+    contextWindow: number;
+    /** Current context occupancy percentage (0-100) */
+    occupancyPct: number;
+    /** Name of the model in use */
+    modelName: string;
+    /** Current iteration number (0-indexed) */
+    iteration: number;
+}
+/** Current token usage for the active streaming response */
+export declare const tokenUsage: import("@preact/signals-core").Signal<TokenUsageState | null>;
+export declare const updateTokenUsage: (usage: TokenUsageState) => void;
+export declare const clearTokenUsage: () => void;
 export interface ProgressStatus {
     kind: string | null;
     message?: string;
@@ -59,7 +106,7 @@ export interface ProgressEvent {
     kind: string;
     id?: string;
     label?: string;
-    status?: 'active' | 'done' | 'error';
+    status?: "active" | "done" | "error";
     text?: string;
     children?: ProgressChild[];
     metadata?: Record<string, unknown>;
@@ -85,6 +132,12 @@ export declare const progressEvents: import("@preact/signals-core").Signal<Progr
  * This prevents multiple rows from appearing for the same event.
  */
 export declare const addProgressEventToLastMessage: (event: ProgressEvent) => void;
+/**
+ * Append a content token to the last assistant message's segments array.
+ * Creates a new text segment or appends to an existing one, while also
+ * updating `content` for backward compat (history persistence, feedback, etc.).
+ */
+export declare const appendTokenToSegments: (token: string) => void;
 export declare const isExpanded: import("@preact/signals-core").Signal<boolean>;
 /**
  * @deprecated Sources are now stored per-message on `StoredChatMessage.sources`. Will be removed in v2.0.
@@ -104,7 +157,7 @@ export declare const submitPendingTrigger: import("@preact/signals-core").Signal
 export declare const focusInputTrigger: import("@preact/signals-core").Signal<number>;
 export declare const userContext: import("@preact/signals-core").Signal<UserContextItem[]>;
 export declare const pendingUserContext: import("@preact/signals-core").Signal<UserContextItem[]>;
-export type ImageUploadStatus = 'uploading' | 'ready' | 'error';
+export type ImageUploadStatus = "uploading" | "ready" | "error";
 export interface PendingImage {
     id: string;
     file: File;
@@ -154,10 +207,24 @@ export declare const clearActions: () => void;
 export declare const setLoading: (loading: boolean) => void;
 export declare const setProgressStatus: (status: ProgressStatus) => void;
 export declare const clearProgressStatus: () => void;
+/**
+ * Mark all active progress events on the last assistant message as "done".
+ * Called when the user cancels/stops streaming so thinking timers stop.
+ */
+export declare const finalizeActiveProgressEvents: () => void;
 export declare const addProgressEvent: (event: ProgressEvent) => void;
 export declare const clearProgressEvents: () => void;
 export declare const setInterruptedSession: (session: InterruptedSession | null) => void;
 export declare const clearInterruptedSession: () => void;
+/**
+ * Remove the last assistant message if it has no content AND no progress events.
+ * Used after Stop / AbortError to clean up the empty placeholder
+ * that was added before streaming started.
+ *
+ * If the model was thinking (progress events exist), the message is kept
+ * so the user can still see the thinking text that was streamed.
+ */
+export declare const removeLastEmptyAssistantMessage: () => void;
 export declare const expandChat: () => void;
 export declare const collapseChat: () => void;
 export declare const setPrefillText: (text: string) => void;
@@ -172,12 +239,28 @@ export declare const clearUserContext: () => void;
 export declare const setPendingUserContext: (items: UserContextItem[]) => void;
 export declare const clearPendingUserContext: () => void;
 export declare const resetChat: () => void;
+/**
+ * Start loading a conversation from history.
+ * Shows loading state immediately for better UX.
+ */
+export declare const startLoadingHistory: () => void;
 /**
  * Load a conversation from history.
  * Populates the chat with messages from a previous conversation.
  */
-export declare const loadConversation: (id: string, historyMessages: Array<{
-    role: "user" | "assistant";
-    content: string;
-    id?: string;
-}>) => void;
+export declare const loadConversation: (id: string, historyMessages: HistoryMessage[]) => void;
+/**
+ * Stop loading history (on error or cancellation).
+ */
+export declare const stopLoadingHistory: () => void;
+/**
+ * Optimistically add a new conversation to the history list.
+ * The conversation appears immediately in the dropdown without
+ * waiting for the server to confirm via listConversations.
+ */
+export declare const addOptimisticConversation: (id: string, title: string) => void;
+/**
+ * Select and load a conversation by ID (fetch from API, navigate to chat, load messages).
+ * Use from history dropdown or anywhere else in the SDK that needs to open a past conversation.
+ */
+export declare const selectConversationById: (conversationId: string) => Promise<void>;

package/dist/store/index.d.ts

@@ -8,3 +8,4 @@ export * as chatStore from './chat';
 export * as contextStore from './context';
 export * as workflowStore from './workflow';
 export * as suggestionsStore from './suggestions';
+export * as pagePilotStore from './pagePilot';

package/dist/store/pagePilot.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Page Pilot Store
+ * Signal-based state for tracking when the AI agent is piloting the page
+ * (executing interact_with_page actions like click, type, select, etc.)
+ */
+/** Current piloting operation type */
+export type PilotOperation = 'click' | 'type' | 'select' | 'focus' | 'toggle' | null;
+/** Whether page interaction is currently in progress */
+export declare const isPiloting: import("@preact/signals-core").Signal<boolean>;
+/** Current operation type being performed */
+export declare const pilotOperation: import("@preact/signals-core").Signal<PilotOperation>;
+/** Flag to indicate cancellation was requested */
+export declare const isCancelled: import("@preact/signals-core").Signal<boolean>;
+/** Tool call ID of the current action (for sending cancellation result) */
+export declare const currentToolCallId: import("@preact/signals-core").Signal<string | null>;
+/**
+ * Start piloting mode - called when an interact_with_page action begins
+ */
+export declare function startPiloting(operation: PilotOperation, toolCallId?: string): void;
+/**
+ * Stop piloting mode - called when an interact_with_page action completes
+ */
+export declare function stopPiloting(): void;
+/**
+ * Cancel the current piloting action - called when user clicks Stop
+ */
+export declare function cancelPiloting(): void;
+/**
+ * Reset cancellation flag after it's been handled
+ */
+export declare function resetCancellation(): void;
+/**
+ * Check if cancellation was requested
+ */
+export declare function wasCancelled(): boolean;
+/** Whether a destructive action is awaiting user confirmation */
+export declare const needsConfirmation: import("@preact/signals-core").Signal<boolean>;
+/** Human-readable description of the action pending confirmation */
+export declare const confirmationLabel: import("@preact/signals-core").Signal<string | null>;
+/** Resolver function for the confirmation promise */
+export declare const confirmationResolver: import("@preact/signals-core").Signal<((confirmed: boolean) => void) | null>;
+/**
+ * Request user confirmation for a destructive action.
+ * Shows a confirmation UI and returns a Promise that resolves when the user responds.
+ *
+ * @param label - Description of the action (e.g., 'Agent wants to click "Delete Account"')
+ * @returns Promise<boolean> - true if user confirmed, false if denied
+ */
+export declare function requestConfirmation(label: string): Promise<boolean>;
+/**
+ * Resolve the pending confirmation request.
+ * Called by the UI when the user clicks Allow or Deny.
+ *
+ * @param confirmed - Whether the user confirmed the action
+ */
+export declare function resolveConfirmation(confirmed: boolean): void;

package/dist/store/suggestions.d.ts

@@ -2,12 +2,12 @@
  * Suggestions Store
  * Signal-based state for page-aware suggested questions
  *
- * The backend generates a pool of 15-20 diverse suggestions.
+ * The backend generates a small set of suggested questions.
  * This store sorts them client-side based on page relevance
  * for instant page-aware suggestions without additional LLM calls.
  */
 import type { SuggestedQuestion } from '../api/client';
-/** Base suggestion pool from backend (15-20 suggestions) */
+/** Base suggestion pool from backend */
 export declare const suggestionPool: import("@preact/signals-core").Signal<SuggestedQuestion[]>;
 /** Currently displayed suggestions (sorted by page relevance) */
 export declare const suggestions: import("@preact/signals-core").Signal<SuggestedQuestion[]>;

package/dist/types/dom-scanner.d.ts

@@ -20,6 +20,10 @@ export interface ScanOptions {
     minTextLength?: number;
     /** Maximum text length before truncation (default: 500) */
     maxTextLength?: number;
+    /** Maximum total output length in characters (default: 50000) */
+    maxTotalLength?: number;
+    /** Maximum label length for interactable elements (default: 100) */
+    maxLabelLength?: number;
     /** Include element positions/coordinates (default: false) */
     includePositions?: boolean;
 }

package/dist/utils/dom-scanner.d.ts

@@ -8,6 +8,22 @@ import { type CompactScanResult, type InteractionType, type ScanOptions } from "
  * Called before scanning to remove stale refs.
  */
 export declare function clearPillarRefs(): void;
+/**
+ * Check if an element or any of its ancestors is marked for redaction.
+ * Elements with `data-pillar-redact` or password inputs are redacted.
+ * Their text content is replaced with [REDACTED] in scan output.
+ */
+export declare function isRedacted(el: Element): boolean;
+/**
+ * Check if an element represents a destructive action.
+ * Used to gate interactions behind user confirmation.
+ *
+ * Returns true if:
+ * - The element has `data-pillar-destructive` attribute (explicit opt-in)
+ * - The element's label or text content contains destructive keywords
+ * - The element is a reset/submit button on a form with "delete" in its action URL
+ */
+export declare function isDestructiveElement(el: Element): boolean;
 /**
  * Check if an element is interactable
  */
@@ -16,12 +32,22 @@ export declare function isInteractable(el: Element): boolean;
  * Determine the interaction type for an element
  */
 export declare function getInteractionType(el: Element): InteractionType;
+/**
+ * Validate that a ref string matches the expected pillar ref format.
+ * Prevents CSS selector injection from malformed/malicious ref values.
+ *
+ * @param ref - Ref string to validate
+ * @returns true if the ref matches the expected format
+ */
+export declare function isValidPillarRef(ref: string): boolean;
 /**
  * Build full selector from short ref ID.
  * Converts "pr-abc" to '[data-pillar-ref="pr-abc"]'
+ * Throws if the ref format is invalid to prevent CSS selector injection.
  *
  * @param shortRef - Short ref ID (e.g., "pr-abc")
  * @returns Full CSS selector for querySelector
+ * @throws Error if the ref format is invalid
  */
 export declare function buildSelectorFromRef(shortRef: string): string;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pillar-ai/sdk",
-  "version": "0.1.14",
+  "version": "0.1.15",
   "description": "Pillar Embedded Help SDK - Add contextual help and AI chat to your application",
   "type": "module",
   "main": "./dist/pillar.esm.js",

package/src/actions/types.ts

@@ -182,6 +182,19 @@ export interface ActionDefinition<TData = Record<string, unknown>> {
    */
   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.
    *
@@ -216,6 +229,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>;
+  }>;
 }
 
 /**
@@ -248,6 +265,12 @@ 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;
 }
 
 /**
@@ -314,6 +337,16 @@ 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>;
+  }>;
 }
 
 /**