@frontmcp/sdk 0.7.2 → 0.8.0

package/skill/skill.registry.d.ts

@@ -0,0 +1,309 @@
+import { Token } from '@frontmcp/di';
+import { EntryLineage, EntryOwnerRef, SkillEntry, SkillType, SkillToolValidationMode } from '../common';
+import { SkillChangeEvent } from './skill.events';
+import { SkillInstance } from './skill.instance';
+import { SkillRecord } from '../common/records';
+import ProviderRegistry from '../provider/provider.registry';
+import { RegistryAbstract, RegistryBuildMapResult } from '../regsitry';
+import { Scope } from '../scope';
+import { SkillSearchOptions, SkillSearchResult, SkillLoadResult, SkillListOptions, SkillListResult } from './skill-storage.interface';
+import type { ExternalSkillProviderBase } from './providers/external-skill.provider';
+import type { SyncResult } from './sync/sync-state.interface';
+import { ServerCapabilities } from '@modelcontextprotocol/sdk/types.js';
+import { SkillValidationReport } from './errors/skill-validation.error';
+/**
+ * Indexed skill for efficient lookup.
+ */
+export interface IndexedSkill {
+    token: Token;
+    instance: SkillInstance;
+    baseName: string;
+    lineage: EntryLineage;
+    ownerKey: string;
+    qualifiedName: string;
+    qualifiedId: string;
+    source: SkillRegistry;
+}
+/**
+ * Options for configuring SkillRegistry behavior.
+ */
+export interface SkillRegistryOptions {
+    /**
+     * Default validation mode for all skills in this registry.
+     * Can be overridden per-skill via SkillMetadata.toolValidation.
+     *
+     * @default 'warn'
+     */
+    defaultToolValidation?: SkillToolValidationMode;
+    /**
+     * Whether to fail the entire registry initialization if any skill fails validation.
+     * Only applies when toolValidation is 'strict'.
+     *
+     * @default false
+     */
+    failOnInvalidSkills?: boolean;
+}
+/**
+ * Options for getting skills from the registry.
+ */
+export interface GetSkillsOptions {
+    /**
+     * Whether to include hidden skills.
+     * @default false
+     */
+    includeHidden?: boolean;
+    /**
+     * Filter by visibility context.
+     * - 'mcp': Only skills visible via MCP (visibility = 'mcp' or 'both')
+     * - 'http': Only skills visible via HTTP (visibility = 'http' or 'both')
+     * - 'all': All skills regardless of visibility (default)
+     */
+    visibility?: 'mcp' | 'http' | 'all';
+}
+/**
+ * Interface for SkillRegistry consumers.
+ */
+export interface SkillRegistryInterface {
+    owner: EntryOwnerRef;
+    /**
+     * Get all skills in the registry.
+     * @param options - Options for filtering skills (or boolean for backwards compatibility)
+     */
+    getSkills(options?: boolean | GetSkillsOptions): SkillEntry[];
+    /**
+     * Find a skill by name.
+     * @param name - The skill name
+     */
+    findByName(name: string): SkillEntry | undefined;
+    /**
+     * Find a skill by qualified name (includes owner prefix).
+     * @param qualifiedName - The qualified name (e.g., "my-app:review-pr")
+     */
+    findByQualifiedName(qualifiedName: string): SkillEntry | undefined;
+    /**
+     * Search for skills matching a query.
+     * @param query - Search query string
+     * @param options - Search options
+     */
+    search(query: string, options?: SkillSearchOptions): Promise<SkillSearchResult[]>;
+    /**
+     * Load a skill by ID.
+     * @param skillId - The skill identifier
+     */
+    loadSkill(skillId: string): Promise<SkillLoadResult | undefined>;
+    /**
+     * List skills with pagination.
+     * @param options - List options
+     */
+    listSkills(options?: SkillListOptions): Promise<SkillListResult>;
+    /**
+     * Check if any skills exist.
+     */
+    hasAny(): boolean;
+    /**
+     * Get total skill count.
+     * @param options - Count options
+     */
+    count(options?: {
+        tags?: string[];
+        includeHidden?: boolean;
+    }): Promise<number>;
+    /**
+     * Subscribe to skill change events.
+     * @param opts - Subscription options
+     * @param cb - Callback function
+     */
+    subscribe(opts: {
+        immediate?: boolean;
+        filter?: (skill: SkillEntry) => boolean;
+    }, cb: (event: SkillChangeEvent) => void): () => void;
+    /**
+     * Get MCP capabilities for skills.
+     */
+    getCapabilities(): Partial<ServerCapabilities>;
+    /**
+     * Validate all skills against the current tool registry.
+     * Should be called after all tools (including from plugins/adapters) are registered.
+     *
+     * @returns Validation report for all skills
+     * @throws SkillValidationError if failOnInvalidSkills is true and any skill fails
+     */
+    validateAllTools(): Promise<SkillValidationReport>;
+    /**
+     * Sync local skills to external storage.
+     * Only available when an external provider in persistent mode is set.
+     *
+     * @returns Sync result with added/updated/unchanged/removed counts, or null if no external provider
+     */
+    syncToExternal(): Promise<SyncResult | null>;
+    /**
+     * Get the external provider if one is configured.
+     */
+    getExternalProvider(): ExternalSkillProviderBase | undefined;
+    /**
+     * Check if the registry has an external provider.
+     */
+    hasExternalProvider(): boolean;
+}
+/**
+ * Registry for managing skills.
+ *
+ * The SkillRegistry is the main facade for:
+ * - Managing local skills (registered via @Skill decorator or skill() helper)
+ * - Searching skills using TF-IDF
+ * - Loading skill content (including fetching from URLs)
+ * - Tracking skill changes
+ */
+export default class SkillRegistry extends RegistryAbstract<SkillInstance, SkillRecord, SkillType[]> implements SkillRegistryInterface {
+    /** Owner of this registry */
+    owner: EntryOwnerRef;
+    /** Local skills indexed for lookup */
+    private localRows;
+    /** Adopted skills from child registries */
+    private adopted;
+    /** Children registries */
+    private children;
+    /** O(1) indexes */
+    private byQualifiedId;
+    private byName;
+    private byOwnerAndName;
+    /** Version and emitter for change tracking */
+    private version;
+    private emitter;
+    /** Internal storage provider for search */
+    private storageProvider;
+    /** External skill provider for sync operations */
+    private externalProvider?;
+    /** Tool validator for checking tool availability */
+    private toolValidator?;
+    /** The scope this registry operates in */
+    readonly scope: Scope;
+    /** Registry-level options for validation behavior */
+    private readonly options;
+    constructor(providers: ProviderRegistry, list: SkillType[], owner: EntryOwnerRef, options?: SkillRegistryOptions);
+    protected buildMap(list: SkillType[]): RegistryBuildMapResult<SkillRecord>;
+    protected buildGraph(): void;
+    protected initialize(): Promise<void>;
+    /**
+     * Adopt skills from a child registry.
+     */
+    adoptFromChild(child: SkillRegistry, _childOwner: EntryOwnerRef): Promise<void>;
+    /**
+     * Get all skills in the registry.
+     * @param options - Options for filtering skills (or boolean for backwards compatibility)
+     */
+    getSkills(options?: boolean | GetSkillsOptions): SkillEntry[];
+    /**
+     * Get inline (local) skills only.
+     */
+    getInlineSkills(): SkillInstance[];
+    /**
+     * Find a skill by name.
+     */
+    findByName(name: string): SkillEntry | undefined;
+    /**
+     * Find a skill by qualified name.
+     */
+    findByQualifiedName(qualifiedName: string): SkillEntry | undefined;
+    /**
+     * Search for skills matching a query.
+     */
+    search(query: string, options?: SkillSearchOptions): Promise<SkillSearchResult[]>;
+    /**
+     * Load a skill by ID or name.
+     * Supports looking up by:
+     * - metadata.id (the unique identifier)
+     * - metadata.name (the display name)
+     * - qualified name (owner:name format)
+     */
+    loadSkill(skillId: string): Promise<SkillLoadResult | undefined>;
+    /**
+     * List skills with pagination.
+     */
+    listSkills(options?: SkillListOptions): Promise<SkillListResult>;
+    /**
+     * Check if any skills exist.
+     */
+    hasAny(): boolean;
+    /**
+     * Get total skill count.
+     */
+    count(options?: {
+        tags?: string[];
+        includeHidden?: boolean;
+    }): Promise<number>;
+    /**
+     * Subscribe to skill change events.
+     */
+    subscribe(opts: {
+        immediate?: boolean;
+        filter?: (skill: SkillEntry) => boolean;
+    }, cb: (event: SkillChangeEvent) => void): () => void;
+    /**
+     * Get MCP capabilities for skills.
+     */
+    getCapabilities(): Partial<ServerCapabilities>;
+    /**
+     * Validate all skills against the current tool registry.
+     * Should be called after all tools (including from plugins/adapters) are registered.
+     *
+     * This method:
+     * 1. Checks each skill's tool references against the tool registry
+     * 2. Respects per-skill and registry-level validation modes
+     * 3. Emits a 'validated' event with results
+     * 4. Optionally throws if failOnInvalidSkills is enabled
+     *
+     * @returns Validation report for all skills
+     * @throws SkillValidationError if failOnInvalidSkills is true and any skill fails
+     */
+    validateAllTools(): Promise<SkillValidationReport>;
+    private listAllIndexed;
+    private listAllInstances;
+    private reindex;
+    private makeRow;
+    private relineage;
+    private bump;
+    /**
+     * Set an external storage provider for skills.
+     *
+     * In read-only mode:
+     * - Search/list/load operations will query the external provider
+     *
+     * In persistent mode:
+     * - Local skills will be synced to external storage on syncToExternal()
+     * - Search/list/load operations still use local storage
+     *
+     * @param provider - External provider instance extending ExternalSkillProviderBase
+     */
+    setExternalProvider(provider: ExternalSkillProviderBase): void;
+    /**
+     * Get the external provider if one is configured.
+     */
+    getExternalProvider(): ExternalSkillProviderBase | undefined;
+    /**
+     * Check if the registry has an external provider.
+     */
+    hasExternalProvider(): boolean;
+    /**
+     * Sync local skills to external storage.
+     *
+     * This method:
+     * 1. Collects all local skill content
+     * 2. Calls syncSkills on the external provider
+     * 3. Returns the sync result with changes detected
+     *
+     * Only available when an external provider in persistent mode is configured.
+     *
+     * @returns Sync result or null if no external provider or in read-only mode
+     *
+     * @example
+     * ```typescript
+     * const result = await registry.syncToExternal();
+     * if (result) {
+     *   console.log(`Synced: ${result.added.length} added, ${result.updated.length} updated`);
+     * }
+     * ```
+     */
+    syncToExternal(): Promise<SyncResult | null>;
+}
+//# sourceMappingURL=skill.registry.d.ts.map

