import type { MessageAnnotations } from '../../protocol.js';
import type { MsgSchemaShape } from '../factory.js';
type Binding = {
    variant: string;
};
type Annotations = Record<string, MessageAnnotations>;
export type ListActionsHost = {
    getState(): unknown;
    getBindingDescriptors(): Binding[] | null;
    getMsgAnnotations(): Annotations | null;
    getMsgSchema(): MsgSchemaShape | null;
    getAgentAffordances(): ((state: unknown) => Array<{
        type: string;
        [k: string]: unknown;
    }>) | null;
};
/**
 * `dispatchMode` on each action is `'shared'` (human can also click via
 * a UI affordance) or `'agent-only'` (no UI binding — agent is the only
 * dispatcher). `'human-only'` variants are filtered out before this
 * point — they never reach the LLM.
 *
 * `source` distinguishes WHERE the affordance came from:
 *   - `'binding'` — a tagged event handler is currently mounted in a
 *     live scope (refcount > 0). Variants inside dead branches —
 *     `show({when: false})`, unmounted `branch()` cases, removed `each`
 *     items — auto-vanish from this set as their lifetimes dispose.
 *     This is the framework's "what can the user click right now"
 *     answer, and it's the default surface for the agent.
 *   - `'always-affordable'` — either the app's `agentAffordances(state)`
 *     hook listed the variant, or the variant carries the
 *     `@alwaysAffordable` JSDoc tag. Both are the explicit "agent can
 *     reach this even when no live UI binding maps to it" knob — bulk
 *     seed ops (`Matrix/AddAlternatives`) and similar agent-driven
 *     paths typically land here.
 *   - `'schema'` — variant is annotated `@agentOnly` (the canonical
 *     "no UI button maps to this; the agent is the only dispatcher")
 *     and isn't already covered above. The payload is schema-synthesized
 *     and the agent fills it in.
 *
 * `'shared'` variants WITHOUT a live binding, without
 * `agentAffordances` mention, and without `@alwaysAffordable` are
 * **deliberately hidden**. They're reachable through UI navigation —
 * the human user can't click them right now, and dispatching them
 * blindly would mutate state that drives `show()`/`branch()` gates,
 * popping hidden UI subtrees into view in places the user didn't
 * navigate to.
 */
export type ListActionsResult = {
    actions: Array<{
        variant: string;
        /**
         * Human-readable phrase from `@intent("…")`, or `null` when the
         * variant is unannotated. Mirror of LapActionsResponse.intent —
         * callers should treat `null` as a documentation gap and not as
         * "missing label, fall back to variant name".
         */
        intent: string | null;
        requiresConfirm: boolean;
        dispatchMode: 'shared' | 'agent-only';
        source: 'binding' | 'always-affordable' | 'schema';
        selectorHint: string | null;
        payloadHint: object | null;
        /**
         * Whether the action can be dispatched right now. Omitted (= `true`)
         * for reachable actions; `false` for a variant whose `@routeGated`
         * predicate is currently falsy — surfaced as unavailable rather than
         * hidden, so the agent knows it exists and what unblocks it.
         */
        available?: boolean;
        /** Why an `available: false` action can't be dispatched now (from the
         * `@routeGated` reason, or a generic fallback). */
        unavailableReason?: string | null;
        /** Cautionary text from `@warning` JSDoc, or null. */
        warning: string | null;
        /** Concrete examples from `@example` JSDoc, in source order. */
        examples: string[];
        /**
         * Effect kinds this variant emits, from `@emits("k1", "k2")`.
         * Empty when not annotated. Lets the agent know what side
         * effects fire — useful for batching ("100 dispatches × cloud-
         * save = bad") and for confirming destructive flows.
         */
        emits: string[];
        /**
         * Per-field guidance lifted from `@should("…")` JSDoc on payload
         * fields. Path is dot/bracket notation rooted at the payload
         * (e.g. `"cells"` for a top-level field, `"cells[].meta"` for an
         * array element's nested field). Useful when the field is typed
         * as `unknown` or as a polymorphic shape — the hint says "type
         * matches the criterion's kind: number for quantity, …" so the
         * agent doesn't have to guess from the bare schema.
         *
         * Empty when no field on this variant carries an `@should` hint.
         */
        fieldHints: Array<{
            path: string;
            hint: string;
        }>;
    }>;
};
export declare function handleListActions(host: ListActionsHost): ListActionsResult;
export {};
//# sourceMappingURL=list-actions.d.ts.map