pyfect-dev 0.1.0__py3-none-any.whl

pyfect/ai/_mcp/reverse_policy.py

@@ -0,0 +1,155 @@
+"""What a revision lets a server ask its client (Effect's per-revision
+``toReverseClient``), past the capability check every operation shares."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import assert_never, cast
+
+from pyfect.ai.mcp_protocol import AnyProtocolAdapter
+from pyfect.ai.mcp_schema import (
+    ClientCapabilities,
+    CreateMessageParams,
+    CreateMessageResult,
+    ElicitRequestParams,
+    JsonObject,
+    McpInputRequest,
+)
+
+_TOOL_CONTENT = ("tool_use", "tool_result")
+_CONTEXTS = ("thisServer", "allServers")
+
+
+def _has_tool_content(content: object) -> bool:
+    blocks = cast("list[object]", content) if isinstance(content, list) else [content]
+    return any(
+        isinstance(block, dict) and cast("dict[str, object]", block).get("type") in _TOOL_CONTENT
+        for block in blocks
+    )
+
+
+def _uses_tools(params: Mapping[str, object]) -> bool:
+    """Assumes no shape, as the input-request check runs before any decoding."""
+    if "tools" in params or "toolChoice" in params:
+        return True
+    messages = params.get("messages")
+    if not isinstance(messages, list):
+        return False
+    return any(
+        isinstance(message, Mapping)
+        and _has_tool_content(cast("Mapping[str, object]", message).get("content"))
+        for message in cast("list[object]", messages)
+    )
+
+
+def _input_fields(request: Mapping[str, object]) -> Mapping[str, object]:
+    """``request.params`` as JavaScript reads a field of it: nothing or null
+    raises, anything else that is not an object has no fields."""
+    params = request["params"]
+    if params is None:
+        raise TypeError("input request params are null")
+    return cast("Mapping[str, object]", params) if isinstance(params, Mapping) else {}
+
+
+def sampling_refusal(
+    protocol: AnyProtocolAdapter, capabilities: ClientCapabilities, params: CreateMessageParams
+) -> str | None:
+    """Why ``params`` cannot be sent, if so (Effect's per-revision
+    ``createMessage``): 2025-11-25 gates tool use and included context on
+    their nested capabilities; before it, requests with either form have no
+    wire shape."""
+    uses_tools = _uses_tools(params)
+    if protocol.supports_icons:
+        sampling = capabilities.get("sampling") or {}
+        if uses_tools and sampling.get("tools") is None:
+            return "Client did not advertise the sampling.tools capability"
+        if params.get("includeContext") in _CONTEXTS and sampling.get("context") is None:
+            return "Client did not advertise the sampling.context capability"
+        return None
+    if uses_tools or any(
+        isinstance(m["content"], list)
+        or (
+            not protocol.supports_audio
+            and cast("dict[str, object]", m["content"]).get("type") == "audio"
+        )
+        for m in params["messages"]
+    ):
+        return "Request is not representable by this protocol"
+    return None
+
+
+def sampling_result_refusal(
+    protocol: AnyProtocolAdapter, capabilities: ClientCapabilities, result: CreateMessageResult
+) -> str | None:
+    """2025-11-25: a client that did not advertise ``sampling.tools`` must
+    not answer with tool use."""
+    if not protocol.supports_icons:
+        return None
+    sampling = capabilities.get("sampling") or {}
+    uses_tools = result.get("stopReason") == "toolUse" or _has_tool_content(result["content"])
+    if uses_tools and sampling.get("tools") is None:
+        return "Client did not advertise the sampling.tools capability"
+    return None
+
+
+def project_elicitation(
+    protocol: AnyProtocolAdapter, capabilities: ClientCapabilities, params: ElicitRequestParams
+) -> ElicitRequestParams | str:
+    """``params`` as ``protocol`` sends them, or why it cannot (Effect's
+    per-revision ``elicit``): 2025-11-25 gates each mode on its nested
+    capability (an empty one is form support); 2025-06-18 has form mode
+    only, sent without its ``mode``."""
+    url = params.get("mode") == "url"
+    if protocol.supports_icons:
+        elicitation = capabilities.get("elicitation") or {}
+        supported = (
+            "url" in elicitation if url else "form" in elicitation or "url" not in elicitation
+        )
+        if not supported:
+            mode = "url" if url else "form"
+            return f"Client did not advertise the elicitation.{mode} capability"
+        return params
+    if url:
+        return "Request is not representable by this protocol"
+    return cast("ElicitRequestParams", {k: v for k, v in params.items() if k != "mode"})
+
+
+def required_input_capabilities(
+    requests: Mapping[str, McpInputRequest] | None, capabilities: ClientCapabilities
+) -> dict[str, JsonObject]:
+    """The client capabilities ``requests`` need that the client did not
+    declare (Effect's ``requiredCapabilitiesForInputRequests``). As there, it
+    sees a handler's requests before they are decoded, and raises on one it
+    cannot read."""
+    required: dict[str, JsonObject] = {}
+    for request in (requests or {}).values():
+        method = request["method"]
+        if method == "roots/list":
+            if capabilities.get("roots") is None:
+                required["roots"] = {}
+        elif method == "sampling/createMessage":
+            params = _input_fields(request)
+            advertised = capabilities.get("sampling")
+            sampling = required.get("sampling", {})
+            if _uses_tools(params) and (advertised or {}).get("tools") is None:
+                sampling["tools"] = {}
+            if (
+                params.get("includeContext") in _CONTEXTS
+                and (advertised or {}).get("context") is None
+            ):
+                sampling["context"] = {}
+            if advertised is None or sampling:
+                required["sampling"] = sampling
+        elif method == "elicitation/create":
+            mode = "url" if _input_fields(request).get("mode") == "url" else "form"
+            elicitation = capabilities.get("elicitation")
+            supported = elicitation is not None and (
+                elicitation.get("url") is not None
+                if mode == "url"
+                else elicitation.get("form") is not None or not elicitation
+            )
+            if not supported:
+                required.setdefault("elicitation", {})[mode] = {}
+        else:
+            assert_never(method)
+    return required

pyfect/ai/_mcp/routing_header.py

@@ -0,0 +1,24 @@
+"""The value encoding of 2026-07-28's HTTP routing headers (``Mcp-Name``,
+``Mcp-Param-*``)."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import re
+
+_BASE64_PREFIX = "=?base64?"
+_BASE64_SUFFIX = "?="
+_PLAIN_HEADER = re.compile(r"^[\t\x20-\x7e]*$")
+
+
+def decode_routing_header(value: str) -> str | None:
+    """A routing header's value: plain visible ASCII as is, else UTF-8
+    Base64 between ``=?base64?`` and ``?=`` (``None`` when malformed)."""
+    if not (value.startswith(_BASE64_PREFIX) and value.endswith(_BASE64_SUFFIX)):
+        return value if _PLAIN_HEADER.match(value) else None
+    encoded = value[len(_BASE64_PREFIX) : -len(_BASE64_SUFFIX)]
+    try:
+        return base64.b64decode(encoded, validate=True).decode("utf-8")
+    except (binascii.Error, UnicodeDecodeError):
+        return None

