Summary
Embedded / in-process plane (TOKENOPS_EMBEDDED, no TOKENOPS_URL, mounting /v1/runs on the agent) duplicates control-plane responsibility inside agent processes. Two modes to explain, test, and keep in sync. When TOKENOPS_URL is set, agents should not keep a hybrid local TOKENOPS_DB ledger path.
Area: ControlPlaneClient.from_env, TOKENOPS_EMBEDDED, local Store as plane substitute, should_mount_run_registration
Desired behavior
- Always talk to a real control plane over its API (
TOKENOPS_URL).
- No embedded Store-as-plane path for product/demos; tests use a plane fixture or test server, not a second mental model.
- Agents never mount
/v1/runs.
- No hybrid local
TOKENOPS_DB for ledger when TOKENOPS_URL is set.
Acceptance sketch
TOKENOPS_EMBEDDED removed (or test-only and undocumented).- One deployment story: plane process + agents with URL + shared contract via APIs.
Reference: docs/notes/2026-07-23-design-fix-notes.md §4
Summary
Embedded / in-process plane (
TOKENOPS_EMBEDDED, noTOKENOPS_URL, mounting/v1/runson the agent) duplicates control-plane responsibility inside agent processes. Two modes to explain, test, and keep in sync. WhenTOKENOPS_URLis set, agents should not keep a hybrid localTOKENOPS_DBledger path.Area:
ControlPlaneClient.from_env,TOKENOPS_EMBEDDED, localStoreas plane substitute,should_mount_run_registrationDesired behavior
TOKENOPS_URL)./v1/runs.TOKENOPS_DBfor ledger whenTOKENOPS_URLis set.Acceptance sketch
TOKENOPS_EMBEDDEDremoved (or test-only and undocumented).Reference:
docs/notes/2026-07-23-design-fix-notes.md§4