loom-kernel 1.9.0__tar.gz → 1.9.2__tar.gz

{loom_kernel-1.9.0 → loom_kernel-1.9.2}/CHANGELOG.md

@@ -1,3 +1,63 @@
+# 🚀 Release 1.9.2 ([#157](https://github.com/the-reacher-data/loom-py/pull/157)) ([`3b32161`](https://github.com/the-reacher-data/loom-py/commit/3b32161dfcfe12fe25fe05ff7ccb4d6a71a6b64a))
+
+
+
+## 🐛 Fixes
+### ai
+- **ai:** make outbound auth work for MCP and let a grant boot offline
+
+
+
+
+
+
+
+
+# 🚀 Release 1.9.1 ([#155](https://github.com/the-reacher-data/loom-py/pull/155)) ([`587affc`](https://github.com/the-reacher-data/loom-py/commit/587affcfbf46301ccd3e02a5edeb34e63b460628))
+
+
+## ✨ Features
+### rest
+- **rest:** let an application whose only content is agents boot<br>
+  > Reported from downstream: an app whose manifest declares only AGENTS failed
+  > six times in a row on `create_app`, each message naming a symptom rather than
+  > the cause ("no module named 'sqlalchemy'", "No UseCase classes discovered.",
+  > "the greenlet library is required...").
+  > `persistence.backend: none`: no unit of work, no repositories, no model
+  > compilation, `database:` ignored. `sqlalchemy` stays the default and its
+  > no-models error now names the way out.
+  > `create_app` imports the SQLAlchemy backend lazily, inside the wiring that
+  > needs it, so the `sqlalchemy` extra is no longer required to import it.
+  > One discovery guard instead of three: an app fails only when it has no use
+  > case, no interface and no agent, and every discovery error now names
+  > `app.discovery.mode: manifest` and `AGENTS`.
+  > `ai.models.<role>.output_mode: tool | native` pins the structured-output
+  > mode a deployment needs; absent keeps the engine's own resolution.
+  > The AWS resolvers log and report the key as written, never the `%VAR%`
+  > expanded path, and split dot-notation before expanding so an environment
+  > value can never introduce a JSON separator or reach an error message.
+  > Fetch errors carry the AWS error code instead of the client's message.
+  > Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
+  > Claude-Session: https://claude.ai/code/session_016xY1skW5S2PU9Fc3M7tfAW
+
+
+
+
+
+
+
+
+## ✅ Tests
+### quality
+- **quality:** clear the SonarCloud findings of the agents-only slice<br>
+  > The quality gate failed on one reliability issue: the subprocess helper
+  > asserted inside a `try` whose `except Exception` also catches
+  > `AssertionError`, so a failed check reported itself as a caught error
+  > (S5779). It raises `RuntimeError` now, and the block check does too.
+
+
+
+
 # 🚀 Release 1.9.0 ([#154](https://github.com/the-reacher-data/loom-py/pull/154)) ([`22d9a89`](https://github.com/the-reacher-data/loom-py/commit/22d9a894c766d2414ee6607e990b6473dd5ebfe3))
 
 

