ph-core 0.2.0__py3-none-any.whl

ph/__init__.py

@@ -0,0 +1,9 @@
+"""pH — a Python agent harness ported from DeepSeek Harness.
+
+The core distribution. See `docs/dev-notes/phase-0.md` for what Phase 0 landed
+and `plans/Implementation_Plan.md` for the work breakdown.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.2.0"

ph/agent/__init__.py

@@ -0,0 +1,33 @@
+"""`ph.agent` — the agent handle, its inbox, and the registry."""
+
+from __future__ import annotations
+
+from .inbox import Inbox, InboxNotifications, InboxTarget
+from .registry import AgentRegistry
+from .types import (
+    AgentCancelCause,
+    AgentOptions,
+    AgentStatus,
+    PreStepDecision,
+    PreStepRequest,
+    RequestErrorAction,
+    RequestFailure,
+    RequestProposal,
+    TurnEndReason,
+)
+
+__all__ = [
+    "AgentCancelCause",
+    "AgentOptions",
+    "AgentRegistry",
+    "AgentStatus",
+    "Inbox",
+    "InboxNotifications",
+    "InboxTarget",
+    "PreStepDecision",
+    "PreStepRequest",
+    "RequestErrorAction",
+    "RequestFailure",
+    "RequestProposal",
+    "TurnEndReason",
+]

ph/agent/inbox.py

@@ -0,0 +1,215 @@
+"""The agent inbox: durable, replayable pending input.
+
+Three delivery semantics, ported exactly, because the difference is what makes
+steering feel instant and injection feel invisible:
+
+| call | lands at | wakes an idle agent |
+|---|---|---|
+| `followup(msg)` | next **turn** | yes |
+| `steer(msg)` | next **step** | yes |
+| `inject(msg)` | next **step** | **no** — it waits for another message |
+
+Every mutation is logged as `agent/inbox/spliced` *before* the projection
+changes, so a resumed agent reconstructs its queue from the log rather than
+losing whatever the user typed before the crash.
+
+@module ph.agent.inbox
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from typing import Literal, TypeAlias
+
+from pydantic import ConfigDict
+
+from ..json import JsonObject
+from ..llm.types import Message
+from ..session import Session
+from ..wire import WireModel
+
+__all__ = ["Inbox", "InboxNotifications", "InboxTarget"]
+
+InboxTarget: TypeAlias = Literal["next-turn", "next-step"]
+
+
+@dataclass(frozen=True, slots=True)
+class InboxNotifications:
+    """Live mirrors of durable inbox mutations."""
+
+    inserted: Callable[[Message], None]
+    discarded: Callable[[Message], None]
+    claimed: Callable[[Message, int], None]
+
+
+class InboxSplice(WireModel):
+    """One inbox mutation, as `agent/inbox/spliced` carries it.
+
+    Declared rather than hand-built and hand-parsed, the way every other durable
+    payload is (`UserQuestion`, `RequestContext`, `Message`): `WireModel` owns the
+    camelCase aliases and the log's frozen mapping, so `_mutate` writing a key and
+    `_apply` reading one cannot drift, and `ph_app.tui.adapter` has something to
+    validate against instead of re-spelling `inserted` and `removedCount`.
+
+    `removed_count` is `None` rather than `0` when absent, and `outcome` likewise,
+    because `to_wire()` omits `None` — an insert-only splice must not start
+    emitting `"removedCount": 0` into logs that never carried it.
+
+    `extra="ignore"` overrides `WireModel`'s `forbid`: a log is read by builds
+    older than the one that wrote it, and a key added later must be skipped on
+    replay rather than condemn the whole session.
+    """
+
+    model_config = ConfigDict(extra="ignore")
+
+    target: InboxTarget
+    start: int
+    inserted: list[Message]
+    removed_count: int | None = None
+    outcome: Literal["canceled"] | None = None
+    """Whether the removed messages were canceled or consumed. Written and not
+    yet read back: live, the difference is `_notify.discarded` against
+    `_notify.claimed`, and on replay this key is the only thing that still knows
+    which happened."""
+
+
+class Inbox:
+    """A replay-once projection that incrementally consumes later splices."""
+
+    __slots__ = ("_notify", "_session", "_state")
+
+    def __init__(self, session: Session, notifications: InboxNotifications) -> None:
+        self._session = session
+        self._notify = notifications
+        self._state: dict[str, list[Message]] = {"next-turn": [], "next-step": []}
+        # Replay only this lifecycle's splices: a fork inherits its parent's
+        # transcript, not its parent's unanswered queue.
+        for event in session.events[session.header.seed_length or 0 :]:
+            if event.type != "agent/inbox/spliced":
+                continue
+            try:
+                self._apply(event.data)
+            except ValueError as error:
+                raise ValueError(
+                    f"invalid persisted inbox splice at session seq {event.seq}"
+                ) from error
+
+    @property
+    def next_turn(self) -> tuple[Message, ...]:
+        return tuple(self._state["next-turn"])
+
+    @property
+    def next_step(self) -> tuple[Message, ...]:
+        return tuple(self._state["next-step"])
+
+    @property
+    def has_pending(self) -> bool:
+        return bool(self._state["next-turn"] or self._state["next-step"])
+
+    def clear(self) -> None:
+        """Durably cancel all pending input, next-step before next-turn."""
+        self.splice("next-step", 0, len(self._state["next-step"]), [])
+        self.splice("next-turn", 0, len(self._state["next-turn"]), [])
+
+    def claim(self, target: InboxTarget, turn: int) -> list[Message]:
+        """Take the batch proposed for one step.
+
+        Always every pending `next-step` message, plus — at a turn boundary —
+        exactly one queued turn. Claiming more than one turn would merge two
+        user prompts into one model call.
+        """
+        claimed = self._mutate("next-step", 0, len(self._state["next-step"]), [], False)
+        if target == "next-turn":
+            claimed.extend(self._mutate("next-turn", 0, 1, [], False))
+        for message in claimed:
+            self._notify.claimed(message, turn)
+        return claimed
+
+    def append(self, target: InboxTarget, message: Message) -> None:
+        self.splice(target, len(self._state[target]), 0, [message])
+
+    def splice(
+        self, target: InboxTarget, start: int, delete_count: int, inserted: Sequence[Message]
+    ) -> list[Message]:
+        """Standard splice semantics, durably recorded; removed messages are canceled."""
+        return self._mutate(target, start, delete_count, list(inserted), True)
+
+    # ------------------------------------------------------------- internals --
+
+    def _mutate(
+        self,
+        target: InboxTarget,
+        start: int,
+        delete_count: int,
+        inserted: list[Message],
+        discard_removed: bool,
+    ) -> list[Message]:
+        pending = self._state[target]
+        start = min(max(start, 0), len(pending))
+        delete_count = min(max(delete_count, 0), len(pending) - start)
+        if delete_count == 0 and not inserted:
+            return []
+        splice = InboxSplice(
+            target=target,
+            start=start,
+            inserted=inserted,
+            removed_count=delete_count or None,
+            outcome="canceled" if delete_count and discard_removed else None,
+        )
+        # The one rule a write can still break. The coordinates are clamped above
+        # and the values are already typed, so there is nothing here to parse.
+        self._unique(target, start, delete_count, inserted)
+        # The durable event commits BEFORE the live projection mutates, so a
+        # synchronous `session/event` observer sees the pre-splice lists and can
+        # reconstruct exactly what was removed from the normalized coordinates.
+        self._session.append("agent/inbox/spliced", splice.to_wire())
+        removed = pending[start : start + delete_count]
+        pending[start : start + delete_count] = inserted
+        if discard_removed:
+            for message in removed:
+                self._notify.discarded(message)
+        for message in inserted:
+            self._notify.inserted(message)
+        return list(removed)
+
+    def _apply(self, splice: JsonObject) -> None:
+        """Replay one logged splice, or refuse the log."""
+        parsed = InboxSplice.model_validate(splice)
+        pending = self._state[parsed.target]
+        removed_count = parsed.removed_count or 0
+        self._placed(parsed.target, parsed.start, removed_count)
+        self._unique(parsed.target, parsed.start, removed_count, parsed.inserted)
+        pending[parsed.start : parsed.start + removed_count] = list(parsed.inserted)
+
+    def _placed(self, target: InboxTarget, start: int, removed_count: int) -> None:
+        """That the coordinates fall inside the queue they name.
+
+        Replay only: `_mutate` clamps both into range before it writes, so on the
+        write path these branches cannot fail and checking them there would read
+        as though they could.
+        """
+        pending = self._state[target]
+        if not 0 <= start <= len(pending) or not 0 <= removed_count <= len(pending) - start:
+            raise ValueError("invalid inbox splice")
+
+    def _unique(
+        self, target: InboxTarget, start: int, removed_count: int, inserted: Sequence[Message]
+    ) -> None:
+        """That no message id would end up pending twice, across both queues.
+
+        The one rule both paths share, so it takes messages rather than a payload:
+        `_mutate` is holding the `Message` list it just built and has no reason to
+        serialize it and read the ids back out.
+        """
+        pending = self._state[target]
+        other: InboxTarget = "next-step" if target == "next-turn" else "next-turn"
+        candidate = [
+            *(m.id for m in pending[:start]),
+            *(m.id for m in inserted),
+            *(m.id for m in pending[start + removed_count :]),
+            *(m.id for m in self._state[other]),
+        ]
+        if len(set(candidate)) != len(candidate):
+            duplicate = next(i for i in candidate if candidate.count(i) > 1)
+            raise ValueError(f'message "{duplicate}" is already pending')

ph/agent/registry.py

@@ -0,0 +1,186 @@
+"""`ctx.agents` — agent creation, and the events every agent publishes.
+
+An agent is a handle: an id, a session, a **scoped context**, an inbox, a
+status and a cancel. The registry owns the scope — it creates it, provides the
+handle into it as `agent`, and disposes it — and the driver runs inside it.
+That split is what keeps the loop a replaceable row (invariant I1): a second
+driver inherits the scope tree, the `agent` provision and the lifecycle events
+without reproducing them.
+
+@module ph.agent.registry
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+
+from ..cordis import Context, events, plugin
+from ..keys import AGENT, AGENTS, SESSIONS
+from ..session import Session
+from .types import (
+    AgentDriver,
+    AgentHandle,
+    AgentOptions,
+    PreStepRequest,
+    RequestFailure,
+    RequestProposal,
+)
+
+__all__ = ["AgentRegistry", "apply"]
+
+events.declare("agent/created", "emit", owner="ph.agent", doc="An agent handle was created.")
+events.declare("agent/disposed", "emit", owner="ph.agent", doc="An agent handle was disposed.")
+events.declare(
+    "agent/status", "emit", owner="ph.agent", doc="An agent moved between idle and running."
+)
+events.declare(
+    "agent/error", "emit", owner="ph.agent", doc="A failure was reported at its live boundary."
+)
+events.declare("agent/session-start", "emit", owner="ph.agent", doc="An agent bound a session.")
+events.declare(
+    "agent/inbox/inserted", "emit", owner="ph.agent", doc="A message entered a pending list."
+)
+events.declare(
+    "agent/inbox/claimed", "emit", owner="ph.agent", doc="A pending message was claimed for a turn."
+)
+events.declare(
+    "agent/inbox/discarded", "emit", owner="ph.agent", doc="A pending message was canceled."
+)
+events.declare(
+    "agent/pre-step",
+    "waterfall",
+    PreStepRequest,
+    owner="ph.agent",
+    doc="The authoritative reject-or-enter decision for one step.",
+)
+events.declare(
+    "agent/request",
+    "waterfall",
+    RequestProposal,
+    owner="ph.agent",
+    doc="Proposes the call config for one request.",
+)
+events.declare(
+    "agent/request-error",
+    "waterfall",
+    RequestFailure,
+    owner="ph.agent",
+    doc="A failed request; a listener may answer with a retry.",
+)
+events.declare(
+    "agent/turn-stopping",
+    "serial",
+    owner="ph.agent",
+    doc="Last chance to keep a turn alive; a listener objects by steering.",
+)
+
+DriverFactory = Callable[[Context, Session, AgentOptions], AgentDriver]
+"""Builds a driver inside an already-created agent scope."""
+
+
+@dataclass(slots=True)
+class AgentRegistry:
+    """The service published as `ctx.agents`."""
+
+    ctx: Context
+    driver_factory: DriverFactory | None = None
+    _agents: dict[str, AgentDriver] = field(default_factory=dict)
+
+    def register_driver(self, factory: DriverFactory) -> Callable[[], None]:
+        """Claim the driver used by `create()`.
+
+        The loop is a plugin like any other (invariant I1): swapping it is a row
+        change, not a fork.
+        """
+        self.driver_factory = factory
+
+        def release() -> None:
+            if self.driver_factory is factory:
+                self.driver_factory = None
+
+        return release
+
+    def create(
+        self,
+        session: Session,
+        options: AgentOptions | None = None,
+        *,
+        parent: AgentHandle | None = None,
+    ) -> AgentDriver:
+        """Build an agent and the scope it owns.
+
+        **`parent` puts the child's scope inside its parent's** (P6-27), which is what
+        makes containment structural instead of materialized. Three things then stop being
+        remembered:
+
+        * **visibility inherits**, because `isolation_chain` reaches the parent's layers
+          and the existing masking already walks it;
+        * **disposal cascades**, because `Context.dispose` already unwinds `_children`;
+        * **a parent can reach its child**, which is what makes a supervisor able to
+          diagnose one.
+
+        Optional and defaulting to a root agent with no parent.
+        """
+        if self.driver_factory is None:
+            raise RuntimeError("no agent driver is registered; mount an agent-loop row")
+        base = parent.ctx if parent is not None else self.ctx
+        scope = base.scope(f"agent:{session.id}")
+        agent = self.driver_factory(scope, session, options or AgentOptions())
+        scope.provide(AGENT, agent)
+        self._agents[agent.id] = agent
+        # **The roster entry is an effect of the scope it describes**, which it
+        # had to become the moment P6-27 nested agents: `dispose(agent_id)` used
+        # to be the only thing that popped `_agents`, and a parent's
+        # `Context.dispose` now tears a child's scope down without going through
+        # it. That left `agents.get(child)` handing back a live-looking handle
+        # over a dead context, `agents.list()` — "every live agent, for a sweep
+        # that must visit all of them" — including it, and `agent/disposed`
+        # never firing. Structural for the same reason the lifetime is: a second
+        # provider that nests without registering a teardown effect of its own
+        # cannot leak a handle it never had to remember.
+        scope.add_disposer(lambda: self._forget(agent), label=f"agents.entry({agent.id})")
+        scope.emit("agent/created", agent)
+        scope.emit("agent/session-start", agent, session)
+        return agent
+
+    def get(self, agent_id: str) -> AgentDriver | None:
+        """The live agent by id, or `None`. The symmetric read to `ctx.sessions.get`.
+
+        A plugin that has an agent id — a runtime keyed by it, a policy folding
+        its session — reaches the agent's scope and session through here, instead
+        of shadowing the registry with its own `agent/created` side table.
+        """
+        return self._agents.get(agent_id)
+
+    def list(self) -> list[AgentDriver]:
+        """Every live agent, for a sweep that must visit all of them."""
+        return list(self._agents.values())
+
+    def _forget(self, agent: AgentDriver) -> None:
+        """Drop the roster entry and announce it, once, whoever unwound the scope.
+
+        Both doors reach here: `dispose(agent_id)` below, and a parent scope
+        cascading into this one. `emit` before the pop is deliberate — a listener
+        asking `agents.get` about the agent it is being told about should still
+        find it — and the pop is idempotent, so the explicit path calling
+        `scope.dispose()` afterwards runs this a second time and does nothing.
+        """
+        if self._agents.pop(agent.id, None) is None:
+            return
+        agent.ctx.emit("agent/disposed", agent)
+
+    async def dispose(self, agent_id: str) -> None:
+        agent = self._agents.get(agent_id)
+        if agent is None:
+            return
+        await agent.dispose()
+        # `_forget` rides the scope's own teardown, so the announcement and the
+        # roster drop happen exactly once whichever way the scope goes.
+        await agent.ctx.dispose()
+
+
+@plugin("agent", inject=[SESSIONS])
+async def apply(ctx: Context, config: None) -> None:
+    """Mount the agent registry."""
+    ctx.provide(AGENTS, AgentRegistry(ctx=ctx))

ph/agent/types.py

@@ -0,0 +1,214 @@
+"""Agent-facing vocabulary: cancellation causes, decisions, turn endings, and
+the payloads the agent waterfalls carry.
+
+The waterfall payloads are frozen dataclasses rather than string-keyed dicts so
+a listener's signature *is* the contract: the limits and permissions plugins
+(Phase 4) that own `agent/pre-step`, and the retry plugin on
+`agent/request-error`, read fields the type checker knows about, and
+`phern events` can name the payload beside the event.
+
+@module ph.agent.types
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal, Protocol, TypeAlias
+
+from ..cancel import Cancellation
+from ..llm.types import LlmCallConfig, LlmFailure, Message
+from ..wire import WireDataclass
+
+if TYPE_CHECKING:
+    from ..cordis import Context
+    from ..session import Session
+    from .inbox import Inbox
+
+__all__ = [
+    "AgentCancelCause",
+    "AgentDriver",
+    "AgentHandle",
+    "AgentOptions",
+    "AgentStatus",
+    "PreStepDecision",
+    "PreStepRequest",
+    "RequestErrorAction",
+    "RequestFailure",
+    "RequestProposal",
+    "TurnEndReason",
+]
+
+AgentStatus: TypeAlias = Literal["idle", "running"]
+
+
+class AgentHandle(Protocol):
+    """What a seam, a tool body or a waterfall payload may assume about an agent.
+
+    Six read-only facts, and deliberately no more: this is the surface the
+    seams actually read, and it is the surface `ph.testing.StubAgent` has, so a
+    test can stand in an agent without standing up a loop. A Protocol rather than
+    the driver class for two reasons that reinforce each other: two
+    implementations exist (the loop and the stub), and the driver imports this
+    module, so naming it here would be a cycle.
+
+    **`signal` is the sixth, and it is here because two seams already reached
+    for it.** `AgentDriver.cancel` is the verb; the token it trips is the fact,
+    and a row that *asks a human* has to know whether the work is still wanted
+    before it puts a question on someone's screen. `ph_stabilize.permissions_fs`
+    and the RLM harness both wrote `getattr(agent, "signal", None)` for it — no
+    agent had the attribute, so the default answered every call.
+
+    `Cancellation`, not `CancelToken`: a seam may ask whether the work is still
+    wanted and may not end it. Non-optional because every driver owns one —
+    `_Phase.token` is built at construction and is what `session/cancel` trips,
+    through the verb the TUI and RPC share.
+
+    **`status` is a fact, not a verb**, which is why it is here and not on
+    `AgentDriver` beside `cancel`. It was on the driver, so a seam holding a
+    handle could not ask whether the agent was busy — and `compaction` asked with
+    `getattr(agent, "status", "idle")`, whose default answered *idle* for every
+    stub, in the one place that refuses to compact a working agent.
+
+    Properties rather than attributes, so that a driver whose `session` is a
+    `Session` satisfies a reader that accepts `Session | None`: a Protocol
+    attribute is settable and therefore invariant, and would refuse exactly the
+    implementation this describes.
+    """
+
+    @property
+    def id(self) -> str: ...
+    @property
+    def ctx(self) -> Context: ...
+    @property
+    def session(self) -> Session | None: ...
+    @property
+    def options(self) -> AgentOptions: ...
+    @property
+    def status(self) -> AgentStatus: ...
+    @property
+    def signal(self) -> Cancellation: ...
+
+
+class AgentDriver(AgentHandle, Protocol):
+    """What the registry, the daemon and a supervising row may *do* to an agent.
+
+    The handle plus the verbs — the surface `AgentRegistry.create` hands back and
+    `ph_app`'s supervisor drives. Separate from `AgentHandle` because most callers
+    have no business steering: a seam that could reach `cancel` through a
+    parameter typed for reading is a seam that will, eventually.
+    """
+
+    @property
+    def inbox(self) -> Inbox: ...
+    def steer(self, message: Message) -> None: ...
+    def inject(self, message: Message) -> None: ...
+    def followup(self, message: Message) -> None: ...
+    def interject(self, message: Message) -> None: ...
+    def cancel(self, cause: AgentCancelCause, *, keep_inbox: bool = False) -> None: ...
+    async def run(self) -> None: ...
+    async def prompt(self, text: str) -> None: ...
+    async def dispose(self) -> None: ...
+
+
+@dataclass(frozen=True, slots=True)
+class AgentCancelCause(WireDataclass):
+    """Why an active driver was canceled."""
+
+    kind: Literal["user", "parent", "hook", "disposed", "legacy"]
+    reason: str | None = None
+    """Set only for `hook`: which listener objected, and why."""
+
+
+@dataclass(frozen=True, slots=True)
+class TurnEndReason(WireDataclass):
+    """Why a turn ended.
+
+    `error` always carries structured facts rather than a flattened string: the
+    code is what a retry policy and a later reader both route on.
+    """
+
+    kind: Literal["completed", "aborted", "blocked", "error", "max-tokens", "interrupted"]
+    reason: AgentCancelCause | None = None
+    error: LlmFailure | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class PreStepRequest:
+    """`agent/pre-step`: the batch about to enter a step, before the decision.
+
+    **`session` is not optional here**, though `AgentHandle.session` is. A
+    pre-step is a step about to happen, so there is a turn, so there is a
+    session — and the one production constructor is the driver, whose own
+    `session` is a `Session`. The handle keeps its `| None` for the callers that
+    hold one outside a turn, and for `StubAgent`. Three listeners on this chain
+    each re-derived it from the handle and each guarded the `None` differently.
+    """
+
+    agent: AgentHandle
+    session: Session
+    messages: tuple[Message, ...]
+    turn: int
+    step: int
+
+
+@dataclass(frozen=True, slots=True)
+class PreStepDecision:
+    """The authoritative decision about whether a step happens, and with what.
+
+    `reject` closes the turn as `blocked`; `enter` supplies the exact messages
+    the step will log. A limits or permissions plugin owns this decision by
+    returning without calling `next()`.
+    """
+
+    kind: Literal["reject", "enter"]
+    messages: tuple[Message, ...] = ()
+    reason: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class RequestProposal:
+    """`agent/request`: the call config the loop proposes for one request."""
+
+    agent: AgentHandle
+    turn: int
+    step: int
+    config: LlmCallConfig
+
+
+@dataclass(frozen=True, slots=True)
+class RequestFailure:
+    """`agent/request-error`: a request that ended in `error` or `aborted`."""
+
+    agent: AgentHandle
+    turn: int
+    step: int
+    provider: str
+    failure: LlmFailure
+
+
+@dataclass(frozen=True, slots=True)
+class RequestErrorAction:
+    """What to do about a failed model request: retry, or let it stand."""
+
+    kind: Literal["retry"]
+    delay_ms: int = 0
+
+
+@dataclass(frozen=True, slots=True)
+class AgentOptions:
+    """Per-agent settings resolved at creation."""
+
+    provider: str = ""
+    model: str = ""
+    max_tokens: int | None = None
+    temperature: float | None = None
+    reasoning_effort: str | None = None
+
+    def seed_config(self) -> LlmCallConfig:
+        return LlmCallConfig(
+            provider=self.provider,
+            model=self.model,
+            reasoning_effort=self.reasoning_effort,
+            temperature=self.temperature,
+            max_tokens=self.max_tokens,
+        )

