@frontmcp/sdk 0.7.2 → 0.8.0

package/skill/skill-storage.factory.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Skill Storage Factory
+ *
+ * Factory functions for creating skill storage providers.
+ * Supports Memory (default), VectorDB, and External backends.
+ *
+ * @module skill/skill-storage.factory
+ */
+import type { FrontMcpLogger } from '../common';
+import type { ToolRegistryInterface } from '../common/interfaces/internal';
+import type { SkillStorageProvider, SkillStorageProviderType } from './skill-storage.interface';
+import { SkillToolValidator } from './skill-validator';
+import { MemorySkillProviderOptions } from './providers/memory-skill.provider';
+import type { ExternalSkillProviderBase, ExternalSkillMode } from './providers/external-skill.provider';
+import type { SkillSyncStateStore } from './sync/sync-state.interface';
+/**
+ * VectorDB provider options (for external vector database).
+ */
+export interface VectorDBSkillProviderOptions {
+    /**
+     * Embedding strategy to use.
+     * @default 'tfidf'
+     */
+    strategy?: 'tfidf' | 'ml';
+    /**
+     * Model name for ML embeddings.
+     * @default 'Xenova/all-MiniLM-L6-v2'
+     */
+    modelName?: string;
+    /**
+     * Default number of search results.
+     * @default 10
+     */
+    defaultTopK?: number;
+    /**
+     * Default minimum similarity threshold.
+     * @default 0.1
+     */
+    defaultMinScore?: number;
+}
+/**
+ * External provider configuration.
+ * Used when connecting to external skill storage (e.g., shared vector DB).
+ */
+export interface ExternalSkillProviderConfig {
+    /**
+     * Operating mode for the external provider.
+     *
+     * - 'read-only': Skills are fetched from external storage, no writes
+     * - 'persistent': Local skills are synced to external storage with SHA-based change detection
+     */
+    mode: ExternalSkillMode;
+    /**
+     * Store for persisting sync state.
+     * Required for persistent mode to track which skills have been synced.
+     */
+    syncStateStore?: SkillSyncStateStore;
+    /**
+     * Default number of search results.
+     * @default 10
+     */
+    defaultTopK?: number;
+    /**
+     * Default minimum similarity threshold.
+     * @default 0.1
+     */
+    defaultMinScore?: number;
+}
+/**
+ * Extended factory result that includes external provider when applicable.
+ */
+export interface ExtendedSkillStorageFactoryResult extends SkillStorageFactoryResult {
+    /**
+     * The external provider instance if type is 'external'.
+     * Provides access to sync methods and state.
+     */
+    externalProvider?: ExternalSkillProviderBase;
+}
+/**
+ * Options for creating a skill storage provider.
+ */
+export interface SkillStorageFactoryOptions {
+    /**
+     * Provider type to use.
+     * @default 'memory'
+     */
+    provider?: 'memory' | 'vectordb' | 'external';
+    /**
+     * Options for memory provider.
+     */
+    memory?: Omit<MemorySkillProviderOptions, 'toolValidator'>;
+    /**
+     * Options for VectorDB provider.
+     */
+    vectordb?: VectorDBSkillProviderOptions;
+    /**
+     * Configuration for external provider.
+     * Note: External providers require a concrete implementation to be passed.
+     */
+    external?: ExternalSkillProviderConfig;
+    /**
+     * Custom external provider instance.
+     * Required when provider is 'external'.
+     * Must extend ExternalSkillProviderBase.
+     */
+    externalProvider?: ExternalSkillProviderBase;
+    /**
+     * Tool registry for validating tool references.
+     * Required for tool validation in search results.
+     */
+    toolRegistry?: ToolRegistryInterface;
+    /**
+     * Logger instance.
+     */
+    logger?: FrontMcpLogger;
+}
+/**
+ * Result of creating a skill storage provider.
+ */
+export interface SkillStorageFactoryResult {
+    /**
+     * The created storage provider.
+     */
+    provider: SkillStorageProvider;
+    /**
+     * The type of provider created.
+     */
+    type: SkillStorageProviderType;
+    /**
+     * Tool validator (if tool registry was provided).
+     */
+    toolValidator?: SkillToolValidator;
+}
+/**
+ * Create a skill storage provider based on configuration.
+ *
+ * @param options - Configuration options
+ * @returns The created provider with type information
+ *
+ * @example Memory provider (default)
+ * ```typescript
+ * const { provider, type } = createSkillStorageProvider({
+ *   toolRegistry: scope.tools,
+ *   logger,
+ * });
+ * ```
+ *
+ * @example VectorDB provider
+ * ```typescript
+ * const { provider, type } = createSkillStorageProvider({
+ *   provider: 'vectordb',
+ *   vectordb: { strategy: 'ml' },
+ *   toolRegistry: scope.tools,
+ *   logger,
+ * });
+ * ```
+ *
+ * @example External provider (read-only)
+ * ```typescript
+ * const { provider, type, externalProvider } = createSkillStorageProvider({
+ *   provider: 'external',
+ *   externalProvider: new MyExternalProvider({ mode: 'read-only' }),
+ *   logger,
+ * });
+ * ```
+ *
+ * @example External provider (persistent)
+ * ```typescript
+ * const { provider, externalProvider } = createSkillStorageProvider({
+ *   provider: 'external',
+ *   externalProvider: new MyExternalProvider({
+ *     mode: 'persistent',
+ *     syncStateStore: new MemorySyncStateStore(),
+ *   }),
+ *   logger,
+ * });
+ * // Later: sync local skills
+ * await externalProvider.syncSkills(localSkills);
+ * ```
+ */
+export declare function createSkillStorageProvider(options?: SkillStorageFactoryOptions): ExtendedSkillStorageFactoryResult;
+/**
+ * Create an in-memory skill storage provider explicitly.
+ *
+ * @param options - Configuration options
+ * @returns An in-memory skill storage provider
+ */
+export declare function createMemorySkillProvider(options?: {
+    toolRegistry?: ToolRegistryInterface;
+    defaultTopK?: number;
+    defaultMinScore?: number;
+    logger?: FrontMcpLogger;
+}): SkillStorageFactoryResult;
+//# sourceMappingURL=skill-storage.factory.d.ts.map