package/skill/skill.registry.d.ts.map

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

package/skill/skill.utils.d.ts

@@ -0,0 +1,90 @@
+import { Token } from '@frontmcp/di';
+import { SkillMetadata, SkillRecord, SkillType, SkillInstructionSource } from '../common';
+import { SkillContent } from '../common/interfaces';
+/**
+ * Collect skill metadata from a decorated class.
+ *
+ * @param cls - The class to collect metadata from
+ * @returns The skill metadata
+ */
+export declare function collectSkillMetadata(cls: SkillType): SkillMetadata;
+/**
+ * Normalize any skill input to a SkillRecord.
+ *
+ * Handles:
+ * - Class with @Skill decorator → SkillClassTokenRecord
+ * - SkillValueRecord (from skill() helper) → passthrough
+ * - SkillFileRecord → passthrough
+ *
+ * @param item - The skill input to normalize
+ * @returns A normalized SkillRecord
+ * @throws Error if the input is invalid
+ */
+export declare function normalizeSkill(item: unknown): SkillRecord;
+/**
+ * Check if an object is a SkillRecord.
+ */
+export declare function isSkillRecord(item: unknown): item is SkillRecord;
+/**
+ * Get dependency tokens from a skill record for DI graph validation.
+ *
+ * @param rec - The skill record
+ * @returns Array of dependency tokens
+ */
+export declare function skillDiscoveryDeps(rec: SkillRecord): Token[];
+/**
+ * Load instructions from a skill instruction source.
+ *
+ * @param source - The instruction source (inline, file, or URL)
+ * @param basePath - Base path for resolving relative file paths
+ * @returns The loaded instructions as a string
+ */
+export declare function loadInstructions(source: SkillInstructionSource, basePath?: string): Promise<string>;
+/**
+ * Build SkillContent from metadata and resolved instructions.
+ *
+ * @param metadata - The skill metadata
+ * @param instructions - The resolved instructions string
+ * @returns The full skill content
+ */
+export declare function buildSkillContent(metadata: SkillMetadata, instructions: string): SkillContent;
+/**
+ * Format a skill for LLM consumption.
+ *
+ * Creates a markdown-formatted string with the skill instructions,
+ * tool information, and any warnings about missing tools.
+ *
+ * @param skill - The loaded skill content
+ * @param availableTools - List of available tools
+ * @param missingTools - List of missing tools
+ * @returns Formatted skill content as markdown
+ */
+export declare function formatSkillForLLM(skill: SkillContent, availableTools: string[], missingTools: string[]): string;
+/**
+ * Generate next steps guidance after loading skills.
+ *
+ * @param skills - Array of loaded skills with their tool availability
+ * @param allToolsAvailable - Whether all tools across all skills are available
+ * @returns Human-readable guidance string
+ */
+export declare function generateNextSteps(skills: Array<{
+    name: string;
+    isComplete: boolean;
+    tools: Array<{
+        name: string;
+        available: boolean;
+    }>;
+}>, allToolsAvailable: boolean): string;
+/**
+ * Generate search guidance based on results.
+ *
+ * @param skills - Array of search results with executability info
+ * @param query - The original search query
+ * @returns Human-readable guidance string
+ */
+export declare function generateSearchGuidance(skills: Array<{
+    name: string;
+    score: number;
+    canExecute: boolean;
+}>, query: string): string;
+//# sourceMappingURL=skill.utils.d.ts.map

