ctxmesh 0.1.0b1__py3-none-any.whl

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/_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)

ctxmesh/_capability.py

@@ -0,0 +1,64 @@
+"""Request-scoped propagation of the run capability (ADR 0030 §3).
+
+The run capability is the unforgeable token the BFF mints at ``/invoke`` identifying the
+INVOKING user (its ``sub`` is that user's hashed identity). It arrives on the inbound
+request headers, and the SDK must relay it on every outbound MCP tool call so the egress
+sidecar can resolve *that* user's credential — never another user's.
+
+It is held in a :class:`contextvars.ContextVar` (PEP 567), **not** a module global. Each
+inbound request runs in its own execution context — a fresh thread under the entrypoint's
+``ThreadingHTTPServer``, or an ``asyncio`` task — so concurrent requests for different
+users never observe each other's capability. There is no cross-user bleed by construction.
+
+There is deliberately **no setter that mutates a process-wide value**: the only way to bind
+a capability is :func:`capability_scope`, which is request-scoped and RESETS the ContextVar
+on exit. :func:`current_capability` only ever reads the current context. This structural
+absence of a global accessor is the no-bleed guarantee (a compromised/injected agent cannot
+reach out and set another request's capability).
+"""
+
+from contextlib import contextmanager
+from contextvars import ContextVar
+from typing import Iterator, Mapping, Optional
+
+# The header the BFF mints into and the launcher passes through — MUST match
+# runcap.HeaderName on the Go side (internal/runcap). Case-insensitive on the wire.
+CAPABILITY_HEADER = "X-Ctxmesh-Run-Capability"
+
+# The request-scoped capability. default=None ⇒ a run with no capability (unattended /
+# minting-disabled) resolves as org/public only, never another user's grant.
+_run_capability: "ContextVar[Optional[str]]" = ContextVar("ctxmesh_run_capability", default=None)
+
+
+def current_capability() -> Optional[str]:
+    """Return the run capability bound to the CURRENT request context, or ``None``."""
+    return _run_capability.get()
+
+
+def _extract(headers: Optional[Mapping[str, str]]) -> Optional[str]:
+    """Pull the capability out of inbound *headers* case-insensitively (HTTP header case
+    is not guaranteed), returning ``None`` when absent or blank."""
+    if not headers:
+        return None
+    target = CAPABILITY_HEADER.lower()
+    for key, value in headers.items():
+        if key.lower() == target:
+            stripped = (value or "").strip()
+            return stripped or None
+    return None
+
+
+@contextmanager
+def capability_scope(headers: Optional[Mapping[str, str]]) -> Iterator[None]:
+    """Bind the run capability extracted from inbound *headers* for the duration of the
+    block, then reset it.
+
+    Request-scoped: the ContextVar is set on entry and RESET on exit, so even if a worker
+    thread is later reused for another request it can never leak a prior request's
+    capability. A missing/blank header binds ``None`` (an unattended run).
+    """
+    token = _run_capability.set(_extract(headers))
+    try:
+        yield
+    finally:
+        _run_capability.reset(token)

ctxmesh/_checkpoint.py

