jev-mcp-python 0.1.0__py3-none-any.whl

jev_mcp/server.py

@@ -0,0 +1,176 @@
+"""MCP entry point: stdio by default, Streamable HTTP when `JEV_MCP_TRANSPORT=streamable-http`.
+
+stdout belongs to the protocol. Logging goes to stderr, and SIGINT/SIGTERM stop the
+server and exit 0 without a traceback.
+"""
+
+import contextlib
+import gc
+import logging
+import os
+import signal
+import sys
+from collections.abc import Callable, Generator, Iterable
+from importlib.metadata import version
+from typing import Any, override
+
+import anyio
+import uvicorn
+from mcp.server.mcpserver import Context, MCPServer
+from mcp.shared.exceptions import MCPError
+from mcp.types import INTERNAL_ERROR, CallToolResult, CancelledNotificationParams, NotificationParams, Tool
+
+from jev_mcp.errors import RedactingFilter, Redactor
+from jev_mcp.serialize import stringify
+from jev_mcp.settings import LogLevel, Settings, load_settings
+from jev_mcp.stdio import stdio_streams
+from jev_mcp.tools import TOOLS, Runtime, Toolset
+
+SERVER_NAME = "jev-mcp"
+DISTRIBUTION = "jev-mcp-python"
+
+logger = logging.getLogger("jev_mcp")
+
+NULL_ARGUMENTS = stringify(
+    [
+        {
+            "expected": "record",
+            "code": "invalid_type",
+            "path": ["params", "arguments"],
+            "message": "Invalid input: expected record, received null",
+        }
+    ]
+)
+"""The TS SDK's text for `"arguments": null`: its request schema's zod issues, as a -32603."""
+
+
+class JevMCPServer(MCPServer):
+    """`MCPServer` whose `tools/list` and `tools/call` both go through one `Toolset` (ADR-0013).
+
+    The decorator path derives schemas from Python signatures: it adds `title` keys, an
+    `outputSchema`, and never emits `execution`, so it cannot reproduce the TS snapshot
+    (ADR-0006, ADR-0010). The Toolset is the single registry: what it publishes is what it
+    dispatches, and it returns the reference's result shapes itself.
+    """
+
+    def __init__(self, *, toolset: Toolset, log_level: LogLevel) -> None:
+        super().__init__(name=SERVER_NAME, version=version(DISTRIBUTION), log_level=log_level)
+        self.toolset = toolset
+        # The SDK acts on both before any handler runs (the dispatcher cancels the request, the
+        # runner marks the session initialized); without a handler it logs each as unhandled.
+        self._lowlevel_server.add_notification_handler(
+            "notifications/cancelled", CancelledNotificationParams, _already_handled
+        )
+        self._lowlevel_server.add_notification_handler(
+            "notifications/initialized", NotificationParams, _already_handled
+        )
+
+    @override
+    async def list_tools(self) -> list[Tool]:
+        return self.toolset.definitions()
+
+    @override
+    async def call_tool(
+        self, name: str, arguments: dict[str, Any], context: Context[Any, Any] | None = None
+    ) -> CallToolResult:
+        # The SDK hands a missing or null `arguments` over as `{}`. The raw params tell them apart:
+        # the reference validates a missing one as `undefined`, which reports the root instead of each
+        # required field, and its request schema rejects null before any tool.
+        params = {} if context is None else context.request_context.params or {}
+        if "arguments" in params and params["arguments"] is None:
+            raise MCPError(code=INTERNAL_ERROR, message=NULL_ARGUMENTS)
+        sent = context is None or "arguments" in params
+        return await self.toolset.call(name, arguments if sent else None)
+
+    async def run_stdio_async(self) -> None:
+        """The SDK's stdio loop over this server's own transport (`jev_mcp.stdio`)."""
+        async with stdio_streams() as (read_stream, write_stream):
+            lowlevel = self._lowlevel_server
+            await lowlevel.run(read_stream, write_stream, lowlevel.create_initialization_options())
+
+
+async def _already_handled(ctx: object, params: object) -> None:
+    return None
+
+
+def build_server(settings: Settings) -> JevMCPServer:
+    """The server with every tool; `tools/list` and `tools/call` share the Toolset's one registry."""
+    return JevMCPServer(toolset=Toolset(Runtime(settings), TOOLS), log_level=settings.log_level)
+
+
+def configure_logging(level: LogLevel, secrets: Iterable[str] = ()) -> None:
+    """Log to stderr. Every record, from any logger, is redacted of `secrets` first (ADR-0008)."""
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(logging.Formatter("%(asctime)s %(levelname)s %(name)s: %(message)s"))
+    handler.addFilter(RedactingFilter(Redactor(secrets)))
+    root = logging.getLogger()
+    root.handlers[:] = [handler]
+    root.setLevel(level)
+
+
+class _UvicornServer(uvicorn.Server):
+    """Leaves signals to `serve`, which owns them for both transports."""
+
+    @contextlib.contextmanager
+    def capture_signals(self) -> Generator[None]:
+        yield
+
+
+async def _stop_on_signal(stop: Callable[[], None]) -> None:
+    with anyio.open_signal_receiver(signal.SIGINT, signal.SIGTERM) as signals:
+        async for signum in signals:
+            logger.info("received %s, shutting down", signal.Signals(signum).name)
+            stop()
+            return
+
+
+async def serve(server: JevMCPServer, settings: Settings) -> None:
+    try:
+        await _serve(server, settings)
+    finally:
+        with anyio.CancelScope(shield=True):
+            await server.toolset.aclose()
+
+
+async def _serve(server: JevMCPServer, settings: Settings) -> None:
+    async with anyio.create_task_group() as tg:
+        if settings.transport == "stdio":
+            tg.start_soon(_stop_on_signal, tg.cancel_scope.cancel)
+            await server.run_stdio_async()
+        else:
+            app = server.streamable_http_app(host=settings.http_host)
+            # log_config=None: uvicorn's loggers propagate to the stderr root handler.
+            config = uvicorn.Config(app, host=settings.http_host, port=settings.http_port, log_config=None)
+            http = _UvicornServer(config)
+
+            def stop() -> None:
+                http.should_exit = True
+
+            tg.start_soon(_stop_on_signal, stop)
+            await http.serve()
+        tg.cancel_scope.cancel()
+
+
+def freeze_startup_heap() -> None:
+    """Move everything allocated so far (modules, schemas, the toolset) out of the collector's reach.
+
+    None of it becomes garbage, and a full collection that rescans it pauses every in-flight call
+    for 10-15 ms, which alone breaks the P9 p95 budget at 64 concurrent calls (`make load`).
+    """
+    gc.collect()
+    gc.freeze()
+
+
+def main() -> None:
+    settings = load_settings()
+    configure_logging(settings.log_level, settings.secret_values())
+    server = build_server(settings)
+    freeze_startup_heap()
+    anyio.run(serve, server, settings)
+    # A stdin read abandoned at shutdown still blocks one of anyio's non-daemon worker threads, and
+    # interpreter exit would join it until the client closes stdin. `serve` has already closed
+    # everything the server owns, so flush and leave without joining it.
+    logging.shutdown()
+    sys.stdout.flush()
+    sys.stderr.flush()
+    os._exit(0)

