import type { SkillMeta } from '../types/skills.js';
/**
 * One row of the skill catalog as the model sees it: a name and the one-line description
 * that tells it when to reach for the skill. Bodies and resources are deliberately absent —
 * those live behind `load_skill` / `read_skill_resource` (progressive disclosure).
 */
export interface SkillCatalogEntry {
    name: string;
    description: string;
}
/**
 * The change between two catalog snapshots, computed by name. A description-only change on
 * an existing skill is neither added nor removed: the catalog announces availability
 * (present / absent), not wording edits, and rebaselining wording into the prompt is the
 * compaction step's job, not the announcement's.
 */
export interface SkillCatalogDelta {
    added: SkillCatalogEntry[];
    removed: string[];
}
/**
 * `systemNotes.ts` tag for the catalog-delta announcement, shared by `ctx.ts` (writes it on
 * add/remove) and `Runtime.ts` (retires it at compaction once the delta it announced is
 * folded into a rebaselined `skillPrompt`) so the two call sites cannot drift onto different
 * strings and silently stop recognising each other's note.
 */
export declare const SKILL_CATALOG_NOTE_TAG = "skill-catalog";
/** Project skill metadata (baseline or live) down to the catalog shape the model sees. */
export declare function skillCatalogEntries(metas: readonly Pick<SkillMeta, 'name' | 'description'>[]): SkillCatalogEntry[];
/**
 * Set-difference two catalogs by name. Both halves are sorted by name so the result is
 * deterministic regardless of insertion order — the announcement text and any snapshot
 * comparison must be stable.
 */
export declare function diffSkillCatalog(previous: readonly SkillCatalogEntry[], next: readonly SkillCatalogEntry[]): SkillCatalogDelta;
/**
 * Render a catalog delta as the single context block delivered to the model when the live
 * roster changes. Names what became available (with descriptions) and what was withdrawn,
 * then restates the full current roster — the roster is the durable truth; the delta only
 * draws the model's attention to the change.
 *
 * Delivered as a runtime system note (see `systemNotes.ts`), never by editing `skillPrompt`,
 * because rewriting the serialized tools/prompt block discards the provider's prompt cache
 * for the whole conversation.
 */
export declare function renderSkillCatalogDelta(delta: SkillCatalogDelta, roster: readonly string[]): string;
/**
 * Fixed instruction header for the in-prompt catalog. Kept verbatim so the frozen baseline
 * (`skillPrompt`) is byte-identical to what `SkillsCapability` always produced — the only
 * thing that varies is the trailing skill list.
 */
export declare const SKILL_CATALOG_PROMPT_HEADER: string;
/**
 * Render the `## Available skills` prompt section for a catalog. `undefined` for an empty
 * catalog so the caller emits no section at all — matching the contract that an agent with
 * no skills gets no catalog block.
 *
 * Used both at wire time (the frozen `skillPrompt` baseline, from `SkillsCapability`) and at
 * compaction (rebaselining the prompt from the current live roster, the one place the cached
 * prompt is already being rewritten).
 */
export declare function renderSkillCatalogPrompt(entries: readonly SkillCatalogEntry[]): string | undefined;