fal: typed image/video helpers + queue polling realism

[tombeckenham]

Closes #170.

This branch was originally written against the pre-#152 fal handler. Upstream landed the general handler with host-aware routing and RawJSONResponse support before I opened the PR, so I've rebased and trimmed the scope to what's still missing: typed helpers and queue polling realism.

What

1. Typed helpers — onFalImage / onFalVideo

The current onFalQueue(modelOrPrompt, response: unknown, opts?) takes opaque JSON. Callers building fal mocks against the real wire shape hand-write the envelope every time:

// image:
{ images: [{ url, width, height, content_type }], timings, seed, has_nsfw_concepts, prompt }
// video:
{ video: { url, content_type, file_name, file_size }, seed }

This PR adds two helpers that accept the same ImageResponse / VideoResponse shapes used by onImage / onVideo and translate to fal's wire shape under the hood:

mock.onFalImage(/flux/, { images: [{ url: "https://mock.fal.media/x.png" }] });
mock.onFalVideo(/kling/, { video: { id: "v1", status: "completed", url: "https://mock.fal.media/clip.mp4" } });

Both delegate to onFalQueue so recording, matching, and lifecycle behavior stay identical.

2. Queue polling realism

falQueueStates always stores jobs as COMPLETED on submit (src/fal.ts pre-PR line 421). Production code that polls /status and reacts to IN_QUEUE / IN_PROGRESS (e.g. queue position decay, log streaming, latency metrics) can't be exercised end-to-end against aimock today.

Opt in with MockServerOptions.falQueue: { pollsBeforeInProgress, pollsBeforeCompleted }:

• Submit creates the job in IN_QUEUE (when thresholds > 0) with queue_position.
• Each /status (or /{id}) poll advances IN_QUEUE → IN_PROGRESS → COMPLETED.
• Status response includes logs: [{ timestamp, level, message }] (one entry per transition) and metrics.inference_time (wall-clock elapsed since submit) once COMPLETED.
• Cancel before completion → 200 { status: "CANCELLED" }; cancel after → 400 { status: "ALREADY_COMPLETED" } (unchanged).
• Result fetch before completion → 202 with current status body.

Defaults preserve existing behavior: both thresholds default to 0 so unconfigured mocks still report COMPLETED on submit, no test churn.

Out of scope (already shipped or follow-up)

• Hostname-aware routing (x-fal-target-host) — already in upstream fal.ts.
• rest.alpha.fal.ai/storage/upload/initiate — already in upstream fal.ts.

Test plan

• 8 new cases in src/__tests__/fal.test.ts: image lifecycle, video lifecycle, sync run with image envelope, polling IN_QUEUE → IN_PROGRESS → COMPLETED with logs[] + metrics.inference_time, result-before-complete (202), cancel-before-complete (CANCELLED), cancel-after-complete (ALREADY_COMPLETED), ImageItem URL fallback.
• pnpm test — 2849 passed, 37 skipped, no regressions.
• pnpm run format:check clean.
• pnpm run lint clean.

Files

• src/fal.ts — typed-response converters (imageResponseToFalJson, videoResponseToFalJson); queue progression state machine (advanceJob, queuePosition, statusResponseBody); FalQueueJob extended with pollCount, pollsBeforeInProgress, pollsBeforeCompleted, submittedAt, completedAt, logs.
• src/llmock.ts — onFalImage, onFalVideo.
• src/types.ts — FalQueueConfig; MockServerOptions.falQueue; HandlerDefaults.falQueue.
• src/server.ts — propagate falQueue to handler defaults.
• src/__tests__/fal.test.ts — new describe block for typed helpers + polling.
• docs/fal-ai/index.html — new sections "Typed Helpers" and "Polling Realism"; queue lifecycle table now mentions logs/metrics/CANCELLED.
• README.md — fal.ai added to the Multimedia APIs line.

---

Follow-up: 15 min queue-walk default (commit 723fa5c)

Bumped DEFAULT_FAL_TIMEOUT_MS from 2 min → 15 min. Video generations (kling, veo, runway, etc.) routinely take 5–10 minutes on the upstream queue; the prior default was tripping legitimate recording flows mid-walk. Callers needing a tighter budget can still override via record.fal.timeoutMs. Existing recorder tests pin their own timeoutMs (2000/5000ms) so the bumped default is exercised only via callers that omit it. pnpm test now: 3013 passed.

Verification

Verified end-to-end against the OpenStory app — recording a kling-video/v3/pro image-to-video job now completes the queue walk and persists the final job body as expected.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@copilotkit/aimock@171

