@pillar-ai/sdk 0.1.34 → 0.2.0

package/dist/actions/types.d.ts

@@ -1,530 +0,0 @@
-/**
- * Action Types - Type definitions for code-first action definitions.
- *
- * These types enable developers to define actions in their application code
- * rather than in the admin UI, with full TypeScript support.
- *
- * @example
- * ```ts
- * // lib/pillar/actions/index.ts
- * import type { SyncActionDefinitions } from '@pillar-ai/sdk';
- *
- * export const actions = {
- *   open_settings: {
- *     description: 'Navigate to the settings page',
- *     type: 'navigate' as const,
- *     path: '/settings',
- *     autoRun: true,
- *   },
- * } as const satisfies SyncActionDefinitions;
- *
- * export default actions;
- *
- * // Sync via CI/CD: npx pillar-sync --actions ./lib/pillar/actions/index.ts
- * // Register handlers at runtime: pillar.onTask('open_settings', () => router.push('/settings'));
- * ```
- */
-/**
- * Supported action types.
- *
- * - navigate: Navigate to a page within the app
- * - 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' | 'query' | 'copy_text' | 'external_link' | 'start_tutorial' | 'inline_ui';
-/**
- * Supported platforms for action deployments.
- */
-export type Platform = 'web' | 'ios' | 'android' | 'desktop';
-/**
- * Schema property definition for a single field.
- * Supports nested objects and arrays with items.
- */
-export interface ActionDataSchemaProperty {
-    type: 'string' | 'number' | 'boolean' | 'array' | 'object';
-    description?: string;
-    enum?: string[];
-    default?: unknown;
-    /** Items schema for array types */
-    items?: ActionDataSchemaProperty;
-    /** Nested properties for object types */
-    properties?: Record<string, ActionDataSchemaProperty>;
-    /** Required fields for nested object types */
-    required?: string[];
-}
-/**
- * JSON Schema definition for action data.
- *
- * When provided, the AI will extract data from the user's query
- * and populate the action's data field before execution.
- */
-export interface ActionDataSchema {
-    type: 'object';
-    properties: Record<string, ActionDataSchemaProperty>;
-    required?: string[];
-}
-/**
- * Definition for a single action.
- *
- * Actions are defined in code and synced to the server during CI/CD.
- * The server stores the metadata, and the SDK executes the handler locally.
- *
- * @template TData - Type for the data passed to the handler
- */
-export interface ActionDefinition<TData = Record<string, unknown>> {
-    /**
-     * Human-readable description for AI matching.
-     *
-     * The AI uses semantic similarity to match user queries to this description.
-     * Be specific about when this action should be suggested.
-     *
-     * @example "Navigate to the billing page. Suggest when user asks about payments, invoices, or subscription."
-     */
-    description: string;
-    /**
-     * Example user queries that should trigger this action.
-     *
-     * Provide 3-5 natural phrasings users might say:
-     * - Imperative: "open settings", "go to billing"
-     * - Questions: "where can I change my password?"
-     * - Informal: "settings", "show analytics"
-     *
-     * These are embedded and used for semantic matching alongside the description.
-     */
-    examples?: string[];
-    /**
-     * Type of action - determines how the SDK handles it.
-     */
-    type: ActionType;
-    /**
-     * Path for navigate actions.
-     *
-     * Can include template variables like `/users/{userId}`.
-     */
-    path?: string;
-    /**
-     * External URL for external_link actions.
-     */
-    externalUrl?: string;
-    /**
-     * JSON Schema for data extraction from user query.
-     *
-     * When provided, the AI will attempt to extract structured data
-     * from the conversation before executing the action.
-     */
-    dataSchema?: ActionDataSchema;
-    /**
-     * Default data to pass to the handler.
-     */
-    defaultData?: TData;
-    /**
-     * Context required for this action to be available.
-     *
-     * @example { loggedIn: true, plan: 'pro' }
-     */
-    requiredContext?: Record<string, unknown>;
-    /**
-     * Whether to auto-run this action without user confirmation.
-     *
-     * Only the highest-scoring action can auto-run.
-     * Use for simple navigations where user intent is clear.
-     *
-     * @default false
-     */
-    autoRun?: boolean;
-    /**
-     * Whether the action completes immediately after execution.
-     *
-     * If false, the SDK waits for host app confirmation.
-     * Use true for simple navigations and clipboard operations.
-     *
-     * @default false
-     */
-    autoComplete?: boolean;
-    /**
-     * Whether this action returns data for the agent.
-     *
-     * If true, the handler's return value is sent back to the agent
-     * for further reasoning. Use for query/lookup actions that inform
-     * the agent's next decision.
-     *
-     * @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.
-     *
-     * This runs in the client - the server only stores metadata.
-     * If `returns: true`, the return value is sent to the agent.
-     */
-    handler: (data: TData) => void | unknown | Promise<void | unknown>;
-}
-/**
- * Map of action name to definition.
- *
- * Action names should be snake_case identifiers.
- */
-export type ActionDefinitions = Record<string, ActionDefinition<unknown>>;
-/**
- * Metadata for a single action in the manifest (no handler).
- *
- * This is what gets synced to the server.
- */
-export interface ActionManifestEntry {
-    name: string;
-    description: string;
-    examples?: string[];
-    type: ActionType;
-    path?: string;
-    external_url?: string;
-    auto_run?: boolean;
-    auto_complete?: boolean;
-    returns_data?: boolean;
-    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.
- *
- * Contains all action metadata without handlers.
- */
-export interface ActionManifest {
-    /**
-     * Platform this manifest is for.
-     */
-    platform: Platform;
-    /**
-     * Version of the client app (semver or git SHA).
-     */
-    version: string;
-    /**
-     * Git commit SHA for traceability.
-     */
-    gitSha?: string;
-    /**
-     * When this manifest was generated.
-     */
-    generatedAt: string;
-    /**
-     * 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.
- */
-export interface ClientInfo {
-    platform: Platform;
-    version: string;
-}
-/**
- * Action definition for syncing (without handler).
- *
- * Use this type when defining actions for CI/CD sync.
- * Handlers are registered separately at runtime via pillar.onTask().
- *
- * @example
- * ```ts
- * import type { SyncActionDefinitions } from '@pillar-ai/sdk';
- *
- * export const actions: SyncActionDefinitions = {
- *   open_settings: {
- *     description: 'Navigate to settings page',
- *     type: 'navigate',
- *     path: '/settings',
- *     autoRun: true,
- *   },
- * };
- * ```
- */
-export interface SyncActionDefinition<TData = Record<string, unknown>> {
-    /** Human-readable description for AI matching */
-    description: string;
-    /** Example user queries that should trigger this action */
-    examples?: string[];
-    /** Type of action */
-    type: ActionType;
-    /** Path for navigate actions */
-    path?: string;
-    /** External URL for external_link actions */
-    externalUrl?: string;
-    /** JSON Schema for data extraction from user query */
-    dataSchema?: ActionDataSchema;
-    /** Default data to pass to the handler */
-    defaultData?: TData;
-    /** Context required for this action to be available */
-    requiredContext?: Record<string, unknown>;
-    /** Whether to auto-run this action without user confirmation */
-    autoRun?: boolean;
-    /** Whether the action completes immediately after execution */
-    autoComplete?: boolean;
-    /**
-     * Whether this action returns data for the agent.
-     * 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).
- *
- * Use this type for your actions file that gets synced via CI/CD.
- */
-export type SyncActionDefinitions = Record<string, SyncActionDefinition<unknown>>;
-/**
- * Base data types for each action type.
- * These are automatically inferred from the action's `type` field.
- */
-export interface NavigateActionData {
-    /** CSS selector to highlight after navigation */
-    highlight_selector?: string;
-    /** Path that was navigated to (injected by SDK) */
-    path?: string;
-}
-export interface TriggerActionData {
-    /** The action being triggered */
-    action?: string;
-    /** Additional action parameters */
-    [key: string]: unknown;
-}
-export interface InlineUIData {
-    /** Card type for rendering */
-    card_type: string;
-    /** Additional card data */
-    [key: string]: unknown;
-}
-export interface ExternalLinkData {
-    /** The URL being opened */
-    url?: string;
-}
-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.
- */
-export interface ActionTypeDataMap {
-    navigate: NavigateActionData;
-    trigger_action: TriggerActionData;
-    query: QueryActionData;
-    inline_ui: InlineUIData;
-    external_link: ExternalLinkData;
-    copy_text: CopyTextData;
-    open_modal: Record<string, unknown>;
-    fill_form: Record<string, unknown>;
-    start_tutorial: Record<string, unknown>;
-}
-/**
- * Extract the data type for a specific action from an ActionDefinitions map.
- *
- * Type inference priority:
- * 1. If `defaultData` is defined, use that type (for custom fields)
- * 2. Otherwise, infer from the action's `type` field using ActionTypeDataMap
- * 3. Fall back to Record<string, unknown>
- *
- * @example
- * ```ts
- * const actions = {
- *   // Inferred from type: "navigate" → NavigateActionData
- *   open_settings: {
- *     description: '...',
- *     type: 'navigate',
- *     path: '/settings',
- *   },
- *   // Custom data via defaultData
- *   add_source: {
- *     description: '...',
- *     type: 'navigate',
- *     defaultData: { type: '', url: '', name: '' },
- *   },
- * } as const satisfies SyncActionDefinitions;
- * ```
- */
-export type ActionDataType<TActions extends SyncActionDefinitions | ActionDefinitions, TName extends keyof TActions> = TActions[TName] extends {
-    defaultData: infer D;
-} ? D extends Record<string, unknown> ? D : Record<string, unknown> : TActions[TName] extends {
-    type: infer T;
-} ? T extends keyof ActionTypeDataMap ? ActionTypeDataMap[T] : Record<string, unknown> : Record<string, unknown>;
-/**
- * Extract all action names from an ActionDefinitions map.
- *
- * @example
- * ```ts
- * const actions = { open_settings: {...}, add_source: {...} };
- * type Names = ActionNames<typeof actions>; // 'open_settings' | 'add_source'
- * ```
- */
-export type ActionNames<T extends SyncActionDefinitions | ActionDefinitions> = Extract<keyof T, string>;
-/**
- * Typed task handler function.
- *
- * @template TData - The data type for this action
- */
-export type TypedTaskHandler<TData = Record<string, unknown>> = (data: TData) => void | Promise<void>;
-/**
- * Type-safe onTask method signature.
- *
- * When actions are provided to PillarProvider, this type enables
- * TypeScript to infer the correct data type for each action handler.
- *
- * @template TActions - The action definitions map
- */
-export interface TypedOnTask<TActions extends SyncActionDefinitions | ActionDefinitions> {
-    <TName extends ActionNames<TActions>>(taskName: TName, handler: TypedTaskHandler<ActionDataType<TActions, TName>>): () => void;
-    (taskName: string, handler: TypedTaskHandler): () => void;
-}
-/**
- * Extended Pillar interface with type-safe onTask.
- *
- * Use this when you want strongly typed task handlers based on
- * your action definitions.
- *
- * @template TActions - The action definitions map
- *
- * @example
- * ```ts
- * import type { TypedPillar } from '@pillar-ai/sdk';
- * import type { actions } from './actions';
- *
- * const pillar = usePillar<typeof actions>();
- *
- * // TypeScript knows `data` has { type, url, name }
- * pillar.onTask('add_source', (data) => {
- *   console.log(data.url);
- * });
- * ```
- */
-export interface TypedPillarMethods<TActions extends SyncActionDefinitions | ActionDefinitions> {
-    onTask: TypedOnTask<TActions>;
-}
-/**
- * Result returned from an action's execute function.
- *
- * Follows the MCP tool result format. Plain objects are also accepted
- * by the SDK and normalized to this shape automatically.
- */
-export interface ActionResult {
-    content: Array<{
-        type: 'text';
-        text: string;
-    } | {
-        type: 'image';
-        data: string;
-        mimeType: string;
-    }>;
-    isError?: boolean;
-}
-/**
- * Unified action definition that co-locates metadata and handler.
- *
- * Use with `pillar.defineAction()` or the `usePillarAction()` React hook.
- * The CLI scanner (`npx pillar-sync --scan ./src`) discovers these
- * definitions automatically — no barrel file needed.
- *
- * @template TInput - Type of the input object passed to `execute`
- *
- * @example
- * ```ts
- * pillar.defineAction({
- *   name: 'add_to_cart',
- *   description: 'Add a product to the shopping cart',
- *   inputSchema: {
- *     type: 'object',
- *     properties: {
- *       productId: { type: 'string', description: 'Product ID' },
- *       quantity: { type: 'number', description: 'Quantity to add' },
- *     },
- *     required: ['productId', 'quantity'],
- *   },
- *   execute: async ({ productId, quantity }) => {
- *     await cartApi.add(productId, quantity);
- *     return { content: [{ type: 'text', text: 'Added to cart' }] };
- *   },
- * });
- * ```
- */
-export interface ActionSchema<TInput = Record<string, unknown>> {
-    /** Unique action name (e.g., 'add_to_cart') */
-    name: string;
-    /** Human-readable description for AI matching */
-    description: string;
-    /**
-     * Type of action - determines how the SDK handles it and organizes it in the UI.
-     */
-    type?: ActionType;
-    /**
-     * JSON Schema describing the input parameters.
-     * The AI extracts structured data from the conversation to populate these.
-     */
-    inputSchema?: {
-        type: 'object';
-        properties: Record<string, unknown>;
-        required?: string[];
-    };
-    /**
-     * Example user queries that should trigger this action.
-     * Used for semantic matching alongside the description.
-     */
-    examples?: string[];
-    /**
-     * Whether to auto-execute without user confirmation.
-     * @default false
-     */
-    autoRun?: boolean;
-    /**
-     * Whether the action completes immediately after execution.
-     * @default true
-     */
-    autoComplete?: boolean;
-    /**
-     * Handler function executed when the AI invokes this action.
-     *
-     * Can return:
-     * - An `ActionResult` with MCP-style content blocks
-     * - A plain object (SDK normalizes it for the agent)
-     * - `void` if the action has no return value
-     */
-    execute: (input: TInput) => Promise<ActionResult | unknown | void> | ActionResult | unknown | void;
-}

package/dist/api/ag-ui-adapter.d.ts

@@ -1,76 +0,0 @@
-/**
- * AG-UI Client Adapter for Pillar SDK
- *
- * Bridges the new AGUIClient to existing chat store patterns.
- * Allows gradual migration without changing all components at once.
- *
- * Copyright (C) 2025 Pillar Team
- */
-import type { ResolvedConfig } from '../core/config';
-import type { ExecutionPlan } from '../core/plan';
-import type { TaskButtonData } from '../components/Panel/TaskButton';
-import type { UserContextItem } from '../types/user-context';
-import type { ArticleSummary, ChatMessage, ChatResponse, ProgressEvent } from './client';
-import type { QueryRequest, ChatImage } from './mcp-client';
-import { type ClientTool } from './ag-ui-client';
-export interface LegacyStreamCallbacks {
-    /** Called for each text token */
-    onToken?: (token: string) => void;
-    /** Called when sources are available */
-    onSources?: (sources: ArticleSummary[]) => void;
-    /** Called when actions are available */
-    onActions?: (actions: TaskButtonData[]) => void;
-    /** Called when a plan is created */
-    onPlan?: (plan: ExecutionPlan) => void;
-    /** Called for progress updates */
-    onProgress?: (progress: ProgressEvent) => void;
-    /** Called when conversation starts (early conversation_id) */
-    onConversationStarted?: (conversationId: string, messageId?: string) => void;
-    /** Called when agent requests data from host app */
-    onQueryRequest?: (request: QueryRequest) => Promise<void>;
-    /** Called on error */
-    onError?: (error: string) => void;
-    /** Called when stream is complete */
-    onComplete?: (conversationId?: string, queryLogId?: string) => void;
-}
-/**
- * Wraps AGUIClient to provide the same interface as the legacy MCPClient.
- * Used during migration to minimize component changes.
- */
-export declare class AGUIClientAdapter {
-    private client;
-    private currentStep;
-    constructor(config: ResolvedConfig);
-    /**
-     * Register a client-side tool (query action).
-     */
-    registerTool(tool: ClientTool): void;
-    /**
-     * Unregister a client-side tool.
-     */
-    unregisterTool(toolName: string): void;
-    /**
-     * Chat with streaming, using legacy callback patterns.
-     */
-    chat(message: string, callbacks: LegacyStreamCallbacks, options?: {
-        history?: ChatMessage[];
-        userContext?: UserContextItem[];
-        images?: ChatImage[];
-        signal?: AbortSignal;
-    }): Promise<ChatResponse>;
-    /**
-     * Get current thread ID.
-     */
-    get threadId(): string;
-    /**
-     * Start a new conversation.
-     */
-    newThread(): string;
-    /**
-     * Send action result back to the agent (for query actions).
-     *
-     * @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): Promise<void>;
-}

package/dist/api/ag-ui-bridge.d.ts

@@ -1,49 +0,0 @@
-/**
- * AG-UI Bridge
- *
- * Temporary bridge that converts Phase 1's JSON-RPC wrapped AG-UI events
- * to native AG-UI events. This allows the SDK to use AG-UI patterns while
- * the backend still uses JSON-RPC transport.
- *
- * Will be removed after Phase 3 (pure AG-UI transport).
- */
-import type { AGUIEvent } from '@ag-ui/core';
-/**
- * Unwrap an AG-UI event from a JSON-RPC notification.
- *
- * Phase 1 backend wraps AG-UI events like this:
- * {
- *   "jsonrpc": "2.0",
- *   "method": "notifications/progress",
- *   "params": {
- *     "ag_ui_event": { "type": "RUN_STARTED", ... }
- *   }
- * }
- *
- * @param jsonRpcEvent - The JSON-RPC notification from the backend
- * @returns The unwrapped AG-UI event, or null if not an AG-UI event
- */
-export declare function unwrapAGUIEvent(jsonRpcEvent: unknown): AGUIEvent | null;
-/**
- * Check if a JSON-RPC event contains an AG-UI event.
- */
-export declare function isAGUIWrappedEvent(jsonRpcEvent: unknown): boolean;
-/**
- * Convert legacy MCP progress events to AG-UI events.
- *
- * This is for backwards compatibility during the transition.
- * Converts old-style progress events to AG-UI events.
- *
- * @param legacyEvent - The legacy MCP progress event
- * @returns An array of AG-UI events (may be multiple for some conversions)
- */
-export declare function convertLegacyProgressToAGUI(legacyEvent: Record<string, unknown>): AGUIEvent[];
-/**
- * Process a raw SSE event and extract AG-UI events.
- *
- * Handles both new AG-UI wrapped events and legacy progress events.
- *
- * @param rawEvent - The parsed JSON from an SSE data line
- * @returns An array of AG-UI events
- */
-export declare function processSSEEvent(rawEvent: unknown): AGUIEvent[];