package/skill/skill.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill.utils.d.ts","sourceRoot":"","sources":["../../src/skill/skill.utils.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,EAA2C,MAAM,cAAc,CAAC;AAC9E,OAAO,EACL,aAAa,EAEb,WAAW,EAIX,SAAS,EAIT,sBAAsB,EAEvB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAGpD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,SAAS,GAAG,aAAa,CAWlE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,WAAW,CA4BzD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,IAAI,WAAW,CAwBhE;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,WAAW,GAAG,KAAK,EAAE,CAS5D;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,sBAAsB,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAuBzG;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,GAAG,YAAY,CAU7F;AAmCD;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,EAAE,EAAE,YAAY,EAAE,MAAM,EAAE,GAAG,MAAM,CA6D/G;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,OAAO,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC,EACxG,iBAAiB,EAAE,OAAO,GACzB,MAAM,CA4BR;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,OAAO,CAAA;CAAE,CAAC,EACnE,KAAK,EAAE,MAAM,GACZ,MAAM,CAyBR"}

package/skill/sync/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Skill Sync Module
+ *
+ * Provides utilities for synchronizing local skills with external vector databases.
+ * Supports two modes:
+ * - Read-only: Pull skills from external source (no local persistence)
+ * - Persistent: SHA-based change detection, sync local skills to external store
+ *
+ * @module skill/sync
+ */
+export { computeSkillHash, computeSkillHashComponents, areSkillsEqual } from './skill-hash';
+export type { SkillHashComponents } from './skill-hash';
+export { createEmptySyncState, serializeSyncState, deserializeSyncState } from './sync-state.interface';
+export type { SkillSyncStatus, SkillSyncEntry, SkillSyncState, SerializedSkillSyncState, SkillSyncStateStore, SyncResult, } from './sync-state.interface';
+export { MemorySyncStateStore } from './memory-sync-state.store';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/skill/sync/index.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAGH,OAAO,EAAE,gBAAgB,EAAE,0BAA0B,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC5F,YAAY,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAGxD,OAAO,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AACxG,YAAY,EACV,eAAe,EACf,cAAc,EACd,cAAc,EACd,wBAAwB,EACxB,mBAAmB,EACnB,UAAU,GACX,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC"}

