Merge pull request #11 from runcycles/feat/v0.1.5-model-gate

feat(v0.1.5): CyclesModelGate via wrap_model_call (architecture parity)

Author: amavashev

AUDIT.md

@@ -1,7 +1,7 @@
 # langchain-runcycles — Middleware API Conformance Audit
 
 **Date:** 2026-05-10
-**Package:** `langchain-runcycles` v0.1.4
+**Package:** `langchain-runcycles` v0.1.5
 **LangChain target:** `langchain >= 1.0, < 2.0`, `langchain-core >= 1.0, < 2.0` (tested against `langchain==1.2.18`, `langchain-core==1.3.3`, `langgraph==1.1.10`)
 **Cycles SDK target:** `runcycles >= 0.4.1` (tested against `runcycles==0.4.1`, Python 3.10+)
 **Server audit:** Cycles protocol conformance is owned by [`cycles-client-python/AUDIT.md`](https://github.com/runcycles/cycles-client-python/blob/main/AUDIT.md). This document audits this package's contract with the LangChain agent middleware API only.
@@ -41,6 +41,8 @@ Compared the following across LangChain documentation and this package's source:
 |---|---|---|
 | `wrap_tool_call(self, request, handler)` | `langchain_runcycles/tool_gate.py:80` | Sync. Reads `request.tool_call['name'/'args'/'id']` and `request.state` (best-effort). Returns `ToolMessage` on deny, else `handler(request)`. |
 | `awrap_tool_call(self, request, handler)` | `langchain_runcycles/tool_gate.py:160` | Async. Awaits the SDK; awaits `handler(request)` if it returns a coroutine. |
+| `wrap_model_call(self, request, handler)` | `langchain_runcycles/model_gate.py:108` | Sync (v0.1.5+). Reads `request.state` (best-effort). Returns `ModelResponse(result=[AIMessage(...)])` on deny — agent terminates naturally because the AIMessage has no `tool_calls`. |
+| `awrap_model_call(self, request, handler)` | `langchain_runcycles/model_gate.py:188` | Async (v0.1.5+). Awaits the SDK; awaits `handler(request)` if it returns a coroutine. |
 | `before_model(self, state, runtime)` | `langchain_runcycles/fanout.py:81` | Sync. Decorated with `@hook_config(can_jump_to=["end"])`. Returns `None` when allowed, halt-dict otherwise. |
 | `abefore_model(self, state, runtime)` | `langchain_runcycles/fanout.py:113` | Async. Same contract. |
 
@@ -113,8 +115,9 @@ Locked down by `tests/test_tool_gate.py::test_idempotency_keys_are_deterministic
 
 ## Test coverage
 
-- 85 tests across:
+- 115 tests across:
   - `tests/test_tool_gate.py`, `tests/test_tool_gate_async.py` — sync + async tool-gate paths (including settlement_error_policy raise/log, idempotency-key determinism, and v0.1.3 namespace static/callable/no-namespace/cross-run-collision)
+  - `tests/test_model_gate.py`, `tests/test_model_gate_async.py` — sync + async model-gate paths (v0.1.5+); decide allow/deny, reserve lifecycle, settlement raise/log, namespace
   - `tests/test_fanout.py`, `tests/test_fanout_async.py` — sync + async fan-out paths (including state-derived idempotency namespace)
   - `tests/test_examples.py` — import smoke for bundled examples
   - `tests/integration/test_live_agent.py` — `create_agent` construction with our middleware against a `FakeMessagesListChatModel`, verifying the AgentMiddleware contract is satisfied at runtime
@@ -126,7 +129,7 @@ Locked down by `tests/test_tool_gate.py::test_idempotency_keys_are_deterministic
 ## Known limitations (v0.1.x)
 
 - **Reserve mode commits at estimate**, not at actual usage. Tool-level cost instrumentation is left to the caller. A future revision may expose a `cost_fn` analogous to `stream_reservation`. Locked down by `tests/test_tool_gate.py::test_commit_called_with_configured_estimate`.
-- **No model-call middleware yet.** `CyclesModelGate` (using `wrap_model_call`) is planned for v0.2; v0.1.x covers tool-call gating and fan-out caps only. For LLM-spend tracking today, use `runcycles.stream_reservation` directly inside an LLM-spend handler.
+- **Model-call middleware ships at architecture parity, not production parity.** `CyclesModelGate` (v0.1.5+) implements `wrap_model_call` with the same three modes as `CyclesToolGate`, but commits at the configured `estimate` (no provider-specific token extraction yet) and uses a UUID per-call key (model requests don't carry a stable upstream id like `tool_call_id`). Provider extractors (OpenAI, Anthropic) and streaming integration are v0.2.0 scope. For precise actual-cost capture today, use the callback handler from `cycles-client-python` or wait for v0.2.0.
 - **Single tenant per middleware instance** unless you supply a `SubjectExtractor` callable. Per-call subject resolution is fully supported via the callable form; only the static-Subject convenience is single-tenant.
 - **Synthetic `tool_call_id` when missing.** A `ToolCallRequest` with no `id` field has its denial `ToolMessage` correlated via a fabricated `missing-<12-hex>` id, with a warning logged at `langchain_runcycles._internal`. Because the synthesis is fresh per call, the resulting idempotency key on this fallback path is *not* retry-stable. Conformant LangChain runtimes always supply `id`. Locked down by `tests/test_tool_gate.py::test_synthetic_tool_call_id_when_missing`.
 - **Fan-out gate rejects per-tool action mappings.** `CyclesFanOutGate` gates *model turns*, not tool calls; a per-tool-name `Mapping` for `action` is meaningless there and is rejected at construction with `TypeError`. Locked down by `tests/test_fanout.py::test_fanout_rejects_mapping_action`.

CHANGELOG.md

@@ -5,6 +5,43 @@ 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.1.5] - 2026-05-10
+
+Adds `CyclesModelGate` — pre-model-call authorization middleware — closing the third leg of the LangChain agent governance triad. Closes #10.
+
+`CyclesToolGate` already gated tool calls; `CyclesFanOutGate` already capped model turns; this release adds the third middleware so model calls themselves are intercepted via LangChain's `wrap_model_call` hook. With v0.1.5, the package can truthfully say it puts pre-execution authority in front of model calls, tool calls, and runaway agent loops.
+
+This is the **architecture milestone** — feature parity with `CyclesToolGate`. The **production milestone** (v0.2.0) will add provider-specific token-cost extractors, streaming integration, and a polished demo agent.
+
+### Added
+
+- **`CyclesModelGate`** — new `AgentMiddleware` subclass overriding `wrap_model_call` (sync) and `awrap_model_call` (async). On denial in `decide` mode, returns a `ModelResponse` whose `AIMessage` carries the denial reason (the agent terminates naturally because the AIMessage has no `tool_calls`).
+- **All three modes** (`decide` / `reserve` / `decide+reserve`) at parity with `CyclesToolGate`.
+- **`settlement_error_policy`** parity (default `"raise"`).
+- **`idempotency_namespace`** parity (static or callable, callable receives the `ModelRequest`).
+- **Public API exports**: `CyclesModelGate` re-exported from `langchain_runcycles`.
+
+### Changed
+
+- README "What's in the box" gains a third bullet for `CyclesModelGate`.
+- AUDIT.md hooks table gains `wrap_model_call` / `awrap_model_call` rows; "No model-call middleware yet" line removed from Known Limitations.
+- `docs/runcycles.mdx` gets a third middleware section + a 3-class composition example.
+
+### Known limitations (carried into v0.2.0)
+
+- **Commits at the configured `estimate`**, not actual token cost. Provider-specific token extraction (OpenAI, Anthropic) is v0.2.0 scope. For precise per-call actual-cost capture today, use the callback handler from `cycles-client-python` instead, or until v0.2.0 ships.
+- **No streaming integration**. For streaming LLM calls, use `runcycles.stream_reservation` directly. v0.2.0 may add streaming support inside `wrap_model_call`.
+- **Per-call key uses UUID fallback**. Model-call requests don't carry an upstream-stable id like `tool_call_id`, so each call gets a fresh UUID for the per-call slot. Namespacing (`model-decide-{namespace}-{32-hex}`) still scopes by run/workflow/tenant. v0.2.0 may extract a turn-id or message-hash for full retry-stability.
+
+### Test coverage
+
+- 28 new tests (115 total, was 87). Coverage 99.07% (gate 95%).
+- Sync + async parity for all paths; dedicated tests for the deny-path `ModelResponse` shape.
+
+### Backward compatibility
+
+Purely additive. v0.1.4 callers' code unchanged.
+
 ## [0.1.4] - 2026-05-10
 
 External review of v0.1.3 caught two real defects (stale README dep line, type alias narrower than the documented per-call opt-out) plus a docs-example issue (undefined helper in a runnable-looking snippet). All fixed; no functional change.
@@ -85,6 +122,7 @@ Initial public release. First-class LangChain agent middleware integration for C
 - Examples: `tenant_budget_agent.py` (tenant cap + risky-tool denial) and `multi_agent_fanout.py` (multi-agent / HITL flow).
 - `AUDIT.md` documenting LangChain middleware API conformance (hooks, ToolMessage shape, jump_to semantics, SDK methods consumed).
 
+[0.1.5]: https://github.com/runcycles/langchain-runcycles/compare/v0.1.4...v0.1.5
 [0.1.4]: https://github.com/runcycles/langchain-runcycles/compare/v0.1.3...v0.1.4
 [0.1.3]: https://github.com/runcycles/langchain-runcycles/compare/v0.1.2...v0.1.3
 [0.1.2]: https://github.com/runcycles/langchain-runcycles/compare/v0.1.1...v0.1.2

README.md

@@ -6,23 +6,25 @@
 
 # Cycles for LangChain — AI agent middleware for budget and action authority
 
-**LangChain middleware for pre-tool-call authorization, fan-out caps, and per-tenant budget enforcement in `create_agent` workflows.** Provider-neutral: works with any LangChain 1.x agent regardless of model provider, as long as actions flow through LangChain middleware/tool execution.
+**LangChain middleware for pre-execution budget authority over model calls, tool calls, and runaway agent loops in `create_agent` workflows.** Provider-neutral: works with any LangChain 1.x agent regardless of model provider, as long as actions flow through LangChain middleware/tool execution.
 
 Built on LangChain's [`AgentMiddleware`](https://docs.langchain.com/oss/python/langchain/middleware/) API:
 
+- **`wrap_model_call`** — pre-model-call authorization plus optional reserve/commit/release lifecycle around each LLM invocation (v0.1.5+)
 - **`wrap_tool_call`** — tool-call authorization plus optional reserve/commit/release lifecycle around each tool execution
 - **`before_model`** (with `@hook_config(can_jump_to=["end"])`) — fan-out caps and external policy halts before another model turn
 
-Model-call reservation via `wrap_model_call` is on the roadmap but **not implemented in v0.1.x**. For token-level streaming budget tracking today, use `runcycles.stream_reservation` directly inside an LLM-spend handler.
+Per-call actual-cost extraction (provider-specific token-usage parsing) and streaming integration are v0.2.0 scope. Until then, `CyclesModelGate` commits at the configured `estimate`; for precise per-call token capture today, use the `BaseCallbackHandler` recipe in [`cycles-client-python/examples/langchain_integration.py`](https://github.com/runcycles/cycles-client-python/blob/main/examples/langchain_integration.py).
 
 Install via `pip install langchain-runcycles`.
 
 ## What's in the box
 
+- **`CyclesModelGate`** (v0.1.5+) — runs before every model call. Authorizes via `client.decide()` and/or reserves budget. Returns a `ModelResponse` carrying the denial reason on deny so the agent terminates naturally.
 - **`CyclesToolGate`** — runs before every tool call. Authorizes via `client.decide()` and/or reserves budget via `client.create_reservation()`. Returns a `ToolMessage` on denial so the model can recover gracefully.
 - **`CyclesFanOutGate`** — runs before every model turn. Halts the agent (with `jump_to: "end"`) when a turn cap is hit or when an external policy says to stop. Useful for runaway-loop protection and per-tenant burst caps.
 
-Both work with sync or async LangChain agents and the sync (`CyclesClient`) or async (`AsyncCyclesClient`) Cycles client.
+All three work with sync or async LangChain agents and the sync (`CyclesClient`) or async (`AsyncCyclesClient`) Cycles client. Compose them in a single `middleware=[...]` list — typical order is `[CyclesFanOutGate, CyclesModelGate, CyclesToolGate]` so fan-out caps trigger before model spend before tool side effects.
 
 ## Installation
 
@@ -61,6 +63,24 @@ If `client.decide()` denies the call, `send_email` is never invoked — the mode
 
 ## Middleware
 
+### `CyclesModelGate` (v0.1.5+)
+
+Gates each model call. Same three modes as `CyclesToolGate`. On denial in `decide` mode, returns a `ModelResponse` whose `AIMessage` carries the denial reason — the agent terminates naturally because the AIMessage has no `tool_calls`.
+
+```python
+from langchain_runcycles import CyclesModelGate
+
+model_gate = CyclesModelGate(
+    client,
+    subject=Subject(tenant="acme", agent="researcher"),
+    action=Action(kind="llm.completion", name="gpt-4o"),
+    mode="reserve",
+    estimate=Amount(unit=Unit.USD_MICROCENTS, amount=2_000_000),  # $0.02 per call
+)
+```
+
+> v0.1.5 commits at the configured `estimate`. Per-call actual-cost extraction (token usage from provider response metadata) and streaming integration land in v0.2.0. For precise per-call token cost capture today, use the `BaseCallbackHandler` recipe in [`cycles-client-python/examples/langchain_integration.py`](https://github.com/runcycles/cycles-client-python/blob/main/examples/langchain_integration.py).
+
 ### `CyclesToolGate`
 
 Gates each tool call. Three modes:

docs/runcycles.mdx

@@ -122,6 +122,74 @@ agent.invoke({"messages": [{"role": "user", "content": "Email alice@example.com
 
 ---
 
+## CyclesModelGate: pre-model-call authorization (v0.1.5+)
+
+`CyclesModelGate` overrides `wrap_model_call` to gate every LLM invocation. Same three modes as `CyclesToolGate`. On denial in `decide` mode, returns a `ModelResponse` whose `AIMessage` carries the denial reason: the agent terminates naturally because the `AIMessage` has no `tool_calls`.
+
+| Mode | Behavior |
+| :--- | :--- |
+| `"decide"` | Calls `client.decide()`. Denies the model call on a non-allow decision. No reservation. |
+| `"reserve"` | Creates a reservation, calls the model, commits on success (at the configured `estimate`), releases on exception. |
+| `"decide+reserve"` | Authorizes via `decide()` first, then reserves and commits at the configured `estimate`. Most strict. |
+
+```python CyclesModelGate icon="cpu"
+from langchain_runcycles import CyclesModelGate
+from runcycles import Action, Amount, Subject, Unit
+
+model_gate = CyclesModelGate(
+    client,
+    subject=Subject(tenant="acme", agent="researcher"),
+    action=Action(kind="llm.completion", name="gpt-4o"),
+    mode="reserve",
+    estimate=Amount(unit=Unit.USD_MICROCENTS, amount=2_000_000),  # $0.02 per call
+    denial_message="Cycles denied this model call: {reason}",
+)
+```
+
+<Tip>
+    v0.1.5 commits at the configured `estimate` rather than extracting actual token usage from the provider response. Provider-specific token extractors (OpenAI, Anthropic) and streaming integration land in v0.2.0. For precise per-call token cost capture today, the `BaseCallbackHandler` recipe in `cycles-client-python` works alongside this middleware.
+</Tip>
+
+### Compose all three gates
+
+The full LangChain agent governance triad (fan-out caps, model-spend reservation, and tool-call authorization) uses one `middleware=[...]` list:
+
+```python All three gates icon="layer-group"
+from langchain.agents import create_agent
+from langchain_runcycles import CyclesFanOutGate, CyclesModelGate, CyclesToolGate
+from runcycles import Action, Amount, Subject, Unit
+
+agent = create_agent(
+    model="claude-sonnet-4-6",
+    tools=[search, send_email],
+    middleware=[
+        CyclesFanOutGate(
+            max_turns=20,
+            client=client,
+            subject=Subject(tenant="acme"),
+            action=Action(kind="model.turn", name="research"),
+        ),
+        CyclesModelGate(
+            client,
+            subject=Subject(tenant="acme", agent="researcher"),
+            action=Action(kind="llm.completion", name="claude-sonnet-4-6"),
+            mode="reserve",
+            estimate=Amount(unit=Unit.USD_MICROCENTS, amount=2_000_000),
+        ),
+        CyclesToolGate(
+            client,
+            subject=Subject(tenant="acme", agent="researcher"),
+            action={"send_email": Action(kind="tool.call", name="send_email")},
+            mode="decide+reserve",
+        ),
+    ],
+)
+```
+
+This order (fan-out first, then model, then tool) means runaway loops halt before model spend, and model spend is reserved before tool side effects.
+
+---
+
 ## CyclesToolGate: pre-tool-call authorization
 
 `CyclesToolGate` overrides `wrap_tool_call` to gate every tool call. It supports three modes:

langchain_runcycles/__init__.py

@@ -24,13 +24,15 @@
     TurnCounter,
 )
 from langchain_runcycles.fanout import CyclesFanOutGate
+from langchain_runcycles.model_gate import CyclesModelGate
 from langchain_runcycles.tool_gate import CyclesToolGate, Mode, SettlementErrorPolicy
 
 __all__ = [
     "ActionConfig",
     "ActionExtractor",
     "ActionMap",
     "CyclesFanOutGate",
+    "CyclesModelGate",
     "CyclesToolGate",
     "DenialFormatter",
     "IdempotencyNamespace",