jev_mcp/settings.py

@@ -0,0 +1,73 @@
+"""Process configuration, read once from the environment at startup (ADR-0008).
+
+The environment is the only source: no `.env` file, no secrets dir, no constructor
+overrides, no CLI flags. Provider variables keep the reference's names exactly, so
+each field carries its own alias and there is no prefix. Values are kept raw;
+provider resolution and the model default belong to the resolver (P4).
+"""
+
+from typing import Literal, cast, get_args
+
+from pydantic import Field, SecretStr
+from pydantic_settings import BaseSettings, PydanticBaseSettingsSource, SettingsConfigDict
+
+Transport = Literal["stdio", "streamable-http"]
+LogLevel = Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(case_sensitive=True, extra="ignore", frozen=True)
+
+    # Provider selection and model (reference names; resolved in P4).
+    jev_provider: str = Field(default="auto", validation_alias="JEV_PROVIDER")
+    jev_mcp_model: str | None = Field(default=None, validation_alias="JEV_MCP_MODEL")
+
+    # Credentials and endpoints. Base URLs are secrets too: they can carry userinfo (ADR-0008).
+    typesafe_api_key: SecretStr | None = Field(default=None, validation_alias="TYPESAFE_API_KEY")
+    typesafe_base_url: SecretStr | None = Field(default=None, validation_alias="TYPESAFE_BASE_URL")
+    openrouter_api_key: SecretStr | None = Field(default=None, validation_alias="OPENROUTER_API_KEY")
+    jev_cloudflare_api_token: SecretStr | None = Field(default=None, validation_alias="JEV_CLOUDFLARE_API_TOKEN")
+    cloudflare_api_token: SecretStr | None = Field(default=None, validation_alias="CLOUDFLARE_API_TOKEN")
+    cloudflare_account_id: str | None = Field(default=None, validation_alias="CLOUDFLARE_ACCOUNT_ID")
+    ai_gateway_api_key: SecretStr | None = Field(default=None, validation_alias="AI_GATEWAY_API_KEY")
+    jev_api_key: SecretStr | None = Field(default=None, validation_alias="JEV_API_KEY")
+    jev_api_base_url: SecretStr | None = Field(default=None, validation_alias="JEV_API_BASE_URL")
+
+    # Python-only process settings; the reference is stdio-only.
+    transport: Transport = Field(default="stdio", validation_alias="JEV_MCP_TRANSPORT")
+    http_host: str = Field(default="127.0.0.1", validation_alias="JEV_MCP_HTTP_HOST")
+    http_port: int = Field(default=8000, ge=1, le=65535, validation_alias="JEV_MCP_HTTP_PORT")
+    log_level: LogLevel = Field(default="INFO", validation_alias="JEV_MCP_LOG_LEVEL")
+    # Debug only: let telemetry spans record payload text (arguments, results, patterns). Off by default.
+    telemetry_payloads: bool = Field(default=False, validation_alias="JEV_MCP_TELEMETRY_PAYLOADS")
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        return (env_settings,)
+
+    def secret_values(self) -> list[str]:
+        """Every configured secret value, for redaction — derived from the schema (ADR-0008, ADR-0017).
+
+        Every `SecretStr` field participates, so a new credential cannot be forgotten; the naming
+        guard in `tests/unit/test_settings.py` fails if a credential-named field is not `SecretStr`.
+        """
+        values: list[str] = []
+        for name, field in type(self).model_fields.items():
+            annotation = field.annotation
+            if annotation is not SecretStr and SecretStr not in get_args(annotation):
+                continue
+            secret = cast("SecretStr | None", getattr(self, name))
+            if secret is not None:
+                values.append(secret.get_secret_value())
+        return values
+
+
+def load_settings() -> Settings:
+    return Settings()

