@pillar-ai/sdk 0.1.19 → 0.1.22

package/dist/content/extensions/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * TipTap Extensions for SDK content rendering
+ */
+export { CalloutNode, type CalloutType } from './CalloutNode';
+export { AccordionNode } from './AccordionNode';

package/dist/content/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Content rendering utilities for the SDK
+ */
+export { renderArticleContent, renderTipTapContent, isJSONContent, } from './renderer';
+export type { CalloutType } from './extensions';

package/dist/content/renderer.d.ts

@@ -0,0 +1,24 @@
+/**
+ * TipTap Content Renderer
+ * Converts TipTap JSON content to HTML for display in the SDK panel
+ */
+import type { JSONContent } from '@tiptap/core';
+/**
+ * Check if content is TipTap JSON format (has a 'type' property)
+ */
+export declare function isJSONContent(content: unknown): content is JSONContent;
+/**
+ * Render TipTap JSON content to HTML
+ *
+ * @param content - TipTap JSON content object
+ * @returns HTML string
+ */
+export declare function renderTipTapContent(content: JSONContent): string;
+/**
+ * Render article content to HTML
+ * Handles both TipTap JSON and legacy HTML string content
+ *
+ * @param content - TipTap JSON content or HTML string
+ * @returns HTML string
+ */
+export declare function renderArticleContent(content: JSONContent | string | null | undefined): string;

package/dist/core/Pillar.d.ts

@@ -2,6 +2,7 @@
  * Main Pillar SDK Class
  * Entry point for all SDK functionality
  */
+import { type ToolSchema } from "../tools";
 import { type PillarConfig, type ResolvedConfig, type ThemeConfig } from "./config";
 import { type Context, type Suggestion, type UserProfile } from "./context";
 import { type CardRenderer, type PillarEvents, type TaskExecutePayload } from "./events";