package/skill/skill-storage.factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-storage.factory.d.ts","sourceRoot":"","sources":["../../src/skill/skill-storage.factory.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAChD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAC3E,OAAO,KAAK,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAChG,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAuB,0BAA0B,EAAE,MAAM,mCAAmC,CAAC;AACpG,OAAO,KAAK,EAAE,yBAAyB,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AACxG,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAGvE;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAE1B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,2BAA2B;IAC1C;;;;;OAKG;IACH,IAAI,EAAE,iBAAiB,CAAC;IAExB;;;OAGG;IACH,cAAc,CAAC,EAAE,mBAAmB,CAAC;IAErC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;GAEG;AACH,MAAM,WAAW,iCAAkC,SAAQ,yBAAyB;IAClF;;;OAGG;IACH,gBAAgB,CAAC,EAAE,yBAAyB,CAAC;CAC9C;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,QAAQ,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,UAAU,CAAC;IAE9C;;OAEG;IACH,MAAM,CAAC,EAAE,IAAI,CAAC,0BAA0B,EAAE,eAAe,CAAC,CAAC;IAE3D;;OAEG;IACH,QAAQ,CAAC,EAAE,4BAA4B,CAAC;IAExC;;;OAGG;IACH,QAAQ,CAAC,EAAE,2BAA2B,CAAC;IAEvC;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,yBAAyB,CAAC;IAE7C;;;OAGG;IACH,YAAY,CAAC,EAAE,qBAAqB,CAAC;IAErC;;OAEG;IACH,MAAM,CAAC,EAAE,cAAc,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;OAEG;IACH,QAAQ,EAAE,oBAAoB,CAAC;IAE/B;;OAEG;IACH,IAAI,EAAE,wBAAwB,CAAC;IAE/B;;OAEG;IACH,aAAa,CAAC,EAAE,kBAAkB,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,GAAE,0BAA+B,GACvC,iCAAiC,CA6EnC;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,GAAE;IACP,YAAY,CAAC,EAAE,qBAAqB,CAAC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,CAAC,EAAE,cAAc,CAAC;CACpB,GACL,yBAAyB,CAiB3B"}

package/skill/skill-storage.interface.d.ts

