weft-rag 2.4.0__py3-none-any.whl

weft_agent/__init__.py

@@ -0,0 +1,69 @@
+"""First-party agentic front end — task **7.1**, `docs/05-grilling-sessions.md` G8.
+
+**A pack, not an agentic REPL.** `docs/03`'s governing rule keeps logic out of the driving
+adapter; G8 settled that the agent lands after release, built against `weft-kernel` and
+`weft-rag`'s *published, versioned* API rather than a moving one — so it registers through the
+same `weft.packs` entry point a third party would use, and nothing here reaches into
+`weft_cli`. `tests/architecture/test_ff21_agent_is_an_ordinary_pack.py`'s own module docstring
+states the three properties that test falsifies; this pack's whole job at 7.1 is to be a
+distribution that satisfies all three and nothing more.
+
+**Registers `next-action` against `weft_prompts.contract.Prompt`, and, since task 7.4, `agent`
+against `weft_command.contract.Command` — both contracts published by `weft-rag`, never by this
+pack**, the structural half of `01` -> Phase 7's own claim, "built against nothing but the
+released API". `weft_agent.command.AgentCommand` is the loop (task 7.2) and the tool catalogue
+(task 7.3) reached through the one surface a stranger's own command would use; see that
+module's own docstring for the ambient-service seam it needed `weft_cli.cli.run_command` to
+open. `AgentCommandResult`'s own renderer is registered the identical way any pack's is
+(`weft_kernel.discovery.PackRegistrar.add_renderer`, task 6.20's own seam).
+"""
+
+from __future__ import annotations
+
+from functools import partial
+
+from pydantic import BaseModel, ConfigDict
+
+from weft_agent.command import AgentCommand, AgentCommandResult
+from weft_agent.prompts import NEXT_ACTION_NAME, NextActionPrompt
+from weft_agent.render import render_agent
+from weft_command.contract import Command
+from weft_kernel.discovery import PackRegistrar
+from weft_prompts.contract import Prompt
+
+
+class Settings(BaseModel):
+    """`weft-agent`'s pack settings — task 7.2's own: the loop's step budget.
+
+    `max_steps` is an operator's decision, not a number baked into `weft_agent.loop`, per that
+    module's own docstring. Defaulted to 10: enough for a handful of tool calls plus a final
+    answer on the kind of multi-step retrieval question this pack exists for, without letting a
+    model stuck in a loop run away unbounded.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    max_steps: int = 10
+
+
+def register(registrar: PackRegistrar, settings: Settings) -> None:
+    """Register `NextActionPrompt` as `"next-action"` for `Prompt`, `AgentCommand` as `"agent"`
+    for `Command`, and that command's own renderer.
+
+    `settings` is accepted, per the fixed two-parameter shape every pack declares, and unused —
+    `AgentCommand.run` reads `Settings` itself, for the reason its own module docstring gives
+    (a module-scope import here would be circular).
+    """
+    registrar.add(Prompt, NEXT_ACTION_NAME, NextActionPrompt)
+    registrar.add(Command, "agent", partial(AgentCommand, settings))
+    registrar.add_renderer(AgentCommandResult, render_agent)
+
+
+__all__ = [
+    "NEXT_ACTION_NAME",
+    "AgentCommand",
+    "AgentCommandResult",
+    "NextActionPrompt",
+    "Settings",
+    "register",
+]

weft_agent/command.py

@@ -0,0 +1,147 @@
+"""`weft agent` — the command that drives `weft_agent.loop.run_agent` through the published
+`weft_command.contract.Command` surface. Ledger task **7.4**.
+
+**This is the seam Phase 8's own close review predicted, one phase early.** `docs/lessons.md`
+`L5.15`'s shape — a *consuming* side of `ServiceRegistry` anyone can reach (`ctx.require`) and a
+*producing* side reachable only by editing `weft-cli` — is what made this command impossible to
+write honestly until `weft_cli.cli.run_command` registered the run's `LLM` (and `Prompts`,
+`TokenSink`) by their *published contract types*, not only under its own private `Dependencies`.
+See that module's own docstring for the repair; nothing here depends on `weft_cli` at all, and
+`weft_agent` must not — that pack boundary is task 7.1's own claim and this task does not reopen
+it.
+
+**`registry = ctx.require(Registry)`, not a name this command resolves itself.** The agent's own
+tool catalogue is built from whatever `Registry` the run assembled (`weft_agent.command_tools.
+command_tools`), which is `ctx.require`'s exact job: a service every stage may need regardless of
+what pipeline runs, resolved by type with no name to disambiguate — there is exactly one registry
+per run.
+
+**The command declares `write`, not more.** `03` → *Permissions*: a command declares the highest
+class it may reach, and the agent may reach `write` commands (`weft_agent.tools.
+REACHABLE_CLASSES`) but never `overwrite`/`destroy` — G12's ceiling, held by that catalogue and by
+`weft_agent.command_tools.RefusingConsent`, not by this declaration. Declaring `destroy` here
+would ask a human to confirm something the agent cannot do anyway.
+
+**`max_steps` comes from `weft_agent.Settings`, this pack's own configured budget** — an
+operator's decision (that model's own docstring), read here rather than hard-coded a second time.
+Imported inside `run`, not at module scope: `weft_agent/__init__.py` imports `AgentCommand` from
+this module to register it, so a module-scope `from weft_agent import Settings` here would be a
+circular import at the moment `weft_agent` itself is still being defined.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from weft_agent import Settings
+
+from collections.abc import Mapping
+from typing import ClassVar, cast
+
+from pydantic import BaseModel, ConfigDict
+
+from weft_agent.command_tools import command_tools
+from weft_agent.loop import AgentTool, StopReason, run_agent
+from weft_agent.payload import AgentTranscript
+from weft_command.contract import CommandResult
+from weft_command.permission import PermissionClass
+from weft_kernel.context import Context
+from weft_kernel.payload import Outcome, Produced
+from weft_kernel.registry import Registry
+from weft_llm.contract import LLM
+
+_AGENT_HELP = (
+    "drive a goal to an answer, calling the run's published commands as tools "
+    "(docs/01-high-level-plan.md -> Phase 7)"
+)
+
+
+class AgentArgs(BaseModel):
+    """What `weft agent` needs from a caller: the goal to work toward, and nothing else."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    goal: str
+
+
+class AgentCommandResult(CommandResult):
+    """What one agent run produced — the full transcript, the final answer if there is one,
+    and why the loop stopped. The same three facts `weft_agent.loop.AgentOutcome` carries,
+    restated as a `CommandResult` so `weft_cli`/a stranger's renderer can format them without
+    depending on `weft_agent.loop` itself.
+    """
+
+    transcript: AgentTranscript
+    final_answer: str | None
+    stopped_because: StopReason
+
+
+class AgentCommand:
+    """`weft agent` — one ReAct run toward a goal, its tools drawn from the run's own
+    published command surface. See this module's own docstring for the seam it needed opened.
+    """
+
+    args_model: ClassVar[type[BaseModel]] = AgentArgs
+    result_model: ClassVar[type[CommandResult]] = AgentCommandResult
+    permission_class: ClassVar[PermissionClass] = PermissionClass.WRITE
+    help: ClassVar[str] = _AGENT_HELP
+
+    def __init__(self, settings: Settings | None = None, config: object = None) -> None:
+        """`settings` bound at construction, `config` accepted and unused.
+
+        **Bound rather than constructed in `run`**, which is what `weft_qdrant` and `weft_openai`
+        already do through `functools.partial`. The first version built a fresh `Settings()` per
+        run, so `[packs.agent] max_steps = 3` validated, was accepted and was silently discarded —
+        a knob that reads as configurable and is not. `config` is the per-plugin argument every
+        factory receives and an agent has nothing per-stage to configure.
+        """
+        del config
+        # Imported here, not at module scope: `weft_agent/__init__.py` imports this module in
+        # order to register the command, so a module-scope import would be a cycle — the same
+        # reason the docstring above already gives for `Settings` not appearing in the imports.
+        from weft_agent import Settings  # noqa: PLC0415
+
+        self._settings = settings if settings is not None else Settings()
+
+    @property
+    def max_steps(self) -> int:
+        """The configured step budget this command will run under."""
+        return self._settings.max_steps
+
+    async def run(self, args: BaseModel, ctx: Context) -> Outcome[CommandResult]:
+        # Local import: `weft_agent/__init__.py` imports `AgentCommand` from this module to
+        # register it, so a module-scope `from weft_agent import Settings` here would be a
+        # circular import at the moment `weft_agent` itself is still being defined — see this
+        # module's own docstring.
+
+        agent_args = cast(AgentArgs, args)
+        registry = ctx.require(Registry)
+        llm = ctx.require(LLM)
+        tools = command_tools(registry)
+
+        outcome = await run_agent(
+            goal=agent_args.goal,
+            # `CommandTool` satisfies `AgentTool` structurally at runtime (it carries
+            # `description` and an async `call`) but not statically: `AgentTool.description`
+            # is declared `ClassVar[str]`, while `CommandTool` sets it as an instance
+            # attribute in `__init__`. `weft_agent.loop`'s own `NextActionPrompt`/`Prompt`
+            # pairing is the identical, already-established shape for "a static check cannot
+            # see a structural conformance that holds at runtime" — this is that same cast,
+            # not a new pattern.
+            tools=cast("Mapping[str, AgentTool]", tools),
+            llm=llm,
+            ctx=ctx,
+            max_steps=self.max_steps,
+        )
+
+        return Produced(
+            value=AgentCommandResult(
+                transcript=outcome.transcript,
+                final_answer=outcome.final_answer,
+                stopped_because=outcome.stopped_because,
+            )
+        )
+
+
+__all__ = ["AgentArgs", "AgentCommand", "AgentCommandResult"]

weft_agent/command_tools.py

@@ -0,0 +1,164 @@
+"""The agent reaches Weft only through the published command surface — ledger task **7.3**.
+
+`docs/03-cli.md` → *Two modes, one implementation*, and `docs/05-grilling-sessions.md` → G12.
+See `tests/unit/weft_agent/test_command_tools.py`'s own module docstring for the three properties
+this module makes true; restated here only as pointers to where each lives:
+
+*(a)* `CommandTool.call` reaches a `Command` only through `weft_command.invocation.invoke` — never
+`instance.run(...)` directly — so the permission gate task 7.0 moved onto that seam applies to the
+agent exactly as it applies to `weft_cli`. `tests/unit/weft_agent/test_command_tools.py::
+test_the_tool_runs_a_command_only_through_the_seam` asserts this over the module's own source.
+
+*(b)* The observation returned to the model is built from the typed `Outcome[CommandResult]`
+`invoke` returns, never from `weft_command.render.Rendered` — this module imports nothing from
+`weft_cli` at all, per `weft_agent`'s own pack-boundary rule (task 7.1).
+
+*(c)* `RefusingConsent` is this pack's answer to `weft_command.invocation.Consent` — G12's
+settled ceiling ("nothing but a TTY counts as consent") expressed as code: every
+`overwrite`/`destroy`-class command is refused, and the refusal is returned as an observation so
+the model can read it and choose otherwise, never raised out of the loop.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from typing import Final, cast
+
+from pydantic import BaseModel
+
+from weft_agent.tools import tool_catalogue
+from weft_command.catalogue import help_of
+from weft_command.contract import Command, CommandResult
+from weft_command.invocation import invoke
+from weft_command.permission import PermissionClass
+from weft_kernel.context import Context
+from weft_kernel.errors import WeftError
+from weft_kernel.payload import NothingToProduce, Outcome, Produced
+from weft_kernel.registry import Registry, unwrap_factory
+
+#: G12's ceiling, read the other way round from `weft_agent.tools.REACHABLE_CLASSES`: these are
+#: the two classes nothing but a TTY may answer for, enumerated explicitly (rather than as
+#: "everything but read/write/network") so a sixth `PermissionClass` member is permitted by
+#: default and a reviewer has to notice it was never added here — the population this module
+#: actually decides over, per `docs/lessons.md` `L6.4`.
+_REFUSED_CLASSES: Final[frozenset[PermissionClass]] = frozenset(
+    {PermissionClass.OVERWRITE, PermissionClass.DESTROY}
+)
+
+
+class ConsentRefusedError(WeftError):
+    """A `PermissionClass.OVERWRITE`/`DESTROY` command, refused because nothing here is a TTY.
+
+    Raised by `RefusingConsent.decide` and caught by `CommandTool.call`, never allowed to escape
+    the loop — see this module's own docstring, property *(c)*.
+    """
+
+
+class RefusingConsent:
+    """`weft_command.invocation.Consent`, answered the way G12 settled it for an agent.
+
+    `permission_class` is read off `instance` with `getattr`, defensively — the identical
+    discipline `weft_cli.confirm.gate` uses for the same attribute, and for the same reason:
+    `permission_class` is a `Command.required_declarations` name, never a required `isinstance`
+    member, so nothing guarantees a stranger's `Command` carries it beyond registration having
+    already refused it if it did not.
+    """
+
+    async def decide(self, *, command_name: str, instance: object, args: BaseModel) -> None:
+        del args
+        permission_class = getattr(instance, "permission_class", None)
+        if permission_class in _REFUSED_CLASSES:
+            refused = cast(PermissionClass, permission_class)
+            raise ConsentRefusedError(
+                f"'{command_name}' is a {refused.value}-class command. Consent cannot be given "
+                "without a TTY, and nothing in this run is one, so it is refused."
+            )
+
+
+def _observation_of(outcome: Outcome[CommandResult]) -> str:
+    """The typed `Outcome` a `Command` produced, turned into the string an `AgentTool` returns.
+
+    Never built from `Rendered` — see this module's own docstring, property *(b)*. A `Produced`
+    serialises its own value's fields; `NothingToProduce`/`Failed` carry only a `reason`, which is
+    exactly what an agent needs to decide what to try next.
+    """
+    if isinstance(outcome, Produced):
+        return json.dumps(outcome.value.model_dump(mode="json"))
+    if isinstance(outcome, NothingToProduce):
+        return f"nothing to produce: {outcome.reason}"
+    # `Failed` by elimination, and **the type checker is what says so** — `pyright` narrows
+    # `Outcome` to it here and rejects a further `isinstance` as unnecessary. The first draft of
+    # this function asserted the same fact instead; an `assert` is stripped under `-O` and would
+    # have left the loop a bare `None` where it expects a string, while proving nothing a build
+    # was not already proving. If `weft-kernel` ever grows a fourth `Outcome` member, this line
+    # fails the gate rather than silently mis-reading one.
+    return f"command failed: {outcome.reason}"
+
+
+class CommandTool:
+    """One registered `Command`, offered to the agent's loop as an `AgentTool`.
+
+    Constructed directly against a `Registry` and a registered name, deliberately independent of
+    `weft_agent.tools.tool_catalogue`'s own filtering — `command_tools` below is what wires the
+    two together for the ordinary case, but a `CommandTool` built for a `destroy`-class command
+    the catalogue would never offer must still refuse it correctly, which is exactly what
+    `tests/unit/weft_agent/test_command_tools.py::
+    test_a_destroy_class_command_is_refused_even_if_a_tool_exists_for_it` builds to prove the two
+    halves — catalogue and consent — fail independently.
+    """
+
+    def __init__(self, *, registry: Registry, command_name: str) -> None:
+        self._registry = registry
+        self._command_name = command_name
+        entry = registry.entry(Command, command_name)
+        factory = unwrap_factory(entry.factory)
+        self.description = help_of(factory, command_name)
+
+    async def call(self, arguments: Mapping[str, object], ctx: Context) -> str:
+        """Build this command's `args_model` from `arguments`, then run it through `invoke`.
+
+        Never calls `instance.run(...)` — see this module's own docstring, property *(a)*, and
+        `test_the_tool_runs_a_command_only_through_the_seam`, which asserts this over the
+        module's source rather than over one call at runtime. `ConsentRefusedError` and any
+        other `WeftError` the command itself raises are caught here and returned as the
+        observation, per this pack's own reliability decision (`weft_agent.loop`'s own
+        docstring): a tool returns a string, and the model reads the refusal on its next turn
+        rather than the run ending underneath it. `CancelledError` is not caught and propagates
+        untouched.
+        """
+        entry = self._registry.entry(Command, self._command_name)
+        instance = cast(Command, entry.factory(None))
+        args_instance = instance.args_model(**dict(arguments))
+
+        try:
+            outcome = await invoke(
+                command_name=self._command_name,
+                instance=instance,
+                args=args_instance,
+                ctx=ctx,
+                consent=RefusingConsent(),
+                distribution=entry.distribution,
+            )
+        except ConsentRefusedError as error:
+            return str(error)
+        except WeftError as error:
+            return str(error)
+
+        return _observation_of(outcome)
+
+
+def command_tools(registry: Registry) -> Mapping[str, CommandTool]:
+    """One `CommandTool` per entry `weft_agent.tools.tool_catalogue` offers, keyed identically.
+
+    The catalogue already applied G12's ceiling (`REACHABLE_CLASSES`) and `EXCLUDED_BY_NAME`; this
+    only wraps each surviving name in the tool the loop can actually call. `RefusingConsent` is
+    the belt to the catalogue's braces — see this module's own docstring, property *(c)*, and
+    `CommandTool`'s own docstring for why the two are tested independently.
+    """
+    return {
+        name: CommandTool(registry=registry, command_name=name) for name in tool_catalogue(registry)
+    }
+
+
+__all__ = ["CommandTool", "ConsentRefusedError", "RefusingConsent", "command_tools"]

