loom-kernel 2.4.0__tar.gz → 2.6.0__tar.gz

{loom_kernel-2.4.0 → loom_kernel-2.6.0}/CHANGELOG.md

@@ -4,6 +4,13 @@
 
 ### core
 
+- **core:** a memory cache alias can be bounded. `cache: max_size` (entries) and
+  the new `cache: max_bytes` (stored payload bytes) serve every
+  `aiocache.SimpleMemoryCache` alias through `loom.core.cache.memory.BoundedMemoryCache`,
+  which evicts least-recently-used entries past either bound. Before, `max_size`
+  failed at boot (aiocache's class does not accept it) and a memory alias grew
+  without limit. Redis and the other server backends are unaffected.
+
 - **core:** `loom.core.model` (module `_loom_type`) is the one module that decides whether
   a boundary type is a `msgspec.Struct` or a strict `pydantic.BaseModel`.
   `loom_type(symbol)` resolves an authored symbol by `issubclass`,
@@ -24,6 +31,43 @@
 
 ### ai
 
+- **ai:** `provider: typesafe` binds TypeSafe's Jev, a decision model that
+  fills a typed output from the state it is given and never writes text, so a
+  role whose answer is a choice or a verdict can run on it. Extra
+  `ai-typesafe` (pydantic-ai 2.45 or later); `credentials_ref` names the
+  variable holding the API key, `endpoint` overrides the base URL. pydantic-ai
+  fills a TypeSafe output by tool alone, so a binding pinning `output_mode:
+  native` fails start-up with the new `OUTPUT_MODE_UNSUPPORTED`, instead of
+  being refused by the model on every request.
+- **core:** `loom.core.plugins.optional.import_optional` is the one way loom
+  loads a module that needs an optional extra: the island imports its SDK
+  at the top, the selector loads the island by name, and the island's
+  `ImportError` becomes a `MissingExtraError` naming the extra. The rule is
+  written in `docs/architecture/clean-architecture.md`.
+- **ai:** each pydantic-ai provider is an island under
+  `loom.ai.engines.pydantic_ai.providers` (`bedrock`, `openai`, `anthropic`,
+  `gateway`, `typesafe`), and each optional extra of the engine one under
+  `loom.ai.engines.pydantic_ai.extras` (`mcp`, `a2a`, `skills`,
+  `handlebars`): the one module importing its SDK. `_models.py` keeps the
+  binding table and loads the island through `require_provider_sdk`, now a
+  reading of `import_optional`; the MCP toolset, the A2A client, the skills
+  capability and the templating check load theirs the same way. No
+  behaviour change: `PROVIDER_UNKNOWN`, `PROVIDER_NOT_INSTALLED`,
+  `PROVIDER_SETTING_MISSING` and `TEMPLATE_EXTRA_MISSING` fire exactly as
+  before.
+- **core:** boto3 is an island too, `loom.core.config._boto3`: the SSM and
+  Secrets Manager resolvers load it on first use and fail with `ConfigError`
+  naming `config-ssm` when it is absent, instead of a module-level `None`
+  sentinel checked later. `aiocache` and `prometheus-client` are required
+  dependencies, so `CacheGateway` and `ObservabilityRuntime` import them at
+  the top like any other, dropping an `importlib.import_module("aiocache")`
+  and a `None` sentinel that guarded nothing. Tests that stood in for an
+  absent or stubbed SDK now go through `tests/helpers/extras.py`.
+- **ai:** `AgentAnswer`, `AgentResult` and the `final` event carry `provider_details`: what
+  the provider reported about the final answer beyond the answer itself,
+  verbatim — Jev's confidence and probabilities per field, another
+  provider's finish reason — or `None`. In process only: the `/run` body and
+  the `final` frame keep their four keys, as `messages` taught them to.
 - **ai:** `output.type_ref` and `deps_type` accept a strict
   `pydantic.BaseModel` (`model_config["extra"] == "forbid"`) wherever they
   accept a `msgspec.Struct`. A pydantic output is handed to pydantic-ai as
@@ -123,6 +167,23 @@
   The `etl-polars` extra now requires `polars>=1.24`, the release that
   named that join option `nulls_equal`.
 
+- **etl:** `storage.temp.storage_options` reaches the checkpoint write. A
+  pipeline declaring `aws_server_side_encryption` / `aws_sse_kms_key_id` /
+  `aws_sse_bucket_key_enabled` for its temporaries wrote them with the bucket
+  default encryption and said nothing: the filter guarding the fsspec cleanup
+  returned an empty mapping unless an `endpoint_url` was set, and forwarded
+  only endpoint and credentials when it was. The encryption options now
+  survive that filter with or without an endpoint, in either spelling
+  (lowercase or uppercase), and reach both halves of the atomic write — the
+  `sink_ipc` through object_store under their own names, and the rename, a
+  server-side copy, as `s3_additional_kwargs` botocore parameters. The read
+  path is untouched, decryption being server-side. Any other key of the
+  delta-rs mapping is still dropped, now logged at debug; the Spark checkpoint
+  backend cannot take them at all (it reads SSE from Hadoop's S3A conf) and
+  logs a warning when encryption is declared. The declared mapping is parsed
+  once, so the two halves never disagree: `aws_sse_bucket_key_enabled: "false"`
+  (or `"yes"`, `"on"`, `"1"`) yields the same flag on either side.
+
 ### ai
 
 - **ai:** an MCP session that dies after it opened no longer fails every later

{loom_kernel-2.4.0 → loom_kernel-2.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: loom-kernel
-Version: 2.4.0
+Version: 2.6.0
 Summary: Loom Python project
 License-File: LICENSE
 Classifier: Typing :: Typed
@@ -27,6 +27,8 @@ Provides-Extra: ai-pydantic
 Requires-Dist: pydantic-ai-slim<3,>=2; extra == 'ai-pydantic'
 Provides-Extra: ai-templates
 Requires-Dist: pydantic-ai-slim[spec]<3,>=2; extra == 'ai-templates'
+Provides-Extra: ai-typesafe
+Requires-Dist: pydantic-ai-slim[typesafe]<3,>=2.45; extra == 'ai-typesafe'
 Provides-Extra: cache
 Requires-Dist: aiocache<1.0,>=0.12; extra == 'cache'
 Requires-Dist: omegaconf<3.0,>=2.3; extra == 'cache'

{loom_kernel-2.4.0 → loom_kernel-2.6.0}/docs/ai/artifacts.md

@@ -509,6 +509,14 @@ The hook's return value is a client-facing DTO delivered verbatim to the caller
 — public on an `allow_anonymous` mount — so return a purpose-built struct,
 never a domain entity.
 
+In process, `AgentAnswer` and `AgentResult` also carry `provider_details`: what the provider
+reported about the final answer beyond the answer itself, verbatim and opaque
+to loom — a decision model's confidence and probabilities per field (see
+[`typesafe`](providers.md#typesafe-fills-an-output-it-never-writes-text)),
+another provider's finish reason — or `None` when it reported nothing. Like
+`messages`, it never reaches the wire: the `/run` body and the `final` frame
+keep their four keys.
+
 The request body accepts an optional `conversation_id`: a string of 1 to 128
 characters that loom never reads and never keys anything on. It selects the
 conversation the loader receives when the artifact declares
@@ -797,8 +805,8 @@ accepts the parameter and ignores it, so scripted tests stay byte for byte.
 
 Clients keep sending `{"prompt", "conversation_id"}`. The `/run` body has
 exactly `output`, `usage`, `interaction_id` and `hook_result`; the `final`
-frame has the same four keys; `messages` appears in neither, nor in any A2A
-frame. Over A2A the thread travels as the message's `contextId`, which the
+frame has the same four keys; `messages` and `provider_details` appear in
+neither, nor in any A2A frame. Over A2A the thread travels as the message's `contextId`, which the
 runtime treats as the `conversation_id` (see [the A2A surface](a2a.md#conversations)).
 
 ### Two turns

{loom_kernel-2.4.0 → loom_kernel-2.6.0}/docs/ai/providers.md

@@ -25,6 +25,7 @@ with `MODEL_ROLE_UNBOUND`. It is never deferred to the first request.
 | `openai` | `ai-openai` | — | the **name of the environment variable** holding the API key; omit it and the SDK reads its own default | OpenAI's own API |
 | `anthropic` | `ai-anthropic` | — | the **name of the environment variable** holding the API key; omit it and the SDK reads its own default | Anthropic's own API |
 | `gateway` | `ai-openai` | `endpoint` | the **name of the environment variable** holding the API key the endpoint expects | **any OpenAI-compatible endpoint** — see below |
+| `typesafe` | `ai-typesafe` | — | the **name of the environment variable** holding the API key; omit it and the SDK reads `TYPESAFE_API_KEY` | TypeSafe's Jev — a decision model, see below |
 
 Which **provider-run tools** each binding admits — web search, web fetch, code
 execution — is decided by the model class of the installed engine, not by this
@@ -107,6 +108,37 @@ An artifact then picks one with `model_role: reasoning`. Moving that agent to a
 cheaper model later is a one-line config change with no artifact edit and no
 redeploy of the agent definition.
 
+## `typesafe` fills an output, it never writes text
+
+Jev, TypeSafe's model, is not a language model: given a state, it answers
+typed questions about it with a calibrated probability each, and pydantic-ai
+turns the agent's `output_type` into those questions. Bind it to a role whose
+output is a strict class of `bool`, `Literal`/`Enum`, bounded `float` or
+`IntEnum` fields; a `str` field, a text answer, a file in the prompt or a
+tool taking arguments is refused by pydantic-ai before any request.
+
+```yaml
+ai:
+  models:
+    verdict:
+      provider: typesafe
+      model: jev-latest
+      credentials_ref: TYPESAFE_API_KEY
+```
+
+pydantic-ai fills a TypeSafe output through tool mode only, so this is the one
+binding whose `output_mode` loom can check before the first request: pinning
+`native` fails **start-up** with `OUTPUT_MODE_UNSUPPORTED`, naming the mode
+the provider serves. `endpoint`, when set, replaces the API's base URL.
+`streaming` changes nothing: Jev returns each answer whole.
+
+What makes the answer worth having — the probability behind each field and
+the margin by which it cleared its threshold — comes back on
+`AgentAnswer.provider_details`, verbatim as pydantic-ai reports it
+(`confidence`, `probabilities`, `scores`, `requests`), so a use case can act
+on a firm verdict and escalate a doubtful one. In process only; see
+[what the caller receives](artifacts.md#what-the-caller-receives).
+
 ## Credentials never live in the artifact — or in the config
 
 `credentials_ref` is a **reference**, never the secret itself: an AWS profile
@@ -114,7 +146,7 @@ name for `bedrock`, and for the API-key providers the **name of an environment
 variable** loom reads at start-up. An unset variable fails start-up with
 `PROVIDER_SETTING_MISSING` naming it, instead of a 401 on the first call; omit
 `credentials_ref` and each SDK reads its own default variable
-(`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`).
+(`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `TYPESAFE_API_KEY`).
 
 The value is validated fail-closed at start-up — a value shaped like literal
 secret material (`AKIA…`, `sk-…`, `ghp_…`, a URL with credentials in its
@@ -193,7 +225,9 @@ loom does not infer it per provider. Two consequences follow from that:
   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.
+  start-up. The one exception is `typesafe`, whose models pydantic-ai serves
+  by tool alone, so a `native` pin on it fails start-up with
+  `OUTPUT_MODE_UNSUPPORTED`.
 
 ## Asking for the answer whole, not as a stream
 

loom_kernel-2.6.0/docs/architecture/clean-architecture.md

@@ -0,0 +1,44 @@
+# Clean architecture rules
+
+Project invariants:
+
+1. Domain/Application layers must not import infrastructure.
+2. Repositories are interface-driven.
+3. Runtime side effects are explicit and observable.
+4. Public APIs are typed and documented.
+
+This contract is enforced through module boundaries and strict typing checks.
+
+## Optional dependencies: islands
+
+A dependency loom does not require lives behind an extra, and the code that
+uses it follows one pattern, whatever the pillar:
+
+1. **One optional dependency, one island.** An island is a module that
+   imports the vendor SDK at its top, with an ordinary `import`, and nothing
+   else in loom imports that SDK. The island builds what the SDK serves
+   (`loom.ai.engines.pydantic_ai.providers.bedrock`, `loom.core.sql.clickhouse`,
+   `loom.streaming.bytewax`).
+2. **The selector loads the island, not the SDK.** A registry keyed by
+   provider, engine or backend name loads the island by module path once it
+   knows the name — `loom.core.plugins.optional.import_optional` for a module
+   of loom, `loom.core.plugins.entrypoints` for a plugin distribution — and
+   translates `MissingExtraError` into its own coded failure naming the extra
+   (`PROVIDER_NOT_INSTALLED` in the AI layer).
+3. **Nothing else.** No `import` inside a function to reach a vendor SDK, no
+   module-level `try`/`except ImportError` with a `None` sentinel checked
+   later, no `importlib.import_module("vendor")` on the request path, no
+   attribute lookup on a vendor module.
+
+The island needs no `try`/`except` of its own: its `ImportError` is what
+`import_optional` translates. Islands today: the pydantic-ai providers and
+extras (`loom.ai.engines.pydantic_ai.providers`, `.extras`), boto3 for the
+config resolvers (`loom.core.config._boto3`), and the whole-package islands
+that predate the rule (`loom.core.sql.clickhouse`, `loom.streaming.bytewax`,
+`loom.etl.testing`). A dependency listed under `dependencies` is not
+optional and gets no island: import it at the top like any other. A test that stands in for an absent or stubbed SDK
+blocks the SDK **and** evicts the island, so the next load re-imports it;
+`tests/helpers/extras.py` does both. A module that reads an SDK the application
+itself may or may not have loaded — pydantic in `loom.core.model` — gates on
+`sys.modules` instead, on purpose: loom never loads what the application did
+not. Code that predates this rule is migrated when it is next touched.

{loom_kernel-2.4.0 → loom_kernel-2.6.0}/docs/etl/pipelines.md

@@ -164,6 +164,12 @@ storage:
 
   tmp_root: /var/lib/loom/lake/_tmp
 
+  temp:
+    root: s3://my-lake/_checkpoints
+    storage_options:
+      aws_server_side_encryption: aws:kms
+      aws_sse_kms_key_id: alias/loom-temp
+
 observability:
   log:
     enabled: true
@@ -179,6 +185,11 @@ observability:
     # database: ops
 ```
 
+Server-side encryption declared in `storage.temp.storage_options` is honoured by
+the Polars engine only; with `engine: spark` the checkpoint write goes through
+Hadoop's S3A, which takes it from `fs.s3a.server-side-encryption-*` on the
+session instead.
+
 ```python
 from loom.etl import ETLRunner
 

{loom_kernel-2.4.0 → loom_kernel-2.6.0}/docs/guides/etl.md

@@ -164,6 +164,12 @@ storage:
 
   tmp_root: /var/lib/loom/lake/_tmp
 
+  temp:
+    root: s3://my-lake/_checkpoints
+    storage_options:
+      aws_server_side_encryption: aws:kms
+      aws_sse_kms_key_id: alias/loom-temp
+
 observability:
   log:
     enabled: true
@@ -179,6 +185,11 @@ observability:
     # database: ops
 ```
 
+Server-side encryption declared in `storage.temp.storage_options` is honoured by
+the Polars engine only; with `engine: spark` the checkpoint write goes through
+Hadoop's S3A, which takes it from `fs.s3a.server-side-encryption-*` on the
+session instead.
+
 ```python
 from loom.etl import ETLRunner
 

{loom_kernel-2.4.0 → loom_kernel-2.6.0}/docs/rest/cache.md

@@ -59,7 +59,8 @@ cache:
   ttl:                      # per-entity overrides; append _list for the list side
     user: 600
     user_list: 300
-  max_size: 1000            # injected into every aiocache.SimpleMemoryCache alias
+  max_size: 1000            # entry cap for every aiocache.SimpleMemoryCache alias
+  max_bytes: 33554432       # byte cap for the same aliases; either or both
   aiocache_alias: data      # alias that stores entities (default: "default")
   counter_alias: counters   # alias that stores the generation counters (default: same as aiocache_alias)
   aiocache_config:
@@ -80,6 +81,7 @@ cache:
 | `ttl_jitter` | `0.1` | Random spread applied per write so a burst does not expire at once; `0` disables it |
 | `ttl` | `{}` | Per-entity overrides; `user` for the entity read, `user_list` for the list side |
 | `max_size` | none | Entry cap for `aiocache.SimpleMemoryCache` aliases; ignored by Redis |
+| `max_bytes` | none | Byte cap on the stored payloads of the same aliases; ignored by Redis |
 | `aiocache_alias` | `default` | Alias of the data backend |
 | `counter_alias` | none | Alias of the counter backend; falls back to `aiocache_alias` |
 | `aiocache_config` | `{}` | Alias map handed to `aiocache`, one entry per alias |
@@ -94,6 +96,16 @@ Redis `INCR`), and a serializer in front of them would break that. When
 falls back to a non-atomic get-and-set, which is fine for a single process and
 not for several.
 
+`aiocache.SimpleMemoryCache` itself accepts no bound: it only shrinks by TTL.
+An alias configured with that class and a bound — `max_size` or `max_bytes` at
+the `cache:` level, or its own inside `aiocache_config`, which win — is served by
+`loom.core.cache.memory.BoundedMemoryCache` instead, which evicts the least
+recently used entries the moment a write crosses either bound. Bytes are
+measured on the stored payload, so on the data alias they are the serialized
+size, exactly. A single value larger than `max_bytes` is kept and evicts
+everything else, because a `get` right after a `set` must not miss. Redis and
+every other server backend are forwarded unchanged and bound their own memory.
+
 The YAML reads `aiocache_config:` only. `CacheConfig.from_mapping` also accepts
 the short key `aiocache:` for callers building the config by hand; from the
 YAML that key — like any other key `CacheConfig` does not declare, `ttls:` for
@@ -410,7 +422,7 @@ cache:
 
 Keep a separate counter alias for any multi-process deployment: with one alias
 the counters share the data serializer and lose the atomic increment.
-`max_size` has no effect on Redis.
+`max_size` and `max_bytes` have no effect on Redis.
 
 ## Failures
 

{loom_kernel-2.4.0 → loom_kernel-2.6.0}/pyproject.toml

@@ -122,6 +122,11 @@ ai-openai = [
 ai-anthropic = [
     "pydantic-ai-slim[anthropic]>=2,<3",
 ]
+# TypeSafe's Jev: a decision model that fills a typed output from a state, no
+# text. Its model class first shipped in pydantic-ai 2.45.
+ai-typesafe = [
+    "pydantic-ai-slim[typesafe]>=2.45,<3",
+]
 # Only an artefact declaring `template:` on an instruction block needs this:
 # the engine compiles a Handlebars template and renders it per request. An
 # artefact whose instructions are literal never reaches the import.
@@ -255,7 +260,7 @@ dev = [
     "httpx>=0.27",
     "types-pyyaml>=6.0.12.20260724",
     "jsonschema>=4.26.0",
-    "pydantic-ai-slim[anthropic,bedrock,openai,spec]>=2,<3",
+    "pydantic-ai-slim[anthropic,bedrock,openai,spec,typesafe]>=2.45,<3",
     "fasta2a>=0.6,<1",
     "a2a-sdk>=1.1,<2",
     "pydantic-ai-harness[skills]>=0.28,<1",

{loom_kernel-2.4.0 → loom_kernel-2.6.0}/src/loom/ai/abc.py

@@ -179,6 +179,12 @@ class AgentResult(LoomFrozenStruct, frozen=True, kw_only=True):
         messages: New messages of this run in the engine's own serialised
             form; ``None`` when they are longer than
             ``policies.max_history_bytes``.
+        provider_details: What the provider reported about the final answer
+            beyond the answer itself, verbatim and opaque to loom — a
+            decision model's confidence and probabilities per field, another
+            provider's finish reason. ``None`` when it reported nothing. In
+            process only: the ``/run`` body and the ``final`` frame never
+            carry it.
     """
 
     output: object
@@ -186,6 +192,7 @@ class AgentResult(LoomFrozenStruct, frozen=True, kw_only=True):
     interaction_id: str | None = None
     hook_result: object | None = None
     messages: bytes | None = None
+    provider_details: Mapping[str, Any] | None = None
 
 
 class AgentAnswer(LoomFrozenStruct, Generic[AnswerT], frozen=True, kw_only=True):
@@ -205,11 +212,16 @@ class AgentAnswer(LoomFrozenStruct, Generic[AnswerT], frozen=True, kw_only=True)
             overrode it for this call only.
         usage: Resource accounting of this run only.
         interaction_id: Identifier the runtime minted for this run.
+        provider_details: What the provider reported about this answer beyond
+            the answer itself, verbatim and opaque to loom — a decision
+            model's confidence and probabilities per field, another
+            provider's finish reason — or ``None`` when it reported nothing.
     """
 
     output: AnswerT
     usage: AgentUsage
     interaction_id: str | None = None
+    provider_details: Mapping[str, Any] | None = None
 
 
 class McpHandle(Protocol):
@@ -678,6 +690,9 @@ class FinalEvent(LoomFrozenStruct, frozen=True, kw_only=True, tag="final", tag_f
         messages: New messages of this run in the engine's own serialised
             form; ``None`` when they are longer than
             ``policies.max_history_bytes``.
+        provider_details: What the provider reported about the final answer
+            beyond the answer itself, as on :class:`AgentResult`; the
+            runtime copies it there, and no wire surface publishes it.
     """
 
     output: object
@@ -685,6 +700,7 @@ class FinalEvent(LoomFrozenStruct, frozen=True, kw_only=True, tag="final", tag_f
     interaction_id: str | None = None
     hook_result: object | None = None
     messages: bytes | None = None
+    provider_details: Mapping[str, Any] | None = None
 
 
 AgentEvent = TextDeltaEvent | ToolCallEvent | ToolResultEvent | ErrorEvent | FinalEvent

loom_kernel-2.6.0/src/loom/ai/engines/pydantic_ai/_a2a.py

@@ -0,0 +1,79 @@
+"""Outbound A2A transport: this agent calling a remote one (T147).
+
+Two entry points, one connection recipe, both served by the
+:mod:`~loom.ai.engines.pydantic_ai.extras.a2a` island, the one module of the
+engine that imports the ``a2a-sdk``:
+
+* :func:`create_a2a_client` is the :data:`~loom.ai.runtime.A2AClientFactory`
+  the runtime opens at start-up. Entering it fetches the remote card, applies
+  the grant's skill filter to it and hands back a usable session, so an
+  unreachable or mismatched agent fails start-up as ``A2A_AGENT_UNREACHABLE``
+  instead of surfacing on the first delegation.
+* :func:`send_to_remote_agent` performs one delegation.
+
+This module loads the island when a grant names it — :func:`require_a2a_sdk`
+at build, the two entry points at call — so a deployment that declares no
+``a2a`` grant never imports the SDK, and one that does fails start-up naming
+the ``ai-a2a`` extra when it is missing.
+"""
+
+from __future__ import annotations
+
+from contextlib import AbstractAsyncContextManager
+from typing import TYPE_CHECKING, Protocol, cast
+
+from loom.ai.compiler import CompiledA2ACapability
+from loom.ai.registry import require_provider_sdk
+
+if TYPE_CHECKING:
+    from a2a.client import Client
+
+_ISLAND = "loom.ai.engines.pydantic_ai.extras.a2a"
+_EXTRA = "ai-a2a"
+
+
+class _A2ASdk(Protocol):
+    """The two names the A2A island publishes."""
+
+    def create_a2a_client(
+        self, capability: CompiledA2ACapability
+    ) -> AbstractAsyncContextManager[Client]: ...
+
+    async def send_to_remote_agent(self, capability: CompiledA2ACapability, prompt: str) -> str: ...
+
+
+def _sdk() -> _A2ASdk:
+    """Load the island; the cast records the contract every island keeps."""
+    return cast(_A2ASdk, require_provider_sdk("a2a", _ISLAND, _EXTRA))
+
+
+def require_a2a_sdk() -> None:
+    """Fail the build when the ``ai-a2a`` extra is not installed.
+
+    Raises:
+        AgentCompilationError: With ``PROVIDER_NOT_INSTALLED`` naming the
+            extra when the island cannot be imported.
+    """
+    _sdk()
+
+
+def create_a2a_client(capability: CompiledA2ACapability) -> AbstractAsyncContextManager[Client]:
+    """Open one session against a remote agent, card fetched and checked.
+
+    Satisfies :data:`~loom.ai.runtime.A2AClientFactory`. See the island's
+    ``create_a2a_client`` for what entering the context does and raises.
+
+    Example::
+
+        runtime = AgentRuntime(..., a2a_client_factory=create_a2a_client)
+    """
+    return _sdk().create_a2a_client(capability)
+
+
+async def send_to_remote_agent(capability: CompiledA2ACapability, prompt: str) -> str:
+    """Delegate one prompt to a remote agent and return its reply text.
+
+    See the island's ``send_to_remote_agent`` for the contract: the reply is
+    untrusted data, presented as a tool value and never as instruction.
+    """
+    return await _sdk().send_to_remote_agent(capability, prompt)

{loom_kernel-2.4.0 → loom_kernel-2.6.0}/src/loom/ai/engines/pydantic_ai/_capabilities.py

@@ -26,7 +26,7 @@ from collections.abc import Callable, Iterator, Mapping, Sequence
 from dataclasses import dataclass
 from enum import Enum
 from types import MappingProxyType
-from typing import Any, Final, NamedTuple, cast
+from typing import Any, Final, NamedTuple, Protocol, cast
 
 from pydantic_ai import ToolReturn
 from pydantic_ai.capabilities import AbstractCapability
@@ -78,11 +78,11 @@ from loom.ai.errors import (
     AgentCompilationError,
     AgentRunError,
     AgentRunErrorCode,
-    provider_not_installed,
     python_factory_failed,
     python_factory_not_callable,
     python_remote_not_granted,
 )
+from loom.ai.registry import require_provider_sdk
 from loom.core.di import LoomContainer
 from loom.core.engine.compilable import Compilable
 from loom.core.engine.plan import ExecutionPlan
@@ -528,18 +528,22 @@ def _skills_capability(
         AgentCompilationError: When the ``ai-harness`` extra is not installed.
     """
     del context
-    # Local import: the skills harness ships behind the optional ``ai-harness``
-    # extra, and importing it at module load would break every deployment that
-    # declares no ``skills`` grant.
-    try:
-        from pydantic_ai_harness import Skills
-    except ImportError as exc:
-        raise AgentCompilationError([provider_not_installed("skills", "ai-harness")]) from exc
+    sdk = cast(
+        _SkillsSdk,
+        require_provider_sdk("skills", "loom.ai.engines.pydantic_ai.extras.skills", "ai-harness"),
+    )
     return cast(
-        "AbstractCapability[Any]", Skills(capability.directory, include=list(capability.names))
+        "AbstractCapability[Any]",
+        sdk.Skills(capability.directory, include=list(capability.names)),
     )
 
 
+class _SkillsSdk(Protocol):
+    """The one name the skills island publishes."""
+
+    Skills: type[Any]
+
+
 _KINDS: Final[Mapping[type[CompiledCapability], _KindBinding]] = MappingProxyType(
     {
         CompiledUsecaseCapability: _KindBinding(_Destination.TOOLSET, _usecase_toolset),

{loom_kernel-2.4.0 → loom_kernel-2.6.0}/src/loom/ai/engines/pydantic_ai/_engine.py

@@ -242,6 +242,7 @@ class PydanticAIEngine:
                 agent=self._plan.name,
                 max_history_bytes=self._plan.policies.max_history_bytes,
             ),
+            provider_details=result.response.provider_details,
         )
 
     def run_stream(
@@ -783,6 +784,7 @@ class PydanticAIEngine:
                 agent=self._plan.name,
                 max_history_bytes=self._plan.policies.max_history_bytes,
             ),
+            provider_details=result.response.provider_details,
         )
 
 

{loom_kernel-2.4.0 → loom_kernel-2.6.0}/src/loom/ai/engines/pydantic_ai/_events.py

@@ -77,6 +77,11 @@ IGNORED_EVENT_KINDS: frozenset[str] = frozenset(
         "realtime_input_transcription_error",
         "realtime_session_reconnect",
         "realtime_session_error",
+        # An application's own event and a capability's typed event, emitted into
+        # the engine's stream by code loom never runs; the closed loom union has
+        # no member for either (FR-035).
+        "custom",
+        "capability",
     }
 )
 """Engine event kinds with no loom counterpart; carried by no consumer."""

{loom_kernel-2.4.0 → loom_kernel-2.6.0}/src/loom/ai/engines/pydantic_ai/_instructions.py

@@ -14,7 +14,7 @@ from __future__ import annotations
 
 from collections.abc import Awaitable, Callable, Mapping
 from types import MappingProxyType
-from typing import Any, Final, TypeAlias
+from typing import Any, Final, Protocol, TypeAlias, cast
 
 from pydantic_ai import RunContext
 from pydantic_ai.messages import InstructionPart
@@ -26,8 +26,11 @@ from loom.ai.errors import (
     template_compilation_failed,
     template_extra_missing,
 )
+from loom.core.plugins.optional import MissingExtraError, import_optional
 
 TEMPLATING_EXTRA: Final[str] = "ai-templates"
+_HANDLEBARS_ISLAND: Final[str] = "loom.ai.engines.pydantic_ai.extras.handlebars"
+"""The one module of the engine importing ``pydantic_handlebars``."""
 """``pyproject.toml`` optional-dependency extra installing ``pydantic_handlebars``."""
 
 AgentInstructionItem: TypeAlias = InstructionPart | Callable[[RunContext[Any]], Awaitable[str]]
@@ -85,12 +88,31 @@ def ensure_templating_available(plan: AgentPlan) -> None:
 
 def _pydantic_handlebars_importable() -> bool:
     try:
-        import pydantic_handlebars  # noqa: F401
-    except ImportError:
+        _handlebars()
+    except MissingExtraError:
         return False
     return True
 
 
+class _Handlebars(Protocol):
+    """The two names the templating island publishes."""
+
+    HandlebarsError: type[Exception]
+
+    def compile_checked(
+        self, text: str, schema: Mapping[str, Any] | None
+    ) -> Callable[[Any], str]: ...
+
+
+def _handlebars() -> _Handlebars:
+    """Load the island; the cast records the contract every island keeps.
+
+    Raises:
+        MissingExtraError: When ``pydantic_handlebars`` is not installed.
+    """
+    return cast(_Handlebars, import_optional(_HANDLEBARS_ISLAND, extra=TEMPLATING_EXTRA))
+
+
 def build_instructions(plan: AgentPlan) -> list[AgentInstructionItem]:
     """Project every compiled instruction block onto the engine's keyword form.
 
@@ -210,22 +232,17 @@ def _handlebars_instruction(
         AgentCompilationError: The template fails to parse, or fails the
             compatibility check against its declared schema.
     """
-    import pydantic_handlebars
-
+    handlebars = _handlebars()
     schema = None if state is None else state.schema
     try:
-        if schema is not None:
-            pydantic_handlebars.check_template_compatibility(
-                block.text, dict(schema), raise_on_error=True
-            )
-        compiled = pydantic_handlebars.compile(block.text)
-    except pydantic_handlebars.HandlebarsError as exc:
+        rendered = handlebars.compile_checked(block.text, schema)
+    except handlebars.HandlebarsError as exc:
         raise AgentCompilationError(
             [template_compilation_failed(component, label, str(exc))]
         ) from exc
 
     async def render(ctx: RunContext[Any]) -> str:
-        return compiled.render(ctx.deps.state)
+        return rendered(ctx.deps.state)
 
     return render