@@ -0,0 +1,230 @@
+import { SkillMetadata } from '../common/metadata';
+import { SkillContent } from '../common/interfaces';
+/**
+ * Options for searching skills.
+ */
+export interface SkillSearchOptions {
+    /**
+     * Maximum number of results to return.
+     * @default 10
+     */
+    topK?: number;
+    /**
+     * Filter by specific tags.
+     */
+    tags?: string[];
+    /**
+     * Minimum similarity score threshold (0-1).
+     * @default 0.1
+     */
+    minScore?: number;
+    /**
+     * Only return skills where all referenced tools are available.
+     * @default false
+     */
+    requireAllTools?: boolean;
+    /**
+     * Skill IDs to exclude from results.
+     */
+    excludeIds?: string[];
+    /**
+     * Filter by specific tools (skills must reference these tools).
+     */
+    tools?: string[];
+}
+/**
+ * Options for listing skills.
+ */
+export interface SkillListOptions {
+    /**
+     * Number of skills to skip (for pagination).
+     * @default 0
+     */
+    offset?: number;
+    /**
+     * Maximum number of skills to return.
+     * @default 50
+     */
+    limit?: number;
+    /**
+     * Filter by specific tags.
+     */
+    tags?: string[];
+    /**
+     * Field to sort by.
+     * @default 'name'
+     */
+    sortBy?: 'name' | 'priority' | 'createdAt';
+    /**
+     * Sort order.
+     * @default 'asc'
+     */
+    sortOrder?: 'asc' | 'desc';
+    /**
+     * Include hidden skills in results.
+     * @default false
+     */
+    includeHidden?: boolean;
+}
+/**
+ * Result from a skill search operation.
+ */
+export interface SkillSearchResult {
+    /**
+     * The skill metadata.
+     */
+    metadata: SkillMetadata;
+    /**
+     * Relevance score (0-1).
+     */
+    score: number;
+    /**
+     * Tools that are available in the current scope.
+     */
+    availableTools: string[];
+    /**
+     * Tools that are referenced but not available.
+     */
+    missingTools: string[];
+    /**
+     * Source of the skill ('local' or 'external').
+     */
+    source: 'local' | 'external';
+}
+/**
+ * Result from loading a skill.
+ */
+export interface SkillLoadResult {
+    /**
+     * The loaded skill content.
+     */
+    skill: SkillContent;
+    /**
+     * Tools that are available in the current scope.
+     */
+    availableTools: string[];
+    /**
+     * Tools that are referenced but not available.
+     */
+    missingTools: string[];
+    /**
+     * True if all required tools are available.
+     */
+    isComplete: boolean;
+    /**
+     * Warning message if tools are missing.
+     */
+    warning?: string;
+}
+/**
+ * Result from listing skills.
+ */
+export interface SkillListResult {
+    /**
+     * List of skill metadata.
+     */
+    skills: SkillMetadata[];
+    /**
+     * Total number of skills matching the filter.
+     */
+    total: number;
+    /**
+     * Whether there are more skills beyond this page.
+     */
+    hasMore: boolean;
+}
+/**
+ * Provider type identifier.
+ */
+export type SkillStorageProviderType = 'memory' | 'vectordb' | 'postgres' | 'external' | 'custom';
+/**
+ * Interface for skill storage providers.
+ *
+ * Storage providers handle persistence and retrieval of skills,
+ * enabling both local (in-memory) and external (database) storage.
+ */
+export interface SkillStorageProvider {
+    /**
+     * Provider type identifier.
+     */
+    readonly type: SkillStorageProviderType;
+    /**
+     * Initialize the storage provider.
+     * Called once during startup.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Search for skills matching a query.
+     *
+     * @param query - Search query string
+     * @param options - Search options
+     * @returns Array of matching skills with scores
+     */
+    search(query: string, options?: SkillSearchOptions): Promise<SkillSearchResult[]>;
+    /**
+     * Load a skill by ID.
+     *
+     * @param skillId - The skill identifier
+     * @returns The loaded skill or null if not found
+     */
+    load(skillId: string): Promise<SkillLoadResult | null>;
+    /**
+     * List skills with optional filtering and pagination.
+     *
+     * @param options - List options
+     * @returns Paginated list of skills
+     */
+    list(options?: SkillListOptions): Promise<SkillListResult>;
+    /**
+     * Check if a skill exists.
+     *
+     * @param skillId - The skill identifier
+     * @returns True if the skill exists
+     */
+    exists(skillId: string): Promise<boolean>;
+    /**
+     * Count skills matching optional criteria.
+     *
+     * @param options - Filter options
+     * @returns Number of matching skills
+     */
+    count(options?: {
+        tags?: string[];
+        includeHidden?: boolean;
+    }): Promise<number>;
+    /**
+     * Dispose of resources.
+     * Called during shutdown.
+     */
+    dispose(): Promise<void>;
+}
+/**
+ * Interface for skill storage providers that support adding skills.
+ * Used by providers that can dynamically add skills (e.g., file watchers).
+ */
+export interface MutableSkillStorageProvider extends SkillStorageProvider {
+    /**
+     * Add a skill to the storage.
+     *
+     * @param skill - The skill content to add
+     */
+    add(skill: SkillContent): Promise<void>;
+    /**
+     * Update an existing skill.
+     *
+     * @param skillId - The skill identifier
+     * @param skill - The updated skill content
+     */
+    update(skillId: string, skill: SkillContent): Promise<void>;
+    /**
+     * Remove a skill from the storage.
+     *
+     * @param skillId - The skill identifier
+     */
+    remove(skillId: string): Promise<void>;
+    /**
+     * Clear all skills from the storage.
+     */
+    clear(): Promise<void>;
+}
+//# sourceMappingURL=skill-storage.interface.d.ts.map

