mirrors-sdk 0.1.0__tar.gz

mirrors_sdk-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+recursive-include tests *.py
+recursive-include tests *.json

mirrors_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: mirrors-sdk
+Version: 0.1.0
+Summary: Background trace capture and bounded optional context for Python agents
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: httpx<0.29,>=0.28.1
+
+# Mirrors Python SDK
+
+Capture original conversation history in the background and retrieve optional
+context before assembling a model request. Your application keeps control of its
+system prompt, model calls, tools, streaming, errors and cancellation.
+
+Python 3.11 or later. This source package is **not yet published to PyPI**.
+Install the reviewed source locally:
+
+```sh
+python -m pip install ./packages/python-sdk
+```
+
+## Synchronous integration
+
+```python
+import os
+from uuid import uuid4
+
+from mirrors_sdk import Mirrors
+
+mirrors = Mirrors(
+    api_url=os.environ["MIRRORS_API_URL"],
+    api_key=os.environ["MIRRORS_API_KEY"],
+    agent_id=os.environ["MIRRORS_AGENT_ID"],
+)
+execution_id = str(uuid4())
+
+# Map the application's complete original history to canonical messages.
+trace = {
+    "id": execution_id,
+    "messages": [{"role": "user", "content": "Help with my account"}],
+}
+mirrors.capture_trace(trace)  # Returns immediately; do not wait before a model call.
+
+selected = mirrors.get_context(trace, timeout_ms=1000)
+system = original_system_prompt
+if selected.context:
+    system += "\n\n" + selected.context
+
+# The application's existing model call and error/stream handling stay here.
+response = existing_model_call(system=system, messages=original_messages)
+```
+
+Appending the returned text is synchronous. `get_context` is also a synchronous
+Python method, but it may wait for optional network context for **at most 1,000 ms
+from call entry**, including snapshot copying and scheduling. Use a shorter
+`timeout_ms` from 1–1000 to reduce that wait. Timing is bounded best effort, not a
+hard real-time guarantee while Python or the operating system cannot schedule work.
+It does not wait for capture delivery. No user event loop or async framework is
+required. Async applications may use `await mirrors.aget_context(trace)` to avoid
+blocking their event loop.
+
+The SDK starts its mode heartbeat in the background. Until a valid mode lease is
+available, or after it expires, retrieval immediately returns empty local shadow
+fallback. Confirmed shadow returns empty while evaluating in the background; off
+does not retrieve context. Capture continues in every server mode. A successful
+response contains `context`, `mode`, `delivery`, `reason`, `elapsed_ms` and nullable
+`freshness`; `delivery == "accepted"` means receipt, not application or model success.
+Use text promptly and check its `freshness` expiry if dispatch is delayed.
+
+Copy the URL and agent ID from the agent's SDK connection settings. Keep keys in
+server secrets with runtime read/write permissions. The SDK refuses redirects and
+requires HTTPS, except for literal loopback development addresses. It never logs
+keys, requests or conversation contents.
+
+## Original evidence and final capture
+
+Canonical messages preserve original roles (`system`, `user`, `assistant`, `tool`),
+text, reasoning, block order and tool call/result IDs. Preserve original history;
+do not include SDK context in evidence or invent missing associations. Capture
+copies accepted input so later caller mutations cannot change an admitted request.
+Oversized, cyclic, non-JSON or custom-object inputs are rejected without truncation.
+
+After the execution and its response stream have ended, capture the full final
+history:
+
+```python
+ticket = mirrors.capture_trace(
+    completed_original_trace,
+    final=True,
+    terminal="completed",  # Or "failed" / "canceled"; not a task-success label.
+)
+# Inspect outside the model path. wait() takes seconds and never waits indefinitely.
+receipt = ticket.wait(timeout=2)
+```
+
+`ticket.receipt.status` distinguishes `pending`, `accepted`, `dropped` and
+`unconfirmed`. A timeout or connection loss may follow a server commit, so
+`unconfirmed` does not mean rejected. Accepted ingestion with `status == "queued"`
+does not mean analysis has finished. Retries retain the same immutable request
+identity; there is no infinite retry loop or durable crash queue.
+
+Use a fresh execution ID after restart, finalization or `release_trace(id)`. Release
+only performs local cleanup; it does not claim server completion. For a conversation
+spanning executions, supply both canonical fields `conversationId` and
+`conversationRevision`, with a durable, atomically allocated increasing revision.
+Keep that pair and source metadata fixed throughout one execution. Optional
+`user: {"id": ..., "segment": ...}` uses opaque internal IDs, never email addresses.
+These canonical JSON field names match the TypeScript SDK and wire protocol.
+
+For whole-turn latency, call `turn = mirrors.start_turn()` at user-message acceptance
+and `turn.finish()` after the final response, including tools, streaming and retries.
+The first finish freezes monotonic milliseconds. Supply it as `turnLatencyMs` on the
+final trace only; omit unknown duration. Timing does not imply success.
+
+## Shutdown and emergency bypass
+
+```python
+# At shutdown, outside the agent's model path:
+summary = mirrors.flush(timeout_ms=2000)
+mirrors.dispose()
+```
+
+`flush` waits only for capture tickets pending when called and reports accepted,
+dropped, unconfirmed and pending counts. Its `complete` flag is true only when every
+selected ticket was accepted. `close(timeout_ms=2000)` combines a bounded flush
+and disposal. `dispose()` immediately disables optional work without waiting for
+network completion. Background threads do not keep the Python process alive, so
+process exit may abandon captures; flush explicitly when confirmation matters.
+
+`set_enabled(False)` cancels optional work and clears active state. Re-enabling
+requires fresh execution IDs. Invalid configuration stays inert and yields explicit
+fallback receipts. SDK failures do not invoke, retry or replace application model
+calls. Cancellation passed as `threading.Event` to `get_context(..., cancel=event)`
+returns a distinct canceled result; preserve the application's own cancellation
+check before invoking its provider. Async task cancellation propagates normally.
+
+## Limits and design tradeoffs
+
+| Limit | Value |
+| --- | --- |
+| Encoded snapshot | 1,000,000 bytes; 10,000 messages; 50,000 JSON nodes; depth 32 |
+| Pending captures | 16 prefixes and 16 finals, separately |
+| Active execution state / recent final receipts | 64 / 128 |
+| Pending context retrievals | 16, independent of capture |
+| Capture timeout defaults | 1 second prefix; 6 seconds final |
+| Explicit capture `timeout_ms` | 1–30,000 ms |
+| Context / response bytes | 32,768 / 65,536 |
+| Circuit default | 3 failures, 30-second cooldown, one recovery probe per endpoint |
+| Mode heartbeat / lease | 1 second with jitter / at most 3 seconds |
+
+One daemon event-loop thread and one HTTPX client own network work; at most two
+daemon DNS lookups isolate stalled system resolution. The benefit is cancellable,
+pooled HTTP for synchronous callers without a thread per upload. The cost is the
+HTTPX dependency and best-effort background delivery. Endpoint circuits
+are independent, so a successful capture cannot hide context failures. Uncertain
+captures reconcile before newer ordinals; final retries share their original budget.
+
+The package mirrors the current TypeScript `captureTrace` / `getContext` boundary.
+It does not port the legacy session adapters or ready-only injection helpers, and
+it contains no private policy engine or provider integration. Tests cover local
+protocol behavior and package installation; they do not establish PyPI publication,
+hosted service compatibility, production latency or model-quality improvement.
+
+## Development
+
+```sh
+python -m pip install ./packages/python-sdk build
+python -m unittest discover -s packages/python-sdk/tests -v
+python -m build packages/python-sdk
+```
+
+CI runs behavioral and real loopback HTTP tests on Python 3.11, 3.13 and 3.14, then
+builds and installs the wheel in a clean environment. No test calls a real provider
+or a hosted Mirrors service.

