ai-lcr 0.7.0 → 0.7.2

package/CHANGELOG.md

@@ -4,6 +4,45 @@ All notable changes to `ai-lcr` are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/), and the project adheres to
 [Semantic Versioning](https://semver.org/).
 
+## [0.7.2] — 2026-06-20
+
+Async media jobs now have a **deadline/SLA**: a provider that accepts a job and
+then hangs (`queued`/`running` forever) is failed over to the next provider and
+recorded, instead of polling silently forever.
+
+### Added
+
+- **`MediaSubmitOptions.deadlineMs`** — per-job SLA. When a `poll()` finds the
+  job still `queued`/`running` at/after its deadline, the leg is treated as a
+  provider failure and runs the same failover path a `status:"error"` triggers
+  (re-submit to the next provider, carrying the deadline forward unchanged so a
+  hung provider can't reset the request's clock). Exhausted → a fail CallRecord
+  is settled and the poll throws (message contains "timeout").
+- **`MediaLCRConfig.defaultDeadlineMs`** (defaults to the new exported
+  **`DEFAULT_VIDEO_DEADLINE_MS` = 12 min**) and **`MediaLCRConfig.now`** (injectable
+  clock, defaults to `Date.now`, for deterministic tests).
+- **`MediaJobHandle.deadlineAt`** (absolute epoch ms) — survives the JSON
+  round-trip to a cross-process poll worker. Pre-0.7.2 handles without it keep
+  the old never-time-out behavior.
+- A CallRecord is now emitted on the **timeout** terminal outcome too (not just
+  success/error), with each hung leg carrying `errorClass: "timeout"` — so the
+  dashboard sees timeouts and timeout-driven failovers.
+
+## [0.7.1] — 2026-06-20
+
+Async media adapters now forward a caller-supplied webhook URL to the provider,
+so async video jobs can complete by **push** instead of poll-only.
+
+### Added
+
+- **`metadata.webhookUrl` is forwarded to the provider on async `submit`.**
+  `runware-media` adds it as the `videoInference` task's `webhookURL`; `fal-media`
+  appends it as the `?fal_webhook=` query param on the submit POST. The webhook is
+  a push path — the caller still polls as a fallback. Fixed task fields stay
+  un-clobberable (placed after the input spread). `metadata` was previously
+  accepted but dropped, so the documented "webhook hint" never reached the
+  provider; now it does.
+
 ## [0.7.0] — 2026-06-20
 
 The text router now records the **provider-reported actual cost** when a provider

package/dist/index.cjs

@@ -22,6 +22,7 @@ var index_exports = {};
 __export(index_exports, {
   DEFAULT_PROVIDERS: () => DEFAULT_PROVIDERS,
   DEFAULT_REFERENCE: () => DEFAULT_REFERENCE,
+  DEFAULT_VIDEO_DEADLINE_MS: () => DEFAULT_VIDEO_DEADLINE_MS,
   MEDIA_PRICING: () => MEDIA_PRICING,
   MODEL_PRICES: () => MODEL_PRICES,
   OFFICIAL_PRICES: () => OFFICIAL_PRICES,
@@ -1379,6 +1380,7 @@ function comparePrices(registry, ref = DEFAULT_REFERENCE) {
     };
   });
 }
