@pillar-ai/sdk 0.1.22 → 0.1.24

package/dist/tools/index.d.ts

@@ -23,5 +23,6 @@
  *
  * @module tools
  */
+export { validateToolName, TOOL_NAME_PATTERN } from './types';
 export type { ToolType, ToolDataSchema, ToolDataSchemaProperty, ToolDefinition, ToolDefinitions, ToolManifest, ToolManifestEntry, ClientInfo, Platform, SyncToolDefinition, SyncToolDefinitions, ToolTypeDataMap, NavigateToolData, TriggerToolData, InlineUIData, ExternalLinkData, CopyTextData, QueryToolData, ToolDataType, ToolNames, TypedTaskHandler, TypedOnTask, TypedPillarMethods, ToolExecuteResult, ToolSchema, ActionType, ActionDataSchema, ActionDataSchemaProperty, ActionDefinition, ActionDefinitions, ActionManifest, ActionManifestEntry, SyncActionDefinition, SyncActionDefinitions, NavigateActionData, TriggerActionData, QueryActionData, ActionTypeDataMap, ActionDataType, ActionNames, ActionResult, ActionSchema, } from './types';
 export { setClientInfo, getClientInfo, getHandler, getToolDefinition, hasTool, getToolNames, getManifest, clearRegistry, getToolCount, getActionDefinition, hasAction, getActionNames, getActionCount, } from './registry';

package/dist/tools/types.d.ts

@@ -37,17 +37,17 @@
  * - start_tutorial: Start a tutorial/walkthrough
  * - inline_ui: Display inline UI card in chat
  */
-export type ToolType = 'navigate' | 'open_modal' | 'fill_form' | 'trigger_tool' | 'query' | 'copy_text' | 'external_link' | 'start_tutorial' | 'inline_ui';
+export type ToolType = "navigate" | "open_modal" | "fill_form" | "trigger_tool" | "query" | "copy_text" | "external_link" | "start_tutorial" | "inline_ui";
 /**
  * Supported platforms for tool deployments.
  */