@@ -41,7 +42,10 @@ export declare class Pillar {
     private _getStoredExternalUserId;
     private _taskHandlers;
     private _anyTaskHandler;
-    _registeredActions: Map<string, Record<string, unknown>>;
+    _registeredTools: Map<string, Record<string, unknown>>;
+    /** @deprecated Use _registeredTools instead */
+    get _registeredActions(): Map<string, Record<string, unknown>>;
+    private _definedTools;
     private _cardRenderers;
     private _debugPanelContainer;
     private _routeObserver;
@@ -437,47 +441,91 @@ export declare class Pillar {
      */
     onTask(taskName: string, handler: (data: Record<string, unknown>) => void): () => void;
     /**
-     * Register an action definition at runtime.
+     * Define a tool with co-located metadata and handler.
      *
-     * This is primarily for demos and development. In production, actions
+     * This is the recommended way to register tools. The metadata
+     * (name, description, inputSchema) is discoverable by the CLI scanner
+     * (`npx pillar-sync --scan ./src`) and the handler runs client-side.
+     *
+     * If `execute` returns a value, it is automatically sent back to the
+     * agent — no explicit `returns: true` flag needed.
+     *
+     * @param schema - Tool schema with metadata and execute handler
+     * @returns Unsubscribe function that removes the tool
+     *
+     * @example
+     * const unsub = pillar.defineTool({
+     *   name: 'add_to_cart',
+     *   description: 'Add a product to the shopping cart',
+     *   inputSchema: {
+     *     type: 'object',
+     *     properties: {
+     *       productId: { type: 'string' },
+     *       quantity: { type: 'number' },
+     *     },
+     *     required: ['productId', 'quantity'],
+     *   },
+     *   execute: async ({ productId, quantity }) => {
+     *     await cartApi.add(productId, quantity);
+     *     return { content: [{ type: 'text', text: 'Added to cart' }] };
+     *   },
+     * });
+     *
+     * // Later: unsub() to remove the tool
+     */
+    defineTool<TInput = Record<string, unknown>>(schema: ToolSchema<TInput>): () => void;
+    /** @deprecated Use defineTool instead */
+    defineAction<TInput = Record<string, unknown>>(schema: ToolSchema<TInput>): () => void;
+    /**
+     * Register a tool definition at runtime.
+     *
+     * @deprecated Use `defineTool()` instead, which co-locates metadata and handler.
+     *
+     * This is primarily for demos and development. In production, tools
      * should be synced via the `pillar-sync` CLI during CI/CD.
      *
-     * The action definition is stored locally and can be used by `onTask`
-     * handlers. For actions with `returnsData: true`, the handler's return
+     * The tool definition is stored locally and can be used by `onTask`
+     * handlers. For tools with `returnsData: true`, the handler's return
      * value is sent back to the agent.
      *
-     * @param action - Action definition with name and properties
+     * @param tool - Tool definition with name and properties
      *
      * @example
-     * pillar.registerAction({
+     * pillar.registerTool({
      *   name: 'list_datasets',
      *   description: 'List available datasets',
      *   type: 'query',
      *   returnsData: true,
      * });
      */
+    registerTool(tool: {
+        name: string;
+    } & Record<string, unknown>): void;
+    /** @deprecated Use registerTool instead */
     registerAction(action: {
         name: string;
     } & Record<string, unknown>): void;
     /**
-     * Get a registered action definition by name.
+     * Get a registered tool definition by name.
      *
-     * @param name - Action name
-     * @returns Action definition or undefined
+     * @param name - Tool name
+     * @returns Tool definition or undefined
      */
+    getRegisteredTool(name: string): Record<string, unknown> | undefined;
+    /** @deprecated Use getRegisteredTool instead */
     getRegisteredAction(name: string): Record<string, unknown> | undefined;
     /**
-     * Get handler for an action, checking all registration systems.
+     * Get handler for a tool, checking all registration systems.
      *
      * Lookup order:
-     * 1. Code-first action registry (synced via pillar-sync CLI) - handler in definition
+     * 1. Code-first tool registry (synced via pillar-sync CLI) - handler in definition
      * 2. Task handlers (registered via onTask at runtime)
      *
      * This is the recommended pattern:
-     * - Action definitions synced to server via CLI (so AI knows what's possible)
+     * - Tool definitions synced to server via CLI (so AI knows what's possible)
      * - Handlers registered at runtime via onTask (client-side execution)
      *
-     * @param actionName - Action name to look up
+     * @param toolName - Tool name to look up
      * @returns Handler function or undefined if not found
      *
      * @example
@@ -486,7 +534,7 @@ export declare class Pillar {
      *   const result = await handler({ limit: 10 });
      * }
      */
-    getHandler(actionName: string): ((data: Record<string, unknown>) => unknown) | undefined;
+    getHandler(toolName: string): ((data: Record<string, unknown>) => unknown) | undefined;
     /**
      * Register a catch-all handler for any task.
      * Useful for logging, analytics, or handling unknown tasks.
@@ -524,20 +572,22 @@ export declare class Pillar {
      */
     completeTask(taskName: string, success?: boolean, data?: Record<string, unknown>): void;
     /**
-     * Signal that an action has completed.
+     * Signal that a tool has completed.
      *
-     * For simple actions, this emits the completion event.
-     * For wizard actions (modals, multi-step flows), call this when the user
+     * For simple tools, this emits the completion event.
+     * For wizard tools (modals, multi-step flows), call this when the user
      * finishes the flow.
      *
-     * @param actionName - The action identifier
-     * @param success - Whether the action completed successfully (default: true)
+     * @param toolName - The tool identifier
+     * @param success - Whether the tool completed successfully (default: true)
      * @param data - Optional result data
      *
      * @example
      * // In your wizard completion handler:
-     * pillar.completeAction('add_source', true, { sourceId: source.id });
+     * pillar.completeTool('add_source', true, { sourceId: source.id });
      */
+    completeTool(toolName: string, success?: boolean, data?: Record<string, unknown>): Promise<void>;
+    /** @deprecated Use completeTool instead */
     completeAction(actionName: string, success?: boolean, data?: Record<string, unknown>): Promise<void>;
     /**
      * Confirm task execution result.
@@ -651,29 +701,36 @@ export declare class Pillar {
      */
     private _executeWorkflowStep;
     /**
-     * Send action result back to the agent.
+     * Send tool result back to the agent.
      *
-     * Called automatically for actions with `returns: true` after their
+     * Called automatically for tools with `returns: true` after their
      * handler completes. The result is sent to the agent for further reasoning.
      *
-     * @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
      * @internal
      */
+    sendToolResult(toolName: string, result: unknown, toolCallId?: string): Promise<void>;
+    /** @deprecated Use sendToolResult instead */
     sendActionResult(actionName: string, result: unknown, toolCallId?: string): Promise<void>;
     /**
-     * Execute a query action and send the result back to the agent.
+     * Execute a query tool and send the result back to the agent.
      *
      * This is called when the agent sends a `query_request` event.
-     * Query actions are expected to return data that the agent can use
+     * Query tools are expected to return data that the agent can use
      * for further reasoning.
      *
-     * @param actionName - The name of the action to execute
-     * @param args - Arguments for the action
+     * @param toolName - The name of the tool to execute
+     * @param args - Arguments for the tool
      * @param schema - Optional schema for parameter validation
      */
+    executeQueryTool(toolName: string, args?: Record<string, unknown>, schema?: {
+        properties?: Record<string, unknown>;
+        required?: string[];
+    }): Promise<void>;
+    /** @deprecated Use executeQueryTool instead */
     executeQueryAction(actionName: string, args?: Record<string, unknown>, schema?: {
         properties?: Record<string, unknown>;
         required?: string[];

package/dist/core/config.d.ts

@@ -1,7 +1,7 @@
 /**
  * Pillar SDK Configuration Types
  */
-import type { Platform } from '../actions/types';
+import type { Platform } from '../tools/types';
 /** Which side of the screen the panel appears on. */
 export type PanelPosition = 'left' | 'right';
 /** How the panel interacts with page content: 'overlay' floats over it, 'push' shifts it aside. */

package/dist/core/events.d.ts

@@ -164,7 +164,13 @@ export interface PillarEvents {
     };
     /** User logged out. */
     "user:logout": Record<string, never>;
-    /** Query action returned a result to the agent. */
+    /** Query tool returned a result to the agent. */
+    "tool:result": {
+        toolName: string;
+        result: unknown;
+        toolCallId?: string;
+    };
+    /** @deprecated Use tool:result instead */
     "action:result": {
         actionName: string;
         result: unknown;

package/dist/index.d.ts

@@ -22,9 +22,9 @@ export { EventEmitter, type CardCallbacks, type CardRenderer, type PillarEvents,
 export { Pillar, type ChatContext, type PillarState } from "./core/Pillar";
 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, } from "./core/config";
 export { type AssistantContext, type Context, type Suggestion, type UserProfile, } from "./core/context";
-export { clearRegistry, getActionCount, getActionDefinition, getActionNames, getClientInfo, getHandler, getManifest, hasAction, setClientInfo, type ActionDataSchema, type ActionDataType, type ActionDefinition, type ActionDefinitions, type ActionManifest, type ActionManifestEntry, type ActionNames, type ActionType, type ActionTypeDataMap, type ClientInfo, type CopyTextData, type ExternalLinkData, type InlineUIData, type NavigateActionData, type Platform, type SyncActionDefinition, type SyncActionDefinitions, type TriggerActionData, type TypedOnTask, type TypedPillarMethods, type TypedTaskHandler, } from "./actions";
+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 { APIClient, type ArticleSummary, type ChatMessage, type ChatResponse, type ProgressEvent, } from "./api/client";
-export { type ActionRequest, type ChatImage, type ImageUploadResponse, type TokenUsage, } from "./api/mcp-client";
+export { type ToolRequest, type ToolData, type ChatImage, type ImageUploadResponse, type TokenUsage, toolToTaskButton, type ActionRequest, type ActionData, actionToTaskButton, } from "./api/mcp-client";
 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";