pyfect/ai/_mcp/sessions.py

@@ -0,0 +1,114 @@
+"""The Streamable HTTP transport's sessions, bounded.
+
+Any peer the Origin check admits can open a session, so the table is
+capped, a session idle past its timeout is dropped (each request renews
+it; one serving a request is kept), and the message that opens it is read
+under a size limit. Effect's table has none of these (see PARITY.md).
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+from pyfect import byte_size
+from pyfect._core import Effect
+from pyfect.ai._mcp.core import McpServerService
+from pyfect.ai._mcp.dispatch import Connection
+from pyfect.byte_size import ByteSize
+from pyfect.duration import Duration, Seconds, to_seconds
+from pyfect.effect import fail, succeed
+from pyfect.errors import IllegalArgumentError
+
+DEFAULT_MAX_SESSIONS = 1000
+DEFAULT_IDLE_TIMEOUT: Duration = 30 * 60
+DEFAULT_MAX_MESSAGE_BYTES: byte_size.Input = "4 MiB"
+
+
+@dataclass(frozen=True)
+class Limits:
+    """Parsed by ``limits``: every field is positive."""
+
+    max_sessions: int
+    idle_timeout: Seconds
+    max_message_bytes: ByteSize
+
+
+def limits(
+    max_sessions: int, idle_timeout: Duration, max_message_bytes: byte_size.Input
+) -> Effect[Limits, IllegalArgumentError]:
+    if isinstance(max_sessions, bool) or max_sessions < 1:
+        return fail(IllegalArgumentError(f"max_sessions must be at least 1, got {max_sessions!r}"))
+    timeout = to_seconds(idle_timeout)
+    if not timeout > 0:
+        return fail(
+            IllegalArgumentError(f"session_idle_timeout must be positive, got {idle_timeout!r}")
+        )
+    size = byte_size.from_input(max_message_bytes)
+    if size is None or byte_size.is_zero(size):
+        return fail(
+            IllegalArgumentError(
+                f"max_message_bytes must be a positive byte size, got {max_message_bytes!r}"
+            )
+        )
+    return succeed(Limits(max_sessions, timeout, size))
+
+
+@dataclass
+class _Entry:
+    connection: Connection
+    last_used: float
+
+
+class Table:
+    """Sessions by id. Times are the clock's monotonic seconds."""
+
+    def __init__(self, server: McpServerService, limits: Limits) -> None:
+        self._server = server
+        self.limits = limits
+        self._entries: dict[str, _Entry] = {}
+
+    def __len__(self) -> int:
+        return len(self._entries)
+
+    def _idle(self, entry: _Entry, now: float) -> bool:
+        timeout = self.limits.idle_timeout
+        return (
+            not math.isinf(timeout)
+            and now - entry.last_used > timeout
+            and not entry.connection.busy
+        )
+
+    def _drop(self, session_id: str) -> Connection:
+        connection = self._entries.pop(session_id).connection
+        self._server.disconnect(connection.client_id)
+        return connection
+
+    def sweep(self, now: float) -> list[Connection]:
+        """Drop the idle sessions; the caller closes what is returned."""
+        idle = [id for id, entry in self._entries.items() if self._idle(entry, now)]
+        return [self._drop(id) for id in idle]
+
+    def full(self) -> bool:
+        return len(self._entries) >= self.limits.max_sessions
+
+    def open(self, session_id: str, connection: Connection, now: float) -> bool:
+        """Add a session; ``False`` when the table is full."""
+        if self.full():
+            return False
+        self._entries[session_id] = _Entry(connection, now)
+        self._server.connect(connection)
+        return True
+
+    def get(self, session_id: str, now: float) -> tuple[Connection | None, Connection | None]:
+        """The live session (renewed), and the idle one it replaced, to close."""
+        entry = self._entries.get(session_id)
+        if entry is None:
+            return None, None
+        if self._idle(entry, now):
+            return None, self._drop(session_id)
+        entry.last_used = now
+        return entry.connection, None
+
+    def pop(self, session_id: str) -> Connection | None:
+        return self._drop(session_id) if session_id in self._entries else None