jev_mcp/stdio.py

@@ -0,0 +1,99 @@
+"""The stdio transport: newline-delimited JSON-RPC on stdin and stdout, as the reference's SDK speaks it.
+
+It replaces the SDK's `stdio_server` for what that one cannot do:
+
+- `JSON.parse` accepts a lone surrogate escape (`"\\ud83d"`) and keeps it. The SDK's parser (jiter)
+  rejected the whole line, so the request got no reply; it also accepts `NaN` and `Infinity`, which
+  `JSON.parse` rejects. Lines are read with `decode_json` instead, which keeps a lone surrogate as one
+  code point, with those constants refused.
+- `JSON.stringify` writes a lone surrogate as a `\\udxxx` escape. pydantic cannot encode one, and the
+  SDK's writer would fail on the first reply that echoes it; such a frame goes through `stringify_compact`.
+- The stdin read runs in a thread that shutdown can abandon: a blocked `readline()` would otherwise
+  hold the server open after a signal.
+
+Undecodable input bytes still become U+FFFD, as Node's `Buffer.toString('utf8')` makes them in the
+reference. While serving, fd 1 points at stderr so stray writes by handlers or children miss the wire.
+The streams are plain anyio memory streams, not the SDK's context-carrying ones: a stdin reader has
+no per-message contextvars to hand over, and the dispatcher then runs handlers in its own context.
+"""
+
+import contextlib
+import os
+import sys
+from collections.abc import AsyncGenerator, Generator
+from io import TextIOWrapper
+from typing import BinaryIO
+
+import anyio
+import anyio.to_thread
+from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
+from mcp.shared.message import SessionMessage
+from mcp.types import JSONRPCMessage, jsonrpc_message_adapter
+from pydantic_core import PydanticSerializationError
+
+from jev_mcp.domain import decode_json
+from jev_mcp.serialize import stringify_compact
+
+type Streams = tuple[MemoryObjectReceiveStream[SessionMessage | Exception], MemoryObjectSendStream[SessionMessage]]
+
+
+def parse_line(line: str) -> SessionMessage | Exception:
+    """One JSON-RPC message read as `JSON.parse` reads it, or the error for the dispatcher to drop."""
+    try:
+        value = decode_json(line)
+        return SessionMessage(jsonrpc_message_adapter.validate_python(value, by_name=False))
+    except (ValueError, RecursionError) as error:  # a pydantic ValidationError is a ValueError
+        return error
+
+
+def encode_frame(message: JSONRPCMessage) -> str:
+    """The message as one JSON line's text, with any lone surrogate escaped as `JSON.stringify` does."""
+    try:
+        return message.model_dump_json(by_alias=True, exclude_unset=True)
+    except PydanticSerializationError:
+        return stringify_compact(message.model_dump(mode="json", by_alias=True, exclude_unset=True))
+
+
+class _AbandonableLines(anyio.AsyncFile[str]):
+    async def readline(self) -> str:
+        return await anyio.to_thread.run_sync(self.wrapped.readline, abandon_on_cancel=True)
+
+
+@contextlib.asynccontextmanager
+async def stdio_streams() -> AsyncGenerator[Streams]:
+    """Read and write streams for `Server.run` over the process's stdin and stdout."""
+    stdin = _AbandonableLines(TextIOWrapper(sys.stdin.buffer, encoding="utf-8", errors="replace"))
+    with _claim_stdout() as wire:
+        stdout = anyio.wrap_file(TextIOWrapper(wire, encoding="utf-8"))
+        read_writer, read_stream = anyio.create_memory_object_stream[SessionMessage | Exception](0)
+        write_stream, write_reader = anyio.create_memory_object_stream[SessionMessage](0)
+
+        async def read() -> None:
+            async with read_writer:
+                async for line in stdin:
+                    await read_writer.send(parse_line(line))
+
+        async def write() -> None:
+            async with write_reader:
+                async for session_message in write_reader:
+                    await stdout.write(encode_frame(session_message.message) + "\n")
+                    await stdout.flush()
+
+        async with anyio.create_task_group() as tg:
+            tg.start_soon(read)
+            tg.start_soon(write)
+            yield read_stream, write_stream
+
+
+@contextlib.contextmanager
+def _claim_stdout() -> Generator[BinaryIO]:
+    """The wire on a private descriptor while fd 1 points at stderr; fd 1 is restored on exit."""
+    sys.stdout.flush()
+    private = os.dup(1)
+    os.dup2(2, 1)
+    try:
+        with os.fdopen(private, "wb", closefd=False) as wire:
+            yield wire
+    finally:
+        os.dup2(private, 1)
+        os.close(private)

