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

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

@@ -1,3 +1,76 @@
+# 🚀 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))
+
+
+## ✨ Features
+### ai
+- **ai:** run a deployment use case on every completed agent run (on_output)<br>
+  > An agent artifact may declare `on_output: {usecase: <key>}`. The runtime
+  > then executes that use case exactly once per run that completes with a
+  > validated output, as the caller, through the normal use-case path
+  > (executor, rules, unit of work), with a command carrying the output under
+  > `output` plus runtime context (interaction_id, conversation_id, subject,
+  > mechanism, agent, provider, model). The use case's return value comes back
+  > as `hook_result`; a failing hook fails the run with HOOK_FAILED (500), an
+  > authorization denial with UNAUTHORIZED (403); the model never sees the hook.
+  > Every admitted run now carries an `interaction_id` on its result, its SSE
+  > `final`/`error` frame and its HTTP error body, and the request accepts an
+  > opaque `conversation_id` (1..128) propagated verbatim to the hook.
+  > Compile-time refusals: unknown use case, unsatisfiable Input, a use case
+  > that is both a `kind: usecase` grant and the hook, and a deps bundle whose
+  > invoker is missing or unbound (checked at start-up before any client opens).
+  > The hook is shielded from client disconnects and bounded by
+  > tool_timeout_ms; RuntimeExecutor now rolls back its unit of work on
+  > cancellation as well as on exceptions, and the SSE transport settles the
+  > frame task before closing the event generator.
+  > pyright now resolves imports against the project venv when invoked
+  > directly, so a globally installed dependency cannot shadow the pinned one.
+  > Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
+  > Claude-Session: https://claude.ai/code/session_01Gr9ww7Ut7iiPZcukawEXzH
+
+
+
+
+
+
+## ♻️ Refactor
+### ai
+- **ai:** clear the SonarCloud findings of the on_output hook<br>
+  > The quality gate of #154 failed on a single reliability finding (S7497):
+  > the hook runner's `except asyncio.CancelledError` turned an internal
+  > cancellation into `RuntimeError` instead of re-raising. Wait on the hook
+  > task with `asyncio.wait` instead of `asyncio.shield`, which returns once
+  > the task ends, cancelled included; the consumer's cancellation is then
+  > the only `CancelledError` reaching the handler, always re-raised, and the
+  > internal cancel is detected after the wait. `_consumer_cancelled` and its
+  > `cancelling()` probe go away. `_settle` bounds its wait with
+  > `asyncio.timeout` (S7483).
+
+- **ai:** name _settle's bound so Sonar S7483 stops matching the parameter<br>
+  > Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
+  > Claude-Session: https://claude.ai/code/session_016xY1skW5S2PU9Fc3M7tfAW
+  > --------
+  > Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
+
+
+
+
+
+
+# 🚀 Release 1.8.1 ([#152](https://github.com/the-reacher-data/loom-py/pull/152)) ([`e8d1d81`](https://github.com/the-reacher-data/loom-py/commit/e8d1d81cf2b3fe15e8351108b893d6076950f0cd))
+
+
+
+## 🐛 Fixes
+### release
+- **release:** merge the release PR when its check rollup is empty
+
+
+
+
+
+
+
+
 # 🚀 Release 1.8.0 ([#147](https://github.com/the-reacher-data/loom-py/pull/147)) ([`1d9667e`](https://github.com/the-reacher-data/loom-py/commit/1d9667e3))
 
 

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

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

{loom_kernel-1.8.0 → loom_kernel-1.9.0}/docs/ai/artifacts.md

@@ -68,6 +68,8 @@ model_role: reasoning
 output:
   kind: type_ref
   ref: myapp.domain.incidents:IncidentReport
+on_output:
+  usecase: incidents.record_report
 capabilities:
   - kind: usecase
     keys:
@@ -109,6 +111,7 @@ metadata:
 | `instructions` | yes | — | Non-empty. **Never published.** Never a place to encode authorization. |
 | `model_role` | no | `default` | `^[a-z][a-z0-9_-]{0,31}$`. A logical role, never a vendor name or a model id. |
 | `output` | yes | — | The declared answer shape. See below. |
