export { projectAgentResultForDisplay } from './presentation/result.cjs';
export { AgentProjectionEvent, AgentProjectionOperation, AgentProjectionRenderBlock, AgentProjectionStatus, AgentProjectionTool, AgentRequestProjection, createAgentRequestProjection, projectAgentEvent, projectAgentEvents } from './projection/request.cjs';
export { DEFAULT_WORKFLOW_PROJECTION_LIMITS, WorkflowNodeProjection, WorkflowNodeStreamEvent, WorkflowProjectionLimits, WorkflowRenderBlockIssue, WorkflowRenderBlockIssueCode, WorkflowRenderFrameSet, createWorkflowNodeProjection, projectWorkflowNodeEvent } from './projection/workflow.cjs';

/**
 * Media reference roles — the builder's side of the one vocabulary.
 *
 * Image generation reads an image as subject / character / style / mask /
 * edit target / composition. Video generation reads an image as first frame /
 * last frame / asset / style, a video as extend / restyle, and an audio clip as
 * lip sync; an asset/style image or a reference video may carry a `name` the
 * prompt addresses as `@name` (server: `matrx_ai/media/video_reference_roles.py`).
 *
 * A reference image in an image-generation request says what it controls.
 * The role rides on the image block itself (`role` on the image part); absent
 * = a plain image the model sees. The server owns the wire mapping and the
 * refusal gate (aidream `matrx_ai/media/image_reference_roles.py`); this module
 * mirrors its vocabulary and limits so the builder can tell the truth BEFORE a
 * run: a role the selected model cannot take is shown grayed with the reason.
 *
 * Limits come from the catalog: the routing offering's
 * `capabilities_override.image_reference_roles` (`{role: max, total: n}`).
 * Law: `common-docs/systems/agents/typed-messages/FEATURE.md` (Image generation).
 * Home: `@ai-matrx/agents` (moved from matrx-frontend `features/agents/image-roles/roles.ts`).
 */
/** The roles an IMAGE-generating model reads an image as (vocabulary order). */
declare const IMAGE_REFERENCE_ROLES: readonly ["subject", "character", "style", "mask", "edit_target", "composition_control"];
/** The roles a VIDEO-generating model reads an image as (`style` is shared). */
declare const VIDEO_IMAGE_ROLES: readonly ["first_frame", "last_frame", "asset", "style"];
/** Roles on a video part beside a video prompt. */
declare const VIDEO_REFERENCE_ROLES: readonly ["extend", "restyle"];
/** Roles on an audio part beside a video prompt. */
declare const AUDIO_REFERENCE_ROLES: readonly ["lip_sync"];
type ImageReferenceRole = (typeof IMAGE_REFERENCE_ROLES)[number] | (typeof VIDEO_IMAGE_ROLES)[number];
type VideoReferenceRole = (typeof VIDEO_REFERENCE_ROLES)[number];
type AudioReferenceRole = (typeof AUDIO_REFERENCE_ROLES)[number];
/** Any role a media part can carry — one union, one metadata table. */
type ReferenceRole = ImageReferenceRole | VideoReferenceRole | AudioReferenceRole;
interface ImageRoleMeta {
    /** Segment label — plain words, never the wire token. */
    label: string;
    /** What the run form asks for when a variable fills this role. */
    ask: string;
    /** One line: what the model does with an image in this role. */
    explanation: string;
}
declare const IMAGE_ROLE_META: Record<ReferenceRole, ImageRoleMeta>;
/** Which roles a block of this kind offers for this output modality. */
declare function rolesFor(blockKind: "image" | "video" | "audio", output: "image" | "video"): readonly ReferenceRole[];
/** Roles whose reference may carry a name the prompt addresses as `@name`. */
declare function roleTakesName(role: ReferenceRole | null | undefined): boolean;
/** `@name` rule shared with the server (media/video_reference_roles.py). */
declare function normalizeReferenceName(raw: string): string | null;
declare function isReferenceRole(value: unknown): value is ReferenceRole;
declare function isImageReferenceRole(value: unknown): value is ImageReferenceRole;
/**
 * `{role: max, total: n, named: n}` — image roles from
 * `capabilities_override.image_reference_roles`, video/audio roles and the
 * named-reference cap from `capabilities_override.video_reference_roles`.
 * Empty = the model takes no roled reference.
 */
type ImageRoleLimits = Partial<Record<ReferenceRole | "total" | "named", number>>;
/** Read the offering's role limits (image + video maps) defensively. */
declare function readImageRoleLimits(raw: unknown): ImageRoleLimits;
type ImageRoleVerdict = {
    verdict: "ok";
} | {
    verdict: "refused";
    reason: string;
};
/**
 * Can this model take an image in this role? The reason is a sentence a
 * person can act on; it names the role and the model, like the server's
 * refusal does.
 */
