videobook 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -6,6 +6,79 @@ and the package uses [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-10-25
+
+### Added
+
+- KIE Kling 4.0 reference-to-video and keyframe-to-video, 3 to 30 seconds at
+  720p or 1080p. Reference-to-video takes up to ten images and five videos,
+  and generates from the prompt alone when none are connected. Keyframe-to-video
+  takes a first frame, up to eight middle keyframes and a last frame, as many
+  as the duration allows. Prompts name connected media the way Kling 4.0 does:
+  `@image_1`, `@video_1`, `@first_frame`, `@keyframe_1` and `@last_frame`.
+- KIE PixVerse V6 Max text-to-video and image-to-video, 1 to 15 seconds at
+  360p to 1080p, with optional generated audio and a seed. Image-to-video
+  follows the image's aspect ratio.
+- KIE OmniHuman 2.0, which animates one image to a driving audio track at 720p
+  for as long as the audio runs, with an optional prompt of up to 300
+  characters. KIE's watermark stays on by default (`enable_watermark`).
+- The KIE Grok Imagine Video 1.5 preview, the KIE Grok Imagine endpoint that
+  takes first and last frames, a loop image (`loop_url`) and up to four timed
+  `keyframes`. It shares the Grok Imagine Video 1.5 image-to-video frontier
+  ranking. Kling 4.0, PixVerse V6 Max and OmniHuman 2.0 are on no top-10 board
+  and appear in the unranked group.
+
+### Changed
+
+- Upgrade all `@apicity/*` dependencies to 0.18.1, which prices the new KIE
+  models. Its endpoint catalog now lists fal `v1.queue.status` and
+  `v1.queue.result`, with the other fal SDK methods written as method
+  shorthand, so `apicity har report` from `@apicity/cli` 0.18.1 can resolve the
+  fal polling captures Videobook writes. The requests sent to fal are
+  unchanged.
+- Image and video models default to a 12-second duration (or the nearest
+  allowed length), a 9:16 aspect ratio and their highest resolution, quality
+  and bitrate. Each notebook remembers the last duration, aspect ratio,
+  resolution and quality a cell used, and applies them to new cells and model
+  switches. Goals saved before this change keep their 2K scene; new goals use
+  4K.
+- On desktop, Settings shows AI providers in one column and accounts, storage
+  and diagnostics in another; on phones the columns stack behind section jump
+  buttons. The chat input stays a plain bar on Settings.
+- The Library opens from an Assets button in the notebook toolbar instead of
+  the header, and Arrange is renamed Clean.
+- Library browsing pages assets before building their rows and no longer runs
+  ffprobe while listing; proxy checks and duration backfills run as background
+  jobs.
+- A Post can take its published link without being saved to iPhone or Dropbox
+  first.
+
+### Fixed
+
+- HAR captures of KIE's nested Veo and Suno SDK calls are named by their
+  apicity catalog dot paths, such as `api.v1.veo.generate` and
+  `api.v1.generate.sounds`, instead of their SDK paths, so `apicity har report`
+  resolves them. Sub-provider prefixes that are URL segments stay:
+  `kie.claude.post.v1.messages` is named `claude.v1.messages`.
+- A generation that fails before reaching its provider, such as a request the
+  schema refuses, is captured under the provider's catalog endpoint, and fal,
+  Alibaba and KIE file uploads are captured as `storage.upload.initiate`,
+  `api.v1.uploads` and `api.fileStreamUpload`, so `apicity har report` resolves
+  them.
+- A notebook generation whose provider fails after accepting the request now
+  marks its plan failed with the provider error. `list_notebook_generation_plans`
+  and the Jobs screen kept reporting such plans as awaiting output.
+- v3 goals saved with a 2K scene load again and keep that resolution when they
+  are edited, approved or retried.
+- Image subject edits check the provider key before uploading the source image,
+  so a missing or placeholder key no longer sends the image to a public file
+  host for a request that cannot run.
+- Settings loads when the page opens on it, or when it opens before the MCP
+  connection is ready.
+- The multyculty workflow and video poster recovery tests no longer time out on
+  loaded hosts, and the chat-composer browser test no longer reads the runner's
+  `.env` or provider keys and matches the ranked model picker.
+
 ## [0.3.0] - 2026-10-24
 
 ### Added

package/dist/asset-media-projection.js

@@ -0,0 +1,161 @@
+import { createHash } from "node:crypto";
+import { findAudioFile, findPrimaryMediaFile, findVideoFile } from "videobook-engine";
+import { logger } from "./logger.js";
+import { queue } from "./queue.js";
+import { scheduleMediaDurationBackfill, scheduleVideoProxyAssessment, } from "./jobs/assess-media-probes.js";
+import { videoProxyAssessmentMatches, videoProxyMetadataMatches, } from "./video-proxy.js";
+export const PARTIAL_DOWNLOAD_RE = /\.(mp4|mov)\.part$/i;
+const DURATION_PROBE_EXT_RE = /\.(mp4|mov|webm|mkv|mp3|wav|m4a|aac|ogg|flac)$/i;
+const IMAGE_FILE_RE = /\.(jpg|jpeg|png|webp|gif)$/i;
+export function findAssetMediaFile(files, asset) {
+    return asset.kind === "audio"
+        ? findAudioFile(files, asset.kind)
+        : asset.kind === "video"
+            ? findVideoFile(files.filter((file) => file.name !== "proxy.mp4"))
+            : findPrimaryMediaFile(files, asset.kind);
+}
+// Content fingerprint for cache-busting media URLs. Pure function of the
+// manifest tuples; partial downloads are excluded because their size grows on
+// every poll while no served URL points at them.
+function computeAssetFingerprint(files) {
+    const settled = files.filter((f) => !PARTIAL_DOWNLOAD_RE.test(f.name));
+    if (settled.length === 0)
+        return "";
+    const sorted = [...settled].sort((a, b) => a.name.localeCompare(b.name));
+    const hash = createHash("sha1");
+    for (const f of sorted) {
+        hash.update(f.name);
+        hash.update("\0");
+        hash.update(String(f.sizeBytes ?? 0));
+        hash.update("\0");
+        hash.update(f.objectHash);
+        hash.update("\0");
+    }
+    return hash.digest("hex").slice(0, 12);
+}
+export function indexByArtifactId(rows) {
+    const map = new Map();
+    for (const row of rows)
+        map.set(row.artifactId, row);
+    return map;
+}
+export function groupByArtifactId(rows) {
+    const map = new Map();
+    for (const row of rows) {
+        const list = map.get(row.artifactId);
+        if (list)
+            list.push(row);
+        else
+            map.set(row.artifactId, [row]);
+    }
+    return map;
+}
+function streamSeconds(stream) {
+    return stream.durationTicks * stream.timeBase.numerator / stream.timeBase.denominator;
+}
+export function assetStreamProfile(streams, meta) {
+    const videoStream = streams.find((stream) => stream.kind === "video" && stream.video);
+    const audioStream = streams.find((stream) => stream.kind === "audio" && stream.audio);
+    const frameRate = videoStream?.video?.averageFrameRate
+        ?? videoStream?.video?.nominalFrameRate;
+    const streamDuration = videoStream ? streamSeconds(videoStream) : 0;
+    const metadataDuration = Number(meta?.duration);
+    const sourceDuration = streamDuration > 0
+        ? streamDuration
+        : Number.isFinite(metadataDuration) ? metadataDuration : 0;
+    const sourceProfile = sourceDuration > 0
+        ? {
+            videoDuration: sourceDuration,
+            avgFps: frameRate ? frameRate.numerator / frameRate.denominator : null,
+            hasAudio: audioStream !== undefined || meta?.hasAudio === true,
+        }
+        : null;
+    return { videoStream, audioStream, frameRate, sourceProfile };
+}
+function isActiveWork(work) {
+    return work !== null && (work.status === "pending" || work.status === "working");
+}
+export function servedVideoProxyFile(input) {
+    if (input.artifact.kind !== "video" || !input.mediaFile)
+        return null;
+    const proxyFile = input.files.find((file) => file.name === "proxy.mp4");
+    if (!proxyFile)
+        return null;
+    const metadata = input.proxyMetadata;
+    if (metadata.ok && videoProxyMetadataMatches(metadata.value, input.mediaFile, proxyFile)) {
+        return proxyFile;
+    }
+    const assessed = metadata.ok
+        && videoProxyAssessmentMatches(metadata.value, input.mediaFile, proxyFile);
+    if (!assessed && !isActiveWork(input.work) && input.sourceProfile) {
+        scheduleVideoProxyAssessment({
+            bookId: input.bookId,
+            artifactId: input.artifact.artifactId,
+            sourceFile: input.mediaFile,
+            proxyFile,
+            sourceProfile: input.sourceProfile,
+        });
+    }
+    return null;
+}
+export function assetDuration(input) {
+    const stored = input.meta?.duration;
+    if (typeof stored === "number")
+        return stored;
+    const stream = input.profile.videoStream ?? input.profile.audioStream;
+    const measured = stream ? streamSeconds(stream) : 0;
+    if (measured > 0)
+        return measured;
+    if (input.meta && input.mediaFile && DURATION_PROBE_EXT_RE.test(input.mediaFile.name)) {
+        scheduleMediaDurationBackfill({
+            bookId: input.bookId,
+            artifactId: input.artifactId,
+            mediaFile: input.mediaFile,
+        });
+    }
+    return null;
+}
+function mediaCacheBust(kind, files, mediaFile) {
+    if (kind === "video" || kind === "image") {
+        const fingerprint = computeAssetFingerprint(files);
+        return fingerprint ? `?v=${fingerprint}` : "";
+    }
+    const mediaHash = mediaFile?.objectHash;
+    return mediaHash ? `?v=${mediaHash.slice(0, 12)}` : "";
+}
+export function assetMediaUrls(input) {
+    const { artifact, files } = input;
+    const base = `/files/${input.bookId}/${artifact.artifactId}`;
+    const cacheBust = mediaCacheBust(artifact.kind, files, input.mediaFile);
+    const characterImage = artifact.kind === "character"
+        ? files.find((file) => IMAGE_FILE_RE.test(file.name)) ?? null
+        : null;
+    const served = characterImage ?? input.proxyFile ?? input.mediaFile;
+    const media_url = served ? `${base}/${served.name}${cacheBust}` : null;
+    if (characterImage)
+        return { media_url, thumbnail_url: media_url };
+    const hasThumbnail = files.some((file) => file.name === "original.jpg");
+    const thumbnail_url = hasThumbnail
+        ? `${base}/original.jpg${cacheBust}`
+        : artifact.kind === "image" ? media_url : null;
+    return { media_url, thumbnail_url };
+}
+export async function scheduleMissingVideoPoster(engine, input) {
+    const { artifact, mediaFile } = input;
+    if (artifact.kind !== "video" || input.status !== "ready" || !mediaFile)
+        return;
+    if (input.files.some((file) => file.name === "original.jpg"))
+        return;
+    const recovery = await engine.metadata.artifacts.read(artifact.artifactId, "poster-recovery");
+    if (recovery.ok && recovery.value.failed && recovery.value.sourceHash === mediaFile.objectHash)
+        return;
+    void queue.enqueue(`extract-video-poster-${input.bookId}-${artifact.artifactId}-${mediaFile.objectHash}`, {
+        type: "extract_video_poster",
+        bookId: input.bookId,
+        posterArtifactId: artifact.artifactId,
+        sourceFilename: mediaFile.name,
+        sourceHash: mediaFile.objectHash,
+    }).catch((error) => {
+        logger.error("poster-enqueue-failed", { assetId: artifact.artifactId, error });
+    });
+}

package/dist/command-reference.js

@@ -90,7 +90,7 @@ export function renderGenerationModels() {
 
 Generated by \`npm run docs:commands\` from the media catalog (\`server/src/media/catalog.ts\`). Call \`generate_image\`, \`generate_video\` or \`generate_audio\` with one of these model ids; \`list_generation_models\` returns the same list with every option, enum, range and default read from the apicity schemas.
 
-Image and video pickers rank exact catalog endpoints using the committed top-10 snapshots in @apicity/cost 0.17.1, originally sourced from Artificial Analysis. No leaderboard is fetched at runtime. Rankings are per operation: t2i, i2i, t2v, i2v, v2v, and r2v (derived from the text/image-to-video boards). Each ranked option shows rank, Elo, and a bundled price label; prices are indicative ranges, not a quote for the selected settings.
+Image and video pickers rank exact catalog endpoints using the committed top-10 snapshots in @apicity/cost 0.18.1, originally sourced from Artificial Analysis. No leaderboard is fetched at runtime. Rankings are per operation: t2i, i2i, t2v, i2v, v2v, and r2v (derived from the text/image-to-video boards). Each ranked option shows rank, Elo, and a bundled price label; prices are indicative ranges, not a quote for the selected settings.
 
 Configured frontier models appear first; other models retain their existing order in a separate group. Providers without credentials are marked unavailable. Saved selections and defaults stay unchanged. Catalog variants on a frontier board are included even if previously hidden; non-frontier hidden variants remain hidden. A model version or lite variant never inherits another endpoint's score.
 
@@ -98,6 +98,8 @@ Kling 4 supports text, frames, references and video editing; it appears in the u
 
 HeyGen Avatar 3 and 4 digital twins are text-to-video with a stock avatar (Abigail Office Front) and voice (Ivy); the prompt is the spoken script. Avatar 5 uses the SDK defaults Abigail Sofa Front and Warm Pro Narrator. Avatar 4 image-to-video animates an image with the script and defaults to Ivy. Connected audio overrides speech synthesis. Video Agent v2 and v3 accept a production prompt. HeyGen lipsync, translation, filler-word removal, HeyGen Voice TTS and Ideogram vector endpoints are outside this catalog addition.
 
+Kie Kling 4.0 reference-to-video and keyframe-to-video, PixVerse V6 Max text-to-video and image-to-video, and OmniHuman 2.0 are on no top-10 board, so they appear in the unranked group. Kling 4.0 prompts name connected media as Kling 4.0 documents them: \`@image_1\` and \`@video_1\` for references, \`@first_frame\`, \`@keyframe_1\` and \`@last_frame\` for frames; with no media connected, both endpoints generate from the prompt alone. PixVerse V6 Max image-to-video follows the image's aspect ratio. OmniHuman 2.0 renders as long as its driving audio. The Kie Grok Imagine Video 1.5 preview takes first and last frames, a loop image (\`loop_url\`) and up to four timed \`keyframes\`, and shares the Grok Imagine Video 1.5 image-to-video ranking.
+
 Top-10 coverage policy: every registry endpoint must map exactly to a catalog entry or appear in the known gaps below. Models with no provider endpoint in the registry: ${unmapped.join(", ")}. Catalog gaps do not imply provider API support is missing; adding those endpoints is separate work.
 
 | Known endpoint gap | Reason |

package/dist/diagnostics.js

@@ -14,7 +14,7 @@ const EVENTS = [
     "process-video-enqueue-failed", "waveform-write-failed", "timeline-reencode",
     "pad-video-started", "video-analysis-failed", "description-truncated",
     "description-cache-failed", "watermark-placement-fallback", "waveform-enqueue-failed",
-    "poster-enqueue-failed",
+    "poster-enqueue-failed", "proxy-assessment-enqueue-failed", "duration-backfill-enqueue-failed",
     "watermark-probe-fallback", "generation-error-clear-failed", "timeline-orientation-failed",
     "generation-cost-estimate", "job-error", "semantic-index-deferred",
     "tag-asset-failed", "voice-session-closed", "alive-captions-regions-failed",

package/dist/generation-reference-mentions.js

@@ -65,6 +65,25 @@ export function rewriteSeedanceAssetMentions(prompt, refs) {
     }
     return replaceNotebookMentions(prompt, replacements);
 }
+function numberedMentions(refs, marker) {
+    return refMentionEntries(refs).map(({ ref, index }) => ({
+        reference: ref,
+        replacement: `@${marker}_${index + 1}`,
+    }));
+}
+export function rewriteKling4ReferenceMentions(prompt, imageRefs, videoRefs) {
+    return replaceNotebookMentions(prompt, [
+        ...numberedMentions(imageRefs, "image"),
+        ...numberedMentions(videoRefs, "video"),
+    ]);
+}
+export function rewriteKling4FrameMentions(prompt, frames) {
+    return replaceNotebookMentions(prompt, [
+        ...frames.first.slice(0, 1).map((reference) => ({ reference, replacement: "@first_frame" })),
+        ...numberedMentions(frames.keyframes, "keyframe"),
+        ...frames.last.slice(0, 1).map((reference) => ({ reference, replacement: "@last_frame" })),
+    ]);
+}
 export function rewriteViduReferenceMentions(prompt, imageRefs, audioRefs) {
     return replaceNotebookMentions(prompt, [
         ...refMentionEntries(imageRefs).map(({ ref, index }) => ({

package/dist/goal-plan-v3.js

@@ -4,6 +4,8 @@ import { goalPromptWords } from "./goal-prompt-budget.js";
 import { LIGHTNING_COLD_OPEN_SECONDS, LIGHTNING_SCENE_ASPECT_RATIO, LIGHTNING_SCENE_MODEL, LIGHTNING_SCENE_OUTPUT_FORMAT, LIGHTNING_SCENE_PROMPT_WORDS, LIGHTNING_SCENE_RESOLUTION, LIGHTNING_VIDEO_DURATION_SECONDS, LIGHTNING_VIDEO_GENERATE_AUDIO, LIGHTNING_VIDEO_OUTPUT_FORMAT, LIGHTNING_VIDEO_PROMPT_WORDS, LIGHTNING_VIDEO_RESOLUTION, LIGHTNING_VIDEO_MODEL, LIGHTNING_WATERMARK_PROFILE, preservedPrompt, } from "./lightning-defaults.js";
 const IMAGE_LIMIT = 30;
 const VIDEO_LIMIT = 10;
+const LEGACY_SCENE_RESOLUTION = "2K";
+const SCENE_RESOLUTIONS = [LEGACY_SCENE_RESOLUTION, "4K"];
 export const goalMediaRefSchema = z.object({
     kind: z.enum(["image", "video"]),
     artifactId: z.string().min(1),
@@ -22,7 +24,7 @@ export const goalPlanV3Schema = z.object({
         tool: z.literal("generate_image"),
         model: z.literal(LIGHTNING_SCENE_MODEL),
         aspectRatio: z.enum(["16:9", "9:16", "1:1"]),
-        resolution: z.literal(LIGHTNING_SCENE_RESOLUTION),
+        resolution: z.enum(SCENE_RESOLUTIONS),
         outputFormat: z.literal(LIGHTNING_SCENE_OUTPUT_FORMAT),
         imageRefs: z.array(goalMediaRefSchema).max(IMAGE_LIMIT),
     }).strict(),
@@ -59,6 +61,14 @@ export const goalPlanV3Schema = z.object({
         }).strict(),
     }).strict(),
 }).strict();
+function withLegacySceneResolution(plan) {
+    if (typeof plan !== "object" || plan === null || !("version" in plan) || plan.version !== 3)
+        return plan;
+    if (!("scene" in plan) || typeof plan.scene !== "object" || plan.scene === null || "resolution" in plan.scene)
+        return plan;
+    return { ...plan, scene: { ...plan.scene, resolution: LEGACY_SCENE_RESOLUTION } };
+}
+export const savedGoalPlanV3Schema = z.preprocess(withLegacySceneResolution, goalPlanV3Schema);
 export function isGoalPlanV3(plan) {
     return plan?.version === 3;
 }

package/dist/goal-plan.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { LIGHTNING_VIDEO_MODEL } from "./lightning-defaults.js";
 import { GOAL_PROMPT_BUDGET, goalPromptWords } from "./goal-prompt-budget.js";
 import { GOAL_STYLE_IDS, goalStyleFragment, resolveGoalStyleOptions } from "./goal-styles.js";
-export { compileGoalV3Approval, compileGoalV3Steps, goalMediaRefSchema, goalPlanV3Schema, isGoalPlanV3, refreshGoalPlanV3 } from "./goal-plan-v3.js";
+export { compileGoalV3Approval, compileGoalV3Steps, goalMediaRefSchema, goalPlanV3Schema, isGoalPlanV3, refreshGoalPlanV3, savedGoalPlanV3Schema } from "./goal-plan-v3.js";
 export { GOAL_PROMPT_BUDGET, goalPromptWords } from "./goal-prompt-budget.js";
 export const GOAL_VIDEO_TOOL = "generate_video";
 export const GOAL_VIDEO_MODEL = LIGHTNING_VIDEO_MODEL;

package/dist/goal-store.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { firstEmptyNotebookGridSlot, notebookOccupiedSlots } from "videobook-engine/notebook-grid";
-import { goalMediaRefSchema, goalPlanSchema, goalPlanV3Schema, goalStyleSchema, legacyGoalPlanSchema } from "./goal-plan.js";
+import { goalMediaRefSchema, goalPlanSchema, goalStyleSchema, legacyGoalPlanSchema, savedGoalPlanV3Schema } from "./goal-plan.js";
 import { mutateNotebook } from "./notebook-mutations.js";
 import { arrangeGoalNotebook } from "./notebook-goal-layout.js";
 const KEY = "application.goals.v2";
@@ -68,7 +68,7 @@ function mediaFrom(value) {
 }
 export function goalContent(cell) {
     const inputs = cell.inputs ?? {};
-    const plan = z.union([goalPlanV3Schema, goalPlanSchema, legacyGoalPlanSchema]).safeParse(inputs.plan);
+    const plan = z.union([savedGoalPlanV3Schema, goalPlanSchema, legacyGoalPlanSchema]).safeParse(inputs.plan);
     const requestedStyle = goalStyleSchema.safeParse(inputs.requestedStyle);
     const media = mediaFrom(inputs.media);
     return {

package/dist/har-capture.js

@@ -4,6 +4,7 @@ import { createHarCapture } from "@apicity/har";
 import { currentBookContext } from "./book-context.js";
 import { harDirectory, readHarSettings } from "./har-settings.js";
 import { logger } from "./logger.js";
+const localFailures = new AsyncLocalStorage();
 const pending = new Set();
 let maintenance = Promise.resolve();
 export async function maintainHarCaptures(operation) {
@@ -51,11 +52,36 @@ export async function withHarCapture(meta, operation, base = globalThis.fetch, c
     try {
         return await runCapture(meta, operation, base, context);
     }
+    catch (error) {
+        localFailures.getStore()?.add(error);
+        throw error;
+    }
     finally {
         finish();
         pending.delete(finished);
     }
 }
+export async function withHarLocalFailure(meta, operation) {
+    const failures = localFailures.getStore() ?? new Set();
+    return localFailures.run(failures, async () => {
+        try {
+            return await operation();
+        }
+        catch (error) {
+            const seen = new Set();
+            let cause = error;
+            while (!seen.has(cause)) {
+                if (failures.has(cause))
+                    throw error;
+                seen.add(cause);
+                if (!(cause instanceof Error) || cause.cause === undefined)
+                    break;
+                cause = cause.cause;
+            }
+            return withHarCapture(meta, () => { throw error; });
+        }
+    });
+}
 async function runCapture(meta, operation, base, context) {
     const settings = await readHarSettings();
     if (settings.mode === "off")
@@ -99,8 +125,15 @@ async function runCapture(meta, operation, base, context) {
     }
 }
 const HTTP_METHODS = new Set(["get", "post", "put", "patch", "delete", "head", "options"]);
-function endpointDotPath(path) {
-    return (path.length > 1 && HTTP_METHODS.has(path[0] ?? "") ? path.slice(1) : path).join(".");
+const SDK_ONLY_NAMESPACES = new Map([["kie", new Set(["veo", "suno"])]]);
+function endpointDotPath(provider, path) {
+    const [head = "", next = ""] = path;
+    if (path.length > 1 && HTTP_METHODS.has(head))
+        return path.slice(1).join(".");
+    if (path.length < 3 || !HTTP_METHODS.has(next))
+        return path.join(".");
+    const rest = path.slice(2);
+    return (SDK_ONLY_NAMESPACES.get(provider)?.has(head) ? rest : [head, ...rest]).join(".");
 }
 const providerCalls = new WeakMap();
 export function withProviderCall(provider, meta, operation) {
@@ -119,7 +152,7 @@ export function capturedProvider(provider, factory, base = globalThis.fetch) {
     function wrap(target, path) {
         return new Proxy(target, {
             apply(fn, receiver, args) {
-                return withHarCapture({ provider, endpoint: endpointDotPath(path), input: args.length === 1 ? args[0] : args }, (fetch) => transports.run(fetch, () => Reflect.apply(fn, receiver, args)), base);
+                return withHarCapture({ provider, endpoint: endpointDotPath(provider, path), input: args.length === 1 ? args[0] : args }, (fetch) => transports.run(fetch, () => Reflect.apply(fn, receiver, args)), base);
             },
             get(object, property, receiver) {
                 const value = Reflect.get(object, property, receiver);

package/dist/jobs/_image-edit-adapter.js

@@ -99,6 +99,7 @@ function kieImageEditAdapter(model, build) {
     });
     return {
         id: model.apiId,
+        envKey: "KIE_API_KEY",
         uploadAsset: (engine, artifactId, filename) => uploadAssetToKie(engine, artifactId, filename),
         buildSemanticRequest: (input) => buildRequest({ ...input, imageUrls: [input.imageUrls[0]] }),
         buildRegionRequest: buildRequest,
@@ -166,6 +167,7 @@ function falImageEditAdapter(model) {
     const buildRequest = (input) => toProviderRequest(model.apiId, catalogEditRequest(model, input));
     return {
         id: model.apiId,
+        envKey: "FAL_API_KEY",
         uploadAsset: (engine, artifactId, filename) => uploadAssetToFal(engine, artifactId, filename),
         buildSemanticRequest: (input) => buildRequest({ ...input, imageUrls: [input.imageUrls[0]] }),
         buildRegionRequest: buildRequest,

package/dist/jobs/assess-media-probes.js

@@ -0,0 +1,94 @@
+import { join } from "node:path";
+import { probeVideo } from "../ffmpeg.js";
+import { logger } from "../logger.js";
+import { queue, registerJobHandler } from "../queue.js";
+import { invalidVideoProxyMetadata, probeStoredVideoFile, videoProxyAssessmentMatches, videoProxyMetadata, videoProxyValidationError, } from "../video-proxy.js";
+const PROXY_FILENAME = "proxy.mp4";
+export function scheduleVideoProxyAssessment(input) {
+    const jobId = `assess-video-proxy-${input.bookId}-${input.artifactId}-${input.proxyFile.objectHash}`;
+    void queue.enqueue(jobId, {
+        type: "assess_video_proxy",
+        bookId: input.bookId,
+        proxyAssetId: input.artifactId,
+        sourceFilename: input.sourceFile.name,
+        sourceHash: input.sourceFile.objectHash,
+        proxyHash: input.proxyFile.objectHash,
+        sourceProfile: input.sourceProfile,
+    }).catch((error) => {
+        logger.error("proxy-assessment-enqueue-failed", { assetId: input.artifactId, error });
+    });
+}
+export function scheduleMediaDurationBackfill(input) {
+    const jobId = `backfill-media-duration-${input.bookId}-${input.artifactId}-${input.mediaFile.objectHash}`;
+    void queue.enqueue(jobId, {
+        type: "backfill_media_duration",
+        bookId: input.bookId,
+        durationAssetId: input.artifactId,
+        mediaFilename: input.mediaFile.name,
+        mediaHash: input.mediaFile.objectHash,
+    }).catch((error) => {
+        logger.error("duration-backfill-enqueue-failed", { assetId: input.artifactId, error });
+    });
+}
+async function currentFile(engine, artifactId, name, objectHash) {
+    const manifest = await engine.files.manifest(artifactId);
+    if (!manifest.ok)
+        return null;
+    return manifest.value.files.find((file) => file.name === name && file.objectHash === objectHash) ?? null;
+}
+export async function assessStoredVideoProxy(engine, assetId, sourceFile, proxyFile, sourceProfile) {
+    let assessment;
+    try {
+        const proxy = await probeStoredVideoFile(engine, assetId, proxyFile.name);
+        const error = videoProxyValidationError(sourceProfile, proxy);
+        assessment = error
+            ? invalidVideoProxyMetadata(sourceFile, proxyFile, error)
+            : videoProxyMetadata(sourceFile, proxyFile, proxy);
+    }
+    catch (cause) {
+        const error = cause instanceof Error ? cause.message : String(cause);
+        assessment = invalidVideoProxyMetadata(sourceFile, proxyFile, error);
+    }
+    await engine.metadata.artifacts.write(assetId, "proxy", assessment);
+    return assessment.valid;
+}
+async function runVideoProxyAssessment(engine, payload) {
+    const { proxyAssetId } = payload;
+    const sourceFile = await currentFile(engine, proxyAssetId, payload.sourceFilename, payload.sourceHash);
+    const proxyFile = await currentFile(engine, proxyAssetId, PROXY_FILENAME, payload.proxyHash);
+    if (!sourceFile || !proxyFile)
+        return { skipped: true };
+    const existing = await engine.metadata.artifacts.read(proxyAssetId, "proxy");
+    if (existing.ok && videoProxyAssessmentMatches(existing.value, sourceFile, proxyFile)) {
+        return { skipped: true };
+    }
+    return {
+        valid: await assessStoredVideoProxy(engine, proxyAssetId, sourceFile, proxyFile, payload.sourceProfile),
+    };
+}
+async function runMediaDurationBackfill(engine, payload, signal) {
+    const { durationAssetId } = payload;
+    const metadata = await engine.metadata.artifacts.read(durationAssetId, "original");
+    if (!metadata.ok || typeof metadata.value.duration === "number")
+        return { skipped: true };
+    if (!await currentFile(engine, durationAssetId, payload.mediaFilename, payload.mediaHash)) {
+        return { skipped: true };
+    }
+    const dir = await engine.workspaces.resolveArtifact(durationAssetId);
+    if (!dir.ok)
+        throw new Error(`backfill_media_duration: ${dir.error.message}`);
+    const probe = await probeVideo(join(dir.value, payload.mediaFilename), { signal });
+    if (!Number.isFinite(probe.duration) || probe.duration <= 0)
+        return { skipped: true };
+    const written = await engine.metadata.artifacts.write(durationAssetId, "original", {
+        ...metadata.value,
+        duration: probe.duration,
+    });
+    if (!written.ok)
+        throw new Error(written.error.message);
+    return { duration: probe.duration };
+}
+export function registerAssessMediaProbeJobs(engine) {
+    registerJobHandler("assess_video_proxy", async (payload) => runVideoProxyAssessment(engine, payload));
+    registerJobHandler("backfill_media_duration", async (payload, { signal }) => runMediaDurationBackfill(engine, payload, signal));
+}

package/dist/jobs/complete-provider-task.js

@@ -1,4 +1,3 @@
-import { withHarCapture } from "../har-capture.js";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { writeFile, unlink, readFile as readFsFile } from "node:fs/promises";
@@ -48,9 +47,7 @@ async function reclaimFailedCompletion(engine, task, ctx) {
     return lease.ownerId;
 }
 export function registerCompleteProviderTaskJob(engine) {
-    registerJobHandler("complete_kie_task", async (payload, ctx) => withHarCapture({
-        provider: String(payload.taskType).split("_")[0] ?? "unknown", endpoint: "generation.complete", input: payload,
-    }, async () => {
+    registerJobHandler("complete_kie_task", async (payload, ctx) => {
         const { taskId, taskType, assetId, bookId, meta, resultUrls, resultObject, } = payload;
         // Pattern C: inherit the provider lease via getOwner, abort if the row
         // already terminated, and register the lease so the wrapper's catch path
@@ -128,7 +125,7 @@ export function registerCompleteProviderTaskJob(engine) {
             clearInterval(heartbeat);
             await engine.jobs.locks.release(assetDir);
         }
-    }, globalThis.fetch, { providerTaskId: payload.taskId, model: payload.meta.model, runId: payload.meta.runId, attemptId: payload.meta.attemptId }));
+    });
 }
 async function mediaOutputs(taskType, taskId, urls) {
     if (taskType === MEDIA_TASK_TYPES.machgen)

package/dist/jobs/generate-media.js

@@ -1,4 +1,5 @@
-import { withHarCapture } from "../har-capture.js";
+import { withHarLocalFailure } from "../har-capture.js";
+import { generationHarEndpoint } from "../media/har-endpoint.js";
 import { withBookContext } from "../book-context.js";
 import { isSeedanceEdit } from "../media/seedance-edit.js";
 import { registerJobHandler } from "../queue.js";
@@ -87,7 +88,7 @@ async function generateMedia(engine, job, ctx) {
 }
 export async function runGenerateMedia(engine, job, ctx) {
     return withBookContext({ bookId: job.bookId, engine, operation: "generate_media", artifactId: job.assetId,
-        attemptId: job.generationId ?? job.assetId, runId: job.runId, model: job.model }, () => withHarCapture({ provider: resolveModel(job.model).provider, endpoint: "generation.submit", input: job }, () => generateMedia(engine, job, ctx)));
+        attemptId: job.generationId ?? job.assetId, runId: job.runId, model: job.model }, () => withHarLocalFailure({ provider: resolveModel(job.model).provider, endpoint: generationHarEndpoint(resolveModel(job.model)), input: job }, () => generateMedia(engine, job, ctx)));
 }
 export function registerGenerateMediaJob(engine) {
     registerJobHandler("generate_media", (payload, ctx) => runGenerateMedia(engine, payload, ctx));

package/dist/jobs/image-subjects.js

@@ -4,6 +4,7 @@ import sharp from "sharp";
 import { KIE_RESULT_TIMEOUT_MS, kieProvider, parseResultUrls, waitForKieResult, } from "./_kie-poll.js";
 import { GROK_EXACT_MASK_ADAPTER_ID, imageEditAdapter, IMAGE_EDIT_ADAPTERS, } from "./_image-edit-adapter.js";
 import { DEFAULT_IMAGE_EDIT_MODEL_ID } from "../image-edit-models.js";
+import { requireApiKey } from "../api-key.js";
 import { compositeImageRegionEdit, imageRegionEditPrompt } from "../image-region-edit.js";
 import { IMAGE_SUBJECT_MAP_VERSION, applyGrokSegmentsToSubjects, composeImageSubjectRemoval, exactEditMaskIndexes, grokMaskIndex, parseGrokSegmentMapResult, persistSeedreamSubjectLayers, readImageSubjectMapRecord, resolveImageSubjectSource, writeCurrentImageSubjectAnalysisRecord, } from "../image-subject-map.js";
 import { enqueueSearchIndex } from "./enqueue-search-index.js";
@@ -534,6 +535,7 @@ export async function previewImageSubjectEditRequest(engine, payload, imageUrls)
         : adapter.buildSemanticRequest(input);
 }
 async function runAdapterImageSubjectEdit(engine, payload, adapter, route, prepared, sourceFilename, signal) {
+    requireApiKey(adapter.envKey);
     const stored = await readStoredImageSubjectEditTask(engine, payload.imageAssetId);
     const storedMatch = stored?.adapterId === adapter.id ? stored : null;
     let request = storedMatch?.request ?? null;

package/dist/jobs/kie-paygate.js

@@ -1,4 +1,4 @@
-import { withHarCapture } from "../har-capture.js";
+import { withHarLocalFailure } from "../har-capture.js";
 import { createKie } from "../usage-providers.js";
 import { submitMediaJob } from "../usage-providers.js";
 import { mintOtp } from "@apicity/cost";
@@ -177,8 +177,8 @@ async function submitQueuedKieTaskInner(engine, task) {
     return writeResult.value.task;
 }
 export async function submitKieTask(engine, ctx, args) {
-    return withHarCapture({ provider: "kie", endpoint: "generation.paygate", input: args.request }, () => submitKieTaskInner(engine, ctx, args));
+    return withHarLocalFailure({ provider: "kie", endpoint: "api.v1.jobs.createTask", input: args.request }, () => submitKieTaskInner(engine, ctx, args));
 }
 export async function submitQueuedKieTask(engine, task) {
-    return withHarCapture({ provider: "kie", endpoint: "generation.queued", input: task }, () => submitQueuedKieTaskInner(engine, task));
+    return withHarLocalFailure({ provider: "kie", endpoint: "api.v1.jobs.createTask", input: task }, () => submitQueuedKieTaskInner(engine, task));
 }

package/dist/jobs/register-all.js

@@ -38,6 +38,7 @@ import { registerLabelMusicSectionsJob } from "./label-music-sections.js";
 import { registerEditingMomentsJob } from "./analyze-editing-moments.js";
 import { registerExtractWaveformJob } from "./extract-waveform.js";
 import { registerExtractVideoPosterJob } from "./extract-video-poster.js";
+import { registerAssessMediaProbeJobs } from "./assess-media-probes.js";
 import { registerReplaceVideoAudioJob } from "./replace-video-audio.js";
 import { registerSpliceVideoJob } from "./splice-video.js";
 import { registerSmoothSceneConcatJob } from "./smooth-scene-concat.js";
@@ -109,6 +110,7 @@ export function registerAllJobHandlers(engine, books = bookManager) {
     registerExtractAudioJob(engine);
     registerExtractWaveformJob(engine);
     registerExtractVideoPosterJob(engine);
+    registerAssessMediaProbeJobs(engine);
     registerAnalyzeMusicJob(engine);
     registerPlanGoalJob(engine);
     registerAssembleGoalJob(engine);