Skip to content

dimagi-internal/ace / skills/output-preview-capture

output-preview-capture

Verified

Internal /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

SourceArtifactUsed for
ace-webGET {ACE_WEB_BASE_URL}/api/w/{workspace}/opps/{opp}/runs/{run}/preview-gapsthe gap list — output_key, phase, kind, url, auth per output. Used VERBATIM; never re-derive ace-web's product walk
Per-run staterun_state.yamlproduct 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 22-scenarios/pdd-to-test-prompts.mdthe ONE real question the chatbot picture shows answered
Calleropp, run_id, captured_phase (the run_state phase key this runs in), optional phase filter, --run-endscope

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:

KindFrame(s)Session
connect_opportunitytop 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_programits 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 fallbackconnect
chatbotthe 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 pagenone (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 waynone (anonymous)
solicitationits labs page opened with ?program_id=<labs_program_id> — labs' sticky context otherwise 404s itlabs
dashboard / labs reportthe rendered report, top of page, with data loadedlabs
walkthrough (canopy DDD package)the package page at its walkthrough's first scene — its hero video is H.264, which headless Chromium paints whitecanopy
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 drawan HTML file rendered in Chromium; otherwise Drive's thumbnailDrive service account

Process

  1. Resolve the run and the scope.

    • opp, run_id, and captured_phase come from the caller. At run end captured_phase is the last phase that ran, and pass --run-end.
    • The workspace is the plugin .env's ACE_WEB_WORKSPACE (the script reads it; pass --workspace only for a run in another workspace — the same rule as bin/ace-bind).
    • Resolve the run folder with resolve_opp_path. Read run_state.yaml to a local file (drive_read_file writeToPath, default text/plain export) and, when the scope includes ocs-setup OR synthetic-data-and-workflows (any auth: ocs gap — the Phase 7 ocs_coach is shot as its public chat and needs a real question too, ace#2887), 2-scenarios/pdd-to-test-prompts.md the same way, and pass it as --test-prompts.
    • Scratch dir: <scratchpad>/output-preview-capture/<run_id>-<captured_phase>/.
  2. 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.json has, per gap, the target folder (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. A skipped gap 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 from ACE_HQ_USERNAME / ACE_HQ_PASSWORD, persists ~/.ace/connect-session.json. /ace:connect-login is only the manual fallback when those credentials cannot log in.
    • labs: runs bin/labs-walkthrough-login.ts once, unconditionally, before the first labs gap — Phase 7 Step 3.0's restore — and uses ~/.ace/labs-session.json. /ace:labs-login is the same script.
    • canopy: the token canopy issues for ace (canopy agent token --slug ace, via lib/ace-canopy-pat.ts — the same answer bin/ace-canopy-web acts with, playbook/integrations/canopy-web.md) as a Bearer header. How canopy picks it: canopy agent-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-login is not needed for previews. So EVERY auth: ocs output — a chatbot, or a link such as products.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).
  3. LOOK at every frame — this is the gate, not the screen verdict. Read each PNG listed for a captured gap. 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 a skipped gap, nor a failed one whose reason is login on 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's public_url, or run_state's team_slug + public_id), not another attempt.
    • A failed or skipped gap: nothing to upload; carry its reason to the report.
  4. Write each gap that has ≥1 accepted frame. Per gap, in order:

    1. Folder. plan.json's folder is <N>-<phase>/previews/<slug>. Find the <N>-<phase> folder in the run folder (drive_list_folder), then drive_create_folder (find-or-create) previews, then <slug> inside it.

    2. 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 by file_id. Trashing "every child" put 198 such frames in the bin on kaduna-graduation/20261015-1411 (ace#3044). So:

      • drive_list_folder the slug folder and write its JSON to a local file. If it has a _previews.yaml, drive_read_file it to a local file too.
      • Read every citing artifact to a local file: always run_state.yaml (step 1's copy), plus 6-qa-and-training/app-screenshot-capture_manifest.yaml when 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, note reason.
      • Otherwise drive_trash_file exactly the ids in trash — nothing else. Every keep child is cited by an artifact (cited_by): leave it where it is, neither trashed nor moved, so its file_id and 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.
    3. Upload each accepted PNG under its plan.json name — drive_upload_binary({name, localFilePath, mimeType: 'image/png', parentFolderId, shareAnyoneWithLink: true}). Keep each response's sharing. It must read anyone-with-link: an SA-only frame cannot be opened by ace-web's reader or embedded by scripts/embed-doc-screenshots.ts, which on connect-fi/20261018-1440 failed the LLO guide with "problem retrieving the image" (ace#3234). If it reads sa-only, run drive_set_anyone_with_link on that id.

    4. Index. Write the uploads as [{name, file_id, sharing}] to a local JSON file (accepted frames only, in display order, sharing copied from each upload response). index refuses any frame whose sharing is not anyone-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 in plan.json first. Upload it with drive_upload_binary({name: '_previews.yaml', mimeType: 'text/yaml', localFilePath, parentFolderId}) — never drive_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 $ids runs ONCE with the whole list as one argument (seen live as missing --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
      
    5. 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).

  5. 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
    

    --refresh is 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 the previews/ 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 of 3-commcare/previews/apps-* (Phase 6 emulator walk); this skill is its fallback only.
  • agents/synthetic-data-and-workflows.md § Step 3.95 — primary writer of 7-synthetic/previews/synthetic-workflows-* from the DDD render.
  • decisions-render — the same utility-skill shape (every phase end, idempotent).

Change Log

DateChangeAuthor
2026-10-16A 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-30Program 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-30Nameless 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-30First 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-29Initial 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
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: 196kUpdated Claude CodeCodexVerifiedInstall
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: 193kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 193kUpdated Claude CodeCodexVerifiedInstall
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: 193kUpdated Claude CodeCodexVerifiedInstall