@frontmcp/sdk 0.7.2 → 0.8.1

package/skill/providers/external-skill.provider.d.ts

@@ -0,0 +1,240 @@
+import type { FrontMcpLogger } from '../../common';
+import type { SkillContent } from '../../common/interfaces';
+import type { SkillMetadata } from '../../common/metadata';
+import type { SkillStorageProvider, SkillSearchOptions, SkillSearchResult, SkillLoadResult, SkillListOptions, SkillListResult } from '../skill-storage.interface';
+import type { SkillSyncState, SkillSyncStateStore, SyncResult } from '../sync/sync-state.interface';
+/**
+ * Operating mode for external skill providers.
+ *
+ * - 'read-only': Skills are fetched from external storage, no local writes
+ * - 'persistent': Local skills are synced to external storage with SHA-based change detection
+ */
+export type ExternalSkillMode = 'read-only' | 'persistent';
+/**
+ * Options for creating an external skill provider.
+ */
+export interface ExternalSkillProviderOptions {
+    /**
+     * Operating mode for the provider.
+     * @see ExternalSkillMode
+     */
+    mode: ExternalSkillMode;
+    /**
+     * Store for persisting sync state.
+     * Required for persistent mode, optional for read-only.
+     */
+    syncStateStore?: SkillSyncStateStore;
+    /**
+     * Logger instance for diagnostic output.
+     */
+    logger?: FrontMcpLogger;
+    /**
+     * Default number of search results.
+     * @default 10
+     */
+    defaultTopK?: number;
+    /**
+     * Default minimum similarity threshold.
+     * @default 0.1
+     */
+    defaultMinScore?: number;
+}
+/**
+ * Options for skill search in external storage.
+ */
+export interface ExternalSkillSearchOptions extends SkillSearchOptions {
+    /**
+     * Include metadata like embeddings in results.
+     */
+    includeMetadata?: boolean;
+}
+/**
+ * Options for listing skills from external storage.
+ */
+export interface ExternalSkillListOptions extends SkillListOptions {
+    /**
+     * Cursor for pagination (provider-specific).
+     */
+    cursor?: string;
+}
+/**
+ * Abstract base class for external skill storage providers.
+ *
+ * Provides two operating modes:
+ *
+ * **Read-Only Mode:**
+ * - All search/load operations fetch from external storage
+ * - No local persistence or modification
+ * - Use case: Pull skills from a shared skill repository
+ *
+ * **Persistent Mode:**
+ * - Local skills are synced to external storage
+ * - SHA-based change detection minimizes writes
+ * - Tracks sync state to detect added/updated/removed skills
+ * - Use case: Publish local skills to external vector DB
+ *
+ * @example Implementing a REST API provider
+ * ```typescript
+ * class RestSkillProvider extends ExternalSkillProviderBase {
+ *   constructor(private apiUrl: string, options: ExternalSkillProviderOptions) {
+ *     super(options);
+ *   }
+ *
+ *   protected async fetchSkill(skillId: string): Promise<SkillContent | null> {
+ *     const response = await fetch(`${this.apiUrl}/skills/${skillId}`);
+ *     if (!response.ok) return null;
+ *     return response.json();
+ *   }
+ *
+ *   // ... implement other abstract methods
+ * }
+ * ```
+ */
+export declare abstract class ExternalSkillProviderBase implements SkillStorageProvider {
+    readonly type: "external";
+    /** Operating mode */
+    protected readonly mode: ExternalSkillMode;
+    /** Current sync state (loaded from store on init) */
+    protected syncState: SkillSyncState | null;
+    /** Store for persisting sync state */
+    protected readonly syncStateStore?: SkillSyncStateStore;
+    /** Logger instance */
+    protected readonly logger?: FrontMcpLogger;
+    /** Default search result count */
+    protected readonly defaultTopK: number;
+    /** Default minimum similarity threshold */
+    protected readonly defaultMinScore: number;
+    /** Whether the provider has been initialized */
+    private initialized;
+    constructor(options: ExternalSkillProviderOptions);
+    /**
+     * Fetch a single skill from external storage.
+     *
+     * @param skillId - The skill identifier
+     * @returns The skill content or null if not found
+     */
+    protected abstract fetchSkill(skillId: string): Promise<SkillContent | null>;
+    /**
+     * Fetch multiple skills from external storage.
+     *
+     * @param options - List options (pagination, filtering)
+     * @returns Array of skill content
+     */
+    protected abstract fetchSkills(options?: ExternalSkillListOptions): Promise<SkillContent[]>;
+    /**
+     * Search for skills in external storage.
+     *
+     * @param query - Search query string
+     * @param options - Search options
+     * @returns Array of search results with scores
+     */
+    protected abstract searchExternal(query: string, options?: ExternalSkillSearchOptions): Promise<SkillSearchResult[]>;
+    /**
+     * Add or update a skill in external storage.
+     *
+     * @param skill - The skill content to upsert
+     */
+    protected abstract upsertSkill(skill: SkillContent): Promise<void>;
+    /**
+     * Delete a skill from external storage.
+     *
+     * @param skillId - The skill identifier to delete
+     */
+    protected abstract deleteSkill(skillId: string): Promise<void>;
+    /**
+     * Get the total count of skills in external storage.
+     *
+     * @param options - Filter options
+     */
+    protected abstract countExternal(options?: {
+        tags?: string[];
+        includeHidden?: boolean;
+    }): Promise<number>;
+    /**
+     * Check if a skill exists in external storage.
+     *
+     * @param skillId - The skill identifier
+     */
+    protected abstract existsExternal(skillId: string): Promise<boolean>;
+    /**
+     * Initialize the provider.
+     * Loads sync state for persistent mode.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Search for skills.
+     * Delegates to the abstract searchExternal method.
+     */
+    search(query: string, options?: SkillSearchOptions): Promise<SkillSearchResult[]>;
+    /**
+     * Load a skill by ID.
+     * Fetches from external storage and constructs a SkillLoadResult.
+     */
+    load(skillId: string): Promise<SkillLoadResult | null>;
+    /**
+     * List skills with pagination.
+     */
+    list(options?: SkillListOptions): Promise<SkillListResult>;
+    /**
+     * Check if a skill exists.
+     */
+    exists(skillId: string): Promise<boolean>;
+    /**
+     * Count skills.
+     */
+    count(options?: {
+        tags?: string[];
+        includeHidden?: boolean;
+    }): Promise<number>;
+    /**
+     * Dispose of resources.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Sync local skills to external storage.
+     *
+     * This method:
+     * 1. Loads previous sync state
+     * 2. Computes SHA-256 hash for each local skill
+     * 3. Compares hashes to detect changes
+     * 4. Upserts new/changed skills
+     * 5. Deletes skills no longer present locally
+     * 6. Saves updated sync state
+     *
+     * @param localSkills - Array of local skill content to sync
+     * @returns Sync result with added/updated/unchanged/removed counts
+     * @throws Error if called in read-only mode
+     *
+     * @example
+     * ```typescript
+     * const result = await provider.syncSkills(localSkills);
+     * console.log(`Synced: ${result.added.length} added, ${result.updated.length} updated`);
+     * ```
+     */
+    syncSkills(localSkills: SkillContent[]): Promise<SyncResult>;
+    /**
+     * Get the current sync state.
+     * Returns null if in read-only mode or never synced.
+     * Returns a deep copy to prevent external mutation.
+     */
+    getSyncState(): SkillSyncState | null;
+    /**
+     * Clear the sync state.
+     * Forces a full re-sync on next syncSkills call.
+     */
+    clearSyncState(): Promise<void>;
+    /**
+     * Check if the provider is operating in read-only mode.
+     */
+    isReadOnly(): boolean;
+    /**
+     * Check if the provider is operating in persistent mode.
+     */
+    isPersistent(): boolean;
+    /**
+     * Convert SkillContent to SkillMetadata.
+     * Override in subclasses if additional metadata is available.
+     */
+    protected skillToMetadata(skill: SkillContent): SkillMetadata;
+}
+//# sourceMappingURL=external-skill.provider.d.ts.map

