adopt-agent 0.3.0__py3-none-any.whl

adopt_agent/__init__.py

@@ -0,0 +1,78 @@
+"""The single model seam: budget, tracing, idempotency, adapters.
+
+Contracts §10.1 · AI spec §1-§8 · implementation spec §4.13. Implemented at S7.
+
+**Every model call in either repository passes through `Runner.run`.** The
+`no-provider-sdk` import contract enforces the other half -- that provider
+clients live only under `adapters/` -- so the rule survives contributors who
+never read the AI spec.
+
+**Nothing here imports an adapter eagerly**, and that is load-bearing twice
+over: `adopt_store` depends on this package for the runtime-annex port, so an
+eager import would drag a provider client into the store and break
+`no-provider-sdk` correctly; and offline mode must refuse *before* the adapter
+module loads, which is what makes "no socket opened" provable rather than
+argued.
+
+Invariants carried from S0 and still true: provider clients are imported only in
+`adapters/`, budget logic lives only in `budget.py`, traces record digests and
+never payloads, and no model identifier is hard-coded anywhere -- including as a
+default, and including in this package's only data file, `prices.json`, whose
+model names are price-table keys and select nothing.
+"""
+
+from adopt_agent.annex import AgentRunRecord, AnnexRecords
+from adopt_agent.api import (
+    Adapter,
+    AdapterInfo,
+    AdapterKind,
+    AdapterResponse,
+    AgentRequest,
+    AgentResult,
+    AgentRunner,
+    AgentStatus,
+    Artifact,
+    Budget,
+    Cost,
+    ToolCall,
+    ToolSpec,
+    Trace,
+    TraceStep,
+)
+from adopt_agent.budget import BudgetVerdict, Meter
+from adopt_agent.pricing import ModelPrice, cost_usd, price_for, stale_rows
+from adopt_agent.runner import Runner
+from adopt_agent.schema_check import SchemaViolation, UnsupportedSchema, validate_against_schema
+from adopt_agent.skills import LoadedSkill, load_skill
+
+__all__ = [
+    "Adapter",
+    "AdapterInfo",
+    "AdapterKind",
+    "AdapterResponse",
+    "AgentRequest",
+    "AgentResult",
+    "AgentRunRecord",
+    "AgentRunner",
+    "AgentStatus",
+    "AnnexRecords",
+    "Artifact",
+    "Budget",
+    "BudgetVerdict",
+    "Cost",
+    "LoadedSkill",
+    "Meter",
+    "ModelPrice",
+    "Runner",
+    "SchemaViolation",
+    "ToolCall",
+    "ToolSpec",
+    "Trace",
+    "TraceStep",
+    "UnsupportedSchema",
+    "cost_usd",
+    "load_skill",
+    "price_for",
+    "stale_rows",
+    "validate_against_schema",
+]

adopt_agent/adapters/__init__.py

@@ -0,0 +1,29 @@
+"""The only package permitted to import a model-provider client SDK.
+
+Adapters translate; they never enforce policy (AI spec §1, §2). Everything hard
+-- budget metering, the single output-schema retry, idempotency, tracing -- is
+the seam's, which is what keeps an adapter thin enough to be written twice.
+
+**This module deliberately imports no adapter.** `base.REGISTRY` maps an id to a
+module path and `build_adapter` imports it on demand, for two reasons that both
+matter:
+
+1. **`adopt_store` depends on `adopt_agent`** -- it realizes the runtime-annex
+   port (contracts §12, CR-45). If importing `adopt_agent` pulled every adapter
+   in, `adopt_store` would transitively reach a provider client and
+   `no-provider-sdk` would break -- correctly, because it would then be true.
+2. **Offline must refuse before the import**, not merely before the request.
+   F13.7 says a hosted adapter raises "before any socket opens"; refusing
+   before the module loads is the stronger claim, and it is what lets S6's
+   blocked-socket harness prove it rather than argue it from reading code.
+
+`no-provider-sdk` still sees every import edge statically -- the contract is
+about *where* a provider client may be imported, and the answer is here.
+
+**At S7 no adapter imports a vendor SDK at all** *(CR-46)*. The hosted adapters
+speak HTTP over the standard library, because `03` §7.3 forbids copyleft
+`in-binary` and both official SDKs drag `certifi` (MPL-2.0) into the wheel. The
+contract stays declared and preventive: it fires the moment anyone adds one.
+"""
+
+__all__: list[str] = []

adopt_agent/adapters/_wire.py

@@ -0,0 +1,227 @@
+"""One HTTPS client for every hosted adapter, over the standard library.
+
+**Why the standard library and not a vendor SDK.** Owner decision, 2026-08-06,
+recorded as CR-46. `03` §7.3 makes `in-binary` **permissive only, no copyleft,
+ever** -- and the transitive closure of both official SDKs includes `certifi`
+(MPL-2.0) and `tqdm` (MPL-2.0 AND MIT). The licence gate refused them, correctly.
+Rather than amend the policy for two convenience libraries, the adapters talk
+HTTP directly: `urllib.request` over `ssl.create_default_context()` uses the
+**operating system's** trust store, so there is no CA bundle to vendor and no
+copyleft to carry.
+
+That trade is cheap precisely because of how thin an adapter is here. AI spec §1
+assigns budget metering, the output-schema retry, idempotency and tracing to the
+seam; an adapter translates one request and one response and owns exactly one
+thing of its own -- a bounded retry on a *transient* failure, inside
+`AGENT_ADAPTER_TIMEOUT_S`, where the seam's meter cannot double-count it.
+
+**Nothing here reads a credential from anywhere but the environment**, and no
+credential is logged, traced or returned (`03` §3). The error raised on failure
+carries a status code and never a response body, because a provider's error body
+can echo the prompt back.
+"""
+
+import json
+import ssl
+import urllib.error
+import urllib.request
+from collections.abc import Callable
+from typing import Any, Final
+
+from adopt_const import AGENT_ADAPTER_TIMEOUT_S
+from adopt_obs import AdoptError, ErrorCode
+
+__all__ = ["post_json"]
+
+#: Statuses worth one retry: the provider said "not now", not "not ever".
+#: 4xx other than 429 are the caller's fault and retrying them spends money to
+#: receive the same refusal.
+_RETRYABLE: Final[frozenset[int]] = frozenset({408, 425, 429, 500, 502, 503, 504})
+
+#: One retry, and only for the statuses above. AI spec §1 puts transient retry
+#: with the adapter and bounds it; the seam does not retry at all, because that
+#: would double-count cost.
+_MAX_ATTEMPTS: Final[int] = 2
+
+_CONTEXT: Final[ssl.SSLContext] = ssl.create_default_context()
+
+#: Hosts a plaintext POST is permitted to. A locally served model on loopback
+#: has no network to intercept; anything else carries a prompt in the clear, and
+#: AI spec §8 has no exception for convenience.
+_LOOPBACK: Final[frozenset[str]] = frozenset({"localhost", "127.0.0.1", "::1", "[::1]"})
+
+
+#: The only fields lifted out of a provider's error body. Enumerated identifiers
+#: naming a parameter or a failure class -- never free text. `message` is
+#: excluded on purpose: a content-policy refusal quotes what triggered it.
+_ERROR_IDENTIFIERS: Final[tuple[str, ...]] = ("type", "code", "param")
+
+#: A hard ceiling on each identifier, so a provider that returns something
+#: unexpected in one of these fields cannot turn this into a body dump.
+# const-sync: ok -- a display cap for an error identifier, not a tunable.
+_IDENTIFIER_MAX_CHARS: Final[int] = 64
+
+#: The status that means "this request shape is wrong", and the only one worth
+#: renegotiating. A 401 or a 404 is not fixed by dropping a parameter.
+# const-sync: ok -- an HTTP status code, not CLI_COLD_START_MS.
+_BAD_REQUEST: Final[int] = 400
+
+#: A ceiling on renegotiation, so a provider rejecting a different field each
+#: time terminates instead of looping. Three is the number of parameters any
+#: adapter here declares negotiable.
+# const-sync: ok -- a loop bound for parameter negotiation, not a tunable.
+_MAX_ADJUSTMENTS: Final[int] = 3
+
+
+def _body(exc: urllib.error.HTTPError) -> str:
+    """The error body, read once and memoized.
+
+    `HTTPError` is a file object: the second reader gets an empty string. Both
+    the diagnostic string and the negotiation need it, so neither may own it.
+    """
+    cached = getattr(exc, "_adopt_body", None)
+    if cached is None:
+        try:
+            cached = exc.read().decode("utf-8", errors="replace")
+        except Exception:  # an error path must not raise
+            cached = ""
+        exc._adopt_body = cached  # type: ignore[attr-defined]
+    return str(cached)
+
+
+def _rejected(exc: urllib.error.HTTPError) -> tuple[str, str]:
+    """`(code, param)` from a provider error body, or `("", "")`."""
+    try:
+        payload = json.loads(_body(exc))
+    except Exception:  # diagnosis is best-effort: an error path must not raise
+        return "", ""
+    error = payload.get("error") if isinstance(payload, dict) else None
+    if not isinstance(error, dict):
+        return "", ""
+    return str(error.get("code") or "")[:_IDENTIFIER_MAX_CHARS], str(error.get("param") or "")[
+        :_IDENTIFIER_MAX_CHARS
+    ]
+
+
+def _identifiers(exc: urllib.error.HTTPError) -> str:
+    """`(type=…, param=…)` from a provider error body, or `""`.
+
+    Reading the body cannot itself fail the request: a provider under load
+    returns HTML, and an error path that raises while explaining an error is
+    strictly worse than one that says less.
+    """
+    try:
+        payload = json.loads(_body(exc))
+    except Exception:  # diagnosis is best-effort: an error path must not raise
+        return ""
+    error = payload.get("error") if isinstance(payload, dict) else None
+    if not isinstance(error, dict):
+        return ""
+    parts = [
+        f"{field}={str(error[field])[:_IDENTIFIER_MAX_CHARS]}"
+        for field in _ERROR_IDENTIFIERS
+        if error.get(field)
+    ]
+    return f" ({', '.join(parts)})" if parts else ""
+
+
+def post_json(
+    url: str,
+    payload: dict[str, Any],
+    headers: dict[str, str],
+    *,
+    adapter_id: str,
+    negotiate: Callable[[dict[str, Any], str, str], bool] | None = None,
+) -> dict[str, Any]:
+    """POST JSON and return the decoded object, or raise `AGENT_PROVIDER_ERROR`.
+
+    The body is never included in the raised message. A provider's error payload
+    routinely echoes the request back, and AI spec §8.3 says prompt text is not
+    retrievable from our artifacts -- an exception message is one of ours.
+
+    **Three identifier fields are the exception, and they are an allowlist rather
+    than a relaxation** *(CR-52)*. `HTTP 400` alone is undiagnosable: it says a
+    request was malformed and not which part, so the first real-model run left
+    "the request shape is wrong somewhere" as the whole finding, and the privacy
+    rule that produced that message is not one to soften. `error.type`,
+    `error.code` and `error.param` are **enumerated identifiers naming a
+    parameter or a failure class** -- `unsupported_parameter`, `temperature` --
+    and cannot carry prompt text, because they are not free-text fields.
+    `error.message` is deliberately **excluded**: it is free text, and a
+    content-policy refusal quotes the content that triggered it.
+
+    **`negotiate` is how a caller answers a 400 that names a parameter**
+    *(CR-52)*. It is handed `(payload, code, param)`, may adjust the payload in
+    place, and returns whether it did; a `True` costs one more attempt with the
+    adjusted payload. **This is not a transient retry** and is counted
+    separately -- a provider that rejects a parameter will reject it forever, so
+    retrying unchanged is spending money to receive the same refusal, while
+    retrying *changed* is the only way to discover a shape the endpoint accepts.
+
+    Why discovery rather than a table keyed by model: `04` §2 forbids any
+    hard-coded model identifier, *including as a default*, so a table mapping
+    model prefixes to parameter sets is exactly the "house lab" that rule exists
+    to prevent -- and it would be wrong the day a vendor ships a variant. The
+    provider names the parameter it will not take; that is the authority.
+    """
+    probe = urllib.request.Request(url, method="POST")  # noqa: S310 -- checked immediately
+    if probe.type != "https" and probe.host.split(":")[0] not in _LOOPBACK:
+        raise AdoptError(
+            ErrorCode.AGENT_PROVIDER_ERROR,
+            message=f"{adapter_id} refused a plaintext endpoint that is not loopback",
+            hint=(
+                "Plaintext is permitted only to localhost, where there is no network "
+                "to intercept. Anything else carries a prompt across a wire in the "
+                "clear, and AI spec §8 does not have an exception for convenience."
+            ),
+        )
+
+    last: str = "no attempt was made"
+    #: Each parameter may be adjusted at most once, so negotiation terminates
+    #: even against a provider that rejects a different field every time.
+    adjustments = 0
+    attempt = 0
+    while attempt < _MAX_ATTEMPTS:
+        request = urllib.request.Request(  # noqa: S310 -- scheme checked above
+            url,
+            data=json.dumps(payload).encode("utf-8"),
+            headers={**headers, "content-type": "application/json"},
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(  # noqa: S310 -- scheme checked above
+                request, timeout=AGENT_ADAPTER_TIMEOUT_S, context=_CONTEXT
+            ) as response:
+                decoded: dict[str, Any] = json.loads(response.read().decode("utf-8"))
+                return decoded
+        except urllib.error.HTTPError as exc:
+            last = f"HTTP {exc.code}{_identifiers(exc)}"
+            if (
+                negotiate is not None
+                and exc.code == _BAD_REQUEST
+                and adjustments < _MAX_ADJUSTMENTS
+            ):
+                code, param = _rejected(exc)
+                if param and negotiate(payload, code, param):
+                    adjustments += 1
+                    continue  # a changed request, not a repeat of a refused one
+            if exc.code not in _RETRYABLE or attempt == _MAX_ATTEMPTS - 1:
+                break
+        except (urllib.error.URLError, TimeoutError) as exc:
+            last = f"{type(exc).__name__}"
+            if attempt == _MAX_ATTEMPTS - 1:
+                break
+        except json.JSONDecodeError:
+            last = "the provider returned a body that is not JSON"
+            break
+        attempt += 1
+
+    raise AdoptError(
+        ErrorCode.AGENT_PROVIDER_ERROR,
+        message=f"{adapter_id} failed after {_MAX_ATTEMPTS} attempt(s): {last}",
+        hint=(
+            "The seam does not retry beyond the adapter's own bounded attempts, and "
+            "it does not fall back to another adapter -- a silent substitution changes "
+            "cost, behaviour and data residency without the operator knowing."
+        ),
+    )

adopt_agent/adapters/anthropic.py

@@ -0,0 +1,183 @@
+"""The hosted Anthropic adapter. AI spec §2, kind `hosted`, offline **denied**.
+
+Its own module rather than a flag on the OpenAI-compatible one, because the
+Messages API differs where it matters: `system` is a top-level parameter rather
+than a message, `max_tokens` is **required**, tool results come back as content
+blocks rather than as a separate field, and usage is reported under different
+keys. Folding two wire shapes into one class with branches is how an adapter
+stops being a translation and starts being a place bugs hide.
+
+**No model identifier appears in this file**, including as a default
+(AI spec §2). **No credential is logged, traced or returned** (`03` §3).
+"""
+
+import hashlib
+import json
+import os
+from collections.abc import Mapping
+from typing import Any, Final
+
+from adopt_agent.adapters._wire import post_json
+from adopt_agent.api import AdapterResponse, ToolCall, ToolSpec
+from adopt_obs import AdoptError, ErrorCode
+
+__all__ = ["AnthropicAdapter", "build"]
+
+_URL: Final[str] = "https://api.anthropic.com/v1/messages"
+_KEY_ENV: Final[str] = "ANTHROPIC_API_KEY"
+_VERSION: Final[str] = "2023-06-01"
+# const-sync: ok -- a determinism requirement from AI spec §2, not a tunable.
+_TEMPERATURE: Final[float] = 0.0
+#: The Messages API requires `max_tokens`. When the caller's budget sets no
+#: token cap there is still a number to send, so the request is bounded rather
+#: than open-ended -- an unbounded generation against a per-token price is the
+#: failure the budget exists to prevent.
+_FALLBACK_MAX_TOKENS: Final[int] = 4_096
+
+
+class AnthropicAdapter:
+    """Realizes `api.Adapter` structurally over the Messages API."""
+
+    id: str = "anthropic"
+    kind: str = "hosted"
+
+    def __init__(self, *, model: str, api_key: str | None) -> None:
+        self._model = model
+        #: The content blocks of the previous assistant turn, kept so a
+        #: `tool_result` has the `tool_use` it answers. Per-run state: the
+        #: runner builds one adapter per `run()`, so this never spans runs.
+        self._previous_assistant: list[dict[str, object]] | None = None
+        self._api_key = api_key
+
+    def model(self) -> str:
+        return self._model
+
+    def params_hash(self) -> str:
+        """Excludes the credential: a hash of a secret is a lookup away from it."""
+        material = f"{self.id}|{_URL}|{self._model}|{_TEMPERATURE}|{_VERSION}"
+        return hashlib.sha256(material.encode("utf-8")).hexdigest()
+
+    def complete(
+        self,
+        *,
+        system: str,
+        user: str,
+        tools: list[ToolSpec],
+        tool_results: list[Mapping[str, Any]],
+        max_tokens: int | None,
+    ) -> AdapterResponse:
+        # A `tool_result` must answer a `tool_use` the API has already seen, in
+        # an assistant turn of the same conversation. Sending the result on its
+        # own -- which this adapter did until the first real-model run -- is a
+        # 400 every time, and it is why conformance cases 4 and 6 reported
+        # `status='error'` after the tool had demonstrably been invoked.
+        #
+        # The seam's signature does not carry conversation history and does not
+        # need to: `build_adapter` is called once per `run()`, so the adapter
+        # instance spans every turn of that run and can remember the assistant
+        # turn it just received. Keeping it here rather than widening `complete`
+        # is deliberate -- the history is a *provider wire* concern, and `02`
+        # §10.1's Protocol stays exactly as declared.
+        messages: list[dict[str, Any]] = [
+            {"role": "user", "content": [{"type": "text", "text": user}]}
+        ]
+        if tool_results and self._previous_assistant is not None:
+            messages.append({"role": "assistant", "content": self._previous_assistant})
+            messages.append(
+                {
+                    "role": "user",
+                    "content": [
+                        {
+                            "type": "tool_result",
+                            "tool_use_id": str(result["id"]),
+                            # `json.dumps`, not `str`: the payload is a dict, and
+                            # `str` renders Python repr with single quotes, which
+                            # is not JSON and is not what the model was shown.
+                            "content": _render(result["content"]),
+                        }
+                        for result in tool_results
+                    ],
+                }
+            )
+
+        payload: dict[str, Any] = {
+            "model": self._model,
+            "system": system,
+            "messages": messages,
+            "max_tokens": max_tokens or _FALLBACK_MAX_TOKENS,
+            "temperature": _TEMPERATURE,
+        }
+        if tools:
+            payload["tools"] = [
+                {
+                    "name": tool.name,
+                    "description": tool.description,
+                    "input_schema": tool.input_schema,
+                }
+                for tool in tools
+            ]
+
+        headers = {"anthropic-version": _VERSION}
+        if self._api_key:
+            headers["x-api-key"] = self._api_key
+        body = post_json(_URL, payload, headers, adapter_id=self.id)
+        blocks = body.get("content")
+        # Kept verbatim rather than rebuilt from the normalized response: a
+        # `tool_use` block echoed back with its `id` and `input` reconstructed by
+        # us is a different block, and the API matches on what it sent.
+        self._previous_assistant = blocks if isinstance(blocks, list) else None
+        return _to_response(body)
+
+
+def _render(content: object) -> str:
+    """A tool payload as JSON text, never as a Python repr."""
+    return content if isinstance(content, str) else json.dumps(content, sort_keys=True)
+
+
+def _to_response(body: Mapping[str, Any]) -> AdapterResponse:
+    """Normalize one turn, refusing a shape this adapter cannot read.
+
+    Refusing rather than defaulting to empty text matters: an unreadable
+    response silently read as "no text, no tool calls" ends the seam's loop and
+    returns `ok`, which is a wrong answer dressed as a successful run.
+    """
+    blocks = body.get("content")
+    if not isinstance(blocks, list):
+        raise AdoptError(
+            ErrorCode.AGENT_PROVIDER_ERROR,
+            message="anthropic returned no content blocks",
+            hint="The endpoint answered with a shape this adapter cannot read.",
+        )
+
+    texts: list[str] = []
+    calls: list[ToolCall] = []
+    for block in blocks:
+        if block.get("type") == "text":
+            texts.append(str(block.get("text") or ""))
+        elif block.get("type") == "tool_use":
+            arguments = block.get("input")
+            calls.append(
+                ToolCall(
+                    id=str(block.get("id") or "call"),
+                    name=str(block.get("name") or "unknown"),
+                    arguments=arguments if isinstance(arguments, dict) else {},
+                )
+            )
+
+    usage = body.get("usage") or {}
+    return AdapterResponse(
+        text="".join(texts),
+        tool_calls=calls,
+        input_tokens=int(usage.get("input_tokens") or 0),
+        output_tokens=int(usage.get("output_tokens") or 0),
+    )
+
+
+def build(*, model: str | None, endpoint: str | None) -> AnthropicAdapter:
+    if not model:
+        raise AdoptError(
+            ErrorCode.AGENT_ADAPTER_UNKNOWN,
+            message="ADOPT_MODEL is unset and this adapter has no default model",
+            hint="Model selection is configuration, never code (AI spec §2).",
+        )
+    return AnthropicAdapter(model=model, api_key=os.environ.get(_KEY_ENV))

adopt_agent/adapters/base.py

@@ -0,0 +1,140 @@
+"""The adapter registry and the offline gate. AI spec §2.
+
+**The offline gate runs before the import, not before the request.** F13.7 says a
+hosted adapter under offline mode raises "before any socket opens", and the
+strongest available reading is stronger than that: this module refuses *before
+the adapter module is even imported*, so no provider code loads, no client is
+constructed and no connection pool exists. That also keeps `adopt` cold-start
+inside `CLI_COLD_START_MS` -- nothing provider-shaped is imported by `adopt
+version`.
+
+**Adapters are resolved by name through a lazy import.** The registry maps an id
+to a module path and `build_adapter` imports it on demand. `no-provider-sdk`
+still sees every import edge statically, so the contract loses nothing: the
+rule is about *where* a provider client may be imported, and every one of them
+is under `adopt_agent.adapters`.
+
+**There is no fallback.** AI spec §2: if the configured adapter is unavailable
+the seam raises. A silent substitution changes cost, behaviour and data
+residency without the operator knowing, and in a client environment that is a
+security-review finding rather than a convenience.
+
+**No model identifier appears anywhere in this package outside `prices.json`.**
+`ADOPT_MODEL` names the model and an adapter fails fast with
+`AGENT_ADAPTER_UNKNOWN` when it is absent. A hard-coded default is how a tool
+aimed at every lab acquires a house lab.
+"""
+
+import importlib
+from typing import Final, Protocol
+
+from adopt_agent.api import Adapter, AdapterInfo, AdapterKind
+from adopt_obs import AdoptError, ErrorCode
+
+__all__ = ["REGISTRY", "AdapterFactory", "build_adapter", "describe_adapters"]
+
+
+class AdapterFactory(Protocol):
+    """What every adapter module exposes as `build`."""
+
+    def __call__(self, *, model: str | None, endpoint: str | None) -> Adapter: ...
+
+
+class _Entry:
+    """One registry row: the kind, and where the code lives."""
+
+    def __init__(self, kind: AdapterKind, module: str, *, needs_endpoint: bool = False) -> None:
+        self.kind = kind
+        self.module = module
+        self.needs_endpoint = needs_endpoint
+
+
+#: AI spec §2's registry, verbatim in its ids and kinds.
+#:
+#: `fake_recorded` is `test`, **not** `local`. That typing is load-bearing: the
+#: `conformance-matrix` gate requires at least one *local* adapter green, and if
+#: the recorded fake counted as local then a pipeline exercising no real model at
+#: all would satisfy the gate whose entire purpose is to prove one was exercised.
+REGISTRY: Final[dict[str, _Entry]] = {
+    "anthropic": _Entry("hosted", "adopt_agent.adapters.anthropic"),
+    "openai": _Entry("hosted", "adopt_agent.adapters.openai"),
+    "local_openai": _Entry("local", "adopt_agent.adapters.local_openai", needs_endpoint=True),
+    "fake_recorded": _Entry("test", "adopt_agent.adapters.fake_recorded"),
+}
+
+
+def _unknown(adapter_id: str) -> AdoptError:
+    return AdoptError(
+        ErrorCode.AGENT_ADAPTER_UNKNOWN,
+        message=f"no adapter is registered as {adapter_id!r}",
+        hint=f"Registered adapters: {', '.join(sorted(REGISTRY))}.",
+    )
+
+
+def _offline_denied(adapter_id: str) -> AdoptError:
+    return AdoptError(
+        ErrorCode.AGENT_OFFLINE_ADAPTER_DENIED,
+        message=f"{adapter_id!r} is a hosted adapter and this process is offline",
+        hint=(
+            "Offline is the default (contracts §1.7). Pass --allow-network, or use "
+            "the local adapter, which is always available offline. Nothing was sent: "
+            "the refusal happens before the adapter module is imported."
+        ),
+    )
+
+
+def _unavailable_reason(
+    entry: _Entry, *, offline: bool, model: str | None, endpoint: str | None
+) -> str | None:
+    """Why this adapter cannot be used right now, or `None` if it can.
+
+    Three different causes with three different fixes -- an offline denial, a
+    missing endpoint and an unset model -- so `AdapterInfo.reason` says which.
+    Reporting a bare `available: false` would leave an operator guessing.
+    """
+    if offline and entry.kind == "hosted":
+        return "hosted adapter denied under offline mode (ADOPT_OFFLINE)"
+    if entry.needs_endpoint and not endpoint:
+        return "ADOPT_ADAPTER_ENDPOINT is not set"
+    if entry.kind != "test" and not model:
+        return "ADOPT_MODEL is not set; the seam never picks a model for you"
+    return None
+
+
+def describe_adapters(
+    *, offline: bool, model: str | None = None, endpoint: str | None = None
+) -> list[AdapterInfo]:
+    """Contracts §14's `adapters[{id, kind, available, reason}]`, unshaped.
+
+    Reports every registered adapter rather than only the usable ones: an
+    operator asking "why can I not use Anthropic" needs the row that says so.
+    """
+    infos: list[AdapterInfo] = []
+    for adapter_id in sorted(REGISTRY):
+        entry = REGISTRY[adapter_id]
+        reason = _unavailable_reason(entry, offline=offline, model=model, endpoint=endpoint)
+        infos.append(
+            AdapterInfo(id=adapter_id, kind=entry.kind, available=reason is None, reason=reason)
+        )
+    return infos
+
+
+def build_adapter(
+    adapter_id: str, *, offline: bool, model: str | None = None, endpoint: str | None = None
+) -> Adapter:
+    """Resolve and construct one adapter, or raise.
+
+    The offline check is the **first** thing that happens after the id is
+    recognised, and it happens before `import_module`. That ordering is what
+    makes "no socket opened" provable by the blocked-socket harness rather than
+    argued from reading the adapter's code.
+    """
+    entry = REGISTRY.get(adapter_id)
+    if entry is None:
+        raise _unknown(adapter_id)
+    if offline and entry.kind == "hosted":
+        raise _offline_denied(adapter_id)
+
+    module = importlib.import_module(entry.module)
+    factory: AdapterFactory = module.build
+    return factory(model=model, endpoint=endpoint)