ph/agent_loop/__init__.py

@@ -0,0 +1,35 @@
+"""`ph.agent_loop` — the ReAct driver, mounted as a row like anything else."""
+
+from __future__ import annotations
+
+from functools import partial
+
+from ..agent.registry import DriverFactory
+from ..cordis import Context, plugin
+from ..keys import AGENTS, LLM, SESSIONS, SYSTEM_PROMPT
+from ..wire import WireModel
+from .driver import AgentCanceled, ReactLoopAgent
+
+__all__ = ["AgentCanceled", "Config", "ReactLoopAgent", "apply"]
+
+
+class Config(WireModel):
+    """Row config for the loop.
+
+    `max_parallel_tool_calls` is the native batch pool width — an agent-loop
+    setting, as in dsh (`agentLoop.config.maxParallelToolCalls`), distinct from
+    the Code Mode row's `max_parallel_sub_calls` for one program's sub-calls.
+    """
+
+    max_parallel_tool_calls: int = 10
+
+
+@plugin("agent-loop", config=Config, inject=[AGENTS, LLM, SESSIONS, SYSTEM_PROMPT])
+async def apply(ctx: Context, config: Config) -> None:
+    """Register `ReactLoopAgent` as the driver `ctx.agents.create()` uses."""
+    # Annotated, so mypy holds the driver to `AgentDriver` here — `ctx.agents` is
+    # untyped, so `register_driver` would take anything.
+    factory: DriverFactory = partial(
+        ReactLoopAgent, max_parallel_tool_calls=config.max_parallel_tool_calls
+    )
+    ctx.add_disposer(ctx.require(AGENTS).register_driver(factory), label="agent-loop")