package/skill/providers/external-skill.provider.d.ts.map

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

package/skill/providers/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Skill Storage Providers
+ *
+ * Implementations of SkillStorageProvider for different backends.
+ *
+ * @module skill/providers
+ */
+export { MemorySkillProvider } from './memory-skill.provider';
+export type { MemorySkillProviderOptions } from './memory-skill.provider';
+export { ExternalSkillProviderBase } from './external-skill.provider';
+export type { ExternalSkillMode, ExternalSkillProviderOptions, ExternalSkillSearchOptions, ExternalSkillListOptions, } from './external-skill.provider';
+//# sourceMappingURL=index.d.ts.map

package/skill/providers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/skill/providers/index.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AAGH,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,YAAY,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAC;AAG1E,OAAO,EAAE,yBAAyB,EAAE,MAAM,2BAA2B,CAAC;AACtE,YAAY,EACV,iBAAiB,EACjB,4BAA4B,EAC5B,0BAA0B,EAC1B,wBAAwB,GACzB,MAAM,2BAA2B,CAAC"}

package/skill/providers/memory-skill.provider.d.ts

@@ -0,0 +1,97 @@
+import { SkillContent } from '../../common/interfaces';
+import { SkillToolValidator } from '../skill-validator';
+import { SkillStorageProviderType, SkillSearchOptions, SkillSearchResult, SkillLoadResult, SkillListOptions, SkillListResult, MutableSkillStorageProvider } from '../skill-storage.interface';
+/**
+ * Configuration options for MemorySkillProvider.
+ */
+export interface MemorySkillProviderOptions {
+    /**
+     * Default number of search results.
+     * @default 10
+     */
+    defaultTopK?: number;
+    /**
+     * Default minimum similarity threshold.
+     * @default 0.1
+     */
+    defaultMinScore?: number;
+    /**
+     * Optional tool validator for enriching results.
+     */
+    toolValidator?: SkillToolValidator;
+}
+/**
+ * In-memory skill storage provider using TF-IDF for search.
+ *
+ * This is the default provider used when no external storage is configured.
+ * It stores skills in memory and uses TF-IDF vectorization for similarity search.
+ */
+export declare class MemorySkillProvider implements MutableSkillStorageProvider {
+    readonly type: SkillStorageProviderType;
+    private vectorDB;
+    private skills;
+    private defaultTopK;
+    private defaultMinScore;
+    private toolValidator?;
+    private initialized;
+    constructor(options?: MemorySkillProviderOptions);
+    /**
+     * Set the tool validator after construction.
+     * Useful when the validator isn't available at construction time.
+     */
+    setToolValidator(validator: SkillToolValidator): void;
+    initialize(): Promise<void>;
+    search(query: string, options?: SkillSearchOptions): Promise<SkillSearchResult[]>;
+    load(skillId: string): Promise<SkillLoadResult | null>;
+    list(options?: SkillListOptions): Promise<SkillListResult>;
+    exists(skillId: string): Promise<boolean>;
+    count(options?: {
+        tags?: string[];
+        includeHidden?: boolean;
+    }): Promise<number>;
+    add(skill: SkillContent): Promise<void>;
+    update(skillId: string, skill: SkillContent): Promise<void>;
+    remove(skillId: string): Promise<void>;
+    clear(): Promise<void>;
+    dispose(): Promise<void>;
+    /**
+     * Bulk add skills (more efficient than adding one by one).
+     */
+    addMany(skills: SkillContent[]): Promise<void>;
+    /**
+     * Index a single skill in the vector database.
+     */
+    private indexSkill;
+    /**
+     * Build searchable text for TF-IDF indexing.
+     * Uses term weighting to improve relevance:
+     * - Description: 3x weight (most important for matching)
+     * - Tags: 2x weight
+     * - Tools: 1x weight
+     * - Name: 1x weight
+     */
+    private buildSearchableText;
+    /**
+     * Convert SkillContent to SkillMetadata.
+     * This is needed because SkillContent doesn't store the original metadata format.
+     */
+    private skillToMetadata;
+    /**
+     * Get tags from a skill (stored in metadata but not in SkillContent directly).
+     * We store them in a custom property for now.
+     */
+    private getSkillTags;
+    /**
+     * Check if a skill is hidden from discovery.
+     */
+    private isHidden;
+    /**
+     * Get priority of a skill.
+     */
+    private getPriority;
+    /**
+     * Get visibility of a skill.
+     */
+    private getVisibility;
+}
+//# sourceMappingURL=memory-skill.provider.d.ts.map