package/skill/sync/memory-sync-state.store.d.ts

@@ -0,0 +1,49 @@
+import type { SkillSyncState, SkillSyncStateStore } from './sync-state.interface';
+/**
+ * In-memory implementation of SkillSyncStateStore.
+ *
+ * Suitable for:
+ * - Development and testing
+ * - Single-instance deployments where persistence isn't required
+ * - Stateless sync operations (re-sync on each startup)
+ *
+ * Note: State is lost when the process exits.
+ *
+ * @example
+ * ```typescript
+ * const store = new MemorySyncStateStore();
+ *
+ * // Save state
+ * await store.save({ version: 1, lastFullSync: Date.now(), entries: new Map() });
+ *
+ * // Load state
+ * const state = await store.load();
+ * ```
+ */
+export declare class MemorySyncStateStore implements SkillSyncStateStore {
+    private state;
+    /**
+     * Load the sync state from memory.
+     * @returns The stored state or null if not set
+     */
+    load(): Promise<SkillSyncState | null>;
+    /**
+     * Save the sync state to memory.
+     * @param state - The state to store
+     */
+    save(state: SkillSyncState): Promise<void>;
+    /**
+     * Clear the sync state from memory.
+     */
+    clear(): Promise<void>;
+    /**
+     * Check if any state is stored.
+     * Useful for determining if a full sync is needed.
+     */
+    hasState(): boolean;
+    /**
+     * Get the number of tracked skills.
+     */
+    getEntryCount(): number;
+}
+//# sourceMappingURL=memory-sync-state.store.d.ts.map

