1. Why

The harness can now give an environment a cast of sub-actors: people on the caller's side who are neither the agent nor the person it serves, such as a voice near the person, someone who takes the phone, the caller's own phone menu or a second chat participant (companion PR below). The platform has to switch that on per deployment, keep what the harness produces, and show it: which sub-actors a world has, which scenarios bind them, and who said what in a call.

2. What changed

3. Behavior callouts

• Off by default: with ALK_SUB_ACTORS unset the sandboxes never receive HARNESS_SUB_ACTORS, so builds and runs are unchanged, and adopted templates bring no cast.
• Migration: 0098_sub_actors (scenario bindings, transcript role and speaker name, chat role). It is additive; no data is rewritten.
• "Not applicable" is stored as held. A sub-goal about a sub-actor that did not enter arrives from the harness as held=True with a "Not applicable" reason, so it counts as held in pass rates. There is no separate not-applicable verdict.
• The prebuilt templates are a frontend catalogue today: the templates and adopt endpoints are still mocks in prebuilt.js and environments.js, so the per-vertical casts live there and follow the list response's sub_actors switch. When the templates endpoint lands it should return the same cast shape.
• Transcript rows may carry speaker_role = "sub_actor" with a speaker_name; rows written before this PR have speaker_name = "". Readers that switch on user / assistant see the new value only for calls that bound a sub-actor.
• The harness registers channels for computer-use, browser, coding and multi-agent targets but refuses them until runners for those agent kinds exist, so no such data reaches the platform yet.
• Platform evals other than CSAT do not see sub-actor turns yet: voice transcripts for evals keep only conversational roles.

4. Tests

The touched backend suites (test_harness_sub_actors.py, test_hosted_harness_gateway.py, test_hosted_harness_channels.py, test_alk_simulate_ingestion.py, test_harness_scenario_amend.py, test_harness_scenario_labels.py, test_analytics_functional.py, test_run_results_v3_facets_catalog_parity.py, test_harness_provider.py, test_ended_reason.py): 722 passed; the one failure, test_voice_simulator_uses_single_dataset_language, fails the same way on dev. The frontend simulate-environments API and simulate/environments section suites: 1571 passed, 2 skipped. makemigrations --check reports no changes, and yarn contracts:check and the MCP manifest check pass. CI does not run on this stacked PR until it targets dev.

Tested end to end

On a local platform with this branch, ALK_SUB_ACTORS=true and the companion ALK branch: one voice agent (ride booking, real calls) and one chat agent (order status), each built fresh.

Found and fixed while testing: a sub-actor added from the builder chat never reached the environment, because checkpoint promotion only copied the contract, scenarios, sub-goals and coverage outputs. It now copies the cast as well (test_a_cast_added_in_the_builder_chat_reaches_the_environment, which fails without the fix).

5. Commands to run the tests

cd futureagi
bin/test simulate/tests/test_harness_sub_actors.py simulate/tests/test_hosted_harness_gateway.py \
  simulate/tests/test_analytics_functional.py simulate/tests/test_run_results_v3_facets_catalog_parity.py -v

cd ../frontend
yarn test:run src/api/simulate-environments src/sections/simulate/environments
yarn contracts:check

Terminal output

<image: backend and frontend test output>

6. Steps to test on local

1. Set ALK_SUB_ACTORS=true for the backend and run it with the companion ALK branch.
2. Build an environment for a voice agent and, in the builder chat, add a voice near the person and someone who takes the phone from them.
3. Open the environment's Contract tab; confirm the actors panel lists both sub-actors with how many scenarios bring each in.
4. Open the scenarios tab; confirm a scenario that binds them shows them under its name.
5. Filter scenarios by Sub-actors; confirm none shows only the scenarios without one.
6. Run a bound scenario and open the call; confirm the second voice's turn is labelled with its name.
7. Open the run's results and pick a sub-actor under "Actor"; confirm only that sub-actor's sub-goal columns remain, and "Person served" shows the rest.
8. Open Templates, use the customer support line template, and confirm the overview lists its cast.
9. Unset ALK_SUB_ACTORS, rebuild, adopt the template again, and confirm none of the above appears.

<video: actors panel, scenario filter, and a call with a sub-actor turn>

7. Scope in / scope out

E2E: exempt (harness-gap sub-actors are off by default and only appear in hosted harness runs)

8. Design choices

• The bindings are stored on the scenario row as written by the harness, so the filter and the UI read the same shape the run used.
• Sub-actor turns use their own role instead of being folded into user, so attribution survives to evals and metrics stay limited to the person and the agent.
• One setting gates the feature end to end; the sandbox decides nothing on its own.

Companion PR: future-agi/agent-learning-kit#177

Linear

Closes TH-8651