package/skill/providers/memory-skill.provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-skill.provider.d.ts","sourceRoot":"","sources":["../../../src/skill/providers/memory-skill.provider.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAEvD,OAAO,EAAE,kBAAkB,EAAwB,MAAM,oBAAoB,CAAC;AAC9E,OAAO,EACL,wBAAwB,EACxB,kBAAkB,EAClB,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,2BAA2B,EAC5B,MAAM,4BAA4B,CAAC;AAmGpC;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;OAEG;IACH,aAAa,CAAC,EAAE,kBAAkB,CAAC;CACpC;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,YAAW,2BAA2B;IACrE,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAY;IAEnD,OAAO,CAAC,QAAQ,CAAuC;IACvD,OAAO,CAAC,MAAM,CAAwC;IACtD,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,eAAe,CAAS;IAChC,OAAO,CAAC,aAAa,CAAC,CAAqB;IAC3C,OAAO,CAAC,WAAW,CAAS;gBAEhB,OAAO,GAAE,0BAA+B;IAWpD;;;OAGG;IACH,gBAAgB,CAAC,SAAS,EAAE,kBAAkB,GAAG,IAAI;IAI/C,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAgFrF,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IA+BtD,IAAI,CAAC,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC;IAgD9D,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIzC,KAAK,CAAC,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,aAAa,CAAC,EAAE,OAAO,CAAA;KAAO,GAAG,OAAO,CAAC,MAAM,CAAC;IAwBlF,GAAG,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAKvC,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAc3D,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOtC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAM9B;;OAEG;IACG,OAAO,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBpD;;OAEG;IACH,OAAO,CAAC,UAAU;IAelB;;;;;;;OAOG;IACH,OAAO,CAAC,mBAAmB;IA0D3B;;;OAGG;IACH,OAAO,CAAC,eAAe;IAiCvB;;;OAGG;IACH,OAAO,CAAC,YAAY;IAMpB;;OAEG;IACH,OAAO,CAAC,QAAQ;IAIhB;;OAEG;IACH,OAAO,CAAC,WAAW;IAInB;;OAEG;IACH,OAAO,CAAC,aAAa;CAGtB"}