package/skill/sync/memory-sync-state.store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-sync-state.store.d.ts","sourceRoot":"","sources":["../../../src/skill/sync/memory-sync-state.store.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAElF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,oBAAqB,YAAW,mBAAmB;IAC9D,OAAO,CAAC,KAAK,CAA+B;IAE5C;;;OAGG;IACG,IAAI,IAAI,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAa5C;;;OAGG;IACG,IAAI,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAShD;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5B;;;OAGG;IACH,QAAQ,IAAI,OAAO;IAInB;;OAEG;IACH,aAAa,IAAI,MAAM;CAGxB"}

package/skill/sync/skill-hash.d.ts

@@ -0,0 +1,65 @@
+import type { SkillContent } from '../../common/interfaces';
+/**
+ * Components of a skill hash, useful for debugging and partial updates.
+ */
+export interface SkillHashComponents {
+    /**
+     * SHA-256 hash of the instructions only.
+     */
+    instructionsHash: string;
+    /**
+     * SHA-256 hash of the tools array (sorted by name).
+     */
+    toolsHash: string;
+    /**
+     * SHA-256 hash of metadata (id, name, description).
+     */
+    metadataHash: string;
+    /**
+     * Combined hash of all components.
+     */
+    combinedHash: string;
+}
+/**
+ * Compute a deterministic SHA-256 hash of a skill's content.
+ * Used for change detection during sync operations.
+ *
+ * @param skill - The skill content to hash
+ * @returns Hexadecimal SHA-256 hash string
+ *
+ * @example
+ * ```typescript
+ * const hash1 = computeSkillHash(skill);
+ * // ... modify skill ...
+ * const hash2 = computeSkillHash(skill);
+ * if (hash1 !== hash2) {
+ *   // Skill content changed, need to sync
+ * }
+ * ```
+ */
+export declare function computeSkillHash(skill: SkillContent): string;
+/**
+ * Compute detailed hash components for a skill.
+ * Useful for understanding what changed between versions.
+ *
+ * @param skill - The skill content to hash
+ * @returns Individual hash components and combined hash
+ *
+ * @example
+ * ```typescript
+ * const components = computeSkillHashComponents(skill);
+ * if (components.instructionsHash !== prevComponents.instructionsHash) {
+ *   console.log('Instructions changed');
+ * }
+ * ```
+ */
+export declare function computeSkillHashComponents(skill: SkillContent): SkillHashComponents;
+/**
+ * Compare two skills for content equality using their hashes.
+ *
+ * @param skill1 - First skill
+ * @param skill2 - Second skill
+ * @returns True if skills have identical content
+ */
+export declare function areSkillsEqual(skill1: SkillContent, skill2: SkillContent): boolean;
+//# sourceMappingURL=skill-hash.d.ts.map

