@shop-os/modelkit 0.2.13 → 0.2.15

package/CHANGELOG.md

@@ -9,6 +9,22 @@ header in the release PR.
 
 ## [Unreleased]
 
+## [0.2.15] - Unreleased
+
+### Added
+- `MediaRef.durationSeconds`: the measured length of a video or audio ref. The kit never measures it; callers pass it when known.
+- `ReferenceLimits.videoSeconds` (`VideoSecondsLimits`: `min`, `max`, `total`, `editMin`): per-video and combined length limits for reference videos. `editMin` raises the per-video minimum when `taskType` is `edit` (Seedance 2.5: 4 s). Rows without it accept any length.
+- `ModelConstraints.sourceVideoSeconds` (`min`, `max`, `editMin`, `inReferenceTotal`): length limits for the source video. `inReferenceTotal` counts the source toward the combined reference limit where the provider sends it as a reference video (Seedance).
+- `videoLengthViolation(model, input)`: pure checker that returns the first length violation as a user-facing message, else `undefined`. Unknown lengths are skipped. Exported from the root and `/catalog` entries.
+- `resolveVideoOptions` rejects a reference or source video outside the row limits with a non-retryable `unsupported_option` error before any provider call. Videos dropped by the reference caps do not count.
+- Snapshot rows carry the provider limits: MiniMax H3 and H3 Max reference (2-15 s each, 15 s combined), Seedance 2.0 and 2.0 Fast (2-15 s each, 15 s combined), Seedance 2.5 (2-30 s each, 30 s combined, 4 s minimum for edit), Gemini Omni 1.0 and 1.1 (10 s), Kling O1 v2v source video (3-10.05 s).
+
+## [0.2.14] - Unreleased
+
+- Keep AI SDK 6 and its compatible provider packages, including Bedrock and usage tracking.
+- Add per-call media retry limits so durable workflow controllers can own retries without duplicate provider submissions.
+
+
 ## [0.2.13] - 2026-09-18
 
 ### Added

package/README.md

@@ -110,11 +110,40 @@ for a model the catalog does not carry yet; the next step is a catalog row.
 | `experimental_generateSpeech`, `transcribe`, `embed`, `embedMany`, `rerank`, agents, UI streams | Re-exported from `ai` unchanged; the catalog has no rows for them.                                                                                                                                                                                                                                                                |
 
 An optional second `CallContext` argument selects enterprise keys, adds cancellation
-(combined with `abortSignal`), and sets `onUnsupported`. Package-level functions read
+(combined with `abortSignal`), sets media `maxRetries`, and sets `onUnsupported`. Package-level functions read
 keys from the environment; a configured kit adds routing, catalog overrides, custom
 fetch, provider endpoint overrides (`endpoints.ark` for the Ark base url), logging, and
 the `onUsage` sink.
 
