feat: add the video job contract and provider error taxonomy

[kiyeonjeon21]

First PR of the provider interface work (step 3.3): the shared contract, with Runway moved onto it.

Why

Each video provider spoke its own dialect.
Seedance blocks inside one fal.subscribe call with no job ID, so a crash mid-wait loses a paid job.
Kling needs a task type just to poll, Gemini's cancel is a no-op, and wait methods have five different names.
Callers told a likeness rejection from a quota error by matching provider wording, which breaks silently when a provider rewords a message.
The CLI branches on provider name in 16 places in generate video alone.

What this adds

• VideoGenerator (ai-providers/src/video/contract.ts): submitVideo, getVideoJob, cancelVideoJob?, downloadVideo.
  • A VideoJob is plain, serializable data, so a job submitted in one process can be polled, resumed, or cancelled from another.
  • VideoRequest.from is where Omni multi-turn edits and Kling/Veo extension will plug in.
• ProviderError with 12 kinds and classifyProviderError. Content wording beats status codes, so a 422 likeness filter reads as likeness and a 429 "insufficient credits" reads as quota. ModelRetiredError is now one of these.
• providerRequest (ai-providers/src/shared/http.ts): one HTTP path. It retries 429/502/503/504 and network errors and honours Retry-After. Every failure becomes a classified error, and messages carry the path without the query string, so keys never leak.
• resolveVideoModel: catalog lookup and the shutdown check before any request.
• waitForVideoJob: generic polling that rides out retryable read errors, supports an abort signal, and on timeout keeps the job ID in the error.
• describeVideoContract: a reusable suite every provider must pass. It covers handles, poll and download, classified job failures, classified submit errors, model validation before any request, declared continuations, and cancel.
• Shared fake network: it moves to @vibeframe/ai-providers/testing with no test-runner dependency, and the CLI re-exports it with its build routes.
• Runway on the contract: RunwayProvider implements the contract, and its older methods wrap it, so CLI callers are unchanged until the CLI moves (PR 3).

Also

• Provider count fixed: sync-counts.sh and the website counted every folder under ai-providers/src, so catalog and shared were counted as integrations. They now count folders that contain a *Provider.ts: 14, not 16.
• Old HTTP helper kept for now: fetchJson in shared/http.ts stays until Gemini moves onto providerRequest.

Verification

• New tests:
  • Error classification: 4
  • HTTP retries and parsing: 5
  • Wait helper: 4
  • Runway contract: 9
  • Existing Runway tests unchanged: 4
• pnpm build, pnpm lint, pnpm typecheck, tests (providers 164, CLI 1215, MCP 73), pre-push gate.
• Live Runway: vibe generate video -p runway --duration 2 downloaded a 2.04 s clip (about $0.24).
• Live auth error: a bad key came back as {kind: "auth", status: 401, retryable: false} with Runway's message.

Next

PR 2 moves Kling, Grok, Seedance (onto the fal queue, so jobs survive a crash), and Omni onto the contract.
PR 3 removes the provider-name branches from the CLI.

https://claude.ai/code/session_011S1BLTaFctZNQzGERpkCuA

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
vibeframe	Ready	Preview	Oct 4, 2026 1:50pm UTC