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

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

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

{loom_kernel-2.3.1 → loom_kernel-2.4.0}/docs/ai/overview.md

@@ -207,6 +207,54 @@ place with no models starts the application with a WARNING that names
 `persistence.backend: none` as the way out, and still requires a reachable
 database.
 
+## When loom is not enough: the escape hatch
+
+Loom is a wrapper over pydantic-ai, and a wrapper you cannot step around is a
+ceiling. `native_agent` is the step around it: an async context manager that
+hands back the very `Agent` this deployment runs, the dependency bundle of
+the calling identity, and the artifact's spend caps already projected, so
+calling code can drive pydantic-ai with its own API — `iter()`,
+`run(event_stream_handler=...)`, `capture_run_messages()`, a capability of
+its own.
+
+```python
+from loom.ai.engines.pydantic_ai import native_agent
+
+async def execute(self, triage: AgentHandle[Assessment] = Agent("incident-triage")):
+    async with (
+        native_agent(triage) as access,
+        access.agent.iter(
+            "classify this page", deps=access.deps, usage_limits=access.usage_limits
+        ) as run,
+    ):
+        async for node in run:
+            ...  # your own decision between nodes
+```
+
+Loom's chain-cycle, depth and admission bounds hold for the whole block —
+there is no supported way to drive the hatch outside them, so skipping
+`max_concurrent_runs` is never the default path. Pass `access.usage_limits`
+explicitly — pydantic-ai enforces no cap you do not pass it yourself. To add
+a tool for this one run only, pass `toolsets=`/`capabilities=` to `iter()`
+rather than registering it on the shared agent (see the rule below).
+
+It lives in `loom.ai.engines.pydantic_ai`, not in `loom.ai`: importing an engine
+is the explicit act of leaving loom's neutral surface, and the neutral
+`AgentHandle.native()` returns `object` precisely so the engine package is the
+one that names the type.
+
+The full account of what still holds and what is lost is written once, on
+`AgentHandle.native()`'s own docstring — read it before relying on this hatch
+for anything beyond the sketch above.
+
+**One rule.** The `agent` you receive is the single object serving every run of
+that agent in this worker. Read it, run it, never mutate it: registering a tool,
+a validator or a capability on it changes every other run, including the ones
+loom itself drives. `access.shaped_agent` — the same spec with no output
+validator registered — stands in for it when the plan declares `output_check`
+and this run overrides the output shape: pydantic-ai refuses a run-level
+`output_type` on an agent holding one.
+
 ## Where to go next
 
 - **[Artifact reference](artifacts.md)** — the complete `spec_version: 1`

{loom_kernel-2.3.1 → loom_kernel-2.4.0}/src/loom/ai/__init__.py