package/skill/skill-storage.interface.d.ts.map

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

package/skill/skill-validator.d.ts

@@ -0,0 +1,63 @@
+import { ToolRegistryInterface } from '../common/interfaces/internal';
+/**
+ * Result of validating tool availability for a skill.
+ */
+export interface ToolValidationResult {
+    /**
+     * Tools that are available (exist and not hidden).
+     */
+    available: string[];
+    /**
+     * Tools that don't exist in the registry.
+     */
+    missing: string[];
+    /**
+     * Tools that exist but are hidden from discovery.
+     */
+    hidden: string[];
+    /**
+     * True if all required tools are available (exist and not hidden).
+     */
+    complete: boolean;
+}
+/**
+ * Validates tool availability for skills.
+ *
+ * This validator checks if the tools referenced by a skill are available
+ * in the current scope. It categorizes tools as available, missing, or hidden.
+ */
+export declare class SkillToolValidator {
+    private readonly toolRegistry;
+    constructor(toolRegistry: ToolRegistryInterface);
+    /**
+     * Validate tool availability for a list of tool names.
+     *
+     * @param toolNames - Array of tool names to validate
+     * @param requiredTools - Optional set of tool names that are required
+     * @returns Validation result with categorized tools
+     */
+    validate(toolNames: string[], requiredTools?: Set<string>): ToolValidationResult;
+    /**
+     * Format a warning message for missing/hidden tools.
+     *
+     * @param result - Validation result
+     * @param skillName - Name of the skill (for error message)
+     * @returns Warning message or undefined if no issues
+     */
+    formatWarning(result: ToolValidationResult, skillName: string): string | undefined;
+    /**
+     * Check if a single tool is available (exists and not hidden).
+     *
+     * @param toolName - Name of the tool to check
+     * @returns True if the tool is available
+     */
+    isToolAvailable(toolName: string): boolean;
+    /**
+     * Check if a single tool exists (regardless of visibility).
+     *
+     * @param toolName - Name of the tool to check
+     * @returns True if the tool exists
+     */
+    toolExists(toolName: string): boolean;
+}
+//# sourceMappingURL=skill-validator.d.ts.map

package/skill/skill-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-validator.d.ts","sourceRoot":"","sources":["../../src/skill/skill-validator.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,SAAS,EAAE,MAAM,EAAE,CAAC;IAEpB;;OAEG;IACH,OAAO,EAAE,MAAM,EAAE,CAAC;IAElB;;OAEG;IACH,MAAM,EAAE,MAAM,EAAE,CAAC;IAEjB;;OAEG;IACH,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;;GAKG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAwB;gBAEzC,YAAY,EAAE,qBAAqB;IAI/C;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,oBAAoB;IAsDhF;;;;;;OAMG;IACH,aAAa,CAAC,MAAM,EAAE,oBAAoB,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAkBlF;;;;;OAKG;IACH,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAK1C;;;;;OAKG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;CAItC"}

package/skill/skill.events.d.ts

