Known errors and recovery

Pireel MCP tools execute in the user's open studio browser tab, relayed through a bridge. Most failures are connection-state problems, not bugs — each has a specific recovery. Never blind-retry; diagnose first.

studio_not_open (HTTP 409)

Meaning: no studio tab is connected to the bridge. The user does not have their Pireel studio project open in a browser, or the tab hasn't finished connecting.

Recovery: data-level tools (cuts, block edits, captions, BYO compose/apply, plan) automatically fall back to OFFLINE MODE — they edit the user's most recently updated cloud project directly (the result carries offline: true and the project name; changes appear next time the project is opened). Only video-dependent tools hard-fail with this error: extract_asr, analyze_visual, capture_frame, lay_out, and Pireel-LLM generation. For those, open a tab yourself: call create_browser_handoff and open the returned url with your OWN built-in/embedded browser tool — never via the OS open command or the user's default browser (single-use ticket; a surface you cannot see wastes it and leaves you blind). Pre-signed-in, ~60s, never show it to the user. If you have no embedded browser, ask the user to open their studio project at https://pireel.com instead. Do not blind-retry the same call — the answer will not change until a tab connects.

studio_tab_closed

Meaning: the studio tab disconnected mid-call — closed, navigated away, refreshed, or the machine slept.

Recovery: re-open a tab (create_browser_handoff → built-in browser, or ask the user to re-focus theirs). Then — important — call get_state before resuming: the interrupted operation may or may not have applied, and your snapshot is now untrustworthy. Verify what actually landed instead of re-issuing mutations on faith (a repeated cut lands twice).

tool_timeout after Ns

Meaning: the bridge gave up waiting for the tab. Instant (badge) operations time out at 60s; slow generation/analysis (card) tools at 600s. A timeout usually means the tab is throttled (backgrounded), the machine is under load, or a genuinely huge job.