/**
 * SkillsManager — orchestrates the skill store, cached index, index-first
 * search (hydrating instructions only for matches), prompt-index rendering,
 * and the mutation gate.
 *
 * Read paths fail open (errors surface as empty results + a warn log);
 * write paths fail closed (errors reject the mutation).
 */
import type { SkillDefinition, SkillIndexItem, SkillMutationAction, SkillMutationResult, SkillSearchQuery, SkillsConfig } from "../types/index.js";
import { SkillSessionTracker } from "./skillSessionTracker.js";
export declare class SkillsManager {
    private readonly config;
    private readonly store;
    private cachedIndex;
    private cachedIndexAt;
    /** Serializes writes within this process — see requestMutation(). */
    private mutationQueue;
    /** Per-session activation state (pinned skills). */
    readonly sessions: SkillSessionTracker;
    constructor(config: SkillsConfig);
    /**
     * Cached index read, sorted by name. TTL 0 disables caching. Sorting
     * here (not per render) keeps every downstream listing byte-stable
     * regardless of store enumeration order.
     */
    getIndex(forceRefresh?: boolean): Promise<SkillIndexItem[]>;
    private invalidateIndex;
    /**
     * Index-first search: filter the cached index, hydrate only the matched
     * entries (max `limit`) with instructions. Cost: one cached index read +
     * N_matched store gets.
     */
    search(query: SkillSearchQuery): Promise<SkillDefinition[]>;
    /** Index entries only — no instructions. For discovery/listing. */
    list(scopeId?: string): Promise<SkillIndexItem[]>;
    /** Fetch one skill by id, falling back to name lookup. */
    get(idOrName: string): Promise<SkillDefinition | null>;
    /**
     * Render the system-prompt skills index for one call, or null when
     * nothing is visible. Never includes instructions.
     */
    buildPromptIndex(options?: {
        scopeId?: string;
        tags?: string[];
    }): Promise<string | null>;
    /**
     * Render the `<available_skills>` block for the use_skill tool
     * description ("tool" discovery mode), or null when nothing is visible.
     * Bounded by listingBudgetChars; entries are never dropped.
     */
    buildToolListing(options?: {
        scopeId?: string;
        tags?: string[];
    }): Promise<string | null>;
    /** Visible (active, scope- and tag-filtered) index entries for one call. */
    private visibleItems;
    /**
     * Read an auxiliary resource file bundled with a skill. Paths are
     * relative to the skill; traversal segments are rejected. Null when the
     * skill, the resource, or store resource support is absent.
     */
    getResource(idOrName: string, resourcePath: string): Promise<string | null>;
    /**
     * Whether skill create/update/delete is enabled on this instance. Gates the
     * LLM-facing `skill_*` tools (registration) and the server REST mutation
     * routes. Direct programmatic `requestMutation` calls are intentionally not
     * gated, so a host can still seed skills at startup.
     */
    get mutationsAllowed(): boolean;
    /**
     * Gate a proposed mutation through the host's onMutationRequest hook,
     * then apply it when approved. No hook configured means direct apply
     * (the tools themselves are already gated by allowMutations).
     */
    requestMutation(action: SkillMutationAction): Promise<SkillMutationResult>;
    private applyMutation;
    private assertNameAvailable;
}