ctxmesh 0.1.0b1__tar.gz

ctxmesh-0.1.0b1/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: ctxmesh
+Version: 0.1.0b1
+Summary: Typed Python SDK over the ctxmesh launcher localhost plane (memory / tools / feedback).
+Author: ctxmesh
+License: Apache-2.0
+Keywords: ctxmesh,ctxmesh,llm,agents,observability
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: Apache Software License
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: opentelemetry-sdk~=1.27
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc~=1.27
+Requires-Dist: openinference-semantic-conventions~=0.1.30
+Requires-Dist: jsonschema<5,>=4.20
+Provides-Extra: dev
+Requires-Dist: ruff==0.6.9; extra == "dev"
+Requires-Dist: pytest==8.3.3; extra == "dev"
+
+# ctxmesh — ctxmesh Python SDK
+
+Optional, typed sugar over the launcher's language-agnostic localhost platform
+plane (ADR 0002). Bundled into `base-python`, importable as `ctxmesh`. Never a
+hard dependency: every capability it exposes is *also* a raw launcher endpoint.
+
+- **Distribution name:** `ctxmesh` · **import name:** `ctxmesh`
+- **Python:** 3.9+ · **runtime deps:** the plane clients are pure stdlib; the
+  model + step-tracing helpers add a minimal OTLP/gRPC exporter +
+  OpenInference semantic-convention constants, **pinned to the exact versions
+  `images/base-python` already bundles** (opentelemetry `1.27.0`,
+  openinference-semantic-conventions `0.1.30`) — so `import ctxmesh` adds **zero
+  net footprint** to the base image.
+
+## Surface
+
+```python
+from ctxmesh import agent
+
+client = agent.from_env()          # in-pod: reads the launcher-injected env
+
+# memory (:2998, M5)
+client.memory.get()                       # full context (list)
+client.memory.put([{"role": "user", "content": "hi"}])
+client.memory.append({"role": "assistant", "content": "hey"})
+client.memory.search("hi")
+# bind a conversationId for the turn (the agent reads it from the request):
+turn = client.with_conversation("conv-42")
+turn.memory.get()
+
+# tools / discovery (:2999, M4)
+client.tools.list()                       # live manifest as Tool objects
+client.tools.call("word-count", text="a b c")   # MCP tools/call
+
+# feedback (:2995, M9)
+client.feedback.score("trace-abc", "thumbs-up", 1, comment="great")
+
+# model gateway ($MODEL_GATEWAY_URL, M2/M8) — emits an OpenInference LLM span
+resp = client.model.chat("gpt-4o-mini", [{"role": "user", "content": "q"}])
+resp.text        # the completion; resp.usage → token counts; resp.raw → full body
+```
+
+`agent.from_env()` **fails fast** (`NotInPodError`) when no launcher env is
+present — it never silently no-ops. For tests / offline use, build a
+`PlaneConfig` explicitly (`PlaneConfig.for_test(...)`) and call
+`agent.from_config(config)` against a fake localhost plane.
+
+## Step-tracing helpers (custom loops)
+
+A framework agent (LangChain/OpenAI/Anthropic) gets its `step → tool → model`
+trace tree SDK-free via base-image OpenInference auto-instrumentation. A **custom,
+no-framework loop** has no inferable step boundaries, so it emits the tree
+explicitly with `client.trace.*` — producing an OpenInference tree
+**structurally identical** to a framework one (same `CHAIN`/`TOOL`/`LLM` span
+kinds + attribute keys), exported over the same OTLP/gRPC path to the collector
+(`:4317`) → Langfuse.
+
+```python
+# Bind the inbound /invoke request so the WHOLE tree roots under the launcher's
+# `agent.invoke` span (the launcher injected a W3C `traceparent`). Without this
+# bind the SDK spans would start a detached trace.
+with client.trace.request_context(request.headers):
+    with client.trace.step("plan") as step:            # CHAIN span
+        step.set_input(user_prompt)
+        plan = client.model.chat(model, messages)       # nested LLM span (auto)
+        with client.trace.tool("web_search", args) as t:  # TOOL span (child of step)
+            t.set_output(client.tools.call("web_search", **args))
+        step.set_output(plan.text)
+```
+
+`client.trace.loop(name, headers=request.headers)` is a convenience that binds
+the request context **and** opens the `AGENT` loop-root span in one `with`.
+
+**Rooting under `agent.invoke` is the invariant** — the SDK extracts the W3C
+`traceparent` the launcher proxy injects on every `/invoke` and makes the step
+spans children of the launcher's `agent.invoke` root (same trace id, correct
+parent span id), not a detached trace.
+
+**Offline / telemetry resilience:** when `OTEL_EXPORTER_OTLP_ENDPOINT` is unset
+(offline/tests) the trace client runs in **no-op export** mode — spans are still
+created (so nesting/propagation still works and can be asserted) but exported
+nowhere. Export/setup failures degrade to no-op and **never crash the loop** (a
+telemetry blip is not an error); this is deliberately distinct from the plane
+clients, which *surface* endpoint errors (a rejected memory write is a real
+error).
+
+## Serving an agent (`ctxmesh.serve`)
+
+You don't hand-roll the HTTP server, the `/invoke` body/​envelope, the
+`/healthz`/`/readyz` probes, the `$AGENT_PORT` the launcher proxies to, the
+`traceparent` capture, or the SSE token stream — `ctxmesh.serve` encodes the whole
+runtime contract, and it binds `request_scope` for you (so a custom loop keeps the
+invoking user's run capability instead of silently downgrading to org/public creds):
+
+```python
+import ctxmesh
+
+def handle(req: ctxmesh.InvokeRequest) -> str:
+    # req.client is scoped to the caller (capability + granted approvals bound) and
+    # conversation-aware (req.conversation_id); req.headers roots the trace.
+    with req.client.trace.loop("my-agent", headers=req.headers):
+        answer = req.client.model.chat(
+            "gpt-4o-mini", [{"role": "user", "content": req.input}]
+        )
+    return answer.text          # or return a ctxmesh.ManagedResult for steps/tools/approval
+
+ctxmesh.serve(handle)           # blocks; serves /invoke + health on $AGENT_PORT
+```
+
+- **Streaming** is transparent: call `req.emit_token(delta)` as your loop produces
+  content — it emits an SSE `token` frame when the caller sent
+  `Accept: text/event-stream`, and is a no-op otherwise (same handler, both modes).
+- **The stock managed agent** is just `ctxmesh.serve()` with **no** handler — it runs
+  the config-driven tool-calling loop (`run_managed_loop`) with `ManagedConfig.from_env()`.
+  That is exactly the managed-agent image's entrypoint.
+- `serve(handler, *, client=…, agent_name=…, port=…)` overrides the env defaults
+  (`agent.from_env()` / `$AGENT_NAME` / `$AGENT_PORT`) — handy for local runs and tests.
+
+`examples/sdk-custom-agent` shows the same loop with the HTTP handler written out by
+hand — the "under the hood" reference for what `serve` collapses into one call.
+
+## Dev
+
+The toolchain (ruff + pytest, pinned) is wired into the engine `Makefile`:
+
+```
+make py-venv     # create .venv-sdk with pinned ruff+pytest (from host python3)
+make lint        # go lint + ruff (sdk/python)
+make test        # go unit tests + pytest (sdk/python)
+```
+
+Pins live in `requirements-dev.txt` (mirrored in the `dev` extra of
+`pyproject.toml`).

ctxmesh-0.1.0b1/README.md

@@ -0,0 +1,133 @@
+# ctxmesh — ctxmesh Python SDK
+
+Optional, typed sugar over the launcher's language-agnostic localhost platform
+plane (ADR 0002). Bundled into `base-python`, importable as `ctxmesh`. Never a
+hard dependency: every capability it exposes is *also* a raw launcher endpoint.
+
+- **Distribution name:** `ctxmesh` · **import name:** `ctxmesh`
+- **Python:** 3.9+ · **runtime deps:** the plane clients are pure stdlib; the
+  model + step-tracing helpers add a minimal OTLP/gRPC exporter +
+  OpenInference semantic-convention constants, **pinned to the exact versions
+  `images/base-python` already bundles** (opentelemetry `1.27.0`,
+  openinference-semantic-conventions `0.1.30`) — so `import ctxmesh` adds **zero
+  net footprint** to the base image.
+
+## Surface
+
+```python
+from ctxmesh import agent
+
+client = agent.from_env()          # in-pod: reads the launcher-injected env
+
+# memory (:2998, M5)
+client.memory.get()                       # full context (list)
+client.memory.put([{"role": "user", "content": "hi"}])
+client.memory.append({"role": "assistant", "content": "hey"})
+client.memory.search("hi")
+# bind a conversationId for the turn (the agent reads it from the request):
+turn = client.with_conversation("conv-42")
+turn.memory.get()
+
+# tools / discovery (:2999, M4)
+client.tools.list()                       # live manifest as Tool objects
+client.tools.call("word-count", text="a b c")   # MCP tools/call
+
+# feedback (:2995, M9)
+client.feedback.score("trace-abc", "thumbs-up", 1, comment="great")
+
+# model gateway ($MODEL_GATEWAY_URL, M2/M8) — emits an OpenInference LLM span
+resp = client.model.chat("gpt-4o-mini", [{"role": "user", "content": "q"}])
+resp.text        # the completion; resp.usage → token counts; resp.raw → full body
+```
+
+`agent.from_env()` **fails fast** (`NotInPodError`) when no launcher env is
+present — it never silently no-ops. For tests / offline use, build a
+`PlaneConfig` explicitly (`PlaneConfig.for_test(...)`) and call
+`agent.from_config(config)` against a fake localhost plane.
+
+## Step-tracing helpers (custom loops)
+
+A framework agent (LangChain/OpenAI/Anthropic) gets its `step → tool → model`
+trace tree SDK-free via base-image OpenInference auto-instrumentation. A **custom,
+no-framework loop** has no inferable step boundaries, so it emits the tree
+explicitly with `client.trace.*` — producing an OpenInference tree
+**structurally identical** to a framework one (same `CHAIN`/`TOOL`/`LLM` span
+kinds + attribute keys), exported over the same OTLP/gRPC path to the collector
+(`:4317`) → Langfuse.
+
+```python
+# Bind the inbound /invoke request so the WHOLE tree roots under the launcher's
+# `agent.invoke` span (the launcher injected a W3C `traceparent`). Without this
+# bind the SDK spans would start a detached trace.
+with client.trace.request_context(request.headers):
+    with client.trace.step("plan") as step:            # CHAIN span
+        step.set_input(user_prompt)
+        plan = client.model.chat(model, messages)       # nested LLM span (auto)
+        with client.trace.tool("web_search", args) as t:  # TOOL span (child of step)
+            t.set_output(client.tools.call("web_search", **args))
+        step.set_output(plan.text)
+```
+
+`client.trace.loop(name, headers=request.headers)` is a convenience that binds
+the request context **and** opens the `AGENT` loop-root span in one `with`.
+
+**Rooting under `agent.invoke` is the invariant** — the SDK extracts the W3C
+`traceparent` the launcher proxy injects on every `/invoke` and makes the step
+spans children of the launcher's `agent.invoke` root (same trace id, correct
+parent span id), not a detached trace.
+
+**Offline / telemetry resilience:** when `OTEL_EXPORTER_OTLP_ENDPOINT` is unset
+(offline/tests) the trace client runs in **no-op export** mode — spans are still
+created (so nesting/propagation still works and can be asserted) but exported
+nowhere. Export/setup failures degrade to no-op and **never crash the loop** (a
+telemetry blip is not an error); this is deliberately distinct from the plane
+clients, which *surface* endpoint errors (a rejected memory write is a real
+error).
+
+## Serving an agent (`ctxmesh.serve`)
+
+You don't hand-roll the HTTP server, the `/invoke` body/​envelope, the
+`/healthz`/`/readyz` probes, the `$AGENT_PORT` the launcher proxies to, the
+`traceparent` capture, or the SSE token stream — `ctxmesh.serve` encodes the whole
+runtime contract, and it binds `request_scope` for you (so a custom loop keeps the
+invoking user's run capability instead of silently downgrading to org/public creds):
+
+```python
+import ctxmesh
+
+def handle(req: ctxmesh.InvokeRequest) -> str:
+    # req.client is scoped to the caller (capability + granted approvals bound) and
+    # conversation-aware (req.conversation_id); req.headers roots the trace.
+    with req.client.trace.loop("my-agent", headers=req.headers):
+        answer = req.client.model.chat(
+            "gpt-4o-mini", [{"role": "user", "content": req.input}]
+        )
+    return answer.text          # or return a ctxmesh.ManagedResult for steps/tools/approval
+
+ctxmesh.serve(handle)           # blocks; serves /invoke + health on $AGENT_PORT
+```
+
+- **Streaming** is transparent: call `req.emit_token(delta)` as your loop produces
+  content — it emits an SSE `token` frame when the caller sent
+  `Accept: text/event-stream`, and is a no-op otherwise (same handler, both modes).
+- **The stock managed agent** is just `ctxmesh.serve()` with **no** handler — it runs
+  the config-driven tool-calling loop (`run_managed_loop`) with `ManagedConfig.from_env()`.
+  That is exactly the managed-agent image's entrypoint.
+- `serve(handler, *, client=…, agent_name=…, port=…)` overrides the env defaults
+  (`agent.from_env()` / `$AGENT_NAME` / `$AGENT_PORT`) — handy for local runs and tests.
+
+`examples/sdk-custom-agent` shows the same loop with the HTTP handler written out by
+hand — the "under the hood" reference for what `serve` collapses into one call.
+
+## Dev
+
+The toolchain (ruff + pytest, pinned) is wired into the engine `Makefile`:
+
+```
+make py-venv     # create .venv-sdk with pinned ruff+pytest (from host python3)
+make lint        # go lint + ruff (sdk/python)
+make test        # go unit tests + pytest (sdk/python)
+```
+
+Pins live in `requirements-dev.txt` (mirrored in the `dev` extra of
+`pyproject.toml`).

ctxmesh-0.1.0b1/pyproject.toml

@@ -0,0 +1,106 @@
+# ctxmesh — the ctxmesh Python SDK.
+#
+# Distribution name: "ctxmesh"; import name: "ctxmesh". Both match so
+# `pip install ctxmesh` gives `import ctxmesh` with zero surprises (spec
+# "Packaging & base-image bundling").
+#
+# Typed sugar over the launcher's language-agnostic localhost platform plane
+# (ADR 0002): memory (:2998), tools/discovery (:2999), feedback (:2995), the
+# model gateway ($MODEL_GATEWAY_URL), and the step-tracing helpers (OTLP :4317).
+# The SDK is NEVER a hard dependency. The plane clients are pure stdlib (urllib);
+# the m10.3 model + trace helpers add a MINIMAL OTLP/gRPC exporter + OpenInference
+# semantic-convention constants — pinned to the EXACT versions already bundled in
+# images/base-python (opentelemetry 1.27.0 + openinference-semantic-conventions
+# 0.1.30), so the SDK adds ZERO net footprint to base-python and stays 3.9-compatible.
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ctxmesh"
+version = "0.1.0-beta.1"
+description = "Typed Python SDK over the ctxmesh launcher localhost plane (memory / tools / feedback)."
+readme = "README.md"
+# 3.9 is the floor because the agent base image still ships it; the classifiers below
+# state the range actually supported. A library that claims only 3.9 reads as abandoned to
+# anyone running a current interpreter, whether or not it works there.
+requires-python = ">=3.9"
+license = { text = "Apache-2.0" }
+authors = [{ name = "ctxmesh" }]
+keywords = ["ctxmesh", "ctxmesh", "llm", "agents", "observability"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "License :: OSI Approved :: Apache Software License",
+]
+# Runtime deps for the m10.3 model + step-tracing helpers. Pinned to the exact
+# versions images/base-python already bundles, so `import ctxmesh` adds nothing
+# net to the base image (the plane clients themselves remain pure stdlib):
+#   * opentelemetry-sdk + the OTLP/gRPC exporter — export step spans to the
+#     collector (:4317) over the SAME path as auto-instrumentation → Langfuse.
+#   * openinference-semantic-conventions — the CHAIN/TOOL/LLM span kinds + attr
+#     keys, so a custom-loop tree is byte-for-byte a framework tree.
+# All three install cleanly and run on the 3.9 target (host python 3.9.6).
+# RANGES, not pins. This is a LIBRARY: it is installed alongside the user's own code, and
+# an exact pin on opentelemetry-sdk makes ctxmesh uninstallable next to any application that
+# already has a different OTel — which is most applications that would want us. An
+# application pins; a library states the range it works across and lets the resolver decide.
+#
+# Compatible-release (~=) on the OTel packages: they move together and have broken minor to
+# minor before, so the ceiling is deliberate rather than optimistic. jsonschema has a stable
+# 4.x API and gets the wider range.
+#
+# The images that BUNDLE this SDK pin exact versions in their own requirements.txt — that is
+# where pinning belongs, because an image IS an application.
+dependencies = [
+    "opentelemetry-sdk~=1.27",
+    "opentelemetry-exporter-otlp-proto-grpc~=1.27",
+    "openinference-semantic-conventions~=0.1.30",
+    "jsonschema>=4.20,<5",
+]
+
+[project.optional-dependencies]
+# Pinned dev toolchain — reproducible on a clean host / CI (no host-global
+# installs). Bootstrapped into a venv by `make py-venv` (see the repo Makefile).
+# ruff 0.6.9 and pytest 8.3.x both support Python 3.9 (the host is 3.9.6).
+dev = [
+    "ruff==0.6.9",
+    "pytest==8.3.3",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+ctxmesh = ["py.typed"]
+
+# ── ruff ──────────────────────────────────────────────────────────────────────
+[tool.ruff]
+line-length = 100
+target-version = "py39"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+# A pragmatic-but-strict set: pycodestyle/pyflakes (E,F), bugbear (B),
+# isort (I), comprehensions (C4), simplify (SIM). pyupgrade (UP) is deliberately
+# omitted: the SDK targets 3.9 and uses explicit typing.Dict/List/Optional for
+# clarity (all under `from __future__ import annotations`), which UP would
+# rewrite to PEP 585/604 forms — a style change, not a correctness one.
+select = ["E", "F", "B", "I", "C4", "SIM"]
+
+[tool.ruff.lint.per-file-ignores]
+# Tests may use asserts and longer fixture bodies freely. SIM117 (combine nested
+# `with`) is ignored in tests because the step-tracing tests deliberately NEST
+# `with` blocks (request_context → step → tool/llm) to express — and assert — the
+# span-tree topology; flattening them into one `with` would obscure the very
+# parent/child nesting under test.
+"tests/*" = ["B011", "SIM117"]
+
+# ── pytest ────────────────────────────────────────────────────────────────────
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"

ctxmesh-0.1.0b1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ctxmesh-0.1.0b1/src/ctxmesh/__init__.py

@@ -0,0 +1,105 @@
+"""ctxmesh — the ctxmesh Python SDK.
+
+Typed, optional sugar over the launcher's language-agnostic localhost platform
+plane (ADR 0002). Every capability the SDK exposes is *also* a raw launcher
+endpoint; the SDK never adds a capability the plane does not have — it only
+removes the raw-HTTP boilerplate and applies the run context.
+
+Surface:
+
+    from ctxmesh import agent
+
+    client = agent.from_env()                 # reads the launcher-injected env
+
+    client.memory.get(); client.memory.put(entries)
+    client.memory.append(entry); client.memory.search(query)
+
+    client.tools.list()                       # live discovery manifest (:2999)
+    client.tools.call(name, **args)           # invoke a bound MCP tool
+
+    client.feedback.score(trace_id, name, value, comment=None)   # :2995
+
+    client.model.chat(model, messages, **opts)  # $MODEL_GATEWAY_URL; emits LLM span
+
+    # knowledge-base retrieval (M68, ADR 0061 Fork 3):
+    client.knowledge.search("what is X?")    # POST :2998/knowledge/search
+
+    # multimodal content-parts helpers (M68, ADR 0061 Fork 5):
+    from ctxmesh import text_part, image_url, content
+    msgs = [{"role": "user", "content": content(
+        text_part("What is in this image?"),
+        image_url("https://example.com/photo.jpg"),
+    )}]
+
+    # step-tracing helpers for a custom loop (the M10 core). Bind the inbound
+    # request so the tree roots under the launcher's agent.invoke span:
+    with client.trace.request_context(request.headers):
+        with client.trace.step("plan") as step:            # CHAIN span
+            plan = client.model.chat(model, messages)       # nested LLM span
+            with client.trace.tool("search", args) as t:    # TOOL span (child)
+                t.set_output(client.tools.call("search", **args))
+            step.set_output(plan)
+"""
+
+from ctxmesh import agent
+from ctxmesh._approval import pause_for_approval
+from ctxmesh._multimodal import content, image_url, text_part
+from ctxmesh.client import Client
+from ctxmesh.config import PlaneConfig
+from ctxmesh.errors import (
+    ApprovalRequiredError,
+    ConfigError,
+    CtxmeshError,
+    EndpointError,
+    GuardrailBlockedError,
+    NotInPodError,
+)
+from ctxmesh.knowledge import KnowledgeClient
+from ctxmesh.managed import (
+    DEFAULT_MAX_STEPS,
+    ManagedConfig,
+    ManagedResult,
+    mint_conversation_id,
+    run_managed_loop,
+)
+from ctxmesh.model import ChatResponse, ModelClient
+from ctxmesh.runs import Run, RunEvent, RunsClient
+from ctxmesh.serve import InvokeRequest, serve
+from ctxmesh.skills import Skill
+from ctxmesh.trace import SpanHandle, TraceClient
+
+__all__ = [
+    "agent",
+    "Client",
+    "PlaneConfig",
+    "CtxmeshError",
+    "ConfigError",
+    "NotInPodError",
+    "EndpointError",
+    "GuardrailBlockedError",
+    "ModelClient",
+    "ChatResponse",
+    "Skill",
+    "TraceClient",
+    "SpanHandle",
+    "run_managed_loop",
+    "mint_conversation_id",
+    "ManagedConfig",
+    "ManagedResult",
+    "DEFAULT_MAX_STEPS",
+    "pause_for_approval",
+    "ApprovalRequiredError",
+    "RunsClient",
+    "Run",
+    "RunEvent",
+    "serve",
+    "InvokeRequest",
+    # M68: knowledge-base retrieval
+    "KnowledgeClient",
+    # M68: multimodal content-parts helpers (ADR 0061 Fork 5)
+    "text_part",
+    "image_url",
+    "content",
+]
+
+__version__ = "0.1.0-beta.1"

ctxmesh-0.1.0b1/src/ctxmesh/_approval.py

@@ -0,0 +1,123 @@
+"""Request-scoped human-in-the-loop approvals (ADR 0034 §HITL, m32.4).
+
+A run can gate a sensitive step on human approval. The agent calls
+:func:`pause_for_approval(key, summary)`; if ``key`` is in the set of approvals GRANTED for this
+run, the call returns and the step proceeds — otherwise it raises
+:class:`ctxmesh.errors.ApprovalRequiredError`, which the managed loop turns into a
+``requires_action`` (approval) outcome. When the approver resolves it, the run is re-invoked with
+the approved key in the granted set, so the same ``pause_for_approval`` call now proceeds.
+
+The granted set is held in a :class:`contextvars.ContextVar` (PEP 567), **not** a module global —
+the same no-cross-bleed guarantee as the run capability (:mod:`ctxmesh._capability`): each inbound
+request runs in its own execution context, so concurrent runs never observe each other's approvals.
+The only way to bind approvals is :func:`approval_scope`, which RESETS the ContextVar on exit; there
+is no process-wide setter.
+"""
+
+from contextlib import contextmanager
+from contextvars import ContextVar
+from typing import FrozenSet, Iterable, Iterator, Mapping, Optional
+
+from ctxmesh.errors import ApprovalRequiredError
+
+# The approvals granted for the CURRENT run (a set of step keys). Empty ⇒ nothing approved yet, so
+# every pause_for_approval raises.
+_granted_approvals: "ContextVar[FrozenSet[str]]" = ContextVar(
+    "ctxmesh_granted_approvals", default=frozenset()
+)
+
+# ── The stateless approval VOUCHER (ADR 0074 §3, m82.4) ──────────────────────────────────────────
+#
+# require-approval is enforced at the egress WIRE, not just here in the loop: a tool call for a
+# require-approval tool is FORWARDED by the sidecar only when the request carries a valid, signed
+# X-Ctxmesh-Approval voucher (a short-lived token bound to {runId, toolName} the BFF minted on a
+# human's approval). The managed loop's pause_for_approval is now the PRESENTATION UX — necessary
+# but no longer sufficient — and the SDK must RELAY the voucher on the tool-call retry so the
+# sidecar forwards it.
+#
+# The voucher arrives on the RESUMED run's inbound /invoke headers (the BFF stamped
+# X-Ctxmesh-Approval after approval-grant). We hold it request-scoped in a ContextVar and relay it
+# on every outbound tool call — the EXACT sibling of the run-capability relay
+# (:mod:`ctxmesh._capability`) and the record toggle (:mod:`ctxmesh._record`): a launcher-internal
+# header the SDK forwards but never originates. The sidecar's {tool, run} binding means a voucher
+# only unlocks the ONE approved tool; relaying it on every call is safe (a mismatched tool 403s).
+
+# The header the BFF stamps on a resumed run and the SDK relays on each tool-call egress — must
+# match runcap.ApprovalHeaderName on the Go side (internal/runcap) + hdrApproval (internal/bff).
+# Case-insensitive on the wire.
+APPROVAL_HEADER = "X-Ctxmesh-Approval"
+
+# The request-scoped approval voucher. default=None ⇒ a run with no granted require-approval tool:
+# the tool client relays no voucher and a require-approval tool gets the sidecar's 403.
+_approval_voucher: "ContextVar[Optional[str]]" = ContextVar(
+    "ctxmesh_approval_voucher", default=None
+)
+
+
+@contextmanager
+def approval_scope(approvals: Optional[Iterable[str]]) -> Iterator[None]:
+    """Bind the set of GRANTED approval keys for the duration of the block, then reset it.
+
+    Request-scoped: set on entry, RESET on exit, so a reused worker thread can never leak a prior
+    run's approvals. ``None`` binds the empty set (nothing approved).
+    """
+    token = _granted_approvals.set(frozenset(approvals or ()))
+    try:
+        yield
+    finally:
+        _granted_approvals.reset(token)
+
+
+def pause_for_approval(key: str, summary: str) -> None:
+    """Gate the current step on human approval (human-in-the-loop, m32.4).
+
+    If ``key`` has been approved for this run (the approver resolved a prior pause), this returns
+    and the step proceeds. Otherwise it raises :class:`~ctxmesh.errors.ApprovalRequiredError`, which
+    the managed loop surfaces as a ``requires_action`` (approval) outcome carrying ``key`` +
+    ``summary`` (a human-readable description of what needs approving). The run resumes on approval.
+
+    ``key`` is a STABLE identifier for this decision point (e.g. ``"send-email"``) — the same key
+    must be used across the initial call and the resumed re-invoke so the approval matches.
+    """
+    if key in _granted_approvals.get():
+        return
+    raise ApprovalRequiredError(
+        f"approval required for {key!r}: {summary}", key=key, summary=summary
+    )
+
+
+def current_approval_voucher() -> Optional[str]:
+    """Return the approval voucher bound to the CURRENT request context, or ``None``.
+
+    The tool client relays this on each outbound MCP tool call (the egress sidecar verifies it for a
+    require-approval tool). ``None`` outside a resumed/approved run — the sidecar then returns its
+    403 ``approval_required`` for a require-approval tool.
+    """
+    return _approval_voucher.get()
+
+
+def _extract_voucher(headers: Optional[Mapping[str, str]]) -> Optional[str]:
+    """Pull the approval voucher out of inbound *headers* case-insensitively (HTTP header case is
+    not guaranteed), returning ``None`` when absent or blank."""
+    if not headers:
+        return None
+    target = APPROVAL_HEADER.lower()
+    for key, value in headers.items():
+        if key.lower() == target:
+            stripped = (value or "").strip()
+            return stripped or None
+    return None
+
+
+@contextmanager
+def voucher_scope(headers: Optional[Mapping[str, str]]) -> Iterator[None]:
+    """Bind the approval voucher extracted from inbound *headers* for the duration of the block,
+    then reset it.
+
+    Request-scoped (set on entry, RESET on exit) so a reused worker thread can never leak a prior
+    request's voucher. A missing/blank header binds ``None`` (no granted require-approval tool)."""
+    token = _approval_voucher.set(_extract_voucher(headers))
+    try:
+        yield
+    finally:
+        _approval_voucher.reset(token)