keystone-request-context 0.3.0__py3-none-any.whl

keystone/request_context/__init__.py

@@ -0,0 +1,85 @@
+"""Keystone AI — shared request-context library.
+
+Provides the ``ContextVar`` slots and Starlette middleware that propagate
+per-request identifiers (request_id, correlation_id, trace_id, user_id,
+workspace_id, entity_id, stage_id, agent_id, traceparent) plus the full
+header snapshot, available to any downstream code via plain
+``ContextVar.get()`` calls.
+
+``request_id`` (``X-Request-ID``) is per-API-call — each service mints a
+fresh one on every inbound hop, used to pin log lines to a single HTTP
+request to THIS service. Do NOT forward.
+
+``correlation_id`` (``X-Correlation-ID``) is per-business-turn — the FE /
+API gateway mints it once and every downstream service forwards it
+verbatim, so a search by ``correlation_id`` in Splunk / Langfuse returns
+every log line + trace span for the whole turn. ALWAYS forward.
+
+Usage::
+
+    from keystone.request_context import (
+        RequestContextMiddleware,
+        correlation_id_var,
+        request_id_var,
+        workspace_id_var,
+    )
+
+    app.add_middleware(RequestContextMiddleware)
+
+    # Anywhere downstream:
+    rid = request_id_var.get()         # this hop only; log key
+    cid = correlation_id_var.get()     # forward to upstream calls
+    ws = workspace_id_var.get()
+"""
+
+from .caller_identity import (
+    LLMCallerIdentity,
+    gateway_identity_headers,
+    get_caller_identity,
+    get_self_agent,
+    reset_caller_identity,
+    set_caller_identity,
+    set_self_agent,
+)
+from .middleware import (
+    CORRELATION_ID_HEADER,
+    REQUEST_ID_HEADER,
+    RequestContextMiddleware,
+    normalize_correlation_id,
+)
+from .vars import (
+    agent_id_var,
+    correlation_id_var,
+    entity_id_var,
+    headers_var,
+    request_id_var,
+    stage_id_var,
+    trace_id_var,
+    traceparent_var,
+    user_id_var,
+    workspace_id_var,
+)
+
+__all__ = [
+    "CORRELATION_ID_HEADER",
+    "REQUEST_ID_HEADER",
+    "LLMCallerIdentity",
+    "RequestContextMiddleware",
+    "agent_id_var",
+    "correlation_id_var",
+    "entity_id_var",
+    "gateway_identity_headers",
+    "get_caller_identity",
+    "get_self_agent",
+    "headers_var",
+    "normalize_correlation_id",
+    "request_id_var",
+    "reset_caller_identity",
+    "set_caller_identity",
+    "set_self_agent",
+    "stage_id_var",
+    "trace_id_var",
+    "traceparent_var",
+    "user_id_var",
+    "workspace_id_var",
+]

keystone/request_context/caller_identity.py