jev_mcp/telemetry.py

@@ -0,0 +1,223 @@
+"""In-process spans and metrics (ROADMAP P9). Nothing here writes to stdout or the wire.
+
+A span carries its name, a duration, and attributes that are counts, flags, or enumerated labels —
+never evidence, claims, diffs, candidate text, or keys. Payload text is recorded only when the
+`JEV_MCP_TELEMETRY_PAYLOADS` debug flag is on, and only into the span's separate `payloads`.
+
+Every finished span goes to two sinks: `SpanLog` keeps recent spans and logs each one at DEBUG
+(stderr, through the redacting handler), and `Metrics` folds it into counters and duration
+histograms. The span tree follows the call: `mcp.tool` is the root, and `jev.evaluate`,
+`jev.validate`, `jev.policy`, and `regex.extract` open under it through a context variable, so the
+pure layers stay free of any recorder.
+"""
+
+import logging
+import math
+from bisect import bisect_left
+from collections import deque
+from collections.abc import Callable
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from time import perf_counter
+from types import TracebackType
+from typing import Final, Literal, Protocol
+
+type SpanName = Literal["mcp.tool", "jev.evaluate", "jev.validate", "jev.policy", "regex.extract"]
+type Attribute = bool | int | float | str
+
+logger = logging.getLogger("jev_mcp.telemetry")
+
+
+@dataclass(slots=True, eq=False)
+class Span:
+    """One timed step. `duration` is in seconds; `payloads` stays empty unless the debug flag is on."""
+
+    name: SpanName
+    attributes: dict[str, Attribute]
+    parent: "Span | None" = None
+    duration: float = 0.0
+    payloads: dict[str, str] = field(default_factory=dict[str, str])
+
+
+class SpanSink(Protocol):
+    def record(self, span: Span) -> None: ...
+
+
+class SpanLog:
+    """The most recent finished spans, oldest first. Each is also logged at DEBUG."""
+
+    def __init__(self, capacity: int = 1024) -> None:
+        self.spans: deque[Span] = deque(maxlen=capacity)
+
+    def record(self, span: Span) -> None:
+        self.spans.append(span)
+        if logger.isEnabledFor(logging.DEBUG):
+            logger.debug("span %s", describe(span))
+
+
+def describe(span: Span) -> str:
+    """`name duration_ms k=v ...`, payloads last. The log handler redacts configured secrets."""
+    parts = [span.name, f"{span.duration * 1000:.3f}ms"]
+    parts += [f"{key}={value}" for key, value in span.attributes.items()]
+    parts += [f"{key}={value!r}" for key, value in span.payloads.items()]
+    return " ".join(parts)
+
+
+DURATION_BUCKETS_MS: Final = (0.1, 0.5, 1.0, 2.5, 5.0, 10.0, 20.0, 50.0, 100.0, 250.0, 1000.0, 5000.0, math.inf)
+ACTIONS: Final = ("auto", "review", "escalate")
+CAP_SCOPES: Final = ("context", "item")
+
+
+class Metrics:
+    """Counters and per-span duration histograms, keyed Prometheus-style: `name{label="value"}`.
+
+    - `calls{tool}` and `outcomes{tool,outcome}` per `mcp.tool`. `actions{action}` counts each
+      call's one headline auto/review/escalate Action (a call with none adds nothing);
+      `item_actions{tool,action}` counts the per-item Actions of verify, classify and extract.
+      `truncated{scope}` counts calls that cut a document the judgment is made over (`context`)
+      or a candidate's or class's own text (`item`, telemetry only), per `validation/caps.py`.
+    - `provider_errors{error}` and `tokens{direction}` per `jev.evaluate`.
+    - `fail_closed{kind}` counts answers validation rejected.
+    - `regex_timeouts` counts patterns that ran out of time.
+    - `duration_ms_bucket{span,le}` (cumulative), `duration_ms_sum{span}`, `duration_ms_count{span}`.
+    """
+
+    def __init__(self) -> None:
+        self._values: dict[str, float] = {}
+        self._durations: dict[SpanName, _Histogram] = {}
+
+    def record(self, span: Span) -> None:
+        attributes = span.attributes
+        match span.name:
+            case "mcp.tool":
+                self._add(f'calls{{tool="{attributes["tool"]}"}}')
+                self._add(f'outcomes{{tool="{attributes["tool"]}",outcome="{attributes.get("outcome", "none")}"}}')
+                headline = attributes.get("action")
+                for action in ACTIONS:
+                    self._add(f'actions{{action="{action}"}}', int(headline == action))
+                    items = _number(attributes.get(f"item_actions.{action}", 0))
+                    if items:
+                        self._add(f'item_actions{{tool="{attributes["tool"]}",action="{action}"}}', items)
+                for scope in CAP_SCOPES:
+                    if attributes.get(f"truncated.{scope}") is True:
+                        self._add(f'truncated{{scope="{scope}"}}')
+            case "jev.evaluate":
+                if "error" in attributes:
+                    self._add(f'provider_errors{{error="{attributes["error"]}"}}')
+                self._add('tokens{direction="input"}', _number(attributes.get("input_tokens", 0)))
+                self._add('tokens{direction="output"}', _number(attributes.get("output_tokens", 0)))
+            case "jev.validate":
+                if attributes.get("valid") is False:
+                    self._add(f'fail_closed{{kind="{attributes["kind"]}"}}')
+            case "regex.extract":
+                if attributes.get("outcome") == "timeout":
+                    self._add("regex_timeouts")
+            case "jev.policy":
+                pass
+        self._observe(span.name, span.duration * 1000)
+
+    def _add(self, key: str, amount: float = 1) -> None:
+        self._values[key] = self._values.get(key, 0) + amount
+
+    def _observe(self, name: SpanName, ms: float) -> None:
+        histogram = self._durations.get(name)
+        if histogram is None:
+            histogram = self._durations[name] = _Histogram()
+        histogram.observe(ms)
+
+    def snapshot(self) -> dict[str, float]:
+        values = dict(self._values)
+        for name, histogram in self._durations.items():
+            cumulative = 0
+            for bound, count in zip(DURATION_BUCKETS_MS, histogram.counts, strict=True):
+                cumulative += count
+                if cumulative:
+                    le = "+Inf" if bound == math.inf else f"{bound:g}"
+                    values[f'duration_ms_bucket{{span="{name}",le="{le}"}}'] = cumulative
+            values[f'duration_ms_sum{{span="{name}"}}'] = histogram.total
+            values[f'duration_ms_count{{span="{name}"}}'] = histogram.count
+        return dict(sorted(values.items()))
+
+
+class _Histogram:
+    """Per-bucket counts, cumulated only at snapshot time: observing is one bisect and three adds."""
+
+    __slots__ = ("count", "counts", "total")
+
+    def __init__(self) -> None:
+        self.counts = [0] * len(DURATION_BUCKETS_MS)
+        self.total = 0.0
+        self.count = 0
+
+    def observe(self, ms: float) -> None:
+        self.counts[bisect_left(DURATION_BUCKETS_MS, ms)] += 1
+        self.total += ms
+        self.count += 1
+
+
+def _number(value: Attribute) -> float:
+    return value if isinstance(value, int | float) and not isinstance(value, bool) else 0
+
+
+_active: ContextVar[tuple["Telemetry", Span] | None] = ContextVar("jev_mcp_telemetry_span", default=None)
+
+
+class Telemetry:
+    """A server's recorder: opens spans and hands each finished one to the span log and metrics."""
+
+    def __init__(self, *, payloads: bool = False, capacity: int = 1024) -> None:
+        self.payloads = payloads
+        """The debug flag: whether spans may record payload text."""
+        self.spans = SpanLog(capacity)
+        self.metrics = Metrics()
+        self._sinks: tuple[SpanSink, ...] = (self.spans, self.metrics)
+
+    def span(self, name: SpanName, **attributes: Attribute) -> "_Scope":
+        """Time a `with` block as a child of the active span. An escaping exception is named, never quoted."""
+        return _Scope(self, name, attributes)
+
+    def record(self, span: Span) -> None:
+        for sink in self._sinks:
+            sink.record(span)
+
+    def payload(self, span: Span, key: str, text: Callable[[], str]) -> None:
+        """Record payload text on `span` only under the debug flag; `text` is not called otherwise."""
+        if self.payloads:
+            span.payloads[key] = text()
+
+
+class _Scope:
+    """The `with` block behind a span; a class rather than a generator, as spans sit on the hot path."""
+
+    __slots__ = ("_start", "_telemetry", "_token", "span")
+
+    def __init__(self, telemetry: Telemetry | None, name: SpanName, attributes: dict[str, Attribute]) -> None:
+        self._telemetry = telemetry
+        self.span = Span(name, attributes)
+
+    def __enter__(self) -> Span:
+        if self._telemetry is not None:
+            active = _active.get()
+            self.span.parent = None if active is None else active[1]
+            self._token = _active.set((self._telemetry, self.span))
+            self._start = perf_counter()
+        return self.span
+
+    def __exit__(self, kind: type[BaseException] | None, error: BaseException | None, _: TracebackType | None) -> None:
+        if self._telemetry is None:
+            return
+        span = self.span
+        span.duration = perf_counter() - self._start
+        _active.reset(self._token)
+        if kind is not None:
+            if issubclass(kind, Exception):
+                span.attributes["error"] = kind.__name__
+            else:
+                span.attributes["cancelled"] = True
+        self._telemetry.record(span)
+
+
+def span(name: SpanName, **attributes: Attribute) -> _Scope:
+    """A child of the active span, recorded by its telemetry. Outside any span, nothing is recorded."""
+    active = _active.get()
+    return _Scope(None if active is None else active[0], name, attributes)

