feat(list_reservations): lock in from/to ISO-8601 window passthrough (0.4.2)

Client-side companion to cycles-protocol-v0.yaml revision 2026-05-21
(runcycles/cycles-protocol#97) and runcycles/cycles-server#160. Closes
issue #159 from the client perspective.

The existing `list_reservations(**query_params: str)` signature already
forwards arbitrary kwargs to the URL query string, so the new `from`
and `to` ISO-8601 date-time params work over the wire today without a
code change. This commit adds sync + async regression tests that pin
that contract — future tightening of the kwargs signature cannot drop
the new params silently.

Caveat baked into the tests: `from` is a Python reserved keyword, so
the supported call-site syntax is the dict-unpack form

  client.list_reservations(**{
      "from": "2026-05-21T00:00:00Z",
      "to":   "2026-05-22T00:00:00Z",
  })

rather than direct kwargs. CHANGELOG.md documents this for users.

No protocol or wire-format change; servers older than v0.1.25.20
silently ignore the new params per the additive-parameter guarantee
in cycles-protocol-v0.yaml. 391 tests pass at 100% coverage.

Bumped to 0.4.2, updated AUDIT.md and CHANGELOG.md.

Author: amavashev

AUDIT.md

@@ -1,7 +1,8 @@
-# Cycles Protocol v0.1.23 — Client (Python) Audit
+# Cycles Protocol v0.1.25 — Client (Python) Audit
 
-**Date:** 2026-03-14
-**Spec:** `cycles-protocol-v0.yaml` (OpenAPI 3.1.0, v0.1.23)
+**Date:** 2026-05-21 (v0.4.2 — `from` / `to` ISO-8601 window-filter passthrough on `list_reservations` per `cycles-protocol-v0.yaml` revision 2026-05-21; closes the client side of runcycles/cycles-server#159. No code change — the existing `**query_params` signature already forwards arbitrary kwargs to the URL query string. Added sync + async regression tests that lock the passthrough in (using the `**{"from": ..., "to": ...}` dict-unpack form because `from` is a Python reserved keyword). 391 tests pass at 100% coverage.),
+2026-03-14
+**Spec:** `cycles-protocol-v0.yaml` (OpenAPI 3.1.0, v0.1.25)
 **Client:** `runcycles` (Python 3.10+ / httpx / Pydantic v2)
 **Server audit:** See `cycles-server/AUDIT.md` (all passing)
 

CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.2] - 2026-05-21
+
+Wire-passthrough verification for the new `from` / `to` query params on `list_reservations`. Implements `cycles-protocol-v0.yaml` revision 2026-05-21 ([runcycles/cycles-protocol#97](https://github.com/runcycles/cycles-protocol/pull/97)) on the client side; runcycles/cycles-server#160 ships the server impl.
+
+### Added
+
+- Sync + async regression tests confirming `list_reservations` forwards `from` / `to` ISO-8601 date-time values to the URL query string byte-exactly. The client's `**query_params` signature already accepted these — the tests lock that in so future tightening cannot drop the params silently.
+
+### Notes
+
+- **`from` is a Python reserved keyword.** Callers cannot write `client.list_reservations(from="...", to="...")` directly. The supported pattern is the dict-unpack form:
+  ```python
+  client.list_reservations(**{"from": "2026-05-21T00:00:00Z", "to": "2026-05-22T00:00:00Z"})
+  ```
+  The wire format is identical; only the Python call-site syntax differs.
+- No protocol or wire-format change. Servers older than v0.1.25.20 will silently ignore the params per the additive-parameter guarantee in `cycles-protocol-v0.yaml`.
+- 391 tests pass at 100% coverage (gate ≥95%).
+
 ## [0.4.1] - 2026-05-08
 
 PyPI metadata refresh for category-search discovery. No code changes; package wire format and API are identical to 0.4.0.

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "runcycles"
-version = "0.4.1"
+version = "0.4.2"
 description = "Python AI agent budget control — enforce LLM cost limits, tool permissions, and multi-tenant policies before agent actions execute."
 readme = "README.md"
 license = "Apache-2.0"

tests/test_client.py

@@ -154,6 +154,30 @@ def test_list_reservations(self, config: CyclesConfig, httpx_mock) -> None:  # t
 
         assert response.is_success
 
+    def test_list_reservations_with_from_to_window(self, config: CyclesConfig, httpx_mock) -> None:  # type: ignore[no-untyped-def]
+        """`from`/`to` ISO-8601 window filter passthrough (cycles-protocol v0.1.25 revision 2026-05-21).
+
+        `from` is a Python reserved keyword so callers must use the dict-unpack form
+        `**{"from": ..., "to": ...}` rather than a direct kwarg. The client forwards
+        the params byte-exactly to the URL query string."""
+        httpx_mock.add_response(
+            method="GET",
+            url="http://localhost:7878/v1/reservations?tenant=acme&from=2026-05-21T00%3A00%3A00Z&to=2026-05-22T00%3A00%3A00Z",
+            json={"reservations": [], "has_more": False},
+            status_code=200,
+        )
+
+        with CyclesClient(config) as client:
+            response = client.list_reservations(
+                **{
+                    "tenant": "acme",
+                    "from": "2026-05-21T00:00:00Z",
+                    "to": "2026-05-22T00:00:00Z",
+                }
+            )
+
+        assert response.is_success
+
     def test_get_reservation(self, config: CyclesConfig, httpx_mock) -> None:  # type: ignore[no-untyped-def]
         httpx_mock.add_response(
             method="GET",
@@ -397,6 +421,28 @@ async def test_list_reservations(self, config: CyclesConfig, httpx_mock) -> None
 
         assert response.is_success
 
+    async def test_list_reservations_with_from_to_window(self, config: CyclesConfig, httpx_mock) -> None:  # type: ignore[no-untyped-def]
+        """Async parity for the `from`/`to` window-filter passthrough.
+
+        See sync sibling for the reserved-keyword caveat on `from`."""
+        httpx_mock.add_response(
+            method="GET",
+            url="http://localhost:7878/v1/reservations?tenant=acme&from=2026-05-21T00%3A00%3A00Z&to=2026-05-22T00%3A00%3A00Z",
+            json={"reservations": [], "has_more": False},
+            status_code=200,
+        )
+
+        async with AsyncCyclesClient(config) as client:
+            response = await client.list_reservations(
+                **{
+                    "tenant": "acme",
+                    "from": "2026-05-21T00:00:00Z",
+                    "to": "2026-05-22T00:00:00Z",
+                }
+            )
+
+        assert response.is_success
+
     async def test_get_reservation(self, config: CyclesConfig, httpx_mock) -> None:  # type: ignore[no-untyped-def]
         httpx_mock.add_response(
             method="GET",