dimagi-internal/ace / skills/output-preview-capture
output-preview-capture
VerifiedInternal /ace:run step — Screenshot run outputs that lack a preview.
Output Preview Capture
Run workspace: when the dispatch carries a run_workspace: block, its values replace the .env ones this skill names — ACE_HQ_DOMAIN → run_workspace.hq_domain, ACE_WEB_WORKSPACE → the run's workspace: from run_state.yaml (pass --workspace) — and a partner workspace never falls back to .env. Contract: skills/_run-workspace.md.
Every output ace-web lists must be either a file its in-page viewer draws, or
have one or more GOOD screenshots (ace-web docs/specs/2026-09-29-output-previews-design.md,
addendum "every output is a doc or has screenshots"). ace-web computes which
outputs are neither — the gap list — and this skill photographs them.
A UTILITY skill, like decisions-render: it is not a run_state step, it is
idempotent, and it never fails or blocks a phase. Called by each phase agent
from Phase 3 to Phase 8 at the end of its write-back (filtered to that phase),
and once by the orchestrator at run end (all phases, --run-end).
Deterministic pieces live in lib/preview-capture.ts (gap parsing, which gaps
to take now, folder, per-kind shot plan, page screening, index) on top of the
contract helpers in lib/output-previews.ts; both are pinned by tests. The
browser work is scripts/output-preview-capture.ts. What stays here is the
Drive I/O and the one thing no script can do: looking at every frame.
Inputs
| Source | Artifact | Used for |
|---|---|---|
| ace-web | GET {ACE_WEB_BASE_URL}/api/w/{workspace}/opps/{opp}/runs/{run}/preview-gaps | the gap list — output_key, phase, kind, url, auth per output. Used VERBATIM; never re-derive ace-web's product walk |
| Per-run state | run_state.yaml | product fields the gap does not carry: a program's id / name, a solicitation's labs_program_id, and — for ace-web older than #831, whose gaps carry no public_url — a chatbot's public_url / team_slug + public_id |
| Phase 2 | 2-scenarios/pdd-to-test-prompts.md | the ONE real question the chatbot picture shows answered |
| Caller | opp, run_id, captured_phase (the run_state phase key this runs in), optional phase filter, --run-end | scope |
Products
For each gap captured, in the folder of the phase that BUILT the output:
<N>-<phase>/previews/<slug of output_key>/<NN>-<step>.png— the accepted frames (anyone-with-link).<N>-<phase>/previews/<slug of output_key>/_previews.yaml— the authoritative index:captured_by: output-preview-capture,captured_phase: <caller's phase>, one caption per frame saying what the frame SHOWS. Real YAML bytes (drive_upload_binary,text/yaml), never a Google Doc.
Nothing about previews is written under phases.<phase>.products — ace-web
reads any mapping there with a file_id as an output.
What makes a GOOD screenshot (per kind)
planCapture in lib/preview-capture.ts is the table in code:
| Kind | Frame(s) | Session |
|---|---|---|
connect_opportunity | top of the opportunity page (apps, payment units, dates, budget); then its Verification / payments section. Opened at the PM org's url when the run recorded a different holding org (pm-nm): the gap carries the holder's /a/<nm>/… link, which ace@ is not a member of and which 404s by design (ace#2893) | connect |
connect_program | its CARD on …/a/<org>/program/ — Connect has no program detail route; the recorded /program/<uuid>/ 404s. The card is found by the program's UUID (its edit / invite / new-opportunity controls carry /program/<uuid>/), else by its EXACT recorded name — never by the gap title. Before the shot the card's description is clamped to 3 full-width lines, so the frame is a landscape card (name, description, delivery type, dates, budget, invite funnel) rather than a tall strip of wrapped text. Neither → skipped (could not identify the program's card): a frame of the wrong program is never the fallback | connect |
chatbot | the PUBLIC chat page (the gap's public_url, else run_state's) with one real Phase 2 question answered — the question with the SHORTEST expected answer — framed so the user's question sits at the top and the whole answer fits (viewport grown to ≤2000px), the widget's [no tag] debug line hidden. Never the OCS admin page | none (anonymous) |
any other output on a session the script has no login for — auth: ocs, e.g. Phase 7's products.ocs_coach (kind: link) | the bot's PUBLIC chat, exactly as for chatbot: the gap's public_url, else built from the product's team_slug + public_id. Neither → skipped (the capture script has no OCS login …): the admin URL is never opened, because it can only land on OCS's login page (ace#2887). Any other session the script cannot open is skipped the same way | none (anonymous) |
solicitation | its labs page opened with ?program_id=<labs_program_id> — labs' sticky context otherwise 404s it | labs |
dashboard / labs report | the rendered report, top of page, with data loaded | labs |
walkthrough (canopy DDD package) | the package page at its walkthrough's first scene — its hero video is H.264, which headless Chromium paints white | canopy |
commcare_app (fallback) | the HQ app's Form Summary — only once the Phase 6 emulator walk has had its turn (deferred before Phase 6; never deferred at run end) | hq |
| Drive file the viewer cannot draw | an HTML file rendered in Chromium; otherwise Drive's thumbnail | Drive service account |
Process
-
Resolve the run and the scope.
opp,run_id, andcaptured_phasecome from the caller. At run endcaptured_phaseis the last phase that ran, and pass--run-end.- The workspace is the plugin
.env'sACE_WEB_WORKSPACE(the script reads it; pass--workspaceonly for a run in another workspace — the same rule asbin/ace-bind). - Resolve the run folder with
resolve_opp_path. Readrun_state.yamlto a local file (drive_read_filewriteToPath, defaulttext/plainexport) and, when the scope includesocs-setupORsynthetic-data-and-workflows(anyauth: ocsgap — the Phase 7ocs_coachis shot as its public chat and needs a real question too, ace#2887),2-scenarios/pdd-to-test-prompts.mdthe same way, and pass it as--test-prompts. - Scratch dir:
<scratchpad>/output-preview-capture/<run_id>-<captured_phase>/.
-
Capture. One Bash call; the script restores every session itself (below) and writes nothing to Drive:
ACE_ROOT="${CLAUDE_PLUGIN_ROOT:-$(python3 -c "import json,os; d=json.load(open(os.path.expanduser('~/.claude/plugins/installed_plugins.json'))); print(d['plugins']['ace@ace'][0]['installPath'])")}" node "$ACE_ROOT/node_modules/tsx/dist/cli.mjs" "$ACE_ROOT/scripts/output-preview-capture.ts" capture \ --opp <opp> --run <run_id> --captured-phase <captured_phase> \ [--phase <phase-to-filter>] [--run-end] \ --run-state <local run_state.yaml> [--test-prompts <local pdd-to-test-prompts.md>] \ --out <scratch dir>The last stdout line is a JSON summary (
captured,failed,skipped,deferred);<scratch dir>/plan.jsonhas, per gap, the targetfolder(relative to the run folder), the local frame paths, each frame's caption and its deterministic screen verdict. The script already retried each failure once with a fresh session. Askippedgap was never attempted: its reason is structural (no public chat url, no session for that auth, no program id), so no retry can close it — report the reason, do not re-run it. A 404 from ace-web means its gap endpoint is not deployed — report that and stop (nothing to do, nothing to fail).Sessions — all headless, all work on canopy's cloud runner:
- connect / hq:
PlaywrightSession(the ace-connect MCP's own session code): probes Connect AND HQ, re-logs-in fromACE_HQ_USERNAME/ACE_HQ_PASSWORD, persists~/.ace/connect-session.json./ace:connect-loginis only the manual fallback when those credentials cannot log in. - labs: runs
bin/labs-walkthrough-login.tsonce, unconditionally, before the first labs gap — Phase 7 Step 3.0's restore — and uses~/.ace/labs-session.json./ace:labs-loginis the same script. - canopy: the token canopy issues for ace (
canopy agent token --slug ace, vialib/ace-canopy-pat.ts— the same answerbin/ace-canopy-webacts with,playbook/integrations/canopy-web.md) as a Bearer header. How canopy picks it: canopyagent-core/agent-runtime.md§ Session identity. No token fails loudly with canopy's reason (ace#2805). A labs session does NOT open canopy pages (they bounce to Google sign-in). - ocs: none — the chatbot's public chat page is anonymous.
/ace:ocs-loginis not needed for previews. So EVERYauth: ocsoutput — achatbot, or alinksuch asproducts.ocs_coach— is photographed on its public chat or skipped; its admin URL is never a target (ace#2887). - google: ace@dimagi-ai.com's canopy Google token (
canopy cred google-token).
- connect / hq:
-
LOOK at every frame — this is the gate, not the screen verdict.
Readeach PNG listed for acapturedgap. Reject a frame that shows a login or sign-in page, an error or 404, a spinner / "loading" / an empty report (a report with no numbers, a table with no rows), a blank or white page or video box, a context picker ("Select context", "No organizations found"), or the WRONG thing (a different opportunity, program or chatbot than the gap's title). Also reject one whose caption does not describe what is actually on it — or rewrite the caption to what it shows. The deterministic screen only catches the obvious; passing it proves nothing.- All frames of a gap rejected: re-run step 2 ONCE for that gap alone
(
--only <gap id>); a second rejection means write NOTHING for that output and record why (what the frame showed). Never re-run askippedgap, nor afailedone whose reason isloginon a session the script cannot log in to (ocs): the retry repeats a step that cannot pass. The fix for those is the gap's data (ace-web'spublic_url, or run_state'steam_slug+public_id), not another attempt. - A
failedorskippedgap: nothing to upload; carry its reason to the report.
- All frames of a gap rejected: re-run step 2 ONCE for that gap alone
(
-
Write each gap that has ≥1 accepted frame. Per gap, in order:
-
Folder.
plan.json'sfolderis<N>-<phase>/previews/<slug>. Find the<N>-<phase>folder in the run folder (drive_list_folder), thendrive_create_folder(find-or-create)previews, then<slug>inside it. -
Plan the clear — then trash ONLY what the plan names. A folder can hold files that are not stale previews: a Phase 6 Learn leg that walked on the device and then failed the Connect gate leaves its real frames here under an
items: []index, and the capture manifest, FLW guide and deck cite every one byfile_id. Trashing "every child" put 198 such frames in the bin on kaduna-graduation/20261015-1411 (ace#3044). So:drive_list_folderthe slug folder and write its JSON to a local file. If it has a_previews.yaml,drive_read_fileit to a local file too.- Read every citing artifact to a local file: always
run_state.yaml(step 1's copy), plus6-qa-and-training/app-screenshot-capture_manifest.yamlwhen it exists (it does once Phase 6 has run). - Run:
node "$ACE_ROOT/node_modules/tsx/dist/cli.mjs" "$ACE_ROOT/scripts/output-preview-capture.ts" clear-plan \ --listing <listing.json> [--index <old _previews.yaml>] \ --cited run_state.yaml=<local run_state.yaml> \ [--cited 6-qa-and-training/app-screenshot-capture_manifest.yaml=<local manifest>] write: false→ another skill owns this output's previews with ≥1 item and the gap list is stale: write nothing, notereason.- Otherwise
drive_trash_fileexactly the ids intrash— nothing else. Everykeepchild is cited by an artifact (cited_by): leave it where it is, neither trashed nor moved, so itsfile_idand recorded drive path stay valid. The new index is authoritative, so a kept frame it does not list is shown to no one. Name the kept count in the report. Never touch any other folder — Phase 6's app folders and Phase 7's dashboard folders are only ever written here when the gap list says that output has NO previews.
-
Upload each accepted PNG under its
plan.jsonname —drive_upload_binary({name, localFilePath, mimeType: 'image/png', parentFolderId, shareAnyoneWithLink: true}). Keep each response'ssharing. It must readanyone-with-link: an SA-only frame cannot be opened by ace-web's reader or embedded byscripts/embed-doc-screenshots.ts, which on connect-fi/20261018-1440 failed the LLO guide with "problem retrieving the image" (ace#3234). If it readssa-only, rundrive_set_anyone_with_linkon that id. -
Index. Write the uploads as
[{name, file_id, sharing}]to a local JSON file (accepted frames only, in display order,sharingcopied from each upload response).indexrefuses any frame whosesharingis notanyone-with-link, missing included. Then:node "$ACE_ROOT/node_modules/tsx/dist/cli.mjs" "$ACE_ROOT/scripts/output-preview-capture.ts" index \ --plan <scratch dir>/plan.json --gap <gap id> --uploaded <uploads.json>It writes
<scratch dir>/<slug>/_previews.yaml(buildCaptureIndex→captured_by: output-preview-capture,captured_phase, captions). If you rewrote a caption in step 3, edit it inplan.jsonfirst. Upload it withdrive_upload_binary({name: '_previews.yaml', mimeType: 'text/yaml', localFilePath, parentFolderId})— neverdrive_create_file.Looping over several gaps in one Bash call? ACE's shell is zsh, which does NOT word-split an unquoted
$var—for id in $idsruns ONCE with the whole list as one argument (seen live asmissing --gap). Read one id per line instead:printf '%s\n' "${GAP_IDS[@]}" | while IFS= read -r id; do node "$ACE_ROOT/node_modules/tsx/dist/cli.mjs" "$ACE_ROOT/scripts/output-preview-capture.ts" index \ --plan "$PLAN" --gap "$id" --uploaded "$SCRATCH/uploads-${id//[^A-Za-z0-9]/-}.json" done -
Read it back and assert.
drive_read_file({fileId, writeToPath}), then… output-preview-capture.ts verify --plan … --gap <id> --readback <file> --count <N>. Exit 1 → re-upload once; still failing → trash the folder's contents and report the output as not previewed (an index a reader cannot parse is worse than none).
-
-
Re-fetch the gap list and report.
node "$ACE_ROOT/node_modules/tsx/dist/cli.mjs" "$ACE_ROOT/scripts/output-preview-capture.ts" gaps \ --opp <opp> --run <run_id> [--phase <phase>] --refresh--refreshis required here — it sends?refresh=true(ace-web#832), which drops ace-web's cached snapshot and rebuilds it from Drive. Without it the cached snapshot predates thepreviews/folders just created, and every gap just filled still reads as open (seen live on spark-facilitator/20260926-1800: 9 of 9 "left" right after writing 8). Step 2's fetch does not need it. On an ace-web that ignores the parameter, a gap you just filled that is still listed is reported as "written, not yet visible", not as a failure. Return ONE line the caller puts in its phase summary:previews: N captured, M gaps left (<output_key>: <why>; …), plus the deferred app gaps at Phase 3 (apps.learn: waits for the Phase 6 walk).
Best effort — this skill never fails a phase
Any error — ace-web unreachable, no credentials, a login that will not
complete, Drive refusing a write — ends with the report line naming it. It
never throws to the caller, never writes a verdict, never touches
run_state.yaml, and never re-dispatches a producer. A missing picture is
reported; it is not a blocker.
MCP Tools Used
- ace-gdrive:
resolve_opp_path,drive_list_folder,drive_read_file,drive_create_folder,drive_trash_file,drive_upload_binary.
Scripts (Bash): scripts/output-preview-capture.ts (gaps, capture,
clear-plan, index, verify), which calls bin/labs-walkthrough-login.ts for the labs
restore.
Mode Behavior
- Auto / default / review: identical — no pause, no prompt. The frames are judged by this skill's own look in step 3, not by a human gate.
- Dry-run: run steps 1–3 (capture and look) and report; skip step 4's Drive writes.
Related skills
app-screenshot-capture— primary writer of3-commcare/previews/apps-*(Phase 6 emulator walk); this skill is its fallback only.agents/synthetic-data-and-workflows.md § Step 3.95— primary writer of7-synthetic/previews/synthetic-workflows-*from the DDD render.decisions-render— the same utility-skill shape (every phase end, idempotent).
Change Log
| Date | Change | Author |
|---|---|---|
| 2026-10-16 | A cited frame is never trashed (ace#3044). Step 4.2's "trash every child" put 198 manifest-cited Learn frames in the bin on kaduna-graduation/20261015-1411 (a failed leg's items: [] folder). The clear is now planned by clear-plan (planPreviewFolderClear, pinned in test/lib/preview-capture.test.ts): a child any citing artifact names by id is kept in place; only the plan's trash ids are removed; no plan without a citer. | ACE team |
| 2026-09-30 | Program card is a landscape frame (0.13.1618). The card's half-width, PDD-length description made a 891×1570 strip; it is now clamped to 3 full-width lines (891×410 live). | ACE team |
| 2026-09-30 | Nameless program caption (0.13.1614). A program matched by UUID with no recorded name is captioned from its card's own heading, never Connect program this program — …; with no name at all the caption names nothing. | ACE team |
| 2026-09-30 | First real run fixes (spark-facilitator/20260926-1800). (1) The program card matched the WRONG program: run_state recorded the program with no name, the plan fell back to the gap title "Connect program", and the card shot took the first card on the page (a probe program). The card is now found by the program's UUID, else its exact recorded name, and otherwise SKIPPED — never a wrong-thing fallback. (2) The chatbot frame showed the tail of a long answer without the question: prefer the shortest-expected-answer prompt, put the question at the top, grow the viewport to fit, hide [no tag]. (3) Step 5 re-fetches with --refresh (ace-web#832). Gap public_url (ace-web#831) is used directly; zsh-safe loop pattern in Step 4.4. | ACE team |
| 2026-09-29 | Initial skill (ace-web output previews addendum: every output is a doc or has screenshots). Reads ace-web's preview-gaps list and photographs the Connect program/opportunity, the chatbot's public chat with a real Phase 2 question answered, the solicitation, labs reports, the canopy DDD package, Drive files the viewer cannot draw, and — as a fallback after Phase 6 — CommCare apps via HQ's form summary. Every frame is looked at before upload. Called at the end of Phases 3–8 and at run end. Smoke-tested live on spark-facilitator/20260926-1800's outputs (8/8 kinds captured; Drive write + readback verified in a scratch folder). | ACE team |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |