fix(v0.1.5): reject Mapping action + integration test parity

Two release-readiness gaps caught by self-review on PR #11:

1. CyclesModelGate.__init__ now rejects per-tool Mapping action with a
   TypeError mirroring CyclesFanOutGate's behavior. Without this check,
   passing a Mapping (e.g. {'send_email': Action(...)}) to CyclesModelGate
   would fail at the first model call with the less-informative
   ValueError 'Action mapping requires a tool name' from resolve_action.
   Mappings are meaningless for ModelGate (model calls don't carry a
   tool name); rejecting at construction with a clearer error matches
   CyclesFanOutGate's pattern.

2. tests/integration/test_live_agent.py extended to:
   - Confirm CyclesModelGate satisfies the AgentMiddleware protocol
   - Confirm a real create_agent() call accepts CyclesModelGate as
     middleware
   - Confirm all three middleware compose in a single create_agent()
     call (the canonical v0.1.5+ shape with fan-out -> model -> tool
     ordering)

Without (2), the package had unit-test coverage for ModelGate but no
proof that LangChain's create_agent accepts the new middleware at
runtime. The new tests catch any future LangChain release that breaks
the wrap_model_call signature or hook registration.

118 tests pass (was 115, +3 new). Coverage 99.07%. ruff + mypy clean.

Author: amavashev

langchain_runcycles/model_gate.py

@@ -22,6 +22,7 @@
 from __future__ import annotations
 
 import logging
+from collections.abc import Mapping
 from typing import TYPE_CHECKING, Any, Literal
 
 from langchain.agents.middleware import AgentMiddleware
@@ -86,6 +87,12 @@ def __init__(
                 f"Invalid settlement_error_policy {settlement_error_policy!r}; "
                 f"expected one of {_VALID_SETTLEMENT_POLICIES}."
             )
+        if isinstance(action, Mapping):
+            raise TypeError(
+                "CyclesModelGate.action does not support per-tool Mapping: model "
+                "calls don't carry a tool name. Pass a single Action or a "
+                "Callable[[ModelRequest], Action]."
+            )
         self._client = client
         self._subject = subject
         self._action = action

tests/integration/test_live_agent.py

@@ -22,14 +22,15 @@
 from langchain_core.tools import tool
 from runcycles import Action, CyclesClient, CyclesConfig, CyclesResponse, Subject
 
-from langchain_runcycles import CyclesFanOutGate, CyclesToolGate
+from langchain_runcycles import CyclesFanOutGate, CyclesModelGate, CyclesToolGate
 
 
 def test_classes_satisfy_AgentMiddleware_protocol() -> None:
-    """Both middleware classes must inherit from AgentMiddleware so create_agent
-    accepts them in its `middleware=[...]` list."""
+    """All three middleware classes must inherit from AgentMiddleware so
+    create_agent accepts them in its `middleware=[...]` list."""
     assert issubclass(CyclesToolGate, AgentMiddleware)
     assert issubclass(CyclesFanOutGate, AgentMiddleware)
+    assert issubclass(CyclesModelGate, AgentMiddleware)
 
 
 def test_create_agent_accepts_tool_gate(sync_client: CyclesClient, subject: Any, action: Any) -> None:
@@ -87,6 +88,65 @@ def noop(x: str) -> str:
     assert agent is not None
 
 
+def test_create_agent_accepts_model_gate(sync_client: CyclesClient, subject: Any) -> None:
+    """A real `create_agent` call with CyclesModelGate as middleware succeeds.
+    Verifies the wrap_model_call hook annotation is well-formed."""
+
+    @tool
+    def noop(x: str) -> str:
+        """A no-op tool."""
+        return x
+
+    fake_model = FakeMessagesListChatModel(responses=[AIMessage(content="ok")])
+    model_gate = CyclesModelGate(
+        sync_client,
+        subject=subject,
+        action=Action(kind="llm.completion", name="fake-model"),
+        mode="decide",
+    )
+
+    agent = create_agent(model=fake_model, tools=[noop], middleware=[model_gate])
+    assert agent is not None
+
+
+def test_create_agent_accepts_full_triad(
+    sync_client: CyclesClient, subject: Any, action: Any
+) -> None:
+    """All three middleware classes composed in a single create_agent call.
+
+    This is the v0.1.5+ canonical shape: fan-out -> model -> tool ordering as
+    the recommended composition pattern. Verifies the three classes don't
+    interfere with each other's hook registration.
+    """
+
+    @tool
+    def noop(x: str) -> str:
+        """A no-op tool."""
+        return x
+
+    fake_model = FakeMessagesListChatModel(responses=[AIMessage(content="ok")])
+    fanout = CyclesFanOutGate(
+        5,
+        client=sync_client,
+        subject=Subject(tenant="acme"),
+        action=Action(kind="model.turn", name="research"),
+    )
+    model_gate = CyclesModelGate(
+        sync_client,
+        subject=subject,
+        action=Action(kind="llm.completion", name="fake-model"),
+        mode="decide",
+    )
+    tool_gate = CyclesToolGate(sync_client, subject=subject, action=action, mode="decide")
+
+    agent = create_agent(
+        model=fake_model,
+        tools=[noop],
+        middleware=[fanout, model_gate, tool_gate],
+    )
+    assert agent is not None
+
+
 @pytest.fixture
 def subject() -> Subject:  # noqa: F811 - integration tests don't import the package conftest
     return Subject(tenant="acme", agent="bot")

tests/test_model_gate.py

@@ -32,6 +32,22 @@ def test_invalid_settlement_policy_raises(sync_client: CyclesClient, subject: An
         )
 
 
+def test_model_gate_rejects_mapping_action(sync_client: CyclesClient, subject: Any) -> None:
+    """A per-tool-name Mapping makes no sense for CyclesModelGate (which gates
+    LLM calls, not tool calls). Reject at construction with a clear error rather
+    than letting it fail mid-call with the less-informative 'tool name required'
+    error from resolve_action."""
+    from runcycles import Action
+
+    mapping = {"some_tool": Action(kind="tool.call", name="some_tool")}
+    with pytest.raises(TypeError, match="does not support per-tool Mapping"):
+        CyclesModelGate(
+            sync_client,
+            subject=subject,
+            action=mapping,  # type: ignore[arg-type]
+        )
+
+
 # --- decide-mode paths ---------------------------------------------------------------