pyfect/ai/_mcp/stdio.py

@@ -0,0 +1,110 @@
+"""The stdio transport: one client, newline-delimited JSON-RPC on standard
+input and output."""
+
+from __future__ import annotations
+
+from typing import Any, Never, cast
+
+from pyfect import _json_text, stream
+from pyfect._concurrency import for_each
+from pyfect._core import Effect
+from pyfect._fiber import Fiber
+from pyfect._json_text import parse as parse_json_text
+from pyfect.ai._mcp import batch
+from pyfect.ai._mcp.core import McpServer
+from pyfect.ai._mcp.dispatch import Connection, ServerInfo, error_response
+from pyfect.ai.mcp_protocol import Registry
+from pyfect.ai.mcp_schema import InvalidRequest, JsonObject, ParseError
+from pyfect.effect import gen, provide_service, succeed, suspend, sync
+from pyfect.errors import Done
+from pyfect.logger import CurrentLogLevel, LogToStderr
+from pyfect.platform_error import PlatformError
+from pyfect.queue import Queue
+from pyfect.stdio import Stdio
+
+_VOID: Effect[None] = succeed(None)
+_OUTPUT_BUFFER = 8
+
+
+def _encode(message: JsonObject) -> str:
+    return _json_text.stringify(message) + "\n"
+
+
+def _await_batch(fiber: Fiber[None, Never]) -> Effect[object]:
+    return fiber.await_exit()
+
+
+def serve(info: ServerInfo, registry: Registry) -> Effect[None, PlatformError, McpServer | Stdio]:
+    """Serve the client on standard input until it ends, then let the
+    requests still running finish. Standard output carries only the
+    protocol: the console loggers write to standard error (``LogToStderr``),
+    so a logged defect cannot corrupt it."""
+
+    @gen
+    def run():
+        server = yield from McpServer()
+        io = yield from Stdio()
+        # Bounded, as in Effect's stdio protocol: a client that stops reading
+        # holds up writers, so a subscription's backlog can overflow.
+        lines = Queue[str, Done](_OUTPUT_BUFFER)
+
+        def write(message: JsonObject) -> Effect[None]:
+            return lines.offer(_encode(message)).as_void()
+
+        batches: list[Fiber[None, Never]] = []
+
+        def write_batch(replies: list[JsonObject]) -> Effect[None]:
+            return lines.offer(_encode(cast("Any", replies))).as_void()
+
+        level = yield from CurrentLogLevel()
+        connection = Connection(
+            server,
+            info,
+            registry,
+            server.next_client_id(),
+            "stdio",
+            broadcast=write,
+            default_log_level=level,
+        )
+
+        def receive(line: str) -> Effect[None]:
+            if not line.strip():
+                return _VOID
+            try:
+                message: Any = parse_json_text(line)
+            except ValueError:
+                return write(error_response(None, ParseError("Parse error")))
+            if isinstance(message, list):
+                messages = cast("list[object]", message)
+                if not batch.accepts(connection, messages):
+                    return write(
+                        error_response(None, InvalidRequest("JSON-RPC batches are not supported"))
+                    )
+                # On its own fiber: the batch may wait on answers still to be read.
+                answered = batch.answer(connection, messages, write).flat_map(
+                    lambda replies: write_batch(replies) if replies else _VOID
+                )
+                return answered.fork_daemon().map(batches.append)
+            return connection.dispatch(message, write)
+
+        writer = yield from stream.from_queue(lines).run(io.stdout()).fork()
+        server.connect(connection)
+        reading = io.stdin.decode_text().split_lines().run_for_each(receive)
+        finished = suspend(lambda: for_each(list(batches), _await_batch)).as_void()
+        serving = yield from (
+            reading.and_then(connection.drain())
+            .and_then(finished)
+            .ensuring(
+                sync(lambda: server.disconnect(connection.client_id)).and_then(connection.close())
+            )
+            .fork()
+        )
+        # A dead writer would leave every writer waiting on the bounded output. Only a writer
+        # that ended early can interrupt anything: the output ends after serving has exited.
+        yield from writer.await_exit().and_then(serving.interrupt()).fork()
+        yield from serving.await_exit()
+        yield from lines.end()
+        yield from writer.join()
+        yield from serving.join()
+
+    return run.pipe(provide_service(LogToStderr, True))