mirrors_sdk-0.1.0/README.md

@@ -0,0 +1,166 @@
+# Mirrors Python SDK
+
+Capture original conversation history in the background and retrieve optional
+context before assembling a model request. Your application keeps control of its
+system prompt, model calls, tools, streaming, errors and cancellation.
+
+Python 3.11 or later. This source package is **not yet published to PyPI**.
+Install the reviewed source locally:
+
+```sh
+python -m pip install ./packages/python-sdk
+```
+
+## Synchronous integration
+
+```python
+import os
+from uuid import uuid4
+
+from mirrors_sdk import Mirrors
+
+mirrors = Mirrors(
+    api_url=os.environ["MIRRORS_API_URL"],
+    api_key=os.environ["MIRRORS_API_KEY"],
+    agent_id=os.environ["MIRRORS_AGENT_ID"],
+)
+execution_id = str(uuid4())
+
+# Map the application's complete original history to canonical messages.
+trace = {
+    "id": execution_id,
+    "messages": [{"role": "user", "content": "Help with my account"}],
+}
+mirrors.capture_trace(trace)  # Returns immediately; do not wait before a model call.
+
+selected = mirrors.get_context(trace, timeout_ms=1000)
+system = original_system_prompt
+if selected.context:
+    system += "\n\n" + selected.context
+
+# The application's existing model call and error/stream handling stay here.
+response = existing_model_call(system=system, messages=original_messages)
+```
+
+Appending the returned text is synchronous. `get_context` is also a synchronous
+Python method, but it may wait for optional network context for **at most 1,000 ms
+from call entry**, including snapshot copying and scheduling. Use a shorter
+`timeout_ms` from 1–1000 to reduce that wait. Timing is bounded best effort, not a
+hard real-time guarantee while Python or the operating system cannot schedule work.
+It does not wait for capture delivery. No user event loop or async framework is
+required. Async applications may use `await mirrors.aget_context(trace)` to avoid
+blocking their event loop.
+
+The SDK starts its mode heartbeat in the background. Until a valid mode lease is
+available, or after it expires, retrieval immediately returns empty local shadow
+fallback. Confirmed shadow returns empty while evaluating in the background; off
+does not retrieve context. Capture continues in every server mode. A successful
+response contains `context`, `mode`, `delivery`, `reason`, `elapsed_ms` and nullable
+`freshness`; `delivery == "accepted"` means receipt, not application or model success.
+Use text promptly and check its `freshness` expiry if dispatch is delayed.
+
+Copy the URL and agent ID from the agent's SDK connection settings. Keep keys in
+server secrets with runtime read/write permissions. The SDK refuses redirects and
+requires HTTPS, except for literal loopback development addresses. It never logs
+keys, requests or conversation contents.
+
+## Original evidence and final capture
+
+Canonical messages preserve original roles (`system`, `user`, `assistant`, `tool`),
+text, reasoning, block order and tool call/result IDs. Preserve original history;
+do not include SDK context in evidence or invent missing associations. Capture
+copies accepted input so later caller mutations cannot change an admitted request.
+Oversized, cyclic, non-JSON or custom-object inputs are rejected without truncation.
+
+After the execution and its response stream have ended, capture the full final
+history:
+
+```python
+ticket = mirrors.capture_trace(
+    completed_original_trace,
+    final=True,
+    terminal="completed",  # Or "failed" / "canceled"; not a task-success label.
+)
+# Inspect outside the model path. wait() takes seconds and never waits indefinitely.
+receipt = ticket.wait(timeout=2)
+```
+
+`ticket.receipt.status` distinguishes `pending`, `accepted`, `dropped` and
+`unconfirmed`. A timeout or connection loss may follow a server commit, so
+`unconfirmed` does not mean rejected. Accepted ingestion with `status == "queued"`
+does not mean analysis has finished. Retries retain the same immutable request
+identity; there is no infinite retry loop or durable crash queue.
+
+Use a fresh execution ID after restart, finalization or `release_trace(id)`. Release
+only performs local cleanup; it does not claim server completion. For a conversation
+spanning executions, supply both canonical fields `conversationId` and
+`conversationRevision`, with a durable, atomically allocated increasing revision.
+Keep that pair and source metadata fixed throughout one execution. Optional
+`user: {"id": ..., "segment": ...}` uses opaque internal IDs, never email addresses.
+These canonical JSON field names match the TypeScript SDK and wire protocol.
+
+For whole-turn latency, call `turn = mirrors.start_turn()` at user-message acceptance
+and `turn.finish()` after the final response, including tools, streaming and retries.
+The first finish freezes monotonic milliseconds. Supply it as `turnLatencyMs` on the
+final trace only; omit unknown duration. Timing does not imply success.
+
+## Shutdown and emergency bypass
+
+```python
+# At shutdown, outside the agent's model path:
+summary = mirrors.flush(timeout_ms=2000)
+mirrors.dispose()
+```
+
+`flush` waits only for capture tickets pending when called and reports accepted,
+dropped, unconfirmed and pending counts. Its `complete` flag is true only when every
+selected ticket was accepted. `close(timeout_ms=2000)` combines a bounded flush
+and disposal. `dispose()` immediately disables optional work without waiting for
+network completion. Background threads do not keep the Python process alive, so
+process exit may abandon captures; flush explicitly when confirmation matters.
+
+`set_enabled(False)` cancels optional work and clears active state. Re-enabling
+requires fresh execution IDs. Invalid configuration stays inert and yields explicit
+fallback receipts. SDK failures do not invoke, retry or replace application model
+calls. Cancellation passed as `threading.Event` to `get_context(..., cancel=event)`
+returns a distinct canceled result; preserve the application's own cancellation
+check before invoking its provider. Async task cancellation propagates normally.
+
+## Limits and design tradeoffs
+
+| Limit | Value |
+| --- | --- |
+| Encoded snapshot | 1,000,000 bytes; 10,000 messages; 50,000 JSON nodes; depth 32 |
+| Pending captures | 16 prefixes and 16 finals, separately |
+| Active execution state / recent final receipts | 64 / 128 |
+| Pending context retrievals | 16, independent of capture |
+| Capture timeout defaults | 1 second prefix; 6 seconds final |
+| Explicit capture `timeout_ms` | 1–30,000 ms |
+| Context / response bytes | 32,768 / 65,536 |
+| Circuit default | 3 failures, 30-second cooldown, one recovery probe per endpoint |
+| Mode heartbeat / lease | 1 second with jitter / at most 3 seconds |
+
+One daemon event-loop thread and one HTTPX client own network work; at most two
+daemon DNS lookups isolate stalled system resolution. The benefit is cancellable,
+pooled HTTP for synchronous callers without a thread per upload. The cost is the
+HTTPX dependency and best-effort background delivery. Endpoint circuits
+are independent, so a successful capture cannot hide context failures. Uncertain
+captures reconcile before newer ordinals; final retries share their original budget.
+
+The package mirrors the current TypeScript `captureTrace` / `getContext` boundary.
+It does not port the legacy session adapters or ready-only injection helpers, and
+it contains no private policy engine or provider integration. Tests cover local
+protocol behavior and package installation; they do not establish PyPI publication,
+hosted service compatibility, production latency or model-quality improvement.
+
+## Development
+
+```sh
+python -m pip install ./packages/python-sdk build
+python -m unittest discover -s packages/python-sdk/tests -v
+python -m build packages/python-sdk
+```
+
+CI runs behavioral and real loopback HTTP tests on Python 3.11, 3.13 and 3.14, then
+builds and installs the wheel in a clean environment. No test calls a real provider
+or a hosted Mirrors service.

