export interface ActionSpec {
    /**
     * Action identifier. Emitted verbatim as the `id` field on parsed action
     * events so bindings can dispatch with a simple switch. Keep identifiers
     * in snake_case.
     */
    readonly id: string;
    /**
     * Optional override for the bracketed cue shown to the model. Defaults to
     * the action's snake_case id with underscores converted to spaces.
     */
    readonly cue?: string;
    /** Short description of the action for prompts and tooling. */
    readonly description?: string;
    /**
     * Optional short usage hint shown to the model in prompts. Helps nudge when
     * the action feels natural without hardcoding character-specific logic.
     */
    readonly usageHint?: string;
}
export type ActionSchema = readonly ActionSpec[];
export interface ActionCue {
    /** The exact label that appears between square brackets. */
    readonly label: string;
    /** The runtime action id the cue dispatches to. */
    readonly id: string;
}
export interface ActionCueSummary {
    readonly label: string;
    readonly id: string;
    readonly description?: string;
    readonly usageHint?: string;
}
export declare class ActionSchemaError extends Error {
    constructor(message: string);
}
/**
 * Validates that an action schema is well-formed. Returns an error message on
 * the first problem detected; returns null on success.
 */
export declare function validateActionSchema(schema: ActionSchema): string | null;
export declare function assertValidActionSchema(schema: ActionSchema): void;
/**
 * Expands an action schema into the flat list of cues the model is allowed
 * to emit. Ordering is deterministic (schema declaration order) so prompt-
 * cache keys remain stable across rebuilds.
 */
export declare function expandActionCues(schema: ActionSchema): readonly ActionCue[];
/**
 * Returns one canonical prompt-facing cue per runtime action.
 */
export declare function summarizeActionCues(schema: ActionSchema): readonly ActionCueSummary[];
/**
 * Renders the schema as a flat, comma-separated list of bracketed cues for
 * inclusion in the system prompt. The prose complements the GBNF grammar
 * by enumerating the exact vocabulary — the grammar constrains syntax, the
 * prose lists the allowed cues.
 */
export declare function renderActionCueList(schema: ActionSchema): string;