package/skill/session/index.d.ts

@@ -0,0 +1,4 @@
+export * from './skill-session.types';
+export * from './skill-session.manager';
+export * from './skill-session-store.interface';
+//# sourceMappingURL=index.d.ts.map

package/skill/session/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/skill/session/index.ts"],"names":[],"mappings":"AAEA,cAAc,uBAAuB,CAAC;AACtC,cAAc,yBAAyB,CAAC;AACxC,cAAc,iCAAiC,CAAC"}

package/skill/session/skill-session-store.interface.d.ts

@@ -0,0 +1,79 @@
+import type { SkillSessionState } from './skill-session.types';
+/**
+ * Interface for skill session storage.
+ * Implementations can store session state in memory, Redis, etc.
+ */
+export interface SkillSessionStore {
+    /**
+     * Save or update a session state.
+     */
+    save(session: SkillSessionState): Promise<void>;
+    /**
+     * Get a session state by ID.
+     * Returns null if session doesn't exist.
+     */
+    get(sessionId: string): Promise<SkillSessionState | null>;
+    /**
+     * Update specific fields of a session.
+     */
+    update(sessionId: string, updates: Partial<SkillSessionState>): Promise<void>;
+    /**
+     * Delete a session.
+     */
+    delete(sessionId: string): Promise<void>;
+    /**
+     * List active sessions (sessions with an active skill).
+     */
+    listActive(options?: {
+        limit?: number;
+    }): Promise<SkillSessionState[]>;
+    /**
+     * Clean up expired sessions.
+     * @param maxAge - Maximum age in milliseconds
+     */
+    cleanup(maxAge: number): Promise<number>;
+    /**
+     * Store type identifier.
+     */
+    readonly type: 'memory' | 'redis' | 'custom';
+}
+/**
+ * In-memory implementation of SkillSessionStore.
+ * Suitable for single-instance deployments or testing.
+ */
+export declare class MemorySkillSessionStore implements SkillSessionStore {
+    readonly type: "memory";
+    private sessions;
+    /**
+     * Deep-clone the activeSkills Map and its nested Sets.
+     */
+    private cloneActiveSkills;
+    save(session: SkillSessionState): Promise<void>;
+    get(sessionId: string): Promise<SkillSessionState | null>;
+    update(sessionId: string, updates: Partial<SkillSessionState>): Promise<void>;
+    delete(sessionId: string): Promise<void>;
+    listActive(options?: {
+        limit?: number;
+    }): Promise<SkillSessionState[]>;
+    cleanup(maxAge: number): Promise<number>;
+    /**
+     * Clear all sessions. Useful for testing.
+     */
+    clear(): void;
+    /**
+     * Get the number of stored sessions.
+     */
+    size(): number;
+}
+/**
+ * Factory function to create a skill session store.
+ */
+export declare function createSkillSessionStore(options?: {
+    type?: 'memory' | 'redis';
+    redis?: {
+        host?: string;
+        port?: number;
+        keyPrefix?: string;
+    };
+}): SkillSessionStore;
+//# sourceMappingURL=skill-session-store.interface.d.ts.map

