loom-kernel 2.5.0__tar.gz → 2.7.0__tar.gz

{loom_kernel-2.5.0 → loom_kernel-2.7.0}/CHANGELOG.md

@@ -31,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
@@ -51,6 +88,33 @@
   boundaries already use; `LoomRestAdapter`'s Struct projection goes
   through it too.
 
+### prefect
+
+- **prefect:** a deployment may run each time another one completes, inheriting
+  some of its parameters. The per-flow YAML takes an optional `trigger` block:
+  `after`, the upstream deployment as `<flow>/<deployment>` or, for a loom ETL
+  whose flow and deployment share its name, that name; and `inherit_params`, a
+  list of parameter names. The deployer registers it as a Prefect
+  `DeploymentEventTrigger` on `prefect.flow-run.Completed` whose related
+  resources must include both that flow and that deployment, since a deployment
+  name is only unique within its flow. Each inherited parameter is rendered, as
+  text, from the completed run's stored parameters, which loom records resolved,
+  so `${today-1d}` upstream reaches the downstream run as the concrete date.
+  Only fields declared exactly `str`, `date` or `datetime` can be inherited (a
+  null would render as `"None"`), and each must be stored on the upstream run,
+  that is declared under its YAML `params` or submitted: a value it only took
+  from a signature default renders as empty text, which a `str` field takes as
+  `""` and a `date` field fails to decode. Every other parameter takes the
+  deployment's default, and a placeholder among them resolves against the
+  downstream run's creation time. The block is decoded strictly (an unknown key,
+  a wrong type or an `after` with spaces around either part is refused) when the
+  flow is built and, for YAML declarations, as a `ConfigError` before any
+  deployment is registered. A trigger coexists with `schedule`, in which case
+  the ETL runs on both. If the upstream run failed to record its parameters, the
+  downstream run inherits the placeholder text and resolves it against its own
+  creation time. Without `trigger` the deployment is registered exactly as
+  before.
+
 ## ⚠ Behaviour changes
 
 ### core
@@ -96,6 +160,44 @@
   OpenAPI schemas for request bodies and responses alike, matching the
   untitled document a Struct always produced.
 