@@ -0,0 +1,206 @@
+"""Per-request caller identity propagated to outbound building-block calls (llm-gateway, rag, …).
+
+Lifted from ``services/rag`` (FDP-3118) so every keystone service AND the agent SDK share ONE
+identity-forwarding contract: the gateway derives the LiteLLM credential from the caller
+identity — agent (``agent_id``+``agent_version``) and/or end-user (``user_id``). FDP-1734
+originally allowed EXACTLY ONE; FR-70 relaxed that so an agent serving an end user carries BOTH —
+the gateway requires at least one and picks the agent's key whenever an agent is named. In an
+agent pod the agent whose key must resolve is the pod itself, not the inbound caller — see
+:func:`set_self_agent` (FDP-3663).
+
+    set_caller_identity(LLMCallerIdentity(...)) -> token   # at the request / run / task boundary
+    reset_caller_identity(token)                            # in a finally
+    get_caller_identity() -> LLMCallerIdentity | None
+    gateway_identity_headers(auth_token=, operation=, caller_service=) -> dict[str, str]
+    set_self_agent(agent_id, agent_version)                 # once, from an agent pod's composition root
+
+Whoever owns the boundary (a service's ``IdentityMiddleware``, or the agent runtime per run)
+fills the ContextVar; outbound clients read it in their ``_headers()`` builder and forward every
+field. Transparent forwarder — nothing here is service-static; ``caller_service`` names the
+forwarding service (e.g. ``"rag"``, ``"agent-runtime"``).
+
+NOTE: this bundle is a DISTINCT representation from the individual ID ContextVars in ``vars.py``
+(request_id / correlation_id / entity_id / … set by ``RequestContextMiddleware`` for
+logging/audit). This one is the outbound identity contract, set by the service's own
+``IdentityMiddleware`` / the agent runtime. They coexist by design; reconciling them is a later
+cleanup, not this lift.
+"""
+
+from __future__ import annotations
+
+import uuid
+from contextvars import ContextVar, Token
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True, slots=True)
+class LLMCallerIdentity:
+    """Per-request identity bundle forwarded to building-block services as-is.
+
+    Caller identity: agent (``agent_id`` + ``agent_version``) and/or end-user (``user_id``) —
+    WHO CALLED THIS PROCESS. At least one must be set — the gateway rejects a call carrying
+    neither. BOTH are set for the FR-70 case of an agent serving an end user, and both must then
+    be FORWARDED: the agent selects the credential and the agent quota tier, the user selects the
+    consumption tier. ``entity``/``stage`` are forwarded when present (the gateway derives them
+    from the workspace otherwise).
+
+    Note this is not the same question as *"whose gateway credential"* — in an agent pod that is
+    :func:`set_self_agent`, the agent making the outbound hop, not the one recorded here.
+    """
+
+    entity_id: str
+    stage_id: str
+    workspace_id: str
+    correlation_id: str
+    # who called this process — agent and/or end-user; at least one is set (FR-70 allows both),
+    # and a human-triggered run leaves the agent pair empty
+
+    agent_id: str = ""
+    agent_version: str = ""
+    user_id: str = ""
+    # FDP-3072 W5 (S3) — the turn's opaque invocation key (inv_…), minted by the gateway and
+    # handed to the pod per-request. A CREDENTIAL: repr=False keeps it out of any accidental
+    # log/str of this bundle; it is emitted outbound only as X-Invocation-Key.
+    invocation_key: str = field(default="", repr=False)
+
+
+_caller_identity: ContextVar[LLMCallerIdentity | None] = ContextVar(
+    "keystone_llm_caller_identity",
+    default=None,
+)
+
+# The agent this PROCESS is — not who called it. A plain module global, not a ContextVar: it is
+# process-static config (the operator injects it into the pod), identical for every run the process
+# handles. Unset in every service that is not an agent pod, which keeps their headers unchanged.
+_self_agent: tuple[str, str] | None = None
+
+
+def set_self_agent(agent_id: str, agent_version: str) -> None:
+    """Register the agent this process IS, for outbound ``X-Agent-ID`` / ``X-Agent-Version``.
+
+    Call once from the composition root (FDP-3663). Blank ``agent_id`` clears the registration, so
+    a local/offline run with no injected identity behaves exactly as before.
+
+    **Why this is separate from the caller identity.** ``LLMCallerIdentity.agent_id`` answers *"who
+    called me"* — empty when a human triggered the run. The gateway's ``X-Agent-ID`` answers a
+    different question: *"whose LiteLLM key, budget, model allowlist and Langfuse project does this
+    call use"*, which is always the agent **making** the call. Feeding the caller's (absent) agent id
+    into that header sent every pro-code LLM call down the gateway's user path, so it billed the
+    WORKSPACE key and applied no per-agent budget, token cap or model allowlist at all.
+    """
+    global _self_agent
+    _self_agent = (agent_id, agent_version) if agent_id else None
+
+
+def get_self_agent() -> tuple[str, str] | None:
+    """The ``(agent_id, agent_version)`` this process is, or ``None`` when not an agent pod."""
+    return _self_agent
+
+
+def set_caller_identity(identity: LLMCallerIdentity) -> Token[LLMCallerIdentity | None]:
+    """Bind ``identity`` to the current execution context. Pass the returned token to
+    ``reset_caller_identity`` in a ``finally`` — failing to reset leaks identity into the next
+    request/run handled by the same worker process."""
+    return _caller_identity.set(identity)
+
+
+def get_caller_identity() -> LLMCallerIdentity | None:
+    return _caller_identity.get()
+
+
+def reset_caller_identity(token: Token[LLMCallerIdentity | None]) -> None:
+    _caller_identity.reset(token)
+
+
+def gateway_identity_headers(*, auth_token: str, operation: str, caller_service: str) -> dict[str, str]:
+    """Build outbound building-block headers from the current caller-identity ContextVar.
+
+    Emits EVERY caller identity the context carries: ``X-Agent-ID`` + ``X-Agent-Version`` for an
+    agent/service call, ``X-User-ID`` for an end-user call, and BOTH when an agent is serving an
+    end user (FR-70).
+
+    This used to be exclusive — ``X-User-ID`` else the agent pair — on the pre-FR-70 rule that
+    the gateway 400s when both are present. FR-70 relaxed that (``auth._validate_caller_identity``
+    now rejects only a call carrying NEITHER), so the XOR silently dropped the agent on exactly
+    the case it was meant to describe: an agent run on behalf of a user reached the gateway as a
+    plain user call, which resolved the WORKSPACE virtual key instead of the agent's, skipped the
+    agent quota tier, and left per-agent cost attribution (FR-21) and the Langfuse agent blank.
+
+    ``caller_service`` → ``X-Caller-Service`` (the forwarding service). No-context fallback
+    (``get_caller_identity() is None``) emits empty agent headers + a random correlation id — the
+    gateway rejects that, which is the correct loud-failure mode for a bare/boot-time call.
+
+    When :func:`set_self_agent` has registered this process as an agent, ``X-Agent-ID`` +
+    ``X-Agent-Version`` are emitted for THAT agent **alongside** ``X-User-ID``. The gateway allows
+    both since FR-70 — *"an agent serving an end_user carries both; the agent resolves the
+    credential, and user_id becomes the subject of the consumption quota tier"* — and it is
+    explicitly "strictly more permissive, so no previously-valid call is affected" (source:
+    ``llm-gateway`` ``routers/middleware/auth.py::_validate_caller_identity``, which as of the
+    2026-08-13 develop merge rejects only a call carrying NEITHER). Without a registered self agent
+    the behaviour is byte-identical to before, which is why no other service's headers change.
+
+    ``X-Agent-Version`` is REQUIRED whenever ``X-Agent-ID`` is present — the gateway 400s with
+    ``LLM_MISSING_CALLER_METADATA`` otherwise — so the two are always emitted as a pair.
+    """
+    caller = get_caller_identity()
+    if caller is None:
+        entity_id = stage_id = workspace_id = agent_id = agent_version = user_id = ""
+        correlation_id = str(uuid.uuid4())
+    else:
+        entity_id = caller.entity_id
+        stage_id = caller.stage_id
+        workspace_id = caller.workspace_id
+        agent_id = caller.agent_id
+        agent_version = caller.agent_version
+        user_id = caller.user_id
+        correlation_id = caller.correlation_id
+    invocation_key = "" if caller is None else caller.invocation_key
+    headers = {
+        "Content-Type": "application/json",
+        "X-Entity-ID": entity_id,
+        "X-Stage-ID": stage_id,
+        "X-Workspace-ID": workspace_id,
+        "X-Correlation-ID": correlation_id,
+        "X-Caller-Service": caller_service,
+        "X-Caller-Operation": operation,
+    }
+    # Only emit Authorization when a token is actually present. An empty token would produce the
+    # literal header value ``"Bearer "`` (trailing space, no credential), which httpx/h11 reject as an
+    # illegal header value → the request never leaves the pod. Downstreams that need no east-west
+    # bearer (e.g. RAG, auth-terminated at Kong and trusting the forwarded identity headers) pass
+    # ``auth_token=""`` and correctly get no Authorization header.
+    if auth_token:
+        headers["Authorization"] = f"Bearer {auth_token}"
+    # FDP-3072 W5 (S3b) — the invocation key rides its OWN header, deliberately NOT Authorization:
+    # that slot already carries real east-west bearers (llm-gateway), and dual-run (S5 step 1)
+    # requires this emission to be purely ADDITIVE — legacy identity headers keep flowing until
+    # Kong's strip-and-stamp flips. A separate header also dissolves the "two credentials, one
+    # header" routing problem Ops raised: the Kong plugin just reads X-Invocation-Key.
+    if invocation_key:
+        headers["X-Invocation-Key"] = invocation_key
+    self_agent = get_self_agent()
+    if self_agent is not None:
+        # Agent pod (FDP-3663): name the agent MAKING this hop — its key, budget, model allowlist
+        # and Langfuse project are the ones that must apply — and keep the end user alongside it so
+        # they stay the subject of the consumption quota tier (FR-70). Self wins over the inbound
+        # caller's pair: on an agent-to-agent hop the credential belongs to the agent calling now.
+        headers["X-Agent-ID"], headers["X-Agent-Version"] = self_agent
+        if user_id:
+            headers["X-User-ID"] = user_id
+    else:
+        # Not an agent pod (rag, memory, CLI, …): forward the inbound caller's identity as-is.
+        if user_id:
+            headers["X-User-ID"] = user_id
+        if agent_id or not user_id:
+            # The agent pair rides whenever an agent is named, alongside X-User-ID when both are
+            # set. The `not user_id` arm keeps the no-identity case emitting the EMPTY pair, which
+            # is what makes the gateway reject a context-less call loudly (see the docstring)
+            # instead of it leaving with no identity header at all.
+            #
+            # This is deliberately in the `else` arm: an agent pod already emitted ITS OWN pair
+            # above, and the inbound caller's `agent_id` must not overwrite it — that is the whole
+            # point of FDP-3663 (self wins on an agent-to-agent hop). Hoisting this to a bare `if`
+            # silently restores the workspace-key bug for exactly the A2A case.
+            headers["X-Agent-ID"] = agent_id
+            headers["X-Agent-Version"] = agent_version
+    return headers

