@supernal/interface 1.0.0

package/dist/esm/src/decorators/Tool.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Supernal AI Interface - Enhanced Tool Decorator System
+ *
+ * Provides comprehensive tool registration with AI safety controls and universal capabilities.
+ * Automatically generates tool schemas with AI control vs testing distinction.
+ */
+import { ToolCategory, ToolFrequency, ToolComplexity } from '../types';
+export interface ToolConfig {
+    name?: string;
+    description?: string;
+    category?: ToolCategory;
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    returnType?: 'markdown' | 'json';
+    supportsStreaming?: boolean;
+    tags?: string[];
+    keywords?: string[];
+    useCases?: string[];
+    permissions?: {
+        level?: string;
+        sensitiveDataAccess?: boolean;
+        networkAccess?: boolean;
+        requiredScopes?: string[];
+    };
+    frequency?: ToolFrequency;
+    complexity?: ToolComplexity;
+    toolId?: string;
+    elementId?: string;
+    selector?: string;
+    containerId?: string;
+    providerName?: string;
+    examples?: string[];
+    aiDescription?: string;
+    executionContext?: 'ui' | 'api' | 'both';
+    mockData?: any;
+    toolType?: 'test-only' | 'ai-safe' | 'ai-restricted' | 'ai-dangerous';
+    aiEnabled?: boolean;
+    requiresApproval?: boolean;
+    dangerLevel?: 'safe' | 'moderate' | 'dangerous' | 'destructive';
+    generateSimulation?: boolean;
+    generateStories?: boolean;
+    elementType?: 'button' | 'input' | 'select' | 'textarea' | 'link' | 'div';
+    actionType?: 'click' | 'change' | 'type' | 'select' | 'navigate' | 'hover' | 'scroll';
+    callbacks?: {
+        storage?: boolean;
+        validation?: boolean;
+        navigation?: boolean;
+        lifecycle?: boolean;
+    };
+    origin?: {
+        path?: string;
+        elements?: string[];
+        modal?: string;
+    };
+    testId?: string;
+    uiSelector?: string;
+    /**
+     * Optional lifecycle callback - invoked after tool execution
+     * If not provided, a default callback will auto-generate a message from elementId + actionType
+     */
+    onExecute?: (result: {
+        success: boolean;
+        message?: string;
+        data?: any;
+        error?: Error;
+    }) => void;
+    /**
+     * Enable/disable auto-reporting (default: true if elementId is provided)
+     */
+    autoReport?: boolean;
+}
+/**
+ * Shorthand configuration for @Tool decorator
+ * Only requires the fields that CANNOT be inferred
+ */
+export interface ToolShorthandConfig {
+    /** Natural language examples for AI matching (REQUIRED) */
+    examples: string[];
+    /** Override inferred name (optional) */
+    name?: string;
+    /** Override inferred danger level (optional) */
+    dangerLevel?: 'safe' | 'moderate' | 'dangerous' | 'destructive';
+    /** Override AI enablement (optional, defaults to inferred from toolType) */
+    aiEnabled?: boolean;
+    /** Override inferred container (optional, inherits from @ToolProvider) */
+    containerId?: string;
+    /** State storage callbacks (optional) */
+    callbacks?: {
+        storage?: boolean;
+        validation?: boolean;
+        navigation?: boolean;
+        lifecycle?: boolean;
+    };
+}
+export interface ToolMetadata {
+    methodName: string;
+    name: string;
+    description: string;
+    category: ToolCategory;
+    inputSchema: any;
+    outputSchema: any;
+    returnType: 'markdown' | 'json';
+    supportsStreaming: boolean;
+    tags: string[];
+    keywords: string[];
+    useCases: string[];
+    permissions: any;
+    frequency: ToolFrequency;
+    complexity: ToolComplexity;
+    toolId: string;
+    elementId?: string;
+    selector?: string;
+    containerId?: string;
+    componentName?: string;
+    stateful?: boolean;
+    callbacks?: {
+        storage?: boolean;
+        validation?: boolean;
+        navigation?: boolean;
+        lifecycle?: boolean;
+    };
+    providerClass?: string;
+    providerName?: string;
+    isStandalone: boolean;
+    examples: string[];
+    aiDescription: string;
+    executionContext: 'ui' | 'api' | 'both';
+    mockData?: any;
+    toolType: 'test-only' | 'ai-safe' | 'ai-restricted' | 'ai-dangerous';
+    aiEnabled: boolean;
+    requiresApproval: boolean;
+    dangerLevel: 'safe' | 'moderate' | 'dangerous' | 'destructive';
+    generateSimulation: boolean;
+    generateStories: boolean;
+    elementType?: 'button' | 'input' | 'select' | 'textarea' | 'link' | 'div';
+    actionType?: 'click' | 'change' | 'type' | 'select' | 'navigate' | 'hover' | 'scroll';
+    origin?: {
+        path?: string;
+        elements?: string[];
+        modal?: string;
+    };
+    method?: Function;
+    instance?: any;
+    testId?: string;
+    uiSelector?: string;
+    /**
+     * Optional lifecycle callback - invoked after tool execution
+     */
+    onExecute?: (result: {
+        success: boolean;
+        message?: string;
+        data?: any;
+        error?: Error;
+    }) => void;
+    /**
+     * Enable/disable auto-reporting (default: true if elementId is provided)
+     */
+    autoReport?: boolean;
+}
+/**
+ * Tool decorator - supports both class methods and standalone functions
+ *
+ * Since JSDoc extraction at runtime is impossible (comments are stripped during compilation),
+ * this decorator relies on method name inference and explicit configuration.
+ *
+ * @example Shorthand syntax (recommended) - for class methods
+ * ```typescript
+ * @ToolProvider('MyContainer')
+ * class MyTools {
+ *   @Tool('my-button', { examples: ['click button'] })
+ *   async clickButton() { }
+ * }
+ * ```
+ *
+ * @example Full config syntax (backward compatible) - for standalone functions
+ * ```typescript
+ * const myTool = Tool({
+ *   elementId: 'my-button',
+ *   containerId: 'MyContainer',
+ *   examples: ['click button'],
+ * })(async () => { });
+ * ```
+ *
+ * @param configOrElementId Full config object or elementId string for shorthand
+ * @param options Optional shorthand config (when first param is string)
+ */
+export declare function Tool(elementId: string, options?: ToolShorthandConfig): MethodDecorator;
+export declare function Tool(config: ToolConfig): any;
+/**
+ * Global default reporter - can be set by application (e.g., ToolManager)
+ */
+declare let globalDefaultReporter: ((result: {
+    success: boolean;
+    message?: string;
+    data?: any;
+    error?: Error;
+}) => void) | null;
+export declare function setDefaultToolReporter(reporter: typeof globalDefaultReporter): void;
+/**
+ * Get all tools (both class methods and standalone functions)
+ * @deprecated Use ToolRegistry.getAllTools() instead
+ */
+export declare function getStandaloneTools(): ToolMetadata[];
+/**
+ * Get tool by ID (works for both class methods and standalone functions)
+ * @deprecated Use ToolRegistry.getTool() instead
+ */
+export declare function getStandaloneTool(toolId: string): ToolMetadata | undefined;
+export {};
+//# sourceMappingURL=Tool.d.ts.map

package/dist/esm/src/decorators/Tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tool.d.ts","sourceRoot":"","sources":["../../../../src/decorators/Tool.ts"],"names":[],"mappings":"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"}