+### prefect
+
+- **prefect:** a placeholder counts from the run's scheduled start instead of
+  the wall clock. `${today-1d}`, `${yesterday}` and `${now±N}` counted from
+  `datetime.now()` inside the flow, so a queued run that started after
+  midnight, or a retry the next day, processed another day than its slot's.
+  `etl_flow`, `maintenance_flow` and `backfill_flow` (`start_from` included)
+  and the run name now resolve against the run's scheduled start
+  (`prefect.runtime.flow_run.scheduled_start_time`, read in UTC): the slot of
+  a scheduled run, the same slot on every retry, the creation time of a manual
+  run. A late run's `${now}` therefore covers up to its scheduled time, not up
+  to the moment it started. Outside a flow run the wall clock still applies.
+  The backfill finalize pass still pins `window_end` to the current chunk.
+- **prefect:** resuming from the manifest now works for placeholder
+  parameters. The correlation id was computed from the resolved value, so
+  with `${now}` it carried the seconds of the clock and a retry never found
+  the manifest of the attempt before it; anchored, every attempt of a run
+  computes the same id. The id is now also computed from the decoded
+  parameters rather than the submitted ones, so a value and its recorded ISO
+  string key the same manifest. Two ids change: a `date` field submitted as
+  an ISO string (`"2026-09-21"` now keys `20260921T000000`, as the `date`
+  itself always did), and a `correlation_field` typed as a plain `Enum`,
+  which now keys the member's sanitised name (`Color_RED`) instead of its
+  submitted value (`red`); a `StrEnum` renders as its value and keeps its id.
+  Do not upgrade across a run you intend to resume from its manifest.
+- **prefect:** the run records the parameters it resolved. Prefect stored and
+  showed the placeholder text, so nothing told which days a run processed.
+  After decoding, the flow updates its own run: the parameters the API stored
+  for it, with each placeholder replaced by its value (dates and datetimes in
+  ISO 8601, a backfill's `start_from` included); nothing is added. The UI
+  shows the concrete window, a run resubmitted from the UI ("Retry") or
+  copied reproduces it, and an automation reading `flow_run.parameters` gets
+  dates. A run that stores no placeholder makes no call, so a resubmitted run
+  makes none. A retry inside the same process (`retries`) still holds the
+  placeholders it started with and repeats the call with the same values,
+  which is harmless. The update is one attempt with a 10-second timeout; if
+  it fails, the flow logs it at `ERROR` in the run's logs and goes on.
+
 ## 🐛 Fixes
 
 ### core
@@ -130,6 +232,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.5.0 → loom_kernel-2.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: loom-kernel
-Version: 2.5.0
+Version: 2.7.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.5.0 → loom_kernel-2.7.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.5.0 → loom_kernel-2.7.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.7.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.5.0 → loom_kernel-2.7.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.5.0 → loom_kernel-2.7.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
 
@@ -882,7 +893,7 @@ that matches nothing is a `ConfigError`.
 
 A declaration file has one of two shapes. The first is a **per-ETL document**:
 the YAML `etl_flow` already reads (`schedule`, `params`, `tags`, `environments`,
-`retry`, `notifications`, `correlation_field`) plus the keys that replace the
+`retry`, `notifications`, `correlation_field`, `trigger`) plus the keys that replace the
 Python module:
 
 ```yaml
@@ -947,6 +958,78 @@ declares neither `etls:` nor `pipeline` is a `ConfigError` naming the file, so
 keep ETL declarations in their own directory (`config/etls/`) or in one `etls:`
 file rather than next to the storage YAML.
 
+### Placeholders count from the run's scheduled start
+
+A parameter may hold a placeholder: `${today}`, `${today±Nd}`, `${yesterday}`,
+`${now}` or `${now±N}` with `d`, `h` or `m`. Inside a flow run it counts from
+the run's scheduled start, read in UTC, not from the moment the run executes:
+
+- a scheduled run resolves against its slot, even when it starts late or
+  after midnight;
+- a retry, by the engine or through "Retry" in the UI, resolves against the
+  same slot;
+- a manual run resolves against the time it was created.
+
+A late run's `${now}` therefore covers up to its scheduled time. The run name
+follows the same rule.
+
+Once resolved, the flow writes the values back to its own run: the
+parameters the API stored for it, with each placeholder replaced by its value
+(dates and datetimes in ISO 8601, a backfill's `start_from` included). Nothing
+else is added or changed. The run then shows the window it processed, and a
+run resubmitted from the UI ("Retry") or copied reproduces it exactly: its
+parameters are concrete, so it makes no call. A retry inside the same process
+(`retries`) still holds the placeholders it started with, resolves them to the
+same values and repeats the call, which is harmless.
+
+The update is a single attempt with a 10-second timeout. If it fails, the flow
+logs it at `ERROR`, in the run's logs, and runs anyway; the run then keeps
+showing the placeholders.
+
+Because every attempt of a run resolves the same values, the correlation id,
+and therefore the manifest a retry resumes from, is stable across attempts.
+
+### Running a deployment after another one
+
+A per-flow YAML may name the deployment whose completed runs start this one,
+and the parameters it copies from them:
+
+```yaml
+trigger:
+  after: respondio_messages_daily
+  inherit_params: [updated_at_from, updated_at_to]
+```
+
+`after` is the upstream deployment as `<flow>/<deployment>`, or a single name
+when the flow and the deployment share it, as every loom ETL's do. The
+deployer registers a Prefect `DeploymentEventTrigger` that fires on
+`prefect.flow-run.Completed` of a run related to both that flow and that
+deployment; a deployment name alone is only unique within its flow.
+
+Each name in `inherit_params` is copied from the completed run's stored
+parameters. Since the run records its placeholders resolved, the downstream
+run receives the same concrete window. The name must therefore be stored on the
+upstream run, which means declared under the upstream YAML's `params` (or
+submitted with the run): a value the upstream flow only took from its
+signature default is not stored, so it renders as empty text, which a `str`
+field accepts as `""` and a `date` or `datetime` field fails to decode. The trigger passes each value as text,
+so only a field declared exactly `str`, `date` or `datetime` can be inherited;
+an optional field is refused because a null would arrive as the text `"None"`.
+
+- Parameters not inherited take this deployment's defaults; a placeholder
+  among them resolves against the downstream run's own creation time.
+- If the upstream run could not record its parameters, the downstream run
+  inherits the placeholder text and resolves it against its own creation
+  time, which may not be the upstream slot.
+- `trigger` and `schedule` may both be set, and the ETL then runs on both: on
+  its schedule and after each completed upstream run.
+- The upstream name is not checked against the deployments that exist: a
+  trigger naming no deployment never fires.
+
+The block is decoded strictly: `after` and `inherit_params` are its only keys,
+`after` must name a deployment, without surrounding spaces in either part, and
+each inherited name must be a field of the flow's params type.
+
 ### Validation before any deployment
 
 Every declaration is read and checked before the first deployment is

{loom_kernel-2.5.0 → loom_kernel-2.7.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.5.0 → loom_kernel-2.7.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.7.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.5.0 → loom_kernel-2.7.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.5.0 → loom_kernel-2.7.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,
         )