@pillar-ai/sdk 0.1.33 → 0.2.0

package/README.md

@@ -31,7 +31,7 @@ Pillar understands the intent, builds a multi-step plan, and executes it client-
 - **Multi-Step Plans** — Chain actions into workflows for complex tasks
 - **Context-Aware** — Knows current page, user state, and selected text
 - **Knowledge Sync** — Trained on your docs, Zendesk, Intercom, and more
-- **Custom Action Cards** — Render interactive UI for confirmations and data input
+- **Render Custom Components** — Render your own interactive UI in the chat
 - **Framework Bindings** — First-class support for React, Vue, and Svelte
 
 ## Why Pillar?
@@ -42,7 +42,7 @@ Pillar understands the intent, builds a multi-step plan, and executes it client-
 
 ## Documentation
 
-**[View Full Documentation](https://trypillar.com/docs)** | [Getting Started](https://trypillar.com/docs/get-started/quickstart) | [API Reference](https://trypillar.com/docs/reference/core)
+**[View Full Documentation](https://trypillar.com/docs)** | [Getting Started](https://trypillar.com/docs/get-started/quickstart) | [API Reference](https://trypillar.com/docs/reference)
 
 ## Installation
 
@@ -56,11 +56,9 @@ yarn add @pillar-ai/sdk
 
 ## Quick Start
 
-### 1. Get Your Product Key
+### 1. Get your agent slug
 
-> **⚠️ Beta Onboarding:** Cloud access is currently manual while we learn from early teams. Join the waitlist at [trypillar.com](https://trypillar.com), and we will reach out to onboard you.
->
-> By default, you'll get an engineer from Pillar to help with setup. If you prefer onboarding without engineering support, include that in your waitlist request and we will support that too.
+Sign up at [app.trypillar.com](https://app.trypillar.com) and grab your agent slug from the dashboard.
 
 ### 2. Initialize the SDK
 
@@ -69,7 +67,7 @@ import { Pillar } from "@pillar-ai/sdk";
 
 // Initialize and get the instance
 const pillar = await Pillar.init({
-  productKey: "your-product-key", // Provided during onboarding
+  agentSlug: "your-agent-slug", // Provided during onboarding
 });
 
 // Now you can use instance methods
@@ -95,7 +93,7 @@ Use `onTask` to handle actions when the AI executes them:
 
 ```javascript
 const pillar = await Pillar.init({
-  productKey: "your-product-key",
+  agentSlug: "your-agent-slug",
 });
 
 // Handle navigation
@@ -122,7 +120,7 @@ For production, define tools in code and sync them via the `pillar-sync` CLI dur
 
 ```javascript
 const pillar = await Pillar.init({
-  productKey: "your-product-key",
+  agentSlug: "your-agent-slug",
 
   panel: {
     position: "right", // 'left' | 'right'
@@ -144,29 +142,29 @@ const pillar = await Pillar.init({
 
 ## API Reference
 
-| Method | Description |
-|--------|-------------|
-| `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 |
+| Method                       | Description                              |
+| ---------------------------- | ---------------------------------------- |
+| `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).
+For complete API documentation, see the [API Reference](https://trypillar.com/docs/reference).
 
 ## Framework Integrations
 
 For idiomatic integration with your framework, use our framework-specific packages:
 
-| Framework | Package | Installation |
-|-----------|---------|--------------|
-| React | [@pillar-ai/react](https://github.com/pillarhq/sdk-react) | `npm install @pillar-ai/react` |
-| Vue | [@pillar-ai/vue](https://github.com/pillarhq/sdk-vue) | `npm install @pillar-ai/vue` |
-| Svelte | [@pillar-ai/svelte](https://github.com/pillarhq/sdk-svelte) | `npm install @pillar-ai/svelte` |
+| Framework | Package                                                     | Installation                    |
+| --------- | ----------------------------------------------------------- | ------------------------------- |
+| React     | [@pillar-ai/react](https://github.com/pillarhq/sdk-react)   | `npm install @pillar-ai/react`  |
+| Vue       | [@pillar-ai/vue](https://github.com/pillarhq/sdk-vue)       | `npm install @pillar-ai/vue`    |
+| Svelte    | [@pillar-ai/svelte](https://github.com/pillarhq/sdk-svelte) | `npm install @pillar-ai/svelte` |
 
 ## License
 

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

@@ -27,8 +27,6 @@ export interface ToolResult {
         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?: {
         conversation_id?: string;
@@ -285,8 +283,6 @@ export interface ConversationStatus {
     partial_response?: string;
     display_trace?: DisplayStep[];
     registered_tools?: Record<string, unknown>[];
-    /** @deprecated Use registered_tools instead */
-    registered_actions?: Record<string, unknown>[];
 }
 /**
  * Convert ToolData from MCP response to TaskButtonData for UI rendering.

package/dist/cli/sync.js

@@ -437,6 +437,9 @@ function buildManifestFromScan(tools, platform, version, gitSha, agentGuidance)
   return manifest;
 }
 async function main() {
+  console.log(
+    "[pillar-sync] Note: pillar-sync in @pillar-ai/sdk is deprecated. Use pillar-cli instead: npx pillar-cli sync"
+  );
   const args = parseArgs(process.argv.slice(2));
   if (args.help) {
     printUsage();

package/dist/components/Cards/ConfirmActionCard.d.ts

@@ -3,17 +3,28 @@
  *
  * Renders inline_ui type actions as inline cards in the chat.
  * If a custom card renderer is registered for the card_type, it's used.
- * Otherwise, a default confirmation card is rendered.
+ * Otherwise, a default preview card is rendered.
+ *
+ * When `needsConfirmation` is set, the default card includes Confirm / Cancel
+ * buttons that gate execution of the tool's `execute` handler.
  */
 import type { CardCallbacks } from '../../core/events';
 import type { TaskButtonData } from '../Panel/TaskButton';
 /**
- * Create the default confirmation card for inline_ui actions.
- * Used when no custom card renderer is registered.
+ * Create the default card for inline_ui actions.
+ * When callbacks include onConfirm/onCancel, confirm/cancel buttons are shown.
  */
 export declare function createDefaultConfirmCard(action: TaskButtonData, callbacks: CardCallbacks): HTMLDivElement;
+export interface ConfirmActionCardOptions {
+    needsConfirmation?: boolean;
+    onConfirm?: (data?: Record<string, unknown>) => void;
+    onCancel?: () => void;
+}
 /**
- * Create a confirmation card for a confirm_action type action.
+ * Create a card for an inline_ui type action.
  * Uses custom renderer if registered, otherwise uses default.
+ *
+ * When `options.needsConfirmation` is true, the card includes Confirm/Cancel
+ * buttons that call the provided `onConfirm`/`onCancel` callbacks.
  */
-export declare function createConfirmActionCard(action: TaskButtonData, onConfirm: (data?: Record<string, unknown>) => void, onCancel: () => void): HTMLDivElement;
+export declare function createConfirmActionCard(action: TaskButtonData, options?: ConfirmActionCardOptions): HTMLDivElement;

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

@@ -26,6 +26,8 @@ export interface TaskButtonData {
     autoRun?: boolean;
     /** If true, action completes without waiting for host confirmation */
     autoComplete?: boolean;
+    /** If true, show a confirmation card before executing */
+    needsConfirmation?: boolean;
 }
 interface TaskButtonProps {
     task: TaskButtonData;

package/dist/core/Pillar.d.ts

@@ -675,10 +675,8 @@ export declare class Pillar {
      *     <div class="invite-card">
      *       <h3>Invite Team Members</h3>
      *       ${data.emails.map(e => `<div>${e}</div>`).join('')}
-     *       <button id="confirm">Send Invites</button>
      *     </div>
      *   `;
-     *   container.querySelector('#confirm').onclick = callbacks.onConfirm;
      *   return () => container.innerHTML = ''; // cleanup
      * });
      */
@@ -696,6 +694,36 @@ export declare class Pillar {
      * @param cardType - The card type identifier
      */
     hasCardRenderer(cardType: string): boolean;
+    /**
+     * Get the position (messageIndex, segmentIndex) of the last card segment
+     * in the current message list. Returns null if there are no card segments.
+     */
+    getLatestCardPosition(): {
+        messageIndex: number;
+        segmentIndex: number;
+    } | null;
+    /**
+     * Check if a given message position is in the latest message.
+     * This becomes false as soon as any new message is added (including hidden
+     * messages from sendResult). Segment position within the same message is
+     * ignored — text segments after a card in the same assistant turn don't
+     * make the card "stale".
+     */
+    isPositionLatest(messageIndex: number, _segmentIndex: number): boolean;
+    /**
+     * Subscribe to message list changes (for reactive card context).
+     * Returns an unsubscribe function.
+     */
+    subscribeToMessages(callback: () => void): () => void;
+    /**
+     * Whether the chat is currently streaming a response.
+     */
+    get isChatLoading(): boolean;
+    /**
+     * Subscribe to chat loading-state changes (for reactive `isReady` in card context).
+     * Returns an unsubscribe function.
+     */
+    subscribeToLoadingState(callback: () => void): () => void;
     /**
      * Get the active workflow, if any.
      */
@@ -753,6 +781,20 @@ export declare class Pillar {
     sendToolResult(toolName: string, result: unknown, toolCallId?: string): Promise<void>;
     /** @deprecated Use sendToolResult instead */
     sendActionResult(actionName: string, result: unknown, toolCallId?: string): Promise<void>;
+    /**
+     * Send a tool result as a new chat message, triggering a fresh LLM turn.
+     *
+     * Unlike `sendToolResult` (which responds to a pending tool call via `action/result`),
+     * this method injects the data as a new user message so the LLM can reason about it
+     * and decide what to do next (e.g., call another tool like `display_checkout`).
+     *
+     * Use this for results from already-rendered inline_ui cards where the original
+     * tool call has already completed and there is no pending `tool_call_id`.
+     *
+     * @param toolName - The name of the tool that generated the result
+     * @param result - Structured data to send to the LLM
+     */
+    sendToolResultAsMessage(toolName: string, result: Record<string, unknown>): void;
     /**
      * Execute a query tool and send the result back to the agent.
      *

package/dist/core/config.d.ts

@@ -332,13 +332,18 @@ export interface ZIndexConfig {
 }
 export interface PillarConfig {
     /**
-     * Your product key from the Pillar app.
+     * Your agent slug from the Pillar dashboard.
+     * This is the primary identifier for your copilot agent.
      * Get it at app.trypillar.com
      */
+    agentSlug?: string;
+    /**
+     * @deprecated Use `agentSlug` instead. Will be removed in a future version.
+     */
     productKey?: string;
     /**
      * Display name for the assistant shown in the sidebar tab.
-     * @default 'Assistant'
+     * @default 'Copilot'
      */
     assistantDisplayName?: string;
     /**
@@ -500,6 +505,7 @@ export interface ResolvedSuggestionsConfig {
 }
 export interface ResolvedConfig {
     productKey: string;
+    agentSlug?: string;
     apiBaseUrl: string;
     /** Display name for the assistant shown in the sidebar tab */
     assistantDisplayName: string;

package/dist/core/events.d.ts

@@ -27,17 +27,32 @@ export interface TaskExecutePayload {
  * Callbacks provided to custom card renderers.
  */
 export interface CardCallbacks {
-    /**
-     * Called when user confirms the action. Pass modified data if needed.
-     * WARNING: Data passed here flows through the SDK pipeline (telemetry,
-     * agent context, logs). Never include secrets, tokens, or PII.
-     */
-    onConfirm: (modifiedData?: Record<string, unknown>) => void;
-    /** Called when user cancels the action */
-    onCancel: () => void;
+    /** Confirm the action — triggers the tool's `execute` handler. Only present when the tool has `needsConfirmation`. */
+    onConfirm?: (modifiedData?: Record<string, unknown>) => void;
+    /** Cancel the action — dismisses the card. Only present when the tool has `needsConfirmation`. */
+    onCancel?: () => void;
+    /** Send a result back to the AI agent so it can continue reasoning. */
+    sendResult?: (result: Record<string, unknown>) => Promise<void>;
     /** Called to report card state changes (for analytics/confirmation) */
     onStateChange?: (state: "loading" | "success" | "error", message?: string) => void;
 }
+/**
+ * Context about a card's position in the chat.
+ * Passed to card renderers so they can adapt their UI
+ * (e.g., collapse when no longer the latest card).
+ */
+export interface ToolCardContext {
+    /** True when this is the last card segment across all messages. */
+    isLatest: boolean;
+    /** True when no message is being streamed — safe to call sendResult. */
+    isReady: boolean;
+    /** Zero-based index of the message containing this card. */
+    messageIndex: number;
+    /** Zero-based index of this segment within its message's segments array. */
+    segmentIndex: number;
+    /** The tool name / card type. */
+    toolName: string;
+}
 /**
  * Card field schema definition for declarative card configuration.
  */
@@ -88,8 +103,6 @@ export interface CardRegistrationOptions {
     /** Theme/styling options */
     theme?: {
         variant?: "default" | "compact" | "wide";
-        confirmLabel?: string;
-        cancelLabel?: string;
     };
 }
 /**
@@ -102,14 +115,14 @@ export interface RegisteredCard {
 }
 /**
  * Card renderer function signature.
- * Customers register these to render custom confirmation cards.
+ * Customers register these to render custom inline UI cards.
  *
  * @param container - DOM element to render the card into
  * @param data - Action data including extracted values from AI
- * @param callbacks - Callbacks for confirm/cancel actions
+ * @param callbacks - Callbacks for state reporting
  * @returns Optional cleanup function called when card is unmounted
  */
-export type CardRenderer = (container: HTMLElement, data: Record<string, unknown>, callbacks: CardCallbacks) => (() => void) | void;
+export type CardRenderer = (container: HTMLElement, data: Record<string, unknown>, callbacks: CardCallbacks, context?: ToolCardContext) => (() => void) | void;
 export interface PillarEvents {
     /** SDK is initialized and ready. */
     ready: void;

package/dist/index.d.ts

@@ -6,7 +6,7 @@
  * <script src="https://cdn.trypillar.com/sdk/pillar.min.js"></script>
  * <script>
  *   Pillar.init({
- *     productKey: 'your-product-key',
+ *     agentSlug: 'your-agent-slug',
  *   });
  * </script>
  *
@@ -15,16 +15,18 @@
  * import { Pillar } from '@pillar-ai/sdk';
  *
  * await Pillar.init({
- *   productKey: 'your-product-key',
+ *   agentSlug: 'your-agent-slug',
  * });
  */
-export { EventEmitter, type CardCallbacks, type CardRenderer, type PillarEvents, type TaskExecutePayload, } from "./core/events";
-export { Pillar, type ChatContext, type PillarState, type ToolInfo } from "./core/Pillar";
+export { EventEmitter, type CardCallbacks, type CardRenderer, type ToolCardContext, type PillarEvents, type TaskExecutePayload, } from "./core/events";
+export { Pillar, getApiClient, type ChatContext, type PillarState, type ToolInfo } from "./core/Pillar";
+export { getPillarInstance } from "./core/instance";
 export { DEFAULT_SIDEBAR_TABS, type DOMScanningConfig, type EdgeTriggerConfig, type InteractionHighlightConfig, type MobileTriggerConfig, type MobileTriggerIcon, type MobileTriggerPosition, type MobileTriggerSize, type PanelConfig, type PanelMode, type PanelPosition, type PillarConfig, type ResolvedConfig, type ResolvedDOMScanningConfig, type ResolvedInteractionHighlightConfig, type ResolvedMobileTriggerConfig, type ResolvedPanelConfig, type ResolvedSuggestionsConfig, type ResolvedThemeConfig, type SidebarTabConfig, type SuggestionsConfig, type TextSelectionConfig, type ThemeColors, type ThemeConfig, type ThemeMode, type UrlParamsConfig, type ZIndexConfig, } from "./core/config";
 export { type AssistantContext, type Context, type Suggestion, type UserProfile, } from "./core/context";
-export { clearRegistry, getToolCount, getToolDefinition, getToolNames, getClientInfo, getHandler, getManifest, hasTool, setClientInfo, type ToolDataSchema, type ToolDataSchemaProperty, type ToolDataType, type ToolDefinition, type ToolDefinitions, type ToolManifest, type ToolManifestEntry, type ToolNames, type ToolType, type ToolTypeDataMap, type ToolExecuteResult, type ToolSchema, type ClientInfo, type CopyTextData, type ExternalLinkData, type InlineUIData, type NavigateToolData, type TriggerToolData, type QueryToolData, type Platform, type SyncToolDefinition, type SyncToolDefinitions, type TypedOnTask, type TypedPillarMethods, type TypedTaskHandler, getActionCount, getActionDefinition, getActionNames, hasAction, type ActionDataSchema, type ActionDataSchemaProperty, type ActionDataType, type ActionDefinition, type ActionDefinitions, type ActionManifest, type ActionManifestEntry, type ActionNames, type ActionType, type ActionTypeDataMap, type ActionResult, type ActionSchema, type NavigateActionData, type TriggerActionData, type QueryActionData, type SyncActionDefinition, type SyncActionDefinitions, } from "./tools";
+export { clearRegistry, getToolCount, getToolDefinition, getToolNames, getClientInfo, getHandler, getManifest, hasTool, setClientInfo, type ToolDataSchema, type ToolDataSchemaProperty, type ToolDataType, type ToolDefinition, type ToolDefinitions, type ToolManifest, type ToolManifestEntry, type ToolNames, type ToolType, type ToolTypeDataMap, type ToolExecuteResult, type ToolSchemaBase, type InlineUIToolSchema, type ExecutableToolSchema, type ToolSchema, type ClientInfo, type CopyTextData, type ExternalLinkData, type InlineUIData, type NavigateToolData, type TriggerToolData, type QueryToolData, type Platform, type SyncToolDefinition, type SyncToolDefinitions, type TypedOnTask, type TypedPillarMethods, type TypedTaskHandler, getActionCount, getActionDefinition, getActionNames, hasAction, type ActionDataSchema, type ActionDataSchemaProperty, type ActionDataType, type ActionDefinition, type ActionDefinitions, type ActionManifest, type ActionManifestEntry, type ActionNames, type ActionType, type ActionTypeDataMap, type ActionResult, type ActionSchema, type NavigateActionData, type TriggerActionData, type QueryActionData, type SyncActionDefinition, type SyncActionDefinitions, } from "./tools";
 export { APIClient, type ArticleSummary, type ChatMessage, type ChatResponse, type ProgressEvent, } from "./api/client";
 export { type ToolRequest, type ToolData, type ChatImage, type ImageUploadResponse, type TokenUsage, toolToTaskButton, type ActionRequest, type ActionData, actionToTaskButton, } from "./api/mcp-client";
+export { normalizeToolResult } from "./utils/normalize-tool-result";
 export { DEFAULT_SCAN_OPTIONS, INTERACTABLE_ROLES, INTERACTABLE_TAGS, SKIP_TAGS, type CompactScanResult, type InteractionType, type ScanOptions, } from "./types/dom-scanner";
 export { buildSelectorFromRef, clearPillarRefs, isDestructiveElement, isInteractable, isRedacted, isValidPillarRef, scanPageDirect, } from "./utils/dom-scanner";
 export { generateContextId, getContextDisplayLabel, isDOMSnapshotContext, isHighlightedTextContext, type DOMSnapshotContext, type GenericContext, type HighlightedTextContext, type ProductContext, type UserContextItem, type UserProfileContext, } from "./types/user-context";