contexory-sdk 0.1.0__py3-none-any.whl

contexory/__init__.py

@@ -0,0 +1,67 @@
+from .apply_tools import AppliedTools, apply_tools
+from .client import (
+    DEFAULT_BASE_URL,
+    DEFAULT_LABEL,
+    Contexory,
+    FetchResponse,
+    ResolvedContext,
+    default_fetch,
+)
+from .errors import ContexoryResolveError, ContexorySignatureError
+from .instrument import (
+    AGENT_VERSION_ATTRIBUTE,
+    RELEASE_BAGGAGE_KEY,
+    VENDOR_ATTRIBUTES,
+    VENDORS,
+    Instrumentation,
+    instrument,
+    open_inference_metadata,
+    open_llmetry_association_properties,
+    openai_agents_trace_metadata,
+)
+from .mcp_upstream import (
+    canonical_json,
+    clamp_ttl,
+    description_hash,
+    hash_mcp_tools,
+    mcp_tools_hash,
+    report_upstream_hashes,
+    schema_hash,
+    watch_mcp_tools,
+)
+from .release import normalize_release
+from .types import ResolvedTool, ResolvePayload, Upstream
+
+__all__ = [
+    "AGENT_VERSION_ATTRIBUTE",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_LABEL",
+    "RELEASE_BAGGAGE_KEY",
+    "VENDORS",
+    "VENDOR_ATTRIBUTES",
+    "AppliedTools",
+    "Contexory",
+    "ContexoryResolveError",
+    "ContexorySignatureError",
+    "FetchResponse",
+    "Instrumentation",
+    "ResolvePayload",
+    "ResolvedContext",
+    "ResolvedTool",
+    "Upstream",
+    "canonical_json",
+    "clamp_ttl",
+    "description_hash",
+    "hash_mcp_tools",
+    "mcp_tools_hash",
+    "report_upstream_hashes",
+    "schema_hash",
+    "watch_mcp_tools",
+    "apply_tools",
+    "default_fetch",
+    "instrument",
+    "normalize_release",
+    "open_inference_metadata",
+    "open_llmetry_association_properties",
+    "openai_agents_trace_metadata",
+]

contexory/adapters/claude_agent_sdk.py