@@ -33,6 +33,7 @@ from loom.ai.abc import (
     McpSession,
     McpToolCallResult,
     McpToolInfo,
+    NativeCapableEngine,
     OutputCheck,
     Prompt,
     SqlGrantHandle,
@@ -88,6 +89,7 @@ __all__ = [
     "McpSession",
     "McpToolCallResult",
     "McpToolInfo",
+    "NativeCapableEngine",
     "OutputCheck",
     "Prompt",
     "SqlGrantHandle",

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

@@ -19,7 +19,18 @@ from __future__ import annotations
 from collections.abc import AsyncIterator, Callable, Mapping, Sequence
 from contextlib import AbstractAsyncContextManager
 from decimal import Decimal
-from typing import Any, ClassVar, Final, Generic, Literal, Protocol, TypeAlias, TypeVar, overload
+from typing import (
+    Any,
+    ClassVar,
+    Final,
+    Generic,
+    Literal,
+    Protocol,
+    TypeAlias,
+    TypeVar,
+    overload,
+    runtime_checkable,
+)
 
 from loom.ai.errors import AgentRunErrorCode
 from loom.ai.inference import InferenceTarget
@@ -519,6 +530,62 @@ class AgentHandle(Protocol[AnswerT]):
         """
         ...
 
+    def native(self, *, state: object | None = None) -> object:
+        """Return the engine's own objects for this agent, outside loom's supervision.
+
+        The escape hatch: whatever the engine serving this agent was built
+        from, handed over so calling code can drive the underlying library
+        itself when loom's neutral surface does not cover what it needs.
+        Typed as ``object`` because this module names no engine; the engine
+        package publishes the accessor that narrows it — for the pydantic-ai
+        engine, :func:`loom.ai.engines.pydantic_ai.native_agent`. This is the
+        one place the full what-holds/what-is-lost list is written; every
+        other mention of it points back here.
+
+        **What still holds.** The identity bound to this handle and the
+        artefact's grants: already built into what is returned, so a run
+        driven this way still reaches exactly what the artefact granted, as
+        this caller. ``policies.tool_timeout_ms`` still bounds every
+        capability call, because it is compiled into the tools the returned
+        agent already carries. The artefact's ``output_check`` validator
+        still runs, for the same reason. So do loom's chain-cycle and
+        agent-chain-depth bounds and its admission limit
+        (``max_concurrent_runs``): the returned engine-native objects are
+        reachable only inside the accessor's own ``async with`` block
+        (:func:`loom.ai.engines.pydantic_ai.native_agent` for the
+        pydantic-ai engine), which rejoins those bounds for the whole body.
+
+        **What is lost**, always: loom's own retry policy (including the
+        rule that an agent holding a capability never retries), ``run_timeout_ms``,
+        ``max_iterations``, ``policies.on_unpriced_spend`` and the
+        ``COST_NOT_MEASURABLE`` refusal it can raise, the ``on_output`` hook,
+        the ``conversation`` loader, the event projection, loom's own output
+        decoding (:func:`~loom.ai.engines.pydantic_ai._output.decode_output`
+        for a ``msgspec.Struct`` artefact — a native run returns pydantic-ai's
+        own answer, a mapping, not the artefact's declared type) and
+        ``max_history_bytes``. An application using this hatch is also pinned
+        to the engine it names: nothing here is portable across engines.
+
+        Args:
+            state: This run's state, resolved against the artefact's declared
+                shape exactly as :meth:`run` resolves it.
+
+        Returns:
+            The engine-native objects, in the engine's own types.
+
+        Raises:
+            AgentRunError: With ``UNAUTHORIZED`` when this handle's identity
+                is anonymous, so the hatch never yields what :meth:`run`
+                would have refused; with ``STATE_UNDECLARED`` or
+                ``STATE_REQUIRED`` when *state* does not match the
+                artefact's declared shape.
+            RuntimeError: When the runtime serving this handle was never
+                entered.
+            NotImplementedError: When the engine serving this agent publishes
+                no native form.
+        """
+        ...
+
     def grants(self) -> tuple[str, ...]:
         """Return every grant name reachable through :meth:`mcp` and :meth:`sql`.
 
@@ -708,6 +775,38 @@ class AgentEngine(Protocol):
         ...
 
 
+@runtime_checkable
+class NativeCapableEngine(Protocol):
+    """An :class:`AgentEngine` that also publishes its own native form.
+
+    ``native`` is optional on :class:`AgentEngine` itself; this Protocol
+    exists only so :meth:`~loom.ai.runtime.AgentRuntime.native` can narrow to
+    it with ``isinstance`` instead of reflecting over ``getattr``.
+    """
+
+    def native(
+        self,
+        *,
+        identity: Identity,
+        state: object | None = None,
+        guard: Callable[[], AbstractAsyncContextManager[None]],
+    ) -> object:
+        """Return this engine's own objects, bound to *identity*.
+
+        Args:
+            identity: Verified caller the returned objects are built for.
+            state: This run's state, already resolved against the plan's
+                declared shape.
+            guard: Zero-argument factory of the async context manager a
+                driven run enters to rejoin the runtime's chain and
+                admission bounds.
+
+        Returns:
+            The engine's own objects, in the engine's own types.
+        """
+        ...
+
+
 HealthState = Literal["ok", "degraded", "unavailable"]
 """The three health states. Defined beside the struct that carries it so the alias
 and the field cannot drift apart."""

{loom_kernel-2.3.1 → loom_kernel-2.4.0}/src/loom/ai/engines/pydantic_ai/__init__.py

@@ -20,12 +20,30 @@ free function, because the session it opens is the very toolset the run path
 uses: one connection per server for the whole worker. :func:`create_mcp_client`
 opens a session of its own and is for diagnostics, never for wiring the
 runtime.
+
+:func:`native_agent` is the escape hatch out of loom: an async context
+manager over the agent this adapter built, handed to calling code so it can
+drive pydantic-ai directly for what loom's neutral surface does not serve.
+Being *this* package's export is the point — a caller reaching it has
+imported an engine on purpose. It rejoins loom's chain and admission bounds
+around its body; see :meth:`~loom.ai.abc.AgentHandle.native` for what a
+driven run keeps and loses. :func:`as_run_error` is exported alone for a
+driver that wants loom's error classification without that context manager.
 """
 
 from __future__ import annotations
 
 from loom.ai.engines.pydantic_ai._a2a import create_a2a_client
+from loom.ai.engines.pydantic_ai._errors import as_run_error
+from loom.ai.engines.pydantic_ai._escape import NativeAgent, native_agent
 from loom.ai.engines.pydantic_ai._mcp import create_mcp_client
 from loom.ai.engines.pydantic_ai.provider import PydanticAIEngineProvider
 
-__all__ = ["PydanticAIEngineProvider", "create_a2a_client", "create_mcp_client"]
+__all__ = [
+    "NativeAgent",
+    "PydanticAIEngineProvider",
+    "as_run_error",
+    "create_a2a_client",
+    "create_mcp_client",
+    "native_agent",
+]

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

@@ -33,9 +33,9 @@ from __future__ import annotations
 
 import asyncio
 import logging
-from collections.abc import AsyncGenerator, AsyncIterator, Mapping, Sequence
+from collections.abc import AsyncGenerator, AsyncIterator, Callable, Mapping, Sequence
 from contextlib import AbstractAsyncContextManager, asynccontextmanager
-from dataclasses import fields
+from dataclasses import fields, replace
 from time import perf_counter
 from types import MappingProxyType
 from typing import Any, Final, cast
@@ -65,6 +65,7 @@ from loom.ai.abc import (
 )
 from loom.ai.compiler import AgentPlan
 from loom.ai.engines.pydantic_ai._errors import as_run_error
+from loom.ai.engines.pydantic_ai._escape import NativeAgent, _NativeAccess
 from loom.ai.engines.pydantic_ai._events import translate
 from loom.ai.engines.pydantic_ai._history import (
     RunConversation,
@@ -334,8 +335,59 @@ class PydanticAIEngine:
             return _UNPRICED_SPEND_HEALTH
         return _HEALTHY
 
+    def native(
+        self,
+        *,
+        identity: Identity,
+        state: object | None = None,
+        guard: Callable[[], AbstractAsyncContextManager[None]],
+    ) -> _NativeAccess:
+        """Return this engine's own objects, for a caller driving the run itself.
+
+        Serves :meth:`~loom.ai.abc.AgentHandle.native` through
+        :meth:`~loom.ai.runtime.AgentRuntime.native`; the accessor that names
+        the returned type for calling code is
+        :func:`~loom.ai.engines.pydantic_ai.native_agent`. What a driver keeps
+        and loses is stated once, on :meth:`~loom.ai.abc.AgentHandle.native`.
+
+        Args:
+            identity: Verified caller the dependency bundle is built for.
+            state: This run's state, already resolved against the plan's
+                declared shape by :class:`~loom.ai.runtime.AgentRuntime`.
+            guard: Zero-argument factory of the async context manager a
+                driven run enters to rejoin this runtime's chain and
+                admission bounds; built by
+                :meth:`~loom.ai.runtime.AgentRuntime.native` and carried on
+                the returned carrier unchanged.
+
+        Returns:
+            The plan's own agent, its shaped counterpart, this caller's
+            dependency bundle and the plan's projected spend caps, paired
+            with *guard*.
+        """
+        return _NativeAccess(
+            native=NativeAgent(
+                agent=self._agent,
+                shaped_agent=self._shaped_agent,
+                deps=self._build_deps(identity, state),
+                usage_limits=replace(self._usage_limits),
+            ),
+            guard=guard,
+        )
+
     # -- internals ---------------------------------------------------------
 
+    def _build_deps(self, identity: Identity, state: object | None) -> object:
+        """Build one invocation's dependency bundle for *identity*.
+
+        *state* arrives already resolved against the plan's declared shape; it
+        is cast, never re-validated, into the mapping
+        :class:`~loom.ai.abc.DepsFactory` declares (FR-009).
+        """
+        return self._deps.build(
+            identity, self._container, state=cast("Mapping[str, Any] | None", state)
+        )
+
     async def _run_with_retries(
         self,
         prompt: Prompt,
@@ -350,15 +402,8 @@ class PydanticAIEngine:
         run cost even when the call raises — and it accumulates across retried
         attempts, because a retry spends the provider's tokens again. The
         decoded history, by contrast, is the same list on every attempt.
-
-        *state* is already resolved by
-        :class:`~loom.ai.runtime.AgentRuntime` against the plan's declared
-        shape; it is cast, never re-validated, into the mapping
-        :class:`~loom.ai.abc.DepsFactory` declares (FR-009).
         """
-        deps = self._deps.build(
-            identity, self._container, state=cast("Mapping[str, Any] | None", state)
-        )
+        deps = self._build_deps(identity, state)
         for attempt in range(self._attempts):
             try:
                 result = await self._agent.run(
@@ -535,9 +580,7 @@ class PydanticAIEngine:
         except AgentRunError as rejected:
             yield ErrorEvent(code=rejected.code, message=str(rejected))
             return
-        deps = self._deps.build(
-            identity, self._container, state=cast("Mapping[str, Any] | None", state)
-        )
+        deps = self._build_deps(identity, state)
         spend = RunUsage()
         started = perf_counter()
         for attempt in range(self._attempts):

loom_kernel-2.4.0/src/loom/ai/engines/pydantic_ai/_escape.py

@@ -0,0 +1,118 @@
+"""The escape hatch: this engine's own objects, for what loom does not serve.
+
+It lives in the engine package rather than in :mod:`loom.ai.abc` so that the
+neutral surface keeps naming no engine: importing this module is the explicit
+act of leaving loom's guarantees behind. What a run driven from here keeps and
+loses is stated once, on :meth:`~loom.ai.abc.AgentHandle.native` — this module
+carries the contract, not the reasoning.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Callable
+from contextlib import AbstractAsyncContextManager, asynccontextmanager
+from dataclasses import dataclass
+from typing import Any
+
+from pydantic_ai import Agent
+from pydantic_ai.usage import UsageLimits
+
+from loom.ai.abc import AgentHandle
+from loom.ai.engines.pydantic_ai._errors import as_run_error
+
+
+@dataclass(frozen=True, slots=True)
+class NativeAgent:
+    """What the pydantic-ai engine would itself have used to serve one run.
+
+    Attributes:
+        agent: The agent built from this plan's spec, carrying the artefact's
+            ``output_check`` validator when it declares one. Shared by every
+            run of this plan for the life of the worker: handed over as it
+            is, not copied, so mutating it changes every run of that agent
+            in this worker, including the ones loom itself drives. Refuses a
+            run-level ``output_type`` when it holds a validator (pydantic-ai's
+            own ``UserError``); use :attr:`shaped_agent` for a run that
+            overrides the output shape.
+        shaped_agent: The same agent spec, built with no ``output_check``
+            validator registered, for a run overriding the plan's declared
+            output shape. Identical to :attr:`agent` — the very same object —
+            whenever the plan declares no ``output_check``.
+        deps: The dependency bundle of one caller, carrying their verified
+            identity and this run's state. Every capability call made with it
+            runs as that caller, which is what keeps a run driven from here
+            inside the artefact's own grants.
+        usage_limits: The artefact's spend caps, projected onto the engine's
+            own type and copied for this call: mutating the returned value
+            never changes what the engine enforces on its own, loom-supervised
+            runs. Passing it on to a driven run is the caller's own choice.
+    """
+
+    agent: Agent[Any, Any]
+    shaped_agent: Agent[Any, Any]
+    deps: object
+    usage_limits: UsageLimits
+
+
+@dataclass(frozen=True, slots=True)
+class _NativeAccess:
+    """The carrier :meth:`~loom.ai.engines.pydantic_ai._engine.PydanticAIEngine.native`
+    returns: this engine's own objects, plus how to rejoin loom's bounds.
+
+    Not published: :func:`native_agent` is the one accessor calling code
+    reaches, and it is the one place this carrier is unpacked.
+    """
+
+    native: NativeAgent
+    guard: Callable[[], AbstractAsyncContextManager[None]]
+
+
+@asynccontextmanager
+async def native_agent(
+    handle: AgentHandle[Any], *, state: object | None = None
+) -> AsyncIterator[NativeAgent]:
+    """Drive one agent handle's engine-native objects inside loom's chain and admission bounds.
+
+    Args:
+        handle: Handle an ``Agent()`` marker filled, already bound to the
+            caller of the use case holding it.
+        state: This run's state, resolved against the artefact's declared
+            shape exactly as :meth:`~loom.ai.abc.AgentHandle.run` resolves it.
+
+    Yields:
+        This engine's own objects; see :class:`NativeAgent`.
+
+    Raises:
+        TypeError: When the agent behind *handle* is served by an engine
+            other than pydantic-ai.
+        NotImplementedError: When that engine publishes no native form at all.
+        AgentRunError: With ``UNAUTHORIZED`` when *handle*'s identity is
+            anonymous; with ``STATE_UNDECLARED`` or ``STATE_REQUIRED`` when
+            *state* does not match the artefact's declared shape; with
+            ``AGENT_CALL_CYCLE`` or ``AGENT_CALL_TOO_DEEP`` when entering the
+            guard refuses this run; with ``TOO_MANY_RUNS`` when no admission
+            permit is free.
+        RuntimeError: When the runtime serving *handle* was never entered.
+
+    Example::
+
+        async with (
+            native_agent(handle) as access,
+            access.agent.iter(
+                "triage this", deps=access.deps, usage_limits=access.usage_limits
+            ) as run,
+        ):
+            async for node in run:
+                ...
+    """
+    access = handle.native(state=state)
+    if not isinstance(access, _NativeAccess):
+        raise TypeError(
+            "this agent is not served by the pydantic-ai engine: its native form is "
+            f"{type(access).__name__}, not the pydantic-ai engine's own carrier"
+        )
+    async with access.guard():
+        yield access.native
+
+
+__all__ = ["NativeAgent", "as_run_error", "native_agent"]

{loom_kernel-2.3.1 → loom_kernel-2.4.0}/src/loom/ai/runtime/_handle.py

@@ -172,6 +172,33 @@ class _BoundAgentHandle:
         answer = await self.run(prompt, expect=str, conversation_id=conversation_id, state=state)
         return answer
 
+    def native(self, *, state: object | None = None) -> object:
+        """Return the engine's own objects for this agent, bound to this caller.
+
+        Opens no span and takes no admission slot: nothing is run here, and
+        what the caller then does with the returned objects is outside this
+        runtime's supervision. See :meth:`~loom.ai.abc.AgentHandle.native`.
+
+        Args:
+            state: This run's state, resolved against the artefact's declared
+                shape exactly as :meth:`run` resolves it.
+
+        Returns:
+            The engine-native objects, in the engine's own types.
+
+        Raises:
+            AgentRunError: With ``UNAUTHORIZED`` when this handle's identity is
+                anonymous — the same refusal :meth:`run` makes, so the hatch
+                never yields a bundle the run path would have refused; with
+                ``STATE_UNDECLARED`` or ``STATE_REQUIRED`` when *state* does
+                not match the artefact's declared shape.
+            RuntimeError: When this handle's runtime was never entered.
+            NotImplementedError: When the engine serving this agent declares
+                no native form.
+        """
+        self._require_authenticated()
+        return self._runtime.native(self._name, identity=self._identity, state=state)
+
     def mcp(self, server: str) -> McpHandle:
         """Return this artefact's own filtered view of one ``mcp`` grant.
 

{loom_kernel-2.3.1 → loom_kernel-2.4.0}/src/loom/ai/runtime/_lifecycle.py

@@ -40,6 +40,7 @@ from loom.ai.abc import (
     HealthState,
     McpSession,
     McpToolInfo,
+    NativeCapableEngine,
     Prompt,
     StateShape,
 )
@@ -1031,6 +1032,58 @@ class AgentRuntime:
         self._require_plan(name)
         return self._grants[name]
 
+    def native(self, name: str, *, identity: Identity, state: object | None = None) -> object:
+        """Return one agent's engine-native objects, outside this runtime's supervision.
+
+        Serves :meth:`~loom.ai.abc.AgentHandle.native`; see it for what a run
+        driven through the returned objects keeps and what it loses.
+
+        Args:
+            name: Agent whose engine is asked for its native form.
+            identity: Verified caller the returned objects are bound to.
+            state: This run's state, resolved against *name*'s declared shape
+                exactly as :meth:`run` resolves it.
+
+        Returns:
+            The engine's own objects, in the engine's own types.
+
+        Raises:
+            KeyError: When no agent is named *name*.
+            RuntimeError: When this runtime was never entered.
+            AgentRunError: With ``STATE_UNDECLARED`` or ``STATE_REQUIRED``
+                when *state* does not match *name*'s declared shape.
+            NotImplementedError: When the engine serving *name* declares no
+                ``native``.
+        """
+        slot = self._require_slot(name)
+        resolved_state = _resolve_state(name, slot.plan.state, state)
+        if not isinstance(slot.engine, NativeCapableEngine):
+            raise NotImplementedError(
+                f"{type(slot.engine).__name__} publishes no native form: it declares no 'native'"
+            )
+        return slot.engine.native(
+            identity=identity, state=resolved_state, guard=self._native_guard(name)
+        )
+
+    def _native_guard(self, name: str) -> Callable[[], AbstractAsyncContextManager[None]]:
+        """Build the guard a hand-driven run of *name* enters to rejoin this runtime's bounds.
+
+        Composes :meth:`_chain_bound` and :meth:`_admitted` in the same order
+        :meth:`_run_stream` does, so a run entered through the returned
+        factory is subject to the same cycle, depth and admission bounds as
+        one this runtime drives itself. Handed to the engine's own
+        ``native()`` rather than entered here: the engine pairs it with its
+        own objects, and :func:`~loom.ai.engines.pydantic_ai.native_agent`
+        is the one place it is entered, around the whole hand-driven run.
+        """
+
+        @asynccontextmanager
+        async def _guard() -> AsyncIterator[None]:
+            async with self._chain_bound(name), self._admitted(name):
+                yield
+
+        return _guard
+
     def _build_grants(self) -> dict[str, AgentGrants]:
         """Resolve every plan's grants once, right after its engine is built."""
         return {name: self._plan_grants(plan) for name, plan in self._plans.items()}

{loom_kernel-2.3.1 → loom_kernel-2.4.0}/src/loom/testing/runner.py

@@ -466,6 +466,23 @@ class AgentHandleDouble:
             "call .on_run_text(...) before running the use case",
         )
 
+    def native(self, *, state: object | None = None) -> object:
+        """Refuse the escape hatch: a double has no engine behind it.
+
+        :meth:`~loom.ai.abc.AgentHandle.native` hands back the objects of a
+        live engine, and there is none here. A use case that reaches for it
+        is driving the underlying library itself, which is exactly the code
+        this double cannot stand in for: test it against a real runtime.
+
+        Raises:
+            NotImplementedError: Always.
+        """
+        del state
+        raise NotImplementedError(
+            f"agent {self._name!r} double received native(); a double has no engine behind it, "
+            "so a use case driving the engine itself needs a real runtime to test against"
+        )
+
     def mcp(self, server: str) -> McpHandleDouble:
         """Return this agent's own double for the ``mcp`` grant named *server*.