@ai-matrx/agents 0.13.14 → 0.13.16

package/dist/index.d.cts

@@ -7,3 +7,165 @@ export { F as FollowRuntimeOperationOptions, a as FollowRuntimeOperationToEndOpt
 export { CreateMatrxTransportOptions, MATRX_AI_API_VERSION_DEFAULT, MatrxAiApiVersion, MatrxCallError, MatrxClientToolResult, MatrxPendingCallSummary, MatrxProtocolDowngrade, MatrxProtocolFallbackOptions, MatrxRequestInfo, MatrxToolResultsResponse, MatrxTransportDiagnostics, MatrxTransportTarget, OrganizationContextError, OrganizationContextErrorCode, OrganizationOperation, V2_COVERED_AI_PATH_TEMPLATES, applyAiApiVersion, applyOrganizationContextHeader, assertOrganizationMatchesOperation, assertQueryOrganizationMatchesContext, createMatrxTransport, createOrganizationOperation, fetchWithMatrxProtocolFallback, isCoveredAiPath, isV2Path, listConversationPendingToolCalls, listUserPendingToolCalls, normalizeMatrxError, requireOrganizationContext, submitAgentToolResults, toV1FallbackUrl, toV2Path } from './matrx/index.cjs';
 import '@ai-matrx/data';
 import '@ai-matrx/data/net';
+
+/**
+ * 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 greyed 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;
+    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 a run form shows for a variable: a media variable that fills a
+ * reference role is asked for BY that role ("Style reference"); every other
+ * variable keeps its formatted name.
+ */
+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, labelled 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, type AudioReferenceRole, IMAGE_REFERENCE_ROLES, IMAGE_ROLE_META, type ImageReferenceRole, type ImageRoleLimits, type ImageRoleMeta, type ImageRoleVerdict, type ReferenceRole, type RunInput, type RunInputGroup, type RunInputMediaKind, type RunInputVariable, VIDEO_IMAGE_ROLES, VIDEO_REFERENCE_ROLES, type VideoReferenceRole, deriveRunInputs, imageRoleVerdict, isControlVariable, isImageReferenceRole, isReferenceRole, namedReferenceVerdict, normalizeReferenceName, orderVariablesForForm, partitionControlVariables, readImageRoleLimits, referenceRoleCaption, roleTakesName, rolesFor, variableNameOfImageUrl, variableNameOfMediaUrl, variableRunHint, variableRunLabel };

package/dist/index.d.ts

@@ -7,3 +7,165 @@ export { F as FollowRuntimeOperationOptions, a as FollowRuntimeOperationToEndOpt
 export { CreateMatrxTransportOptions, MATRX_AI_API_VERSION_DEFAULT, MatrxAiApiVersion, MatrxCallError, MatrxClientToolResult, MatrxPendingCallSummary, MatrxProtocolDowngrade, MatrxProtocolFallbackOptions, MatrxRequestInfo, MatrxToolResultsResponse, MatrxTransportDiagnostics, MatrxTransportTarget, OrganizationContextError, OrganizationContextErrorCode, OrganizationOperation, V2_COVERED_AI_PATH_TEMPLATES, applyAiApiVersion, applyOrganizationContextHeader, assertOrganizationMatchesOperation, assertQueryOrganizationMatchesContext, createMatrxTransport, createOrganizationOperation, fetchWithMatrxProtocolFallback, isCoveredAiPath, isV2Path, listConversationPendingToolCalls, listUserPendingToolCalls, normalizeMatrxError, requireOrganizationContext, submitAgentToolResults, toV1FallbackUrl, toV2Path } from './matrx/index.js';
 import '@ai-matrx/data';
 import '@ai-matrx/data/net';
+
+/**
+ * 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 greyed 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;
+    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 a run form shows for a variable: a media variable that fills a
+ * reference role is asked for BY that role ("Style reference"); every other
+ * variable keeps its formatted name.
+ */
+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, labelled 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, type AudioReferenceRole, IMAGE_REFERENCE_ROLES, IMAGE_ROLE_META, type ImageReferenceRole, type ImageRoleLimits, type ImageRoleMeta, type ImageRoleVerdict, type ReferenceRole, type RunInput, type RunInputGroup, type RunInputMediaKind, type RunInputVariable, VIDEO_IMAGE_ROLES, VIDEO_REFERENCE_ROLES, type VideoReferenceRole, deriveRunInputs, imageRoleVerdict, isControlVariable, isImageReferenceRole, isReferenceRole, namedReferenceVerdict, normalizeReferenceName, orderVariablesForForm, partitionControlVariables, readImageRoleLimits, referenceRoleCaption, roleTakesName, rolesFor, variableNameOfImageUrl, variableNameOfMediaUrl, variableRunHint, variableRunLabel };