+### Durable media execution
+
+Goal Mode owns technical recovery. Every image, video, audio, and media-preparation
+call in that host must pass `{ maxRetries: 0 }` as the second argument:
+
+```ts
+const result = await kit.generateImage(
+    { model: "gpt-image-2", prompt: "A product photo" },
+    { maxRetries: 0, signal },
+);
+```
+
+`maxRetries` counts retries after the first request. Zero disables adapter and SDK
+retries, failed status-read retries, and Google's Files-to-inline fallback. Successful
+pending-job responses still poll the same job. Unset retains existing adapter defaults.
+An explicit nonzero limit allows bounded submission retries; a later read failure never
+resubmits an already-created fal job. Text calls instead use AI SDK's first-argument
+`maxRetries: 0` option.
+
+Replicate 1.x has no retry switch. fal 1.x queue methods override its client retry
+setting. With an explicit limit, ModelKit uses their REST prediction/queue endpoints
+and owns retries itself; the usual SDK paths remain when the option is unset. Google
+models and Google Interactions have separate retry controls, both disabled beneath
+ModelKit's policy. SDK image/video model instances also receive the explicit limit.
+The fal Cloudflare passthrough sets `cf-aig-max-attempts: 1` with an explicit limit,
+using [Cloudflare request handling](https://developers.cloudflare.com/ai-gateway/configuration/request-handling/)
+headers so gateway retries do not multiply local attempts. Custom adapters and custom
+provider instances must honor their own retry contract.
+
 `providerOptions` on `generateImage`/`generateVideo` reach the provider only for
 pass-through instances; catalog rows carry their own and the caller's are dropped
 with an `option_ignored` warning.
@@ -213,7 +242,7 @@ const defaultKit = createDefaultModelKit({ keys: { pro: keysFromEnv(process.env)
 | Options     | Image tiers are `512` (Gemini 3.1 Flash only), `1K`, `2K`, `4K`. `resolveOptions` fills catalog defaults, errors on an unsupported aspect ratio, size, resolution or duration (`onUnsupported: "coerce"` snaps to the nearest supported value with a warning instead; since 0.1.6 ratio and duration honour this too, so pass `"coerce"` where the old code snapped silently), trims references (audio first, then video), and drops options the model ignores with a warning. Audio requests go through the same resolver and take `abortSignal` (a row without `supports` supports nothing). `aspectRatio: "adaptive"` means "send no ratio": it is never coerced or replaced by the row default, and Gemini, Muse, Kling and Kling O1 omit the field so the model infers it from the references. Every coercion is also logged once per call through `logger.warn`. Gemini image `safetySettings` and `temperature` are sent only when the caller passes them. A reference with a `label` gets a text part with that label right before the image on Gemini image and Omni ("Image 2:", "Here is the brand logo:"). Topaz takes `upscale` (`enhanceModel`, `subjectDetection`, `faceEnhancement` and its creativity/strength) next to `scaleFactor`/`outputFormat`; Seedance takes `watermark`; MiniMax takes `lastFrame` and `safetyChecker`; Seedream 4.5 goes to `4K` and `9:21`. |
 | Keys        | Enterprise keys win only when every key the adapter (and its route, e.g. the cloudflare token for a vendor that really goes through the gateway) needs is set on the enterprise tier; a fallback to pro keys is logged once per call.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | Routing     | Cloudflare AI Gateway for text only. Never for Gemini images or Omni. fal passthrough for geo-blocked regions; the fal direct route submits to the queue and polls, so `job.result({ timeoutMs, signal })` is live.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| Retry       | One classifier, one policy. Never on content blocks, aborts, or 4xx except 429; SDKs with their own retry (Replicate) run under a single kit attempt; a 429 on a status poll keeps polling.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| Retry       | One classifier, one policy. Never on content blocks, aborts, or 4xx except 429; SDKs with their own retry (Replicate) run under a single kit attempt; a 429 on a status poll keeps polling unless `CallContext.maxRetries` is `0`. See durable media execution above.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | Errors      | `ModelKitError` with `code`, `provider`, `status`, `body`. Gemini `blockReason` and fal `body.detail` are lifted into `body`. A throw with no HTTP status (fetch failed, reset, DNS) is a retryable `network` error on every adapter.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | Usage       | One event per call with the canonical model id and the row's `usage.unit` (adapters supply the quantity in that unit). Gemini image events carry the token counts too (`inputTokens`/`outputTokens`); Google's raw `usageMetadata` rides on `raw.providerMetadata.google`. Video usage is emitted on completion; Seedance keeps `usage`, `duration`, `framespersecond` and `resolution` from the poll on `raw`. Audio: Lyria 3 returns no duration, so it emits `unit: "images", quantity: 1` (token counts ride along as `inputTokens`/`outputTokens`); Replicate audio (Lyria 2, MMAudio) emits `unit: "compute_seconds"` with the prediction time.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | Media parts | `prepareMediaPart` turns a `MediaRef` into an AI SDK file part. Google inlines bytes up to 20 MB and uploads larger payloads through the Files API; call the returned `cleanup` after the request. Other providers get the reference inline.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |

package/dist/catalog.cjs

@@ -48,7 +48,8 @@ __export(catalog_entry_exports, {
   resolveImageOptions: () => resolveImageOptions,
   resolveOptions: () => resolveOptions,
   resolveVideoOptions: () => resolveVideoOptions,
-  sortCatalogRows: () => sortCatalogRows
+  sortCatalogRows: () => sortCatalogRows,
+  videoLengthViolation: () => videoLengthViolation
 });
 module.exports = __toCommonJS(catalog_entry_exports);
 
@@ -180,7 +181,9 @@ function normalizeExposure(value) {
   if (value === "catalog") return ["cowork", "space_builder"];
   if (value === "internal") return [];
   if (Array.isArray(value)) {
-    if (value.every((entry) => SURFACES.includes(entry))) {
+    if (value.every(
+      (entry) => SURFACES.includes(entry)
+    )) {
       const present = new Set(value);
       return SURFACES.filter((surface) => present.has(surface));
     }
@@ -1414,7 +1417,8 @@ var VIDEO_MODELS = [
       // reference clip keeps its own framing.
       aspectRatios: [...OMNI_RATIOS],
       durations: [3, 4, 5, 6, 7, 8, 9, 10],
-      references: { images: 6, videos: 1 },
+      references: { images: 6, videos: 1, videoSeconds: { max: 10 } },
+      sourceVideoSeconds: { max: 10 },
       supports: []
     },
     defaults: {},
@@ -1440,7 +1444,8 @@ var VIDEO_MODELS = [
       aspectRatios: [...OMNI_RATIOS],
       resolutions: ["360p", "720p", "1080p", "4k"],
       durations: [3, 4, 5, 6, 7, 8, 9, 10],
-      references: { images: 6, videos: 1 },
+      references: { images: 6, videos: 1, videoSeconds: { max: 10 } },
+      sourceVideoSeconds: { max: 10 },
       supports: []
     },
     defaults: {},
@@ -1468,7 +1473,14 @@ var VIDEO_MODELS = [
       resolutions: ["480p", "720p", "1080p", "4k"],
       durations: { min: 4, max: 15 },
       durationPresets: [4, 6, 8, 10, 12, 15],
-      references: { images: 9, videos: 3, audios: 3, audioOnly: false },
+      references: {
+        images: 9,
+        videos: 3,
+        audios: 3,
+        audioOnly: false,
+        videoSeconds: { min: 2, max: 15, total: 15 }
+      },
+      sourceVideoSeconds: { min: 2, max: 15, inReferenceTotal: true },
       ratioIgnoredWith: ["firstFrame", "sourceVideo"],
       supports: ["generateAudio", "seed", "lastFrame", "watermark"]
     },
@@ -1500,7 +1512,14 @@ var VIDEO_MODELS = [
       aspectRatios: [...SEEDANCE_RATIOS],
       resolutions: ["480p", "720p"],
       durations: { min: 4, max: 15 },
-      references: { images: 9, videos: 3, audios: 3, audioOnly: false },
+      references: {
+        images: 9,
+        videos: 3,
+        audios: 3,
+        audioOnly: false,
+        videoSeconds: { min: 2, max: 15, total: 15 }
+      },
+      sourceVideoSeconds: { min: 2, max: 15, inReferenceTotal: true },
       ratioIgnoredWith: ["firstFrame", "sourceVideo"],
       supports: ["generateAudio", "seed", "lastFrame", "watermark"]
     },
@@ -1534,7 +1553,13 @@ var VIDEO_MODELS = [
       aspectRatios: [...SEEDANCE_RATIOS],
       resolutions: ["480p", "720p", "1080p"],
       durations: { min: 4, max: 30 },
-      references: { images: 30, videos: 10, audios: 10 },
+      references: {
+        images: 30,
+        videos: 10,
+        audios: 10,
+        videoSeconds: { min: 2, max: 30, total: 30, editMin: 4 }
+      },
+      sourceVideoSeconds: { min: 2, max: 30, editMin: 4, inReferenceTotal: true },
       ratioIgnoredWith: ["firstFrame", "sourceVideo"],
       supports: ["generateAudio", "seed", "lastFrame", "watermark", "taskType"]
     },
@@ -1746,7 +1771,14 @@ var VIDEO_MODELS = [
       aspectRatios: [...H3_REFERENCE_RATIOS],
       resolutions: ["480p", "768p", "2k", "4k"],
       durations: { min: 5, max: 15 },
-      references: { images: 9, videos: 3, audios: 3, total: 12, audioOnly: false },
+      references: {
+        images: 9,
+        videos: 3,
+        audios: 3,
+        total: 12,
+        audioOnly: false,
+        videoSeconds: { min: 2, max: 15, total: 15 }
+      },
       supports: ["seed", "promptExpansion", "safetyChecker"]
     },
     defaults: {
@@ -1777,7 +1809,14 @@ var VIDEO_MODELS = [
       aspectRatios: [...H3_REFERENCE_RATIOS],
       resolutions: ["480p", "768p"],
       durations: { min: 5, max: 15 },
-      references: { images: 9, videos: 3, audios: 3, total: 12, audioOnly: false },
+      references: {
+        images: 9,
+        videos: 3,
+        audios: 3,
+        total: 12,
+        audioOnly: false,
+        videoSeconds: { min: 2, max: 15, total: 15 }
+      },
       supports: ["seed", "promptExpansion", "safetyChecker"]
     },
     defaults: {
@@ -1809,6 +1848,7 @@ var VIDEO_MODELS = [
       aspectRatios: [...KLING_RATIOS],
       durations: { min: 3, max: 10 },
       requires: ["sourceVideo"],
+      sourceVideoSeconds: { min: 3, max: 10.05 },
       supports: []
     },
     defaults: { durationSeconds: 5, aspectRatio: "16:9" },
@@ -2165,13 +2205,20 @@ var ProviderOptionValueSchema = import_zod2.z.lazy(
   ])
 );
 var ProviderOptionsSchema = import_zod2.z.record(import_zod2.z.string(), import_zod2.z.record(import_zod2.z.string(), ProviderOptionValueSchema));
+var VideoSecondsLimitsSchema = import_zod2.z.looseObject({
+  min: import_zod2.z.number().optional(),
+  max: import_zod2.z.number().optional(),
+  total: import_zod2.z.number().optional(),
+  editMin: import_zod2.z.number().optional()
+});
 var ReferenceLimitsSchema = import_zod2.z.looseObject({
   images: import_zod2.z.number().optional(),
   imagesWithVideo: import_zod2.z.number().optional(),
   videos: import_zod2.z.number().optional(),
   audios: import_zod2.z.number().optional(),
   total: import_zod2.z.number().optional(),
-  audioOnly: import_zod2.z.boolean().optional()
+  audioOnly: import_zod2.z.boolean().optional(),
+  videoSeconds: VideoSecondsLimitsSchema.optional()
 });
 var ModelConstraintsSchema = import_zod2.z.looseObject({
   aspectRatios: import_zod2.z.array(AspectRatioSchema).optional(),
@@ -2184,14 +2231,20 @@ var ModelConstraintsSchema = import_zod2.z.looseObject({
   references: ReferenceLimitsSchema.optional(),
   requires: import_zod2.z.array(RequiredInputSchema).optional(),
   supports: import_zod2.z.array(SupportedOptionSchema).optional(),
-  ratioIgnoredWith: import_zod2.z.array(import_zod2.z.enum(["firstFrame", "sourceVideo"])).optional()
+  ratioIgnoredWith: import_zod2.z.array(import_zod2.z.enum(["firstFrame", "sourceVideo"])).optional(),
+  sourceVideoSeconds: VideoSecondsLimitsSchema.omit({ total: true }).extend({ inReferenceTotal: import_zod2.z.boolean().optional() }).optional()
 });
 var MediaRefSchema = import_zod2.z.union([
-  import_zod2.z.looseObject({ url: import_zod2.z.string(), label: import_zod2.z.string().optional() }),
+  import_zod2.z.looseObject({
+    url: import_zod2.z.string(),
+    label: import_zod2.z.string().optional(),
+    durationSeconds: import_zod2.z.number().optional()
+  }),
   import_zod2.z.looseObject({
     bytes: import_zod2.z.instanceof(Uint8Array),
     mime: import_zod2.z.string(),
-    label: import_zod2.z.string().optional()
+    label: import_zod2.z.string().optional(),
+    durationSeconds: import_zod2.z.number().optional()
   })
 ]);
 var ImageSafetySettingSchema = import_zod2.z.looseObject({ category: import_zod2.z.string(), threshold: import_zod2.z.string() });
@@ -2680,6 +2733,49 @@ function trim(field, refs, limit, model, warnings) {
   });
   return refs.slice(0, limit);
 }
+function knownLength(value) {
+  return value !== void 0 && Number.isFinite(value) ? value : void 0;
+}
+function seconds(len, limit) {
+  let digits = 1;
+  while (digits < 3 && Number(len.toFixed(digits)) === limit) digits++;
+  return len.toFixed(digits);
+}
+function effectiveMin(limits, taskType) {
+  if (taskType !== "edit" || limits?.editMin === void 0) return limits?.min;
+  return Math.max(limits.min ?? 0, limits.editMin);
+}
+function videoLengthViolation(model, input) {
+  const limits = model.constraints.references?.videoSeconds;
+  const refMin = effectiveMin(limits, input.taskType);
+  const lengths = (input.referenceVideos ?? []).map(knownLength);
+  if (limits?.max !== void 0) {
+    const max = limits.max;
+    const i = lengths.findIndex((len) => len !== void 0 && len > max);
+    if (i >= 0)
+      return `${model.label} takes reference videos up to ${String(max)} s each; video ${i + 1} is ${seconds(lengths[i], max)} s.`;
+  }
+  if (refMin !== void 0) {
+    const i = lengths.findIndex((len) => len !== void 0 && len < refMin);
+    if (i >= 0)
+      return `${model.label} takes reference videos of at least ${String(refMin)} s each; video ${i + 1} is ${seconds(lengths[i], refMin)} s.`;
+  }
+  const source = knownLength(input.sourceVideo);
+  const sourceLimits = model.constraints.sourceVideoSeconds;
+  if (limits?.total !== void 0) {
+    const refSum = lengths.reduce((acc, len) => acc + (len ?? 0), 0);
+    const sum = refSum + (sourceLimits?.inReferenceTotal ? source ?? 0 : 0);
+    if (sum > limits.total)
+      return `${model.label} takes reference videos up to ${String(limits.total)} s combined; these add up to ${seconds(sum, limits.total)} s.`;
+  }
+  if (source === void 0) return void 0;
+  const sourceMin = effectiveMin(sourceLimits, input.taskType);
+  if (sourceLimits?.max !== void 0 && source > sourceLimits.max)
+    return `${model.label} takes a source video up to ${String(sourceLimits.max)} s; this one is ${seconds(source, sourceLimits.max)} s.`;
+  if (sourceMin !== void 0 && source < sourceMin)
+    return `${model.label} takes a source video of at least ${String(sourceMin)} s; this one is ${seconds(source, sourceMin)} s.`;
+  return void 0;
+}
 function resolveImageOptions(model, request, onUnsupported = "error") {
   const warnings = [];
   const c = model.constraints;
@@ -2865,6 +2961,21 @@ function resolveVideoOptions(model, request, onUnsupported = "error") {
       model: model.id
     });
   }
+  const lengthViolation = videoLengthViolation(model, {
+    referenceVideos: videos.map((v) => v.durationSeconds),
+    taskType: merged.taskType,
+    ...merged.sourceVideo?.durationSeconds !== void 0 && {
+      sourceVideo: merged.sourceVideo.durationSeconds
+    }
+  });
+  if (lengthViolation !== void 0) {
+    throw new ModelKitError({
+      code: "unsupported_option",
+      message: lengthViolation,
+      model: model.id,
+      retryable: false
+    });
+  }
   setOrDelete(merged, "referenceImages", images);
   setOrDelete(merged, "referenceVideos", videos);
   setOrDelete(merged, "referenceAudios", audios);