git-repokit 0.9.10__py3-none-any.whl

repokit/_vendor/ailib/transports/openai_compat.py

@@ -0,0 +1,383 @@
+"""The OpenAI-compatible HTTP transport: LM Studio, Ollama and llama.cpp on
+this machine; OpenAI, OpenRouter, Groq, Together and the Llama endpoints
+over the wire. One adapter. Local versus remote is the spec's endpoint and
+whether it names a credential; nothing in the code knows the difference.
+
+Stdlib only (`urllib`): no `requests`, no `openai` package.
+
+**Everything unusual below is a measured fact, not a precaution**, taken
+against LM Studio on real hardware while this transport's predecessor was
+built (2026-09-04):
+
+* ``response_format: {"type": "json_object"}`` is answered **HTTP 400** --
+  unsupported -- while ``json_schema`` with ``strict`` works. So a strict
+  schema is the only structured-output route here. The schema itself is the
+  caller's: it arrives in the Request, and without one no shape is asked for.
+* ``reasoning_effort: "none"`` is the only thinking-suppression that reaches
+  the model through this API; it is a preset's business (`Spec.extra`), not
+  the transport's, because a hosted provider may reject it.
+* **HTTP 200 with empty content is possible** -- with reasoning on and a low
+  token ceiling, every token went to reasoning and ``content`` came back
+  ``''``. An empty body is a failure here, with a sentence.
+* **Asking for a model that is not loaded makes a local server load it** --
+  17.74 GB off disk in the measured case -- so the id is checked before
+  anything is sent. ``/v1/models`` lists everything DOWNLOADED, not what is
+  in memory (13 against 1, measured); load state comes from LM Studio's own
+  ``/api/v0/models``, which hangs off the server ROOT, not off ``/v1``. A
+  server without that endpoint (Ollama, llama.cpp, every hosted provider)
+  answers "cannot say", a third value that must never be read as "nothing".
+* **A client timeout does not cancel server-side work**, so there is no
+  retry in here; the caller re-runs if it wants one. An HTTP error is
+  reported with the server's own words and is not retried without the
+  schema either -- a provider that rejects ``response_format`` for a routed
+  model has said something the caller needs to hear.
+* **Throughput is dominated by the configured context window, not by the
+  model** (~385x between an oversized and a right-sized window on the same
+  model). The probe reports the loaded window and warns above a threshold,
+  so a caller can say so BEFORE a long job.
+
+**The credential** (2026-09-09) comes from one of three places, read in a
+fixed order at request time: a file the spec names on purpose
+(`credential_file`), then the environment variable it names
+(`credential_env`), then fallback files (`credential_fallbacks`) -- a
+tool's default key location, read only when the environment has nothing.
+The spec holds paths and a name, never the value; the value is read here,
+put in one header, and appears in no identity, record or sentence. A
+missing key is a sentence naming the variable AND the files, so a person
+knows where to put it. The file format is `NAME=value` lines (an `export `
+prefix, surrounding quotes, `#` comments and blank lines tolerated, CRLF and
+a BOM too); a file whose only non-comment line has no `=` is the value
+itself. On POSIX a key file readable by group or others earns a warning.
+"""
+from __future__ import annotations
+
+import ipaddress
+import json
+import os
+import stat
+import time
+import urllib.error
+import urllib.request
+from urllib.parse import urlparse
+
+from ..types import MODEL, ON_PREM, SCHEMA, Readiness, Request, Response, Spec
+
+#: How long to wait on a listing. If reachability takes longer than this the
+#: server is not in a state to work with.
+PROBE_TIMEOUT = 4
+
+#: A key file is a line or a handful; anything larger is not one, and is
+#: not read further.
+KEY_FILE_CAP = 65536
+
+
+def _unquote(value: str) -> str:
+    v = value.strip()
+    if len(v) >= 2 and v[0] == v[-1] and v[0] in ("'", '"'):
+        return v[1:-1]
+    return v
+
+
+def _read_key_file(path: str, name: str) -> str:
+    """The value of `name` in the key file at `path`, or "" when the file
+    does not exist, cannot be read, or has no such line.
+
+    `NAME=value` lines; `export NAME=value` too; surrounding quotes, `#`
+    comments and blank lines tolerated; a BOM and CRLF as well (`utf-8-sig`
+    and `splitlines`). When the file has exactly one non-comment line and
+    that line has no `=`, it is the value itself -- so a file that holds
+    only the token works, and a multi-line file without the name never
+    yields a guess. An empty value reads as absent."""
+    try:
+        with open(os.path.expanduser(path), encoding="utf-8-sig") as f:
+            text = f.read(KEY_FILE_CAP)
+    except (OSError, ValueError):
+        return ""
+    lines = [ln.strip() for ln in text.splitlines()]
+    lines = [ln for ln in lines if ln and not ln.startswith("#")]
+    for line in lines:
+        if line.startswith("export "):
+            line = line[len("export "):].lstrip()
+        key, sep, value = line.partition("=")
+        if sep and name and key.strip() == name:
+            return _unquote(value)
+    if len(lines) == 1 and "=" not in lines[0]:
+        return _unquote(lines[0])
+    return ""
+
+
+def _loose_mode(mode: int) -> bool:
+    """Whether a file mode lets group or others read it."""
+    return bool(stat.S_IMODE(mode) & 0o077)
+
+
+def _permission_warning(path: str) -> str:
+    """POSIX only: a key file readable by group or others. Windows ACLs are
+    not a mode, so nothing is said there."""
+    if os.name != "posix":
+        return ""
+    try:
+        mode = os.stat(os.path.expanduser(path)).st_mode
+    except OSError:
+        return ""
+    if _loose_mode(mode):
+        return f"{path} is readable by others (mode {stat.S_IMODE(mode):o}); chmod 600 it"
+    return ""
+
+#: Above this many tokens the loaded window is far larger than a short
+#: structured task needs, and on a machine whose VRAM the KV cache fills it
+#: is the difference between seconds and minutes.
+ROOMY_CONTEXT = 65536
+
+
+def endpoint_is_on_prem(url: str) -> bool | None:
+    """Whether a request to `url` stays on the user's own network, decided
+    without a DNS lookup: an IP literal that is loopback, private or
+    link-local; `localhost`; a `.local` name. A public host name is not.
+    None when the URL has no host at all."""
+    host = urlparse(url).hostname
+    if not host:
+        return None
+    if host == "localhost" or host.endswith(".local"):
+        return True
+    try:
+        ip = ipaddress.ip_address(host)
+    except ValueError:
+        return False
+    return bool(ip.is_loopback or ip.is_private or ip.is_link_local)
+
+
+class OpenAICompatible:
+    """Stateless: every method takes the spec it is working for."""
+
+    # -- plumbing ----------------------------------------------------------------
+
+    @staticmethod
+    def _credential(spec: Spec) -> tuple[str, str]:
+        """(the bearer token, where it came from) -- ("", "") when there is
+        none. The order is fixed: the file named on purpose, then the
+        environment, then the fallback files. The source is a path or the
+        variable's name, never the value, so a probe may print it."""
+        name = spec.credential_env
+        if spec.credential_file:
+            value = _read_key_file(spec.credential_file, name)
+            if value:
+                return value, spec.credential_file
+        if name:
+            value = os.environ.get(name, "")
+            if value:
+                return value, name
+        for path in spec.credential_fallbacks:
+            value = _read_key_file(path, name)
+            if value:
+                return value, path
+        return "", ""
+
+    @staticmethod
+    def _missing_key(spec: Spec) -> str:
+        """The sentence for a spec that names a credential and has none:
+        the variable and every file, each with why it gave nothing."""
+        who = spec.name or spec.endpoint.rstrip("/")
+        name = spec.credential_env
+        files = [p for p in (spec.credential_file, *spec.credential_fallbacks) if p]
+        if not files:
+            return f"{name} is not set in the environment -- {who} needs a key there"
+        why = []
+        for p in files:
+            if os.path.isfile(os.path.expanduser(p)):
+                why.append(f"{p} has no {name} line" if name else f"{p} is empty")
+            else:
+                why.append(f"{p} does not exist")
+        if not name:
+            return f"{' and '.join(why)} -- {who} needs a key there"
+        return (f"{name} is not set in the environment and {' and '.join(why)} -- "
+                f"{who} needs a key in one of them")
+
+    def _headers(self, spec: Spec, *, post: bool = False) -> dict[str, str]:
+        h = {"Accept": "application/json"}
+        if post:
+            h["Content-Type"] = "application/json"
+        value, _ = self._credential(spec)
+        if value:
+            h["Authorization"] = f"Bearer {value}"
+        return h
+
+    def _get(self, spec: Spec, url: str, timeout: int = PROBE_TIMEOUT):
+        req = urllib.request.Request(url, headers=self._headers(spec))
+        with urllib.request.urlopen(req, timeout=timeout) as r:      # noqa: S310
+            return json.loads(r.read().decode("utf-8", "replace"))
+
+    @staticmethod
+    def _root(spec: Spec) -> str:
+        ep = spec.endpoint.rstrip("/")
+        return ep[:-3] if ep.endswith("/v1") else ep
+
+    # -- the roster ----------------------------------------------------------------
+
+    def models(self, spec: Spec) -> list[str] | None:
+        """Model ids the server reports; None when it cannot be reached (or
+        refuses the credential). Everything DOWNLOADED, not what is loaded."""
+        try:
+            body = self._get(spec, spec.endpoint.rstrip("/") + "/models")
+        except (urllib.error.URLError, OSError, ValueError, TimeoutError):
+            return None
+        data = body.get("data") if isinstance(body, dict) else None
+        if not isinstance(data, list):
+            return None
+        return [d["id"] for d in data if isinstance(d, dict) and isinstance(d.get("id"), str)]
+
+    def _native_records(self, spec: Spec) -> list | None:
+        try:
+            body = self._get(spec, self._root(spec) + "/api/v0/models")
+        except (urllib.error.URLError, OSError, ValueError, TimeoutError):
+            return None
+        data = body.get("data") if isinstance(body, dict) else None
+        return data if isinstance(data, list) else None
+
+    def loaded_models(self, spec: Spec) -> list[str] | None:
+        """Model ids actually in memory, or **None when the server cannot
+        say**. Three-valued on purpose."""
+        data = self._native_records(spec)
+        if data is None:
+            return None
+        return [d["id"] for d in data if isinstance(d, dict) and isinstance(d.get("id"), str)
+                and d.get("state") == "loaded"]
+
+    def context_length(self, spec: Spec) -> int | None:
+        data = self._native_records(spec)
+        if data is None:
+            return None
+        for d in data:
+            if isinstance(d, dict) and d.get("state") == "loaded":
+                n = d.get("loaded_context_length") or d.get("max_context_length")
+                return n if isinstance(n, int) else None
+        return None
+
+    def _target(self, spec: Spec) -> tuple[str, str]:
+        """(model to ask for, why not) -- "" in the second slot means go.
+
+        The order that avoids surprising a person: the spec's model if it is
+        loaded; else the loaded one when the server can say; else the first
+        listed, which is all a server without load state can offer."""
+        ep = spec.endpoint.rstrip("/")
+        if (spec.credential_env or spec.credential_file) and not self._credential(spec)[0]:
+            return "", self._missing_key(spec)
+        listed = self.models(spec)
+        if not listed:
+            hint = f" ({spec.hint})" if spec.hint else ""
+            return "", (f"no model server at {ep} -- start the local server{hint} "
+                        f"or point at another endpoint")
+        live = self.loaded_models(spec)          # None = the server cannot say
+        if spec.model:
+            if live is not None and spec.model not in live:
+                where = ", ".join(live) if live else "none"
+                return "", (f"model {spec.model!r} is not loaded on {ep} (loaded: {where}) -- "
+                            f"asking for it would load it from disk; load it first or name one "
+                            f"that is")
+            if live is None and spec.model not in listed:
+                return "", f"model {spec.model!r} is not on {ep} -- it has: {', '.join(listed)}"
+            return spec.model, ""
+        if live:
+            return live[0], ""                   # the one in memory, not the first on disk
+        if live is not None:                     # the server can say, and says: nothing
+            return "", (f"{ep} has no model loaded -- load one (asking would load one "
+                        f"from disk, which takes minutes)")
+        return listed[0], ""
+
+    # -- the protocol ---------------------------------------------------------------
+
+    def capabilities(self, spec: Spec) -> frozenset[str]:
+        caps = {SCHEMA, MODEL}
+        on_prem = spec.on_prem if spec.on_prem is not None else endpoint_is_on_prem(spec.endpoint)
+        if on_prem:
+            caps.add(ON_PREM)
+        return frozenset(caps)
+
+    def probe(self, spec: Spec) -> Readiness:
+        model, why = self._target(spec)
+        if not model:
+            return Readiness(False, why)
+        ep = spec.endpoint.rstrip("/")
+        n = self.context_length(spec)
+        reason = f"{ep} -- reachable, model {model}" + (f", {n:,}-token context" if n else "")
+        warnings = []
+        if n and n > ROOMY_CONTEXT:
+            warnings.append(f"loaded with a {n:,}-token context; a short structured task needs a "
+                            f"couple of thousand, and an oversized window is the usual reason a local "
+                            f"run takes minutes (reload it at 16k-32k)")
+        # A server that cannot say what is loaded has a catalogue, not a
+        # model: taking the first entry is right for a local server running
+        # one model and arbitrary for a hosted provider, where it decides
+        # both the answer and the price. Measured 2026-09-17: two runs of the
+        # golden matrix on OpenRouter were answered by a model nobody chose.
+        _on_prem = spec.on_prem if spec.on_prem is not None else endpoint_is_on_prem(spec.endpoint)
+        if not spec.model and not _on_prem:
+            warnings.append(f"no model configured, so the first this endpoint lists was used: "
+                            f"{model} -- it decides the answer and the price, and the list can "
+                            f"change between runs; set ai_merge_model to choose")
+        _, source = self._credential(spec)
+        if source:
+            reason += f", key from {source}"              # the route, never the value
+            if source != spec.credential_env:
+                perm = _permission_warning(source)
+                if perm:
+                    warnings.append(perm)
+        return Readiness(True, reason, "; ".join(warnings))
+
+    def invoke(self, spec: Spec, req: Request) -> Response:
+        model, why = self._target(spec)
+        if not model:
+            return Response("failed", error=why)
+        ep = spec.endpoint.rstrip("/")
+        body: dict = {"model": model,
+                      "messages": [{"role": "user", "content": req.prompt}],
+                      "stream": False}
+        honoured = [MODEL]
+        if req.temperature is not None:
+            body["temperature"] = req.temperature
+        if req.max_tokens is not None:
+            body["max_tokens"] = req.max_tokens
+            honoured.append("max_tokens")
+        body.update(dict(spec.extra))
+        if req.schema is not None:
+            body["response_format"] = {"type": "json_schema",
+                                       "json_schema": {"name": "answer", "strict": True,
+                                                       "schema": req.schema}}
+            honoured.append(SCHEMA)
+        http = urllib.request.Request(ep + "/chat/completions", data=json.dumps(body).encode("utf-8"),
+                                      headers=self._headers(spec, post=True), method="POST")
+        started = time.monotonic()
+        # Until this transport streams (the run-while-alive design's second
+        # unit), a server answers in one piece and shows no sign of life
+        # meanwhile -- so the silence window is its ceiling when the caller
+        # set none. A zero timeout on urlopen would fail at once.
+        ceiling = req.timeout or req.idle
+        try:
+            with urllib.request.urlopen(http, timeout=ceiling) as r:   # noqa: S310
+                answer = json.loads(r.read().decode("utf-8", "replace"))
+        except urllib.error.HTTPError as e:
+            detail = ""
+            try:
+                detail = e.read().decode("utf-8", "replace")[:300]
+            except Exception:                                            # noqa: BLE001
+                pass
+            return Response("failed", error=f"{ep} answered HTTP {e.code}{': ' + detail if detail else ''}")
+        except TimeoutError:
+            return Response("failed", error=(f"no answer from {model} within {ceiling}s -- if it is "
+                                             f"generating slowly, the usual cause is a context window "
+                                             f"far larger than the prompt, not the model itself"))
+        except (urllib.error.URLError, OSError) as e:
+            return Response("failed", error=f"cannot reach {ep}: {e}")
+        except ValueError as e:
+            return Response("failed", error=f"{ep} answered something that is not JSON: {e}")
+        elapsed = time.monotonic() - started
+        choices = answer.get("choices") if isinstance(answer, dict) else None
+        if not choices:
+            return Response("failed", error=f"{ep} answered with no choices", elapsed=elapsed)
+        text = (choices[0].get("message") or {}).get("content") or ""
+        if not text.strip():
+            return Response("failed", model_used=model, elapsed=elapsed,
+                            error=(f"{model} answered with empty content -- the reasoning budget may "
+                                   f"have consumed the reply; raise max_tokens or turn reasoning off"))
+        return Response("answered", text=text, model_used=str(answer.get("model") or model),
+                        honoured=tuple(honoured), elapsed=elapsed)

repokit/_vendor/ailib/transports/prompt_file.py

@@ -0,0 +1,41 @@
+"""The prompt-file transport: not a model. It writes the request where a
+person can carry it to any model by hand, and answers "deferred" -- which
+is a status, not a failure and not a success. A caller that wants a
+"write the prompt and stop" mode without routing through the library is
+free to do that itself; this exists so the library's own story is complete
+and so a consumer that DOES want it has it.
+
+The spec's `endpoint` is the directory prompts are written to.
+"""
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+from ..types import ON_PREM, Readiness, Request, Response, Spec
+
+
+class PromptFile:
+    def capabilities(self, spec: Spec) -> frozenset[str]:
+        return frozenset({ON_PREM})                    # nothing leaves at all
+
+    def probe(self, spec: Spec) -> Readiness:
+        if not spec.endpoint:
+            return Readiness(False, "no directory configured for prompts (the spec's endpoint)")
+        return Readiness(True, f"prompts are written to {spec.endpoint}; nothing is sent")
+
+    def invoke(self, spec: Spec, req: Request) -> Response:
+        if not spec.endpoint:
+            return Response("failed", error="no directory configured for prompts (the spec's endpoint)")
+        d = Path(spec.endpoint).expanduser()
+        try:
+            d.mkdir(parents=True, exist_ok=True)
+            path = d / f"prompt_{time.strftime('%Y-%m-%d_%H-%M-%S')}.md"
+            n = 1
+            while path.exists():                       # two in one second
+                n += 1
+                path = d / f"prompt_{time.strftime('%Y-%m-%d_%H-%M-%S')}_{n}.md"
+            path.write_text(req.prompt, encoding="utf-8")
+        except OSError as e:
+            return Response("failed", error=f"cannot write the prompt under {d}: {e}")
+        return Response("deferred", artifact=str(path))