package/dist/index.js

@@ -1602,15 +1602,238 @@ function listUserPendingToolCalls(transport, options = {}) {
     }
   );
 }
+
+// variables/reference-roles.ts
+var IMAGE_REFERENCE_ROLES = [
+  "subject",
+  "character",
+  "style",
+  "mask",
+  "edit_target",
+  "composition_control"
+];
+var VIDEO_IMAGE_ROLES = [
+  "first_frame",
+  "last_frame",
+  "asset",
+  "style"
+];
+var VIDEO_REFERENCE_ROLES = ["extend", "restyle"];
+var AUDIO_REFERENCE_ROLES = ["lip_sync"];
+var ALL_IMAGE_ROLES = [
+  ...IMAGE_REFERENCE_ROLES,
+  ...VIDEO_IMAGE_ROLES
+];
+var IMAGE_ROLE_META = {
+  subject: {
+    label: "Subject",
+    ask: "Subject reference",
+    explanation: "Keeps this exact product or object recognisable: shape, materials, labels."
+  },
+  character: {
+    label: "Character",
+    ask: "Character reference",
+    explanation: "Keeps this person or character looking the same."
+  },
+  style: {
+    label: "Style",
+    ask: "Style reference",
+    explanation: "Borrows only the look (colours, lighting, medium), never the content."
+  },
+  mask: {
+    label: "Mask",
+    ask: "Mask",
+    explanation: "Marks the only area of the edited image that is allowed to change."
+  },
+  edit_target: {
+    label: "Edit this",
+    ask: "Image to edit",
+    explanation: "The image being edited; everything not asked for stays the same."
+  },
+  composition_control: {
+    label: "Composition",
+    ask: "Composition reference",
+    explanation: "Follows its layout, pose and geometry, not its appearance."
+  },
+  first_frame: {
+    label: "First frame",
+    ask: "First frame",
+    explanation: "The video starts on exactly this image."
+  },
+  last_frame: {
+    label: "Last frame",
+    ask: "Last frame",
+    explanation: "The video ends on exactly this image (needs a first frame)."
+  },
+  asset: {
+    label: "Asset",
+    ask: "Asset reference",
+    explanation: "Keeps this product, object or character recognisable throughout the clip."
+  },
+  extend: {
+    label: "Extend",
+    ask: "Video to extend",
+    explanation: "The new clip continues this video from its last frame."
+  },
+  restyle: {
+    label: "Restyle",
+    ask: "Reference video",
+    explanation: "Re-renders this video: same motion and timing, a new look."
+  },
+  lip_sync: {
+    label: "Lip sync",
+    ask: "Lip-sync audio",
+    explanation: "The speech the on-screen face mouths, word for word."
+  }
+};
+function rolesFor(blockKind, output) {
+  if (output === "image") return blockKind === "image" ? IMAGE_REFERENCE_ROLES : [];
+  if (blockKind === "image") return VIDEO_IMAGE_ROLES;
+  if (blockKind === "video") return VIDEO_REFERENCE_ROLES;
+  return AUDIO_REFERENCE_ROLES;
+}
+function roleTakesName(role) {
+  return role === "asset" || role === "style" || role === "restyle" || role === "extend";
+}
+function normalizeReferenceName(raw) {
+  const candidate = raw.trim().replace(/^@/, "");
+  if (!candidate) return null;
+  return /^[A-Za-z][A-Za-z0-9_-]{0,31}$/.test(candidate) ? candidate : null;
+}
+function isReferenceRole(value) {
+  return typeof value === "string" && value in IMAGE_ROLE_META;
+}
+function isImageReferenceRole(value) {
+  return typeof value === "string" && ALL_IMAGE_ROLES.includes(value);
+}
+function readLimitMap(source, accept, out) {
+  if (typeof source !== "object" || source === null || Array.isArray(source)) return;
+  for (const [key, value] of Object.entries(source)) {
+    if (accept(key) && typeof value === "number" && Number.isInteger(value) && value >= 0) {
+      out[key] = value;
+    }
+  }
+}
+function readImageRoleLimits(raw) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return {};
+  const record = raw;
+  const out = {};
+  readLimitMap(
+    record.image_reference_roles,
+    (k) => isImageReferenceRole(k) || k === "total",
+    out
+  );
+  readLimitMap(
+    record.video_reference_roles,
+    (k) => VIDEO_REFERENCE_ROLES.includes(k) || AUDIO_REFERENCE_ROLES.includes(k) || k === "named",
+    out
+  );
+  return out;
+}
+function imageRoleVerdict(role, limits, modelLabel, countOfRole = 1) {
+  const label = IMAGE_ROLE_META[role].label;
+  const noun = VIDEO_REFERENCE_ROLES.includes(role) ? "video" : role === "lip_sync" ? "audio clip" : ALL_IMAGE_ROLES.includes(role) && !IMAGE_REFERENCE_ROLES.includes(role) ? "image" : "reference image";
+  const allowed = limits[role] ?? 0;
+  if (allowed <= 0) {
+    return {
+      verdict: "refused",
+      reason: `${modelLabel} cannot take a ${label} ${noun}. Pick another role or another model.`
+    };
+  }
+  if (countOfRole > allowed) {
+    return {
+      verdict: "refused",
+      reason: `${modelLabel} takes at most ${allowed} ${label} ${noun}${allowed === 1 ? "" : "s"}; this message has ${countOfRole}.`
+    };
+  }
+  return { verdict: "ok" };
+}
+function namedReferenceVerdict(limits, modelLabel) {
+  return (limits.named ?? 0) > 0 ? { verdict: "ok" } : {
+    verdict: "refused",
+    reason: `${modelLabel} cannot take named references. Clear the name, or pick a model with named elements.`
+  };
+}
+function variableNameOfImageUrl(url) {
+  return variableNameOfMediaUrl(url);
+}
+function variableNameOfMediaUrl(url) {
+  if (typeof url !== "string") return null;
+  const match = /^\s*\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}\s*$/.exec(url);
+  return match?.[1] ?? null;
+}
+function referenceRoleCaption(role, name) {
+  const roleLabel = typeof role === "string" && role ? isReferenceRole(role) ? IMAGE_ROLE_META[role].ask : role : null;
+  const refName = typeof name === "string" ? normalizeReferenceName(name) : null;
+  if (!roleLabel && !refName) return null;
+  return [roleLabel, refName ? `@${refName}` : null].filter(Boolean).join(" \xB7 ");
+}
+
+// variables/run-inputs.ts
+var MEDIA_KINDS = ["image", "video", "audio", "document", "youtube"];
+function isControlVariable(def) {
+  return typeof def.control?.key === "string" && def.control.key.length > 0;
+}
+function partitionControlVariables(defs) {
+  const content = [];
+  const settings = [];
+  for (const d of defs) (isControlVariable(d) ? settings : content).push(d);
+  return { content, settings };
+}
+function orderVariablesForForm(defs) {
+  const { content, settings } = partitionControlVariables(defs);
+  if (settings.length === 0) return defs;
+  const ordered = [...content, ...settings];
+  return ordered.every((d, i) => d === defs[i]) ? defs : ordered;
+}
+function roleOf(variable) {
+  const type = variable.customComponent?.type;
+  const role = variable.customComponent?.imageRole;
+  const roled = type === "image" || type === "video" || type === "audio";
+  return roled && isReferenceRole(role) ? role : null;
+}
+function variableRunLabel(variable, formatName) {
+  const role = roleOf(variable);
+  return role ? IMAGE_ROLE_META[role].ask : formatName(variable.name);
+}
+function variableRunHint(variable) {
+  if (variable.helpText) return variable.helpText;
+  const role = roleOf(variable);
+  return role ? IMAGE_ROLE_META[role].explanation : void 0;
+}
+function deriveRunInputs(defs, formatName) {
+  return orderVariablesForForm([...defs ?? []]).map((variable) => {
+    const type = variable.customComponent?.type ?? "textarea";
+    const options = variable.customComponent?.options ?? void 0;
+    return {
+      name: variable.name,
+      label: variableRunLabel(variable, formatName),
+      hint: variableRunHint(variable),
+      group: isControlVariable(variable) ? "settings" : "content",
+      required: Boolean(variable.required),
+      component: type,
+      options: options && options.length > 0 ? options : void 0,
+      mediaKind: MEDIA_KINDS.includes(type) ? type : null,
+      role: roleOf(variable),
+      controlKey: isControlVariable(variable) ? variable.control?.key ?? null : null,
+      variable
+    };
+  });
+}
 export {
+  AUDIO_REFERENCE_ROLES,
   DEFAULT_MATRX_NDJSON_READ_AHEAD,
   DEFAULT_WORKFLOW_PROJECTION_LIMITS,
+  IMAGE_REFERENCE_ROLES,
+  IMAGE_ROLE_META,
   MATRX_AI_API_VERSION_DEFAULT,
   MatrxApiError,
   MatrxRunError,
   OrganizationContextError,
   TERMINAL_MATRX_RUNTIME_STATUSES,
   V2_COVERED_AI_PATH_TEMPLATES,
+  VIDEO_IMAGE_ROLES,
+  VIDEO_REFERENCE_ROLES,
   applyAiApiVersion,
   applyOrganizationContextHeader,
   assertOrganizationMatchesOperation,
@@ -1625,6 +1848,7 @@ export {
   createMatrxTransport,
   createOrganizationOperation,
   createWorkflowNodeProjection,
+  deriveRunInputs,
   extractMatrxErrorCode,
   extractMatrxErrorMessage,
   fetchWithMatrxProtocolFallback,
@@ -1632,31 +1856,47 @@ export {
   followRuntimeOperationToEnd,
   getRuntimeOperationStatus,
   getRuntimeOperationsByLink,
+  imageRoleVerdict,
+  isControlVariable,
   isCoveredAiPath,
+  isImageReferenceRole,
+  isReferenceRole,
   isV2Path,
   listConversationPendingToolCalls,
   listRuntimeOperationEvents,
   listUserPendingToolCalls,
   mintMatrxConversationId,
+  namedReferenceVerdict,
   newEphemeralConversationStart,
   newStoredConversationStart,
   normalizeMatrxError,
   normalizeMatrxStreamEnvelope,
+  normalizeReferenceName,
+  orderVariablesForForm,
   parseMatrxSseFrame,
+  partitionControlVariables,
   projectAgentEvent,
   projectAgentEvents,
   projectAgentResultForDisplay,
   projectWorkflowNodeEvent,
+  readImageRoleLimits,
   readMatrxNdjsonStream,
   readMatrxSseStream,
+  referenceRoleCaption,
   rejoinRuntimeOperation,
   requireOrganizationContext,
   resumeAgentConversation,
+  roleTakesName,
+  rolesFor,
   runAgentToCompletion,
   startAgentRun,
   startMandateRun,
   submitAgentToolResults,
   toV1FallbackUrl,
-  toV2Path
+  toV2Path,
+  variableNameOfImageUrl,
+  variableNameOfMediaUrl,
+  variableRunHint,
+  variableRunLabel
 };
 //# sourceMappingURL=index.js.map