{loom_kernel-1.9.0 → loom_kernel-1.9.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: loom-kernel
-Version: 1.9.0
+Version: 1.9.2
 Summary: Loom Python project
 License-File: LICENSE
 Classifier: Typing :: Typed

{loom_kernel-1.9.0 → loom_kernel-1.9.2}/docs/ai/a2a.md

@@ -88,11 +88,16 @@ session. An agent that authenticates its card endpoint would otherwise fail
 start-up before a skill was ever called.
 
 `kind` names an entry point in the group `loom.ai.remote_auth`, the same group
-MCP servers resolve against: the strategy contract is
-[`httpx.Auth`](https://www.python-httpx.org/advanced/authentication/), which
-knows nothing of either protocol, so a deployment registers its strategy once
-and grants it to either transport. The one strategy an A2A agent cannot use is
-`kind: oauth`, which delegates to the MCP client library's own flow; naming it
+MCP servers resolve against: the strategy contract is the HTTP client's own
+[`Auth`](https://www.python-httpx.org/advanced/authentication/), which knows
+nothing of either protocol, so a deployment registers its strategy once and
+grants it to either transport. The A2A client is loom's own, built with `httpx`,
+while an MCP server is reached through a client using `httpx2` — a strategy
+registered as a class is refused by the other flavour, and a strategy returning
+a plain callable serves both: see
+[mcp.md § Two HTTP libraries, one callable](mcp.md#two-http-libraries-one-callable).
+
+The one strategy an A2A agent cannot use is `kind: oauth`, which delegates to the MCP client library's own flow; naming it
 here is refused with `MCP_AUTH_STRATEGY_INVALID` rather than connecting without
 the credential the deployment asked for.
 

{loom_kernel-1.9.0 → loom_kernel-1.9.2}/docs/ai/mcp.md

@@ -106,6 +106,58 @@ rejected fail-closed.
 Tool filters are matched against the tools the server really advertises, not
 against what the artifact hoped for.
 
+### Booting without the network: `ai.remote_clients`
+
+Granting `kind: mcp` makes every server the grant names a start-up dependency.
+That is right in production and awkward everywhere else — a laptop, a CI job, an
+environment brought up before its side-cars. `ai.remote_clients` says how a
+client that will not open is treated:
+
+```yaml
+ai:
+  remote_clients: optional     # required (default) | optional
+```
+
+| Value | A client that fails to *connect* |
+|---|---|
+| `required` (default) | Aborts start-up, by name, with `MCP_SERVER_UNREACHABLE` — or `A2A_AGENT_UNREACHABLE` for a remote agent. |
+| `optional` | Logged at WARNING and dropped; the runtime starts without it. |
+
+The switch is process-wide and covers the remote agents of `ai.a2a_agents` as
+well as the servers of `ai.mcp_servers`. An unknown value fails configuration
+load with `REMOTE_CLIENTS_UNKNOWN`, naming the key and both accepted values.
+
+Under `optional`, the WARNING carries the error code and the registered name
+only: the transport's own reason is an arbitrary library's exception text and
+can name a URL, so it goes to DEBUG, where an operator asks for it deliberately,
+rather than into routine logs on every boot. The health probe reports the
+dependency `unavailable` once its first pass has run.
+
+`optional` tolerates a network that is not there. It tolerates nothing else, and
+three carve-outs are deliberate:
+
+**A missing client factory is still fatal.** A plan declaring an `mcp` grant in a
+deployment that wired no MCP client factory is a wiring bug, not an offline
+network. It is collected apart, where the factory is found missing, never told
+from a connection failure by reading its message, and aborts start-up under
+**both** values.
+
+**Tool-filter verification still fails closed for a server that did open.** The
+waiver covers only servers that never connected: a server with no session is
+skipped, and a filter on it does not fail start-up. A server that opened has its
+declared filters verified as usual, and a listing that times out still aborts
+start-up under `optional`. Because a tolerated connection failure has already
+spent the shared start-up budget, the verification pass is given a fresh
+`startup_timeout_ms` rather than the exhausted one — otherwise one hanging
+server would fail the filters of every server that answered.
+
+**Nothing becomes lazy.** A start-up client that never opened is not reconnected
+later; the clients are session-affine and closing one from a foreign task is
+refused, so reconnecting them needs a supervisor task that does not exist yet.
+This says nothing about the run path, which builds its own toolset and connects
+on its own: under `optional`, a run against a server that never opened at
+start-up connects then and there, and succeeds if the network came back.
+
 ## Authentication
 
 The MCP specification standardises OAuth 2.0 for HTTP transports, so an
@@ -187,12 +239,62 @@ loom writes the header.
 set credentials on one connection is ambiguous, and compilation refuses it with
 `MCP_AUTH_CONFLICT`.
 
+### Two HTTP libraries, one callable
+
+A strategy is handed to an HTTP client, and the two outbound transports do not
+use the same one.
+
+An `mcp` grant becomes a pydantic-ai `MCPToolset`, which connects through one of
+fastmcp's HTTP transports — `StreamableHttpTransport`, or `SSETransport` when the
+URL ends in `/sse`. Those transports special-case OAuth and pass any other auth
+object straight through to their client, and their client is **`httpx2`**. An
+`a2a` grant goes to a client loom builds itself, with **`httpx`**.
+
+Each library accepts an auth object only when it is an instance of *its own*
+`Auth` class, a two-tuple, or a callable. So an `httpx.Auth` subclass is refused
+by the MCP transport's client, and an `httpx2.Auth` subclass by the A2A one.
+**Loom adapts neither**, and publishes no recipe for a class that satisfies both
+at once: nothing in its test suite would keep such a recipe honest.
+
+| Grant | Client library | A class must subclass |
+|---|---|---|
+| `kind: mcp` | `httpx2`, reached through fastmcp's transport | `httpx2.Auth` |
+| `kind: a2a` | `httpx`, in the client loom builds | `httpx.Auth` |
+
+**A plain callable is the supported answer for both.** Each library wraps a
+callable in a `FunctionAuth` of its own, so one function serves either transport
+— and whatever flavour either library moves to next. It takes the outgoing
+request, sets its headers, and **returns** it:
+
+```python
+def incident_api_key(*, key_ref: str):
+    """Register this as a strategy: it returns the callable both clients wrap."""
+
+    def add_key(request):
+        request.headers["X-API-Key"] = key_ref
+        return request
+
+    return add_key
+```
+
+Returning the request is not optional: the wrapper's flow is
+`yield self._func(request)`, so a callable returning `None` sends `None`.
+Nothing in the inner signature names a library, which is exactly the point — the
+request it receives is of whichever flavour drove it. The two strategies loom
+ships, `bearer` and `static`, are this shape.
+
+A callable is a single-shot flow: it never sees the response, so it cannot
+inspect a `401` or renew. A strategy that needs the response is a class.
+
 ### Writing your own
 
-The contract is [`httpx.Auth`](https://www.python-httpx.org/advanced/authentication/)
-itself, not an abstraction of loom's — nobody has to learn one of ours, and any
-existing `httpx.Auth` in the ecosystem works with no adapter. Register the class
-from **your own package**; loom does not change:
+The contract is the HTTP client's own
+[`Auth`](https://www.python-httpx.org/advanced/authentication/), not an
+abstraction of loom's — nobody has to learn one of ours, and an existing `Auth`
+class works with no adapter, provided it is the flavour of the transport that
+will use it (above). This example authenticates an MCP server, so it subclasses
+`httpx2.Auth`; the identical class written for an A2A agent subclasses
+`httpx.Auth`. Register it from **your own package**; loom does not change:
 
 ```toml
 # pyproject.toml of your own distribution
@@ -204,10 +306,10 @@ A worked example — a server exposing a session endpoint, where the agent
 presents a long-lived bootstrap secret and receives short-lived tokens:
 
 ```python
-import httpx
+import httpx2       # the flavour the MCP transport's client uses
 
 
-class AgentSessionAuth(httpx.Auth):
+class AgentSessionAuth(httpx2.Auth):
     """Exchange a bootstrap secret for a token, renewed when rejected."""
 
     def __init__(self, *, session_url: str, bootstrap_ref: str) -> None:
@@ -226,14 +328,22 @@ class AgentSessionAuth(httpx.Auth):
             yield request
 
     def _mint(self):
-        response = yield httpx.Request(
+        response = yield httpx2.Request(
             "POST", self._url, json={"secret_path": self._ref}
         )
         return response.json()["access_token"]
 ```
 
-Retry-with-a-refreshed-credential is httpx's standard generator shape; loom does
-not reimplement it.
+Retry-with-a-refreshed-credential is the library's standard generator shape;
+loom does not reimplement it.
+
+```{warning}
+`requires_response_body` is honoured by `Auth`'s **own** base flow, not by the
+client. A strategy that overrides `async_auth_flow` — which any asynchronous
+token exchange must — replaces the very code that reads the flag, and has to
+`await response.aread()` itself before touching the body. Setting the attribute
+and overriding the flow leaves the body unread, silently.
+```
 
 If you are designing such an endpoint: this is OAuth 2.0 `client_credentials`
 by another name — `secret_path` is the client id and the bootstrap secret is the
@@ -256,11 +366,12 @@ server's read permissions to that prefix and log failed attempts per path.
 
 The group is `loom.ai.remote_auth`, not `loom.ai.mcp_auth`: one registry serves
 the MCP servers of `ai.mcp_servers` **and** the remote agents of `ai.a2a_agents`
-(see [a2a.md](a2a.md)), because the contract is `httpx.Auth` and knows neither
-protocol. A strategy is registered once and granted to either. The one
-exception is `kind: oauth`, which delegates to the MCP client library's own
-flow: an A2A agent naming it is refused with `MCP_AUTH_STRATEGY_INVALID` rather
-than connected without a credential.
+(see [a2a.md](a2a.md)), because the contract is the HTTP client's and knows
+neither protocol. A strategy returning a callable is registered once and granted
+to either; one registered as a class is granted to the transports of its own
+flavour. The one exception is `kind: oauth`, which delegates to the MCP client
+library's own flow: an A2A agent naming it is refused with
+`MCP_AUTH_STRATEGY_INVALID` rather than connected without a credential.
 
 ### One instance per server
 
@@ -270,6 +381,22 @@ renewing strategy holds the live token, so sharing means one renewal instead of
 one per agent, and no burst of simultaneous logins when several agents start
 together.
 
+What is shared is what the strategy returned. A class instance is shared as
+itself, so a strategy that must renew once, for everybody, stays a class and
+keeps that identity. A callable is shared as itself too, but each client wraps
+it in a `FunctionAuth` of its own, so two clients built from one credential no
+longer hold the same `client.auth` object — they hold two wrappers around one
+function. For a fixed header that is a distinction without a difference, and it
+is the reason a stateful strategy is a class.
+
+```{admonition} Public contract
+:class: note
+`shared_mcp_auth` and `shared_a2a_auth` are exported, and their return type has
+widened from `httpx.Auth | str` to what a client accepts, which now includes a
+callable. Code doing `isinstance(value, httpx.Auth)` on the result stops
+matching for the built-in `bearer` and `static` strategies.
+```
+
 ## The rule: your own tools are a `usecase` grant
 
 Here is the decision that actually comes up, and the one this page exists for.

{loom_kernel-1.9.0 → loom_kernel-1.9.2}/docs/ai/overview.md

@@ -96,6 +96,74 @@ Every agent matched by `specs` is compiled. Only the agents named in
 agent absent from `endpoints` exists in the process and is reachable by nobody.
 Exposure is always an explicit opt-in, never a default.
 
+## An application that is only agents
+
+An application does not need a model, a use case or a REST interface to run an
+agent. Its manifest module declares `AGENTS` and nothing else, discovery runs in
+`manifest` mode, and persistence is switched off:
+
+```python
+# myapp/manifest.py
+AGENTS = ["agents/*.yaml"]          # globs resolve against app.code_path
+```
+
+```yaml
+# config/api.yaml
+app:
+  name: incident-triage
+  discovery:
+    mode: manifest
+    manifest:
+      module: myapp.manifest
+
+persistence:
+  backend: none
+
+ai:
+  engine: pydantic-ai
+  models:
+    default:
+      provider: bedrock
+      model: <model id>
+      region: eu-west-1
+      output_mode: native          # optional, see Model providers
+  endpoints:
+    incident-triage:
+      enabled: true
+      auth: jwt
+```
+
+```bash
+pip install "loom-kernel[rest,ai-pydantic,ai-bedrock]"   # swap the provider extra for yours
+```
+
+The `sqlalchemy` extra is not needed: `create_app` imports the SQLAlchemy backend
+only inside the `sqlalchemy` wiring, so an agents-only process never loads it.
+(`loom.celery` still imports it at module level; this recipe is about the REST
+application, not every loom module.)
+
+What `persistence.backend: none` means:
+
+- No unit of work and no repositories. A granted `usecase` capability still
+  runs through the kernel executor, just without a transaction around it.
+- Discovered models are accepted but **not compiled**, and they get no
+  repository. Declaring them under `none` is harmless and pointless.
+- A `database:` section is ignored, silently.
+- Deferred job dispatch does not fire. `JobService.dispatch` queues the call to
+  run after the unit of work commits, and with no unit of work nothing flushes
+  the queue, so a job dispatched from a use case is dropped without an error.
+  An agents-only application that needs background jobs keeps a real backend.
+
+Only `manifest` discovery can describe this application: the `interfaces` and
+`modules` engines require at least one module path, and their errors — like the
+`RuntimeError` raised when discovery finds no use case, no interface and no
+agent — say so by naming `app.discovery.mode: manifest` and `AGENTS`.
+
+`persistence.backend` still defaults to `sqlalchemy`; loom never infers `none`
+from the absence of models or of a `database:` section. Leaving the default
+in place with no models fails start-up with a message that names
+`persistence.backend: none` as the way out.
+
 ## Where to go next
 
 - **[Artifact reference](artifacts.md)** — the complete `spec_version: 1`

{loom_kernel-1.9.0 → loom_kernel-1.9.2}/docs/ai/providers.md

@@ -118,7 +118,7 @@ redacts itself:
 
 ```pycon
 >>> print(target)
-InferenceTarget(provider='bedrock', model='anthropic.claude-sonnet-4-...', region='eu-west-1', endpoint=None, credentials_ref=<redacted>, options=<redacted>)
+InferenceTarget(provider='bedrock', model='anthropic.claude-sonnet-4-...', region='eu-west-1', endpoint=None, output_mode=None, credentials_ref=<redacted>, options=<redacted>)
 ```
 
 and **refuses** to be serialised at all when it carries a secret reference —
@@ -148,6 +148,44 @@ ai:
 `options` is confined to the deployment configuration and, like
 `credentials_ref`, never reaches the artifact and never survives serialisation.
 
+## Pinning the structured-output mode
+
+Every agent answers with a structured object, and the engine has more than one
+way of asking a model for it. Left alone, the engine picks the mode per
+provider and model. When that choice is wrong for a particular model — it
+accepts tool calls but not a native JSON-schema response, or the reverse — the
+binding pins it with `output_mode`:
+
+| `output_mode` | The engine asks for the answer as | When to set it |
+|---|---|---|
+| *absent* | whatever the engine resolves for that provider and model | the default; leave it unless a run fails at the provider |
+| `tool` | a tool call whose arguments carry the object | the model supports tool calling and rejects the native mode |
+| `native` | the provider's own structured-output response | the model supports structured output and misbehaves with the tool mode |
+
+```yaml
+ai:
+  models:
+    reasoning:
+      provider: bedrock
+      model: <model id>
+      region: eu-west-1
+      output_mode: tool
+```
+
+The mode is per binding and per deployment: the artifact never sees it, and
+loom does not infer it per provider. Two consequences follow from that:
+
+- An unknown value fails **start-up** with `OUTPUT_MODE_UNKNOWN`, naming the
+  role and the two values loom offers. `prompted` is deliberately not one of
+  them: the engine strips markdown fences before validating a prompted answer,
+  while loom decodes the raw text part, so a fenced answer would pass the
+  engine and fail loom.
+- A mode the model rejects at **request time** is a provider refusal, and it
+  surfaces as `PROVIDER_UNAVAILABLE`. The provider's detail stays server-side,
+  in the logs; the caller sees the code. Loom cannot check a mode against a
+  model before the first request, so a wrong pin is found there, not at
+  start-up.
+
 ## What does not happen
 
 **No fallback routing.** An exhausted or failing provider fails the run. It is

{loom_kernel-1.9.0 → loom_kernel-1.9.2}/docs/getting-started/rest.md

@@ -372,6 +372,26 @@ discovery:
     module: app.manifest
 ```
 
+### Choose the persistence backend
+
+`database:` is read by the default backend. `persistence.backend` selects it:
+
+| `persistence.backend` | Reads | What the app gets |
+|---|---|---|
+| `sqlalchemy` (default) | `database:` | unit of work, repositories and compiled tables for every discovered model; requires at least one model and the `sqlalchemy` extra |
+| `dynamodb` | `persistence.dynamodb:` | the DynamoDB repositories, no relational tables |
+| `none` | nothing | no unit of work, no repositories; discovered models are accepted but not compiled, a `database:` section is ignored, and deferred job dispatch never fires |
+
+```yaml
+persistence:
+  backend: none
+```
+
+`none` is for an application whose only content is agents (see
+[An application that is only agents](../ai/overview.md#an-application-that-is-only-agents)).
+It is never inferred: with the default backend and no discovered models,
+start-up fails with a message that names `persistence.backend: none`.
+
 ---
 
 ## Rules + Computes (advanced)

{loom_kernel-1.9.0 → loom_kernel-1.9.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "loom-kernel"
-version = "1.9.0"
+version = "1.9.2"
 description = "Loom Python project"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -362,7 +362,7 @@ markers = [
 
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "1.9.0"
+version = "1.9.2"
 tag_format = "v$version"
 version_files = [
     "pyproject.toml:project.version",

{loom_kernel-1.9.0 → loom_kernel-1.9.2}/src/loom/ai/config.py

@@ -31,9 +31,11 @@ from loom.ai.errors import (
     mcp_auth_strategy_unknown,
     mcp_credentials_inline,
     mcp_url_invalid,
+    output_mode_unknown,
     policy_out_of_range,
+    remote_clients_unknown,
 )
-from loom.ai.inference import InferenceTarget
+from loom.ai.inference import OUTPUT_MODES, InferenceTarget
 from loom.ai.remote_auth import is_strategy_registered, registered_strategy_names
 from loom.core.model import LoomFrozenStruct
 
@@ -54,6 +56,11 @@ _URL_USERINFO_RE = re.compile(r"://[^/]*@")
 # key is that strategy's own setting.
 _AUTH_KIND_KEY = "kind"
 
+# Accepted values of ``ai.remote_clients``: whether a remote client that will
+# not open aborts start-up (``required``) or is dropped with a warning
+# (``optional``).
+_REMOTE_CLIENTS_MODES: tuple[str, ...] = ("required", "optional")
+
 # Bounds of a single remote call, mirroring ``policies.tool_timeout_ms``.
 _TIMEOUT_MS_MIN = 1
 _TIMEOUT_MS_MAX = 600000
@@ -168,6 +175,8 @@ def _validate_model_binding(role: str, target: InferenceTarget) -> list[AgentCom
     for setting in required:
         if not getattr(target, setting):
             issues.append(inference_target_incomplete(role, setting))
+    if target.output_mode is not None and target.output_mode not in OUTPUT_MODES:
+        issues.append(output_mode_unknown(role, target.output_mode, OUTPUT_MODES))
     ref = target.credentials_ref
     if ref is not None and not _is_credentials_reference(ref):
         # The rejected value is deliberately absent from the issue: the error
@@ -296,6 +305,15 @@ class AiConfig(LoomFrozenStruct, frozen=True, kw_only=True):
         startup_timeout_ms: Total budget of start-up: opening every live
             client concurrently and validating the declared tool filters
             share one deadline, whatever the number of servers.
+        remote_clients: Start-up tolerance for the MCP servers and A2A agents
+            the deployment connects to, ``required`` (the default) or
+            ``optional``.  Under ``optional`` a client that fails to *connect*
+            is logged and dropped instead of aborting start-up, so an
+            application can boot with no network.  It tolerates nothing else:
+            a missing client factory is a wiring bug and stays fatal, a server
+            that did open and whose tool listing times out still fails
+            start-up, and no client becomes lazy — one that never opened is
+            not reconnected later.
         max_concurrent_runs: Per-worker run limit (FR-033a).
         max_prompt_bytes: Enforced while reading the request body.
         health_cache_ttl_ms: Refresh period of the health probe.
@@ -304,8 +322,8 @@ class AiConfig(LoomFrozenStruct, frozen=True, kw_only=True):
         AgentCompilationError: Aggregating one issue per invalid model binding
             (incomplete provider settings, literal secret in
             ``credentials_ref``), per unsafe remote server or agent (bad URL,
-            inline credentials, out-of-range timeout) and per endpoint without
-            a named ``auth``.
+            inline credentials, out-of-range timeout), per endpoint without
+            a named ``auth``, and for an unknown ``remote_clients`` mode.
     """
 
     engine: str
@@ -317,6 +335,7 @@ class AiConfig(LoomFrozenStruct, frozen=True, kw_only=True):
     a2a: A2AConfig | None = None
     endpoints: dict[str, AgentEndpointConfig] = field(default_factory=dict)
     startup_timeout_ms: int = 10000
+    remote_clients: str = "required"
     max_concurrent_runs: int = 8
     max_prompt_bytes: int = 65536
     health_cache_ttl_ms: int = 5000
@@ -330,6 +349,8 @@ class AiConfig(LoomFrozenStruct, frozen=True, kw_only=True):
         for name, endpoint in self.endpoints.items():
             if not endpoint.auth.strip():
                 issues.append(endpoint_auth_missing(name))
+        if self.remote_clients not in _REMOTE_CLIENTS_MODES:
+            issues.append(remote_clients_unknown(self.remote_clients, _REMOTE_CLIENTS_MODES))
         if issues:
             raise AgentCompilationError(issues)
 

{loom_kernel-1.9.0 → loom_kernel-1.9.2}/src/loom/ai/engines/pydantic_ai/_mcp.py

@@ -26,7 +26,7 @@ from __future__ import annotations
 
 from collections.abc import AsyncIterator, Mapping
 from contextlib import asynccontextmanager
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, cast
 
 from loom.ai.compiler import CompiledMcpCapability
 from loom.ai.errors import AgentCompilationError, provider_not_installed
@@ -101,7 +101,12 @@ def build_mcp_toolset(capability: CompiledMcpCapability) -> MCPToolset[Any]:
     component = f"mcp server '{capability.server}'"
     headers = headers_from_ref(component, capability.headers_ref) or None
     auth = shared_mcp_auth(capability.server, capability.auth)
-    toolset: MCPToolset[Any] = MCPToolset(capability.url, headers=headers, auth=auth)
+    # ``MCPToolset`` annotates auth as ``httpx.Auth | Literal['oauth'] | str | None``,
+    # which admits no callable, while what really consumes it is fastmcp's HTTP
+    # transport: its ``_set_auth`` special-cases only ``"oauth"``, ``OAuth``, the
+    # OAuth providers and ``str``, and hands anything else to its ``httpx2`` client
+    # untouched — including the callable loom's own strategies return.
+    toolset: MCPToolset[Any] = MCPToolset(capability.url, headers=headers, auth=cast("Any", auth))
     return toolset
 
 

{loom_kernel-1.9.0 → loom_kernel-1.9.2}/src/loom/ai/engines/pydantic_ai/_spec.py

@@ -29,15 +29,21 @@ What is deliberately **not** projected:
 replays a failed *tool* call inside one run, loom's replays a failed
 *provider* call across runs. They share one artifact field on purpose — a
 single operator-facing knob — but neither enforcement subsumes the other.
+
+``output_mode`` (``ai.models.<role>``) is projected next to the spec rather than
+inside it: ``AgentSpec.output_schema`` has no mode field, so the mode travels as
+``Agent.from_spec(output_type=...)`` via :func:`build_output_type`. Absent, the
+engine keeps resolving the mode itself from ``output_schema``.
 """
 
 from __future__ import annotations
 
-from typing import Any
+from typing import Any, assert_never, cast
 
-from pydantic_ai import AgentSpec
+from pydantic_ai import AgentSpec, NativeOutput, StructuredDict, ToolOutput
 
 from loom.ai.compiler import AgentPlan
+from loom.ai.inference import OutputMode
 
 
 def build_agent_spec(plan: AgentPlan) -> AgentSpec:
@@ -45,7 +51,9 @@ def build_agent_spec(plan: AgentPlan) -> AgentSpec:
 
     ``output_schema`` instructs the model on the shape to produce; it does not
     validate the answer (research R-004), which is why the plan's decoder owns
-    validation at the boundary (see ``_output``).
+    validation at the boundary (see ``_output``). How the engine asks for that
+    shape (tool call or native structured output) is not part of the spec;
+    :func:`build_output_type` overrides it when the binding pins a mode.
 
     Args:
         plan: Compiled agent plan.
@@ -61,3 +69,44 @@ def build_agent_spec(plan: AgentPlan) -> AgentSpec:
         output_schema=schema,
         retries=plan.policies.retries,
     )
+
+
+def build_output_type(plan: AgentPlan) -> ToolOutput[Any] | NativeOutput[Any] | None:
+    """Pin the engine's output mode when the model binding declares one.
+
+    Wraps the plan's output schema in the engine's own marker, with no name
+    or description, so the engine builds the same ``StructuredDict`` it would
+    build from ``output_schema`` alone but with the mode fixed instead of
+    resolved per provider. The value has already been validated against
+    :data:`~loom.ai.inference.OUTPUT_MODES` when the config loaded.
+
+    The dispatch is exhaustive rather than defaulted: an unhandled mode fails
+    type checking here (``assert_never``) and raises at run time, so a value
+    that reached this point without the config check — a plan built in
+    process, a mode loom deliberately excludes such as ``prompted`` — cannot
+    be silently served as ``native``.
+
+    Args:
+        plan: Compiled agent plan.
+
+    Returns:
+        ``ToolOutput`` for ``tool``, ``NativeOutput`` for ``native``, ``None``
+        when the binding leaves the mode to the engine.
+
+    Raises:
+        AssertionError: The binding names a mode loom does not offer.
+    """
+    declared = plan.inference.output_mode
+    if declared is None:
+        return None
+    # The struct field is ``str`` (msgspec would reject a Literal during the
+    # decode, before the config check could name the role), so the narrowing
+    # happens here, where the dispatch below either handles the value or
+    # refuses it.
+    mode = cast("OutputMode", declared)
+    structured = StructuredDict(dict(plan.output.schema))
+    if mode == "tool":
+        return ToolOutput(structured)
+    if mode == "native":
+        return NativeOutput(structured)
+    assert_never(mode)