repokit/_vendor/ailib/types.py

@@ -0,0 +1,224 @@
+"""The library's value types: what a backend IS on paper, what a call SAYS,
+and what comes BACK.
+
+A `Spec` is everything needed to build a backend -- which transport, where,
+which model, how to authenticate, how to invoke a CLI -- and nothing that
+varies per call. It is immutable, so it can be shared, hashed and recorded.
+It holds the NAME of the environment variable carrying a credential, or the
+PATH of a file holding one, and never the credential itself: a spec is
+exactly the object that ends up in a cache key, a provenance record and a
+health-check line, and a secret in a frozen dataclass ends up in all three.
+`identity()` is the part of a spec those consumers may see.
+
+A `Request` is what varies per call and is the same for every transport: the
+prompt, the shape the answer must take, the limits. The model is NOT here --
+it is a fact about which backend you built, so it lives in the spec.
+
+A `Response` says what happened with a word (answered, deferred, failed),
+never with a boolean that has to mean three things.
+"""
+from __future__ import annotations
+
+import dataclasses
+import hashlib
+import json
+from dataclasses import dataclass
+from typing import Any, TextIO
+
+STATUSES = ("answered", "deferred", "failed")
+
+#: Capability names a transport may advertise for a given spec.
+SCHEMA = "schema"                 # the answer's shape is enforced, not just requested
+MODEL = "model"                   # the backend can be told which model to use
+STREAM = "stream"                 # output can be echoed as it arrives
+ON_PREM = "data_stays_on_prem"    # the prompt does not leave the user's own network
+TOOLS = "tools"                   # given a working directory, the backend may read and write in it
+
+
+def _basename(path: str) -> str:
+    """The last component of `path` under EITHER separator, so the same
+    logical file yields the same identity on every platform."""
+    return path.replace("\\", "/").rstrip("/").rsplit("/", 1)[-1]
+
+
+@dataclass(frozen=True)
+class Spec:
+    """Everything needed to BUILD a backend. Immutable.
+
+    transport      -- "cli", "openai_compat", "prompt-file", ... (the registry's names)
+    name           -- a human label for the preset; not part of the identity
+    endpoint       -- HTTP transports: the base URL, ending in /v1 for the
+                      OpenAI-compatible surface; the prompt-file transport: the
+                      directory prompts are written to
+    model          -- the model to ask for; "" means the backend's own choice
+    credential_env -- the NAME of the environment variable holding a bearer
+                      token, resolved at request time; never the value
+    credential_file -- the PATH of a file holding the token, read at request
+                      time BEFORE the environment (a file named on purpose
+                      wins). `NAME=value` lines, looked up by credential_env;
+                      a file with a single bare line is the value itself
+    credential_fallbacks -- paths read only when the environment has
+                      nothing, in order (a tool's default key location).
+                      Neither field ever holds the value
+    command        -- CLI transports: the argv template. Placeholders:
+                      {model}, {schema} (the schema inline, one argv token),
+                      {schema_file}, {prompt_file}, {output_file} (paths in the
+                      child's scratch directory), {cwd} (the child's working
+                      directory), {tools} (see `tools`). An empty placeholder
+                      removes itself and the flag before it.
+    tools          -- CLI transports: what `{tools}` becomes when the Request
+                      names a working directory -- the CLI's own grant of what
+                      it may touch there (claude's `--allowedTools` list,
+                      codex's sandbox mode). Without a workdir the placeholder
+                      and its flag vanish, so a call that names none is argv-
+                      identical to a preset without a grant
+    answer         -- CLI transports: where the answer is. "stdout" (default),
+                      "stdout-json:<key>" (stdout is a JSON envelope; take one
+                      key), "stream-json:<key>" (stdout is one JSON event per
+                      line as the CLI works; the answer is one key of the last
+                      event whose type is "result", and an event marked
+                      is_error is a failure carrying that key's text), or
+                      "file:{output_file}"
+    max_turns      -- CLI transports: what `{turns}` becomes -- the CLI's own
+                      budget of agentic turns (claude's `--max-turns`), the
+                      cost fence for a call that is allowed to run while it is
+                      alive. 0 drops the placeholder and its flag. Part of the
+                      identity, because it bounds the answer
+    env_unset      -- variables removed from the CHILD's environment
+    candidates     -- extra executable paths tried after PATH
+    on_prem        -- the preset's word on whether data stays on the user's
+                      network; None lets the transport derive it from the
+                      endpoint
+    hint           -- appended to a not-reachable reason (e.g. where to start
+                      a local server); never part of the identity
+    extra          -- transport-specific request fields, as ordered pairs
+    """
+    transport: str
+    name: str = ""
+    endpoint: str = ""
+    model: str = ""
+    credential_env: str = ""
+    credential_file: str = ""
+    credential_fallbacks: tuple[str, ...] = ()
+    command: tuple[str, ...] = ()
+    tools: str = ""
+    answer: str = "stdout"
+    env_unset: tuple[str, ...] = ()
+    candidates: tuple[str, ...] = ()
+    on_prem: bool | None = None
+    hint: str = ""
+    extra: tuple[tuple[str, Any], ...] = ()
+    max_turns: int = 0
+
+    def with_(self, **changes: Any) -> "Spec":
+        return dataclasses.replace(self, **changes)
+
+    def identity(self) -> str:
+        """What a cache key, a record or a report may hold: the things that
+        decide WHICH model answers. Never the credential's value; not the
+        executable's resolved path (a reinstall must not flush a cache); not
+        the name, the hint, the timeout or the candidates. A key file is
+        named by its BASENAME only: the full path carries the account name,
+        records get pasted into issues, and a moved home must not flush the
+        cache either."""
+        # Labelled, and only the parts that exist: an identity is read by
+        # people in records and reports, and `cli||||...` said nothing about
+        # which fields were empty (2026-09-09; one cache invalidation).
+        parts = [self.transport]
+        if self.endpoint:
+            parts.append(f"endpoint={self.endpoint.rstrip('/')}")
+        if self.model:
+            parts.append(f"model={self.model}")
+        if self.command:
+            parts.append(f"command={' '.join(self.command)}")
+        if self.max_turns:
+            parts.append(f"turns={self.max_turns}")
+        if self.extra:
+            parts.append(f"extra={json.dumps(sorted(self.extra), sort_keys=True, default=str)}")
+        if self.credential_env:
+            parts.append(f"key:{self.credential_env}")
+        for path in (self.credential_file, *self.credential_fallbacks):
+            if path:
+                parts.append(f"keyfile:{_basename(path)}")
+        return " ".join(parts)
+
+
+@dataclass(frozen=True)
+class Request:
+    """What varies per call. Identical for every transport.
+
+    max_tokens=None and temperature=None mean "not sent": a low ceiling is
+    exactly how a reasoning model comes back with empty content. `stream_to`
+    is a text sink a transport echoes output into as it arrives; it is not
+    part of the fingerprint, and neither are the two limits. `workdir` is a
+    directory the caller prepared for the backend to work IN -- a CLI runs
+    there, may read and write there under the spec's `tools` grant, and the
+    directory is left for the caller to read back; "" means the transport's
+    own throwaway scratch. Where the child ran is not what was asked, so
+    the fingerprint excludes it too.
+
+    The two limits (2026-09-18, run while alive): a call ends when the model
+    finishes, when it is demonstrably dead, or when the caller set a
+    ceiling -- never because a number guessed in advance ran out. `idle` is
+    the silence, in seconds, after which a backend that has shown no sign of
+    life is declared dead and stopped (a thinking model is observably alive:
+    its output arrives as it thinks; a dead process emits nothing).
+    `timeout` is a hard ceiling on the whole call and 0, the default, means
+    there is none; a caller sets one for a machine with nobody watching.
+    """
+    prompt: str
+    schema: dict | None = None
+    max_tokens: int | None = None
+    timeout: int = 0
+    temperature: float | None = 0
+    stream_to: TextIO | None = None
+    workdir: str = ""
+    idle: int = 180
+
+    def fingerprint(self) -> str:
+        payload = json.dumps({"prompt": self.prompt, "schema": self.schema,
+                              "max_tokens": self.max_tokens, "temperature": self.temperature},
+                             sort_keys=True, default=str)
+        return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+@dataclass(frozen=True)
+class Response:
+    """What came back. `status` is one of `STATUSES`:
+
+    answered -- `text` holds the answer, `model_used` says who gave it,
+                `honoured` names the Request fields the transport enforced
+    deferred -- nothing was asked; `artifact` is where the prompt was written
+                for a person to carry
+    failed   -- `error` is a sentence a person can act on
+    """
+    status: str
+    text: str = ""
+    error: str = ""
+    model_used: str = ""
+    honoured: tuple[str, ...] = ()
+    artifact: str = ""
+    cached: bool = False
+    cached_at: float = 0.0
+    key: str = ""
+    elapsed: float = 0.0
+
+    def __post_init__(self) -> None:
+        if self.status not in STATUSES:
+            raise ValueError(f"status must be one of {STATUSES}, not {self.status!r}")
+
+    @property
+    def ok(self) -> bool:
+        return self.status == "answered"
+
+    def with_(self, **changes: Any) -> "Response":
+        return dataclasses.replace(self, **changes)
+
+
+@dataclass(frozen=True)
+class Readiness:
+    """A health check's answer: yes or no, a sentence either way, and an
+    optional warning for "yes, but" (a window far larger than the job)."""
+    ok: bool
+    reason: str = ""
+    warning: str = ""