mirrors_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mirrors-sdk"
+version = "0.1.0"
+description = "Background trace capture and bounded optional context for Python agents"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = ["httpx>=0.28.1,<0.29"]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+mirrors_sdk = ["py.typed"]

mirrors_sdk-0.1.0/setup.cfg

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

mirrors_sdk-0.1.0/src/mirrors_sdk/__init__.py

@@ -0,0 +1,33 @@
+"""Mirrors: optional context and best-effort original trace capture."""
+
+from .client import Mirrors
+from .models import (
+    ContextFreshness,
+    ContextResult,
+    DeliveryReceipt,
+    DeliveryTicket,
+    FlushResult,
+    TurnTimer,
+)
+from .types import (
+    CanonicalMessage,
+    CanonicalTrace,
+    EndUser,
+    MessageBlock,
+    SourceCompleteness,
+)
+
+__all__ = [
+    "Mirrors",
+    "ContextFreshness",
+    "ContextResult",
+    "DeliveryReceipt",
+    "DeliveryTicket",
+    "FlushResult",
+    "TurnTimer",
+    "CanonicalMessage",
+    "CanonicalTrace",
+    "EndUser",
+    "MessageBlock",
+    "SourceCompleteness",
+]

mirrors_sdk-0.1.0/src/mirrors_sdk/capture.py