package/skill/session/skill-session-store.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-session-store.interface.d.ts","sourceRoot":"","sources":["../../../src/skill/session/skill-session-store.interface.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE/D;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,IAAI,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEhD;;;OAGG;IACH,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;IAE1D;;OAEG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9E;;OAEG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzC;;OAEG;IACH,UAAU,CAAC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAAC;IAEvE;;;OAGG;IACH,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEzC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;CAC9C;AAED;;;GAGG;AACH,qBAAa,uBAAwB,YAAW,iBAAiB;IAC/D,QAAQ,CAAC,IAAI,EAAG,QAAQ,CAAU;IAClC,OAAO,CAAC,QAAQ,CAAwC;IAExD;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAcnB,IAAI,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAY/C,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAezD,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,iBAAiB,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAyB7E,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxC,UAAU,CAAC,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAqBtE,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAe9C;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,IAAI,IAAI,MAAM;CAGf;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,CAAC,EAAE;IAChD,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;IAC1B,KAAK,CAAC,EAAE;QACN,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;CACH,GAAG,iBAAiB,CAgBpB"}

package/skill/session/skill-session.manager.d.ts

@@ -0,0 +1,137 @@
+import { EventEmitter } from 'events';
+import type { FrontMcpLogger } from '../../common';
+import type { SkillContent } from '../../common/interfaces';
+import type { SkillLoadResult } from '../skill-storage.interface';
+import { SkillSessionState, SkillSessionOptions, SkillActivationResult, ToolAuthorizationResult, SkillSecurityPolicy, SkillPolicyMode } from './skill-session.types';
+import type { SkillSessionStore } from './skill-session-store.interface';
+/**
+ * Manages skill session state and tool authorization.
+ *
+ * Uses AsyncLocalStorage to track the active skill session per request context.
+ * This ensures that tool authorization checks are isolated per MCP session.
+ *
+ * @example
+ * ```typescript
+ * const manager = new SkillSessionManager({ defaultPolicyMode: 'strict' });
+ *
+ * // When loading a skill
+ * const result = manager.activateSkill('review-pr', skillContent, loadResult);
+ *
+ * // When calling a tool
+ * const authResult = manager.checkToolAuthorization('github_get_pr');
+ * if (!authResult.allowed) {
+ *   throw new ToolNotAllowedError(authResult);
+ * }
+ *
+ * // When done with the skill
+ * manager.deactivateSkill();
+ * ```
+ */
+export declare class SkillSessionManager extends EventEmitter {
+    private readonly storage;
+    private readonly options;
+    private readonly logger?;
+    private readonly store?;
+    constructor(options?: SkillSessionOptions, logger?: FrontMcpLogger, store?: SkillSessionStore);
+    /**
+     * Run a function within a skill session context.
+     * The session state will be available via getActiveSession() within the callback.
+     */
+    runWithSession<T>(sessionId: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Get the current session state.
+     * Returns undefined if not running within a session context.
+     */
+    getActiveSession(): SkillSessionState | undefined;
+    /**
+     * Check if there's an active skill in the current session.
+     */
+    hasActiveSkill(): boolean;
+    /**
+     * Get the number of active skills in the current session.
+     */
+    getActiveSkillCount(): number;
+    /**
+     * Get IDs of all active skills in the current session.
+     */
+    getActiveSkillIds(): string[];
+    /**
+     * Get names of all active skills in the current session.
+     */
+    getActiveSkillNames(): string[];
+    /**
+     * Activate a skill in the current session.
+     * This adds the skill to the active skills and expands the tool allowlist.
+     * Multiple skills can be active simultaneously, with their tool allowlists combined.
+     *
+     * @param skillId - The skill identifier
+     * @param skillContent - The loaded skill content
+     * @param loadResult - The skill load result with tool availability info
+     * @param policy - Optional security policy override
+     * @returns Activation result with session state and tool availability
+     */
+    activateSkill(skillId: string, skillContent: SkillContent, loadResult: SkillLoadResult, policy?: SkillSecurityPolicy): SkillActivationResult;
+    /**
+     * Rebuild the combined allowedTools and requiredTools sets from all active skills.
+     */
+    private rebuildCombinedToolSets;
+    /**
+     * Deactivate a skill or all skills in the current session.
+     *
+     * @param skillId - Optional skill ID to deactivate. If not provided, deactivates all skills.
+     */
+    deactivateSkill(skillId?: string): void;
+    /**
+     * Clear all session state (called when no skills remain active).
+     */
+    private clearSessionState;
+    /**
+     * Check if a tool is authorized in the current session.
+     * Returns detailed authorization result including reason.
+     *
+     * @param toolName - The name of the tool to check
+     * @returns Authorization result
+     */
+    checkToolAuthorization(toolName: string): ToolAuthorizationResult;
+    /**
+     * Check if a tool is allowed without checking policy mode.
+     * Simpler check for quick validation.
+     */
+    isToolAllowed(toolName: string): boolean;
+    /**
+     * Get the list of tools allowed by the current skill.
+     */
+    getToolAllowlist(): string[];
+    /**
+     * Dynamically approve a tool for the current session.
+     * Used when policyMode is 'approval' and user approves a tool.
+     */
+    approveToolForSession(toolName: string): void;
+    /**
+     * Deny a tool for the current session.
+     */
+    denyToolForSession(toolName: string): void;
+    /**
+     * Record a tool call in the session.
+     * Updates the tool call count for rate limiting.
+     */
+    recordToolCall(toolName: string): void;
+    /**
+     * Get the current policy mode.
+     */
+    getPolicyMode(): string;
+    /**
+     * Set the policy mode for the current session.
+     * Only applies if there's an active skill.
+     */
+    setPolicyMode(mode: SkillPolicyMode): void;
+    /**
+     * Emit a session event.
+     */
+    private emitSessionEvent;
+    /**
+     * Persist session state to store if available.
+     */
+    private persistSession;
+}
+//# sourceMappingURL=skill-session.manager.d.ts.map

package/skill/session/skill-session.manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-session.manager.d.ts","sourceRoot":"","sources":["../../../src/skill/session/skill-session.manager.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EACrB,uBAAuB,EAEvB,mBAAmB,EACnB,eAAe,EAGhB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,mBAAoB,SAAQ,YAAY;IACnD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8C;IACtE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgC;IACxD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAiB;IACzC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAoB;gBAE/B,OAAO,CAAC,EAAE,mBAAmB,EAAE,MAAM,CAAC,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,iBAAiB;IAa7F;;;OAGG;IACG,cAAc,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAkB5E;;;OAGG;IACH,gBAAgB,IAAI,iBAAiB,GAAG,SAAS;IAIjD;;OAEG;IACH,cAAc,IAAI,OAAO;IAMzB;;OAEG;IACH,mBAAmB,IAAI,MAAM;IAK7B;;OAEG;IACH,iBAAiB,IAAI,MAAM,EAAE;IAM7B;;OAEG;IACH,mBAAmB,IAAI,MAAM,EAAE;IAM/B;;;;;;;;;;OAUG;IACH,aAAa,CACX,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,YAAY,EAC1B,UAAU,EAAE,eAAe,EAC3B,MAAM,CAAC,EAAE,mBAAmB,GAC3B,qBAAqB;IA+ExB;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAc/B;;;;OAIG;IACH,eAAe,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAyFvC;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAYzB;;;;;;OAMG;IACH,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,uBAAuB;IAiIjE;;;OAGG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAIxC;;OAEG;IACH,gBAAgB,IAAI,MAAM,EAAE;IAM5B;;;OAGG;IACH,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAyB7C;;OAEG;IACH,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAyB1C;;;OAGG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAoBtC;;OAEG;IACH,aAAa,IAAI,MAAM;IAKvB;;;OAGG;IACH,aAAa,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI;IAe1C;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAKxB;;OAEG;YACW,cAAc;CAS7B"}