jev_mcp/text.py

@@ -0,0 +1,42 @@
+"""UTF-16 `length` and `truncate` (ADR-0005).
+
+Every cap in the reference is a JS `.length`, which counts UTF-16 code units. An astral
+character (U+10000 and up) is two units there and one code point in Python.
+"""
+
+TRUNCATION_MARKER = " […truncated]"
+
+_HIGH_SURROGATES = range(0xD800, 0xDC00)
+_LOW_SURROGATES = range(0xDC00, 0xE000)
+
+
+def length(text: str) -> int:
+    """JS `text.length`: the number of UTF-16 code units. Lone surrogates count as one unit."""
+    return len(text.encode("utf-16-le", "surrogatepass")) // 2
+
+
+def truncate(text: str, max_units: int) -> str:
+    """JS `truncate` (`lib.ts:47-50`) measured in UTF-16 code units.
+
+    When the cut splits a surrogate pair, the reference keeps the lone high surrogate (quirk Q8);
+    this drops it instead, so the result is one unit shorter (ADR-0005). A lone surrogate already
+    present in `text` is not a split pair and is kept.
+    """
+    if length(text) <= max_units:
+        return text
+    return head(text, max_units) + TRUNCATION_MARKER
+
+
+def head(text: str, max_units: int) -> str:
+    """JS `text.slice(0, max_units)`, except that a split surrogate pair is dropped whole (ADR-0005)."""
+    units = 0
+    cut = 0
+    for index, char in enumerate(text):
+        units += 2 if ord(char) > 0xFFFF else 1
+        if units > max_units:
+            break  # an astral character straddling the cut is the split pair: keep none of it
+        cut = index + 1
+    result = text[:cut]
+    if result and ord(result[-1]) in _HIGH_SURROGATES and cut < len(text) and ord(text[cut]) in _LOW_SURROGATES:
+        result = result[:-1]  # a pair held as two code points is split the same way
+    return result

jev_mcp/tools/__init__.py

@@ -0,0 +1,20 @@
+"""The Jev MCP tools, published in the reference's registration order (`parity-manifest.json` `tools_list_order`)."""
+
+from jev_mcp.tools import classify, compare, decide, extract, find, gate, rerank, review, screen, verify
+from jev_mcp.tools.base import JevTool, Runtime, ToolError, ToolResult
+from jev_mcp.tools.toolset import Toolset
+
+TOOLS: tuple[JevTool, ...] = (
+    verify.TOOL,
+    screen.TOOL,
+    find.TOOL,
+    classify.TOOL,
+    decide.TOOL,
+    rerank.TOOL,
+    compare.TOOL,
+    extract.TOOL,
+    review.TOOL,
+    gate.TOOL,
+)
+
+__all__ = ["TOOLS", "JevTool", "Runtime", "ToolError", "ToolResult", "Toolset"]