@@ -0,0 +1,58 @@
+"""Claude Agent SDK: an in-process MCP proxy that re-exposes external tools with released descriptions.
+
+Claude Code's built-in tools and external MCP servers describe themselves; their
+descriptions cannot be rewritten in flight. The proxy registers each upstream tool again
+under an in-process MCP server with the released description and forwards the call, so
+the model reads Contexory's text. Name the proxy server so the model sees
+`mcp__<server>__<tool>` and disallow the upstream originals with `disallowed_tools`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Iterable, Mapping
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class UpstreamTool:
+    name: str
+    description: str
+    input_schema: Any
+    #: Forwards one call: `await call(args)` returns the MCP result dict (`{"content": [...]}`).
+    call: Callable[[Mapping[str, Any]], Awaitable[dict[str, Any]]]
+
+
+def proxied_tools(context: Any, upstream: Iterable[UpstreamTool], *, include_unmatched: bool = True) -> list[Any]:
+    """`UpstreamTool`s with the released description applied.
+
+    A tool with no released description is kept as-is unless `include_unmatched=False`.
+    """
+    tools = list(upstream)
+    applied = context.apply_tools({t.name: {"name": t.name, "description": t.description} for t in tools})
+    out: list[UpstreamTool] = []
+    released = {t.name for t in context.tools}
+    for tool in tools:
+        if tool.name not in released and not include_unmatched:
+            continue
+        description = applied[tool.name]["description"]
+        out.append(UpstreamTool(tool.name, description, tool.input_schema, tool.call))
+    return out
+
+
+def create_proxy_server(
+    context: Any, upstream: Iterable[UpstreamTool], *, name: str = "contexory", include_unmatched: bool = True
+) -> Any:
+    """An SDK MCP server config for `ClaudeAgentOptions(mcp_servers={name: server})`."""
+    try:
+        from claude_agent_sdk import create_sdk_mcp_server, tool
+    except ImportError as error:
+        raise ImportError(
+            "create_proxy_server() needs the Claude Agent SDK. pip install 'contexory-sdk[claude-agent-sdk]'"
+        ) from error
+
+    wrapped = [
+        tool(t.name, t.description, t.input_schema)(t.call)
+        for t in proxied_tools(context, upstream, include_unmatched=include_unmatched)
+    ]
+    return create_sdk_mcp_server(name=name, tools=wrapped)

contexory/adapters/langchain.py

@@ -0,0 +1,36 @@
+"""LangChain / LangGraph: apply released tool descriptions and the system prompt per model call."""
+
+from __future__ import annotations
+
+from typing import Any
+
+try:
+    from langchain.agents.middleware import AgentMiddleware as _Base
+except ImportError:  # pragma: no cover - the adapter still works duck-typed against any object with `override`
+    _Base = object  # type: ignore[assignment,misc]
+
+
+class ContexoryMiddleware(_Base):  # type: ignore[misc,valid-type]
+    """Agent middleware: `create_agent(model, tools, middleware=[ContexoryMiddleware(ctx)])`.
+
+    Rewrites each model request's tools to the released descriptions. `apply_system=True`
+    also replaces the system message with the release's system prompt.
+    """
+
+    def __init__(self, context: Any, *, apply_system: bool = False):
+        self.context = context
+        self.apply_system = apply_system
+
+    def _rewrite(self, request: Any) -> Any:
+        overrides: dict[str, Any] = {}
+        if request.tools:
+            overrides["tools"] = self.context.apply_tools(list(request.tools))
+        if self.apply_system:
+            overrides["system_prompt"] = self.context.system
+        return request.override(**overrides) if overrides else request
+
+    def wrap_model_call(self, request: Any, handler: Any) -> Any:
+        return handler(self._rewrite(request))
+
+    async def awrap_model_call(self, request: Any, handler: Any) -> Any:
+        return await handler(self._rewrite(request))

contexory/adapters/pydantic_ai.py

@@ -0,0 +1,27 @@
+"""Pydantic AI: apply released tool descriptions through `prepare_tools`."""
+
+from __future__ import annotations
+
+import dataclasses
+from typing import Any
+
+from ..apply_tools import describe_tool
+
+
+def prepare_tools(context: Any) -> Any:
+    """`Agent(model, prepare_tools=prepare_tools(ctx))`.
+
+    Descriptions only: Pydantic AI routes a call back by the tool name it registered,
+    so renames are not offered here.
+    """
+    released = {tool.name: tool for tool in context.tools}
+
+    async def prepare(_run_context: Any, tool_defs: list[Any]) -> list[Any]:
+        return [
+            dataclasses.replace(definition, description=describe_tool(released[definition.name]))
+            if definition.name in released
+            else definition
+            for definition in tool_defs
+        ]
+
+    return prepare

contexory/apply_tools.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+import copy
+import dataclasses
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass, field
+from typing import Any, TypeVar
+
+from .mcp_upstream import description_hash
+from .types import ResolvedTool
+
+T = TypeVar("T")
+
+
+@dataclass
+class AppliedTools:
+    tools: Any
+    #: Applied name to the host's original name; present only for renamed tools.
+    reverse: dict[str, str] = field(default_factory=dict)
+    #: Host tools no resolved tool matched; they pass through unchanged.
+    unmatched: list[str] = field(default_factory=list)
+    #: Resolved tools nothing in the host matched.
+    unused: list[str] = field(default_factory=list)
+    #: Host tools whose override was not applied because the MCP server changed the description
+    #: the override was written against and Contexory has not accepted the change. The server's own text stands.
+    held: list[str] = field(default_factory=list)
+
+
+def describe_tool(tool: ResolvedTool) -> str:
+    return f"{tool.description}\n\n{tool.parameter_notes}" if tool.parameter_notes else tool.description
+
+
+def _get(tool: Any, key: str) -> Any:
+    return tool.get(key) if isinstance(tool, Mapping) else getattr(tool, key, None)
+
+
+def _has(tool: Any, key: str) -> bool:
+    return key in tool if isinstance(tool, Mapping) else hasattr(tool, key)
+
+
+def with_fields(tool: Any, fields: Mapping[str, Any]) -> Any:
+    """A shallow copy with `fields` replaced. Dicts stay dicts and objects keep their class."""
+    if isinstance(tool, Mapping):
+        return {**tool, **fields}
+    if dataclasses.is_dataclass(tool) and not isinstance(tool, type):
+        return dataclasses.replace(tool, **fields)
+    if hasattr(tool, "model_copy"):
+        return tool.model_copy(update=dict(fields))
+    clone = copy.copy(tool)
+    for key, value in fields.items():
+        object.__setattr__(clone, key, value)
+    return clone
+
+
+def _takes_description(tool: Any) -> bool:
+    # A function tool declares `description`; hosted tools have a name and no
+    # description, and growing one would change what the host sends.
+    return isinstance(_get(tool, "description"), str) or _get(tool, "type") == "function"
+
+
+def _upstream_name(host_name: str, server: str | None) -> str:
+    """The name the MCP server gives a tool a host lists as `mcp__<server>__<tool>`."""
+    prefix = f"mcp__{server}__" if server is not None else ""
+    return (
+        host_name[len(prefix) :]
+        if prefix and host_name.startswith(prefix) and len(host_name) > len(prefix)
+        else host_name
+    )
+
+
+def _is_held(match: ResolvedTool, host_name: str, tool: Any, upstream_hashes: Mapping[str, Any] | None) -> bool:
+    """An override pinned to an upstream description is held once the upstream hash is no longer the accepted one."""
+    accepted = match.upstream.hash if match.upstream else None
+    if accepted is None:
+        return False
+    name = _upstream_name(host_name, match.upstream.server)
+    observed = None
+    for key in (name, host_name):
+        entry = (upstream_hashes or {}).get(key)
+        observed = entry.get("d") if isinstance(entry, Mapping) else None
+        if observed is not None:
+            break
+    if observed is None:
+        description = _get(tool, "description")
+        observed = description_hash(name, description) if isinstance(description, str) else None
+    return observed is not None and observed != accepted
+
+
+def apply_tools(
+    resolved: Iterable[ResolvedTool],
+    tools: Any,
+    renames: Mapping[str, str] | None = None,
+    upstream_hashes: Mapping[str, Any] | None = None,
+) -> AppliedTools:
+    """Replace tool descriptions with the released ones.
+
+    `tools` is a dict keyed by tool name or a list of tool objects (dicts or objects
+    with `name`/`description`). Without `renames` a tool is matched by name and only
+    its description changes. A renamed tool (`{your_name: contexory_name}`) takes the
+    Contexory name and description; `reverse` maps the new name back.
+
+    `upstream_hashes` is what each MCP tool's description hashes to now, by host tool name
+    (`watch_mcp_tools(...).latest()`); without it the hash is taken from the host tool's own
+    `description`. An override whose upstream hash differs from the accepted one is `held`.
+    """
+    resolved = list(resolved)
+    by_name = {t.name: t for t in resolved}
+    renames = renames or {}
+    reverse: dict[str, str] = {}
+    unmatched: list[str] = []
+    held: list[str] = []
+    used: set[str] = set()
+    taken: set[str] = set()
+
+    def apply(host_name: str, tool: Any) -> tuple[str, Any]:
+        target = renames[host_name] if host_name in renames else host_name
+        match = by_name.get(target)
+        out_name, out = host_name, tool
+        if match is not None and _takes_description(tool) and _is_held(match, host_name, tool, upstream_hashes):
+            used.add(match.name)
+            held.append(host_name)
+        elif match is not None and _takes_description(tool):
+            used.add(match.name)
+            out = with_fields(tool, {"description": describe_tool(match)})
+            if target != host_name:
+                out_name = target
+                reverse[target] = host_name
+        else:
+            unmatched.append(host_name)
+        # An unnamed list tool is an unmatched pass-through, so it can't collide.
+        if out_name != "":
+            if out_name in taken:
+                raise ValueError(f'apply_tools: two tools would be named "{out_name}"')
+            taken.add(out_name)
+        if out_name != host_name and _has(out, "name"):
+            out = with_fields(out, {"name": out_name})
+        return out_name, out
+
+    if isinstance(tools, Mapping):
+        result: Any = dict(apply(name, tool) for name, tool in tools.items())
+    else:
+        result = [apply(_get(tool, "name") or "", tool)[1] for tool in tools]
+    return AppliedTools(
+        tools=result,
+        reverse=reverse,
+        unmatched=unmatched,
+        unused=[t.name for t in resolved if t.name not in used],
+        held=held,
+    )

contexory/cache.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .payload import parse_payload
+from .signing import sha256_hex, verify_body
+from .types import ResolvePayload
+
+
+@dataclass
+class CachedResolution:
+    payload: ResolvePayload
+    body: str
+    etag: str
+    fetched_at: float
+
+
+class ResolveCache:
+    """File cache under one directory, byte-compatible with the TypeScript SDK's:
+
+    labels/<h>.json      the label's ETag and which release it last pointed at
+    releases/<hash>.json the signed body, named by its content hash
+    keys.json            signing keys seen so far
+
+    A release is immutable, so its file is write-once. Every read re-verifies the
+    signature against the cached keys: a file edited on disk, or a key that is no
+    longer known, reads as a miss instead of as trusted context.
+    """
+
+    def __init__(self, directory: str | os.PathLike[str]):
+        self.dir = Path(directory)
+
+    def _read_json(self, *parts: str) -> Any:
+        try:
+            return json.loads(self.dir.joinpath(*parts).read_text("utf8"))
+        except (OSError, ValueError):
+            return None
+
+    def _write_json(self, value: Any, *parts: str) -> None:
+        """Atomic, and best effort: a cache that cannot be written must not fail a resolve."""
+        path = self.dir.joinpath(*parts)
+        tmp = path.with_name(f"{path.name}.{os.getpid()}.tmp")
+        try:
+            path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+            fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+            with os.fdopen(fd, "w", encoding="utf8") as handle:
+                handle.write(json.dumps(value, separators=(",", ":")))
+            os.replace(tmp, path)
+        except OSError:
+            pass
+
+    def read_keys(self) -> list[dict[str, str]]:
+        data = self._read_json("keys.json")
+        if not isinstance(data, list):
+            return []
+        return [
+            k
+            for k in data
+            if isinstance(k, dict) and isinstance(k.get("keyId"), str) and isinstance(k.get("publicKey"), str)
+        ]
+
+    def write_keys(self, keys: list[dict[str, str]]) -> None:
+        self._write_json(keys, "keys.json")
+
+    def read(self, label_key: str) -> CachedResolution | None:
+        label = self._read_json("labels", f"{label_key}.json")
+        if (
+            not isinstance(label, dict)
+            or not isinstance(label.get("etag"), str)
+            or not isinstance(label.get("hash"), str)
+            or isinstance(label.get("fetchedAt"), bool)
+            or not isinstance(label.get("fetchedAt"), (int, float))
+        ):
+            return None
+        release = self._read_json("releases", f"{label['hash']}.json")
+        if (
+            not isinstance(release, dict)
+            or not isinstance(release.get("body"), str)
+            or not isinstance(release.get("signature"), str)
+            or not isinstance(release.get("keyId"), str)
+            or sha256_hex(release["body"]) != label["hash"]
+        ):
+            return None
+        key = next((k for k in self.read_keys() if k["keyId"] == release["keyId"]), None)
+        if key is None or not verify_body(key["publicKey"], release["body"], release["signature"]):
+            return None
+        payload = parse_payload(release["body"])
+        if payload is None:
+            return None
+        return CachedResolution(payload, release["body"], label["etag"], label["fetchedAt"])
+
+    def write(self, label_key: str, *, body: str, signature: str, key_id: str, etag: str, now: float) -> None:
+        """Only ever called with a body whose signature has just verified."""
+        digest = sha256_hex(body)
+        self._write_json({"body": body, "signature": signature, "keyId": key_id}, "releases", f"{digest}.json")
+        self.touch(label_key, etag=etag, digest=digest, fetched_at=now)
+
+    def touch(self, label_key: str, *, etag: str, digest: str, fetched_at: float) -> None:
+        self._write_json({"etag": etag, "hash": digest, "fetchedAt": fetched_at}, "labels", f"{label_key}.json")

contexory/client.py

@@ -0,0 +1,229 @@
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .apply_tools import apply_tools as _apply_tools
+from .cache import CachedResolution, ResolveCache
+from .errors import ContexoryResolveError, ContexorySignatureError
+from .payload import parse_payload
+from .signing import parse_keys, sha256_hex, verify_body
+from .types import ResolvedTool, ResolvePayload, ResolveSource
+
+DEFAULT_BASE_URL = "https://sync.contexory.com"
+DEFAULT_LABEL = "production"
+_REFUSAL_STATUSES = (401, 403, 404)
+
+
+@dataclass
+class FetchResponse:
+    status: int
+    #: Header names lower-cased.
+    headers: Mapping[str, str]
+    body: bytes
+
+    @property
+    def ok(self) -> bool:
+        return 200 <= self.status < 300
+
+    def text(self) -> str:
+        return self.body.decode("utf8")
+
+
+#: `fetch(url, headers, timeout_seconds)`; raise on a network failure, return any HTTP status.
+Fetch = Callable[[str, Mapping[str, str], float], FetchResponse]
+
+
+def default_fetch(url: str, headers: Mapping[str, str], timeout: float) -> FetchResponse:
+    request = urllib.request.Request(url, headers=dict(headers))
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as res:  # noqa: S310 - https/http base URL
+            return FetchResponse(res.status, {k.lower(): v for k, v in res.headers.items()}, res.read())
+    except urllib.error.HTTPError as err:
+        return FetchResponse(err.code, {k.lower(): v for k, v in err.headers.items()}, err.read())
+
+
+@dataclass
+class ResolvedContext:
+    agent: Any
+    label: str
+    release: Any
+    #: The agent's system prompt for this release.
+    system: str
+    skills: list[dict[str, Any]]
+    tools: list[ResolvedTool]
+    source: ResolveSource
+    #: True when Contexory failed and this is the last good release.
+    stale: bool = False
+    #: Why the live fetch failed, when `stale`.
+    error: BaseException | None = None
+    #: Host tools the last `apply_tools` left alone because their MCP server's description changed.
+    held: list[str] = field(default_factory=list)
+    _reverse: dict[str, str] = field(default_factory=dict, repr=False)
+
+    def apply_tools(
+        self,
+        tools: Any,
+        renames: Mapping[str, str] | None = None,
+        upstream_hashes: Mapping[str, Any] | None = None,
+    ) -> Any:
+        """Apply the released tool descriptions to a dict or list of your tool objects."""
+        applied = _apply_tools(self.tools, tools, renames, upstream_hashes)
+        self._reverse.update(applied.reverse)
+        self.held = applied.held
+        return applied.tools
+
+    def original_tool_name(self, name: str) -> str:
+        """The name you registered a tool under, given the name the model called."""
+        return self._reverse.get(name, name)
+
+
+def _is_refusal(error: BaseException) -> bool:
+    return isinstance(error, ContexoryResolveError) and error.status in _REFUSAL_STATUSES
+
+
+class Contexory:
+    """Resolve the release a label points at. Never worse than the last verified release.
+
+    An unreachable or erroring Contexory serves the last verified release, marked
+    `stale`. A bad signature, or a refusal (revoked key, agent or label gone),
+    raises instead: the cache never overrides an answer.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str | None = None,
+        cache_dir: str | os.PathLike[str] | None = None,
+        ttl_ms: float = 60_000,
+        timeout_ms: float = 3_000,
+        first_fetch_timeout_ms: float = 10_000,
+        fetch: Fetch | None = None,
+        now: Callable[[], float] | None = None,
+        env: Mapping[str, str] | None = None,
+    ):
+        env = os.environ if env is None else env
+        self._api_key = api_key if api_key is not None else env.get("CONTEXORY_API_TOKEN")
+        self._fingerprint = sha256_hex(self._api_key or "")[:16]
+        self._base_url = (base_url or env.get("CONTEXORY_API_BASE") or DEFAULT_BASE_URL).rstrip("/")
+        self._ttl_ms = ttl_ms
+        self._timeout = timeout_ms / 1000
+        self._first_timeout = first_fetch_timeout_ms / 1000
+        self._fetch = fetch or default_fetch
+        self._now = now or (lambda: time.time() * 1000)
+        directory = cache_dir or env.get("CONTEXORY_CACHE_DIR") or Path.home() / ".cache" / "contexory" / "sdk"
+        self._cache = ResolveCache(directory)
+
+    def resolve(self, agent: str, label: str = DEFAULT_LABEL) -> ResolvedContext:
+        if not self._api_key:
+            raise ContexoryResolveError("No Contexory runtime key: pass api_key or set CONTEXORY_API_TOKEN")
+        label_key = sha256_hex(f"{self._base_url}\0{self._fingerprint}\0{agent}\0{label}")[:32]
+        cached = self._cache.read(label_key)
+        if cached is not None and self._now() - cached.fetched_at < self._ttl_ms:
+            return _build(cached.payload, "cache")
+        try:
+            return _build(self._fetch_release(label_key, agent, label, cached), "network")
+        except (ContexorySignatureError, ContexoryResolveError) as error:
+            if isinstance(error, ContexorySignatureError) or _is_refusal(error):
+                raise
+            return self._fall_back(cached, error)
+        except Exception as error:  # noqa: BLE001 - any transport failure is "unreachable"
+            return self._fall_back(cached, error, wrap=True)
+
+    async def aresolve(self, agent: str, label: str = DEFAULT_LABEL) -> ResolvedContext:
+        """`resolve` off the event loop, for async agents."""
+        return await asyncio.to_thread(self.resolve, agent, label)
+
+    def _fall_back(self, cached: CachedResolution | None, error: BaseException, wrap: bool = False) -> ResolvedContext:
+        if cached is not None:
+            context = _build(cached.payload, "stale-cache")
+            context.error = error
+            return context
+        if wrap:
+            raise ContexoryResolveError(f"Could not reach Contexory: {error}", cause=error) from error
+        raise error
+
+    def _get(self, path: str, timeout: float, headers: Mapping[str, str] | None = None) -> FetchResponse:
+        return self._fetch(f"{self._base_url}{path}", dict(headers or {}), timeout)
+
+    def _fetch_release(self, label_key: str, agent: str, label: str, cached: CachedResolution | None) -> ResolvePayload:
+        headers = {"Authorization": f"Bearer {self._api_key}"}
+        if cached is not None:
+            headers["If-None-Match"] = cached.etag
+        # With nothing to fall back on a timeout raises, so the request gets the longer budget.
+        budget = self._timeout if cached is not None else self._first_timeout
+        res = self._get(
+            f"/api/v1/agents/{urllib.parse.quote(agent, safe='')}/resolve?label={urllib.parse.quote(label, safe='')}",
+            budget,
+            headers,
+        )
+        if res.status == 304 and cached is not None:
+            self._cache.touch(label_key, etag=cached.etag, digest=sha256_hex(cached.body), fetched_at=self._now())
+            return cached.payload
+        if not res.ok:
+            raise ContexoryResolveError(f"Contexory resolve answered {res.status}", status=res.status)
+
+        body = res.text()
+        signature = res.headers.get("contexory-signature")
+        key_id = res.headers.get("contexory-key-id")
+        if not signature or not key_id:
+            raise ContexorySignatureError("missing")
+        key = self._key_for(key_id, budget)
+        if key is None:
+            raise ContexorySignatureError("unknown_key")
+        if not verify_body(key["publicKey"], body, signature):
+            raise ContexorySignatureError("invalid")
+
+        payload = parse_payload(body)
+        if payload is None:
+            raise ContexoryResolveError("Contexory resolve sent a payload this SDK cannot read")
+        if payload.agent.slug != agent or payload.label != label:
+            raise ContexoryResolveError("Contexory resolve answered for a different agent or label")
+        self._cache.write(
+            label_key, body=body, signature=signature, key_id=key_id, etag=res.headers.get("etag", ""), now=self._now()
+        )
+        return payload
+
+    def _key_for(self, key_id: str, budget: float) -> dict[str, str] | None:
+        """An id not seen before triggers one discovery fetch, which is how a rotation arrives.
+
+        Keys are merged, not replaced, so a release cached under the previous key still verifies.
+        """
+        known = self._cache.read_keys()
+        hit = next((k for k in known if k["keyId"] == key_id), None)
+        if hit is not None:
+            return hit
+        res = self._get("/api/v1/signing-keys", budget)
+        if not res.ok:
+            raise ContexoryResolveError(f"Contexory signing-keys answered {res.status}", status=res.status)
+        try:
+            data = json.loads(res.text())
+        except ValueError:
+            data = None
+        fetched = parse_keys(data)
+        merged = [k for k in known if not any(f["keyId"] == k["keyId"] for f in fetched)] + fetched
+        self._cache.write_keys(merged)
+        return next((k for k in merged if k["keyId"] == key_id), None)
+
+
+def _build(payload: ResolvePayload, source: ResolveSource) -> ResolvedContext:
+    return ResolvedContext(
+        agent=payload.agent,
+        label=payload.label,
+        release=payload.release,
+        system=payload.system_prompt,
+        skills=payload.skills,
+        tools=payload.tools,
+        source=source,
+        stale=source == "stale-cache",
+    )