@@ -0,0 +1,88 @@
+import { SkillEntry } from '../common';
+import type { SkillValidationReport } from './errors/skill-validation.error';
+import type { SyncResult } from './sync/sync-state.interface';
+/**
+ * Kind of skill change event.
+ */
+export type SkillChangeKind = 'added' | 'updated' | 'removed' | 'reset' | 'validated' | 'synced';
+/**
+ * Scope of a skill change event.
+ * - `global`: Change affects all sessions
+ * - `session`: Change affects only a specific session
+ */
+export type SkillChangeScope = 'global' | 'session';
+/**
+ * Event emitted when skills change in the registry.
+ */
+export type SkillChangeEvent = {
+    /**
+     * Kind of change that occurred.
+     */
+    kind: SkillChangeKind;
+    /**
+     * Whether the change affects all sessions or a specific session.
+     */
+    changeScope: SkillChangeScope;
+    /**
+     * Session ID if changeScope is 'session'.
+     */
+    sessionId?: string;
+    /**
+     * Related request ID if available.
+     */
+    relatedRequestId?: string;
+    /**
+     * Version number of the registry after this change.
+     */
+    version: number;
+    /**
+     * Current snapshot of all skills after the change.
+     */
+    snapshot: readonly SkillEntry[];
+    /**
+     * Validation report when kind is 'validated'.
+     * Contains validation results for all skills in the registry.
+     */
+    validationReport?: SkillValidationReport;
+    /**
+     * Sync result when kind is 'synced'.
+     * Contains information about skills added/updated/removed from external storage.
+     */
+    syncResult?: SyncResult;
+};
+/**
+ * Listener function type for skill change events.
+ */
+type SkillChangeListener = (event: SkillChangeEvent) => void;
+/**
+ * Event emitter for skill changes.
+ *
+ * Used by SkillRegistry to notify subscribers of skill additions,
+ * removals, updates, and resets.
+ */
+export declare class SkillEmitter {
+    private listeners;
+    /**
+     * Register a listener for skill change events.
+     *
+     * @param listener - The listener function
+     * @returns Unsubscribe function
+     */
+    on(listener: SkillChangeListener): () => void;
+    /**
+     * Emit a skill change event to all listeners.
+     *
+     * @param event - The change event
+     */
+    emit(event: SkillChangeEvent): void;
+    /**
+     * Get the number of active listeners.
+     */
+    get listenerCount(): number;
+    /**
+     * Remove all listeners.
+     */
+    clear(): void;
+}
+export {};
+//# sourceMappingURL=skill.events.d.ts.map

package/skill/skill.events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill.events.d.ts","sourceRoot":"","sources":["../../src/skill/skill.events.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AAC7E,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,WAAW,GAAG,QAAQ,CAAC;AAEjG;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEpD;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;OAEG;IACH,IAAI,EAAE,eAAe,CAAC;IAEtB;;OAEG;IACH,WAAW,EAAE,gBAAgB,CAAC;IAE9B;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;OAEG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B;;OAEG;IACH,OAAO,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,QAAQ,EAAE,SAAS,UAAU,EAAE,CAAC;IAEhC;;;OAGG;IACH,gBAAgB,CAAC,EAAE,qBAAqB,CAAC;IAEzC;;;OAGG;IACH,UAAU,CAAC,EAAE,UAAU,CAAC;CACzB,CAAC;AAEF;;GAEG;AACH,KAAK,mBAAmB,GAAG,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;AAE7D;;;;;GAKG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,SAAS,CAAkC;IAEnD;;;;;OAKG;IACH,EAAE,CAAC,QAAQ,EAAE,mBAAmB,GAAG,MAAM,IAAI;IAK7C;;;;OAIG;IACH,IAAI,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI;IAMnC;;OAEG;IACH,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED;;OAEG;IACH,KAAK,IAAI,IAAI;CAGd"}

package/skill/skill.instance.d.ts

