render-and-return

# Render and return the video Two render paths, chosen at runtime: - **Cloud** (default) — `render_client.py` POSTs to HeyGen's render API and gets back a CDN video URL. Fast (<1 min), no install, only `api.heygen.com` needed, the user gets a shareable URL directly. - **Local** — `render_local.py` runs the `hyperframes` CLI with headless Chrome in the sandbox. Only available in the heavy "base environment" (Chrome + CLI installed). Slower (minutes, sandbox CPU) and produces a sandbox *file* (not a shareable URL on its own), but it can render compositions you authored from scratch (free composition), not just the starters. ## Inputs (from customize-composition) - `/.agents/workspace/output/composition/` — the staged composition directory (voiceover already baked in). - `/.agents/workspace/output/variables.json` — validated variable values (cloud path passes these via the API; for local, they're already substituted/used). - The chosen composition's aspect ratio (from its manifest). ## Routing — pick the path Detect the environment first: ```bash # Local is possible only if BOTH binaries resolve to a real, executable target. # `command -v` alone passes a dangling symlink — dereference + test -x. local_ok=yes for bin in hyperframes chrome-headless-shell; do p=$(command -v "$bin" 2>/dev/null) && [ -x "$(readlink -f "$p" 2>/dev/null)" ] || local_ok=no done echo "local render available: $local_ok" ``` Then decide, in priority order: 1. **User override** — prompt says "render locally" / "use local" → local (only if the env supports it; if not, say so and fall back to cloud). Prompt says "use cloud" / "cloud render" → cloud, always. 2. **Free composition** — decided by the explicit classification below (not a keyword guess). If free-composition is required AND the env supports local → local. If required but the env lacks Chrome+CLI → cloud with a degradation warning (a freely-authored composition may not render exactly right without local Chrome). 3. **Default → cloud.** Fast, no broad allowlist, shareable URL. The path for every normal starter-based video. ### Classify: is free-composition required? (explicit, not keyword-matching) Substring matching is wrong here — "kinetic-text social promo" sounds authoring-heavy but the social-promo starter already does kinetic text (no free-auth), while "animate the React useState hook with code samples" sounds simple but needs custom code-block animation (free-auth). So **make the call explicitly**: answer this in one line before routing — > *"Does this prompt require free-form HTML/CSS/GSAP authoring beyond what a > starter + its variables can express? Answer yes/no with one sentence of > reasoning."* `yes` → free-composition. `no` → a starter fits; use it (cloud). Record the answer + reasoning (it goes in the render result for debugging). **Safe default — any ambiguity routes to cloud.** If the classification is unclear, comes back malformed, times out, or you're genuinely unsure → treat it as `no` (cloud). Cloud is fast and cheap, so the bias belongs on the cheap side; never default to the expensive local path on uncertainty. Decision tree (after the classification): - user "local" AND env has Chrome+CLI → **local** - user "cloud" → **cloud** - free-composition = yes AND env has Chrome+CLI → **local** - free-composition = yes AND env missing Chrome+CLI → **cloud** + degradation warning - otherwise → **cloud** ### Token budget Local + free-composition renders are token-expensive (free-auth can burn millions of tokens — author + lint + validate + render iterations). Respect a budget: `MAX_TOKENS_PER_RENDER` (default 6,000,000 — generous; Trace free-auth burned ~3.2M). Keep a rough running sense of tokens spent; as you approach the ceiling, **stop expanding scope, wrap up with what you have, and warn the user** ("approaching the token budget — increase `MAX_TOKENS_PER_RENDER` or simplify the prompt; free-composition is the expensive path") rather than spiraling into more authoring iterations. Always report total tokens spent in your final summary so the user sees the cost. This in-agent guard is **best-effort** (the agent self-monitors; it can't see its exact token count mid-run). True hard enforcement belongs at the orchestration layer — a streaming watchdog on `interaction.usage` that aborts when the ceiling is crossed — tracked as a follow-up (see docs/local-mode.md). ## Cloud path ```bash set +x ASPECT=$(jq -r '.aspect_ratio' /.agents/workspace/compositions/<chosen-id>/manifest.json) RESULT=$(python3 /.agents/workspace/scripts/render_client.py \ /.agents/workspace/output/composition \ /.agents/workspace/output/variables.json \ "{\"resolution\":\"1080p\",\"aspect_ratio\":\"$ASPECT\"}") VIDEO_URL=$(echo "$RESULT" | jq -r '.video_url') ``` The egress proxy injects the HeyGen key; you pass no credential. Returns a HeyGen-CDN URL — give it straight to the user. ## Local path ```bash set +x RESULT=$(python3 /.agents/workspace/scripts/render_local.py \ /.agents/workspace/output/composition \ /.agents/workspace/output/video.mp4) VIDEO_URL=$(echo "$RESULT" | jq -r '.video_url') # gs/public URL if GCS_BUCKET set, else file://… RENDER_SECONDS=$(echo "$RESULT" | jq -r '.render_seconds') ``` `render_local.py` runs `hyperframes render` at the composition's native resolution with `HYPERFRAMES_BROWSER_PATH=/usr/bin/chrome-headless-shell`, then publishes the file: if `GCS_BUCKET` is set it uploads to GCS and returns a public URL; otherwise it returns a `file://` path (sandbox-local) with a note. So a deploy that wants shareable local-render URLs sets `GCS_BUCKET` (+ GCP auth). If `video_url` is a `file://`, tell the user it rendered locally and the file lives in the sandbox. Note the render time (local is slower than cloud). ## When local render fails `render_local.py` raises on a nonzero exit / timeout / missing output. Handle by failure mode — **the general rule is: fall back to cloud render when the failure is environmental, surface + fix when it's the composition.** | Failure | What it means | Do | |---|---|---| | Chrome crashes mid-render | Environmental (sandbox/Chrome) | Retry local **once**; if it crashes again, **fall back to cloud render** and tell the user it rendered on the cloud instead. | | `hyperframes lint` fails on your authored HTML | The composition is malformed (your bug) | **Fix the HTML** per the lint message and re-render. Don't fall back — cloud would fail the same way. | | GSAP runtime error at page-init | Composition bug (bad selector, non-deterministic code, CDN GSAP) | Fix it — most commonly: load GSAP from the local cache (`/workspace/.cache/libs/gsap.min.js`), not a CDN; remove `Math.random()`/`Date.now()`. Re-render. | | Local render exceeds its timeout (20 min) | Too-heavy composition or a stuck Chrome | Fall back to cloud if the composition is starter-based; if it's free-auth, simplify and retry, and warn the user. | | Token budget approached | Free-auth ran long | Stop gracefully, return what you have or fall back to cloud, and warn (see Token budget above). | Always prefer returning *something* (a cloud-rendered video + a note) over returning nothing. Never paste a raw stack trace. ## Returning the result Lead with the playable URL (cloud) or the uploaded URL (local). Mention the duration. If you rendered locally, it's fine to note it took longer. If you fell back from local to cloud, say so briefly. On a failure, show the API/CLI `failure_message` plainly — never a raw stack trace.