agent-tokenops 0.2.1__tar.gz → 0.3.0__tar.gz

{agent_tokenops-0.2.1/src/agent_tokenops.egg-info → agent_tokenops-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-tokenops
-Version: 0.2.1
+Version: 0.3.0
 Summary: TokenOps control plane and SDK for run-aware agent token governance
 Author: Susheem Koul, Tisha Chawla
 License-Expression: MIT
@@ -38,6 +38,8 @@ Requires-Dist: ruff>=0.8; extra == "dev"
 Requires-Dist: mypy>=1.13; extra == "dev"
 Requires-Dist: pre-commit>=4.0; extra == "dev"
 Requires-Dist: types-PyYAML>=6.0; extra == "dev"
+Provides-Extra: contract
+Requires-Dist: agentplane-control-plane>=0.2.0; extra == "contract"
 Provides-Extra: examples
 Requires-Dist: ddgs>=9.0; extra == "examples"
 Requires-Dist: langchain-core>=0.3; extra == "examples"
@@ -100,7 +102,10 @@ add your own.
 
 ## 🚀 Quickstart
 
-Requires Python 3.10+.
+Requires Python 3.10+ and a running control plane — TokenOps has no ledger of its
+own, so every agent (even a single process) governs against one. Zero-setup taste:
+`python -m tokenops.demo` launches a throwaway plane for you automatically. For your
+own agent, start one first (see [Quickdeploy](#-quickdeploy) below), then:
 
 ### 1. Put it in your agent
 
@@ -123,14 +128,16 @@ Anywhere else (Cursor, Copilot, ...), paste this:
 <details>
 <summary><b>Manual</b>, about ten lines</summary>
 
-Wrap your model call once, then hand the wrapped version to your agent.
+Wrap your model call once, then hand the wrapped version to your agent. Needs
+`CONTROL_PLANE_URL` (or `TOKENOPS_URL`) pointing at a running control plane —
+see [Quickdeploy](#-quickdeploy).
 
 ```python
 from tokenops import ControlPlaneClient, tokenops_run
 from tokenops.control import Halt, wrap_complete
 from tokenops.providers import complete
 
-client = ControlPlaneClient.from_env()
+client = ControlPlaneClient.from_env()  # raises if CONTROL_PLANE_URL isn't set
 
 with tokenops_run(client=client, service="my-agent", intent="research",
                   provider="openai", model="gpt-4o") as bound:
@@ -178,9 +185,9 @@ run is out, even from another process.
 ## 🐳 Quickdeploy
 
 > [!TIP]
-> The control plane (`python -m tokenops.server`) shares one budget across
-> processes and powers the dashboard. A single-process agent doesn't need it
-> running at all.
+> Every agent needs a control plane running — TokenOps has no ledger of its own.
+> A single-process agent still needs one, just not the multi-process sharing this
+> section is about. `python -m tokenops.server` powers the dashboard too.
 
 One command, plane + dashboard:
 
@@ -231,8 +238,8 @@ export TOKENOPS_URL=http://localhost:7700
 export TOKENOPS_DB=tokenops.db   # plane and every agent read the same file
 ```
 
-> `TOKENOPS_EMBEDDED=1` overrides `TOKENOPS_URL`. Leave it unset here, or each
-> process silently falls back to its own local ledger and gets the full budget.
+> tokenops has no ledger of its own — every process governs against the plane at
+> `TOKENOPS_URL`. There is no local-fallback env var to accidentally leave unset.
 
 PyPI name is `agent-tokenops`; the import is `tokenops`. Extras:
 `pip install "agent-tokenops[examples]"` for the LangChain benches,
@@ -289,7 +296,7 @@ flowchart LR
 | **Control plane** (`python -m tokenops.server`) | `POST /v1/runs`, shared SQLite, Admin/Dashboard | Agent loops, LLM calls, tools |
 | **SDK (in agents)** | `tokenops_run`, `wrap_complete`, ledger/policies, Chronicle crossing hook | Ad-hoc run IDs; mounting `/v1/runs` when `TOKENOPS_URL` is set |
 
-Chronicle records decision boundaries; TokenOps attaches as the cost/governance observer on live crossings. See [Chronicle](https://github.com/theagentplane/chronicle) for record-and-replay.
+Chronicle records decision boundaries; TokenOps attaches as the cost/governance observer on live crossings. See [Chronicle](https://github.com/theagentplane/chronicle) for record-and-replay, accepted at [REALM](https://realm-workshop.github.io/) (Research on Agent Language Models), a workshop at EMNLP 2026.
 
 </details>
 
@@ -298,22 +305,15 @@ Chronicle records decision boundaries; TokenOps attaches as the cost/governance
 
 | Variable | Purpose |
 |---|---|
-| `TOKENOPS_URL` | Remote plane base URL (e.g. `http://localhost:7700`) → HTTP `register_run` |
-| `TOKENOPS_EMBEDDED` | Set to `1` to force in-process `Store` (tests / single-process) |
-| `TOKENOPS_DB` | SQLite path shared by plane + agents |
+| `TOKENOPS_URL` (or `CONTROL_PLANE_URL`) | The control plane's base URL (e.g. `http://localhost:8800`) — **required** |
 | `TOKENOPS_CONFIG` | YAML for governance seed (core: `src/tokenops/config/default.yaml`) |
 
-`TOKENOPS_URL` also accepts the aliases `CONTROL_PLANE_URL` and
+tokenops has no ledger or run registry of its own — `ControlPlaneClient.from_env()`
+raises if `TOKENOPS_URL`/`CONTROL_PLANE_URL` isn't set, rather than silently falling
+back to anything local. Every process talks to the same plane, so they share one
+budget by construction. `TOKENOPS_URL` also accepts the alias
 `TOKENOPS_CONTROL_PLANE_URL`.
 
-Production / multi-process: set `TOKENOPS_URL`; agents must **not** mount `/v1/runs`. Tests: `TOKENOPS_EMBEDDED=1` (or omit URL).
-
-> **Precedence.** `ControlPlaneClient.from_env` takes the HTTP path only when a
-> URL is set **and** `TOKENOPS_EMBEDDED` is not `1`. Setting both falls back to a
-> local SQLite file with no warning, and every process then gets its own full
-> budget. Check with
-> `print("embedded" if client.embedded else client.url)`.
-
 </details>
 
 <details>
@@ -372,6 +372,7 @@ tests/                     # unit + e2e
   [LinkedIn](https://www.linkedin.com/posts/microsoft-developers_who-spent-all-the-tokens-tokenops-gives-activity-7499191980715982848-224b) and [X](https://x.com/msdev/status/2093425027500978292).
 - **[Who spent all the tokens? Real-time, run-scoped cost control for AI agents](https://commandline.microsoft.com/tokenops-real-time-run-scoped-cost-control-ai-agents/)**: *Command Line*, a Microsoft publication.
 - **[FinOps for AI Agents: Who Spent All the Tokens?](https://www.youtube.com/watch?v=GJX19pNhmSw)**: talk at the **AI Engineer World's Fair**, San Francisco.
+- **Selected to participate in the [GitHub Secure Open Source Fund](https://github.com/open-source/github-secure-open-source-fund)** (Session 5), GitHub Security Lab's open source security program.
 
 ## 🛟 Support
 

{agent_tokenops-0.2.1 → agent_tokenops-0.3.0}/README.md

@@ -53,7 +53,10 @@ add your own.
 
 ## 🚀 Quickstart
 
-Requires Python 3.10+.
+Requires Python 3.10+ and a running control plane — TokenOps has no ledger of its
+own, so every agent (even a single process) governs against one. Zero-setup taste:
+`python -m tokenops.demo` launches a throwaway plane for you automatically. For your
+own agent, start one first (see [Quickdeploy](#-quickdeploy) below), then:
 
 ### 1. Put it in your agent
 
@@ -76,14 +79,16 @@ Anywhere else (Cursor, Copilot, ...), paste this:
 <details>
 <summary><b>Manual</b>, about ten lines</summary>
 
-Wrap your model call once, then hand the wrapped version to your agent.
+Wrap your model call once, then hand the wrapped version to your agent. Needs
+`CONTROL_PLANE_URL` (or `TOKENOPS_URL`) pointing at a running control plane —
+see [Quickdeploy](#-quickdeploy).
 
 ```python
 from tokenops import ControlPlaneClient, tokenops_run
 from tokenops.control import Halt, wrap_complete
 from tokenops.providers import complete
 
-client = ControlPlaneClient.from_env()
+client = ControlPlaneClient.from_env()  # raises if CONTROL_PLANE_URL isn't set
 
 with tokenops_run(client=client, service="my-agent", intent="research",
                   provider="openai", model="gpt-4o") as bound:
@@ -131,9 +136,9 @@ run is out, even from another process.
 ## 🐳 Quickdeploy
 
 > [!TIP]
-> The control plane (`python -m tokenops.server`) shares one budget across
-> processes and powers the dashboard. A single-process agent doesn't need it
-> running at all.
+> Every agent needs a control plane running — TokenOps has no ledger of its own.
+> A single-process agent still needs one, just not the multi-process sharing this
+> section is about. `python -m tokenops.server` powers the dashboard too.
 
 One command, plane + dashboard:
 
@@ -184,8 +189,8 @@ export TOKENOPS_URL=http://localhost:7700
 export TOKENOPS_DB=tokenops.db   # plane and every agent read the same file
 ```
 
-> `TOKENOPS_EMBEDDED=1` overrides `TOKENOPS_URL`. Leave it unset here, or each
-> process silently falls back to its own local ledger and gets the full budget.
+> tokenops has no ledger of its own — every process governs against the plane at
+> `TOKENOPS_URL`. There is no local-fallback env var to accidentally leave unset.
 
 PyPI name is `agent-tokenops`; the import is `tokenops`. Extras:
 `pip install "agent-tokenops[examples]"` for the LangChain benches,
@@ -242,7 +247,7 @@ flowchart LR
 | **Control plane** (`python -m tokenops.server`) | `POST /v1/runs`, shared SQLite, Admin/Dashboard | Agent loops, LLM calls, tools |
 | **SDK (in agents)** | `tokenops_run`, `wrap_complete`, ledger/policies, Chronicle crossing hook | Ad-hoc run IDs; mounting `/v1/runs` when `TOKENOPS_URL` is set |
 
-Chronicle records decision boundaries; TokenOps attaches as the cost/governance observer on live crossings. See [Chronicle](https://github.com/theagentplane/chronicle) for record-and-replay.
+Chronicle records decision boundaries; TokenOps attaches as the cost/governance observer on live crossings. See [Chronicle](https://github.com/theagentplane/chronicle) for record-and-replay, accepted at [REALM](https://realm-workshop.github.io/) (Research on Agent Language Models), a workshop at EMNLP 2026.
 
 </details>
 
@@ -251,22 +256,15 @@ Chronicle records decision boundaries; TokenOps attaches as the cost/governance
 
 | Variable | Purpose |
 |---|---|
-| `TOKENOPS_URL` | Remote plane base URL (e.g. `http://localhost:7700`) → HTTP `register_run` |
-| `TOKENOPS_EMBEDDED` | Set to `1` to force in-process `Store` (tests / single-process) |
-| `TOKENOPS_DB` | SQLite path shared by plane + agents |
+| `TOKENOPS_URL` (or `CONTROL_PLANE_URL`) | The control plane's base URL (e.g. `http://localhost:8800`) — **required** |
 | `TOKENOPS_CONFIG` | YAML for governance seed (core: `src/tokenops/config/default.yaml`) |
 
-`TOKENOPS_URL` also accepts the aliases `CONTROL_PLANE_URL` and
+tokenops has no ledger or run registry of its own — `ControlPlaneClient.from_env()`
+raises if `TOKENOPS_URL`/`CONTROL_PLANE_URL` isn't set, rather than silently falling
+back to anything local. Every process talks to the same plane, so they share one
+budget by construction. `TOKENOPS_URL` also accepts the alias
 `TOKENOPS_CONTROL_PLANE_URL`.
 
-Production / multi-process: set `TOKENOPS_URL`; agents must **not** mount `/v1/runs`. Tests: `TOKENOPS_EMBEDDED=1` (or omit URL).
-
-> **Precedence.** `ControlPlaneClient.from_env` takes the HTTP path only when a
-> URL is set **and** `TOKENOPS_EMBEDDED` is not `1`. Setting both falls back to a
-> local SQLite file with no warning, and every process then gets its own full
-> budget. Check with
-> `print("embedded" if client.embedded else client.url)`.
-
 </details>
 
 <details>
@@ -325,6 +323,7 @@ tests/                     # unit + e2e
   [LinkedIn](https://www.linkedin.com/posts/microsoft-developers_who-spent-all-the-tokens-tokenops-gives-activity-7499191980715982848-224b) and [X](https://x.com/msdev/status/2093425027500978292).
 - **[Who spent all the tokens? Real-time, run-scoped cost control for AI agents](https://commandline.microsoft.com/tokenops-real-time-run-scoped-cost-control-ai-agents/)**: *Command Line*, a Microsoft publication.
 - **[FinOps for AI Agents: Who Spent All the Tokens?](https://www.youtube.com/watch?v=GJX19pNhmSw)**: talk at the **AI Engineer World's Fair**, San Francisco.
+- **Selected to participate in the [GitHub Secure Open Source Fund](https://github.com/open-source/github-secure-open-source-fund)** (Session 5), GitHub Security Lab's open source security program.
 
 ## 🛟 Support
 

{agent_tokenops-0.2.1 → agent_tokenops-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-tokenops"
-version = "0.2.1"
+version = "0.3.0"
 description = "TokenOps control plane and SDK for run-aware agent token governance"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -56,6 +56,14 @@ dev = [
   "pre-commit>=4.0",
   "types-PyYAML>=6.0",
 ]
+# The verified-fake contract suite + e2e run against a real control plane in-process.
+# Not in `dev` because the 0.2.0 line is not on PyPI yet — the tests that need it
+# `pytest.importorskip("control_plane")`, so `[dev]` alone stays green. To run them:
+#   pip install -e ".[dev,contract]"      # once 0.2.0 is released, or
+#   pip install "agentplane-control-plane @ git+https://github.com/theagentplane/control-plane@main"
+contract = [
+  "agentplane-control-plane>=0.2.0",
+]
 examples = [
   "ddgs>=9.0",
   "langchain-core>=0.3",
@@ -74,10 +82,13 @@ testpaths = ["tests"]
 pythonpath = ["src", "."]
 asyncio_mode = "strict"
 markers = [
-  "e2e: example / bench end-to-end tests (not run in default CI)",
-  "live: requires API keys or vendored frameworks",
+  "e2e: example / bench end-to-end tests — real servers, real Governor/policy",
+  "     enforcement, faked model+network only. Part of the default suite (see",
+  "     addopts) precisely so real run+policy regressions are caught.",
+  "live: requires real API keys or vendored frameworks — self-skips without them,",
+  "      excluded from the default run since it needs secrets to do anything.",
 ]
-addopts = "-m 'not e2e and not live'"
+addopts = "-m 'not live'"
 
 [tool.ruff]
 target-version = "py310"

{agent_tokenops-0.2.1 → agent_tokenops-0.3.0/src/agent_tokenops.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-tokenops
-Version: 0.2.1
+Version: 0.3.0
 Summary: TokenOps control plane and SDK for run-aware agent token governance
 Author: Susheem Koul, Tisha Chawla
 License-Expression: MIT
@@ -38,6 +38,8 @@ Requires-Dist: ruff>=0.8; extra == "dev"
 Requires-Dist: mypy>=1.13; extra == "dev"
 Requires-Dist: pre-commit>=4.0; extra == "dev"
 Requires-Dist: types-PyYAML>=6.0; extra == "dev"
+Provides-Extra: contract
+Requires-Dist: agentplane-control-plane>=0.2.0; extra == "contract"
 Provides-Extra: examples
 Requires-Dist: ddgs>=9.0; extra == "examples"
 Requires-Dist: langchain-core>=0.3; extra == "examples"
@@ -100,7 +102,10 @@ add your own.
 
 ## 🚀 Quickstart
 
-Requires Python 3.10+.
+Requires Python 3.10+ and a running control plane — TokenOps has no ledger of its
+own, so every agent (even a single process) governs against one. Zero-setup taste:
+`python -m tokenops.demo` launches a throwaway plane for you automatically. For your
+own agent, start one first (see [Quickdeploy](#-quickdeploy) below), then:
 
 ### 1. Put it in your agent
 
@@ -123,14 +128,16 @@ Anywhere else (Cursor, Copilot, ...), paste this:
 <details>
 <summary><b>Manual</b>, about ten lines</summary>
 
-Wrap your model call once, then hand the wrapped version to your agent.
+Wrap your model call once, then hand the wrapped version to your agent. Needs
+`CONTROL_PLANE_URL` (or `TOKENOPS_URL`) pointing at a running control plane —
+see [Quickdeploy](#-quickdeploy).
 
 ```python
 from tokenops import ControlPlaneClient, tokenops_run
 from tokenops.control import Halt, wrap_complete
 from tokenops.providers import complete
 
-client = ControlPlaneClient.from_env()
+client = ControlPlaneClient.from_env()  # raises if CONTROL_PLANE_URL isn't set
 
 with tokenops_run(client=client, service="my-agent", intent="research",
                   provider="openai", model="gpt-4o") as bound:
@@ -178,9 +185,9 @@ run is out, even from another process.
 ## 🐳 Quickdeploy
 
 > [!TIP]
-> The control plane (`python -m tokenops.server`) shares one budget across
-> processes and powers the dashboard. A single-process agent doesn't need it
-> running at all.
+> Every agent needs a control plane running — TokenOps has no ledger of its own.
+> A single-process agent still needs one, just not the multi-process sharing this
+> section is about. `python -m tokenops.server` powers the dashboard too.
 
 One command, plane + dashboard:
 
@@ -231,8 +238,8 @@ export TOKENOPS_URL=http://localhost:7700
 export TOKENOPS_DB=tokenops.db   # plane and every agent read the same file
 ```
 
-> `TOKENOPS_EMBEDDED=1` overrides `TOKENOPS_URL`. Leave it unset here, or each
-> process silently falls back to its own local ledger and gets the full budget.
+> tokenops has no ledger of its own — every process governs against the plane at
+> `TOKENOPS_URL`. There is no local-fallback env var to accidentally leave unset.
 
 PyPI name is `agent-tokenops`; the import is `tokenops`. Extras:
 `pip install "agent-tokenops[examples]"` for the LangChain benches,
@@ -289,7 +296,7 @@ flowchart LR
 | **Control plane** (`python -m tokenops.server`) | `POST /v1/runs`, shared SQLite, Admin/Dashboard | Agent loops, LLM calls, tools |
 | **SDK (in agents)** | `tokenops_run`, `wrap_complete`, ledger/policies, Chronicle crossing hook | Ad-hoc run IDs; mounting `/v1/runs` when `TOKENOPS_URL` is set |
 
-Chronicle records decision boundaries; TokenOps attaches as the cost/governance observer on live crossings. See [Chronicle](https://github.com/theagentplane/chronicle) for record-and-replay.
+Chronicle records decision boundaries; TokenOps attaches as the cost/governance observer on live crossings. See [Chronicle](https://github.com/theagentplane/chronicle) for record-and-replay, accepted at [REALM](https://realm-workshop.github.io/) (Research on Agent Language Models), a workshop at EMNLP 2026.
 
 </details>
 
@@ -298,22 +305,15 @@ Chronicle records decision boundaries; TokenOps attaches as the cost/governance
 
 | Variable | Purpose |
 |---|---|
-| `TOKENOPS_URL` | Remote plane base URL (e.g. `http://localhost:7700`) → HTTP `register_run` |
-| `TOKENOPS_EMBEDDED` | Set to `1` to force in-process `Store` (tests / single-process) |
-| `TOKENOPS_DB` | SQLite path shared by plane + agents |
+| `TOKENOPS_URL` (or `CONTROL_PLANE_URL`) | The control plane's base URL (e.g. `http://localhost:8800`) — **required** |
 | `TOKENOPS_CONFIG` | YAML for governance seed (core: `src/tokenops/config/default.yaml`) |
 
-`TOKENOPS_URL` also accepts the aliases `CONTROL_PLANE_URL` and
+tokenops has no ledger or run registry of its own — `ControlPlaneClient.from_env()`
+raises if `TOKENOPS_URL`/`CONTROL_PLANE_URL` isn't set, rather than silently falling
+back to anything local. Every process talks to the same plane, so they share one
+budget by construction. `TOKENOPS_URL` also accepts the alias
 `TOKENOPS_CONTROL_PLANE_URL`.
 
-Production / multi-process: set `TOKENOPS_URL`; agents must **not** mount `/v1/runs`. Tests: `TOKENOPS_EMBEDDED=1` (or omit URL).
-
-> **Precedence.** `ControlPlaneClient.from_env` takes the HTTP path only when a
-> URL is set **and** `TOKENOPS_EMBEDDED` is not `1`. Setting both falls back to a
-> local SQLite file with no warning, and every process then gets its own full
-> budget. Check with
-> `print("embedded" if client.embedded else client.url)`.
-
 </details>
 
 <details>
@@ -372,6 +372,7 @@ tests/                     # unit + e2e
   [LinkedIn](https://www.linkedin.com/posts/microsoft-developers_who-spent-all-the-tokens-tokenops-gives-activity-7499191980715982848-224b) and [X](https://x.com/msdev/status/2093425027500978292).
 - **[Who spent all the tokens? Real-time, run-scoped cost control for AI agents](https://commandline.microsoft.com/tokenops-real-time-run-scoped-cost-control-ai-agents/)**: *Command Line*, a Microsoft publication.
 - **[FinOps for AI Agents: Who Spent All the Tokens?](https://www.youtube.com/watch?v=GJX19pNhmSw)**: talk at the **AI Engineer World's Fair**, San Francisco.
+- **Selected to participate in the [GitHub Secure Open Source Fund](https://github.com/open-source/github-secure-open-source-fund)** (Session 5), GitHub Security Lab's open source security program.
 
 ## 🛟 Support
 

{agent_tokenops-0.2.1 → agent_tokenops-0.3.0}/src/agent_tokenops.egg-info/SOURCES.txt

@@ -22,6 +22,7 @@ src/tokenops/control/config.py
 src/tokenops/control/context.py
 src/tokenops/control/core.py
 src/tokenops/control/crossing.py
+src/tokenops/control/dev_plane.py
 src/tokenops/control/engine.py
 src/tokenops/control/governance_cache.py
 src/tokenops/control/http.py
@@ -29,6 +30,7 @@ src/tokenops/control/http_store.py
 src/tokenops/control/instrument.py
 src/tokenops/control/integration.py
 src/tokenops/control/ledger.py
+src/tokenops/control/ledger_backend.py
 src/tokenops/control/models.py
 src/tokenops/control/pricing.py
 src/tokenops/control/propagate.py
@@ -93,6 +95,8 @@ tests/test_governance_config_cache.py
 tests/test_governance_per_agent.py
 tests/test_integration.py
 tests/test_ledger.py
+tests/test_ledger_backend_contract.py
+tests/test_ledger_backend_mode.py
 tests/test_llm_boundary_precall.py
 tests/test_output_runaway.py
 tests/test_policies_wrap_integration.py

{agent_tokenops-0.2.1 → agent_tokenops-0.3.0}/src/agent_tokenops.egg-info/requires.txt

@@ -8,6 +8,9 @@ httpx>=0.27
 fastapi>=0.115
 uvicorn>=0.32
 
+[contract]
+agentplane-control-plane>=0.2.0
+
 [dev]
 pytest>=8.0
 pytest-asyncio>=0.24

{agent_tokenops-0.2.1 → agent_tokenops-0.3.0}/src/tokenops/__init__.py

@@ -4,7 +4,7 @@ from tokenops.env import load_env
 
 load_env()
 
-__version__ = "0.2.1"
+__version__ = "0.3.0"
 
 
 def init() -> None:

{agent_tokenops-0.2.1 → agent_tokenops-0.3.0}/src/tokenops/control/__init__.py

@@ -62,7 +62,15 @@ from tokenops.control.integration import (
     wrap_complete,
     wrap_stream,
 )
-from tokenops.control.ledger import Budget, Ledger, RunState, segment_key
+from tokenops.control.ledger import Budget, Ledger, LocalRunState, segment_key
+from tokenops.control.ledger_backend import (
+    AggregateState,
+    ApplyResult,
+    HttpLedgerBackend,
+    LedgerBackend,
+    LedgerEvent,
+    PrecheckRequest,
+)
 
 # Process-wide: re-attach after every reset_session (Chronicle clears on_crossing).
 install_crossing_hook()
@@ -104,8 +112,15 @@ __all__ = [
     # ledger
     "Budget",
     "Ledger",
-    "RunState",
+    "LocalRunState",
     "segment_key",
+    # ledger backend (remote-only)
+    "LedgerBackend",
+    "HttpLedgerBackend",
+    "LedgerEvent",
+    "PrecheckRequest",
+    "AggregateState",
+    "ApplyResult",
     # harness
     "Governor",
     "RaiseControls",

{agent_tokenops-0.2.1 → agent_tokenops-0.3.0}/src/tokenops/control/client.py

@@ -1,13 +1,18 @@
 """SDK client for the TokenOps control plane.
 
-Prefer :class:`ControlPlaneClient` over posting ``/v1/runs`` at an agent URL.
-When ``TOKENOPS_URL`` is set, registration (and future plane APIs) go over HTTP.
-When ``TOKENOPS_EMBEDDED=1`` or no URL is set, the client uses an in-process
-:class:`~tokenops.control.store.Store` (shared SQLite via ``TOKENOPS_DB``).
-
-Agents should talk to the plane through this client (§6) — do not construct
-``Store(TOKENOPS_DB)`` on the happy path. ``require_store()`` is an escape hatch
-for ledger / dashboard rows until those APIs are fully remote.
+``ControlPlaneClient`` is the only supported way a live agent reaches the plane —
+``from_env()`` requires ``CONTROL_PLANE_URL`` / ``TOKENOPS_URL`` and raises if neither
+is set. There is no embedded / local-file fallback: tokenops has no ledger of its own
+(tokenops#118, the remote-only rewrite) — every spend/inflight/halt read or write goes
+to the control plane over HTTP via :meth:`backend` (a
+:class:`~tokenops.control.ledger_backend.LedgerBackend`), and registration/governance
+config/dashboard rows go through :class:`~tokenops.control.http_store.HttpStore`. Both
+are HTTP-only; neither ever opens a local SQLite file.
+
+The ``store=`` constructor kwarg is a explicit, visible test-only escape hatch (dependency
+injection for unit/integration tests that want to exercise policy logic against a local
+:class:`~tokenops.control.store.Store` without a running plane) — it is never reachable
+from ``from_env()``, so no environment misconfiguration can silently select it.
 """
 
 from __future__ import annotations
@@ -17,8 +22,11 @@ import os
 from collections.abc import Mapping
 from typing import Any, cast
 
+import httpx
+
 from tokenops.control.http import post_run, post_run_sync
 from tokenops.control.http_store import HttpStore
+from tokenops.control.ledger_backend import HttpLedgerBackend, LedgerBackend
 from tokenops.control.models import (
     GovernanceMode,
     RunAlreadyRegisteredError,
@@ -46,7 +54,7 @@ def _mode_value(mode: GovernanceMode | str | None) -> GovernanceMode:
 
 
 class ControlPlaneClient:
-    """Talk to a remote control plane or an embedded Store."""
+    """Talk to the remote control plane over HTTP (or, in tests only, a local Store)."""
 
     def __init__(
         self,
@@ -54,36 +62,43 @@ class ControlPlaneClient:
         url: str | None = None,
         store: Store | None = None,
         timeout: float = 30.0,
+        client: httpx.Client | None = None,
     ) -> None:
         if bool(url) == bool(store):
             raise ValueError("exactly one of url or store is required")
         self._url = url.rstrip("/") if url else None
         self._store = store
         self._hybrid_store: Any = None
+        self._backend: LedgerBackend | None = None
         self._timeout = timeout
+        self._client = client  # optional injected httpx.Client — tests only
 
     @classmethod
     def from_env(cls, *, timeout: float = 30.0) -> ControlPlaneClient:
-        """Build a client from ``TOKENOPS_URL`` / ``TOKENOPS_EMBEDDED`` / ``TOKENOPS_DB``.
+        """Build a client from ``CONTROL_PLANE_URL`` / ``TOKENOPS_URL``.
 
-        * ``TOKENOPS_URL`` or ``CONTROL_PLANE_URL`` set and ``TOKENOPS_EMBEDDED`` not ``1``
-          → HTTP to the plane (no local SQLite).
-        * otherwise → embedded :class:`Store` at ``TOKENOPS_DB``.
+        Raises if neither is set — tokenops has no embedded / local-file ledger to fall
+        back to (tokenops#118). Point this at a running control plane: ``control-plane
+        serve`` locally, or the Docker image, for anything other than tests that pass
+        ``store=`` explicitly.
         """
         from tokenops.control.crossing import install_crossing_hook
 
         install_crossing_hook()
-        embedded = os.environ.get("TOKENOPS_EMBEDDED", "").strip() == "1"
         url = (
             os.environ.get("CONTROL_PLANE_URL")
             or os.environ.get("TOKENOPS_URL")
             or os.environ.get("TOKENOPS_CONTROL_PLANE_URL")
             or ""
         ).strip()
-        if url and not embedded:
-            return cls(url=url, timeout=timeout)
-        db = os.environ.get("TOKENOPS_DB", "tokenops.db")
-        return cls(store=Store(db), timeout=timeout)
+        if not url:
+            raise RuntimeError(
+                "CONTROL_PLANE_URL (or TOKENOPS_URL) is required — tokenops has no "
+                "embedded/local ledger; point it at a running control plane. Run "
+                "`control-plane serve` locally (see the agentplane-control-plane "
+                "package) or use its Docker image, then set CONTROL_PLANE_URL to it."
+            )
+        return cls(url=url, timeout=timeout)
 
     @property
     def url(self) -> str | None:
@@ -91,29 +106,51 @@ class ControlPlaneClient:
 
     @property
     def embedded(self) -> bool:
+        """``True`` only for the explicit test-only ``store=`` constructor path.
+
+        Never ``True`` for a client built by :meth:`from_env` — there is no
+        environment variable that selects a local ledger.
+        """
         return self._store is not None
 
     @property
     def store(self) -> Store | None:
-        """Embedded registration Store, or ``None`` when registration is remote.
-
-        Prefer :meth:`governance_config_for`, :meth:`resolve_run`, and
-        :meth:`require_store` over using this directly. Escape hatch only (§6).
-        """
+        """The explicit test-only local Store, or ``None`` in the (only production)
+        remote mode. Prefer :meth:`backend`, :meth:`governance_config_for`, and
+        :meth:`resolve_run` over using this directly."""
         return self._store
 
+    @property
+    def backend(self) -> LedgerBackend:
+        """The :class:`~tokenops.control.ledger_backend.LedgerBackend` for this client
+        — every spend/inflight/halt read (``precheck``) and write (``events:batch``)
+        goes through this. Only valid in remote mode (``from_env()`` always is)."""
+        if self._url is None:
+            raise RuntimeError(
+                "no LedgerBackend for a store=-constructed (test-only) ControlPlaneClient"
+            )
+        if self._backend is None:
+            key = os.environ.get("CONTROL_PLANE_API_KEY") or os.environ.get("TOKENOPS_API_KEY")
+            self._backend = HttpLedgerBackend(
+                self._url, api_key=key, timeout=self._timeout, client=self._client
+            )
+        return self._backend
+
     def require_store(self) -> Store:
-        """Backing store for ledger / config / dashboard rows.
+        """Registration / governance-config / dashboard-row transport.
 
-        Embedded mode returns the in-process SQLite Store. Remote mode returns
-        :class:`HttpStore` — never a local DB file.
+        The test-only ``store=`` path returns that Store. Remote mode (``from_env()``)
+        returns :class:`HttpStore` — HTTP only, never a local DB file. Ledger accounting
+        (spend/inflight/halt) does **not** go through this — see :meth:`backend`.
         """
         if self._store is not None:
             return self._store
         if self._hybrid_store is None:
             assert self._url is not None
             key = os.environ.get("CONTROL_PLANE_API_KEY") or os.environ.get("TOKENOPS_API_KEY")
-            self._hybrid_store = HttpStore(self._url, api_key=key, timeout=self._timeout)
+            self._hybrid_store = HttpStore(
+                self._url, api_key=key, timeout=self._timeout, client=self._client
+            )
         return cast(Store, self._hybrid_store)
 
     def register_run(
@@ -203,9 +240,9 @@ class ControlPlaneClient:
 def should_mount_run_registration() -> bool:
     """Whether an agent app should expose ``POST /v1/runs``.
 
-    When ``TOKENOPS_URL`` points at a standalone plane (and embedded mode is off),
-    registration is centralized on the plane — agents must not mount the route.
+    Always ``False`` — registration is centralized on the plane (tokenops#118); there
+    is no embedded mode left for an agent to self-host it under. Kept (rather than
+    deleted outright) so existing ``if should_mount_run_registration(): ...`` call
+    sites keep working unchanged while they're cleaned up.
     """
-    if os.environ.get("TOKENOPS_EMBEDDED", "").strip() == "1":
-        return True
-    return not (os.environ.get("TOKENOPS_URL") or "").strip()
+    return False