rlmness-cli 0.2.0__py3-none-any.whl

rlmagent/model/external/cli.py

@@ -0,0 +1,248 @@
+"""Coding agents as models: Claude Code and Codex through their own CLIs, others through ACP."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import re
+import shutil
+import signal
+import subprocess
+import sys
+import tempfile
+import uuid
+from collections.abc import AsyncIterator, Sequence
+from pathlib import Path
+
+from rlmagent.harness.contracts.tooling import CancelToken, ToolSpec
+from rlmagent.harness.contracts.transcript import (
+    CallBlock,
+    CostBreakdown,
+    ModelEntry,
+    TextSegment,
+    TranscriptEntry,
+    UsageStats,
+)
+from rlmagent.harness.provider.wire import (
+    CallCloseEvent,
+    StreamCloseEvent,
+    StreamFaultEvent,
+    WireEvent,
+)
+from rlmagent.model.external import acp
+from rlmagent.model.external.acp import Cancelled as _Cancelled
+from rlmagent.model.external.textcalls import PROTOCOL, parse_reply, render
+
+PREFIXES = ("cli:", "acp:")
+
+# Some models answer in their own tool-call markup instead of a python block.
+FAKE_CALL = re.compile(r"<(function_calls|invoke|parameter|tool_use|tool_call)\b")
+CORRECTION = ("That tool-call markup does nothing here and nothing ran. To run code, reply "
+              "with one ```python block.")
+
+
+def _add(a: UsageStats, b: UsageStats) -> UsageStats:
+    fields = ("total_tokens", "input", "output", "cache_read", "cache_write")
+    return UsageStats(**{f: getattr(a, f) + getattr(b, f) for f in fields},
+                      cost=CostBreakdown(total=a.cost.total + b.cost.total))
+
+
+def is_external(model: str | None) -> bool:
+    return bool(model) and model.startswith(PREFIXES)
+
+
+def parse_model(model: str) -> tuple[str, str, str | None]:
+    """`cli:codex?model=gpt-5.5` -> ("cli", "codex", "gpt-5.5")."""
+    route, _, rest = model.partition(":")
+    name, _, query = rest.partition("?")
+    sub = dict(p.partition("=")[::2] for p in query.split("&") if p).get("model") or None
+    known = PRESETS if route == "cli" else acp.agents()
+    if name not in known:
+        raise ValueError(f"unknown agent {name!r} in {model!r}; known: {', '.join(known)}")
+    return route, name, sub
+
+
+def kill_tree(proc) -> None:
+    """Stop the process and anything it started (npx starts node, for one)."""
+    if proc.returncode is not None:
+        return
+    if sys.platform == "win32":
+        subprocess.run(["taskkill", "/T", "/F", "/PID", str(proc.pid)], capture_output=True)
+        return
+    try:
+        if os.getpgid(proc.pid) == proc.pid:
+            os.killpg(proc.pid, signal.SIGKILL)  # it leads its own group: see own_group()
+        else:
+            proc.kill()
+    except ProcessLookupError:
+        pass  # it ended by itself just now; nothing is left to stop
+
+
+def own_group() -> dict:
+    """Spawn option giving a process its own group, so kill_tree reaches what it starts."""
+    return {} if sys.platform == "win32" else {"start_new_session": True}
+
+
+def _exe(name: str) -> str:
+    found = shutil.which(name)
+    if found is None:
+        raise ValueError(f"{name} not found on PATH")
+    return found
+
+
+def _claude(sub: str | None, system: str, prompt: str, cwd: Path) -> tuple[list[str], str]:
+    (cwd / "system.md").write_text(system, encoding="utf-8")
+    argv = [_exe("claude"), "-p", "--output-format", "json",
+            "--system-prompt-file", str(cwd / "system.md"),
+            "--tools", "", "--strict-mcp-config", "--setting-sources", "project",
+            "--no-session-persistence"]
+    return argv + (["--model", sub] if sub else []), prompt
+
+
+_CODEX_TOOLS = ("shell_tool", "unified_exec", "code_mode_host", "view_image", "browser_use",
+                "computer_use", "apps", "tool_suggest", "sleep_tool", "multi_agent", "goals",
+                "image_generation")
+
+
+def _codex(sub: str | None, system: str, prompt: str, cwd: Path) -> tuple[list[str], str]:
+    argv = [_exe("codex"), "exec", "--json", "--sandbox", "read-only",
+            "--skip-git-repo-check", "--ephemeral", "--ignore-user-config", "-C", str(cwd),
+            "-c", "web_search=disabled"]
+    for feature in _CODEX_TOOLS:
+        argv += ["--disable", feature]
+    return argv + (["-m", sub] if sub else []) + ["-"], f"{system}\n\n{prompt}"
+
+
+def _usage(**kw) -> UsageStats:
+    total = sum(kw.get(k, 0) for k in ("input", "output", "cache_read", "cache_write"))
+    return UsageStats(total_tokens=total, **kw)
+
+
+def parse_claude(out: str) -> tuple[str, UsageStats]:
+    lines = [line for line in out.splitlines() if line.strip()]
+    if not lines:
+        raise ValueError("claude printed nothing")
+    data = json.loads(lines[-1])
+    if data.get("is_error") or data.get("subtype") != "success":
+        raise ValueError(f"claude failed: {data.get('result') or data.get('subtype')}")
+    u = data.get("usage", {})
+    usage = _usage(input=u.get("input_tokens", 0), output=u.get("output_tokens", 0),
+                   cache_read=u.get("cache_read_input_tokens", 0),
+                   cache_write=u.get("cache_creation_input_tokens", 0),
+                   cost=CostBreakdown(total=float(data.get("total_cost_usd") or 0.0)))
+    return str(data.get("result", "")), usage
+
+
+def parse_codex(out: str) -> tuple[str, UsageStats]:
+    texts, usage = [], UsageStats()
+    for line in out.splitlines():
+        try:
+            event = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        kind = event.get("type")
+        if kind == "item.completed" and event.get("item", {}).get("type") == "agent_message":
+            texts.append(event["item"].get("text", ""))
+        elif kind == "turn.completed":
+            u = event.get("usage", {})
+            cached = u.get("cached_input_tokens", 0)
+            usage = _usage(input=u.get("input_tokens", 0) - cached, cache_read=cached,
+                           output=u.get("output_tokens", 0))
+        elif kind in ("error", "turn.failed"):
+            message = event.get("message") or event.get("error", {}).get("message", "")
+            raise ValueError(f"codex failed: {message}")
+    if not texts:
+        raise ValueError("codex gave no answer")
+    return "\n\n".join(texts), usage
+
+
+PRESETS = {"claude-code": (_claude, parse_claude), "codex": (_codex, parse_codex)}
+
+
+async def _run(argv: list[str], stdin: str, cwd: Path, signal: CancelToken | None) -> str:
+    proc = await asyncio.create_subprocess_exec(
+        *argv, cwd=str(cwd), stdin=asyncio.subprocess.PIPE,
+        stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE, **own_group(),
+    )
+    task = asyncio.ensure_future(proc.communicate(stdin.encode("utf-8")))
+    try:
+        while not task.done():
+            if signal is not None and signal.is_cancelled():
+                raise _Cancelled
+            await asyncio.wait({task}, timeout=0.2)
+    finally:
+        if not task.done():
+            kill_tree(proc)
+            task.cancel()
+            await proc.wait()
+    out, err = task.result()
+    if proc.returncode != 0 and not out.strip():
+        raise ValueError(f"{Path(argv[0]).stem} exited {proc.returncode}: {err.decode(errors='replace')[-500:]}")
+    return out.decode("utf-8", errors="replace")
+
+
+def _fault(model: str, reason: str, message: str) -> StreamFaultEvent:
+    entry = ModelEntry(model=model, provider="cli", api="cli", stop_reason=reason,
+                       error_message=message)
+    return StreamFaultEvent(reason=reason, error=entry)
+
+
+class ExternalAgentProvider:
+    """Answers `cli:` models with an agent CLI; anything else goes to `fallback`."""
+
+    def __init__(self, fallback=None) -> None:
+        self.fallback = fallback
+
+    def __getattr__(self, name: str):
+        if self.fallback is None:
+            raise AttributeError(name)
+        return getattr(self.fallback, name)
+
+    def stream_response(self, *, model: str, system: str, messages: Sequence[TranscriptEntry],
+                        tools: Sequence[ToolSpec], signal: CancelToken | None = None,
+                        cache_key: str | None = None) -> AsyncIterator[WireEvent]:
+        if not is_external(model):
+            if self.fallback is None:
+                raise ValueError(f"the cli provider needs a cli: or acp: model, got {model!r}")
+            return self.fallback.stream_response(model=model, system=system, messages=messages,
+                                                 tools=tools, signal=signal, cache_key=cache_key)
+        return self._answer(model, system, messages, tools, signal)
+
+    async def _ask(self, route, name, sub, system, conversation, signal) -> tuple[str, UsageStats]:
+        with tempfile.TemporaryDirectory(ignore_cleanup_errors=True) as tmp:
+            if route == "acp":
+                return await acp.answer(name, sub, f"{system}\n\n{conversation}", Path(tmp), signal)
+            build, parse = PRESETS[name]
+            argv, stdin = build(sub, system, conversation, Path(tmp))
+            return parse(await _run(argv, stdin, Path(tmp), signal))
+
+    async def _answer(self, model, system, messages, tools, signal) -> AsyncIterator[WireEvent]:
+        coding = any(t.name == "python" for t in tools)
+        try:
+            route, name, sub = parse_model(model)
+            system = f"{system}\n\n{PROTOCOL}" if coding else system
+            conversation = render(messages)
+            text, usage = await self._ask(route, name, sub, system, conversation, signal)
+            if coding and parse_reply(text)[1] is None and FAKE_CALL.search(text):
+                conversation += f"\n\n[assistant]\n{text}\n\n[user]\n{CORRECTION}"
+                text, more = await self._ask(route, name, sub, system, conversation, signal)
+                usage = _add(usage, more)
+        except _Cancelled:
+            yield _fault(model, "aborted", "cancelled")
+            return
+        except (ValueError, OSError, json.JSONDecodeError) as exc:
+            yield _fault(model, "error", str(exc))
+            return
+        said, code = parse_reply(text) if coding else (text.strip(), None)
+        content: list = [TextSegment(text=said)] if said else []
+        stop = "stop"
+        if code is not None:
+            call = CallBlock(name="python", id=f"call_{uuid.uuid4().hex[:12]}", arguments={"code": code})
+            content.append(call)
+            stop = "toolUse"
+        message = ModelEntry(content=content, model=model, provider="cli", api="cli",
+                             stop_reason=stop, usage=usage)
+        if code is not None:
+            yield CallCloseEvent(content_index=len(content) - 1, tool_call=call, partial=message)
+        yield StreamCloseEvent(reason=stop, message=message)

rlmagent/model/external/textcalls.py

@@ -0,0 +1,57 @@
+"""The python tool through plain text, for agents that cannot call our tools."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+
+from rlmagent.harness.contracts.transcript import TranscriptEntry, gather_text
+
+PROTOCOL = """## Running code
+You have no tools of your own here; ignore any you think you have. Running a python block is how you use the python tool: the host runs it in a persistent kernel that has the project files and every function named above. To run code, reply with one block:
+
+```python
+print("hello")
+```
+
+Its output comes back in the next message. Put at most one block in a reply; text before it \
+is shown to the user. A reply with no block is your final answer."""
+
+_BLOCK = re.compile(r"```(?:python|py|repl)[ \t]*\r?\n(.*?)```", re.S)
+
+
+def parse_reply(text: str) -> tuple[str, str | None]:
+    """Split a reply into the text before its first python block and the block's code."""
+    match = _BLOCK.search(text)
+    if match is None:
+        return text.strip(), None
+    return text[: match.start()].strip(), match.group(1)
+
+
+def _assistant(entry) -> str:
+    parts = []
+    for block in entry.content:
+        if block.type == "text":
+            parts.append(block.text)
+        elif block.type == "toolCall":
+            parts.append(f"```python\n{block.arguments.get('code', '')}\n```")
+    return "\n".join(parts)
+
+
+def render(messages: Sequence[TranscriptEntry]) -> str:
+    """The conversation as one prompt, oldest first."""
+    parts = []
+    for entry in messages:
+        role = getattr(entry, "role", "")
+        if role == "user":
+            parts.append(f"[user]\n{entry.text}")
+        elif role == "assistant":
+            parts.append(f"[assistant]\n{_assistant(entry)}")
+        elif role == "toolResult":
+            label = "output" if not entry.is_error else "error"
+            parts.append(f"[{entry.tool_name} {label}]\n{gather_text(entry.content)}")
+        elif role == "custom":
+            parts.append(f"[note]\n{entry.text}")
+        elif role in ("compactionSummary", "branchSummary"):
+            parts.append(f"[summary of earlier conversation]\n{entry.summary}")
+    return "\n\n".join(parts)