pyfect/ai/_mcp/subscriptions.py

@@ -0,0 +1,134 @@
+"""2026-07-28's ``subscriptions/listen``: one request's stream of the list
+changes and resource updates it asked for.
+
+Events reach a listener through its own bounded backlog, so a slow client
+holds up nobody else; one whose backlog overflows has its subscription ended,
+after releasing the upstream listener even while its writes stay blocked.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, Never, cast
+
+from pyfect._core import Effect
+from pyfect.ai.mcp_schema import JsonObject, RequestId, SubscriptionFilter
+from pyfect.deferred import Deferred
+from pyfect.effect import gen, provide_service
+from pyfect.exit import Success
+from pyfect.pubsub import Subscription
+from pyfect.queue import Queue
+from pyfect.scope import Scope
+
+MAX_PENDING_NOTIFICATIONS = 64
+OVERFLOW_REASON = "Pending notification limit exceeded"
+SUBSCRIPTION_ID_META = "io.modelcontextprotocol/subscriptionId"
+ACKNOWLEDGED = "notifications/subscriptions/acknowledged"
+UPDATED = "notifications/resources/updated"
+
+
+@dataclass(frozen=True, slots=True)
+class Event:
+    """A server notification a subscription may carry."""
+
+    method: str
+    params: JsonObject
+    list_change_revision: int | None = None
+    """Set on a list change: a listener ignores those at or before the
+    revision it started at, even when their delivery was deferred."""
+
+
+@dataclass(frozen=True, slots=True)
+class Presence:
+    """What the server has registered."""
+
+    tools: bool
+    resources: bool
+    prompts: bool
+
+
+def _honored(requested: SubscriptionFilter, presence: Presence) -> SubscriptionFilter:
+    """The part of ``requested`` the server can deliver."""
+    honored: SubscriptionFilter = {}
+    if presence.tools and requested.get("toolsListChanged") is True:
+        honored["toolsListChanged"] = True
+    if presence.prompts and requested.get("promptsListChanged") is True:
+        honored["promptsListChanged"] = True
+    if presence.resources and requested.get("resourcesListChanged") is True:
+        honored["resourcesListChanged"] = True
+    uris = requested.get("resourceSubscriptions")
+    if presence.resources and uris is not None:
+        honored["resourceSubscriptions"] = uris
+    return honored
+
+
+def _wanted(event: Event, honored: SubscriptionFilter, uris: frozenset[str]) -> bool:
+    match event.method:
+        case "notifications/tools/list_changed":
+            return honored.get("toolsListChanged") is True
+        case "notifications/prompts/list_changed":
+            return honored.get("promptsListChanged") is True
+        case "notifications/resources/list_changed":
+            return honored.get("resourcesListChanged") is True
+        case _:  # UPDATED
+            return event.params.get("uri") in uris
+
+
+def listen(
+    requested: SubscriptionFilter,
+    request_id: RequestId,
+    *,
+    presence: Presence,
+    list_change_revision: int,
+    subscribe: Effect[Subscription[Event], Never, Scope],
+    send: Callable[[str, JsonObject], Effect[None]],
+    terminate: Callable[[RequestId, str], Effect[None]],
+) -> Effect[None, Never, Scope]:
+    """Acknowledge ``requested``, then deliver its events through ``send``.
+    It runs until interrupted; it returns only after ``terminate`` ended a
+    subscription whose backlog overflowed."""
+    honored = _honored(requested, presence)
+    uris = frozenset(honored.get("resourceSubscriptions", ()))
+    identity: JsonObject = {SUBSCRIPTION_ID_META: request_id}
+
+    def project(event: Event) -> JsonObject:
+        meta = event.params.get("_meta")
+        # The server owns the subscription identifier, whatever the event carries.
+        params: JsonObject = {"_meta": {**(meta if isinstance(meta, dict) else {}), **identity}}
+        if event.method == UPDATED:
+            params["uri"] = event.params["uri"]
+        return params
+
+    @gen
+    def run():
+        outer = yield from Scope()
+        events_scope = yield from outer.fork()
+        events = yield from subscribe.pipe(provide_service(Scope, events_scope))
+        pending = Queue[tuple[str, JsonObject]](MAX_PENDING_NOTIFICATIONS, "dropping")
+        overflowed = Deferred[None]()
+
+        @gen
+        def watch():
+            while True:
+                event = yield from events.take()
+                revision = event.list_change_revision
+                if revision is not None and revision <= list_change_revision:
+                    continue
+                if not _wanted(event, honored, uris):
+                    continue
+                if not (yield from pending.offer((event.method, project(event)))):
+                    return
+
+        # The upstream listener goes first, even while transport writes stay blocked.
+        yield from (
+            watch.ensuring(events_scope.close(Success(None)))
+            .and_then(overflowed.succeed(None))
+            .fork_scoped()
+        )
+        yield from send(ACKNOWLEDGED, {"_meta": identity, "notifications": cast("Any", honored)})
+        deliver = pending.take().flat_map(lambda notification: send(*notification)).forever()
+        yield from deliver.race(overflowed.wait())
+        yield from terminate(request_id, OVERFLOW_REASON)
+
+    return run

pyfect/ai/_mcp/tool_schema.py

@@ -0,0 +1,35 @@
+"""The JSON Schema of a tool's parameters or result as MCP lists it
+(Effect's ``toolJsonSchema``): MCP wants an object at the root, so the
+root is compiled inline even when it has an identifier; a recursive root
+keeps its definition and the top-level ``$ref`` is resolved."""
+
+from __future__ import annotations
+
+from pyfect.ai._structured_output_json import resolve_root
+from pyfect.json_schema import Document, JsonSchema
+from pyfect.schema import Top
+from pyfect.schema._jsonschema._annotations import Options, ReferenceCandidate
+from pyfect.schema._jsonschema._compile import Compiler
+from pyfect.schema._jsonschema._references import References
+from pyfect.schema._to_codec_json import to_codec_json_asts
+
+
+def tool_json_schema(schema: Top, *, strict: bool) -> JsonSchema:
+    """``schema``'s JSON Schema, objects closed when ``strict``, its
+    definitions under ``$defs``."""
+    [node] = to_codec_json_asts([schema.__codec__().ast])
+    root = References((), None).candidate(node).ast
+
+    def policy(candidate: ReferenceCandidate) -> str | None:
+        if candidate.ast is root and candidate.occurrences == 1:
+            return None
+        return candidate.identifier
+
+    compiler = Compiler(
+        References((node,), policy), Options("error" if strict else "ignore", False, None)
+    )
+    [out], definitions = compiler.finish([compiler.recur(node, [])])
+    resolved = dict(resolve_root(Document("draft-2020-12", out, definitions)))
+    if definitions:
+        resolved["$defs"] = dict(definitions)
+    return resolved

pyfect/ai/_noul_answers.py

@@ -0,0 +1,64 @@
+"""The provider answers of a ``choice`` / ``score`` / ``noul`` response,
+the answer format Cloudflare's Clef and TypeSafe's System One share."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Literal, TypedDict
+
+from pyfect.ai import decision as D
+from pyfect.ai import decision_model as DM
+
+
+class ChoiceAnswer(TypedDict):
+    type: Literal["choice"]
+    choice: str
+    probabilities: Mapping[str, float]
+    confidence: float
+
+
+class ScoreAnswer(TypedDict):
+    type: Literal["score"]
+    score: float
+    probabilities: Mapping[str, float]
+    confidence: float
+
+
+class NoulAnswer(TypedDict):
+    type: Literal["noul"]
+    noul: float
+
+
+type Answer = ChoiceAnswer | ScoreAnswer | NoulAnswer
+
+
+def provider_answers(
+    decisions: Mapping[str, D.AnyDecision], answers: Mapping[str, Answer]
+) -> dict[str, DM.ProviderAnswer]:
+    """Each decision's answer; a score's probabilities are by level index,
+    so they are keyed by the levels' labels (an index with no level is
+    dropped)."""
+    found: dict[str, DM.ProviderAnswer] = {}
+    for key, decision in decisions.items():
+        answer = answers.get(key)
+        if answer is None:
+            continue
+        match answer["type"]:
+            case "choice":
+                found[key] = DM.ProviderClassifyAnswer(
+                    answer["choice"], answer["probabilities"], answer["confidence"]
+                )
+            case "score":
+                levels = decision.criteria if isinstance(decision, D.Rate) else ()
+                by_index = answer["probabilities"]
+                probabilities = {
+                    level.label: by_index[str(index)]
+                    for index, level in enumerate(levels)
+                    if str(index) in by_index
+                }
+                found[key] = DM.ProviderRateAnswer(
+                    answer["score"], probabilities, answer["confidence"]
+                )
+            case "noul":
+                found[key] = DM.ProviderProbabilityAnswer(answer["noul"])
+    return found