veratown-prototype

HOWTO: Enable Supervisor-Managed ABCL

ABCL coordination runs inside the existing Veratown supervisor. A separately deployed helper observes ABCL messages and performs assigned ABCL actions and participant-facing communication. Do not deploy a dedicated ABCL controller; the supervisor and helper each keep their own BC account, BcClient, and rate queue.

The service tables show environment-only settings. Database-managed profiles are also supported: configure the existing supervisor with a supervisor profile and the communicator with a separate helper profile in the selected runtime database. Keep RUNTIME_TARGET, MONGODB_URI, BC credentials, and observation bearer tokens in Railway variables/secrets. Profile changes take effect only after an operator-managed restart; see the profile wizard guide.

1. Prepare test data and accounts

1. Use RUNTIME_TARGET=test, veratown_prototype_test, and dedicated non-production BC accounts for the supervisor and helper.
2. Use the same BC_ROOM for both processes.
3. Create an enabled region location in the test database.
4. Register an enabled helper agent with capabilities: ["abcl"], matching room/runtime/member identity, and parentAgentId: "supervisor".
5. In Admin Web’s room-scoped game configuration, set rooms.main["abcl.rules"] with the enabled region key, helper ID, and adultsOnlyRoomConfirmed: true. Keep enabled: false until qualification.
6. Never copy consent records, ABCL observations, helper task history, or BC credentials between databases.

The supervisor remains healthy if abcl.rules is missing, disabled, or invalid; in those states ABCL is inactive. No ABCL task is dispatched until the helper is observed inside the configured region.

2. Configure the supervisor

Use the existing supervisor service and its dedicated BC account. In environment mode, set RUNTIME_ROLE=supervisor (or omit it to use the default). In profile mode, the profile role must be supervisor. Do not set RUNTIME_ROLE=abcl; that retired role is rejected at startup. Existing database profiles with role abcl must be changed to supervisor or disabled/retired in Admin Web.

The supervisor and helper must use the same test runtime target and BC room. ABCL coordination adds no second socket or BC account to the supervisor.

3. Create the communicator helper

Create a separate Railway service from the same Veratown branch with the standard build/start commands and the same test runtime/database/room. Configure:

In profile mode, set this service’s own BOT_INSTANCE_ID; its helper profile supplies HELPER_AGENT_ID, room, endpoint, and other supported non-secret settings. Keep the helper’s BC credentials and any observation token in deployment secrets.

Variable	Test value
RUNTIME_ROLE	helper
HELPER_AGENT_ID	The helper registry agentId named by abcl.rules
RUNTIME_TARGET	test
BC_USERNAME / BC_PASSWORD	Dedicated helper account, stored as secrets

Do not use the supervisor’s credentials for the helper. Position the helper manually in the configured region, or configure a startup point that is inside that region. A region-only location is not a valid teleport destination. Participant-facing messages and BC actions have no supervisor fallback.

4. Qualify, activate, and roll back

Start the supervisor and helper, verify their room sync and the helper’s BC-observed position, then enable abcl.rules. Confirm the ABCL opt-in commands and test the disabled/missing config gate, helper leaving the region, participant opt-out during a sequence, malformed mod sync, action timeout, and restart with pending tasks. Keep the feature disabled until qualification and explicit operator approval are complete.

For rollback, set enabled:false (or remove abcl.rules). The supervisor and its other features continue running. Stop the helper service only if it has no other assigned work.