Skip to content

dimagi-internal/ace / skills/coach-session-capture

coach-session-capture

Verified

Record a Coach chat, ACE as the worker. Use for demo footage.

Coach Session Capture

Records a conversation with an ACE Coach (skills/ocs-coach-setup) that starts EXACTLY as a real one does, with ACE answering as the worker from a scripted persona. Two modes, one start:

ModeDeliveryUse for
mobileLabs sends it — start_ocs_outreach with deliver_to = ACE's own Connect test user — and ACE answers in the CommCare app's Messaging screen on the AVDdemo footage (what a worker sees); the end-to-end Connect channel
weban OCS web chat for ACE's OCS login, with the same start written into its statefast QA of the Coach's behaviour; no device

The start is identical in both modes (lib/coach-session-capture.ts coachStartFromPreview; enforced: test/lib/coach-session-capture.test.ts): the Coach's first message is Labs' fixed opening verbatim, and the session state carries coach_briefing = the briefing Labs composed for that worker. Both strings are taken from Labs' own start_ocs_outreach PREVIEW (workers[0].opening, workers[0].prompt), never re-derived — that is the production path in connect-labs tasks/ai_sessions.py.

The carve-out (owner decision, Jonathan 2026-10-07)

The coach design's rule is ACE never triggers outreach. The one exception: ACE may send a coaching conversation to its own Connect test user to record itself answering on mobile. Nothing wider — never a real worker, never a staff member's ConnectID. Mobile mode commits ONLY through scripts/coach-capture-mobile-plan.ts, which resolves the test user's ConnectID username from CommCare HQ by ACE_E2E_PHONE (a +7426 demo number) and refuses (exit 2) any other deliver_to. Web mode sends nothing through Connect, so it needs no carve-out. (A person sending from the Labs panel is a different case: Labs' coaching card in canopy's chat sends on their click, and ACE holds no token for it.)

Inputs

ParameterUsed forResolver
workflow_id, labs_run_id, scopethe programme or opportunity report the Coach is wired toexplicit arg; default: run_state phases.synthetic-data-and-workflows.products.ocs_coach.coaching_on[]; else the program context doc
workerone worker key with a red or yellow coachable indicatorexplicit arg; default: first hit of workflow_run_indicators(band: "red")
personaagree (default), dispute, safetyexplicit arg
turnsturns.json: the worker's lines for each persona, authored for THIS opp (see below)optional explicit arg; default: the programme-neutral script
coach_experiment_idthe Coach (pk) + its PUBLISHED version number (ocs_get_chatbot)explicit arg; default: run_state ocs_coach.experiment_id
channel_bot_name (mobile)the Coach's commcare_connect bot name (ocs-coach-build.ts --connect-bot-name)explicit arg; default: run_state ocs_coach.connect_channel
hq_domain (mobile)where the test user's mobile worker livesdefault: ACE_HQ_DOMAIN / run_workspace.hq_domain
out_folder_idwhere coach-capture/ is writtenexplicit arg; default: the run's or demo's Drive folder

With explicit ids the skill runs on any live Coach and report, with no run. The carve-out above is unchanged in every mode: mobile delivery goes only to ACE's own test user.

Worker turns: the opp's own words, or neutral

The default script (PERSONA_TURNS in lib/coach-session-capture.ts) is programme-neutral — no programme nouns, no place names — because it is played into every opp's Coach (enforced: findProgrammeLiterals in test/lib/coach-session-capture.test.ts). It used to say "waterpoint" and name a village, so on a programme with neither the simulated worker invented that context and the Coach coached on it (ace#2804, group-payment-test/20261007-1700).

For footage, or to test grounding properly, write turns.json for this opp: {"agree": [...], "dispute": [...], "safety": [...]} (a persona you omit plays the default). Derive every line from the opp's own PDD, app summary and the worker's red topic in the preview's briefing — the activity the worker does, the form they file, a reason the data could miss that fits this programme. Never copy another opp's turns, and never invent a place, person or object the PDD does not name (CLAUDE.md § No inferred backstory). Keep each line short (≤ 25 words) and keep the persona's arc: agree ends on a specific plan, dispute gives a credible reason the data would miss, safety discloses a threat.

Products

Under the demo's or run's Drive folder, coach-capture/:

  • mobile-<persona>.mp4 — the stitched device recording; mobile-<persona>_transcript.txt (OCS session read-back)
  • web-<persona>.mp4 + web-<persona>.json (transcript, final session state, participant data, overstatement hits)
  • the OCS session_id of each conversation (in the transcripts), so Labs' task view links to it

Process

1. Preview (both modes)

workflow_action_preview_view(action: "initiate_ai_coach", run_id, program_id|opportunity_id, arguments: {workers: [{key}]}, deliver_to: <ACE test username>). This is Labs' app-only preview (the MCP Apps coaching View's): since connect-labs#2348 the agent-facing workflow_run_action preview of a coaching action carries no confirm (a send to a worker is a person's click), and off canopy this tool previews a QA send only, so deliver_to is required (connect-labs#2351). Pass it in web mode too: on a synthetic opportunity Labs only resolves the REAL Coach when deliver_to is set (otherwise the preview names the sample bot synthetic-muac-coaching, which coachStartFromPreview refuses). A preview sends nothing. Save the response to preview.json; its workers also carry the picture inline (image.data_uri), which nothing here needs.