weft_agent/loop.py

@@ -0,0 +1,214 @@
+"""The agent's ReAct loop — task **7.2**. See this package's own `__init__.py` and
+`docs/01-high-level-plan.md` -> Phase 7 for why the loop takes the shape it does; the reasoning
+lives there and in `tests/unit/weft_agent/test_loop.py`'s own module docstring, not here twice.
+
+**One step is: render the request, ask `weft_prompts.cascade.execute`, act on what came back.**
+`NextActionRequest.tools` and `.transcript` arrive pre-rendered per that payload's own
+docstring — turning the tool catalogue and the transcript into text is this module's job, since
+`string.Template` cannot iterate a tuple.
+
+**A tool name the model invented is refused as an observation, not an exception.** The model is
+an untrusted source of names here exactly as a pipeline document is (requirement 5), but unlike a
+document, the reader of the refusal is the model itself on its next turn — a wrong guess is
+something an agent should be able to recover from, so the refusal is fed back rather than ending
+the run.
+
+**A cascade call that does not produce ends the loop with what was recorded so far, and says
+`NO_DECISION`.** This branch is the one place task 7.2's own brief had decided nothing: it forbade
+adding a `StopReason` member *and* forbade reusing `BUDGET_EXHAUSTED` for anything but the budget,
+which are two constraints with no true value between them. The first pass reused
+`BUDGET_EXHAUSTED`, documented the reuse and reported the contradiction rather than resolving it
+quietly — which is the right handling of a brief that has decided nothing, and is why it was caught.
+
+It is settled against the **operator** rather than against the code. `stopped_because` is a field
+somebody reads to decide what to do next; `BUDGET_EXHAUSTED` on a run that stopped after one step
+of ten tells them to raise the budget, and raising it would change nothing, because the model never
+returned a usable decision. The remedy for this branch is the model or the prompt. Two causes
+wearing one name is not wrong anywhere and ambiguous everywhere.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from enum import StrEnum
+from typing import Protocol, cast, runtime_checkable
+
+from pydantic import BaseModel, ConfigDict
+
+from weft_agent.payload import AgentStep, AgentTranscript, NextAction, NextActionRequest
+from weft_agent.prompts import NextActionPrompt
+from weft_kernel.context import Context
+from weft_kernel.errors import WeftError
+from weft_kernel.payload import Produced
+from weft_llm.contract import LLM
+from weft_prompts.cascade import execute
+from weft_prompts.contract import Prompt
+
+
+@runtime_checkable
+class AgentTool(Protocol):
+    """One tool the loop may offer a model: a name to call it under, a description to pick it
+    by, and the call itself.
+
+    The name a tool is offered under is the key the caller's `tools` mapping supplies, never a
+    member on the tool — a tool run under two names (a catalogue's alias, say) needs no second
+    implementation.
+    """
+
+    #: Not a `ClassVar`. A tool whose description is *derived* — every `CommandTool`'s is, being
+    #: the command's own mandatory `help` — sets this per instance, and declaring it a `ClassVar`
+    #: here would make that a type error while working perfectly at runtime. The Protocol states
+    #: what a tool must *have*, never how the implementer must spell it.
+    description: str
+
+    async def call(self, arguments: Mapping[str, object], ctx: Context) -> str: ...
+
+
+class UndecidedActionError(WeftError):
+    """A `NextAction` carrying neither a call nor a final answer reached the loop.
+
+    Unreachable through `NextAction`'s own validator, and named rather than asserted so that it
+    stays a refusal in an optimised build — see the raise site.
+    """
+
+
+class StopReason(StrEnum):
+    """Why `run_agent` returned — a field somebody reads to decide what to do next.
+
+    **Three members, and the third was added rather than folded into the second on purpose.**
+    Task 7.2's brief forbade adding a member *and* forbade reusing `BUDGET_EXHAUSTED` for
+    anything but the budget, which left no value that is true; the implementer reused it,
+    documented the reuse and reported the contradiction rather than choosing quietly. Settled
+    against the operator: `BUDGET_EXHAUSTED` on a run that stopped after one step of ten tells
+    them to raise the budget, and raising it would change nothing, because the model never
+    returned a usable decision. Two causes wearing one name is not wrong anywhere and ambiguous
+    everywhere.
+    """
+
+    #: The model gave a final answer. The only member that comes with one.
+    ANSWERED = "answered"
+    #: Every one of `max_steps` steps was taken and none of them answered.
+    BUDGET_EXHAUSTED = "budget_exhausted"
+    #: The cascade could not turn what the model said into a `NextAction` at any tier — so the
+    #: run stopped with steps left, and the remedy is the model or the prompt, never the budget.
+    NO_DECISION = "no_decision"
+
+
+class AgentOutcome(BaseModel):
+    """What a run produced: the full transcript, the final answer if there is one, and why the
+    loop stopped."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    transcript: AgentTranscript
+    final_answer: str | None
+    stopped_because: StopReason
+
+
+def _render_tools(tools: Mapping[str, AgentTool]) -> str:
+    """The tool catalogue as the numbered list `next-action`'s prompt text asks for."""
+    if not tools:
+        return "(no tools are available; you must answer directly)"
+    return "\n".join(f"- {name}: {tool.description}" for name, tool in tools.items())
+
+
+def _render_transcript(transcript: AgentTranscript) -> str:
+    """Every step recorded so far, as text a model reads back on its next turn."""
+    if not transcript.steps:
+        return "(nothing yet — this is the first step)"
+    lines: list[str] = []
+    for index, step in enumerate(transcript.steps, start=1):
+        action = step.action
+        lines.append(f"{index}. reasoning: {action.reasoning}")
+        if action.call is not None:
+            lines.append(f"   called '{action.call.tool}' with {dict(action.call.arguments)!r}")
+            lines.append(f"   observed: {step.observation}")
+        else:
+            lines.append(f"   answered: {action.final_answer}")
+    return "\n".join(lines)
+
+
+def _refuse_unknown_tool(requested: str, tools: Mapping[str, AgentTool]) -> str:
+    """Requirement 5, phrased for the model rather than for a log: what was asked for, and
+    what is actually on offer."""
+    available = ", ".join(sorted(tools)) if tools else "(none)"
+    return (
+        f"tool '{requested}' is not available. Available tools: {available}. "
+        "Choose one of the available tools, or answer if you already have enough."
+    )
+
+
+async def run_agent(
+    *,
+    goal: str,
+    tools: Mapping[str, AgentTool],
+    llm: LLM,
+    ctx: Context,
+    max_steps: int,
+) -> AgentOutcome:
+    """Run one ReAct loop toward `goal`, for at most `max_steps` steps.
+
+    Never raises for budget exhaustion or for a cascade that could not produce a decision — both
+    are typed results, per this pack's own reliability decision. `CancelledError` is not caught
+    anywhere here and propagates untouched, the same as everywhere else in this tree.
+    """
+    transcript = AgentTranscript(goal=goal)
+    rendered_tools = _render_tools(tools)
+
+    for _ in range(max_steps):
+        request = NextActionRequest(
+            goal=goal, tools=rendered_tools, transcript=_render_transcript(transcript)
+        )
+        outcome = await execute(
+            llm=llm,
+            # `NextActionPrompt` satisfies `Prompt` structurally at runtime — `version` is
+            # assigned dynamically the same way every registered prompt's is, per
+            # `weft_prompts.contract.Prompt`'s own docstring — but is invisible to a static
+            # check on a concrete class. `weft_prompts.registry.PromptRegistry.render` casts
+            # for the identical reason; there is no tool catalogue to resolve this through yet.
+            prompt=cast(Prompt, NextActionPrompt()),
+            values=request,
+            output=NextAction,
+            role="agent",
+            ctx=ctx,
+        )
+        if not isinstance(outcome, Produced):
+            # The model said something the cascade could not read as a decision at any of its
+            # three tiers. The run stops with budget left, and says so — see `StopReason`.
+            return AgentOutcome(
+                transcript=transcript,
+                final_answer=None,
+                stopped_because=StopReason.NO_DECISION,
+            )
+        action = outcome.value.value
+
+        if action.final_answer is not None:
+            transcript = transcript.with_step(AgentStep(action=action))
+            return AgentOutcome(
+                transcript=transcript,
+                final_answer=action.final_answer,
+                stopped_because=StopReason.ANSWERED,
+            )
+
+        # `NextAction`'s own validator guarantees exactly one of `call`/`final_answer` is set, and
+        # `final_answer` was ruled out above — so this is unreachable. It is a **named refusal
+        # rather than an `assert`**: an assert is stripped under `-O`, which would leave the line
+        # below dereferencing `None` in exactly the build where nobody is watching
+        # (`docs/lessons.md` `L8.37`).
+        call = action.call
+        if call is None:  # pragma: no cover - the validator makes this unreachable
+            raise UndecidedActionError(
+                f"a NextAction reached the loop with neither a call nor a final answer, which "
+                f"NextAction's own validator forbids: {action!r}"
+            )
+
+        tool = tools.get(call.tool)
+        if tool is None:
+            observation = _refuse_unknown_tool(call.tool, tools)
+        else:
+            observation = await tool.call(call.arguments, ctx)
+        transcript = transcript.with_step(AgentStep(action=action, observation=observation))
+
+    return AgentOutcome(
+        transcript=transcript, final_answer=None, stopped_because=StopReason.BUDGET_EXHAUSTED
+    )