@@ -0,0 +1,254 @@
+"""Ordered capture delivery with immutable reconciliation of uncertain writes."""
+
+from __future__ import annotations
+
+import asyncio
+import hashlib
+import json
+import time
+import uuid
+from collections import OrderedDict
+from dataclasses import dataclass, field
+from typing import Any
+
+from .models import DeliveryReceipt
+from .transport import TransportError
+from .wire import Wire
+
+
+@dataclass(frozen=True)
+class _Pending:
+    digest: bytes
+    body: bytes
+    request: dict[str, Any]
+
+
+@dataclass
+class _Trace:
+    metadata: bytes
+    ordinal: int = 0
+    pending: _Pending | None = None
+    sealed: bool = False
+    retired: bool = False
+    lock: asyncio.Lock = field(default_factory=asyncio.Lock)
+    running: asyncio.Task[Any] | None = None
+    final_digest: bytes | None = None
+    final_owner: asyncio.Task[Any] | None = None
+
+
+class CaptureRuntime:
+    """Loop-owned state; application threads communicate through the SDK worker."""
+
+    def __init__(self, transport: Any, config: Any) -> None:
+        self._transport = transport
+        self._config = config
+        self._active: dict[str, _Trace] = {}
+        self._terminal: dict[str, _Trace] = {}
+        self._recent: OrderedDict[str, tuple[bytes, DeliveryReceipt]] = OrderedDict()
+        self._closed = False
+
+    async def send(self, input: dict[str, Any], deadline: float) -> DeliveryReceipt:
+        """Send once; finals may retry once within the same absolute deadline."""
+        receipt = await self._send(input, deadline)
+        if input.get("final") is True:
+            trace_id = input.get("trace", {}).get("id")
+            # A rejected final still ends the host execution. Release any prefix state
+            # left behind by validation/capacity rejection, preserving admitted finals.
+            self.release(trace_id)
+            state = self._terminal.get(trace_id)
+            if state is not None and state.final_owner is asyncio.current_task():
+                # Settled uncertain finals do not consume scarce terminal capacity forever.
+                # Their immutable outcome is retained in the same bounded receipt cache.
+                self._terminal.pop(trace_id, None)
+                if state.final_digest is not None:
+                    self._remember(trace_id, state.final_digest, receipt)
+                self._retire(state)
+        return receipt
+
+    async def _send(self, input: dict[str, Any], deadline: float) -> DeliveryReceipt:
+        if self._closed:
+            return DeliveryReceipt("dropped", "closed")
+        final = input.get("final") is True
+        timeout_ms = self._config.timeout_ms
+        deadline = min(
+            deadline,
+            time.monotonic() + (timeout_ms or (6000 if final else 1000)) / 1000,
+        )
+        try:
+            encoded = Wire.encode(input)
+            snapshot = json.loads(encoded)
+            trace_id = snapshot["trace"]["id"]
+            digest = hashlib.sha256(encoded).digest()
+            metadata = self._metadata(snapshot["trace"])
+        except (TypeError, ValueError, KeyError, RecursionError):
+            return DeliveryReceipt("dropped", "invalid_evidence")
+        previous = self._recent.get(trace_id)
+        if previous is not None:
+            return (
+                previous[1]
+                if previous[0] == digest
+                else DeliveryReceipt("dropped", "terminal_conflict")
+            )
+        state = self._terminal.get(trace_id) or self._active.get(trace_id)
+        if state is not None and state.metadata != metadata:
+            return DeliveryReceipt("dropped", "invalid_evidence")
+        if state is not None and state.sealed and not final:
+            return DeliveryReceipt("dropped", "terminal_conflict")
+        if state is not None and state.sealed and state.final_digest != digest:
+            return DeliveryReceipt("dropped", "terminal_conflict")
+        if state is None:
+            pool = self._terminal if final else self._active
+            if len(pool) >= (16 if final else 64):
+                return DeliveryReceipt("dropped", "capacity")
+            state = _Trace(metadata, sealed=final)
+            pool[trace_id] = state
+            if final:
+                state.final_digest = digest
+                state.final_owner = asyncio.current_task()
+        elif final and not state.sealed:
+            if len(self._terminal) >= 16:
+                return DeliveryReceipt("dropped", "capacity")
+            state.sealed = True
+            state.final_digest = digest
+            state.final_owner = asyncio.current_task()
+            self._active.pop(trace_id, None)
+            self._terminal[trace_id] = state
+        acquired = False
+        try:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                return DeliveryReceipt("unconfirmed", "timeout")
+            await asyncio.wait_for(state.lock.acquire(), remaining)
+            acquired = True
+            state.running = asyncio.current_task()
+            if state.retired or self._closed:
+                return DeliveryReceipt("dropped", "closed")
+            if state.sealed and not final:
+                return DeliveryReceipt("dropped", "superseded")
+            # Another queued final may have completed while this call waited.
+            previous = self._recent.get(trace_id)
+            if previous is not None:
+                return (
+                    previous[1]
+                    if previous[0] == digest
+                    else DeliveryReceipt("dropped", "terminal_conflict")
+                )
+            if state.pending is not None and state.pending.digest != digest:
+                # An uncertain terminal is immutable. A different final cannot replace it.
+                if state.pending.request["final"]:
+                    return DeliveryReceipt("dropped", "terminal_conflict")
+                await self._deliver(state, trace_id, deadline, retry=final)
+            if state.pending is None:
+                if state.ordinal >= 10_000:
+                    return DeliveryReceipt("dropped", "capacity")
+                request = {
+                    **snapshot,
+                    "protocol": 3,
+                    "agentId": self._config.agent_id,
+                    "requestId": str(uuid.uuid4()),
+                    "ordinal": state.ordinal + 1,
+                }
+                state.pending = _Pending(
+                    digest, Wire.encode(request, 1_048_576), request
+                )
+            return await self._deliver(state, trace_id, deadline, retry=final)
+        except asyncio.TimeoutError:
+            return DeliveryReceipt("unconfirmed", "timeout")
+        except asyncio.CancelledError:
+            return DeliveryReceipt("unconfirmed", "transport")
+        except TransportError as error:
+            return DeliveryReceipt(
+                "unconfirmed", "timeout" if error.reason == "timeout" else "transport"
+            )
+        except Exception:
+            # Optional capture must not leak protocol or transport failures into the host.
+            return DeliveryReceipt("unconfirmed", "transport")
+        finally:
+            if acquired:
+                state.running = None
+                state.lock.release()
+
+    async def _deliver(
+        self, state: _Trace, trace_id: str, deadline: float, *, retry: bool
+    ) -> DeliveryReceipt:
+        pending = state.pending
+        assert pending is not None
+        for attempt in range(2 if retry else 1):
+            if time.monotonic() >= deadline:
+                raise asyncio.TimeoutError
+            if state.retired or self._closed:
+                raise asyncio.CancelledError
+            try:
+                response = await self._transport.request(
+                    "trace",
+                    pending.body,
+                    deadline,
+                    lambda value: Wire.trace_response(value, pending.request),
+                    final_recovery=retry,
+                )
+                break
+            except TransportError as error:
+                if (
+                    error.permanent
+                    or not retry
+                    or attempt == 1
+                    or time.monotonic() >= deadline
+                ):
+                    raise
+        if state.retired or self._closed:
+            raise asyncio.CancelledError
+        if time.monotonic() >= deadline:
+            raise asyncio.TimeoutError
+        if not Wire.trace_response(response, pending.request):
+            raise ValueError("Invalid capture response")
+        state.ordinal = pending.request["ordinal"]
+        state.pending = None
+        receipt = DeliveryReceipt("accepted", ingestion=response["ingestion"])
+        if pending.request["final"]:
+            self._active.pop(trace_id, None)
+            self._terminal.pop(trace_id, None)
+            self._remember(trace_id, pending.digest, receipt)
+        return receipt
+
+    def _remember(self, trace_id: str, digest: bytes, receipt: DeliveryReceipt) -> None:
+        self._recent[trace_id] = (digest, receipt)
+        if len(self._recent) > 128:
+            self._recent.popitem(last=False)
+
+    def release(self, trace_id: str) -> None:
+        """Retire prefixes locally; an admitted final retains its delivery opportunity."""
+        state = self._active.pop(trace_id, None)
+        if state is not None:
+            self._retire(state)
+
+    def clear(self) -> None:
+        """Permanently stop capture and abandon all outstanding work."""
+        self._closed = True
+        for state in (*self._active.values(), *self._terminal.values()):
+            self._retire(state)
+        self._active.clear()
+        self._terminal.clear()
+        self._recent.clear()
+
+    @staticmethod
+    def _retire(state: _Trace) -> None:
+        state.retired = True
+        if state.running is not None:
+            state.running.cancel()
+
+    @staticmethod
+    def _metadata(trace: dict[str, Any]) -> bytes:
+        # End-user and measured duration intentionally belong to the final snapshot.
+        fields = (
+            "model",
+            "entryPoint",
+            "completeness",
+            "conversationId",
+            "conversationRevision",
+        )
+        return json.dumps(
+            {key: trace[key] for key in fields if key in trace},
+            sort_keys=True,
+            separators=(",", ":"),
+            ensure_ascii=False,
+        ).encode("utf-8")