-export type Platform = 'web' | 'ios' | 'android' | 'desktop';
+export type Platform = "web" | "ios" | "android" | "desktop";
 /**
  * Schema property definition for a single field.
  * Supports nested objects and arrays with items.
  */
 export interface ToolDataSchemaProperty {
-    type: 'string' | 'number' | 'boolean' | 'array' | 'object';
+    type: "string" | "number" | "boolean" | "array" | "object";
     description?: string;
     enum?: string[];
     default?: unknown;
@@ -65,7 +65,7 @@ export interface ToolDataSchemaProperty {
  * and populate the tool's data field before execution.
  */
 export interface ToolDataSchema {
-    type: 'object';
+    type: "object";
     properties: Record<string, ToolDataSchemaProperty>;
     required?: string[];
 }
@@ -191,6 +191,7 @@ export type ToolDefinitions = Record<string, ToolDefinition<unknown>>;
 export interface ToolManifestEntry {
     name: string;
     description: string;
+    guidance?: string;
     examples?: string[];
     type: ToolType;
     path?: string;
@@ -439,6 +440,28 @@ export interface TypedOnTask<TTools extends SyncToolDefinitions | ToolDefinition
 export interface TypedPillarMethods<TTools extends SyncToolDefinitions | ToolDefinitions> {
     onTask: TypedOnTask<TTools>;
 }
+/**
+ * Valid tool name pattern (matches LLM provider requirements).
+ *
+ * - Must start with a letter or underscore
+ * - Can contain: letters, numbers, underscores, dots, colons, dashes
+ * - Maximum 64 characters
+ *
+ * Examples:
+ *   - Valid: "add_to_cart", "get_user.profile", "api:v2:search"
+ *   - Invalid: "Increment count" (space), "123_start" (starts with number)
+ */
+export declare const TOOL_NAME_PATTERN: RegExp;
+/**
+ * Validate a tool name against LLM provider requirements.
+ *
+ * @param name - Tool name to validate
+ * @returns Object with `valid` boolean and optional `error` message
+ */
+export declare function validateToolName(name: string): {
+    valid: boolean;
+    error?: string;
+};
 /**
  * Result returned from a tool's execute function.
  *
@@ -447,10 +470,10 @@ export interface TypedPillarMethods<TTools extends SyncToolDefinitions | ToolDef
  */
 export interface ToolExecuteResult {
     content: Array<{
-        type: 'text';
+        type: "text";
         text: string;
     } | {
-        type: 'image';
+        type: "image";
         data: string;
         mimeType: string;
     }>;
@@ -490,6 +513,17 @@ export interface ToolSchema<TInput = Record<string, unknown>> {
     name: string;
     /** Human-readable description for AI matching */
     description: string;
+    /**
+     * Agent-facing instructions for when/how to use this tool.
+     *
+     * Appended to the tool description in the LLM's tool list at
+     * selection time. Use for disambiguation and prerequisite hints
+     * (e.g., "Call get_datasources first to obtain a datasource_uid").
+     *
+     * Extracted by `pillar-sync --scan` and stored on the backend
+     * Action model so the agent sees it without runtime code.
+     */
+    guidance?: string;
     /**
      * Type of tool - determines how the SDK handles it and organizes it in the UI.
      */
@@ -499,7 +533,7 @@ export interface ToolSchema<TInput = Record<string, unknown>> {
      * The AI extracts structured data from the conversation to populate these.
      */
     inputSchema?: {
-        type: 'object';
+        type: "object";
         properties: Record<string, unknown>;
         required?: string[];
     };
@@ -527,6 +561,19 @@ export interface ToolSchema<TInput = Record<string, unknown>> {
      * - `void` if the tool has no return value
      */
     execute: (input: TInput) => Promise<ToolExecuteResult | unknown | void> | ToolExecuteResult | unknown | void;
+    /**
+     * Whether to also register this tool with WebMCP (navigator.modelContext).
+     *
+     * When true, the tool will be exposed to browser-native AI agents and
+     * assistive technologies via the W3C WebMCP API. The tool is registered
+     * on mount and unregistered on unmount (or when the tool is removed).
+     *
+     * Only works in browser contexts where `navigator.modelContext` is available
+     * (either natively or via polyfill).
+     *
+     * @default false
+     */
+    webMCP?: boolean;
 }
 /** @deprecated Use ToolType instead */
 export type ActionType = ToolType;

package/dist/utils/tracing.d.ts

@@ -0,0 +1,43 @@
+/**
+ * OpenTelemetry browser tracing for Pillar SDK.
+ *
+ * Initialises a WebTracerProvider that exports spans via OTLP/JSON to the
+ * backend proxy endpoint (`/mcp/telemetry/v1/traces`).  The backend forwards
+ * them to Google Cloud Trace so browser and server spans share the same
+ * project and can be correlated by trace ID.
+ *
+ * Tracing is opt-in via `Pillar.init({ tracing: true })` or automatically
+ * when `debug: true`.
+ */
+import { trace, context, type Tracer, type Span, SpanStatusCode } from '@opentelemetry/api';
+/**
+ * Initialise the browser tracing provider.
+ *
+ * @param apiBaseUrl  The SDK's API base URL (e.g. `https://help-api.trypillar.com`)
+ * @param attrs       Extra resource attributes (product key, visitor id, …)
+ */
+export declare function initTracing(apiBaseUrl: string, attrs?: Record<string, string>): Tracer;
+/** Return the active tracer (or a no-op tracer if tracing is not initialised). */
+export declare function getTracer(): Tracer;
+/** Whether tracing has been initialised. */
+export declare function isTracingEnabled(): boolean;
+/**
+ * Build a W3C `traceparent` header value from the current active span.
+ * Returns `undefined` if there is no active span.
+ */
+export declare function getTraceparentHeader(): string | undefined;
+/**
+ * Inject `traceparent` (and optionally `tracestate`) into a headers object.
+ * Mutates and returns the headers dict.
+ */
+export declare function injectTraceHeaders(headers: Record<string, string>): Record<string, string>;
+/**
+ * Force-flush any pending spans. Call on page unload or when needed.
+ */
+export declare function flushTracing(): Promise<void>;
+/**
+ * Shut down the provider (call on SDK destroy).
+ */
+export declare function shutdownTracing(): Promise<void>;
+export { trace, context, SpanStatusCode };
+export type { Span };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pillar-ai/sdk",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "description": "Product copilot SDK for SaaS and web apps — AI assistant that executes tasks, not just answers questions",
   "type": "module",
   "main": "./dist/pillar.esm.js",
@@ -65,11 +65,14 @@
     }
   },
   "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/context-zone": "^2.5.1",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.212.0",
+    "@opentelemetry/sdk-trace-web": "^2.5.1",
     "@preact/signals": "^1.3.1",
     "marked": "^17.0.1",
     "preact": "^10.25.4",
-    "preact-iso": "^2.9.0",
-    "user": "^0.0.0"
+    "preact-iso": "^2.9.0"
   },
   "devDependencies": {
     "@babel/core": "^7.24.0",

package/dist/actions/definitions/analytics.d.ts

@@ -1,18 +0,0 @@
-export declare const analyticsActions: {
-    view_search_analytics: {
-        description: string;
-        type: "navigate";
-        path: string;
-        autoRun: true;
-        autoComplete: true;
-        handler: () => void;
-    };
-    view_ai_analytics: {
-        description: string;
-        type: "navigate";
-        path: string;
-        autoRun: true;
-        autoComplete: true;
-        handler: () => void;
-    };
-};

package/dist/actions/definitions/content.d.ts

@@ -1,40 +0,0 @@
-export declare const contentActions: {
-    view_all_articles: {
-        description: string;
-        type: "navigate";
-        path: string;
-        autoRun: true;
-        autoComplete: true;
-        handler: () => void;
-    };
-    view_article: {
-        description: string;
-        type: "trigger_action";
-        autoRun: false;
-        autoComplete: false;
-        defaultData: {
-            action: string;
-        };
-        handler: () => void;
-    };
-    filter_stale: {
-        description: string;
-        type: "trigger_action";
-        autoRun: false;
-        autoComplete: false;
-        defaultData: {
-            action: string;
-        };
-        handler: () => void;
-    };
-    view_categories: {
-        description: string;
-        type: "trigger_action";
-        autoRun: false;
-        autoComplete: false;
-        defaultData: {
-            action: string;
-        };
-        handler: () => void;
-    };
-};

package/dist/actions/definitions/index.d.ts

@@ -1,26 +0,0 @@
-/**
- * Action Definitions Index
- *
- * Imports and registers all action definitions for the Pillar Admin app.
- * These are code-first action definitions that get synced to the backend
- * during CI/CD builds.
- *
- * To use in your app:
- * 1. Import this file early in your app initialization
- * 2. Or create your own action definitions using defineActions()
- *
- * The action metadata is extracted via `npm run extract-actions` and
- * synced to the backend via `npm run sync-actions`.
- */
-import './navigation';
-import './settings';
-import './sources';
-import './analytics';
-import './team';
-import './support';
-export { navigationActions } from './navigation';
-export { settingsActions } from './settings';
-export { sourcesActions } from './sources';
-export { analyticsActions } from './analytics';
-export { teamActions } from './team';
-export { supportActions } from './support';

package/dist/actions/definitions/navigation.d.ts

@@ -1,65 +0,0 @@
-export declare const navigationActions: {
-    open_knowledge: {
-        description: string;
-        examples: string[];
-        type: "navigate";
-        path: string;
-        autoRun: true;
-        autoComplete: true;
-        handler: () => void;
-    };
-    open_settings: {
-        description: string;
-        examples: string[];
-        type: "navigate";
-        path: string;
-        autoRun: true;
-        autoComplete: true;
-        handler: () => void;
-    };
-    open_actions: {
-        description: string;
-        examples: string[];
-        type: "navigate";
-        path: string;
-        autoRun: true;
-        autoComplete: true;
-        handler: () => void;
-    };
-    open_analytics: {
-        description: string;
-        examples: string[];
-        type: "navigate";
-        path: string;
-        autoRun: true;
-        autoComplete: true;
-        handler: () => void;
-    };
-    open_ai_tester: {
-        description: string;
-        examples: string[];
-        type: "navigate";
-        path: string;
-        autoRun: true;
-        autoComplete: true;
-        handler: () => void;
-    };
-    open_configure: {
-        description: string;
-        examples: string[];
-        type: "navigate";
-        path: string;
-        autoRun: true;
-        autoComplete: true;
-        handler: () => void;
-    };
-    create_new_action: {
-        description: string;
-        examples: string[];
-        type: "navigate";
-        path: string;
-        autoRun: true;
-        autoComplete: true;
-        handler: () => void;
-    };
-};

package/dist/actions/definitions/settings.d.ts

@@ -1,162 +0,0 @@
-export declare const settingsActions: {
-    open_branding_settings: {
-        description: string;
-        examples: string[];
-        type: "navigate";
-        path: string;
-        autoRun: true;
-        autoComplete: true;
-        handler: () => void;
-    };
-    open_layout_settings: {
-        description: string;
-        examples: string[];
-        type: "navigate";
-        path: string;
-        autoRun: true;
-        autoComplete: true;
-        handler: () => void;
-    };
-    open_header_settings: {
-        description: string;
-        examples: string[];
-        type: "navigate";
-        path: string;
-        autoRun: true;
-        autoComplete: true;
-        handler: () => void;
-    };
-    open_footer_settings: {
-        description: string;
-        examples: string[];
-        type: "navigate";
-        path: string;
-        autoRun: true;
-        autoComplete: true;
-        handler: () => void;
-    };
-    open_features_settings: {
-        description: string;
-        examples: string[];
-        type: "navigate";
-        path: string;
-        autoRun: true;
-        autoComplete: true;
-        handler: () => void;
-    };
-    open_ai_settings: {
-        description: string;
-        examples: string[];
-        type: "navigate";
-        path: string;
-        autoRun: true;
-        autoComplete: true;
-        handler: () => void;
-    };
-    open_seo_settings: {
-        description: string;
-        examples: string[];
-        type: "navigate";
-        path: string;
-        autoRun: true;
-        autoComplete: true;
-        handler: () => void;
-    };
-    enable_ai_assistant: {
-        description: string;
-        type: "trigger_action";
-        autoRun: false;
-        autoComplete: false;
-        defaultData: {
-            action: string;
-            target: string;
-        };
-        handler: () => void;
-    };
-    disable_ai_assistant: {
-        description: string;
-        type: "trigger_action";
-        autoRun: false;
-        autoComplete: false;
-        defaultData: {
-            action: string;
-            target: string;
-        };
-        handler: () => void;
-    };
-    enable_dark_mode: {
-        description: string;
-        examples: string[];
-        type: "trigger_action";
-        autoRun: true;
-        autoComplete: true;
-        defaultData: {
-            action: string;
-            theme: string;
-        };
-        handler: () => void;
-    };
-    disable_dark_mode: {
-        description: string;
-        examples: string[];
-        type: "trigger_action";
-        autoRun: true;
-        autoComplete: true;
-        defaultData: {
-            action: string;
-            theme: string;
-        };
-        handler: () => void;
-    };
-    toggle_dark_mode: {
-        description: string;
-        examples: string[];
-        type: "trigger_action";
-        autoRun: true;
-        autoComplete: true;
-        defaultData: {
-            action: string;
-        };
-        handler: () => void;
-    };
-    change_theme: {
-        description: string;
-        type: "trigger_action";
-        autoRun: true;
-        autoComplete: true;
-        defaultData: {
-            action: string;
-        };
-        handler: () => void;
-    };
-    update_logo: {
-        description: string;
-        type: "trigger_action";
-        autoRun: true;
-        autoComplete: true;
-        defaultData: {
-            action: string;
-        };
-        handler: () => void;
-    };
-    add_footer_link: {
-        description: string;
-        type: "trigger_action";
-        autoRun: true;
-        autoComplete: true;
-        defaultData: {
-            action: string;
-        };
-        handler: () => void;
-    };
-    configure_suggested_questions: {
-        description: string;
-        type: "trigger_action";
-        autoRun: true;
-        autoComplete: true;
-        defaultData: {
-            action: string;
-        };
-        handler: () => void;
-    };
-};

package/dist/actions/definitions/sources.d.ts

@@ -1,44 +0,0 @@
-export declare const sourcesActions: {
-    add_new_source: {
-        description: string;
-        examples: string[];
-        type: "navigate";
-        path: string;
-        autoRun: true;
-        autoComplete: true;
-        dataSchema: {
-            type: "object";
-            properties: {
-                type: {
-                    type: "string";
-                    description: string;
-                };
-                url: {
-                    type: "string";
-                    description: string;
-                };
-                name: {
-                    type: "string";
-                    description: string;
-                };
-            };
-        };
-        handler: () => void;
-    };
-    crawl_website: {
-        description: string;
-        type: "navigate";
-        path: string;
-        autoRun: true;
-        autoComplete: true;
-        handler: () => void;
-    };
-    connect_cloud_storage: {
-        description: string;
-        type: "navigate";
-        path: string;
-        autoRun: true;
-        autoComplete: true;
-        handler: () => void;
-    };
-};

package/dist/actions/definitions/support.d.ts

@@ -1,15 +0,0 @@
-export declare const supportActions: {
-    escalate: {
-        description: string;
-        examples: string[];
-        type: "external_link";
-        externalUrl: string;
-        handler: () => void;
-    };
-    defer: {
-        description: string;
-        examples: string[];
-        type: "trigger_action";
-        handler: () => void;
-    };
-};

package/dist/actions/definitions/team.d.ts

@@ -1,120 +0,0 @@
-export declare const teamActions: {
-    open_team_settings: {
-        description: string;
-        type: "navigate";
-        path: string;
-        autoRun: true;
-        autoComplete: true;
-        handler: () => void;
-    };
-    invite_team_member: {
-        description: string;
-        type: "inline_ui";
-        autoRun: false;
-        autoComplete: false;
-        defaultData: {
-            card_type: string;
-            emails: never[];
-            role: string;
-        };
-        dataSchema: {
-            type: "object";
-            properties: {
-                emails: {
-                    type: "array";
-                    description: string;
-                };
-                role: {
-                    type: "string";
-                    description: string;
-                    enum: string[];
-                };
-            };
-            required: string[];
-        };
-        requiredContext: {
-            userRole: string;
-        };
-        handler: () => void;
-    };
-    view_pending_invitations: {
-        description: string;
-        type: "trigger_action";
-        autoRun: true;
-        autoComplete: true;
-        defaultData: {
-            action: string;
-        };
-        requiredContext: {
-            userRole: string;
-        };
-        handler: () => void;
-    };
-    resend_invitation: {
-        description: string;
-        type: "trigger_action";
-        autoRun: false;
-        autoComplete: false;
-        defaultData: {
-            action: string;
-        };
-        requiredContext: {
-            userRole: string;
-        };
-        handler: () => void;
-    };
-    cancel_invitation: {
-        description: string;
-        type: "trigger_action";
-        autoRun: false;
-        autoComplete: false;
-        defaultData: {
-            action: string;
-        };
-        requiredContext: {
-            userRole: string;
-        };
-        handler: () => void;
-    };
-    remove_team_member: {
-        description: string;
-        type: "trigger_action";
-        autoRun: false;
-        autoComplete: false;
-        defaultData: {
-            action: string;
-        };
-        requiredContext: {
-            userRole: string;
-        };
-        handler: () => void;
-    };
-    promote_to_admin: {
-        description: string;
-        type: "trigger_action";
-        autoRun: false;
-        autoComplete: false;
-        defaultData: {
-            action: string;
-            role: string;
-        };
-        requiredContext: {
-            userRole: string;
-        };
-        handler: () => void;
-    };
-    demote_to_member: {
-        description: string;
-        type: "trigger_action";
-        autoRun: false;
-        autoComplete: false;
-        defaultData: {
-            action: string;
-            role: string;
-        };
-        requiredContext: {
-            userRole: string;
-        };
-        handler: () => void;
-    };
-};