+var DEFAULT_VIDEO_DEADLINE_MS = 12 * 60 * 1e3;
 function newMediaCallId() {
   const c = globalThis.crypto;
   return c?.randomUUID ? c.randomUUID() : `lcr_${Date.now().toString(36)}`;
@@ -1391,7 +1393,9 @@ function createMediaLCR(config) {
     officialPrices = OFFICIAL_PRICES,
     onError,
     onCost,
-    onCall
+    onCall,
+    defaultDeadlineMs = DEFAULT_VIDEO_DEADLINE_MS,
+    now = Date.now
   } = config;
   const safeError = (error, provider) => {
     try {
@@ -1471,7 +1475,7 @@ function createMediaLCR(config) {
       winner: void 0,
       ok: false,
       failedOver: attempts.length > 1,
-      latencyMs: Date.now() - startedAt,
+      latencyMs: now() - startedAt,
       inputTokens: 0,
       outputTokens: 0,
       costUsd: 0,
@@ -1489,7 +1493,7 @@ function createMediaLCR(config) {
       winner: args.provider,
       ok: true,
       failedOver: args.attempts.length > 1,
-      latencyMs: Date.now() - args.startedAt,
+      latencyMs: now() - args.startedAt,
       inputTokens: 0,
       outputTokens: 0,
       costUsd: settled.costCents / 100,
@@ -1503,17 +1507,17 @@ function createMediaLCR(config) {
   };
   const generate = async function generate2(modelId, input) {
     const { def, ranked, baseline } = resolve(modelId);
-    const startedAt = Date.now();
+    const startedAt = now();
     const attempts = [];
     let lastErr;
     for (const route of ranked) {
       const adapter = adapters[route.provider];
       if (!adapter) continue;
-      const attemptStart = Date.now();
+      const attemptStart = now();
       try {
         const result = await adapter.run({ externalId: route.externalId, input });
         const settled = settle(route.pricing, route.refCents, result, input);
-        attempts.push({ provider: route.provider, ok: true, latencyMs: Date.now() - attemptStart });
+        attempts.push({ provider: route.provider, ok: true, latencyMs: now() - attemptStart });
         warnDrift(modelId, route.provider, settled);
         safeCost({
           modelId,
@@ -1542,7 +1546,7 @@ function createMediaLCR(config) {
         attempts.push({
           provider: route.provider,
           ok: false,
-          latencyMs: Date.now() - attemptStart,
+          latencyMs: now() - attemptStart,
           errorClass: classifyError(err)
         });
         safeError(err, route.provider);
@@ -1559,13 +1563,13 @@ function createMediaLCR(config) {
     const { ranked } = resolve(modelId);
     return ranked.filter((r) => typeof adapters[r.provider]?.submit === "function");
   };
-  async function submitFrom(modelId, routes, input, metadata, baseline, startedAt, attempts) {
+  async function submitFrom(modelId, routes, input, metadata, baseline, startedAt, attempts, deadlineAt) {
     let lastErr;
     for (let i = 0; i < routes.length; i++) {
       const route = routes[i];
       const adapter = adapters[route.provider];
       if (!adapter?.submit) continue;
-      const attemptStart = Date.now();
+      const attemptStart = now();
       try {
         const { requestId } = await adapter.submit({ externalId: route.externalId, input, metadata });
         return {
@@ -1582,14 +1586,17 @@ function createMediaLCR(config) {
           baselineUsd: refBaselineUsd(baseline),
           startedAt,
           attemptStart,
-          attempts
+          attempts,
+          // Carry the SLA forward unchanged across a re-submit, so a hung
+          // provider can't reset the request's clock by failing over.
+          ...deadlineAt !== void 0 ? { deadlineAt } : {}
         };
       } catch (err) {
         lastErr = err;
         attempts.push({
           provider: route.provider,
           ok: false,
-          latencyMs: Date.now() - attemptStart,
+          latencyMs: now() - attemptStart,
           errorClass: classifyError(err)
         });
         safeError(err, route.provider);
@@ -1607,7 +1614,10 @@ function createMediaLCR(config) {
         `ai-lcr: no provider for media model "${modelId}" supports async submit (need an adapter with submit/checkStatus)`
       );
     }
-    return submitFrom(modelId, usable, input, options?.metadata, baseline, Date.now(), []);
+    const startedAt = now();
+    const deadlineMs = options?.deadlineMs ?? defaultDeadlineMs;
+    const deadlineAt = typeof deadlineMs === "number" && deadlineMs > 0 ? startedAt + deadlineMs : void 0;
+    return submitFrom(modelId, usable, input, options?.metadata, baseline, startedAt, [], deadlineAt);
   };
   generate.poll = async function poll(handle) {
     const adapter = adapters[handle.provider];
@@ -1628,7 +1638,9 @@ function createMediaLCR(config) {
         handle.metadata,
         handle.baseline ?? baseline,
         handle.startedAt,
-        attempts
+        attempts,
+        handle.deadlineAt
+        // same SLA instant — the new leg inherits the clock
       );
       return { done: false, status: "queued", handle: newHandle, failedOver: true };
     };
@@ -1638,7 +1650,7 @@ function createMediaLCR(config) {
         {
           provider: handle.provider,
           ok: false,
-          latencyMs: Date.now() - handle.attemptStart,
+          latencyMs: now() - handle.attemptStart,
           errorClass: classifyError(err)
         }
       ];
@@ -1656,6 +1668,15 @@ function createMediaLCR(config) {
       return onLegFailure(err, isRetryableError(err));
     }
     if (status.status === "queued" || status.status === "running") {
+      if (handle.deadlineAt !== void 0 && now() >= handle.deadlineAt) {
+        const elapsedMs = now() - handle.startedAt;
+        return onLegFailure(
+          new Error(
+            `ai-lcr: ${handle.provider} job ${handle.requestId} hit its timeout \u2014 still "${status.status}" after ${elapsedMs}ms (deadline ${handle.deadlineAt - handle.startedAt}ms)`
+          ),
+          true
+        );
+      }
       return { done: false, status: status.status, handle };
     }
     if (status.status === "done") {
@@ -1669,7 +1690,7 @@ function createMediaLCR(config) {
       const settled = settle(handle.pricing, handle.refCents, { ...status, outputs }, handle.input);
       const attempts = [
         ...handle.attempts,
-        { provider: handle.provider, ok: true, latencyMs: Date.now() - handle.attemptStart }
+        { provider: handle.provider, ok: true, latencyMs: now() - handle.attemptStart }
       ];
       warnDrift(handle.modelId, handle.provider, settled);
       safeCost({
@@ -2059,6 +2080,7 @@ function createRunwareMediaAdapter(config) {
     // (a `getResponse` poll). Image generation stays on the synchronous `run()`.
     async submit(req) {
       const taskUUID = crypto.randomUUID();
+      const webhookUrl = typeof req.metadata?.["webhookUrl"] === "string" ? req.metadata["webhookUrl"] : void 0;
       await postTask({
         outputType: "URL",
         includeCost: true,
@@ -2066,7 +2088,8 @@ function createRunwareMediaAdapter(config) {
         taskType: "videoInference",
         taskUUID,
         model: req.externalId,
-        deliveryMethod: "async"
+        deliveryMethod: "async",
+        ...webhookUrl ? { webhookURL: webhookUrl } : {}
       });
       return { requestId: taskUUID };
     },
@@ -2134,7 +2157,9 @@ function createFalMediaAdapter(config) {
   };
   const queueBase = (externalId) => externalId.split("/").slice(0, 2).join("/");
   async function submit(req) {
-    const submitRes = await fetchImpl(`${baseUrl}/${req.externalId}`, {
+    const webhookUrl = typeof req.metadata?.["webhookUrl"] === "string" ? req.metadata["webhookUrl"] : void 0;
+    const submitUrl = webhookUrl ? `${baseUrl}/${req.externalId}?fal_webhook=${encodeURIComponent(webhookUrl)}` : `${baseUrl}/${req.externalId}`;
+    const submitRes = await fetchImpl(submitUrl, {
       method: "POST",
       headers,
       body: JSON.stringify(req.input)
@@ -2360,6 +2385,7 @@ function createLCR(config) {
 0 && (module.exports = {
   DEFAULT_PROVIDERS,
   DEFAULT_REFERENCE,
+  DEFAULT_VIDEO_DEADLINE_MS,
   MEDIA_PRICING,
   MODEL_PRICES,
   OFFICIAL_PRICES,

package/dist/index.d.cts

@@ -787,7 +787,31 @@ interface MediaLCRConfig {
      * throws. Media records carry no token counts (inputTokens/outputTokens = 0).
      */
     onCall?: (record: CallRecord) => void;
+    /**
+     * Default SLA for an async job, in ms: how long a submitted job may stay
+     * `queued`/`running` before `poll` declares it timed out and fails over to the
+     * next provider (see {@link MediaSubmitOptions.deadlineMs} for a per-job
+     * override). Defaults to {@link DEFAULT_VIDEO_DEADLINE_MS} (12 min) — long
+     * enough for a slow video render, short enough that a hung provider is caught
+     * instead of polling forever. Set per consumer to match its own product SLA.
+     */
+    defaultDeadlineMs?: number;
+    /**
+     * Injectable clock (epoch ms), defaulting to `Date.now`. The deadline math and
+     * every latency stamp read THIS, so a test can drive a job past its deadline
+     * deterministically without real waits. Production never sets it.
+     */
+    now?: () => number;
 }
+/**
+ * Default async-job SLA: 12 minutes. A submitted job that stays
+ * `queued`/`running` longer than this is treated by `poll` as a provider failure
+ * and fails over to the next provider. Exposed (not buried) so the deadline is
+ * an explicit product knob, overridable per consumer via
+ * {@link MediaLCRConfig.defaultDeadlineMs} and per job via
+ * {@link MediaSubmitOptions.deadlineMs}.
+ */
+declare const DEFAULT_VIDEO_DEADLINE_MS: number;
 interface MediaRunResult {
     outputs: MediaOutput[];
     provider: string;
@@ -799,6 +823,16 @@ interface MediaRunResult {
 interface MediaSubmitOptions {
     /** Opaque caller metadata forwarded to the provider's `submit`. */
     metadata?: Record<string, unknown>;
+    /**
+     * Per-job SLA in ms: how long this job may stay `queued`/`running` before
+     * `poll` declares it timed out and fails over to the next provider. Overrides
+     * {@link MediaLCRConfig.defaultDeadlineMs} (which defaults to
+     * {@link DEFAULT_VIDEO_DEADLINE_MS}, 12 min) for this submit only. The deadline
+     * is captured at submit time as an absolute instant on the handle and carried
+     * forward unchanged across a failover, so the whole request — not each leg —
+     * is bounded by it.
+     */
+    deadlineMs?: number;
 }
 /**
  * A serializable receipt for an in-flight async job, returned by `submit` and
@@ -859,6 +893,15 @@ interface MediaJobHandle {
     attemptStart: number;
     /** Failed attempts so far, threaded across processes for the final CallRecord. */
     attempts: CallRecord["attempts"];
+    /**
+     * Epoch ms the WHOLE request must finish by — the SLA captured at the first
+     * submit ({@link MediaSubmitOptions.deadlineMs} or the config default). When a
+     * `poll` finds the job still `queued`/`running` at/after this instant, the leg
+     * is treated as a provider failure and fails over to the next provider (with
+     * this same deadline carried forward, so a hung provider can't reset the clock).
+     * Absent on pre-0.8 handles — those never time out (the old behavior).
+     */
+    deadlineAt?: number;
 }
 /** Outcome of one `poll` call. `done:false` ⇒ keep polling `handle`. */
 type MediaPollResult = {
@@ -1199,4 +1242,4 @@ type LCRRouter = (modelName: string) => LanguageModelV3;
  */
 declare function createLCR(config: LCRConfig): LCRRouter;
 
-export { type AnyLanguageModel, type BillableContext, type CacheOptions, type CacheStore, type CachedCall, type CachedMeta, type CallRecord, type CooldownOptions, type CostEvent, DEFAULT_PROVIDERS, DEFAULT_REFERENCE, type DefaultProviderId, type ErrorKind, type FormatOptions, type HttpSinkOptions, type LCRConfig, type LCRRouter, MEDIA_PRICING, MODEL_PRICES, type MediaAdapter, type MediaCostEvent, type MediaGenerateRequest, type MediaGenerateResult, type MediaJobHandle, type MediaJobStatus, type MediaLCR, type MediaLCRConfig, type MediaModality, type MediaModelDef, type MediaOutput, type MediaPollResult, type MediaPricing, type MediaRegistry, type MediaRoute, type MediaRunResult, type MediaStatusRequest, type MediaStatusResult, type MediaSubmitOptions, type MediaSubmitRequest, type MediaSubmitResult, type MediaUnit, type MediaUsage, type MemoryCacheOptions, OFFICIAL_PRICES, type PriceComparisonRow, type PromptCacheOptions, type ProviderConfig, type ProviderCost, type ProviderEntry, type RankedRoute, type ReferenceSpec, type RouteAttempt, billableUnits, cheapestRoute, classifyError, classifyErrorKind, comparePrices, createEnvSink, createFalMediaAdapter, createHttpSink, createKunavoMediaAdapter, createLCR, createMediaLCR, createMemoryCacheStore, createRunwareMediaAdapter, durationFromInput, formatCallRecord, getModelPrice, isAbortError, isNetworkError, isRetryableError, normalizedCents, priceCents, rankRoutes, referenceMegapixels, shouldFailover };
+export { type AnyLanguageModel, type BillableContext, type CacheOptions, type CacheStore, type CachedCall, type CachedMeta, type CallRecord, type CooldownOptions, type CostEvent, DEFAULT_PROVIDERS, DEFAULT_REFERENCE, DEFAULT_VIDEO_DEADLINE_MS, type DefaultProviderId, type ErrorKind, type FormatOptions, type HttpSinkOptions, type LCRConfig, type LCRRouter, MEDIA_PRICING, MODEL_PRICES, type MediaAdapter, type MediaCostEvent, type MediaGenerateRequest, type MediaGenerateResult, type MediaJobHandle, type MediaJobStatus, type MediaLCR, type MediaLCRConfig, type MediaModality, type MediaModelDef, type MediaOutput, type MediaPollResult, type MediaPricing, type MediaRegistry, type MediaRoute, type MediaRunResult, type MediaStatusRequest, type MediaStatusResult, type MediaSubmitOptions, type MediaSubmitRequest, type MediaSubmitResult, type MediaUnit, type MediaUsage, type MemoryCacheOptions, OFFICIAL_PRICES, type PriceComparisonRow, type PromptCacheOptions, type ProviderConfig, type ProviderCost, type ProviderEntry, type RankedRoute, type ReferenceSpec, type RouteAttempt, billableUnits, cheapestRoute, classifyError, classifyErrorKind, comparePrices, createEnvSink, createFalMediaAdapter, createHttpSink, createKunavoMediaAdapter, createLCR, createMediaLCR, createMemoryCacheStore, createRunwareMediaAdapter, durationFromInput, formatCallRecord, getModelPrice, isAbortError, isNetworkError, isRetryableError, normalizedCents, priceCents, rankRoutes, referenceMegapixels, shouldFailover };

package/dist/index.d.ts

@@ -787,7 +787,31 @@ interface MediaLCRConfig {
      * throws. Media records carry no token counts (inputTokens/outputTokens = 0).
      */
     onCall?: (record: CallRecord) => void;
+    /**
+     * Default SLA for an async job, in ms: how long a submitted job may stay
+     * `queued`/`running` before `poll` declares it timed out and fails over to the
+     * next provider (see {@link MediaSubmitOptions.deadlineMs} for a per-job
+     * override). Defaults to {@link DEFAULT_VIDEO_DEADLINE_MS} (12 min) — long
+     * enough for a slow video render, short enough that a hung provider is caught
+     * instead of polling forever. Set per consumer to match its own product SLA.
+     */
+    defaultDeadlineMs?: number;
+    /**
+     * Injectable clock (epoch ms), defaulting to `Date.now`. The deadline math and
+     * every latency stamp read THIS, so a test can drive a job past its deadline
+     * deterministically without real waits. Production never sets it.
+     */
+    now?: () => number;
 }
+/**
+ * Default async-job SLA: 12 minutes. A submitted job that stays
+ * `queued`/`running` longer than this is treated by `poll` as a provider failure
+ * and fails over to the next provider. Exposed (not buried) so the deadline is
+ * an explicit product knob, overridable per consumer via
+ * {@link MediaLCRConfig.defaultDeadlineMs} and per job via
+ * {@link MediaSubmitOptions.deadlineMs}.
+ */
+declare const DEFAULT_VIDEO_DEADLINE_MS: number;
 interface MediaRunResult {
     outputs: MediaOutput[];
     provider: string;
@@ -799,6 +823,16 @@ interface MediaRunResult {
 interface MediaSubmitOptions {
     /** Opaque caller metadata forwarded to the provider's `submit`. */
     metadata?: Record<string, unknown>;
+    /**
+     * Per-job SLA in ms: how long this job may stay `queued`/`running` before
+     * `poll` declares it timed out and fails over to the next provider. Overrides
+     * {@link MediaLCRConfig.defaultDeadlineMs} (which defaults to
+     * {@link DEFAULT_VIDEO_DEADLINE_MS}, 12 min) for this submit only. The deadline
+     * is captured at submit time as an absolute instant on the handle and carried
+     * forward unchanged across a failover, so the whole request — not each leg —
+     * is bounded by it.
+     */
+    deadlineMs?: number;
 }
 /**
  * A serializable receipt for an in-flight async job, returned by `submit` and
@@ -859,6 +893,15 @@ interface MediaJobHandle {
     attemptStart: number;
     /** Failed attempts so far, threaded across processes for the final CallRecord. */
     attempts: CallRecord["attempts"];
+    /**
+     * Epoch ms the WHOLE request must finish by — the SLA captured at the first
+     * submit ({@link MediaSubmitOptions.deadlineMs} or the config default). When a
+     * `poll` finds the job still `queued`/`running` at/after this instant, the leg
+     * is treated as a provider failure and fails over to the next provider (with
+     * this same deadline carried forward, so a hung provider can't reset the clock).
+     * Absent on pre-0.8 handles — those never time out (the old behavior).
+     */
+    deadlineAt?: number;
 }
 /** Outcome of one `poll` call. `done:false` ⇒ keep polling `handle`. */
 type MediaPollResult = {
@@ -1199,4 +1242,4 @@ type LCRRouter = (modelName: string) => LanguageModelV3;
  */
 declare function createLCR(config: LCRConfig): LCRRouter;
 
-export { type AnyLanguageModel, type BillableContext, type CacheOptions, type CacheStore, type CachedCall, type CachedMeta, type CallRecord, type CooldownOptions, type CostEvent, DEFAULT_PROVIDERS, DEFAULT_REFERENCE, type DefaultProviderId, type ErrorKind, type FormatOptions, type HttpSinkOptions, type LCRConfig, type LCRRouter, MEDIA_PRICING, MODEL_PRICES, type MediaAdapter, type MediaCostEvent, type MediaGenerateRequest, type MediaGenerateResult, type MediaJobHandle, type MediaJobStatus, type MediaLCR, type MediaLCRConfig, type MediaModality, type MediaModelDef, type MediaOutput, type MediaPollResult, type MediaPricing, type MediaRegistry, type MediaRoute, type MediaRunResult, type MediaStatusRequest, type MediaStatusResult, type MediaSubmitOptions, type MediaSubmitRequest, type MediaSubmitResult, type MediaUnit, type MediaUsage, type MemoryCacheOptions, OFFICIAL_PRICES, type PriceComparisonRow, type PromptCacheOptions, type ProviderConfig, type ProviderCost, type ProviderEntry, type RankedRoute, type ReferenceSpec, type RouteAttempt, billableUnits, cheapestRoute, classifyError, classifyErrorKind, comparePrices, createEnvSink, createFalMediaAdapter, createHttpSink, createKunavoMediaAdapter, createLCR, createMediaLCR, createMemoryCacheStore, createRunwareMediaAdapter, durationFromInput, formatCallRecord, getModelPrice, isAbortError, isNetworkError, isRetryableError, normalizedCents, priceCents, rankRoutes, referenceMegapixels, shouldFailover };
+export { type AnyLanguageModel, type BillableContext, type CacheOptions, type CacheStore, type CachedCall, type CachedMeta, type CallRecord, type CooldownOptions, type CostEvent, DEFAULT_PROVIDERS, DEFAULT_REFERENCE, DEFAULT_VIDEO_DEADLINE_MS, type DefaultProviderId, type ErrorKind, type FormatOptions, type HttpSinkOptions, type LCRConfig, type LCRRouter, MEDIA_PRICING, MODEL_PRICES, type MediaAdapter, type MediaCostEvent, type MediaGenerateRequest, type MediaGenerateResult, type MediaJobHandle, type MediaJobStatus, type MediaLCR, type MediaLCRConfig, type MediaModality, type MediaModelDef, type MediaOutput, type MediaPollResult, type MediaPricing, type MediaRegistry, type MediaRoute, type MediaRunResult, type MediaStatusRequest, type MediaStatusResult, type MediaSubmitOptions, type MediaSubmitRequest, type MediaSubmitResult, type MediaUnit, type MediaUsage, type MemoryCacheOptions, OFFICIAL_PRICES, type PriceComparisonRow, type PromptCacheOptions, type ProviderConfig, type ProviderCost, type ProviderEntry, type RankedRoute, type ReferenceSpec, type RouteAttempt, billableUnits, cheapestRoute, classifyError, classifyErrorKind, comparePrices, createEnvSink, createFalMediaAdapter, createHttpSink, createKunavoMediaAdapter, createLCR, createMediaLCR, createMemoryCacheStore, createRunwareMediaAdapter, durationFromInput, formatCallRecord, getModelPrice, isAbortError, isNetworkError, isRetryableError, normalizedCents, priceCents, rankRoutes, referenceMegapixels, shouldFailover };

package/dist/index.js

@@ -1325,6 +1325,7 @@ function comparePrices(registry, ref = DEFAULT_REFERENCE) {
     };
   });
 }
+var DEFAULT_VIDEO_DEADLINE_MS = 12 * 60 * 1e3;
 function newMediaCallId() {
   const c = globalThis.crypto;
   return c?.randomUUID ? c.randomUUID() : `lcr_${Date.now().toString(36)}`;
@@ -1337,7 +1338,9 @@ function createMediaLCR(config) {
     officialPrices = OFFICIAL_PRICES,
     onError,
     onCost,
-    onCall
+    onCall,
+    defaultDeadlineMs = DEFAULT_VIDEO_DEADLINE_MS,
+    now = Date.now
   } = config;
   const safeError = (error, provider) => {
     try {
@@ -1417,7 +1420,7 @@ function createMediaLCR(config) {
       winner: void 0,
       ok: false,
       failedOver: attempts.length > 1,
-      latencyMs: Date.now() - startedAt,
+      latencyMs: now() - startedAt,
       inputTokens: 0,
       outputTokens: 0,
       costUsd: 0,
@@ -1435,7 +1438,7 @@ function createMediaLCR(config) {
       winner: args.provider,
       ok: true,
       failedOver: args.attempts.length > 1,
-      latencyMs: Date.now() - args.startedAt,
+      latencyMs: now() - args.startedAt,
       inputTokens: 0,
       outputTokens: 0,
       costUsd: settled.costCents / 100,
@@ -1449,17 +1452,17 @@ function createMediaLCR(config) {
   };
   const generate = async function generate2(modelId, input) {
     const { def, ranked, baseline } = resolve(modelId);
-    const startedAt = Date.now();
+    const startedAt = now();
     const attempts = [];
     let lastErr;
     for (const route of ranked) {
       const adapter = adapters[route.provider];
       if (!adapter) continue;
-      const attemptStart = Date.now();
+      const attemptStart = now();
       try {
         const result = await adapter.run({ externalId: route.externalId, input });
         const settled = settle(route.pricing, route.refCents, result, input);
-        attempts.push({ provider: route.provider, ok: true, latencyMs: Date.now() - attemptStart });
+        attempts.push({ provider: route.provider, ok: true, latencyMs: now() - attemptStart });
         warnDrift(modelId, route.provider, settled);
         safeCost({
           modelId,
@@ -1488,7 +1491,7 @@ function createMediaLCR(config) {
         attempts.push({
           provider: route.provider,
           ok: false,
-          latencyMs: Date.now() - attemptStart,
+          latencyMs: now() - attemptStart,
           errorClass: classifyError(err)
         });
         safeError(err, route.provider);
@@ -1505,13 +1508,13 @@ function createMediaLCR(config) {
     const { ranked } = resolve(modelId);
     return ranked.filter((r) => typeof adapters[r.provider]?.submit === "function");
   };
-  async function submitFrom(modelId, routes, input, metadata, baseline, startedAt, attempts) {
+  async function submitFrom(modelId, routes, input, metadata, baseline, startedAt, attempts, deadlineAt) {
     let lastErr;
     for (let i = 0; i < routes.length; i++) {
       const route = routes[i];
       const adapter = adapters[route.provider];
       if (!adapter?.submit) continue;
-      const attemptStart = Date.now();
+      const attemptStart = now();
       try {
         const { requestId } = await adapter.submit({ externalId: route.externalId, input, metadata });
         return {
@@ -1528,14 +1531,17 @@ function createMediaLCR(config) {
           baselineUsd: refBaselineUsd(baseline),
           startedAt,
           attemptStart,
-          attempts
+          attempts,
+          // Carry the SLA forward unchanged across a re-submit, so a hung
+          // provider can't reset the request's clock by failing over.
+          ...deadlineAt !== void 0 ? { deadlineAt } : {}
         };
       } catch (err) {
         lastErr = err;
         attempts.push({
           provider: route.provider,
           ok: false,
-          latencyMs: Date.now() - attemptStart,
+          latencyMs: now() - attemptStart,
           errorClass: classifyError(err)
         });
         safeError(err, route.provider);
@@ -1553,7 +1559,10 @@ function createMediaLCR(config) {
         `ai-lcr: no provider for media model "${modelId}" supports async submit (need an adapter with submit/checkStatus)`
       );
     }
-    return submitFrom(modelId, usable, input, options?.metadata, baseline, Date.now(), []);
+    const startedAt = now();
+    const deadlineMs = options?.deadlineMs ?? defaultDeadlineMs;
+    const deadlineAt = typeof deadlineMs === "number" && deadlineMs > 0 ? startedAt + deadlineMs : void 0;
+    return submitFrom(modelId, usable, input, options?.metadata, baseline, startedAt, [], deadlineAt);
   };
   generate.poll = async function poll(handle) {
     const adapter = adapters[handle.provider];
@@ -1574,7 +1583,9 @@ function createMediaLCR(config) {
         handle.metadata,
         handle.baseline ?? baseline,
         handle.startedAt,
-        attempts
+        attempts,
+        handle.deadlineAt
+        // same SLA instant — the new leg inherits the clock
       );
       return { done: false, status: "queued", handle: newHandle, failedOver: true };
     };
@@ -1584,7 +1595,7 @@ function createMediaLCR(config) {
         {
           provider: handle.provider,
           ok: false,
-          latencyMs: Date.now() - handle.attemptStart,
+          latencyMs: now() - handle.attemptStart,
           errorClass: classifyError(err)
         }
       ];
@@ -1602,6 +1613,15 @@ function createMediaLCR(config) {
       return onLegFailure(err, isRetryableError(err));
     }
     if (status.status === "queued" || status.status === "running") {
+      if (handle.deadlineAt !== void 0 && now() >= handle.deadlineAt) {
+        const elapsedMs = now() - handle.startedAt;
+        return onLegFailure(
+          new Error(
+            `ai-lcr: ${handle.provider} job ${handle.requestId} hit its timeout \u2014 still "${status.status}" after ${elapsedMs}ms (deadline ${handle.deadlineAt - handle.startedAt}ms)`
+          ),
+          true
+        );
+      }
       return { done: false, status: status.status, handle };
     }
     if (status.status === "done") {
@@ -1615,7 +1635,7 @@ function createMediaLCR(config) {
       const settled = settle(handle.pricing, handle.refCents, { ...status, outputs }, handle.input);
       const attempts = [
         ...handle.attempts,
-        { provider: handle.provider, ok: true, latencyMs: Date.now() - handle.attemptStart }
+        { provider: handle.provider, ok: true, latencyMs: now() - handle.attemptStart }
       ];
       warnDrift(handle.modelId, handle.provider, settled);
       safeCost({
@@ -2005,6 +2025,7 @@ function createRunwareMediaAdapter(config) {
     // (a `getResponse` poll). Image generation stays on the synchronous `run()`.
     async submit(req) {
       const taskUUID = crypto.randomUUID();
+      const webhookUrl = typeof req.metadata?.["webhookUrl"] === "string" ? req.metadata["webhookUrl"] : void 0;
       await postTask({
         outputType: "URL",
         includeCost: true,
@@ -2012,7 +2033,8 @@ function createRunwareMediaAdapter(config) {
         taskType: "videoInference",
         taskUUID,
         model: req.externalId,
-        deliveryMethod: "async"
+        deliveryMethod: "async",
+        ...webhookUrl ? { webhookURL: webhookUrl } : {}
       });
       return { requestId: taskUUID };
     },
@@ -2080,7 +2102,9 @@ function createFalMediaAdapter(config) {
   };
   const queueBase = (externalId) => externalId.split("/").slice(0, 2).join("/");
   async function submit(req) {
-    const submitRes = await fetchImpl(`${baseUrl}/${req.externalId}`, {
+    const webhookUrl = typeof req.metadata?.["webhookUrl"] === "string" ? req.metadata["webhookUrl"] : void 0;
+    const submitUrl = webhookUrl ? `${baseUrl}/${req.externalId}?fal_webhook=${encodeURIComponent(webhookUrl)}` : `${baseUrl}/${req.externalId}`;
+    const submitRes = await fetchImpl(submitUrl, {
       method: "POST",
       headers,
       body: JSON.stringify(req.input)
@@ -2305,6 +2329,7 @@ function createLCR(config) {
 export {
   DEFAULT_PROVIDERS,
   DEFAULT_REFERENCE,
+  DEFAULT_VIDEO_DEADLINE_MS,
   MEDIA_PRICING,
   MODEL_PRICES,
   OFFICIAL_PRICES,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-lcr",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Least Cost Routing for LLMs — route every model call to the cheapest available provider, fall back automatically, and track real cost. Built for the Vercel AI SDK.",
   "keywords": [
     "ai",