Merge pull request #9 from runcycles/fix/v0.1.4-readme-and-type-alias

fix(v0.1.4): README dep line + IdempotencyNamespaceResolver type + docs example

Author: amavashev

AUDIT.md

@@ -1,7 +1,7 @@
 # langchain-runcycles — Middleware API Conformance Audit
 
 **Date:** 2026-05-10
-**Package:** `langchain-runcycles` v0.1.3
+**Package:** `langchain-runcycles` v0.1.4
 **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.

CHANGELOG.md

@@ -5,6 +5,20 @@ 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.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.
+
+### Fixed
+
+- **Stale `langchain-core >= 0.3` line in README's Requirements section.** `pyproject.toml` was correctly tightened to `>=1.0,<2.0` in v0.1.2 but the README wasn't updated at the time. Now consistent.
+- **`IdempotencyNamespaceResolver` type alias widened from `Callable[[Any], str]` to `Callable[[Any], str | None]`.** Runtime already supported a callable returning `None` (per-call opt-out, documented since v0.1.3 and tested by `test_callable_namespace_returning_none_opts_out_per_call`). The type signature was narrower than the documented contract; strict-mypy users would have hit a false negative when writing the documented opt-out callable. No behavior change.
+- **Docs idempotency-namespace example now uses `request.state["run_id"]`** instead of an undefined `current_run_id()` / `current_run_id_contextvar.get(...)` helper. The new form is runnable against a real LangChain `ToolCallRequest` and matches the LangChain idiom for accessing per-call state. README, `docs/runcycles.mdx`, and the langchain-ai/docs PR mirror all updated together.
+
+### Behavior change
+
+None. Type widening is permissive (the old narrower type was a strict subset of the new one), README and docs are user-facing prose. v0.1.3 callers' code keeps working unchanged.
+
 ## [0.1.3] - 2026-05-10
 
 Adds run / workflow / tenant scoping to Cycles idempotency keys, addressing the v0.1.2 review concern about cross-run collision when frameworks reuse short tool call ids like `tc_1`. Backward-compatible — keys without a configured namespace keep the v0.1.2 shape exactly. Closes #6.
@@ -71,6 +85,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.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
 [0.1.1]: https://github.com/runcycles/langchain-runcycles/compare/v0.1.0...v0.1.1

README.md

@@ -151,12 +151,11 @@ gate = CyclesToolGate(
     idempotency_namespace="run_2026_05_10_abc",
 )
 
-# Callable — receives the LangChain ToolCallRequest. Pull the namespace from
-# wherever your runtime exposes the run id (a contextvar, your own middleware,
-# request metadata, etc.). The exact accessor depends on your LangChain version.
-def my_run_id(_request):
-    # In production: return your_runtime.current_run_id()
-    return current_run_id_contextvar.get("default")
+# Callable — receives the LangChain ToolCallRequest. Pull the run id from
+# wherever your runtime carries it: request state, a contextvar, your own
+# middleware, etc.
+def my_run_id(request):
+    return request.state["run_id"]
 
 gate = CyclesToolGate(
     client,
@@ -262,7 +261,7 @@ mypy langchain_runcycles
 - Python 3.10+
 - `runcycles >= 0.4.1`
 - `langchain >= 1.0, < 2.0`
-- `langchain-core >= 0.3`
+- `langchain-core >= 1.0, < 2.0`
 
 ## License
 

docs/runcycles.mdx

@@ -273,9 +273,10 @@ gate = CyclesToolGate(
     idempotency_namespace="run_2026_05_10_abc",
 )
 
-# Callable: extract per call from your runtime's run-id source
-def my_run_id(_request):
-    return current_run_id()  # whatever your runtime exposes
+# Callable: receives the LangChain ToolCallRequest; pull the run id from
+# request state, a contextvar, your own middleware, etc.
+def my_run_id(request):
+    return request.state["run_id"]
 
 gate = CyclesToolGate(
     client,

langchain_runcycles/_config.py

@@ -29,10 +29,15 @@
 TurnCounter: TypeAlias = Callable[[Any], int]
 """(state) -> turn count. Default counts AIMessages; override for custom semantics."""
 
-IdempotencyNamespaceResolver: TypeAlias = Callable[[Any], str]
+IdempotencyNamespaceResolver: TypeAlias = Callable[[Any], str | None]
 IdempotencyNamespace: TypeAlias = str | IdempotencyNamespaceResolver
 """Optional run/workflow/tenant scope woven into Cycles idempotency keys.
+
 Static string or a callable receiving the request (tool gate) or state
-(fan-out gate). When supplied, keys take the shape
-``{prefix}-{namespace}-{tool_call_id}``; without it, the v0.1.2 shape
+(fan-out gate). The callable may return ``None`` to disable namespacing
+for that particular call (per-call opt-out — useful when some calls
+should be globally scoped while others are run-scoped).
+
+When a non-empty namespace is in effect, keys take the shape
+``{prefix}-{namespace}-{tool_call_id}``; otherwise the v0.1.2 shape
 ``{prefix}-{tool_call_id}`` is preserved (back-compat)."""

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "langchain-runcycles"
-version = "0.1.3"
+version = "0.1.4"
 description = "LangChain agent middleware for Cycles — pre-tool-call authorization, fan-out caps, and per-tenant budget enforcement for Python agents using create_agent."
 readme = "README.md"
 license = "Apache-2.0"