@@ -0,0 +1,117 @@
+"""L7 supervisor-loop checkpoint (ADR 0091) — the SDK side of the durable delegate suspend/resume.
+
+A depth-0 durable supervisor that delegates and suspends serializes its managed-loop state into an
+opaque **payload** string (built here) and returns it in the ``delegate_waiting`` marker. The BFF
+wraps that payload in a hashed **envelope** (``internal/run/checkpoint.go``) and stores it in the
+run's cursor. On resume the worker injects the ENVELOPE back into the invoke body as
+``body["checkpoint"]``; this module re-verifies it (kind / version / hash — defense in depth; the
+worker already verified before injecting) and extracts the payload's fields.
+
+The payload carries ONLY loop state — never authorization (consent/approval/OBO), which is
+re-derived server-side on resume (ADR 0091 fork 3). Verification is fail-safe: a corrupt /
+version-skewed envelope or payload yields ``None`` and the caller runs fresh from the request input.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+from typing import Any, Dict, Optional
+
+_log = logging.getLogger("ctxmesh.checkpoint")
+
+#: The envelope contract shared with the Go store (internal/run/checkpoint.go). Kept in lockstep: a
+#: bump must roll the SDKs first (a resume rejects an unknown version → fail-safe full re-invoke).
+_ENVELOPE_KIND = "supervisor-loop"
+_ENVELOPE_VERSION = 1
+
+#: The payload's OWN schema version (independent of the envelope — lets the SDK evolve the
+#: loop-state
+#: shape without touching the store's envelope contract). A resume rejects an unknown payload
+#: version.
+PAYLOAD_VERSION = 1
+
+#: Cap on the serialized payload size. The ``delegate_waiting`` marker rides the /invoke response,
+#: which the BFF reads through a 4 MiB LimitReader (internal/bff/invoke.go) — an oversized marker is
+#: silently TRUNCATED, so the loop measures the payload and falls back to blocking dispatch above
+#: this
+#: threshold (a loud, graceful M64 degradation) rather than emitting a truncated, unparseable
+#: marker.
+CHECKPOINT_MAX_BYTES = 1_500_000
+
+
+def build_payload(
+    *,
+    messages: list,
+    step: int,
+    pending: list,
+    tools_called: list,
+    consent_required: list,
+    spotlight_token: str,
+    model_index: int,
+    tool_index: int,
+) -> str:
+    """Serialize the resumable managed-loop state into the opaque payload string.
+
+    Only the fields that cannot be reconstructed on resume are persisted; everything re-derivable
+    (tool manifest, history/memory/knowledge, conversation/message ids, approvals, the per-run
+    breaker) is intentionally omitted and rebuilt from headers/body/store on resume.
+    """
+    payload: Dict[str, Any] = {
+        "v": PAYLOAD_VERSION,
+        "messages": messages,
+        "step": step,
+        "pending": pending,
+        "tools_called": tools_called,
+        "consent_required": consent_required,
+        "spotlight_token": spotlight_token,
+        "model_index": model_index,
+        "tool_index": tool_index,
+    }
+    return json.dumps(payload, separators=(",", ":"))
+
+
+def verify_and_extract(envelope: Any) -> Optional[Dict[str, Any]]:
+    """Verify a checkpoint ENVELOPE and return its payload fields, or ``None`` (fail-safe).
+
+    *envelope* is ``body["checkpoint"]`` as parsed from the invoke body — the worker injects the Go
+    envelope as a raw JSON object, so it normally arrives as a ``dict`` (a JSON string is tolerated
+    too). ``None`` is returned — never raised — for any envelope that is absent, malformed, of an
+    unknown kind/version, whose payload hash does not match, or whose payload is an unknown version;
+    the caller then runs the turn fresh from the request input (the SDK mirror of the worker's
+    full-re-invoke fail-safe).
+    """
+    if envelope is None:
+        return None
+    env = envelope
+    if isinstance(env, (str, bytes)):
+        try:
+            env = json.loads(env)
+        except (json.JSONDecodeError, ValueError):
+            _log.warning("L7 checkpoint: envelope is not valid JSON — running fresh (fail-safe)")
+            return None
+    if not isinstance(env, dict):
+        return None
+    if env.get("kind") != _ENVELOPE_KIND or env.get("version") != _ENVELOPE_VERSION:
+        _log.warning(
+            "L7 checkpoint: unrecognized envelope kind/version — running fresh (fail-safe)"
+        )
+        return None
+    payload_str = env.get("payload")
+    if not isinstance(payload_str, str):
+        return None
+    digest = hashlib.sha256(payload_str.encode()).hexdigest()
+    if digest != env.get("sha256"):
+        _log.warning(
+            "L7 checkpoint: payload hash mismatch (corruption) — running fresh (fail-safe)"
+        )
+        return None
+    try:
+        fields = json.loads(payload_str)
+    except (json.JSONDecodeError, ValueError):
+        return None
+    if not isinstance(fields, dict) or fields.get("v") != PAYLOAD_VERSION:
+        _log.warning("L7 checkpoint: unknown payload version — running fresh (fail-safe)")
+        return None
+    return fields

ctxmesh/_http.py

@@ -0,0 +1,229 @@
+"""Minimal stdlib HTTP helper shared by the plane clients.
+
+The m10.2 clients depend on nothing but the standard library (``urllib``) so the
+SDK stays lean enough to bundle into base-python and runs on the 3.9 target.
+This module centralises the request/response plumbing and — critically — the
+error translation: a non-2xx response or a transport failure becomes an
+:class:`~ctxmesh.errors.EndpointError` carrying the status, never a swallowed
+error (spec: "surface the launcher endpoint's error rather than swallowing").
+
+307/308 redirect handling
+-------------------------
+``urllib`` does not re-POST a body on a 307 response — it raises
+``HTTPError 307``. Our MCP endpoint is registered at ``/mcp/`` (trailing slash)
+and FastMCP/Starlette issues a 307 for ``POST /mcp`` (without the slash).  The
+:func:`request` helper therefore catches 307/308 explicitly and re-issues the
+**same method, body, and headers** to the ``Location`` URL.  Two guards apply:
+
+* **Same-origin only** — the redirect target must share scheme, host, and port
+  with the original URL.  Re-POSTing a body to a different host is a security
+  boundary violation; we raise :class:`~ctxmesh.errors.EndpointError` instead.
+* **Bounded** — at most ``_MAX_REDIRECTS`` consecutive 307/308 hops before we
+  raise, preventing infinite redirect loops.
+
+301/302/303 are left to urllib's default handling (it converts the method to GET,
+which is correct for those status codes and not expected on the localhost plane).
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, Iterator, Optional, Tuple
+
+from ctxmesh.errors import EndpointError
+
+#: Default per-op timeout (seconds). Matches the launcher's own 2s Valkey bound
+#: for the memory path; callers may override for slower endpoints.
+DEFAULT_TIMEOUT = 5.0
+
+#: SSE read timeout (seconds, FUNC-7). A long-lived event stream (runs.stream) may idle
+#: between events for a slow model turn or a run parked at requires_action — far longer
+#: than DEFAULT_TIMEOUT. The server heartbeats well within this window, so a live-but-idle
+#: stream never trips it; a genuinely dead connection still errors after it (not never).
+STREAM_READ_TIMEOUT = 120.0
+
+#: Maximum number of 307/308 hops before we give up to prevent infinite loops.
+_MAX_REDIRECTS = 3
+
+
+def _origin(url: str) -> Tuple[str, str, int]:
+    """Return (scheme, host, port) for *url*, normalising the default port."""
+    parsed = urllib.parse.urlparse(url)
+    scheme = parsed.scheme.lower()
+    host = parsed.hostname or ""
+    # urllib.parse returns None for the default port; normalise to the scheme's.
+    if parsed.port is not None:
+        port = parsed.port
+    elif scheme == "https":
+        port = 443
+    else:
+        port = 80
+    return scheme, host, port
+
+
+class Response:
+    """A thin view over an HTTP response the clients care about."""
+
+    __slots__ = ("status", "headers", "body")
+
+    def __init__(self, status: int, headers: Dict[str, str], body: bytes):
+        self.status = status
+        self.headers = headers
+        self.body = body
+
+    def json(self) -> Any:
+        """Decode the body as JSON, or raise EndpointError on malformed JSON."""
+        if not self.body:
+            return None
+        try:
+            return json.loads(self.body)
+        except json.JSONDecodeError as exc:
+            raise EndpointError(
+                f"endpoint returned malformed JSON: {exc}", status=self.status
+            ) from exc
+
+    def text(self) -> str:
+        return self.body.decode("utf-8", errors="replace")
+
+
+def request(
+    method: str,
+    url: str,
+    *,
+    body: Optional[bytes] = None,
+    headers: Optional[Dict[str, str]] = None,
+    timeout: float = DEFAULT_TIMEOUT,
+    expect: Optional[Tuple[int, ...]] = None,
+) -> Response:
+    """Perform an HTTP request and return a :class:`Response`.
+
+    307/308 redirects are followed by re-issuing the **same method and body**
+    to the ``Location`` URL.  Cross-origin redirects and redirect loops (more
+    than ``_MAX_REDIRECTS`` hops) are refused with an :class:`EndpointError`.
+
+    Raises :class:`EndpointError` when:
+      * the transport fails (connection refused / timeout) — ``status`` is None; or
+      * a 307/308 redirect is cross-origin or exceeds the hop limit; or
+      * ``expect`` is given and the response status is not in it — ``status`` is
+        the actual code so the caller can distinguish 400 from 502.
+    """
+    original_origin = _origin(url)
+    current_url = url
+    hops = 0
+
+    while True:
+        req = urllib.request.Request(current_url, data=body, method=method)  # noqa: S310
+        for key, value in (headers or {}).items():
+            req.add_header(key, value)
+
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as resp:  # noqa: S310
+                resp_headers = {k.lower(): v for k, v in resp.headers.items()}
+                response = Response(resp.status, resp_headers, resp.read())
+        except urllib.error.HTTPError as exc:
+            if exc.code in (307, 308):
+                # urllib raises HTTPError for 307/308 instead of following the
+                # redirect.  Re-issue the same method and body to the Location.
+                location = exc.headers.get("Location") or exc.headers.get("location")
+                if not location:
+                    raise EndpointError(
+                        f"{method} {current_url} returned {exc.code} with no Location header",
+                        status=exc.code,
+                    ) from exc
+                # Resolve relative Location against the current URL.
+                redirect_url = urllib.parse.urljoin(current_url, location)
+                if _origin(redirect_url) != original_origin:
+                    raise EndpointError(
+                        f"{method} {current_url} returned {exc.code} to a "
+                        f"cross-origin location {redirect_url!r}; refusing to "
+                        f"re-POST body to a different host (security boundary)",
+                        status=exc.code,
+                    ) from exc
+                hops += 1
+                if hops > _MAX_REDIRECTS:
+                    raise EndpointError(
+                        f"{method} {url} exceeded {_MAX_REDIRECTS} redirects "
+                        f"(last location: {redirect_url!r})",
+                        status=exc.code,
+                    ) from exc
+                current_url = redirect_url
+                continue
+
+            # A non-2xx with a response body (e.g. feedback 400/502). Read the
+            # body so the caller can see the endpoint's error message, and
+            # surface the status — never swallow it.
+            err_body = exc.read().decode("utf-8", errors="replace") if exc.fp else ""
+            raise EndpointError(
+                f"{method} {url} returned {exc.code}: {err_body.strip()}",
+                status=exc.code,
+                body=err_body,
+            ) from exc
+        except (urllib.error.URLError, OSError, TimeoutError) as exc:
+            # Transport-level failure: no HTTP status. Includes connection refused
+            # (endpoint not wired / down) and timeouts.
+            raise EndpointError(f"{method} {url} failed: {exc}", status=None) from exc
+
+        break  # 2xx (or unexpected status) — exit the redirect loop
+
+    if expect is not None and response.status not in expect:
+        raise EndpointError(
+            f"{method} {url} returned {response.status} "
+            f"(expected {', '.join(str(s) for s in expect)}): {response.text().strip()}",
+            status=response.status,
+            body=response.text(),
+        )
+    return response
+
+
+def stream(
+    method: str,
+    url: str,
+    *,
+    body: Optional[bytes] = None,
+    headers: Optional[Dict[str, str]] = None,
+    timeout: float = DEFAULT_TIMEOUT,
+) -> Iterator[str]:
+    """POST and yield the response body LINE BY LINE (for Server-Sent Events).
+
+    Unlike :func:`request` this does NOT buffer the whole body — it streams, so a token
+    stream is delivered as it arrives. No redirect following (streaming endpoints are
+    same-origin: the model gateway, the agent's own /invoke). Raises :class:`EndpointError`
+    on a non-2xx (with ``status`` + the error body) or a transport failure (``status`` None) —
+    never swallows the failure.
+    """
+    req = urllib.request.Request(url, data=body, method=method)  # noqa: S310
+    for key, value in (headers or {}).items():
+        req.add_header(key, value)
+    try:
+        resp = urllib.request.urlopen(req, timeout=timeout)  # noqa: S310
+    except urllib.error.HTTPError as exc:
+        err_body = exc.read().decode("utf-8", errors="replace") if exc.fp else ""
+        raise EndpointError(
+            f"{method} {url} returned {exc.code}: {err_body.strip()}",
+            status=exc.code,
+            body=err_body,
+        ) from exc
+    except (urllib.error.URLError, OSError, TimeoutError) as exc:
+        raise EndpointError(f"{method} {url} failed: {exc}", status=None) from exc
+
+    # The read loop is INSIDE its own try/except (FUNC-7): urllib's `timeout` is a
+    # per-socket-op timeout, so a mid-stream gap between SSE events raised a RAW
+    # socket TimeoutError here — outside the connect try/except above — killing any
+    # stream with a >timeout idle gap (a slow model turn, or a run parked at
+    # requires_action). Translate it (and any transport error) to EndpointError so the
+    # caller sees the SDK's typed error, never a bare TimeoutError. SSE callers pass a
+    # long read timeout (STREAM_READ_TIMEOUT) and the server heartbeats within it.
+    try:
+        with resp:
+            for raw in resp:
+                yield raw.decode("utf-8", errors="replace").rstrip("\r\n")
+    except (urllib.error.URLError, OSError, TimeoutError) as exc:
+        raise EndpointError(f"{method} {url} stream interrupted: {exc}", status=None) from exc
+
+
+def json_body(value: Any) -> bytes:
+    """Serialise a value as compact JSON bytes (matches the launcher contract)."""
+    return json.dumps(value, separators=(",", ":")).encode("utf-8")