+| `on_output` | no | — | Use case executed once per completed run with the validated output; see below. |
 | `capabilities` | no | `[]` | Explicit grants. Empty means the agent can only talk. |
 | `policies` | no | see below | Execution limits. |
 | `metadata` | no | `{}` | Free-form `string: string` labels. **Never published**, never read by the runtime. |
@@ -165,6 +168,200 @@ output:
 The reference is `module:Symbol`. Filesystem paths are not representable by the
 pattern.
 
+## `on_output` — a use case run once per completed run
+
+```yaml
+output:
+  kind: type_ref
+  ref: myapp.domain.triage:TriageReport
+on_output:
+  usecase: incidents.record_triage   # a use-case key of the registry; must not also be a grant
+```
+
+For every run that **completes** with an output validated against the declared
+shape, the runtime executes that use case **exactly once**, as the caller,
+through the normal use-case path — executor, rules, unit of work. The use
+case's return value comes back to the caller as `hook_result`.
+
+It is **not a tool: the model never sees it.** It never enters the
+instructions, it is never offered to the model, and the model cannot call it,
+skip it or choose its arguments. Whether a triage is recorded is decided by the
+deployment that wrote the artifact, not by the model on each run — which is
+what makes the record deterministic. Granting the same operation as a
+`kind: usecase` tool gives you the opposite: a record that exists only when the
+model felt like calling it, with whatever arguments it wrote.
+
+Only a completed run fires the hook. A run that ends in an `error`, breaches a
+declared limit (`run_timeout_ms`, `max_iterations`, …) or whose client leaves
+the stream before the `final` event never runs it.
+
+### What the use case receives
+
+The command nests the validated output under `output` and offers the run's
+context beside it:
+
+| Name | Value |
+|---|---|
+| `output` | The validated answer, as **one nested value**, whatever the artifact's `output` block declares. |
+| `interaction_id` | Identifier the runtime mints for every admitted run. |
+| `conversation_id` | The request's `conversation_id`, verbatim; `None` when the request carried none. |
+| `subject`, `mechanism` | The caller's identity. |
+| `agent`, `provider`, `model` | The agent's name, and the provider and model its `model_role` resolved to. |
+
+**The Command declares what it wants** and receives only that: the runtime
+filters the offered names down to the ones the Input declares, so a strict
+Command (`forbid_unknown_fields=True`) decodes without listing every context
+name. Because `output` is always nested, a field called `subject` inside the
+model's answer can never shadow the caller's.
+
+```python
+class RecordTriageCommand(Command):
+    output: TriageReport                # the type_ref type itself; dict[str, Any] also works
+    interaction_id: str
+    conversation_id: str | None = None
+    agent: str
+    model: str
+    # `subject`, `mechanism`, `provider` are offered but not declared: filtered out.
+
+
+class TriageRecorded(msgspec.Struct, frozen=True):
+    triage_id: str
+
+
+@use_case_key("incidents.record_triage")
+class RecordTriage(UseCase[Triage, TriageRecorded]):
+    def __init__(self, triages: TriageRepository) -> None:
+        self._triages = triages
+
+    async def execute(
+        self,
+        cmd: RecordTriageCommand = Input(),
+        caller: Identity = Caller(),      # the agent's caller
+    ) -> TriageRecorded:
+        report = cmd.output
+        await self._triages.save(
+            Triage(
+                id=cmd.interaction_id, conversation_id=cmd.conversation_id,
+                subject=caller.subject, agent=cmd.agent, model=cmd.model,
+                incident_ref=report.incident_ref, severity=report.severity,
+                confidence=report.confidence,
+            )
+        )
+        return TriageRecorded(triage_id=cmd.interaction_id)
+```
+
+The verdict the on-call engineer gives later ("wrong severity") is an ordinary
+use case of your application, called with the `interaction_id` the app already
+holds. Loom stores nothing.
+
+### The compile-time rule
+
+The compiler proves that the run can feed the use case, so a missing field is
+never discovered at the end of a paid run. The key is resolved against the
+same registry as a `kind: usecase` grant, and the use case's `execute` must
+take an `Input()` whose required fields are all among `output` and the context
+names above. Four coded issues:
+
+| Code | When |
+|---|---|
+| `ON_OUTPUT_USECASE_UNKNOWN` | The key is not registered. |
+| `ON_OUTPUT_INPUT_UNSATISFIED` | The use case cannot be fed from a run: it is not compiled, its `execute` declares primitive parameters, declares no `Input()`, or its Input requires a name the run does not offer. `internal` and `calculated` command fields and `Caller()` are never demanded. |
+| `ON_OUTPUT_USECASE_ALSO_GRANTED` | The same key also appears in a `kind: usecase` grant. A hook use case must not be callable by the model. |
+| `ON_OUTPUT_INVOKER_MISSING` | Start-up: an agent declares a hook but the dependency bundle carries no `invoker` bound to the caller. Probed before any client opens, so a misconfigured deployment fails at start-up rather than after every run. |
+
+The offline validator (`python -m loom.ai.validate`) accepts the field but
+does not resolve the key: it runs only the configuration-independent phases,
+and a use-case registry is deployment state. The four issues above surface
+when the application compiles its agents.
+
+### `on_output` versus a `kind: usecase` grant
+
+Same vocabulary, same registry, same caller identity, same executor — and
+opposite owners. A **grant** is a tool the *model* may call, when and how it
+decides. A **hook** is a use case the *runtime* calls, once, with the
+validated output. That is why one key cannot be both. Deciding whether an
+operation is a tool at all follows
+[the rule](mcp.md#the-rule-your-own-tools-are-a-usecase-grant) on the MCP page;
+`on_output` is for the operation that must happen after every answer,
+regardless of what the model did.
+
+### When the hook fails, the run fails
+
+The model's answer is withheld and the caller gets a coded error. The hook is
+**never retried**: it runs outside the engine's retry loop, and `HOOK_FAILED`
+is not a retriable code.
+
+| The hook… | The caller gets |
+|---|---|
+| raises | `500` `HOOK_FAILED` with a fixed message — `the output hook failed; the detail is recorded server-side`. The exception never reaches the caller; the server log carries it under the `interaction_id`. |
+| raises `Forbidden`, `Unauthenticated`, `RoleNotAllowedError` or `RolesNotBoundError` | `403` `UNAUTHORIZED`, exactly as a `kind: usecase` tool would. |
+| exceeds `tool_timeout_ms` | Cut at the bound and reported as `HOOK_FAILED`. |
+| is cancelled internally | `HOOK_FAILED`: a hook that cancels itself is a hook failure, not a client exit. |
+
+On `/stream` the failure is a single `error` frame and no `final`.
+
+An anonymous caller — an endpoint declaring `allow_anonymous` — runs the hook
+with `Caller()` bound to `ANONYMOUS`, so the command's `subject` is `""`.
+Recording those is the deployment's choice: a use case whose rules refuse an
+anonymous caller answers `403 UNAUTHORIZED` like any other denial.
+
+### Timing and the concurrency permit
+
+The hook runs after the model has finished, but **inside** the run: the
+`max_concurrent_runs` permit is held until it ends. It is bounded by the same
+`tool_timeout_ms` as a capability call, so the worst-case duration of an
+admitted run is `run_timeout_ms + tool_timeout_ms + 1 s` of grace given to a
+cut hook to observe its cancellation. A hook that ignores that grace runs
+detached afterwards; the permit is released regardless.
+
+A client that disconnects while the hook is running does not interrupt it:
+the hook is shielded, so a record that has begun finishes or fails cleanly and
+its unit of work is committed or rolled back as usual.
+
+A hook cut at its bound is rolled back; on a non-transactional backend such
+as DynamoDB, partial writes may remain, so a hook use case should be
+idempotent on `interaction_id`, and `HOOK_FAILED` means "unknown", not "not
+recorded".
+
+### What the caller receives
+
+Every result carries `interaction_id`, hook or no hook: `AgentResult`, the
+`final` and `error` SSE frames, and every HTTP error body. It is `null` only
+when the failure happened before a run was admitted — a `422` body, a `429`
+`TOO_MANY_RUNS` — because a fixed shape beats a conditional one. `hook_result`
+is on `final` and on `AgentResult`, `null` when the artifact declares no hook.
+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.
+
+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 is copied
+verbatim into the hook's command and nowhere else; an out-of-range value is a
+`422`.
+
+`POST /agents/incident-triage/run` with
+`{"prompt": "Checkout latency doubled since 09:40…", "conversation_id": "c-42"}`:
+
+```json
+{
+  "output": {"incident_ref": "INC-1", "severity": "high", "confidence": 0.71, "alerts": ["A-7", "A-9"]},
+  "usage": {"input_tokens": 1840, "output_tokens": 412, "requests": 3, "duration_ms": 5210},
+  "interaction_id": "7f3c9a0e4b2d4c1e9a7b5d6e8f0a1b2c",
+  "hook_result": {"triage_id": "7f3c9a0e4b2d4c1e9a7b5d6e8f0a1b2c"}
+}
+```
+
+Over `/stream`, the last frame is:
+
+```
+event: final
+data: {"output":{...},"usage":{...},"interaction_id":"7f3c...","hook_result":{"triage_id":"7f3c..."}}
+```
+
+Had `RecordTriage` raised, the app would instead get
+`500 {"code":"HOOK_FAILED","message":"the output hook failed; the detail is recorded server-side","interaction_id":"7f3c..."}`
+— or an `error` frame with the same three fields — and no answer.
+
 ## `capabilities` — the six kinds
 
 A capability is a **grant**, never a discovery. Nothing is expanded

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

@@ -99,7 +99,10 @@ Exposure is always an explicit opt-in, never a default.
 ## Where to go next
 
 - **[Artifact reference](artifacts.md)** — the complete `spec_version: 1`
-  format, field by field, and the folder layout an agent lives in.
+  format, field by field, and the folder layout an agent lives in. It includes
+  [`on_output`](artifacts.md#on_output--a-use-case-run-once-per-completed-run),
+  the use case the runtime executes once per completed run with the validated
+  output.
 - **[Model providers](providers.md)** — the provider matrix, and why an
   OpenAI-compatible endpoint is one provider covering many vendors.
 - **[A2A surface](a2a.md)** — publishing an agent to other agents, and exactly

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

@@ -1,6 +1,6 @@
 [project]
 name = "loom-kernel"
-version = "1.8.0"
+version = "1.9.0"
 description = "Loom Python project"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -269,6 +269,11 @@ extend-immutable-calls = [
 
 [tool.pyright]
 pythonVersion = "3.11"
+# Resolve imports against the project venv even when pyright is invoked
+# directly (editor, hooks) instead of through `uv run`, so a globally
+# installed, older dependency never shadows the pinned one.
+venvPath = "."
+venv = ".venv"
 # src only, deliberately. Checking tests as well surfaces 294 errors across
 # eight rules — mostly stubs that no longer satisfy the protocol they stand in
 # for. That is real signal and worth burning down, but it is a project, not a
@@ -357,7 +362,7 @@ markers = [
 
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "1.8.0"
+version = "1.9.0"
 tag_format = "v$version"
 version_files = [
     "pyproject.toml:project.version",

{loom_kernel-1.8.0 → loom_kernel-1.9.0}/scripts/release/checkout_merged_release.py

@@ -195,9 +195,25 @@ def _is_ready_to_merge(merge_state: str, check_outcomes: Sequence[CheckOutcome])
     # reports through the Checks API, and no workflow runs on a branch pushed by
     # GITHUB_TOKEN, so no coverage is ever uploaded for it. Merging is still
     # safe as long as every check that did report has passed.
-    return bool(check_outcomes) and all(
-        outcome is CheckOutcome.PASSED for outcome in check_outcomes
-    )
+    #
+    # And an empty rollup is the *normal* state, not a missing signal. The branch
+    # and the PR are created with GITHUB_TOKEN, and GitHub deliberately emits no
+    # event for actions taken with it -- the protection against workflows
+    # triggering workflows without end. So no run is ever queued against a release
+    # PR and no check can ever appear. Requiring at least one made the wait
+    # unsatisfiable by construction: every release timed out and was published by
+    # hand.
+    #
+    # What guards a release PR is not CI on a version bump -- the code it describes
+    # already passed CI in the pull requests that composed it. It is that the PR
+    # changes exactly CHANGELOG.md, pyproject.toml and uv.lock and nothing else,
+    # asserted by _validate_snapshot at the top of every poll before this function
+    # is reached. A PR carrying anything more never gets this far.
+    #
+    # This cannot open the loop the token protection exists to prevent: the release
+    # workflow's own `prepare` job refuses a head ref starting with `docs/`, so
+    # merging a release PR never starts another release.
+    return all(outcome is CheckOutcome.PASSED for outcome in check_outcomes)
 
 
 def _validate_polling_bounds(timeout_seconds: float, poll_interval_seconds: float) -> None:

{loom_kernel-1.8.0 → loom_kernel-1.9.0}/src/loom/ai/_transport.py

@@ -218,7 +218,7 @@ def failure_event(exc: BaseException) -> ErrorEvent:
         event = failure_event(AgentRunError(AgentRunErrorCode.RUN_TIMEOUT, "late"))
     """
     if isinstance(exc, AgentRunError):
-        return ErrorEvent(code=exc.code, message=str(exc))
+        return ErrorEvent(code=exc.code, message=str(exc), interaction_id=exc.interaction_id)
     return ErrorEvent(code=AgentRunErrorCode.PROVIDER_UNAVAILABLE, message=_UNEXPECTED_FAILURE)
 
 
@@ -231,16 +231,25 @@ async def _next_frame(frames: AsyncIterator[bytes]) -> bytes | None:
 
 
 async def _drain(pending: asyncio.Future[bytes | None] | None) -> None:
-    """Cancel the awaited frame and wait for it, so nothing outlives the stream."""
+    """Cancel the awaited frame and wait for it, so nothing outlives the stream.
+
+    The wait is shielded and repeated until the frame task is done. A server
+    that cancels its handler again at every checkpoint (an ``anyio`` cancel
+    scope does, after a disconnect) would otherwise cancel the frame task a
+    second time through the bare await — cutting the output hook it shields —
+    and then return early, letting the caller close a generator that task is
+    still running.
+    """
     if pending is None:
         return
     pending.cancel()
-    try:
-        await pending
-    except (Exception, asyncio.CancelledError):
-        # The consumer is already gone: neither the cancellation just requested
-        # nor a late failure has anybody left to be reported to.
-        return
+    while not pending.done():
+        try:
+            await asyncio.shield(pending)
+        except (Exception, asyncio.CancelledError):
+            # The consumer is already gone: neither the cancellation just
+            # requested nor a late failure has anybody left to be reported to.
+            continue
 
 
 async def with_heartbeats(

loom_kernel-1.9.0/src/loom/ai/_usecase.py

@@ -0,0 +1,74 @@
+"""Engine-free helpers to run a granted use case as a given caller.
+
+Both the pydantic-ai capability tools and the runtime output hook invoke a use
+case through the dependency bundle's **bound** invoker, with the caller
+installed as the ambient identity for the duration of the call. This module
+holds that shared piece without importing any engine, so the runtime can use
+it with no optional extra installed.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from loom.ai.errors import AgentRunError, AgentRunErrorCode
+from loom.core.engine.compilable import Compilable
+from loom.core.identity import Identity, reset_identity, set_identity
+from loom.core.use_case.invoker import ApplicationInvoker
+
+
+def require_invoker(bundle: object, label: str) -> ApplicationInvoker:
+    """Return the bundle's invoker, refusing a bundle that carries none.
+
+    Read from the bundle rather than resolved from the container: the bundle's
+    invoker is the one the composition root already bound to this invocation's
+    caller, and the container holds only the unbound singleton.
+
+    Args:
+        bundle: Dependency bundle built for the caller by the deps factory.
+        label: Caller of the refused call, worded as it should appear in the
+            error (``"tool 'lookup'"``, ``"on_output hook 'incidents.record'"``).
+
+    Returns:
+        The invoker bound to the caller.
+
+    Raises:
+        AgentRunError: ``UNAUTHORIZED`` when the bundle carries no invoker.
+    """
+    invoker = getattr(bundle, "invoker", None)
+    if isinstance(invoker, ApplicationInvoker):
+        return invoker
+    raise AgentRunError(
+        AgentRunErrorCode.UNAUTHORIZED,
+        f"{label} requires a dependency bundle exposing an 'invoker' bound to its caller",
+    )
+
+
+async def invoke_as(
+    invoker: ApplicationInvoker,
+    use_case: type[Compilable],
+    identity: Identity,
+    *,
+    params: dict[str, Any] | None,
+    payload: dict[str, Any] | None,
+) -> object:
+    """Invoke ``use_case`` through ``invoker`` with ``identity`` as the ambient caller.
+
+    The identity is installed only for the duration of the call and restored in
+    a ``finally`` block, so a reused task never inherits it.
+
+    Args:
+        invoker: Invoker already bound to ``identity`` by the composition root.
+        use_case: Use case type to run.
+        identity: Caller to install as the ambient identity during the call.
+        params: Query-style parameters forwarded untouched.
+        payload: Body-style payload forwarded untouched.
+
+    Returns:
+        Whatever the use case returns.
+    """
+    token = set_identity(identity)
+    try:
+        return await invoker.invoke(use_case, params=params, payload=payload)
+    finally:
+        reset_identity(token)

{loom_kernel-1.8.0 → loom_kernel-1.9.0}/src/loom/ai/a2a/_rpc.py

@@ -50,6 +50,7 @@ RUN_ERROR_DETAILS: Final[Mapping[AgentRunErrorCode, str]] = MappingProxyType(
         AgentRunErrorCode.TOO_MANY_RUNS: "the agent is at its concurrency limit",
         AgentRunErrorCode.UNAUTHORIZED: "the caller is not permitted to perform this run",
         AgentRunErrorCode.CANCELLED: "the run was cancelled",
+        AgentRunErrorCode.HOOK_FAILED: "the output hook failed",
     }
 )
 

{loom_kernel-1.8.0 → loom_kernel-1.9.0}/src/loom/ai/abc.py

@@ -12,13 +12,16 @@ from __future__ import annotations
 
 from collections.abc import AsyncIterator, Mapping
 from contextlib import AbstractAsyncContextManager
-from typing import Any, ClassVar, Literal, Protocol
+from typing import Any, ClassVar, Final, Literal, Protocol
 
 from loom.ai.errors import AgentRunErrorCode
 from loom.core.di import LoomContainer
 from loom.core.identity import Identity
 from loom.core.model import LoomFrozenStruct
 
+CONVERSATION_ID_MAX_LENGTH: Final[int] = 128
+"""Longest ``conversation_id`` a run accepts; the value itself is opaque."""
+
 
 class AgentUsage(LoomFrozenStruct, frozen=True, kw_only=True):
     """Resource accounting of one agent run.
@@ -43,10 +46,15 @@ class AgentResult(LoomFrozenStruct, frozen=True, kw_only=True):
         output: Answer already decoded and validated against the declared
             output shape.
         usage: Resource accounting of the run.
+        interaction_id: Identifier the runtime minted for this run.
+        hook_result: Return value of the ``on_output`` use case, when the plan
+            declares one.
     """
 
     output: object
     usage: AgentUsage
+    interaction_id: str | None = None
+    hook_result: object | None = None
 
 
 class TextDeltaEvent(
@@ -97,10 +105,13 @@ class ErrorEvent(LoomFrozenStruct, frozen=True, kw_only=True, tag="error", tag_f
     Attributes:
         code: Stable run-time failure code; the retry policy reads its class.
         message: Human-readable description.
+        interaction_id: Identifier of the admitted run this failure belongs
+            to; ``None`` before admission.
     """
 
     code: AgentRunErrorCode
     message: str
+    interaction_id: str | None = None
 
 
 class FinalEvent(LoomFrozenStruct, frozen=True, kw_only=True, tag="final", tag_field="type"):
@@ -110,10 +121,15 @@ class FinalEvent(LoomFrozenStruct, frozen=True, kw_only=True, tag="final", tag_f
         output: Answer already decoded and validated against the declared
             output shape.
         usage: Resource accounting of the whole run.
+        interaction_id: Identifier the runtime minted for this run.
+        hook_result: Return value of the ``on_output`` use case, when the plan
+            declares one.
     """
 
     output: object
     usage: AgentUsage
+    interaction_id: str | None = None
+    hook_result: object | None = None
 
 
 AgentEvent = TextDeltaEvent | ToolCallEvent | ToolResultEvent | ErrorEvent | FinalEvent

{loom_kernel-1.8.0 → loom_kernel-1.9.0}/src/loom/ai/compiler/__init__.py

@@ -22,6 +22,7 @@ from loom.ai.compiler._plan import (
     CompiledCapability,
     CompiledMcpCapability,
     CompiledOutput,
+    CompiledOutputHook,
     CompiledPythonCapability,
     CompiledRemoteAuth,
     CompiledSkillsCapability,
@@ -40,6 +41,7 @@ __all__ = [
     "CompiledCapability",
     "CompiledMcpCapability",
     "CompiledOutput",
+    "CompiledOutputHook",
     "CompiledPythonCapability",
     "CompiledRemoteAuth",
     "CompiledSkillsCapability",

{loom_kernel-1.8.0 → loom_kernel-1.9.0}/src/loom/ai/compiler/_compiler.py

@@ -12,8 +12,14 @@ from collections import defaultdict
 from collections.abc import Sequence
 from types import MappingProxyType
 
-from loom.ai.compiler._plan import AgentPlan, CompiledCapability, CompiledOutput
+from loom.ai.compiler._plan import (
+    AgentPlan,
+    CompiledCapability,
+    CompiledOutput,
+    CompiledOutputHook,
+)
 from loom.ai.compiler.phases._capabilities import compile_capabilities
+from loom.ai.compiler.phases._hook import compile_output_hook
 from loom.ai.compiler.phases._limits import validate_policies
 from loom.ai.compiler.phases._model_role import resolve_model_role
 from loom.ai.compiler.phases._output import compile_output
@@ -122,6 +128,10 @@ class AgentCompiler:
         issues: list[AgentCompilationIssue] = []
         output, output_issues = compile_output(spec.output, component)
         issues.extend(output_issues)
+        on_output, hook_issues = compile_output_hook(
+            spec, component=component, registry=self._registry
+        )
+        issues.extend(hook_issues)
         issues.extend(validate_policies(spec.policies, component))
         inference, role_issues = resolve_model_role(spec.model_role, self._config.models, component)
         issues.extend(role_issues)
@@ -137,7 +147,8 @@ class AgentCompiler:
         issues.extend(capability_issues)
         if issues or output is None or inference is None:
             return None, issues
-        return self._build_plan(spec, inference, output, capabilities, source_path), []
+        plan = self._build_plan(spec, inference, output, capabilities, on_output, source_path)
+        return plan, []
 
     @staticmethod
     def _build_plan(
@@ -145,6 +156,7 @@ class AgentCompiler:
         inference: InferenceTarget,
         output: CompiledOutput,
         capabilities: tuple[CompiledCapability, ...],
+        on_output: CompiledOutputHook | None,
         source_path: str | None,
     ) -> AgentPlan:
         return AgentPlan(
@@ -156,6 +168,7 @@ class AgentCompiler:
             output=output,
             capabilities=capabilities,
             policies=spec.policies,
+            on_output=on_output,
             metadata=MappingProxyType(dict(spec.metadata)),
             source_path=source_path,
         )