@ai-matrx/agents 0.13.15 → 0.14.0

package/dist/index.cjs

@@ -20,14 +20,19 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // index.ts
 var index_exports = {};
 __export(index_exports, {
+  AUDIO_REFERENCE_ROLES: () => AUDIO_REFERENCE_ROLES,
   DEFAULT_MATRX_NDJSON_READ_AHEAD: () => DEFAULT_MATRX_NDJSON_READ_AHEAD,
   DEFAULT_WORKFLOW_PROJECTION_LIMITS: () => DEFAULT_WORKFLOW_PROJECTION_LIMITS,
+  IMAGE_REFERENCE_ROLES: () => IMAGE_REFERENCE_ROLES,
+  IMAGE_ROLE_META: () => IMAGE_ROLE_META,
   MATRX_AI_API_VERSION_DEFAULT: () => MATRX_AI_API_VERSION_DEFAULT,
   MatrxApiError: () => MatrxApiError,
   MatrxRunError: () => MatrxRunError,
   OrganizationContextError: () => OrganizationContextError,
   TERMINAL_MATRX_RUNTIME_STATUSES: () => TERMINAL_MATRX_RUNTIME_STATUSES,
   V2_COVERED_AI_PATH_TEMPLATES: () => V2_COVERED_AI_PATH_TEMPLATES,
+  VIDEO_IMAGE_ROLES: () => VIDEO_IMAGE_ROLES,
+  VIDEO_REFERENCE_ROLES: () => VIDEO_REFERENCE_ROLES,
   applyAiApiVersion: () => applyAiApiVersion,
   applyOrganizationContextHeader: () => applyOrganizationContextHeader,
   assertOrganizationMatchesOperation: () => assertOrganizationMatchesOperation,
@@ -42,6 +47,7 @@ __export(index_exports, {
   createMatrxTransport: () => createMatrxTransport,
   createOrganizationOperation: () => createOrganizationOperation,
   createWorkflowNodeProjection: () => createWorkflowNodeProjection,
+  deriveRunInputs: () => deriveRunInputs,
   extractMatrxErrorCode: () => extractMatrxErrorCode,
   extractMatrxErrorMessage: () => extractMatrxErrorMessage,
   fetchWithMatrxProtocolFallback: () => fetchWithMatrxProtocolFallback,
@@ -49,32 +55,48 @@ __export(index_exports, {
   followRuntimeOperationToEnd: () => followRuntimeOperationToEnd,
   getRuntimeOperationStatus: () => getRuntimeOperationStatus,
   getRuntimeOperationsByLink: () => getRuntimeOperationsByLink,
+  imageRoleVerdict: () => imageRoleVerdict,
+  isControlVariable: () => isControlVariable,
   isCoveredAiPath: () => isCoveredAiPath,
+  isImageReferenceRole: () => isImageReferenceRole,
+  isReferenceRole: () => isReferenceRole,
   isV2Path: () => isV2Path,
   listConversationPendingToolCalls: () => listConversationPendingToolCalls,
   listRuntimeOperationEvents: () => listRuntimeOperationEvents,
   listUserPendingToolCalls: () => listUserPendingToolCalls,
   mintMatrxConversationId: () => mintMatrxConversationId,
+  namedReferenceVerdict: () => namedReferenceVerdict,
   newEphemeralConversationStart: () => newEphemeralConversationStart,
   newStoredConversationStart: () => newStoredConversationStart,
   normalizeMatrxError: () => normalizeMatrxError,
   normalizeMatrxStreamEnvelope: () => normalizeMatrxStreamEnvelope,
+  normalizeReferenceName: () => normalizeReferenceName,
+  orderVariablesForForm: () => orderVariablesForForm,
   parseMatrxSseFrame: () => parseMatrxSseFrame,
+  partitionControlVariables: () => partitionControlVariables,
   projectAgentEvent: () => projectAgentEvent,
   projectAgentEvents: () => projectAgentEvents,
   projectAgentResultForDisplay: () => projectAgentResultForDisplay,
   projectWorkflowNodeEvent: () => projectWorkflowNodeEvent,
+  readImageRoleLimits: () => readImageRoleLimits,
   readMatrxNdjsonStream: () => readMatrxNdjsonStream,
   readMatrxSseStream: () => readMatrxSseStream,
+  referenceRoleCaption: () => referenceRoleCaption,
   rejoinRuntimeOperation: () => rejoinRuntimeOperation,
   requireOrganizationContext: () => requireOrganizationContext,
   resumeAgentConversation: () => resumeAgentConversation,
+  roleTakesName: () => roleTakesName,
+  rolesFor: () => rolesFor,
   runAgentToCompletion: () => runAgentToCompletion,
   startAgentRun: () => startAgentRun,
   startMandateRun: () => startMandateRun,
   submitAgentToolResults: () => submitAgentToolResults,
   toV1FallbackUrl: () => toV1FallbackUrl,
-  toV2Path: () => toV2Path
+  toV2Path: () => toV2Path,
+  variableNameOfImageUrl: () => variableNameOfImageUrl,
+  variableNameOfMediaUrl: () => variableNameOfMediaUrl,
+  variableRunHint: () => variableRunHint,
+  variableRunLabel: () => variableRunLabel
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -1679,4 +1701,222 @@ 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
+    };
+  });
+}
 //# sourceMappingURL=index.cjs.map