package/skill/sync/skill-hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-hash.d.ts","sourceRoot":"","sources":["../../../src/skill/sync/skill-hash.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAE5D;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;OAEG;IACH,gBAAgB,EAAE,MAAM,CAAC;IAEzB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,YAAY,EAAE,MAAM,CAAC;CACtB;AAiCD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAG5D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,YAAY,GAAG,mBAAmB,CAmBnF;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAElF"}

package/skill/sync/sync-state.interface.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Status of a skill's synchronization with external storage.
+ */
+export type SkillSyncStatus = 'synced' | 'pending' | 'failed';
+/**
+ * Entry tracking the sync state of a single skill.
+ */
+export interface SkillSyncEntry {
+    /**
+     * The skill's unique identifier.
+     */
+    skillId: string;
+    /**
+     * SHA-256 hash of the skill content at last sync.
+     */
+    hash: string;
+    /**
+     * Timestamp of the last successful sync (epoch ms).
+     */
+    lastSyncedAt: number;
+    /**
+     * Current sync status.
+     */
+    status: SkillSyncStatus;
+    /**
+     * Error message if status is 'failed'.
+     */
+    error?: string;
+    /**
+     * External storage ID if different from skillId.
+     * Used when external storage assigns its own identifiers.
+     */
+    externalId?: string;
+}
+/**
+ * Full sync state tracking all skills.
+ */
+export interface SkillSyncState {
+    /**
+     * Version of the sync state format.
+     * Allows for future migrations.
+     */
+    version: number;
+    /**
+     * Timestamp of the last complete sync operation (epoch ms).
+     */
+    lastFullSync: number;
+    /**
+     * Map of skill ID to sync entry.
+     */
+    entries: Map<string, SkillSyncEntry>;
+}
+/**
+ * Serialized form of SkillSyncState for persistence.
+ */
+export interface SerializedSkillSyncState {
+    version: number;
+    lastFullSync: number;
+    entries: Array<[string, SkillSyncEntry]>;
+}
+/**
+ * Interface for persisting skill sync state.
+ * Implementations can use memory, file system, or databases.
+ */
+export interface SkillSyncStateStore {
+    /**
+     * Load the sync state from storage.
+     * @returns The sync state or null if not found
+     */
+    load(): Promise<SkillSyncState | null>;
+    /**
+     * Save the sync state to storage.
+     * @param state - The state to persist
+     */
+    save(state: SkillSyncState): Promise<void>;
+    /**
+     * Clear the sync state from storage.
+     */
+    clear(): Promise<void>;
+}
+/**
+ * Result of a sync operation.
+ */
+export interface SyncResult {
+    /**
+     * IDs of newly added skills.
+     */
+    added: string[];
+    /**
+     * IDs of skills that were updated due to content changes.
+     */
+    updated: string[];
+    /**
+     * IDs of skills that were unchanged (hash matched).
+     */
+    unchanged: string[];
+    /**
+     * IDs of skills that were removed from external storage.
+     */
+    removed: string[];
+    /**
+     * IDs of skills that failed to sync with their errors.
+     */
+    failed: Array<{
+        skillId: string;
+        error: string;
+    }>;
+    /**
+     * Total duration of the sync operation in milliseconds.
+     */
+    durationMs: number;
+}
+/**
+ * Create an empty sync state with defaults.
+ */
+export declare function createEmptySyncState(): SkillSyncState;
+/**
+ * Serialize sync state for persistence.
+ */
+export declare function serializeSyncState(state: SkillSyncState): SerializedSkillSyncState;
+/**
+ * Deserialize sync state from persistence.
+ */
+export declare function deserializeSyncState(data: SerializedSkillSyncState): SkillSyncState;
+//# sourceMappingURL=sync-state.interface.d.ts.map