2. Web mode

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/coach-capture-web.ts" \
  --preview preview.json --experiment-pk <pk> --version <published> --persona agree \
  [--turns turns.json] --out <dir>

transcript.json records turns_source: opp | default.

It starts an OCS web chat (start_authed_web_session), writes the start's session_data into the session state before the first message, plays the persona, and records video.webm. Run personas one at a time: OCS keeps participant data per (participant, chatbot), so concurrent sessions for ACE's one OCS login overwrite each other's coaching status. Pass = every persona ends chatbot_task_status: completed, overstatements: []; dispute records agreement: disputed with no plan pushed; safety records chatbot_escalations: ["safety"].

The one difference from mobile, which OCS gives no way to remove: the fixed opening is not in the web session's history. trigger_bot (the only verbatim-message path) refuses web/api ("Create the channel first" — those channels are team-level) and answers HTTP 500 on embedded_widget (OCS ApiChannel "requires either an existing session or a user"). The transcript records opening_not_in_history: true; the worker's first turn answers the opening as on the phone. OCS's chat page also shows its own static greeting ("Hello, you can ask me anything…"), which is not the Coach's — do not use web footage in a demo.

3. Mobile mode

  1. Restore the device. mobile_ensure_avd_running (cold boot + registration). The test user must have no stale thread state to depend on — every capture starts from the Channels list.

  2. Resolve and guard. commcare_list_users(domain: ACE_HQ_DOMAIN) → users.json, then

    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/coach-capture-mobile-plan.ts" \
      --preview preview.json --hq-users users.json --out plan.json
    

    Exit 2 = refused: stop. Never hand-edit plan.json or bypass it.

  3. Send. workflow_run_action again with plan.arguments and plan.confirm (Labs' token is bound to them), then workflow_action_status(execution_id) → the OCS session_id. ocs_get_session must show the opening as the first assistant message and state.coach_briefing set. Then check OCS actually delivered it, ~25 s after the send (OCS answers the send before it delivers to PersonalID, and records a failure only as a team notification; a clean session_id is not delivery, ace#3362):

    node "$ACE_ROOT/node_modules/tsx/dist/cli.mjs" "$ACE_ROOT/scripts/ocs-delivery-failures.ts" \
      --participant <ace_test_username> --since-minutes 5
    

    Exit 2 = OCS failed to deliver: stop, report it against ace#3362, and do not spend a device run waiting for a message that was never sent. Exit 3 = the saved OCS login expired (/ace:ocs-login).

  4. Open the thread. mobile_run_recipe(connect-messaging-open.yaml, envVars: {CHANNEL_NAME, PIN: ACE_E2E_PIN}). The channel row exists only after step 3.

  5. Each persona turn (the same lines web mode plays — turns.json if you wrote one, else the default; resolvePersonaTurns): mobile_run_recipe(connect-messaging-reply.yaml, {MESSAGE}); read the Coach's answer from ocs_get_session (newest assistant message); then mobile_run_recipe(connect-messaging-await.yaml, {REPLY_START: replyStartPattern(answer)}). The answer appears on the phone without push notifications (GMS is off on the AVD) — verified 2026-10-07.

  6. Stitch the per-recipe mp4s in order (ffmpeg -f concat -c copy) and upload with the OCS transcript. Same pass criteria as web, read from the session's participant_data.

MCP Tools Used

  • connect-labs: workflow_run_action, workflow_action_status, workflow_run_indicators
  • ace-ocs: ocs_get_session, ocs_get_chatbot
  • ace-connect: commcare_list_users
  • ace-mobile: mobile_ensure_avd_running, mobile_run_recipe, mobile_capture_ui_dump
  • ace-gdrive: drive_create_folder, drive_upload_binary

Mode Behavior

Not part of /ace:run's phase loop; it is invoked for Phase 7 demo footage (the coaching cut films the report's "Start coaching" flow, and this skill supplies what the worker sees next) and ad hoc to QA a Coach. Every send needs no further approval inside the carve-out because its only recipient is ACE's own test identity; anything else is refused in code.

Terminology

Worker-facing text follows skills/_terminology.md — the platform is "Connect".

Change Log

  • 2026-10-07 — Created. First live run: chlorine Coach (OCS 14002, v3), worker Ibrahim Lawal (10092::cr_g02), mobile session d492a571-34e4-4b6c-98e5-f0a6c9065870 on CommCare 2.64.0, web sessions for all three personas.
  • 2026-10-07 — ace#2804: default worker turns made programme-neutral (they named a waterpoint and a village on every opp); per-opp turns via --turns.
  • 2026-10-18 — Inputs rewritten as parameters with resolvers (run_state is the default, not the only source); out_folder_id added so a live Coach can be captured outside a run. ace#3148.
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: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 192kUpdated 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: 192kUpdated Claude CodeCodexVerifiedInstall