@@ -0,0 +1,92 @@
+import { EntryOwnerRef, SkillEntry, SkillRecord, SkillToolRef } from '../common';
+import { SkillContent } from '../common/interfaces';
+import ProviderRegistry from '../provider/provider.registry';
+import { Scope } from '../scope';
+/**
+ * Concrete implementation of a skill that can be loaded and searched.
+ *
+ * SkillInstance handles:
+ * - Loading instructions from inline strings, files, or URLs
+ * - Building full SkillContent for LLM consumption
+ * - Caching loaded instructions for performance
+ */
+export declare class SkillInstance extends SkillEntry {
+    /** The provider registry this skill is bound to */
+    private readonly providersRef;
+    /** The scope this skill operates in */
+    readonly scope: Scope;
+    /** Cached instructions (loaded lazily) */
+    private cachedInstructions?;
+    /** Cached skill content (built lazily) */
+    private cachedContent?;
+    /** Tags for search indexing */
+    private readonly tags;
+    /** Priority for search ranking */
+    private readonly priority;
+    /** Whether skill is hidden from discovery */
+    private readonly hidden;
+    /** Visibility mode for skill discovery */
+    private readonly skillVisibility;
+    constructor(record: SkillRecord, providers: ProviderRegistry, owner: EntryOwnerRef);
+    protected initialize(): Promise<void>;
+    /**
+     * Get a short description of the skill.
+     */
+    getDescription(): string;
+    /**
+     * Load the skill's instructions from the configured source.
+     * Results are cached after the first load.
+     */
+    loadInstructions(): Promise<string>;
+    /**
+     * Load the full skill content.
+     * Results are cached after the first load.
+     */
+    load(): Promise<SkillContent>;
+    /**
+     * Get tool references with normalized format.
+     */
+    getToolRefs(): SkillToolRef[];
+    /**
+     * Get tool names only.
+     */
+    getToolNames(): string[];
+    /**
+     * Get the skill's tags.
+     */
+    getTags(): string[];
+    /**
+     * Check if the skill is hidden from discovery.
+     */
+    isHidden(): boolean;
+    /**
+     * Get the skill's priority for search ranking.
+     */
+    getPriority(): number;
+    /**
+     * Get the provider registry.
+     */
+    get providers(): ProviderRegistry;
+    /**
+     * Clear cached content (useful for hot-reload scenarios).
+     */
+    clearCache(): void;
+    /**
+     * Create a SkillContent from metadata without async loading.
+     * Returns cached content if available, builds from inline instructions,
+     * or returns undefined if instructions require async loading.
+     *
+     * @returns SkillContent if available synchronously, undefined otherwise
+     */
+    getContentSync(): SkillContent | undefined;
+}
+/**
+ * Create a SkillInstance from a SkillRecord.
+ *
+ * @param record - The skill record
+ * @param providers - Provider registry
+ * @param owner - Owner reference
+ * @returns A new SkillInstance
+ */
+export declare function createSkillInstance(record: SkillRecord, providers: ProviderRegistry, owner: EntryOwnerRef): SkillInstance;
+//# sourceMappingURL=skill.instance.d.ts.map

package/skill/skill.instance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill.instance.d.ts","sourceRoot":"","sources":["../../src/skill/skill.instance.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,UAAU,EAAa,WAAW,EAAE,YAAY,EAAoB,MAAM,WAAW,CAAC;AAC9G,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEpD,OAAO,gBAAgB,MAAM,+BAA+B,CAAC;AAC7D,OAAO,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAcjC;;;;;;;GAOG;AACH,qBAAa,aAAc,SAAQ,UAAU;IAC3C,mDAAmD;IACnD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAmB;IAEhD,uCAAuC;IACvC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IAEtB,0CAA0C;IAC1C,OAAO,CAAC,kBAAkB,CAAC,CAAS;IAEpC,0CAA0C;IAC1C,OAAO,CAAC,aAAa,CAAC,CAAqB;IAE3C,+BAA+B;IAC/B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAW;IAEhC,kCAAkC;IAClC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAElC,6CAA6C;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;IAEjC,0CAA0C;IAC1C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;gBAEtC,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,gBAAgB,EAAE,KAAK,EAAE,aAAa;cAsBlE,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAO3C;;OAEG;IACM,cAAc,IAAI,MAAM;IAIjC;;;OAGG;IACY,gBAAgB,IAAI,OAAO,CAAC,MAAM,CAAC;IAmBlD;;;OAGG;IACY,IAAI,IAAI,OAAO,CAAC,YAAY,CAAC;IAoB5C;;OAEG;IACM,WAAW,IAAI,YAAY,EAAE;IAMtC;;OAEG;IACM,YAAY,IAAI,MAAM,EAAE;IAIjC;;OAEG;IACM,OAAO,IAAI,MAAM,EAAE;IAI5B;;OAEG;IACM,QAAQ,IAAI,OAAO;IAI5B;;OAEG;IACM,WAAW,IAAI,MAAM;IAI9B;;OAEG;IACH,IAAI,SAAS,IAAI,gBAAgB,CAEhC;IAED;;OAEG;IACH,UAAU,IAAI,IAAI;IAKlB;;;;;;OAMG;IACH,cAAc,IAAI,YAAY,GAAG,SAAS;CAa3C;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,WAAW,EACnB,SAAS,EAAE,gBAAgB,EAC3B,KAAK,EAAE,aAAa,GACnB,aAAa,CAEf"}