declare function imageRoleVerdict(role: ReferenceRole, limits: ImageRoleLimits, modelLabel: string, countOfRole?: number): ImageRoleVerdict;
/** Can this model take a named (`@name`) reference at all? */
declare function namedReferenceVerdict(limits: ImageRoleLimits, modelLabel: string): ImageRoleVerdict;
/** The variable an image block is filled by, when its url is exactly `{{name}}`. */
declare function variableNameOfImageUrl(url: unknown): string | null;
/** The variable any media block (image, video, audio) is filled by. */
declare function variableNameOfMediaUrl(url: unknown): string | null;
/**
 * The one-line caption a REDISPLAYED reference shows — "Subject reference",
 * "Style reference · @brand". Shared by the attachment chip and the inline
 * image/video block so a role set in the builder is never lost on reload. An
 * unrecognised role string is shown as-is (honest) rather than dropped.
 */
declare function referenceRoleCaption(role: unknown, name: unknown): string | null;

/**
 * Run inputs — the ONE derivation from an agent's variable definitions to the
 * inputs a run surface asks for.
 *
 * Every surface that runs an agent (the run page and chat composer, Agent
 * Battle's shared request, a Workflow Studio Step node) asks the same
 * questions in the same order: content inputs first, then bound model
 * controls in a "Settings" group; a media variable that fills a reference role
 * is asked for BY that role ("Style reference"); a control keeps the catalog
 * component the builder stamped on it. A speech-script variable is an ordinary
 * content variable — its `{{name}}` lives in a turn's text.
 *
 * Canonical doc: common-docs/systems/agents/typed-messages/FEATURE.md.
 */

/** The minimum variable shape this derivation reads (a superset is fine). */
interface RunInputVariable {
    name: string;
    /** What the person called it ("Normal Text") — `name` is the `{{normal_text}}` key. */
    label?: string | null;
    defaultValue?: unknown;
    helpText?: string | null;
    required?: boolean | null;
    customComponent?: {
        type?: string | null;
        options?: readonly string[] | null;
        imageRole?: unknown;
        min?: number | null;
        max?: number | null;
        step?: number | null;
        toggleValues?: readonly [string, string] | readonly string[] | null;
    } | null;
    control?: {
        key?: string | null;
    } | null;
}
type RunInputGroup = "content" | "settings";
type RunInputMediaKind = "image" | "video" | "audio" | "document" | "youtube";
interface RunInput<V extends RunInputVariable = RunInputVariable> {
    name: string;
    /** What the form asks: the role's ask for a roled media input, else the formatted name. */
    label: string;
    /** The variable's help text, else the role's one-line explanation. */
    hint: string | undefined;
    group: RunInputGroup;
    required: boolean;
    /** The component type the builder chose (`textarea` when none). */
    component: string;
    options: readonly string[] | undefined;
    /** Set when this input takes a file / media reference. */
    mediaKind: RunInputMediaKind | null;
    /** The reference role a media input fills (subject, style, first_frame, …). */
    role: ReferenceRole | null;
    /** The model control this input IS (aspect_ratio, quality, voice, …). */
    controlKey: string | null;
    variable: V;
}
declare function isControlVariable(def: RunInputVariable): boolean;
/** Content inputs first, bound controls after — stable within each group. */
declare function partitionControlVariables<T extends RunInputVariable>(defs: readonly T[]): {
    content: T[];
    settings: T[];
};
/** The order every variable form renders in. Returns the same array when already ordered. */
declare function orderVariablesForForm<T extends RunInputVariable>(defs: T[]): T[];
/**
 * The label every screen shows for a variable: the person's own label
 * ("Normal Text"), else — for a media variable that fills a reference role —
 * the role's ask ("Style reference"), else the key through THE humanizer
 * (`@ai-matrx/kit/text-case` `humanizeIdentifier`). Never the raw key.
 */
declare function variableRunLabel(variable: RunInputVariable, formatName?: (name: string) => string): string;
/** The hint under / beside a variable: its own help text, else the role's line. */
declare function variableRunHint(variable: RunInputVariable): string | undefined;
/** Derive the ordered, grouped, labeled run inputs for an agent's variables. */
declare function deriveRunInputs<V extends RunInputVariable>(defs: readonly V[] | null | undefined, formatName?: (name: string) => string): RunInput<V>[];

export { AUDIO_REFERENCE_ROLES, IMAGE_REFERENCE_ROLES, IMAGE_ROLE_META, VIDEO_IMAGE_ROLES, VIDEO_REFERENCE_ROLES, deriveRunInputs, imageRoleVerdict, isControlVariable, isImageReferenceRole, isReferenceRole, namedReferenceVerdict, normalizeReferenceName, orderVariablesForForm, partitionControlVariables, readImageRoleLimits, referenceRoleCaption, roleTakesName, rolesFor, variableNameOfImageUrl, variableNameOfMediaUrl, variableRunHint, variableRunLabel };
export type { AudioReferenceRole, ImageReferenceRole, ImageRoleLimits, ImageRoleMeta, ImageRoleVerdict, ReferenceRole, RunInput, RunInputGroup, RunInputMediaKind, RunInputVariable, VideoReferenceRole };