rlmagent/model/failover.py

@@ -0,0 +1,129 @@
+"""Fall back to other provider/model pairs when the main one fails outright.
+
+A request moves to the next pair only when it failed before producing any
+output. Once text, reasoning or a tool call has streamed, the reply belongs
+to that provider and its failure is reported as it is: replaying a half-sent
+reply on another model would show the user two answers.
+
+Pairs come from ``RLM_AGENT_FALLBACK`` as ``provider:model`` items separated
+by commas, for example ``openrouter:qwen/qwen3-coder,anthropic:claude-sonnet-4-5``,
+or from ``fallback`` in a trusted project's ``.rlm-agent/settings.toml``.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import AsyncIterator, Callable, Sequence
+
+from rlmagent.harness.contracts.tooling import CancelToken, ToolSpec
+from rlmagent.harness.contracts.transcript import TranscriptEntry
+from rlmagent.harness.provider.base import ModelProvider
+from rlmagent.harness.provider.wire import (
+    SourceRetryEvent,
+    StreamFaultEvent,
+    StreamOpenEvent,
+    WireEvent,
+)
+
+FALLBACK_ENV = "RLM_AGENT_FALLBACK"
+
+# Events that carry no output: a request that failed after only these can be
+# sent elsewhere without the user having seen anything from it.
+_SILENT = (StreamOpenEvent, SourceRetryEvent)
+
+
+def parse_fallbacks(text: str | None) -> list[tuple[str, str]]:
+    """``"a:m1, b:m2"`` -> ``[("a", "m1"), ("b", "m2")]``; bad items are skipped."""
+    pairs: list[tuple[str, str]] = []
+    for item in (text or "").split(","):
+        name, sep, model = item.strip().partition(":")
+        if sep and name.strip() and model.strip():
+            pairs.append((name.strip().lower(), model.strip()))
+    return pairs
+
+
+class FailoverProvider:
+    """Wraps a provider; tries each fallback pair after an outright failure."""
+
+    def __init__(
+        self,
+        primary: ModelProvider,
+        fallbacks: Sequence[tuple[str, str]],
+        resolve: Callable[[str], ModelProvider],
+    ) -> None:
+        self.primary = primary
+        self.fallbacks = list(fallbacks)
+        self._resolve = resolve
+        self._built: dict[str, ModelProvider] = {}
+        self.last_route: tuple[str, str] | None = None
+
+    def __getattr__(self, name: str):
+        # Anything else (service tiers, shutdown hooks…) is the primary's.
+        return getattr(self.primary, name)
+
+    def _provider(self, name: str) -> ModelProvider | None:
+        if name not in self._built:
+            try:
+                self._built[name] = self._resolve(name)
+            except Exception:  # a fallback without credentials is skipped
+                return None
+        return self._built[name]
+
+    async def stream_response(
+        self,
+        *,
+        model: str,
+        system: str,
+        messages: Sequence[TranscriptEntry],
+        tools: Sequence[ToolSpec],
+        signal: CancelToken | None = None,
+        cache_key: str | None = None,
+    ) -> AsyncIterator[WireEvent]:
+        routes: list[tuple[str | None, str]] = [(None, model), *self.fallbacks]
+        for index, (name, route_model) in enumerate(routes):
+            provider = self.primary if name is None else self._provider(name)
+            if provider is None:
+                continue
+            last = index == len(routes) - 1
+            held: list[WireEvent] = []
+            spoke = False
+            failed = False
+            async for event in provider.stream_response(
+                model=route_model, system=system, messages=messages, tools=tools,
+                signal=signal, cache_key=cache_key,
+            ):
+                if spoke:
+                    yield event
+                    continue
+                if isinstance(event, _SILENT):
+                    held.append(event)
+                    continue
+                if (isinstance(event, StreamFaultEvent) and event.reason == "error"
+                        and not last and not (signal and signal.is_cancelled())):
+                    failed = True
+                    break
+                spoke = True
+                self.last_route = (name or "", route_model)
+                for early in held:
+                    yield early
+                yield event
+            if not failed:
+                if not spoke:
+                    for early in held:
+                        yield early
+                return
+
+
+def with_fallbacks(
+    primary: ModelProvider, resolve: Callable[[str], ModelProvider],
+    env: dict[str, str] | None = None,
+) -> ModelProvider:
+    """Wrap *primary* when fallbacks are configured; otherwise return it as is."""
+    source = env if env is not None else os.environ
+    text = source.get(FALLBACK_ENV)
+    if text is None and env is None:
+        from rlmagent.config.loader import project_settings
+
+        text = project_settings().get("fallback")
+    pairs = parse_fallbacks(text)
+    return FailoverProvider(primary, pairs, resolve) if pairs else primary

rlmagent/model/google.py

@@ -0,0 +1,199 @@
+"""Gemini content streaming through the native generate-content endpoint."""
+
+from __future__ import annotations
+
+import json
+import os
+from urllib.parse import quote
+from uuid import uuid4
+
+import httpx
+
+from rlmagent.harness.contracts.transcript import ModelEntry
+from rlmagent.harness.provider.wire import StreamFaultEvent
+from rlmagent.model._oai.normalize import EventAssembler
+from rlmagent.model._oai.parsers import (
+    CallBegin,
+    CallResolved,
+    Finished,
+    Metadata,
+    ReasoningChunk,
+    TextChunk,
+)
+from rlmagent.model._oai.transport import HttpStreamError, open_event_stream
+from rlmagent.model.settings import ConfigError, Credential
+from rlmagent.model.transport.client import build_async_client
+
+
+def content(messages) -> list[dict]:
+    result = []
+    for entry in messages:
+        role = getattr(entry, "role", "")
+        if role == "toolResult":
+            parts = [
+                {"functionResponse": {"name": entry.tool_name, "response": {"result": entry.text}}}
+            ]
+            sender = "user"
+        elif role in ("user", "assistant"):
+            sender = "model" if role == "assistant" else "user"
+            blocks = entry.content
+            parts = [{"text": blocks}] if isinstance(blocks, str) else []
+            if not isinstance(blocks, str):
+                for block in blocks:
+                    if block.type == "text":
+                        parts.append({"text": block.text})
+                    elif block.type == "image":
+                        parts.append(
+                            {"inlineData": {"mimeType": block.mime_type, "data": block.data}}
+                        )
+                    elif block.type == "toolCall":
+                        call = {"functionCall": {"name": block.name, "args": block.arguments}}
+                        if block.thought_signature:
+                            call["thoughtSignature"] = block.thought_signature
+                        parts.append(call)
+        elif hasattr(entry, "summary"):
+            sender, parts = "user", [{"text": entry.summary}]
+        else:
+            continue
+        if parts:
+            if result and result[-1]["role"] == sender:
+                result[-1]["parts"].extend(parts)
+            else:
+                result.append({"role": sender, "parts": parts})
+    return result
+
+
+class GoogleProvider:
+    def __init__(self, credential: Credential):
+        self.credential = credential
+        self._client = build_async_client(timeout=httpx.Timeout(120))
+
+    async def close(self):
+        await self._client.aclose()
+
+    async def stream_response(self, *, model, system, messages, tools, signal=None, cache_key=None):
+        name = model.removeprefix("models/")
+        payload = {
+            "contents": content(messages),
+            "systemInstruction": {"parts": [{"text": system}]},
+        }
+        if tools:
+            payload["tools"] = [
+                {
+                    "functionDeclarations": [
+                        {
+                            "name": tool.name,
+                            "description": tool.description,
+                            "parameters": tool.parameters,
+                        }
+                        for tool in tools
+                    ]
+                }
+            ]
+        url = (
+            self.credential.base_url.rstrip("/")
+            + f"/models/{quote(name, safe='')}:streamGenerateContent?alt=sse"
+        )
+        headers = {
+            "x-goog-api-key": self.credential.api_key,
+            "Content-Type": "application/json",
+            **dict(self.credential.extra_headers),
+        }
+        assembler = EventAssembler(model=model, provider="google", api="google-generate")
+        signatures = {}
+        usage, finish, index = {}, "stop", 0
+        completed = False
+        try:
+            async for event in open_event_stream(
+                self._client, url, payload, headers, signal=signal
+            ):
+                value = json.loads(event.data)
+                signals = []
+                if value.get("error") or value.get("promptFeedback", {}).get("blockReason"):
+                    raise ValueError("Google declined the content request")
+                if value.get("responseId"):
+                    signals.append(Metadata(value["responseId"], value.get("modelVersion")))
+                for candidate in value.get("candidates", [])[:1]:
+                    for part in candidate.get("content", {}).get("parts", []):
+                        if "text" in part:
+                            signals.append(
+                                ReasoningChunk(part["text"])
+                                if part.get("thought")
+                                else TextChunk(part["text"])
+                            )
+                        if "functionCall" in part:
+                            call = part["functionCall"]
+                            identity = call.get("id") or uuid4().hex
+                            signatures[identity] = part.get("thoughtSignature")
+                            signals.extend(
+                                [
+                                    CallBegin(index, identity, call["name"]),
+                                    CallResolved(
+                                        index,
+                                        identity,
+                                        call["name"],
+                                        json.dumps(call.get("args", {})),
+                                    ),
+                                ]
+                            )
+                            index += 1
+                            finish = "tool_calls"
+                    reason = candidate.get("finishReason")
+                    completed = completed or reason is not None
+                    if reason == "MAX_TOKENS":
+                        finish = "length"
+                    elif reason not in (None, "STOP", "MAX_TOKENS"):
+                        raise ValueError(f"Google generation ended with {reason}")
+                if "usageMetadata" in value:
+                    reported = value["usageMetadata"]
+                    usage = {
+                        "prompt_tokens": reported.get("promptTokenCount", 0),
+                        "completion_tokens": reported.get("candidatesTokenCount", 0)
+                        + reported.get("thoughtsTokenCount", 0),
+                        "total_tokens": reported.get("totalTokenCount", 0),
+                        "prompt_tokens_details": {
+                            "cached_tokens": reported.get("cachedContentTokenCount", 0)
+                        },
+                        "completion_tokens_details": {
+                            "reasoning_tokens": reported.get("thoughtsTokenCount", 0)
+                        },
+                    }
+                for parsed in signals:
+                    for output in assembler.accept(parsed):
+                        yield output
+            if signal is not None and signal.is_cancelled():
+                yield StreamFaultEvent(
+                    reason="aborted", error=ModelEntry(model=model, stop_reason="aborted")
+                )
+                return
+            if not completed:
+                raise ValueError("Google stream ended before a terminal candidate")
+            assembler.accept(Finished(finish, usage))
+            for output in assembler.finalize():
+                if hasattr(output, "message"):
+                    for call in output.message.tool_calls:
+                        call.thought_signature = signatures.get(call.id)
+                yield output
+        except (httpx.HTTPError, HttpStreamError, ValueError, KeyError, TypeError) as exc:
+            yield StreamFaultEvent(
+                reason="error",
+                error=ModelEntry(
+                    model=model,
+                    stop_reason="error",
+                    error_message=f"Google request failed ({type(exc).__name__})",
+                ),
+            )
+
+
+def build_google():
+    from rlmagent.config.loader import load_api_key
+
+    key = load_api_key("google")
+    if not key:
+        raise ConfigError("GOOGLE_API_KEY is not set")
+    return GoogleProvider(
+        Credential(
+            key,
+            os.environ.get("GOOGLE_API_BASE", "https://generativelanguage.googleapis.com/v1beta"),
+        )
+    )

rlmagent/model/limits.py

@@ -0,0 +1,46 @@
+"""Runtime model limits — immutable capability data and provider discovery contract."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable
+
+
+class LimitsError(ValueError):
+    """Raised when model-limit values are invalid or inconsistent."""
+
+
+@dataclass(frozen=True, slots=True)
+class ModelLimits:
+    """Immutable, provider-supplied token-budget constraints for a model."""
+
+    context_window: int
+    """Total context-window size in tokens (input + output)."""
+
+    max_output: int
+    """Maximum tokens the model can produce in a single response."""
+
+    def __post_init__(self) -> None:
+        if self.context_window < 1:
+            raise LimitsError(f"context_window must be positive, got {self.context_window}")
+        if self.max_output < 1:
+            raise LimitsError(f"max_output must be positive, got {self.max_output}")
+        if self.max_output >= self.context_window:
+            raise LimitsError(
+                f"max_output ({self.max_output:,}) must be less than "
+                f"context_window ({self.context_window:,})"
+            )
+
+    @property
+    def usable_context(self) -> int:
+        """Effective input budget: context window minus output reservation."""
+        return self.context_window - self.max_output
+
+
+@runtime_checkable
+class LimitsProbe(Protocol):
+    """Optional capability a provider implements to report model limits."""
+
+    async def query_limits(self, model: str) -> ModelLimits:
+        """Return the runtime limits for *model*."""
+        ...