keystone/request_context/middleware.py

@@ -0,0 +1,189 @@
+"""Starlette middleware that populates the request-context ``ContextVar`` slots.
+
+Wire once at the FastAPI / Starlette app:
+
+.. code-block:: python
+
+    from keystone.request_context import RequestContextMiddleware
+
+    app.add_middleware(RequestContextMiddleware)
+
+Per request the middleware:
+
+1. Snapshots ``request.headers`` into :data:`keystone.request_context.headers_var`
+   with keys lowercased (Starlette already does this internally, but we
+   materialize a plain ``dict`` so downstream code can iterate without
+   pulling in Starlette types).
+2. Reads each well-known header and pushes the value into its dedicated
+   ``ContextVar`` slot.
+3. Auto-generates an ``uuid7`` for :data:`request_id_var` (per-API-call,
+   ``X-Request-ID``) when absent, and for :data:`correlation_id_var`
+   (per-turn, ``X-Correlation-ID``) when absent — legacy callers that
+   don't stamp the header still get a value to log against. Both
+   chosen values are echoed back on the response so callers can
+   correlate logs across hops.
+4. Resets every token in a ``try/finally`` block — defensive against
+   worker-reuse patterns (uvicorn keeps event-loop / task references
+   alive between requests).
+"""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+from typing import TYPE_CHECKING
+
+import uuid_utils
+from starlette.middleware.base import BaseHTTPMiddleware
+
+from .vars import (
+    agent_id_var,
+    correlation_id_var,
+    entity_id_var,
+    headers_var,
+    request_id_var,
+    stage_id_var,
+    trace_id_var,
+    traceparent_var,
+    user_id_var,
+    workspace_id_var,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+    from starlette.requests import Request
+    from starlette.responses import Response
+    from starlette.types import ASGIApp
+
+REQUEST_ID_HEADER = "X-Request-ID"
+CORRELATION_ID_HEADER = "X-Correlation-ID"
+
+# Header (lowercase) → ContextVar slot. Keep alphabetical-ish by intent
+# (tracing first, then identity / tenancy) to make the map easy to scan.
+_HEADER_TO_VAR: tuple[tuple[str, ContextVar[str | None]], ...] = (
+    ("x-request-id", request_id_var),
+    ("x-correlation-id", correlation_id_var),
+    ("x-trace-id", trace_id_var),
+    ("traceparent", traceparent_var),
+    ("x-user-id", user_id_var),
+    ("x-workspace-id", workspace_id_var),
+    ("x-entity-id", entity_id_var),
+    ("x-stage-id", stage_id_var),
+    ("x-agent-id", agent_id_var),
+)
+
+
+def _generate_request_id() -> str:
+    """Return a fresh ``uuid7`` string (UUID format with dashes).
+
+    Wrapped so tests can monkey-patch a deterministic generator if needed.
+    """
+    return str(uuid_utils.uuid7())
+
+
+def normalize_correlation_id(value: str | None) -> str | None:
+    """Strip dashes + lowercase a UUID string into the 32-hex W3C trace-id
+    shape so logs, downstream HTTP headers, and Langfuse trace_ids all
+    carry the EXACT SAME literal string.
+
+    Langfuse v3 SDK requires ``trace_id`` to be exactly 32 lowercase hex
+    chars (no dashes) — passing the FE-minted UUID-with-dashes raises
+    "is not a valid 32 lowercase hex char Langfuse trace id" and the
+    workflow span fails to open. Normalizing at the middleware level
+    means every consumer (log binding, ``X-Correlation-ID`` forward,
+    Langfuse start_turn) reads the already-normalized form from
+    ``correlation_id_var`` — no per-call-site strip.
+
+    Returns ``None`` for malformed inputs (caller falls back to
+    auto-minted UUID, then re-normalize).
+
+    Public since FDP-3435: agent-runtime normalizes at its own boundary and
+    derives the run's ``trace_id`` from stored correlation ids with the SAME
+    rule — one implementation, no drift.
+    """
+    if not value:
+        return None
+    cleaned = value.replace("-", "").lower()
+    if len(cleaned) != 32:
+        return None
+    try:
+        int(cleaned, 16)
+    except ValueError:
+        return None
+    return cleaned
+
+
+# Backwards-compatible private alias (pre-FDP-3435 name).
+_normalize_correlation_id = normalize_correlation_id
+
+
+class RequestContextMiddleware(BaseHTTPMiddleware):
+    """Populate the request-context ``ContextVar`` slots for the request lifetime.
+
+    See module docstring for the full contract.
+    """
+
+    def __init__(self, app: ASGIApp) -> None:
+        super().__init__(app)
+
+    async def dispatch(
+        self,
+        request: Request,
+        call_next: Callable[[Request], Awaitable[Response]],
+    ) -> Response:
+        # 1. Materialize the lowercased-key header snapshot.
+        #
+        # Starlette's ``request.headers`` already supports case-insensitive
+        # lookup, but downstream consumers (event_bus DSL, @require) expect
+        # a plain dict so they aren't coupled to Starlette types.
+        headers_snapshot: dict[str, str] = {key.lower(): value for key, value in request.headers.items()}
+
+        # 2. Resolve / mint X-Request-ID (per-API-call) AND X-Correlation-ID
+        # (per-turn). Auto-gen UUID v7 for either when absent so logs always
+        # have a value to pivot on — semantics differ (request_id is per-hop,
+        # correlation_id is forwarded verbatim) but both fall back the same way.
+        request_id = headers_snapshot.get("x-request-id") or _generate_request_id()
+        # X-Correlation-ID is STORED + ECHOED as the 32-hex normalized form
+        # (dashes stripped, lowercased) so logs / forward / Langfuse trace_id
+        # all share one literal string. Malformed inbound value → re-mint a
+        # UUID v7 and normalize that.
+        correlation_raw = headers_snapshot.get("x-correlation-id")
+        correlation_id = _normalize_correlation_id(correlation_raw)
+        if correlation_id is None:
+            # Either no header sent, or value wasn't UUID-shaped — mint fresh.
+            correlation_id = _normalize_correlation_id(_generate_request_id())
+        # Make sure the snapshot reflects the resolved (possibly minted) values
+        # so DSL code reading ``headers_var`` sees a consistent view.
+        headers_snapshot["x-request-id"] = request_id
+        headers_snapshot["x-correlation-id"] = correlation_id
+
+        # 3. Set every ContextVar, retaining tokens so we can reset them
+        # in ``finally``. Resolved (minted-or-received) values already in
+        # ``headers_snapshot`` win for both request_id and correlation_id.
+        tokens = [headers_var.set(headers_snapshot)]
+        for header_name, ctx_var in _HEADER_TO_VAR:
+            value = headers_snapshot.get(header_name)
+            tokens.append(ctx_var.set(value))
+
+        try:
+            response = await call_next(request)
+        finally:
+            # Reset in reverse order — ContextVar.reset is strict about token
+            # ordering when nested calls have stacked sets on the same var.
+            for token in reversed(tokens):
+                try:
+                    token.var.reset(token)
+                except (LookupError, ValueError):
+                    # Defensive: a misbehaving downstream may have stomped
+                    # the var with a bare ``.set()`` and dropped the token.
+                    # We swallow because the alternative is leaking the
+                    # exception into the response path.
+                    pass
+
+        # 4. Echo resolved IDs so clients can correlate logs across hops.
+        response.headers[REQUEST_ID_HEADER] = request_id
+        response.headers[CORRELATION_ID_HEADER] = correlation_id
+        return response
+
+
+__all__ = ["CORRELATION_ID_HEADER", "REQUEST_ID_HEADER", "RequestContextMiddleware"]

keystone/request_context/vars.py

@@ -0,0 +1,119 @@
+"""Request-scoped ``ContextVar`` slots for the Keystone platform.
+
+Every value is populated by :class:`keystone.request_context.RequestContextMiddleware`
+at the boundary of an HTTP request, read by downstream code (services,
+repositories, decorators such as ``@announce`` / ``@require``), and reset
+in a ``try/finally`` block before the request returns.
+
+Conventions
+-----------
+
+* Nine "ID" ContextVars are typed ``str | None`` with ``default=None`` —
+  this preserves the distinction between *absent* (no header was sent) and
+  *explicitly empty string* (header was sent with empty value).
+* ``headers_var`` carries the full raw header snapshot (keys lowercased)
+  as an escape hatch for code that needs headers we haven't promoted to
+  first-class slots yet; defaults to an empty ``dict`` for non-request
+  contexts (workers, crons, tests).
+
+The names mirror the headers documented in
+``specs/conventions/multi-tenancy.md`` and the event-bus impl plan
+(``docs/architecture/event-bus/impl-plan.md`` §Phase 1).
+"""
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+
+# ---------------------------------------------------------------------------
+# Tracing identifiers
+# ---------------------------------------------------------------------------
+
+request_id_var: ContextVar[str | None] = ContextVar("keystone_request_id", default=None)
+"""Per-API-call ID (header ``X-Request-ID``) — DO NOT forward.
+
+Scope: a SINGLE API call. Each service mints its own value on every
+inbound hop — value seen by service A is unrelated to value seen by
+service B in the same business turn. Middleware auto-generates a
+``uuid7`` when the header is absent and echoes the chosen value
+on the response so clients can pin log lines to one HTTP request.
+
+→ Use this to find log lines for ONE inbound request to the current
+service. To stitch a multi-hop turn across services use
+:data:`correlation_id_var` instead — that ID is forwarded verbatim
+by every service.
+"""
+
+correlation_id_var: ContextVar[str | None] = ContextVar("keystone_correlation_id", default=None)
+"""Per-turn correlation ID (header ``X-Correlation-ID``) — FORWARD verbatim.
+
+Scope: a WHOLE business flow that may fan out across many services
+(e.g. one user click → FE → Visual Builder → Agent Hub + LLM Gateway +
+RAG + Memory + Skill + Langfuse). The FE / API gateway mints the value
+ONCE (typically ``crypto.randomUUID()``) and stamps it on the first
+request; every downstream service forwards the same value as-is on
+every outbound hop. Middleware auto-generates a ``uuid7`` as a fallback
+for legacy callers that don't stamp the header (cron jobs, internal
+service-to-service calls) so logs always have something to pivot on;
+the chosen value is echoed back on the response.
+
+→ Forward this on EVERY outbound HTTP / Kafka header. Search by this
+single value in Splunk to see every service log for the turn; paste
+into Langfuse to see the trace.
+"""
+
+trace_id_var: ContextVar[str | None] = ContextVar("keystone_trace_id", default=None)
+"""Cross-service trace identifier (header ``X-Trace-ID``)."""
+
+traceparent_var: ContextVar[str | None] = ContextVar("keystone_traceparent", default=None)
+"""W3C ``traceparent`` header verbatim (for future OTel propagation)."""
+
+# ---------------------------------------------------------------------------
+# Identity / tenancy identifiers
+# ---------------------------------------------------------------------------
+
+user_id_var: ContextVar[str | None] = ContextVar("keystone_user_id", default=None)
+"""Authenticated principal (header ``X-User-ID``)."""
+
+workspace_id_var: ContextVar[str | None] = ContextVar("keystone_workspace_id", default=None)
+"""Active workspace scope (header ``X-Workspace-ID``)."""
+
+entity_id_var: ContextVar[str | None] = ContextVar("keystone_entity_id", default=None)
+"""Active entity scope (header ``X-Entity-ID``)."""
+
+stage_id_var: ContextVar[str | None] = ContextVar("keystone_stage_id", default=None)
+"""Active stage scope (header ``X-Stage-ID``, opt-in per endpoint)."""
+
+agent_id_var: ContextVar[str | None] = ContextVar("keystone_agent_id", default=None)
+"""Caller agent identifier when traffic originates from another agent
+(header ``X-Agent-ID``)."""
+
+# ---------------------------------------------------------------------------
+# Escape hatch — full headers snapshot
+# ---------------------------------------------------------------------------
+
+headers_var: ContextVar[dict[str, str]] = ContextVar("keystone_request_headers", default={})  # noqa: B039 — intentional read-only sentinel; see warning below
+"""Full inbound header snapshot, keys lowercased.
+
+Code paths that need headers we have NOT promoted to a first-class slot
+(e.g. the ``header:`` DSL in ``@announce``) read directly from here.
+``default={}`` keeps the dict truthy-comparable without ``None`` checks
+in worker / no-request scenarios.
+
+WARNING: The default value is a **shared empty dict** for ergonomic reads.
+Never mutate ``headers_var.get()`` — always ``headers_var.set(new_dict)``
+with a fresh dict to avoid bleeding state across requests.
+"""
+
+__all__ = [
+    "agent_id_var",
+    "correlation_id_var",
+    "entity_id_var",
+    "headers_var",
+    "request_id_var",
+    "stage_id_var",
+    "trace_id_var",
+    "traceparent_var",
+    "user_id_var",
+    "workspace_id_var",
+]

keystone_request_context-0.3.0.dist-info/METADATA

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: keystone-request-context
+Version: 0.3.0
+Summary: Shared request-scoped ContextVar slots + Starlette middleware for Keystone AI services.
+Requires-Python: >=3.12
+Requires-Dist: starlette<2,>=1.3.1
+Requires-Dist: uuid-utils<1,>=0.14
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=8; extra == "dev"
+Requires-Dist: pytest-asyncio<1,>=0.24; extra == "dev"
+Requires-Dist: pytest-cov<7,>=6; extra == "dev"
+Requires-Dist: httpx<1,>=0.28; extra == "dev"
+Requires-Dist: ruff==0.15.15; extra == "dev"

keystone_request_context-0.3.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+keystone/request_context/__init__.py,sha256=yqVk8CH3RAYfVucuMsKR9IClWtIzE3GtQ3k1UkrGreA,2332
+keystone/request_context/caller_identity.py,sha256=1iGAOemxcV-BK1MvbK83WqcNmmVZkLHJYRYYo2HmQP4,11563
+keystone/request_context/middleware.py,sha256=i3AmnF3fNbMPYFoTOEedkHvwS_IPZN5vNoeCtIirMqY,7529
+keystone/request_context/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+keystone/request_context/vars.py,sha256=FZaJPLOZO8HCtpLl8sNoC_l5hZLAjKo9sXURuT9KS0I,5315
+keystone_request_context-0.3.0.dist-info/METADATA,sha256=Pj7mqsxb4zou44SllrOVF_SSlsTtkv8iDnmUfTfYFZk,517
+keystone_request_context-0.3.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+keystone_request_context-0.3.0.dist-info/top_level.txt,sha256=XS9DabbjrYNyRjQpLiI8n1RiT-5pV3BRO7CLSCg68ZY,9
+keystone_request_context-0.3.0.dist-info/RECORD,,

keystone_request_context-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

keystone_request_context-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+keystone