commit: 25c4cd6

[jpr5]

CR Review — 7-agent round, 4 findings fixed

Nice contribution @tombeckenham — the queue polling realism is a solid addition. We ran a full 7-agent CR pass and found 4 bugs that need fixing before merge. I've prepared the fixes but couldn't push to your fork (permissions). Here's what needs to change, all in src/fal.ts:

1. IN_PROGRESS state skipped when only pollsBeforeInProgress is set

resolveProgression defaults pollsBeforeCompleted to Math.max(pollsBeforeInProgress, 0), making both thresholds equal. Then advanceJob checks COMPLETED before IN_PROGRESS, so the job jumps IN_QUEUE → COMPLETED, never passing through IN_PROGRESS.

Fix: Default pollsBeforeCompleted to pollsBeforeInProgress + 1 when not explicitly set. Reverse the check order in advanceJob — check IN_PROGRESS first, COMPLETED second.

2. imageItemToFalImage / videoResponseToFalJson produce invalid MIME types

url.split(".").pop() splits on ALL dots including hostname dots. For https://example.com/image, produces "com/image" → content_type: "image/com/image". Also doesn't strip URL fragments.

Fix: Extract the last path segment first (url.split("?")[0].split("#")[0].split("/").pop()), then find the extension via lastIndexOf(".").

3. Double-cancel pushes duplicate log entry

No guard for already-CANCELLED state — repeated cancel calls accumulate spurious "Job cancelled." logs.

Fix: Add if (job.status === "CANCELLED") guard returning 200 with { status: "CANCELLED" } without another log push.

4. parseBody silently returns null on malformed JSON

Fal queue submit/sync-run silently degrades to empty prompt instead of returning 400. Inconsistent with every other handler in the codebase.

Fix: Have parseBody throw on parse failure, catch in the submit/run handler and return 400 with error detail.

---

I have a commit with all 4 fixes ready — if you enable maintainer edits or want me to push it a different way, let me know. Otherwise you can apply the changes yourself from the descriptions above. All 2849 tests still pass after the fixes.

[jpr5]

Note on maintainer edits

We tried to push our fix commits directly to your PR branch but hit a known GitHub platform limitation: "Allow edits from maintainers" is silently ignored for organization-owned forks (community discussion #5634, #9921). Your fork lives under openstory-so (an org), so GitHub reports maintainerCanModify: true on the API but never actually grants push access — regardless of token type, scopes, or SSH config.

For future PRs: if you fork from your personal account (tombeckenham/aimock) instead of the org (openstory-so/aimock-openstory), maintainer edits will work and we can push fixes directly to your branch during CR. This speeds up the review cycle significantly.

For this PR, you can apply the 4 fixes from the review above, or let us know and we'll cherry-pick your commit onto a CopilotKit-owned branch and open a replacement PR with the fixes included (crediting your original commit).

[tombeckenham]

Good point. Let me move this. I was half way through this. Thanks for being proactive

[tombeckenham]

Thanks for the thorough review! Pushed 37dd3fb addressing all four issues:

1. IN_PROGRESS skipped when only pollsBeforeInProgress is set (src/fal.ts:165, 184)

• resolveProgression now defaults pollsBeforeCompleted to pollsBeforeInProgress + 1 when only the in-progress threshold is explicitly set (preserves the "no config = complete on submit" path when neither is set).
• Reversed the check order in advanceJob — IN_PROGRESS check runs before COMPLETED so equal thresholds still pass through IN_PROGRESS.

2. Invalid MIME types from naive URL splitting (src/fal.ts:107)

• Added extractExtension(url, fallback) helper that strips query string + fragment, takes the last path segment via split("/").pop(), then finds the extension via lastIndexOf(".").
• Both imageItemToFalImage and videoResponseToFalJson use it. https://example.com/image now produces image/png (fallback) instead of image/com/image.

3. Double-cancel duplicate log entry (src/fal.ts:436)

• Added if (job.status === "CANCELLED") guard returning 200 { status: "CANCELLED" } without appending another log entry.

4. parseBody silently returns null on malformed JSON (src/fal.ts:487, 721)

• parseBody now throws Malformed JSON: <detail> on parse failure (still returns null for empty body, unchanged).
• The submit/sync-run handler catches and returns 400 { error: { code: "invalid_json", type: "invalid_request_error", message } } — same shape used by images.ts, speech.ts, embeddings.ts, etc.

Also added 5 regression tests in src/__tests__/fal.test.ts covering each fix, updated the pollsBeforeCompleted doc-comment in types.ts, and all 3018 tests + lint + format pass.