feat: add observable and recoverable HTML animation agent runtime

[lollipop798]

Summary

This PR adds an observable and recoverable HTML animation Agent Runtime to the Open SaaS interview starter. It uses PostgreSQL and Wasp PgBoss for durable execution without introducing Redis, and treats Run state, checkpoints, budgets, alerts, and audit records as first-class platform concerns.

The user workflow now supports:

• human-in-the-loop Prompt optimization, editing, re-optimization, and explicit approval;
• immutable animation revisions and branches from any retained successful version;
• schema and AST validation, one targeted repair attempt, and sandboxed CSP preview;
• dual WebM and MP4 video export with real progress, cancellation, retry, quota, and authorized downloads;
• user-owned history plus administrator-wide monitoring and audited sensitive-content reveal.

Detailed documentation is available in English and 简体中文.

Architecture and decisions

• AgentJobQueue, PromptOptimizationQueue, AnimationVideoQueue, and VideoObjectStore keep workflow code independent from PgBoss, Local/S3 storage, and a future Redis/BullMQ worker deployment.
• Run creation, concurrency checks, and worst-path budget reservation commit together. A reconciler uses committed QUEUED rows without a PgBoss id as a transactional outbox.
• Execution is explicitly at least once. Step checkpoints, leases, singleton keys, and orphan Invocation alerts reduce and expose the remaining duplicate-provider-call window.
• The formal generator receives the exact encrypted Prompt snapshot approved by the user; it never silently optimizes again inside the generation worker.
• Revisions copy the direct parent's validated artifact into an encrypted child snapshot. This bounds model context while parentRunId and threadId preserve the complete version tree.
• Prompt, checkpoint, revision baseline, and raw provider content use AES-256-GCM. Administrator reveal requires a reason and writes an immutable audit record.
• Generated HTML, CSS, and JavaScript pass parser/AST validation before one repair attempt. Preview uses sandbox="allow-scripts" and a restrictive CSP with network access blocked.
• Chromium records the real animation to WebM and ffmpeg creates H.264/yuv420p/faststart MP4. Both objects must validate and publish before the database enters SUCCEEDED.
• Browser downloads use short-lived owner-bound tokens. Local files are streamed through an awaited Node.js pipeline; S3 returns a ten-minute signed URL after the same authorization boundary.

Validation

• npm run lint
• npm run prettier:check
• npm run typecheck
• 26 unit tests across 12 files
• 16 PostgreSQL migration, integration, authorization, and fault tests across 2 files
• Prisma schema validation
• fresh database deployment of all 3 migrations
• complete Chromium E2E covering Prompt approval, explicit Refine optimization, a no-optimization branch, video export, and version switching
• git diff --check

The deterministic Chromium E2E was completed with the local Wasp 0.24 compatibility environment before restoring the repository's declared Wasp ^0.25.0 configuration. A Wasp 0.25 compile could not be run locally because the npm registry currently publishes the CLI only through 0.24.0.

Known limitations

• Workers still share the Wasp server process and cannot scale independently yet.
• A provider response followed by a crash before checkpoint persistence can still cause duplicate billing.
• The workflow is fixed rather than a user-defined DAG and currently implements one real model provider.
• Chromium and ffmpeg increase deployment image size and rendering CPU requirements.

Follow-up work can add a Redis/BullMQ adapter, independent workers, provider fallback, webhook alerts, model evaluation, and richer video presets without changing the persisted Run and Step contracts.