From a045003dd2be109ca78868b3e2548cc307789e18 Mon Sep 17 00:00:00 2001 From: Andrey Shiryaev <7615137+shoom1@users.noreply.github.com> Date: Tue, 17 Nov 2026 17:29:24 -0500 Subject: [PATCH 01/15] Sub-agents: a run's control RunControl holds one sub-agent run's limits, cancels the run's own task alone (the first cancel winning, none once it has ended) and tells the hook whether a cancel is the run's own, runs its time limit while a block does, counts its model calls (the last allowed one said so) and its tokens (past max_tokens the answer in progress is its last), and keeps the messages steered to it until its next model call. Nothing uses it yet. --- src/agentic_cli/workflow/agents/control.py | 203 ++++++++++++++++ tests/workflow/test_agent_control.py | 265 +++++++++++++++++++++ 2 files changed, 468 insertions(+) create mode 100644 src/agentic_cli/workflow/agents/control.py create mode 100644 tests/workflow/test_agent_control.py diff --git a/src/agentic_cli/workflow/agents/control.py b/src/agentic_cli/workflow/agents/control.py new file mode 100644 index 00000000..c607ad47 --- /dev/null +++ b/src/agentic_cli/workflow/agents/control.py @@ -0,0 +1,203 @@ +"""One sub-agent run's control: its limits, a cancel of the run alone, and steering. + +``Delegations`` (``agents/delegate.py``) makes a ``RunControl`` for each run +it starts, with the run's limits (its type's over the policy's), binds it to +the run's own task, and hands it to the backend's hook as +``AgentRun.control``; ``Delegations.control(run)`` finds a working run's. + +- ``cancel(by=, error=)`` cancels the run's task: its parent's stop, the + user's, or a limit's. The first cancel wins, and a run that has ended is + not cancelled. The hook, handling the ``CancelledError`` in the run's + task, asks ``own_cancel`` whether it is the run's own: then it stops the + run as a stopped turn's run stops and returns what it has, and the run + ends ``cancelled``; any other cancel (the turn's: Ctrl+C) goes on. +- The time limit (``timeout``) runs while the hook does (``timing``); past + it the run is cancelled by its limit. +- The limits checked at the run's model calls: before each, ``model_call`` + counts it and says whether it is the last allowed (``max_model_calls``), + whose request ends with ``STEP_LIMIT_NOTE``; after each, ``used`` counts + its tokens, and past ``max_tokens`` the run is cancelled by its limit at + that answer. On the call that is the run's last (``final_call``) the + backend drops the answer's tool calls, so the run ends with that answer: + no call past a limit is made, and nothing the model asked for runs after + it. +- ``steer(message)`` gives the run a message, which its next model call + (``take_steering``) adds after its last message, as a user's. + +All of it runs on the event loop; nothing here blocks. +""" + +from __future__ import annotations + +import asyncio +from collections.abc import Iterator +from contextlib import contextmanager +from typing import TYPE_CHECKING, Any + +from agentic_cli.workflow.agents.envelope import ( + CANCELLED_BY, + TIME_LIMIT_ERROR, + TOKEN_LIMIT_ERROR, +) + +if TYPE_CHECKING: + from agentic_cli.workflow.agents.policy import AgentLimits + from agentic_cli.workflow.sessions import RunRef + +#: What the run's last allowed model call is told, after its last message. +STEP_LIMIT_NOTE = ( + "You have reached the most model calls this task may make. Answer now with your best " + "result from what you have; no tools are available for this answer." +) +#: Who cancels a run at one of its limits. +LIMIT = "limit" + + +class RunControl: + """One sub-agent run's control (see the module docstring). + + Args: + ref: The run. + limits: Its limits: its type's over the policy's. + + Attributes: + ref: The run. + limits: Its limits. + cancelled: ``(by, error)`` once it is cancelled: who cancelled it + (``parent``, ``user`` or ``limit``) and why, one line. + """ + + def __init__(self, ref: RunRef, limits: AgentLimits) -> None: + self.ref = ref + self.limits = limits + self.cancelled: tuple[str, str] | None = None + self._steering: list[str] = [] + self._calls = 0 + self._tokens = 0 + self._final = False + self._task: asyncio.Task[Any] | None = None + # Whether cancel() cancelled the task, and own_cancel() has not yet + # taken that cancel. + self._cancelled_task = False + + # -- the run's task -------------------------------------------------------- + + def bind(self, task: asyncio.Task[Any]) -> None: + """Make ``task`` the run's: what ``cancel`` cancels. + + A cancel that came before (the run had no task yet) cancels it now. + """ + self._task = task + if self.cancelled is not None and not task.done(): + self._cancel_task() + + def cancel(self, *, by: str, error: str) -> None: + """Cancel the run's task: ``by`` its parent, the user or a limit, for ``error``. + + Does nothing once the run is cancelled (the first cancel wins) or + its task has ended. + + Raises: + ValueError: ``by`` is not ``parent``, ``user`` or ``limit``. + """ + if by not in CANCELLED_BY: + raise ValueError(f"A run is cancelled by its parent, user or limit, not {by!r}.") + if self.cancelled is not None or (self._task is not None and self._task.done()): + return + self.cancelled = (by, error) + if self._task is not None: + self._cancel_task() + + def own_cancel(self) -> bool: + """In the run's task, handling a ``CancelledError``: whether it is the run's own cancel. + + True for the cancel ``cancel`` made (asked once): the task's cancel + request is withdrawn (``uncancel``), so the hook may stop the run + and return what it has. False for any other cancel (the turn's): + the hook lets it go on. + """ + if not self._cancelled_task: + return False + self._cancelled_task = False + task = asyncio.current_task() + if task is not None and task is self._task: + task.uncancel() + return True + + @contextmanager + def timing(self) -> Iterator[None]: + """Run the block under the run's time limit: past it, the run is cancelled by its limit. + + The clock starts with the block, as the run starts to work, and + stops with it. + """ + timeout = self.limits.timeout + if timeout is None: + yield + return + handle = asyncio.get_running_loop().call_later(timeout, self._out_of_time) + try: + yield + finally: + handle.cancel() + + def _out_of_time(self) -> None: + self.cancel(by=LIMIT, error=TIME_LIMIT_ERROR) + + def _cancel_task(self) -> None: + assert self._task is not None + self._cancelled_task = True + self._task.cancel() + + # -- the limits at its model calls ------------------------------------------- + + def model_call(self) -> bool: + """Count a model call the run is about to make; True when it is the last allowed. + + That call's request ends with ``STEP_LIMIT_NOTE``, and its answer is + the run's last (``final_call``). + """ + self._calls += 1 + self._final = self.at_step_limit + return self._final + + def used(self, input_tokens: int, output_tokens: int) -> None: + """Count what one of the run's model calls used, as ``workflow/usage.py`` counts it. + + Past ``max_tokens`` the run is cancelled by its limit at this answer: + ``cancelled`` is set and the answer is the run's last + (``final_call``), so it ends with it rather than losing it. + """ + self._tokens += input_tokens + output_tokens + limit = self.limits.max_tokens + if limit is not None and self._tokens > limit and self.cancelled is None: + self.cancelled = (LIMIT, TOKEN_LIMIT_ERROR) + self._final = True + + @property + def at_step_limit(self) -> bool: + """Whether the run has made its last allowed model call.""" + limit = self.limits.max_model_calls + return limit is not None and self._calls >= limit + + @property + def final_call(self) -> bool: + """Whether the model call in progress is the run's last: its answer's tool calls are dropped.""" + return self._final + + # -- steering -------------------------------------------------------------- + + def steer(self, message: str) -> None: + """Give the run ``message``, for its next model call. + + Raises: + ValueError: ``message`` is not text, or blank. + """ + if not isinstance(message, str) or not message.strip(): + raise ValueError("A message steered to a run is text.") + self._steering.append(message) + + def take_steering(self) -> list[str]: + """The messages given since the run's last model call, oldest first; given once.""" + taken, self._steering = self._steering, [] + return taken diff --git a/tests/workflow/test_agent_control.py b/tests/workflow/test_agent_control.py new file mode 100644 index 00000000..411b6c95 --- /dev/null +++ b/tests/workflow/test_agent_control.py @@ -0,0 +1,265 @@ +"""One sub-agent run's control (``workflow/agents/control.py``), alone. + +A ``RunControl`` holds a run's limits, cancels the run's own task (its +parent's stop, the user's, a limit's), counts the run's model calls and +tokens against its limits, and keeps the messages steered to it until its +next model call. Driven here with a plain asyncio task for the run. +""" + +from __future__ import annotations + +import asyncio + +import pytest + +from agentic_cli.workflow.agents.control import STEP_LIMIT_NOTE, RunControl +from agentic_cli.workflow.agents.envelope import TIME_LIMIT_ERROR, TOKEN_LIMIT_ERROR +from agentic_cli.workflow.agents.policy import AgentLimits +from agentic_cli.workflow.sessions import RunRef + +REF = RunRef( + agent="researcher", instance="researcher-1", run="researcher-1#1", parent_run=None, depth=1 +) + + +def control(**limits) -> RunControl: + return RunControl(REF, AgentLimits(**limits)) + + +async def a_run(made: RunControl) -> tuple[asyncio.Task, asyncio.Event]: + """A run's task bound to ``made``, waiting until cancelled; the event set once it waits.""" + waiting = asyncio.Event() + + async def run() -> str: + waiting.set() + await asyncio.Event().wait() + return "never" # pragma: no cover + + task = asyncio.create_task(run()) + made.bind(task) + await waiting.wait() + return task, waiting + + +def test_the_step_limit_note(): + assert STEP_LIMIT_NOTE == ( + "You have reached the most model calls this task may make. Answer now with your best " + "result from what you have; no tools are available for this answer." + ) + + +def test_it_holds_its_run_and_limits(): + made = control(max_model_calls=3, timeout=2.5) + assert (made.ref, made.limits, made.cancelled) == ( + REF, AgentLimits(max_model_calls=3, timeout=2.5), None, + ) + + +class TestCancel: + async def test_cancels_the_runs_task_and_says_who_and_why(self): + made = control() + task, _ = await a_run(made) + + made.cancel(by="parent", error="no longer needed") + + with pytest.raises(asyncio.CancelledError): + await task + assert made.cancelled == ("parent", "no longer needed") + + async def test_the_first_cancel_wins(self): + made = control() + task, _ = await a_run(made) + + made.cancel(by="limit", error=TIME_LIMIT_ERROR) + made.cancel(by="parent", error="no longer needed") + + with pytest.raises(asyncio.CancelledError): + await task + assert made.cancelled == ("limit", TIME_LIMIT_ERROR) + + async def test_a_run_that_has_ended_is_not_cancelled(self): + made = control() + + async def run() -> str: + return "done" + + task = asyncio.create_task(run()) + made.bind(task) + assert await task == "done" + + made.cancel(by="parent", error="too late") + + assert made.cancelled is None + + async def test_a_cancel_before_the_task_is_bound_cancels_it_then(self): + made = control() + made.cancel(by="user", error="stopped") + task = asyncio.create_task(asyncio.Event().wait()) + + made.bind(task) + + with pytest.raises(asyncio.CancelledError): + await task + assert made.cancelled == ("user", "stopped") + + def test_who_cancels_is_the_parent_the_user_or_a_limit(self): + with pytest.raises(ValueError, match="parent, user or limit"): + control().cancel(by="someone", error="why") + + +class TestItsOwnCancel: + """The hook, handling a ``CancelledError`` in the run's task, asks + ``own_cancel`` whether it is the run's own (then it ends the run and + returns) or its turn's (then it raises).""" + + async def test_the_controls_cancel_is_the_runs_own_and_is_withdrawn(self): + made = control() + seen: dict = {} + + async def run() -> str: + try: + await asyncio.Event().wait() + except asyncio.CancelledError: + seen["own"] = made.own_cancel() + seen["cancelling"] = asyncio.current_task().cancelling() + await asyncio.sleep(0) # the run may still finish its work + return "what it had" + return "never" # pragma: no cover + + task = asyncio.create_task(run()) + made.bind(task) + await asyncio.sleep(0) + + made.cancel(by="parent", error="no longer needed") + + assert await task == "what it had" + assert seen == {"own": True, "cancelling": 0} + + async def test_another_cancel_is_not(self): + made = control() + seen: dict = {} + + async def run() -> None: + try: + await asyncio.Event().wait() + except asyncio.CancelledError: + seen["own"] = made.own_cancel() + raise + + task = asyncio.create_task(run()) + made.bind(task) + await asyncio.sleep(0) + + task.cancel() # the turn's cancel reaching the run's task + + with pytest.raises(asyncio.CancelledError): + await task + assert seen == {"own": False} + assert made.cancelled is None + + +class TestTheTimeLimit: + async def test_past_it_the_run_is_cancelled_by_its_limit(self): + made = control(timeout=0.05) + + async def run() -> None: + with made.timing(): + await asyncio.Event().wait() + + task = asyncio.create_task(run()) + made.bind(task) + + with pytest.raises(asyncio.CancelledError): + await asyncio.wait_for(task, 5) + assert made.cancelled == ("limit", TIME_LIMIT_ERROR) + + async def test_a_run_that_ends_in_time_is_not_cancelled_later(self): + made = control(timeout=0.05) + + async def run() -> str: + with made.timing(): + return "done" + + task = asyncio.create_task(run()) + made.bind(task) + assert await task == "done" + await asyncio.sleep(0.1) + + assert made.cancelled is None + + async def test_the_clock_starts_with_the_block(self): + made = control(timeout=0.2) + + async def run() -> str: + await asyncio.sleep(0.3) # waiting before it works: not counted + with made.timing(): + await asyncio.sleep(0.05) + return "done" + + task = asyncio.create_task(run()) + made.bind(task) + + assert await asyncio.wait_for(task, 5) == "done" + assert made.cancelled is None + + +class TestTheStepLimit: + def test_the_last_allowed_call_is_said_so(self): + made = control(max_model_calls=3) + + assert [made.model_call() for _ in range(3)] == [False, False, True] + assert (made.at_step_limit, made.final_call) == (True, True) + + def test_before_it_the_run_is_not_at_its_limit(self): + made = control(max_model_calls=3) + made.model_call() + + assert (made.at_step_limit, made.final_call) == (False, False) + + def test_without_a_limit_no_call_is_the_last(self): + made = control() + + assert [made.model_call() for _ in range(200)] == [False] * 200 + assert made.at_step_limit is False + + +class TestTheTokenLimit: + async def test_up_to_it_nothing_happens(self): + made = control(max_tokens=100) + made.used(60, 20) + made.used(15, 5) + + assert (made.cancelled, made.final_call) == (None, False) + + async def test_past_it_the_run_ends_at_that_answer_cancelled_by_its_limit(self): + made = control(max_tokens=100) + task, _ = await a_run(made) + + made.used(60, 20) + made.used(30, 10) + + # Not its task: the answer that went over is the run's last. + assert (made.cancelled, made.final_call) == (("limit", TOKEN_LIMIT_ERROR), True) + assert not task.cancelled() and not task.done() + task.cancel() + + def test_without_a_limit_any_number_is_fine(self): + made = control() + made.used(10**9, 10**9) + + assert made.cancelled is None + + +class TestSteering: + def test_messages_are_taken_oldest_first_once(self): + made = control() + made.steer("Also give Z.") + made.steer("In metric units.") + + assert made.take_steering() == ["Also give Z.", "In metric units."] + assert made.take_steering() == [] + + @pytest.mark.parametrize("message", ["", " ", None]) + def test_a_message_is_text(self, message): + with pytest.raises(ValueError, match="text"): + control().steer(message) From 50105586ced5c58430350b06a2e48fcaaf057102 Mon Sep 17 00:00:00 2001 From: Andrey Shiryaev <7615137+shoom1@users.noreply.github.com> Date: Tue, 17 Nov 2026 17:31:50 -0500 Subject: [PATCH 02/15] Sub-agents: each run under its control Delegations makes each run's RunControl with its type's limits over the policy's, binds it to the run's task, hands it to the hook and keeps it while the run works: control(run) finds it and cancel(run_id, by=, error=) stops the run alone. The hook runs under the run's time limit. A run its control stopped ends cancelled, with who stopped it and what the hook had; a run that made its last allowed model call completes partial (step limit reached); the turn's cancel still wins (interrupted). --- src/agentic_cli/workflow/agents/delegate.py | 181 ++++++++++++-- tests/workflow/test_agent_delegate.py | 262 +++++++++++++++++++- 2 files changed, 415 insertions(+), 28 deletions(-) diff --git a/src/agentic_cli/workflow/agents/delegate.py b/src/agentic_cli/workflow/agents/delegate.py index f4a67445..b1ce7668 100644 --- a/src/agentic_cli/workflow/agents/delegate.py +++ b/src/agentic_cli/workflow/agents/delegate.py @@ -23,6 +23,11 @@ or a failed run's one warning after it), and returns the result envelope (``envelope.envelope``) with the shared state the run changed. +Each run works under its ``RunControl`` (``agents/control.py``, +``AgentRun.control``): its limits (its type's over the policy's), the time +limit running while the hook does, and a cancel of the run alone +(``Delegations.cancel``), which its limits use too. + Each ``AGENT_RUN`` is recorded (``AgentRuns.observe``) as it is made and reported to the turn's live events, so it reaches the turn's stream while the run works. A run ends: @@ -34,11 +39,17 @@ context overflow, ``context.subagent_overflow_message``); - ``refused`` when a model refused its last answer (``agents/outcome.py``); - ``completed`` otherwise, ``partial`` for an answer cut at its output - limit, followed by the cut's one warning (``outcome.cut_off_warning``); + limit, followed by the cut's one warning (``outcome.cut_off_warning``), + and for a run that made its last allowed model call (its step limit: + ``error`` "step limit reached", no warning); +- ``cancelled`` when its control cancelled it (``cancelled_by`` its parent, + the user or a limit: the time limit, the token limit), with what the hook + had of its work, ``partial`` when that is any text; - ``interrupted`` when its caller's task is cancelled (Ctrl+C stops the - turn): the cancel goes on once the run has stopped. A run's own task - cancelled while its caller goes on ends ``interrupted`` too, and its - caller reads that envelope. + turn): the cancel goes on once the run has stopped, whatever else + stopped it. A run's own task cancelled by anything but its control while + its caller goes on ends ``interrupted`` too, and its caller reads that + envelope. """ from __future__ import annotations @@ -52,9 +63,17 @@ from agentic_cli.logging import Loggers from agentic_cli.workflow import live_events from agentic_cli.workflow.agents.brief import BriefError, read_brief, task_message -from agentic_cli.workflow.agents.envelope import INTERRUPTED_ERROR, envelope +from agentic_cli.workflow.agents.control import RunControl +from agentic_cli.workflow.agents.envelope import ( + CANCELLED_BY, + INTERRUPTED_ERROR, + STEP_LIMIT_ERROR, + envelope, +) from agentic_cli.workflow.agents.outcome import CUT, REFUSAL_ERROR, REFUSED, cut_off_warning +from agentic_cli.workflow.agents.policy import AgentLimits from agentic_cli.workflow.agents.runs import ( + RUN_CANCELLED, RUN_COMPLETED, RUN_FAILED, RUN_INTERRUPTED, @@ -132,6 +151,9 @@ class AgentRun: state: The shared state it starts from. history: An inheriting run's parent conversation, as the backend reads it; None for a fresh one. + control: Its control (``agents/control.py``): its limits, a cancel + of the run alone, the messages steered to it. A run made + without one gets one with no limits. """ ref: RunRef @@ -140,6 +162,11 @@ class AgentRun: conversation: SessionRef | None state: Mapping[str, Any] history: Any = None + control: RunControl = None # type: ignore[assignment] # filled below when None + + def __post_init__(self) -> None: + if self.control is None: + object.__setattr__(self, "control", RunControl(self.ref, AgentLimits())) @dataclass(frozen=True) @@ -238,6 +265,8 @@ def __init__( # wait at while one reads them. self._numbered: dict[SessionRef, object] = {} self._numbering = asyncio.Lock() + # The working runs' controls, by (conversation, run id). + self._controls: dict[tuple[SessionRef | None, str], RunControl] = {} def sub_agents(self, agent: str) -> dict[str, AgentConfig]: """The types ``agent`` may start, by name, in its ``sub_agents``' order.""" @@ -263,45 +292,112 @@ async def delegate(self, request: DelegationRequest) -> Delegated: ref, RUN_STARTED, call_id=request.call_id, title=run_title(brief.title), brief=brief.fields(), started_by=started_by(request.caller), mode=BLOCKING, )) + control = RunControl(ref, self._limits(config)) inner = asyncio.create_task( - self._in_run(ref, config, brief, conversation, request), name=f"agent run {ref.run}" + self._in_run(ref, config, brief, conversation, request, control), + name=f"agent run {ref.run}", ) + control.bind(inner) + key = (conversation, ref.run or "") + self._controls[key] = control + try: + return await self._ended(ref, request.call_id, inner, control) + finally: + self._controls.pop(key, None) + + def control(self, run: RunRef | None) -> RunControl | None: + """The control of ``run`` while it works, in the active turn's conversation; else None. + + None for the root's own work (no run), and for a run that has ended. + """ + if run is None or run.run is None: + return None + return self._controls.get((get_active_turn(), run.run)) + + def cancel(self, run_id: str, *, by: str, error: str) -> bool: + """Cancel the working run ``run_id`` of the active turn's conversation, alone. + + ``by`` its parent, the user or a limit; ``error`` says why, as its + envelope will. Its siblings and its turn go on; its parent reads its + envelope (``cancelled``, with what it had of its work). + + Returns: + True when this cancelled it; False for no such working run, or + one cancelled already. + + Raises: + ValueError: ``by`` is not ``parent``, ``user`` or ``limit``. + """ + if by not in CANCELLED_BY: + raise ValueError(f"A run is cancelled by its parent, user or limit, not {by!r}.") + control = self._controls.get((get_active_turn(), run_id)) + if control is None or control.cancelled is not None: + return False + control.cancel(by=by, error=error) + return control.cancelled is not None + + def _limits(self, config: AgentConfig) -> AgentLimits: + """A run of ``config``'s limits: the type's own over the policy's.""" + if config.limits is None: + return self.policy.limits + return config.limits.over(self.policy.limits) + + async def _ended( + self, ref: RunRef, call_id: str, inner: asyncio.Task[RunAnswer], control: RunControl + ) -> Delegated: + """Wait for the run's task ``inner``, then end the run as it went; its envelope.""" try: answer = await inner except asyncio.CancelledError: - self._end(ref, request.call_id, RUN_INTERRUPTED, error=INTERRUPTED_ERROR) - task = asyncio.current_task() - if task is not None and task.cancelling(): + if not _caller_cancelling() and control.cancelled is not None: + # Its control cancelled it and the hook let the cancel out: + # nothing of its work came back. + return self._cancelled(ref, call_id, control.cancelled, RunAnswer()) + self._end(ref, call_id, RUN_INTERRUPTED, error=INTERRUPTED_ERROR) + if _caller_cancelling(): raise - # The run's own task was stopped, not its caller's: the caller - # reads that it ended. + # The run's own task was stopped, not by its control nor its + # caller's: the caller reads that it ended. return Delegated( result=envelope(ref, RUN_INTERRUPTED, error=INTERRUPTED_ERROR), state={}, run=ref ) except RunFailed as error: - return self._failed(ref, request.call_id, str(error), warning=str(error), code=error.code) + return self._failed(ref, call_id, str(error), warning=str(error), code=error.code) except Exception as error: # noqa: BLE001 - a sub-agent's failure is its parent's to read reason = str(error) or type(error).__name__ logger.debug("subagent_failed", run=ref.run, exc_info=error) return self._failed( - ref, request.call_id, reason, + ref, call_id, reason, warning=f"{ref.instance} failed: {reason}", code=type(error).__name__, ) + if _caller_cancelling(): + # The turn was stopped while the run's own cancel ended it (its + # hook took that cancel and answered): the run is the turn's. + self._end(ref, call_id, RUN_INTERRUPTED, error=INTERRUPTED_ERROR) + raise asyncio.CancelledError + if control.cancelled is not None: + return self._cancelled(ref, call_id, control.cancelled, answer) if answer.error is not None: return self._failed( - ref, request.call_id, answer.error, warning=f"{ref.instance} failed: {answer.error}", + ref, call_id, answer.error, warning=f"{ref.instance} failed: {answer.error}", code=None, text=answer.text, state=answer.state, ) if answer.outcome == REFUSED: - self._end(ref, request.call_id, RUN_REFUSED, text=answer.text, error=REFUSAL_ERROR) + self._end(ref, call_id, RUN_REFUSED, text=answer.text, error=REFUSAL_ERROR) result = envelope(ref, RUN_REFUSED, result=answer.text, error=REFUSAL_ERROR) else: - partial = answer.outcome == CUT - end = self._end(ref, request.call_id, RUN_COMPLETED, text=answer.text, partial=partial) - warning = cut_off_warning(end) - if warning is not None: - self._report(warning) - result = envelope(ref, RUN_COMPLETED, result=answer.text, partial=partial) + stepped = STEP_LIMIT_ERROR if control.at_step_limit else None + partial = answer.outcome == CUT or stepped is not None + end = self._end( + ref, call_id, RUN_COMPLETED, text=answer.text, partial=partial, error=stepped + ) + if answer.outcome == CUT: + warning = cut_off_warning(end) + if warning is not None: + self._report(warning) + result = envelope( + ref, RUN_COMPLETED, result=answer.text, partial=partial, error=stepped + ) return Delegated(result=result, state=dict(answer.state), run=ref) async def _number_past_stored(self, conversation: SessionRef | None) -> None: @@ -344,11 +440,13 @@ async def _in_run( brief: Any, conversation: SessionRef | None, request: DelegationRequest, + control: RunControl, ) -> RunAnswer: """The run, in its own task: the active run, and no tool call active. The task's context is a copy of its caller's, so what this sets stays - here. An inheriting type's history is read here, once. + here. An inheriting type's history is read here, once. The run's + time limit runs from when its hook starts (``RunControl.timing``). """ set_active_run(ref) set_active_tool_call(None) @@ -356,14 +454,40 @@ async def _in_run( request.history() if config.inherit_context and request.history is not None else None ) - return await self._hook(AgentRun( + run = AgentRun( ref=ref, config=config, message=task_message(brief, inherit=config.inherit_context), conversation=conversation, state=dict(request.state), history=history, - )) + control=control, + ) + with control.timing(): + return await self._hook(run) + + def _cancelled( + self, + ref: RunRef, + call_id: str, + cancelled: tuple[str, str], + answer: RunAnswer, + ) -> Delegated: + """End ``ref``'s run cancelled (``cancelled``: by whom, why) with what ``answer`` had.""" + by, error = cancelled + logger.info("subagent_cancelled", run=ref.run, agent=ref.agent, by=by, error=error) + partial = bool(answer.text) + self._end( + ref, call_id, RUN_CANCELLED, text=answer.text, error=error, partial=partial, + cancelled_by=by, + ) + return Delegated( + result=envelope( + ref, RUN_CANCELLED, result=answer.text, partial=partial, error=error, + cancelled_by=by, + ), + state=dict(answer.state), run=ref, + ) def _failed( self, @@ -398,11 +522,12 @@ def _end( text: str = "", error: str | None = None, partial: bool = False, + cancelled_by: str | None = None, ) -> WorkflowEvent: """Report and record the ``AGENT_RUN`` that ends ``ref``'s run; that event.""" end = WorkflowEvent.agent_run( ref, status, call_id=call_id, result=result_head(text), error=error, - partial=partial, usage=self._usage(ref), + partial=partial, usage=self._usage(ref), cancelled_by=cancelled_by, ) self._emit(end) return end @@ -422,3 +547,9 @@ def _emit(self, event: WorkflowEvent) -> None: def _report(event: WorkflowEvent) -> None: """Report ``event`` to the turn's live events (none outside a turn).""" live_events.report(event) + + +def _caller_cancelling() -> bool: + """Whether the task running ``delegate`` (the caller's: its turn's) is being cancelled.""" + task = asyncio.current_task() + return task is not None and task.cancelling() > 0 diff --git a/tests/workflow/test_agent_delegate.py b/tests/workflow/test_agent_delegate.py index bac2b2d6..dee417d3 100644 --- a/tests/workflow/test_agent_delegate.py +++ b/tests/workflow/test_agent_delegate.py @@ -18,11 +18,14 @@ from agentic_cli.workflow import live_events from agentic_cli.workflow.agents import ( + DEFAULT_LIMITS, + RUN_CANCELLED, RUN_COMPLETED, RUN_FAILED, RUN_INTERRUPTED, RUN_REFUSED, RUN_STARTED, + AgentLimits, AgentRuns, SubAgentPolicy, ) @@ -36,7 +39,12 @@ RunFailed, started_by, ) -from agentic_cli.workflow.agents.envelope import INTERRUPTED_ERROR +from agentic_cli.workflow.agents.envelope import ( + INTERRUPTED_ERROR, + STEP_LIMIT_ERROR, + TIME_LIMIT_ERROR, + TOKEN_LIMIT_ERROR, +) from agentic_cli.workflow.agents.outcome import CUT, REFUSAL_ERROR, REFUSED from agentic_cli.workflow.config import AgentConfig from agentic_cli.workflow.events import EventType, WorkflowEvent @@ -87,8 +95,8 @@ async def hook(run: AgentRun) -> RunAnswer: def delegations(hook: Hook, **options: Any) -> Delegations: return Delegations( - runs=options.pop("runs", AgentRuns()), policy=SubAgentPolicy(), types=TYPES, hook=hook, - **options, + runs=options.pop("runs", AgentRuns()), policy=options.pop("policy", SubAgentPolicy()), + types=options.pop("types", TYPES), hook=hook, **options, ) @@ -662,3 +670,251 @@ async def stored(conversation: SessionRef) -> dict[str, int]: assert base == {} assert result.result["agent"] == "researcher-5" + + +# -- each run under its control: its limits, a cancel of the run alone -------------------- + + +def waiting(text: str = "Half done.", *, lets_it_out: bool = False) -> tuple[Hook, asyncio.Event]: + """A hook that works until cancelled, and the event set once it works. + + On its run's own cancel it returns ``text`` and the tasks it saved (or, + ``lets_it_out``, lets the cancel out); any other cancel goes on. + """ + working = asyncio.Event() + + async def hook(run: AgentRun) -> RunAnswer: + working.set() + try: + await asyncio.Event().wait() + except asyncio.CancelledError: + if lets_it_out or not run.control.own_cancel(): + raise + return RunAnswer(text=text, state={"tasks": [{"description": "half"}]}) + return RunAnswer() # pragma: no cover + + return hook, working + + +async def stopped( + made: Delegations, working: asyncio.Event, *, by: str, error: str +) -> tuple[Any, list[WorkflowEvent], bool]: + """A delegation in a turn of ``CONVERSATION`` whose run is cancelled once + it works: its result, what it reported, and what ``cancel`` returned.""" + live = LiveEvents() + out: dict[str, Any] = {} + + async def source(): + token = set_active_turn(CONVERSATION) + try: + with live_events.reporting(live): + running = asyncio.create_task(made.delegate(request())) + await working.wait() + out["cancelled"] = made.cancel("researcher-1#1", by=by, error=error) + out["result"] = await running + finally: + reset_active_turn(token) + if False: # pragma: no cover + yield + + events = [item async for item in merged(source(), live)] + return out["result"], events, out["cancelled"] + + +class TestARunsControl: + async def test_the_hook_runs_with_its_types_limits_over_the_policys(self): + hook, asked = answering() + policy = SubAgentPolicy(limits=AgentLimits(max_model_calls=50, timeout=60.0)) + types = { + **TYPES, + "researcher": AgentConfig(name="researcher", prompt="p", description="Finds.", + limits=AgentLimits(timeout=5.0)), + } + + await delegated(delegations(hook, policy=policy, types=types), request()) + await delegated(delegations(hook, policy=policy, types=types), request( + {"agent_type": "middle", "title": "Plan", "objective": "Plan X."} + )) + + researcher, middle = asked + assert (researcher.control.ref, researcher.control.limits) == ( + RESEARCHER, AgentLimits(max_model_calls=50, timeout=5.0) + ) + assert middle.control.limits == AgentLimits(max_model_calls=50, timeout=60.0) + + async def test_by_default_a_run_makes_at_most_100_model_calls(self): + hook, asked = answering() + + await delegated(delegations(hook), request()) + + assert asked[0].control.limits == DEFAULT_LIMITS == AgentLimits(max_model_calls=100) + + async def test_a_working_runs_control_is_found_until_its_end(self): + seen: list[Any] = [] + made: Delegations + + async def hook(run: AgentRun) -> RunAnswer: + seen.append(made.control(run.ref) is run.control) + seen.append(made.control(None)) + return RunAnswer(text="Done.") + + made = delegations(hook) + await delegated(made, request()) + + assert seen == [True, None] + token = set_active_turn(CONVERSATION) + try: + assert made.control(RESEARCHER) is None + finally: + reset_active_turn(token) + + +class TestCancellingOneRun: + async def test_a_hook_that_returns_ends_it_cancelled_with_what_it_had(self): + hook, working = waiting("Half done.") + runs = AgentRuns() + + result, events, cancelled = await stopped( + delegations(hook, runs=runs), working, by="parent", error="no longer needed" + ) + + assert cancelled is True + assert result.result == { + "success": False, "agent": "researcher-1", "run": "researcher-1#1", + "status": RUN_CANCELLED, "partial": True, "result": "Half done.", + "error": "no longer needed", "cancelled_by": "parent", + } + assert result.state == {"tasks": [{"description": "half"}]} + assert statuses(events) == [("agent_run", RUN_STARTED), ("agent_run", RUN_CANCELLED)] + ended = events[-1] + assert (ended.metadata["cancelled_by"], ended.metadata["error"], + ended.metadata["partial"]) == ("parent", "no longer needed", True) + (record,) = runs.records(CONVERSATION) + assert (record.status, record.cancelled_by, record.error, record.result) == ( + RUN_CANCELLED, "parent", "no longer needed", "Half done." + ) + + async def test_a_hook_that_lets_the_cancel_out_ends_it_cancelled_with_nothing(self): + hook, working = waiting(lets_it_out=True) + + result, _, _ = await stopped(delegations(hook), working, by="user", error="stopped") + + assert (result.result["status"], result.result["cancelled_by"], result.result["result"], + result.result["partial"], result.state) == ( + RUN_CANCELLED, "user", "", False, {} + ) + + async def test_only_a_working_run_is_cancelled(self): + hook, _ = answering() + made = delegations(hook) + await delegated(made, request()) + + token = set_active_turn(CONVERSATION) + try: + assert made.cancel("researcher-1#1", by="parent", error="late") is False + assert made.cancel("nobody-1#1", by="parent", error="who") is False + with pytest.raises(ValueError, match="parent, user or limit"): + made.cancel("researcher-1#1", by="someone", error="why") + finally: + reset_active_turn(token) + + async def test_the_turns_cancel_wins(self): + """The run's own cancel and its turn's at once: the run is the turn's, + interrupted, and the cancel goes on.""" + hook, working = waiting() + runs = AgentRuns() + made = delegations(hook, runs=runs) + + async def caller(): + token = set_active_turn(CONVERSATION) + try: + with live_events.reporting(LiveEvents()): + await made.delegate(request()) + finally: + reset_active_turn(token) + + task = asyncio.create_task(caller()) + await asyncio.wait_for(working.wait(), 5) + token = set_active_turn(CONVERSATION) + try: + made.cancel("researcher-1#1", by="parent", error="no longer needed") + finally: + reset_active_turn(token) + task.cancel() + with pytest.raises(asyncio.CancelledError): + await task + + (record,) = runs.records(CONVERSATION) + assert (record.status, record.error, record.cancelled_by) == ( + RUN_INTERRUPTED, INTERRUPTED_ERROR, None + ) + + +class TestTheTimeLimit: + async def test_past_it_the_run_is_cancelled_by_its_limit(self): + hook, _ = waiting("So far: 42.") + types = { + **TYPES, + "researcher": AgentConfig(name="researcher", prompt="p", description="Finds.", + limits=AgentLimits(timeout=0.05)), + } + + result, events = await asyncio.wait_for( + delegated(delegations(hook, types=types), request()), 5 + ) + + assert (result.result["status"], result.result["cancelled_by"], result.result["error"], + result.result["result"]) == ( + RUN_CANCELLED, "limit", TIME_LIMIT_ERROR, "So far: 42." + ) + assert statuses(events) == [("agent_run", RUN_STARTED), ("agent_run", RUN_CANCELLED)] + + +class TestTheLimitsAtModelCalls: + """What a backend's run reports to its control at each model call, and how the run ends.""" + + async def test_a_run_that_made_its_last_allowed_call_completes_partial(self): + async def hook(run: AgentRun) -> RunAnswer: + calls = [run.control.model_call() for _ in range(3)] + assert calls == [False, False, True] + return RunAnswer(text="X is about 42.") + + policy = SubAgentPolicy(limits=AgentLimits(max_model_calls=3)) + result, events = await delegated(delegations(hook, policy=policy), request()) + + assert result.result == { + "success": True, "agent": "researcher-1", "run": "researcher-1#1", + "status": RUN_COMPLETED, "partial": True, "result": "X is about 42.", + "error": STEP_LIMIT_ERROR, + } + # No cut-off warning: the answer was not cut at its output limit. + assert statuses(events) == [("agent_run", RUN_STARTED), ("agent_run", RUN_COMPLETED)] + assert (events[-1].metadata["partial"], events[-1].metadata["error"]) == ( + True, STEP_LIMIT_ERROR + ) + + async def test_a_cut_last_answer_is_still_warned_of(self): + async def hook(run: AgentRun) -> RunAnswer: + run.control.model_call() + return RunAnswer(text="X is\n\n[cut off at the output limit]", outcome=CUT) + + policy = SubAgentPolicy(limits=AgentLimits(max_model_calls=1)) + result, events = await delegated(delegations(hook, policy=policy), request()) + + assert (result.result["partial"], result.result["error"]) == (True, STEP_LIMIT_ERROR) + assert events[-1].content == "researcher-1's answer was cut off at the output limit" + + async def test_a_run_over_its_tokens_ends_cancelled_with_that_answer(self): + async def hook(run: AgentRun) -> RunAnswer: + run.control.used(80, 20) + run.control.used(90, 30) + return RunAnswer(text="Found it.") + + policy = SubAgentPolicy(limits=AgentLimits(max_tokens=150)) + result, events = await delegated(delegations(hook, policy=policy), request()) + + assert (result.result["status"], result.result["cancelled_by"], result.result["error"], + result.result["result"], result.result["partial"]) == ( + RUN_CANCELLED, "limit", TOKEN_LIMIT_ERROR, "Found it.", True + ) + assert statuses(events) == [("agent_run", RUN_STARTED), ("agent_run", RUN_CANCELLED)] From 40c0cbcec3e0d076ecb5ae4c025a2bd45a6833f7 Mon Sep 17 00:00:00 2001 From: Andrey Shiryaev <7615137+shoom1@users.noreply.github.com> Date: Tue, 17 Nov 2026 17:33:35 -0500 Subject: [PATCH 03/15] Sub-agents: the runs a turn may start A turn starts at most max_runs_per_turn sub-agent runs, at any depth: the turn's span counts them, and a task call past the limit is an error result that starts no run (its brief read first, no instance numbered). task's description says At most N runs per turn. --- src/agentic_cli/workflow/agents/brief.py | 6 +- src/agentic_cli/workflow/agents/delegate.py | 27 +++++- src/agentic_cli/workflow/sessions.py | 23 ++++- tests/workflow/test_agent_brief.py | 11 +-- tests/workflow/test_agent_delegate.py | 101 ++++++++++++++++++++ tests/workflow/test_subagents_contract.py | 32 +++++++ 6 files changed, 186 insertions(+), 14 deletions(-) diff --git a/src/agentic_cli/workflow/agents/brief.py b/src/agentic_cli/workflow/agents/brief.py index d86a5083..a34c2823 100644 --- a/src/agentic_cli/workflow/agents/brief.py +++ b/src/agentic_cli/workflow/agents/brief.py @@ -233,10 +233,10 @@ def limit_sentences(policy: SubAgentPolicy) -> list[str]: """The sentences of ``task``'s description that state the limits a delegation enforces. One sentence for each limit the framework enforces on a delegation, with - the number ``policy`` sets, in the order they apply; none while no limit - is enforced. + the number ``policy`` sets, in the order they apply: the runs one turn + may start (``max_runs_per_turn``). """ - return [] + return [f"At most {policy.max_runs_per_turn} runs per turn."] def _type_line(name: str, config: AgentConfig, *, warn: bool = False) -> str: diff --git a/src/agentic_cli/workflow/agents/delegate.py b/src/agentic_cli/workflow/agents/delegate.py index b1ce7668..680a5c86 100644 --- a/src/agentic_cli/workflow/agents/delegate.py +++ b/src/agentic_cli/workflow/agents/delegate.py @@ -8,6 +8,9 @@ - reads the brief against the caller's own sub-agents (``brief.read_brief``): a brief that cannot start a run is the call's error result, and nothing else happens (no run, no record, no event); +- counts the run against its turn's (``SubAgentPolicy.max_runs_per_turn``, + runs at any depth: ``sessions.runs_this_turn``): a call past it is the + error result ``RUNS_PER_TURN_ERROR`` says, and nothing else happens; - names the run (``AgentRuns.run_for``: its instance ``-`` and its run ``#1``, under the caller's run; a turn's first run is numbered past the instances its conversation's store keeps, which ``stored`` says @@ -87,8 +90,10 @@ from agentic_cli.workflow.sessions import ( RunRef, SessionRef, + count_run_this_turn, current_turn_scope, get_active_turn, + runs_this_turn, set_active_run, set_active_tool_call, ) @@ -104,6 +109,12 @@ BLOCKING = "blocking" #: The longest error text a failed run's log line carries. _MAX_LOGGED_ERROR = 500 +#: A ``task`` call's error result once its turn has started the most runs it +#: may (``SubAgentPolicy.max_runs_per_turn``, the number). +RUNS_PER_TURN_ERROR = ( + "This turn has already started {limit} sub-agent runs, the most one turn may start. " + "Answer with what you have." +) def started_by(caller: RunRef | None) -> str: @@ -277,14 +288,24 @@ def sub_agents(self, agent: str) -> dict[str, AgentConfig]: async def delegate(self, request: DelegationRequest) -> Delegated: """Run the sub-agent ``request`` asks for, to its end; its envelope. - A brief that cannot start a run is the error result, and nothing - else happens. A cancel of the caller's task (the turn's) ends the run - ``interrupted`` once it has stopped, and goes on. + A brief that cannot start a run, or a call past the runs its turn + may start, is the error result, and nothing else happens. A cancel + of the caller's task (the turn's) ends the run ``interrupted`` once + it has stopped, and goes on. """ try: config, brief = read_brief(request.arguments, self.sub_agents(request.caller_agent)) except BriefError as error: return Delegated(result={"success": False, "error": str(error)}, state={}, run=None) + started = runs_this_turn() + limit = self.policy.max_runs_per_turn + if started is not None and started >= limit: + logger.info("subagent_runs_per_turn_reached", agent=config.name, limit=limit) + return Delegated( + result={"success": False, "error": RUNS_PER_TURN_ERROR.format(limit=limit)}, + state={}, run=None, + ) + count_run_this_turn() conversation = get_active_turn() await self._number_past_stored(conversation) ref = self._runs.run_for(conversation, request.caller, request.call_id, config.name) diff --git a/src/agentic_cli/workflow/sessions.py b/src/agentic_cli/workflow/sessions.py index 575d1d0b..fe9cd7ab 100644 --- a/src/agentic_cli/workflow/sessions.py +++ b/src/agentic_cli/workflow/sessions.py @@ -146,13 +146,16 @@ class _TurnScope: A task a turn starts copies the turn's context, this object with it; the active turn alone (the same ``SessionRef`` before and after) cannot tell - such a task that the turn it came from is over, this can. + such a task that the turn it came from is over, this can. It also counts + the sub-agent runs the turn starts, at any depth (``runs_this_turn``): + a run's own task shares its turn's span. """ - __slots__ = ("ended",) + __slots__ = ("ended", "runs") def __init__(self) -> None: self.ended = False + self.runs = 0 _turn_scope: ContextVar["_TurnScope | None"] = ContextVar( @@ -184,6 +187,22 @@ def close_turn_scope(token: Token) -> None: scope.ended = True +def runs_this_turn() -> int | None: + """How many sub-agent runs this context's turn has started (``count_run_this_turn``). + + None outside a turn's span: there is no turn to count for. + """ + scope = _turn_scope.get() + return None if scope is None else scope.runs + + +def count_run_this_turn() -> None: + """Count a sub-agent run this context's turn starts; nothing outside a turn's span.""" + scope = _turn_scope.get() + if scope is not None: + scope.runs += 1 + + def turn_has_ended() -> bool: """Whether this context belongs to a turn that has ended. diff --git a/tests/workflow/test_agent_brief.py b/tests/workflow/test_agent_brief.py index 0dae82e8..07785791 100644 --- a/tests/workflow/test_agent_brief.py +++ b/tests/workflow/test_agent_brief.py @@ -274,6 +274,7 @@ def test_the_description(self, logged): "response run in parallel.\n\n" "A sub-agent sees only the brief you write, unless its line below says it sees " "this conversation: put in the brief everything it needs to know.\n\n" + "At most 20 runs per turn.\n\n" "The agents you can hand a task to:\n" "- researcher: Finds facts.\n" "- writer (its brief also needs: deliverable, done_when): Writes the report." @@ -299,13 +300,11 @@ def test_a_blank_description_is_none(self, logged): ) assert [e["agent"] for e in logged] == ["researcher"] - def test_it_states_no_limit_while_none_is_in_force(self): - # The policy's numbers are configuration here; the description says - # only what a delegation enforces. + def test_it_states_the_runs_a_turn_may_start_with_the_policys_number(self): policy = SubAgentPolicy(max_active=2, max_runs_per_turn=3) - text = task_description(TYPES, policy) - assert text == task_description(TYPES, SubAgentPolicy()) - assert brief_module.limit_sentences(policy) == [] + + assert brief_module.limit_sentences(policy) == ["At most 3 runs per turn."] + assert task_description(TYPES, policy).split("\n\n")[2] == "At most 3 runs per turn." def test_the_limits_in_force_are_one_paragraph_before_the_agents(self, monkeypatch): seen: list[SubAgentPolicy] = [] diff --git a/tests/workflow/test_agent_delegate.py b/tests/workflow/test_agent_delegate.py index dee417d3..015a24c6 100644 --- a/tests/workflow/test_agent_delegate.py +++ b/tests/workflow/test_agent_delegate.py @@ -918,3 +918,104 @@ async def hook(run: AgentRun) -> RunAnswer: RUN_CANCELLED, "limit", TOKEN_LIMIT_ERROR, "Found it.", True ) assert statuses(events) == [("agent_run", RUN_STARTED), ("agent_run", RUN_CANCELLED)] + + +# -- the runs one turn may start ------------------------------------------------------ + + +async def in_a_turn(made: Delegations, *asked: DelegationRequest) -> list[Any]: + """Each of ``asked`` delegated in order, in one turn of ``CONVERSATION`` + (its span open, as a manager's turn has it); their results.""" + live = LiveEvents() + results: list[Any] = [] + + async def source(): + token = set_active_turn(CONVERSATION) + scope = open_turn_scope() + try: + with live_events.reporting(live): + for one in asked: + results.append(await made.delegate(one)) + finally: + close_turn_scope(scope) + reset_active_turn(token) + if False: # pragma: no cover + yield + + async for _ in merged(source(), live): + pass + return results + + +class TestTheRunsOfATurn: + async def test_a_call_past_the_limit_starts_no_run(self): + hook, asked = answering() + runs = AgentRuns() + made = delegations(hook, runs=runs, policy=SubAgentPolicy(max_runs_per_turn=2)) + + *ran, refused = await in_a_turn( + made, request(call_id="c1"), request(call_id="c2"), request(call_id="c3") + ) + + assert [r.result["status"] for r in ran] == [RUN_COMPLETED, RUN_COMPLETED] + assert refused.result == { + "success": False, + "error": "This turn has already started 2 sub-agent runs, the most one turn may " + "start. Answer with what you have.", + } + assert (refused.run, refused.state) == (None, {}) + assert len(asked) == 2 + assert [r.ref.instance for r in runs.records(CONVERSATION)] == [ + "researcher-1", "researcher-2", + ] + + async def test_a_brief_that_cannot_start_a_run_counts_nothing(self): + hook, asked = answering() + made = delegations(hook, policy=SubAgentPolicy(max_runs_per_turn=1)) + + bad, good = await in_a_turn( + made, request({"agent_type": "researcher", "title": "Find X"}), request() + ) + + assert bad.run is None and "missing: objective" in bad.result["error"] + assert good.result["status"] == RUN_COMPLETED + + async def test_each_turn_starts_its_own(self): + hook, asked = answering() + made = delegations(hook, policy=SubAgentPolicy(max_runs_per_turn=1)) + + (first,) = await in_a_turn(made, request(call_id="c1")) + (second,) = await in_a_turn(made, request(call_id="c2")) + + assert [first.result["status"], second.result["status"]] == [RUN_COMPLETED] * 2 + + async def test_a_run_started_by_a_run_counts_too(self): + made: Delegations + + async def hook(run: AgentRun) -> RunAnswer: + if run.ref.agent == "middle": + await made.delegate(request( + {"agent_type": "leaf", "title": "Look", "objective": "Look X up."}, + caller=run.ref, caller_agent="middle", call_id="m1", + )) + return RunAnswer(text="Done.") + + made = delegations(hook, policy=SubAgentPolicy(max_runs_per_turn=2)) + + middle, refused = await in_a_turn( + made, + request({"agent_type": "middle", "title": "Plan", "objective": "Plan X."}), + request(call_id="c2"), + ) + + assert middle.result["status"] == RUN_COMPLETED + assert refused.run is None and "already started 2 sub-agent runs" in refused.result["error"] + + async def test_outside_a_turn_nothing_is_counted(self): + hook, asked = answering() + made = delegations(hook, policy=SubAgentPolicy(max_runs_per_turn=1)) + + await delegated(made, request(call_id="c1")) + await delegated(made, request(call_id="c2")) + + assert len(asked) == 2 diff --git a/tests/workflow/test_subagents_contract.py b/tests/workflow/test_subagents_contract.py index 65c8ffc6..050f724e 100644 --- a/tests/workflow/test_subagents_contract.py +++ b/tests/workflow/test_subagents_contract.py @@ -2413,3 +2413,35 @@ async def test_none_lists_or_opens_as_a_conversation(self, make_crew): assert await manager.recent_messages(SESSION, user_id=USER) == [ {"role": "user", "content": "Go."}, {"role": "assistant", "content": "Done."}, ] + + +# -- per-run control: the runs of a turn, cancelling one run, the limits, steering ------------ + + +class TestTheRunsOfATurn: + async def test_a_task_call_past_the_limit_reads_why_and_starts_no_run(self, make_crew): + crew = make_crew( + team(), + subagents=SubAgentPolicy(max_runs_per_turn=1), + coordinator=[calls(delegate("researcher", "Find X.", "c1")), + calls(delegate("researcher", "Find Y.", "c2")), + says("X only."), + calls(delegate("researcher", "Find Y.", "c3")), + says("Y too.")], + researcher=[says("X is 42."), says("Y is 7.")], + ) + + events = await crew.turn() + + assert json.loads(crew.results_read("coordinator", 2)["c2"]) == { + "success": False, + "error": "This turn has already started 1 sub-agent runs, the most one turn may " + "start. Answer with what you have.", + } + assert [e.metadata["status"] for e in runs_of(events)] == [RUN_STARTED, RUN_COMPLETED] + assert crew.requests("researcher") == 1 + + await crew.turn("Now Y.") # a new turn starts its own count + + assert envelope_read(crew.results_read("coordinator", 4)["c3"])["result"] == "Y is 7." + assert [r.ref.instance for r in crew.records()] == ["researcher-1", "researcher-2"] From 56d8895f6d842d00a86363146d5327ae9bc952a6 Mon Sep 17 00:00:00 2001 From: Andrey Shiryaev <7615137+shoom1@users.noreply.github.com> Date: Tue, 17 Nov 2026 17:35:46 -0500 Subject: [PATCH 04/15] Sub-agents: a run stopped alone returns what it has, on both backends Each backend's hook takes its run's own cancel (a limit, its parent) and returns the run's last text and the shared state it changed: ADK's run stops as a stopped turn's (its abort signal, its open calls sealed in its child session), Deep Agents' stream is closed. Any other cancel goes on. The contract suite stops one of two parallel runs while the other finishes, and ends a run at its time limit, on both backends. --- src/agentic_cli/workflow/adk/manager.py | 10 +- src/agentic_cli/workflow/base_manager.py | 7 +- .../workflow/deepagents/manager.py | 11 ++- tests/workflow/test_subagents_contract.py | 99 ++++++++++++++++++- 4 files changed, 122 insertions(+), 5 deletions(-) diff --git a/src/agentic_cli/workflow/adk/manager.py b/src/agentic_cli/workflow/adk/manager.py index 7829e14e..e5976885 100644 --- a/src/agentic_cli/workflow/adk/manager.py +++ b/src/agentic_cli/workflow/adk/manager.py @@ -1470,6 +1470,9 @@ async def _run_agent(self, run: AgentRun) -> RunAnswer: so do the raw log's records of its calls. As a turn's runner is, it is stopped with its abort signal set first, so ADK seals the calls it leaves open, in its child session, before the cancel goes on. + A cancel of the run alone (its control's: a limit, its parent) stops + it so too, and it returns what it has: the last text it wrote and the + shared keys it changed; ``Delegations`` ends it cancelled. Returns: Its last answer with text, that answer's outcome mark, the shared @@ -1517,6 +1520,11 @@ async def _run_agent(self, run: AgentRun) -> RunAnswer: self._report_raw_log() async for event in processor.process_event(item, conversation.session_id): live_events.report(event) + except asyncio.CancelledError: + # The run's own cancel has stopped it as above; any other (its + # turn's) goes on. + if not run.control.own_cancel(): + raise except RuntimeError as error: cause = _plugin_cause(error) if cause is error: @@ -1524,7 +1532,7 @@ async def _run_agent(self, run: AgentRun) -> RunAnswer: raise cause from None finally: self._report_raw_log() - if processor.failure is not None: + if processor.failure is not None and run.control.cancelled is None: error, code = processor.failure if code == OVERFLOW_ERROR_CODE: raise RunFailed(error, code=code) diff --git a/src/agentic_cli/workflow/base_manager.py b/src/agentic_cli/workflow/base_manager.py index b161432c..8063e512 100644 --- a/src/agentic_cli/workflow/base_manager.py +++ b/src/agentic_cli/workflow/base_manager.py @@ -622,8 +622,11 @@ async def _run_agent(self, run: AgentRun) -> RunAnswer: from the shared state ``run.state``, reports the run's events to the turn's live events as they are made, and returns its last answer, its outcome and the shared state it changed. A failure raises (the - provider's error, or ``RunFailed``); a cancel stops the run and - raises. + provider's error, or ``RunFailed``). A cancel stops the run; the + run's own (``run.control.own_cancel()``: a limit's, its parent's) + returns what it has, its last text and the shared state it changed, + and any other (its turn's) raises. ``run.control`` keeps its limits + at its model calls (each backend's in its sub-agents' stacks). Raises: NotImplementedError: This backend runs no sub-agent. diff --git a/src/agentic_cli/workflow/deepagents/manager.py b/src/agentic_cli/workflow/deepagents/manager.py index c5696ef6..d05872e5 100644 --- a/src/agentic_cli/workflow/deepagents/manager.py +++ b/src/agentic_cli/workflow/deepagents/manager.py @@ -729,7 +729,11 @@ async def _run_agent(self, run: AgentRun) -> RunAnswer: checkpoint namespace is not the run's. The run's events go to the turn's live events as they are made, through a processor made for the run. Its input is the shared state it starts from and its - messages: an inheriting run's history, then the task message. + messages: an inheriting run's history, then the task message. A + cancel of the run alone (its control's: a limit, its parent) closes + its stream, which stops its graph, and it returns what it has: the + last text it wrote and the shared keys it changed, as of its last + finished step; ``Delegations`` ends it cancelled. Returns: Its last non-empty answer, as Deep Agents' own ``task`` read one @@ -778,6 +782,11 @@ async def _run_agent(self, run: AgentRun) -> RunAnswer: continue for event in processor.process((), mode, payload): live_events.report(event) + except asyncio.CancelledError: + # The run's own cancel has stopped it; any other (its turn's) + # goes on. + if not run.control.own_cancel(): + raise except Exception as error: if is_context_overflow(error): model = self._resolved_models.get(run.ref.agent) diff --git a/tests/workflow/test_subagents_contract.py b/tests/workflow/test_subagents_contract.py index 050f724e..364bdf07 100644 --- a/tests/workflow/test_subagents_contract.py +++ b/tests/workflow/test_subagents_contract.py @@ -35,15 +35,18 @@ from agentic_cli.tools.jobs.backends import TERMINAL_STATES from agentic_cli.tools.registry import register_tool from agentic_cli.workflow.agents import ( + RUN_CANCELLED, RUN_COMPLETED, RUN_FAILED, RUN_INTERRUPTED, RUN_REFUSED, RUN_STARTED, + AgentLimits, RunRecord, SubAgentPolicy, ) -from agentic_cli.workflow.agents.envelope import read_envelope +from agentic_cli.workflow.agents.control import RunControl +from agentic_cli.workflow.agents.envelope import TIME_LIMIT_ERROR, read_envelope from agentic_cli.workflow.config import AgentConfig from agentic_cli.workflow.events import ( EventType, @@ -441,6 +444,24 @@ async def answers(self, agent: str, call_id: str) -> list[str]: assert self._answers is not None return await self._answers(agent, call_id) + def cancel(self, run: str, *, by: str, error: str) -> bool: + """Cancel the working run ``run`` alone, as its parent, the user or a + limit does (``Delegations.cancel``, in the conversation's context).""" + token = set_active_turn(self.conversation) + try: + return self.manager._delegations.cancel(run, by=by, error=error) + finally: + reset_active_turn(token) + + def control(self, run: str) -> RunControl | None: + """The control of the working run ``run`` (``Delegations.control``).""" + ref = next((record.ref for record in self.records() if record.ref.run == run), None) + token = set_active_turn(self.conversation) + try: + return self.manager._delegations.control(ref) + finally: + reset_active_turn(token) + def recorded(self, call_id: str, run: str | None = None) -> bool: """Whether the record holds ``call_id`` of ``run`` (None: the root's own call) as finished: its result is kept for a stop to answer with.""" @@ -2445,3 +2466,79 @@ async def test_a_task_call_past_the_limit_reads_why_and_starts_no_run(self, make assert envelope_read(crew.results_read("coordinator", 4)["c3"])["result"] == "Y is 7." assert [r.ref.instance for r in crew.records()] == ["researcher-1", "researcher-2"] + + +@register_tool(capabilities=EXEMPT, description="Wait for a run to be cancelled (a contract-test tool).") +async def contract_await_a_cancelled_run() -> dict: + """Wait until a run of this conversation was cancelled, as a slow tool would.""" + runs = get_service(WORKFLOW).agent_runs + conversation = get_active_turn() + for _ in range(500): + if any(record.status == RUN_CANCELLED for record in runs.records(conversation)): + return {"success": True} + await asyncio.sleep(0.01) + return {"success": False, "error": "no run was cancelled"} + + +class TestCancellingOneRun: + """Spec 13: stopping one run while its siblings finish.""" + + async def test_stopping_one_of_two_parallel_runs_lets_the_other_finish(self, make_crew): + crew = make_crew( + [agent("coordinator", sub_agents=("researcher", "checker")), + agent("researcher", tools=(contract_lookup, contract_block)), + agent("checker", tools=(contract_await_a_cancelled_run,))], + coordinator=[calls(delegate("researcher", "Find X.", "c1"), + delegate("checker", "Check X.", "c2")), + says("Done.")], + researcher=[calls(use("contract_lookup", "r1", q="X"), text="X is about 42."), + calls(use("contract_block", "r2"))], + checker=[calls(use("contract_await_a_cancelled_run", "k1")), says("Checked.")], + ) + + with no_blocking_calls(): + turn = crew.start() + await asyncio.wait_for(BLOCKING["started"].wait(), 10) + assert crew.cancel("researcher-1#1", by="parent", error="no longer needed") is True + events = await asyncio.wait_for(turn, 10) + + read = crew.results_read("coordinator") + assert envelope_read(read["c1"]) == { + "success": False, "agent": "researcher-1", "run": "researcher-1#1", + "status": RUN_CANCELLED, "partial": True, "result": "X is about 42.", + "error": "no longer needed", "cancelled_by": "parent", + } + assert envelope_read(read["c2"])["result"] == "Checked." + assert {r.ref.instance: (r.status, r.cancelled_by) for r in crew.records()} == { + "researcher-1": (RUN_CANCELLED, "parent"), "checker-1": (RUN_COMPLETED, None), + } + (cancelled,) = runs_of(events, RUN_CANCELLED) + assert (cancelled.run.run, cancelled.metadata["cancelled_by"]) == ("researcher-1#1", "parent") + assert [e for e in events if e.type is EventType.ERROR] == [] + assert crew.control("researcher-1#1") is None # it has ended + + +class TestTheTimeLimit: + async def test_a_run_past_its_time_is_cancelled_with_what_it_wrote(self, make_crew): + crew = make_crew( + [agent("coordinator", sub_agents=("researcher",)), + agent("researcher", tools=(contract_lookup, contract_block), + limits=AgentLimits(timeout=1.0))], + coordinator=[calls(delegate("researcher", "Find X.", "c1")), says("Done.")], + researcher=[calls(use("contract_lookup", "r1", q="X"), text="X is about 42."), + calls(use("contract_block", "r2"))], + ) + + with no_blocking_calls(): + events = await asyncio.wait_for(crew.turn(), 20) + + assert envelope_read(crew.results_read("coordinator")["c1"]) == { + "success": False, "agent": "researcher-1", "run": "researcher-1#1", + "status": RUN_CANCELLED, "partial": True, "result": "X is about 42.", + "error": TIME_LIMIT_ERROR, "cancelled_by": "limit", + } + (record,) = crew.records() + assert (record.status, record.cancelled_by, record.error) == ( + RUN_CANCELLED, "limit", TIME_LIMIT_ERROR + ) + assert [e.metadata["status"] for e in runs_of(events)] == [RUN_STARTED, RUN_CANCELLED] From 1aa7da836ef5d7224aff724da68bd0b63ef9cedb Mon Sep 17 00:00:00 2001 From: Andrey Shiryaev <7615137+shoom1@users.noreply.github.com> Date: Tue, 17 Nov 2026 17:37:17 -0500 Subject: [PATCH 05/15] CLI: a stopped run's prompt is withdrawn and the turn goes on A sub-agent run stopped by its limit or its parent while its question or permission prompt is on screen cancels the asking task alone: thinking-prompt withdraws the dialog, and the events box now comes back, since the turn goes on (Ctrl+C still leaves it closed). The contract suite pins the rest on both backends: the call answered as not run, the run cancelled by its limit, the turn and the next turn's prompts going on. --- src/agentic_cli/cli/message_processor.py | 19 ++- tests/cli/test_a_stopped_runs_prompt.py | 150 ++++++++++++++++++++++ tests/workflow/test_subagents_contract.py | 56 ++++++++ 3 files changed, 221 insertions(+), 4 deletions(-) create mode 100644 tests/cli/test_a_stopped_runs_prompt.py diff --git a/src/agentic_cli/cli/message_processor.py b/src/agentic_cli/cli/message_processor.py index 8648de8b..af514fcb 100644 --- a/src/agentic_cli/cli/message_processor.py +++ b/src/agentic_cli/cli/message_processor.py @@ -693,7 +693,10 @@ async def _run_turn( asking for input, with nothing left to answer it. The boxes the request's processing opened end with it, out of the transcript, and the cancel is re-raised; the request (``process`` / - ``process_resume``) says ``CANCELLED_LINE`` once. + ``process_resume``) says ``CANCELLED_LINE`` once. A question whose + asking task alone is cancelled (a sub-agent run stopped by its limit + or its parent while its prompt is on screen) has its dialog + withdrawn, and the turn goes on with its events box back. Errors reported as ``EventType.ERROR`` are rendered as they arrive. A recoverable one is a warning and the stream decides the outcome; a @@ -761,9 +764,17 @@ async def _handle_input(request: "UserInputRequest") -> str: # leave a panel on screen that nothing downstream will ever # finish. The placement is read now: /settings may have # changed it since the session started with its own. - response = await self._prompt_user_input( - request, ui, settings.dialog_placement - ) + try: + response = await self._prompt_user_input( + request, ui, settings.dialog_placement + ) + except asyncio.CancelledError: + # The asking task alone was stopped (a sub-agent run's + # limit, its parent), not the turn: the dialog is + # withdrawn and the turn goes on, so its box comes back. + if proc_task is not None and not proc_task.cancelling(): + _open_events_box() + raise _open_events_box() return response diff --git a/tests/cli/test_a_stopped_runs_prompt.py b/tests/cli/test_a_stopped_runs_prompt.py new file mode 100644 index 00000000..687b9e1c --- /dev/null +++ b/tests/cli/test_a_stopped_runs_prompt.py @@ -0,0 +1,150 @@ +"""A sub-agent run stopped while its prompt is on screen, the turn going on. + +A run's limit (its time limit, while the user is slow to answer) or its +parent cancels the run alone: the task awaiting its question is cancelled, +not the turn's. The dialog is withdrawn (thinking-prompt closes a dialog +whose awaiter is cancelled), the turn's events box comes back, since the +turn goes on, and the turn's next question reaches the user. A cancel of the +turn itself (Ctrl+C) still leaves the box closed: the turn is unwinding +(``test_turn_boundary.py``). +""" + +from __future__ import annotations + +import asyncio +from contextlib import suppress +from types import SimpleNamespace + +from prompt_toolkit.application import create_app_session +from prompt_toolkit.input import create_pipe_input +from prompt_toolkit.output import DummyOutput +from thinking_prompt import ThinkingPromptSession + +from agentic_cli.cli.message_processor import MessageProcessor, TurnStatus +from agentic_cli.workflow.events import InputType, UserInputRequest, WorkflowEvent +from tests.cli.dialog_fakes import autospec_session, opening_boxes +from tests.loop_guard import no_blocking_calls + + +def _question(request_id: str) -> UserInputRequest: + return UserInputRequest( + request_id=request_id, tool_name="write_file", prompt="Allow it?", + input_type=InputType.CONFIRM, + ) + + +class _Workflow: + def __init__(self) -> None: + self.callback = None + + def set_input_callback(self, callback) -> None: + self.callback = callback + + def clear_input_callback(self, token=None) -> None: + self.callback = None + + +def _settings() -> SimpleNamespace: + return SimpleNamespace(verbose_thinking=False, default_user="u", dialog_placement="box") + + +def _controller(workflow: _Workflow) -> SimpleNamespace: + return SimpleNamespace(workflow=workflow, update_status_bar=lambda ui: None) + + +async def test_the_events_box_comes_back_and_the_next_question_is_asked(): + ui = opening_boxes(autospec_session()) + on_screen = asyncio.Event() + titles: list[str] = [] + seen: dict = {} + + async def yes_no_dialog(title, text, *args, **kwargs) -> bool: + titles.append(title) + if len(titles) == 1: + on_screen.set() + await asyncio.Event().wait() # the user is slow to answer + return True + + ui.yes_no_dialog.side_effect = yes_no_dialog + + def source(workflow): + async def turn(): + # The sub-agent run's task asks; its limit cancels that task alone. + run = asyncio.create_task(workflow.callback(_question("r1"))) + await on_screen.wait() + run.cancel() + with suppress(asyncio.CancelledError): + await run + seen["box open"] = not ui.boxes[-1].is_finished + yield WorkflowEvent.text("The researcher ran out of time.") + answer = await workflow.callback(_question("c2")) + yield WorkflowEvent.text(f"Asked again: {answer}.") + + return turn() + + with no_blocking_calls(): + result = await MessageProcessor()._run_turn( + source, _controller(_Workflow()), ui, _settings() + ) + + assert result.status is TurnStatus.COMPLETED + assert seen == {"box open": True} + assert len(titles) == 2 + assert [c.args[0] for c in ui.add_response.call_args_list] == [ + "The researcher ran out of time.", "Asked again: yes.", + ] + # Opened, finished at the question, back after it was withdrawn, + # finished at the next question, back after its answer: each once. + assert [box.finish.call_count for box in ui.boxes] == [1, 1, 1] + + +async def test_on_a_real_session_the_dialog_is_withdrawn_and_the_next_one_shown(): + workflow = _Workflow() + seen: dict = {} + + def source(_workflow): + async def turn(): + run = asyncio.create_task(workflow.callback(_question("r1"))) + for _ in range(500): # until the dialog has the focus + if not ui.app.layout.has_focus(ui.default_buffer): + break + await asyncio.sleep(0.01) + seen["shown"] = not ui.app.layout.has_focus(ui.default_buffer) + run.cancel() + with suppress(asyncio.CancelledError): + await run + seen["withdrawn"] = ui.app.layout.has_focus(ui.default_buffer) + seen["answer"] = await workflow.callback(_question("c2")) + yield WorkflowEvent.text("done") + + return turn() + + with create_pipe_input() as keys, create_app_session(input=keys, output=DummyOutput()): + ui = ThinkingPromptSession(message="> ") + ui.app.ttimeoutlen = 0.01 # a lone Esc is read as Esc at once + turn_done = asyncio.Event() + + async def handler(_line: str) -> None: + await MessageProcessor()._run_turn(source, _controller(workflow), ui, _settings()) + turn_done.set() + + running = asyncio.create_task(ui.run_async(handler)) + try: + for _ in range(500): # a session that fails to start ends the wait + if ui.app.is_running or running.done(): + break + await asyncio.sleep(0.01) + assert ui.app.is_running, "the session did not start" + keys.send_text("go\r") + for _ in range(50): # Esc answers the second question "no" + with suppress(TimeoutError): + await asyncio.wait_for(turn_done.wait(), 0.2) + if turn_done.is_set(): + break + if "withdrawn" in seen: + keys.send_text("\x1b") + finally: + ui.exit() + await asyncio.wait_for(running, 5) + + assert seen == {"shown": True, "withdrawn": True, "answer": "no"} diff --git a/tests/workflow/test_subagents_contract.py b/tests/workflow/test_subagents_contract.py index 364bdf07..c2c6739a 100644 --- a/tests/workflow/test_subagents_contract.py +++ b/tests/workflow/test_subagents_contract.py @@ -2542,3 +2542,59 @@ async def test_a_run_past_its_time_is_cancelled_with_what_it_wrote(self, make_cr RUN_CANCELLED, "limit", TIME_LIMIT_ERROR ) assert [e.metadata["status"] for e in runs_of(events)] == [RUN_STARTED, RUN_CANCELLED] + + +class TestALimitAtAPrompt: + """Review Focus 2: a limit that fires while the run waits at a permission + prompt (the user slow to answer): the prompt is withdrawn, the call is + answered as not run, the run ends cancelled by its limit, the turn goes + on with its envelope, and the prompts after it still reach the user.""" + + async def test_the_prompt_is_withdrawn_and_the_turn_goes_on(self, make_crew): + crew = make_crew( + [agent("coordinator", sub_agents=("researcher",), tools=(contract_ask,)), + agent("researcher", tools=("write_file",), limits=AgentLimits(timeout=1.0))], + coordinator=[calls(delegate("researcher", "Write a note.", "c1")), + calls(use("contract_ask", "c2")), says("Done."), + calls(use("contract_ask", "c3")), says("Fine.")], + researcher=[calls(use("write_file", "r1", path="note.txt", content="hi"))], + ) + withdrawn: list[str] = [] + asked: list[str] = [] + answered: list[list[str]] = [] + + async def answer(request: UserInputRequest) -> str: + if request.run is not None: # the researcher's permission prompt + try: + await asyncio.Event().wait() # the user is slow to answer + except asyncio.CancelledError: + withdrawn.append(request.run.instance) + raise + asked.append(request.tool_name) + # Read while the turn runs: Deep Agents keeps a run's answers in + # the record, which the turn's end clears. + answered.append(await crew.answers("researcher", "r1")) + return "B" + + crew.answer_with(answer) + with no_blocking_calls(): + events = await asyncio.wait_for(crew.turn(), 20) + + assert withdrawn == ["researcher-1"] + (record,) = crew.records() + assert (record.status, record.cancelled_by, record.error) == ( + RUN_CANCELLED, "limit", TIME_LIMIT_ERROR + ) + read = envelope_read(crew.results_read("coordinator", 1)["c1"]) + assert (read["status"], read["cancelled_by"], read["error"], read["result"]) == ( + RUN_CANCELLED, "limit", TIME_LIMIT_ERROR, "" + ) + (not_run,) = answered[0] + assert NOT_RUN in not_run + assert asked == ["contract_ask"] + assert '"B"' in crew.results_read("coordinator", 2)["c2"] + assert [e for e in events if e.type is EventType.ERROR] == [] + + await asyncio.wait_for(crew.turn("Ask me again."), 20) + + assert asked == ["contract_ask", "contract_ask"] From 47959acb20ad8346491097c7dd4c55d39b15ab08 Mon Sep 17 00:00:00 2001 From: Andrey Shiryaev <7615137+shoom1@users.noreply.github.com> Date: Tue, 17 Nov 2026 17:41:02 -0500 Subject: [PATCH 06/15] Sub-agents: the step and token limits at each model call Each sub-agent's stack keeps its run's limits at its model calls, ADK's RunControlPlugin in each sub-agent chain and Deep Agents' RunControlMiddleware on each sub-agent's model side: the last allowed call ends with the step-limit note (its tools still declared, since Claude refuses tool calls in a request that defines none), each answer's tokens are counted, and the run's last answer, at its step limit or past its tokens, has its tool calls dropped, so nothing runs after it and no call past a limit is made. --- src/agentic_cli/workflow/adk/manager.py | 18 ++- .../workflow/adk/run_control_plugin.py | 116 +++++++++++++++ .../workflow/deepagents/agent_builder.py | 15 +- .../workflow/deepagents/middleware.py | 131 ++++++++++++++++- tests/workflow/adk/test_plugin_chain.py | 11 +- tests/workflow/adk/test_run_control_plugin.py | 134 +++++++++++++++++ .../workflow/deepagents/test_agent_builder.py | 10 +- .../deepagents/test_run_control_middleware.py | 81 +++++++++++ .../test_subagent_outcome_middleware.py | 10 +- tests/workflow/test_subagents_contract.py | 137 +++++++++++++++++- 10 files changed, 638 insertions(+), 25 deletions(-) create mode 100644 src/agentic_cli/workflow/adk/run_control_plugin.py create mode 100644 tests/workflow/adk/test_run_control_plugin.py create mode 100644 tests/workflow/deepagents/test_run_control_middleware.py diff --git a/src/agentic_cli/workflow/adk/manager.py b/src/agentic_cli/workflow/adk/manager.py index e5976885..f67233ac 100644 --- a/src/agentic_cli/workflow/adk/manager.py +++ b/src/agentic_cli/workflow/adk/manager.py @@ -85,7 +85,7 @@ JOB_RESULT, OUTSIDE_CONTENT_KEY, ) -from agentic_cli.workflow.sessions import ConversationChangedError, SessionInfo +from agentic_cli.workflow.sessions import ConversationChangedError, SessionInfo, get_active_run from agentic_cli.workflow.tool_output import tool_output_dir from agentic_cli.workflow.usage import adk_usage_event @@ -694,9 +694,14 @@ def _agent_plugin_chain(self, agent: LlmAgent) -> list: call (a run's mark reaches the conversation with its result, ``adk/task_tool.py``), and the raw log is the app's own instance (one buffer, which the manager drains, ``_report_raw_log``); - - ``SubAgentOutcomePlugin`` after the raw log: the run's final - answer that a model refused or cut is said so, and marked, as its - parent reads it; + - ``RunControlPlugin`` after the raw log, which records each answer + as the model gave it: the run's limits at its model calls (its + control, ``Delegations.control``), before anything else edits + the request; + - ``SubAgentOutcomePlugin`` after it: the run's final answer that a + model refused or cut is said so, and marked, as its parent reads + it (an answer whose calls the step or token limit dropped among + them); - no memory index, and an overflow handler with no main agent: a sub-agent's overflow, trimmed and retried once, then answers its call with an error response (``CONTEXT_OVERFLOW``) that ends the @@ -707,6 +712,7 @@ def _agent_plugin_chain(self, agent: LlmAgent) -> list: run on this one chain at once, and a provider may number their call ids alike. """ + from agentic_cli.workflow.adk.run_control_plugin import RunControlPlugin from agentic_cli.workflow.adk.subagent_outcome_plugin import SubAgentOutcomePlugin from agentic_cli.workflow.adk.tool_error_plugin import ToolErrorPlugin @@ -716,6 +722,10 @@ def _agent_plugin_chain(self, agent: LlmAgent) -> list: ] if self._llm_logging_plugin is not None: head.append(self._llm_logging_plugin) + head.append(RunControlPlugin( + lambda: self._delegations.control(get_active_run()), + self._agent_kinds().get(agent.name), + )) head.append(SubAgentOutcomePlugin()) return self._chain( head=head, diff --git a/src/agentic_cli/workflow/adk/run_control_plugin.py b/src/agentic_cli/workflow/adk/run_control_plugin.py new file mode 100644 index 00000000..d7ff5901 --- /dev/null +++ b/src/agentic_cli/workflow/adk/run_control_plugin.py @@ -0,0 +1,116 @@ +"""ADK plugin: a sub-agent run's control at each of its model calls (``workflow/agents/control.py``). + +In each sub-agent type's plugin chain (``GoogleADKWorkflowManager._agent_plugin_chain``), +for the run in progress (``get_active_run``: the run's own task, +``agents/delegate.py``), whose control the manager's ``Delegations`` holds: + +- before each model call the call is counted (``RunControl.model_call``), + and the run's last allowed one gets ``STEP_LIMIT_NOTE`` after its last + message, in the request only: as a part of the last content when that is + the user's (a tool result, the task message), so no provider sees two + user messages in a row. Its tools stay declared: Claude refuses a request + whose messages hold tool calls or results when it defines no tools, and no + call that answer makes is run (below); +- after each, what it used (``workflow/usage.py::adk_tokens``, by its + model's provider kind) goes to ``RunControl.used``; +- on the run's last call (``RunControl.final_call``: its step limit's, or + one past its token limit) the answer's function calls are dropped, so ADK + runs none and the run ends with that answer; an answer that was calls + alone keeps an empty text, which ADK takes as the run's last answer + (``MODEL_RETURNED_NO_CONTENT``, no failure for a run). + +It changes the request and the answer in place and returns None, as +``ForeignReasoningPlugin`` does, so every plugin after it still runs. It sits +before ``SubAgentOutcomePlugin``, which then reads an answer whose calls were +dropped as the run's final one. The root's calls (no active run) and a run +without a control are left alone. +""" + +from __future__ import annotations + +from collections.abc import Callable +from typing import TYPE_CHECKING, Any, Optional + +from google.adk.plugins.base_plugin import BasePlugin +from google.genai import types + +from agentic_cli.workflow.agents.control import STEP_LIMIT_NOTE +from agentic_cli.workflow.usage import adk_tokens + +if TYPE_CHECKING: + from google.adk.agents.callback_context import CallbackContext + from google.adk.models.llm_request import LlmRequest + from google.adk.models.llm_response import LlmResponse + + from agentic_cli.workflow.agents.control import RunControl + + +class RunControlPlugin(BasePlugin): + """A sub-agent run's limits at its model calls (see the module docstring). + + Args: + control: The control of the run in progress (None: no run, or none + to control), asked at each callback. + kind: The provider kind of the type's model (``ProviderKind``'s + value), which its usage is read by; None when unknown. + """ + + def __init__(self, control: Callable[[], RunControl | None], kind: str | None) -> None: + super().__init__(name="run_control") + self._control = control + self._kind = kind + + async def before_model_callback( + self, *, callback_context: CallbackContext, llm_request: LlmRequest + ) -> Optional[LlmResponse]: + control = self._control() + if control is None: + return None + if control.model_call(): + llm_request.contents = with_note(list(llm_request.contents or []), STEP_LIMIT_NOTE) + return None + + async def after_model_callback( + self, *, callback_context: CallbackContext, llm_response: LlmResponse + ) -> Optional[LlmResponse]: + if llm_response.partial: + return None + control = self._control() + if control is None: + return None + if llm_response.usage_metadata is not None: + tokens = adk_tokens(llm_response.usage_metadata, self._kind) + control.used(tokens.input, tokens.output) + if control.final_call: + drop_calls(llm_response) + return None + + +def with_note(contents: list[types.Content], note: str) -> list[types.Content]: + """``contents`` with ``note`` after their last message, as the user's. + + A part of the last content when that is the user's (a tool result, the + task message, a steered message); else a user content of its own. + ``contents`` are not changed in place. + """ + text = types.Part.from_text(text=note) + if contents and contents[-1].role == "user": + last = contents[-1] + return [*contents[:-1], last.model_copy(update={"parts": [*(last.parts or []), text]})] + return [*contents, types.Content(role="user", parts=[text])] + + +def drop_calls(llm_response: Any) -> None: + """Drop ``llm_response``'s function calls, in place: it is the run's last answer. + + Its text and thoughts are kept; an answer that was calls alone keeps an + empty text, so ADK takes it as an answer (none is not one: ADK would + call the model again). + """ + content = llm_response.content + if content is None or not any(part.function_call for part in content.parts or ()): + return + kept = [part for part in content.parts or () if not part.function_call] + if not any(part.text is not None and not part.thought for part in kept): + kept.append(types.Part.from_text(text="")) + llm_response.content = types.Content(role=content.role or "model", parts=kept) diff --git a/src/agentic_cli/workflow/deepagents/agent_builder.py b/src/agentic_cli/workflow/deepagents/agent_builder.py index 338d114f..f19bb7ac 100644 --- a/src/agentic_cli/workflow/deepagents/agent_builder.py +++ b/src/agentic_cli/workflow/deepagents/agent_builder.py @@ -19,7 +19,9 @@ side and the tool side. - Model side, outermost first: a sub-agent's refused or cut final answer is - said so (``SubAgentOutcomeMiddleware``, every agent but the root), other + said so (``SubAgentOutcomeMiddleware``, every agent but the root), a + sub-agent run's limits are kept at its model calls (``RunControlMiddleware``, + every agent but the root, given the manager's delegations), other providers' and other agents' reasoning is left out of the request (``ForeignReasoningMiddleware``), Deep Agents' summarization counts @@ -62,6 +64,7 @@ InterruptedCallsMiddleware, MemoryIndexMiddleware, PermissionMiddleware, + RunControlMiddleware, SubAgentOutcomeMiddleware, ToolCallErrorMiddleware, ToolResultCapMiddleware, @@ -156,8 +159,9 @@ def build_agent_tree( the request that carries the summary is sent. delegations: The manager's delegations (``BaseWorkflowManager._delegations``): given, an agent with sub-agents gets the ``task`` tool, which - hands each call to them. Without it no agent delegates (a tree - a unit test builds alone). + hands each call to them, and every agent but the root + ``RunControlMiddleware``, which keeps a run's limits. Without it + no agent delegates (a tree a unit test builds alone). graphs: Filled, when given, with every agent's graph, by name. Raises: @@ -179,6 +183,11 @@ def build(name: str) -> "CompiledStateGraph": memory_index_forget=memory_index_forget if name == root else None, ) if name != root: + # Inside the outcome middleware, which reads the answer whose + # calls it dropped as final; outside the summarization, which + # counts its note. + if delegations is not None: + model_side = [RunControlMiddleware(delegations), *model_side] # Outermost: it sees the answer every other model-side # middleware let through, as the run's answer is read. model_side = [SubAgentOutcomeMiddleware(), *model_side] diff --git a/src/agentic_cli/workflow/deepagents/middleware.py b/src/agentic_cli/workflow/deepagents/middleware.py index 6d7ec1c7..b61b3f13 100644 --- a/src/agentic_cli/workflow/deepagents/middleware.py +++ b/src/agentic_cli/workflow/deepagents/middleware.py @@ -20,6 +20,8 @@ puts the main agent's memory index first in each request. - :class:`SubAgentOutcomeMiddleware`, outermost on a sub-agent's model side, says a refused or cut final answer so, for its parent and its run. +- :class:`RunControlMiddleware`, inside it on a sub-agent's model side, keeps + the run's limits at its model calls. A gate or error result is the call's ``ToolMessage`` with ``status="error"`` and the result dict as JSON content: the model reads it and carries on. @@ -40,7 +42,7 @@ import json from collections.abc import Awaitable, Callable from pathlib import Path -from typing import Any +from typing import TYPE_CHECKING, Any from langchain.agents.middleware import ( AgentMiddleware, @@ -68,6 +70,7 @@ from agentic_cli.models import ProviderKind from agentic_cli.paths import resolve_path from agentic_cli.tools.registry import ToolDefinition, get_registry, identify_tool +from agentic_cli.workflow.agents.control import STEP_LIMIT_NOTE from agentic_cli.workflow.agents.outcome import ( REFUSED, cut_off, @@ -82,12 +85,18 @@ from agentic_cli.workflow.service_registry import PERMISSION_ENGINE, get_service from agentic_cli.workflow.sessions import ( ToolCallRef, + get_active_run, get_active_turn, reset_active_tool_call, set_active_tool_call, ) from agentic_cli.workflow.tool_errors import tool_error_result, unknown_tool_result from agentic_cli.workflow.tool_output import cap_tool_result, is_saved_output +from agentic_cli.workflow.usage import langchain_tokens + +if TYPE_CHECKING: + from agentic_cli.workflow.agents.control import RunControl + from agentic_cli.workflow.agents.delegate import Delegations logger = Loggers.workflow() @@ -855,15 +864,129 @@ def _refusal(message: AIMessage) -> dict | None: def _with_outcome(response: Any) -> Any: """``response`` (any form a model call returns) with its answers through ``marked_answer``.""" + return _mapped(response, marked_answer) + + +def _mapped(response: Any, change: Callable[[AIMessage], AIMessage]) -> Any: + """``response`` (any form a model call returns) with each answer it holds through ``change``.""" if isinstance(response, AIMessage): - return marked_answer(response) + return change(response) if isinstance(response, ModelResponse): return dataclasses.replace(response, result=[ - marked_answer(message) if isinstance(message, AIMessage) else message + change(message) if isinstance(message, AIMessage) else message for message in response.result ]) if isinstance(response, ExtendedModelResponse): return dataclasses.replace( - response, model_response=_with_outcome(response.model_response) + response, model_response=_mapped(response.model_response, change) ) return response + + +def _answers(response: Any) -> list[AIMessage]: + """The answers ``response`` (any form a model call returns) holds.""" + if isinstance(response, AIMessage): + return [response] + if isinstance(response, ModelResponse): + return [message for message in response.result if isinstance(message, AIMessage)] + if isinstance(response, ExtendedModelResponse): + return _answers(response.model_response) + return [] + + +class RunControlMiddleware(AgentMiddleware): + """A sub-agent run's control at each of its model calls (``workflow/agents/control.py``). + + On each sub-agent's model side, inside ``SubAgentOutcomeMiddleware`` and + outside the rest, for the run in progress (``get_active_run``: the run's + own task, ``agents/delegate.py``), whose control the manager's + ``Delegations`` holds: + + - before each model call the call is counted (``RunControl.model_call``), + and the run's last allowed one gets ``STEP_LIMIT_NOTE`` after its last + message, in the request only (``with_note``). Its tools stay bound: + Claude refuses a request whose messages hold tool calls or results + when it defines no tools, and no call that answer makes is run (below); + - after each, what it used (``workflow/usage.py::langchain_tokens``) goes + to ``RunControl.used``; + - on the run's last call (``RunControl.final_call``: its step limit's, + or one past its token limit) the answer's tool calls are dropped + (``without_calls``), so the agent ends with that answer. + + The summarization inside it counts the note; the outcome middleware + outside it reads an answer whose calls were dropped as the run's final + one. The root's calls (no active run) and a run without a control are + left alone. + + Args: + delegations: The manager's delegations, asked at each call for the + run's control (``Delegations.control``). + """ + + def __init__(self, delegations: Callable[[], Delegations]) -> None: + super().__init__() + self._delegations = delegations + + def _control(self) -> RunControl | None: + return self._delegations().control(get_active_run()) + + async def awrap_model_call( + self, + request: ModelRequest, + handler: Callable[[ModelRequest], Awaitable[ModelResponse]], + ) -> Any: + control = self._control() + if control is None: + return await handler(request) + if control.model_call(): + request = request.override(messages=with_note(request.messages, STEP_LIMIT_NOTE)) + response = await handler(request) + for answer in _answers(response): + tokens = langchain_tokens(answer.usage_metadata) + control.used(tokens.input, tokens.output) + if control.final_call: + response = _mapped(response, without_calls) + return response + + +def with_note(messages: list[AnyMessage], note: str) -> list[AnyMessage]: + """``messages`` with ``note`` after the last, as the user's. + + Added to the last message when that is the user's own (a + ``HumanMessage``: the task message, a steered message), as a text block + after its own, so no provider sees two user messages in a row; else a + ``HumanMessage`` of its own (after a tool result). ``messages`` are not + changed in place. + """ + if messages and isinstance(messages[-1], HumanMessage): + last = messages[-1] + content = last.content + blocks = [{"type": "text", "text": content}] if isinstance(content, str) else list(content) + noted = last.model_copy(update={"content": [*blocks, {"type": "text", "text": note}]}) + return [*messages[:-1], noted] + return [*messages, HumanMessage(content=note)] + + +#: The content blocks that hold a tool call, as the adapters write them. +_CALL_BLOCKS = frozenset({"tool_use", "tool_call", "function_call"}) + + +def without_calls(message: AIMessage) -> AIMessage: + """``message`` without its tool calls: the run's last answer, its text and reasoning kept.""" + if not message.tool_calls and not message.invalid_tool_calls: + return message + content = message.content + if isinstance(content, list): + content = [ + block for block in content + if not (isinstance(block, dict) and block.get("type") in _CALL_BLOCKS) + ] + return message.model_copy(update={ + "content": content, + "tool_calls": [], + "invalid_tool_calls": [], + "additional_kwargs": { + key: value for key, value in message.additional_kwargs.items() + if key not in ("tool_calls", "function_call") + }, + }) diff --git a/tests/workflow/adk/test_plugin_chain.py b/tests/workflow/adk/test_plugin_chain.py index 8ffff9ba..8fdbb989 100644 --- a/tests/workflow/adk/test_plugin_chain.py +++ b/tests/workflow/adk/test_plugin_chain.py @@ -31,9 +31,10 @@ A native ADK YAML app gets the same chain: only the building of its agents differs (``workflow/adk/build.py``). Each sub-agent type's runner has a chain of its own in the same order (``_agent_plugin_chain``): no memory index, and -``subagent_outcome`` after the raw log (which records an answer as the model -gave it), where a sub-agent's refused or cut answer is said so, in place, so -every plugin after it still runs. +after the raw log (which records an answer as the model gave it) +``run_control``, where the run's limits are kept at its model calls, then +``subagent_outcome``, where a sub-agent's refused or cut answer is said so; +both change what they see in place, so every plugin after them still runs. """ from __future__ import annotations @@ -125,7 +126,8 @@ async def test_a_plain_config_built_app(project): async def test_a_delegating_app(project): """A tree with a sub-agent: the conversation's chain is the app's; the - sub-agent type's own runner's passes its answers through ``subagent_outcome``.""" + sub-agent type's own runner's keeps a run's limits (``run_control``) and + passes its answers through ``subagent_outcome``.""" manager = GoogleADKWorkflowManager( agent_configs=[ AgentConfig(name="lead", prompt="Lead.", sub_agents=["helper"], @@ -167,6 +169,7 @@ async def test_a_delegating_app(project): "permission", "tool_error", "llm_logging", + "run_control", "subagent_outcome", "foreign_reasoning", "context_cache", diff --git a/tests/workflow/adk/test_run_control_plugin.py b/tests/workflow/adk/test_run_control_plugin.py new file mode 100644 index 00000000..dc843091 --- /dev/null +++ b/tests/workflow/adk/test_run_control_plugin.py @@ -0,0 +1,134 @@ +"""ADK: a sub-agent run's limits at its model calls (``workflow/adk/run_control_plugin.py``). + +What the plugin does to a request and an answer, alone. Whole turns, on both +backends, are in the contract suite (``TestTheStepLimit``, +``TestTheTokenLimit``). +""" + +from __future__ import annotations + +import pytest + +pytest.importorskip("google.adk") + +from google.adk.models.llm_request import LlmRequest # noqa: E402 +from google.adk.models.llm_response import LlmResponse # noqa: E402 +from google.genai import types # noqa: E402 + +from agentic_cli.workflow.adk.run_control_plugin import ( # noqa: E402 + RunControlPlugin, + drop_calls, + with_note, +) +from agentic_cli.workflow.agents.control import STEP_LIMIT_NOTE, RunControl # noqa: E402 +from agentic_cli.workflow.agents.envelope import TOKEN_LIMIT_ERROR # noqa: E402 +from agentic_cli.workflow.agents.policy import AgentLimits # noqa: E402 +from agentic_cli.workflow.sessions import RunRef # noqa: E402 + +REF = RunRef( + agent="researcher", instance="researcher-1", run="researcher-1#1", parent_run=None, depth=1 +) + + +def user(*parts: types.Part) -> types.Content: + return types.Content(role="user", parts=list(parts)) + + +def model(*parts: types.Part) -> types.Content: + return types.Content(role="model", parts=list(parts)) + + +def text(value: str, **fields) -> types.Part: + return types.Part(text=value, **fields) + + +def call(name: str) -> types.Part: + return types.Part.from_function_call(name=name, args={}) + + +def answered(name: str) -> types.Part: + return types.Part.from_function_response(name=name, response={"success": True}) + + +class TestTheNote: + def test_it_is_a_part_of_a_last_user_content(self): + result = user(answered("lookup")) + contents = [user(text("# Task: Find X.")), model(call("lookup")), result] + + noted = with_note(contents, STEP_LIMIT_NOTE) + + assert noted[:2] == contents[:2] + assert noted[2].parts[0] == answered("lookup") + assert noted[2].parts[1].text == STEP_LIMIT_NOTE + assert result.parts == [answered("lookup")] # not changed in place + + def test_after_a_models_content_it_is_a_user_content_of_its_own(self): + contents = [user(text("# Task: Find X.")), model(text("Hm."))] + + assert with_note(contents, STEP_LIMIT_NOTE)[-1] == user(text(STEP_LIMIT_NOTE)) + + +class TestDroppedCalls: + def test_the_text_and_thoughts_stay(self): + answer = LlmResponse(content=model(text("why", thought=True), text("X is 42."), + call("lookup"))) + + drop_calls(answer) + + assert answer.content == model(text("why", thought=True), text("X is 42.")) + + def test_calls_alone_leave_an_empty_text(self): + answer = LlmResponse(content=model(text("why", thought=True), call("lookup"))) + + drop_calls(answer) + + assert answer.content == model(text("why", thought=True), text("")) + + def test_an_answer_without_calls_is_left_as_it_is(self): + content = model(text("X is 42.")) + answer = LlmResponse(content=content) + + drop_calls(answer) + + assert answer.content is content + + +class TestThePlugin: + async def test_the_roots_calls_are_left_alone(self): + plugin = RunControlPlugin(lambda: None, "anthropic") + request = LlmRequest(contents=[user(text("Go."))]) + answer = LlmResponse(content=model(call("lookup"))) + + assert await plugin.before_model_callback(callback_context=None, llm_request=request) is None + assert await plugin.after_model_callback(callback_context=None, llm_response=answer) is None + + assert request.contents == [user(text("Go."))] + assert answer.content == model(call("lookup")) + + async def test_a_call_past_the_token_limit_is_the_runs_last(self): + control = RunControl(REF, AgentLimits(max_tokens=100)) + plugin = RunControlPlugin(lambda: control, "anthropic") + usage = types.GenerateContentResponseUsageMetadata( + prompt_token_count=90, candidates_token_count=20 + ) + answer = LlmResponse(content=model(text("Found it."), call("lookup")), usage_metadata=usage) + + await plugin.before_model_callback(callback_context=None, llm_request=LlmRequest()) + await plugin.after_model_callback(callback_context=None, llm_response=answer) + + assert control.cancelled == ("limit", TOKEN_LIMIT_ERROR) + assert answer.content == model(text("Found it.")) + + async def test_a_partial_answer_counts_nothing(self): + control = RunControl(REF, AgentLimits(max_tokens=1)) + plugin = RunControlPlugin(lambda: control, "anthropic") + usage = types.GenerateContentResponseUsageMetadata( + prompt_token_count=90, candidates_token_count=20 + ) + + await plugin.after_model_callback( + callback_context=None, + llm_response=LlmResponse(content=model(text("Fo")), usage_metadata=usage, partial=True), + ) + + assert control.cancelled is None diff --git a/tests/workflow/deepagents/test_agent_builder.py b/tests/workflow/deepagents/test_agent_builder.py index a465c7fe..025911cc 100644 --- a/tests/workflow/deepagents/test_agent_builder.py +++ b/tests/workflow/deepagents/test_agent_builder.py @@ -47,6 +47,7 @@ from agentic_cli.workflow.deepagents.middleware import ( # noqa: E402 ActiveToolCallMiddleware, PermissionMiddleware, + RunControlMiddleware, SubAgentOutcomeMiddleware, ToolCallErrorMiddleware, ) @@ -444,14 +445,15 @@ def test_the_gate_the_error_and_the_active_call_middleware_in_order(self, create PatchToolCallsMiddleware, PermissionMiddleware, ToolCallErrorMiddleware, ActiveToolCallMiddleware, ] - # A sub-agent's model side has SubAgentOutcomeMiddleware; the root's not. + # A sub-agent's model side has SubAgentOutcomeMiddleware and, given + # the delegations, RunControlMiddleware; the root's neither. assert [type(m) for m in created["lead"]["middleware"]] == [ - PatchToolCallsMiddleware, SubAgentOutcomeMiddleware, + PatchToolCallsMiddleware, SubAgentOutcomeMiddleware, RunControlMiddleware, PermissionMiddleware, ToolCallErrorMiddleware, ActiveToolCallMiddleware, ] assert [type(m) for m in created["worker"]["middleware"]] == [ - PatchToolCallsMiddleware, SubAgentOutcomeMiddleware, PermissionMiddleware, - ToolCallErrorMiddleware, ActiveToolCallMiddleware, + PatchToolCallsMiddleware, SubAgentOutcomeMiddleware, RunControlMiddleware, + PermissionMiddleware, ToolCallErrorMiddleware, ActiveToolCallMiddleware, ] for name, kwargs in created.items(): (gate,) = [m for m in kwargs["middleware"] if isinstance(m, PermissionMiddleware)] diff --git a/tests/workflow/deepagents/test_run_control_middleware.py b/tests/workflow/deepagents/test_run_control_middleware.py new file mode 100644 index 00000000..937870ca --- /dev/null +++ b/tests/workflow/deepagents/test_run_control_middleware.py @@ -0,0 +1,81 @@ +"""Deep Agents: a sub-agent run's limits at its model calls (``RunControlMiddleware``). + +What the middleware does to a request and an answer, alone. Whole turns, on +both backends, are in the contract suite (``TestTheStepLimit``, +``TestTheTokenLimit``). +""" + +from __future__ import annotations + +from types import SimpleNamespace + +import pytest + +pytest.importorskip("deepagents") + +from langchain_core.messages import AIMessage, HumanMessage, ToolMessage # noqa: E402 + +from agentic_cli.workflow.agents.control import STEP_LIMIT_NOTE # noqa: E402 +from agentic_cli.workflow.deepagents.middleware import ( # noqa: E402 + RunControlMiddleware, + with_note, + without_calls, +) + +CALL = {"name": "lookup", "args": {"q": "X"}, "id": "r1", "type": "tool_call"} + + +class TestTheNote: + def test_it_ends_a_last_human_message(self): + task = HumanMessage("# Task: Find X.") + + noted = with_note([task], STEP_LIMIT_NOTE) + + assert noted[0].content == [ + {"type": "text", "text": "# Task: Find X."}, + {"type": "text", "text": STEP_LIMIT_NOTE}, + ] + assert task.content == "# Task: Find X." # not changed in place + + def test_after_a_tool_result_it_is_a_human_message_of_its_own(self): + messages = [HumanMessage("Go."), AIMessage("", tool_calls=[CALL]), + ToolMessage("42", tool_call_id="r1")] + + noted = with_note(messages, STEP_LIMIT_NOTE) + + assert noted[:3] == messages + assert (type(noted[3]), noted[3].content) == (HumanMessage, STEP_LIMIT_NOTE) + + +class TestDroppedCalls: + def test_the_calls_go_and_the_text_and_reasoning_stay(self): + answer = AIMessage( + content=[{"type": "reasoning", "reasoning": "why"}, + {"type": "text", "text": "X is 42."}, + {"type": "tool_use", "id": "r1", "name": "lookup", "input": {"q": "X"}}], + tool_calls=[CALL], + additional_kwargs={"tool_calls": [{"id": "r1"}], "other": 1}, + ) + + kept = without_calls(answer) + + assert kept.content == [{"type": "reasoning", "reasoning": "why"}, + {"type": "text", "text": "X is 42."}] + assert (kept.tool_calls, kept.additional_kwargs) == ([], {"other": 1}) + assert answer.tool_calls == [CALL] # not changed in place + + def test_an_answer_without_calls_is_itself(self): + answer = AIMessage("X is 42.") + + assert without_calls(answer) is answer + + +async def test_the_roots_calls_are_left_alone(): + """No run is active in the root's calls: its control is none.""" + middleware = RunControlMiddleware(lambda: SimpleNamespace(control=lambda run: None)) + answer = AIMessage("", tool_calls=[CALL]) + + async def handler(request): + return answer + + assert await middleware.awrap_model_call("the request", handler) is answer diff --git a/tests/workflow/deepagents/test_subagent_outcome_middleware.py b/tests/workflow/deepagents/test_subagent_outcome_middleware.py index d47d3990..5dbb885f 100644 --- a/tests/workflow/deepagents/test_subagent_outcome_middleware.py +++ b/tests/workflow/deepagents/test_subagent_outcome_middleware.py @@ -30,6 +30,7 @@ from agentic_cli.workflow.deepagents.middleware import ( # noqa: E402 ActiveToolCallMiddleware, PermissionMiddleware, + RunControlMiddleware, SubAgentOutcomeMiddleware, ToolCallErrorMiddleware, answer_outcome, @@ -246,11 +247,12 @@ def outcome(name: str) -> list[type]: assert outcome("coordinator") == [] assert outcome("lead") == outcome("worker") == [SubAgentOutcomeMiddleware] - # Outermost on the model side: before the tool side. + # Outermost on the model side, the run's control inside it, then the + # tool side. worker = [type(m) for m in created["worker"]["middleware"]] - assert worker[-4:] == [ - SubAgentOutcomeMiddleware, PermissionMiddleware, ToolCallErrorMiddleware, - ActiveToolCallMiddleware, + assert worker[-5:] == [ + SubAgentOutcomeMiddleware, RunControlMiddleware, PermissionMiddleware, + ToolCallErrorMiddleware, ActiveToolCallMiddleware, ] diff --git a/tests/workflow/test_subagents_contract.py b/tests/workflow/test_subagents_contract.py index c2c6739a..a6a46234 100644 --- a/tests/workflow/test_subagents_contract.py +++ b/tests/workflow/test_subagents_contract.py @@ -45,8 +45,13 @@ RunRecord, SubAgentPolicy, ) -from agentic_cli.workflow.agents.control import RunControl -from agentic_cli.workflow.agents.envelope import TIME_LIMIT_ERROR, read_envelope +from agentic_cli.workflow.agents.control import STEP_LIMIT_NOTE, RunControl +from agentic_cli.workflow.agents.envelope import ( + STEP_LIMIT_ERROR, + TIME_LIMIT_ERROR, + TOKEN_LIMIT_ERROR, + read_envelope, +) from agentic_cli.workflow.config import AgentConfig from agentic_cli.workflow.events import ( EventType, @@ -2598,3 +2603,131 @@ async def answer(request: UserInputRequest) -> str: await asyncio.wait_for(crew.turn("Ask me again."), 20) assert asked == ["contract_ask", "contract_ask"] + + +def limited(**limits: Any) -> list[AgentConfig]: + """A coordinator, and a researcher with ``limits`` that may look up and say who it is.""" + return [ + agent("coordinator", sub_agents=("researcher",)), + agent("researcher", tools=(contract_lookup, contract_whoami), + limits=AgentLimits(**limits)), + ] + + +def calls_to(events: list[WorkflowEvent], call_id: str) -> list[WorkflowEvent]: + """The turn's tool calls and results of the call ``call_id``.""" + return [ + event for event in events + if event.type in (EventType.TOOL_CALL, EventType.TOOL_RESULT) + and event.metadata.get("tool_call_id") == call_id + ] + + +class TestTheStepLimit: + """Spec 5.4: the run's last allowed model call is told to answer now, and + no call it makes runs; the run completes partial.""" + + async def test_the_last_allowed_call_is_told_and_the_run_completes_partial(self, make_crew): + crew = make_crew( + limited(max_model_calls=2), + coordinator=[calls(delegate("researcher", "Find X.", "c1")), says("Done.")], + researcher=[calls(use("contract_lookup", "r1", q="X"), text="Looking."), + says("X is 42.")], + ) + + with no_blocking_calls(): + events = await crew.turn() + + assert crew.requests("researcher") == 2 + assert STEP_LIMIT_NOTE not in crew.bodies("researcher")[0] + assert crew.last_message("researcher", 1).endswith(STEP_LIMIT_NOTE) + # Its tools stay declared: a request holding tool calls and results + # without them is one Claude refuses. + assert crew.tool_names("researcher", 1) == ["contract_lookup", "contract_whoami"] + assert envelope_read(crew.results_read("coordinator")["c1"]) == { + "success": True, "agent": "researcher-1", "run": "researcher-1#1", + "status": RUN_COMPLETED, "partial": True, "result": "X is 42.", + "error": STEP_LIMIT_ERROR, + } + assert [e for e in events if e.type is EventType.ERROR] == [] + + async def test_a_first_call_that_is_the_last_has_the_note_in_the_task_message( + self, make_crew + ): + crew = make_crew( + limited(max_model_calls=1), + coordinator=[calls(delegate("researcher", "Find X.", "c1")), says("Done.")], + researcher=[says("X is 42.")], + ) + + await crew.turn() + + assert crew.message_count("researcher", 0) == 1 + last = crew.last_message("researcher", 0) + assert last.startswith("# Task: Find X.") and last.endswith(STEP_LIMIT_NOTE) + + async def test_a_call_made_on_the_last_call_is_dropped_never_run(self, make_crew): + crew = make_crew( + limited(max_model_calls=2), + coordinator=[calls(delegate("researcher", "Find X.", "c1")), says("Done.")], + researcher=[calls(use("contract_lookup", "r1", q="X"), text="Looking."), + calls(use("contract_whoami", "r2"), text="X is about 42."), + says("[never asked]")], + ) + + events = await crew.turn() + + assert crew.requests("researcher") == 2 + assert SEEN == [] and calls_to(events, "r2") == [] + read = envelope_read(crew.results_read("coordinator")["c1"]) + assert (read["status"], read["partial"], read["result"], read["error"]) == ( + RUN_COMPLETED, True, "X is about 42.", STEP_LIMIT_ERROR + ) + + async def test_a_last_answer_of_calls_alone_leaves_the_text_before_it(self, make_crew): + crew = make_crew( + limited(max_model_calls=2), + coordinator=[calls(delegate("researcher", "Find X.", "c1")), says("Done.")], + researcher=[calls(use("contract_lookup", "r1", q="X"), text="X is about 42."), + calls(use("contract_whoami", "r2")), + says("[never asked]")], + ) + + events = await crew.turn() + + assert crew.requests("researcher") == 2 + assert SEEN == [] and calls_to(events, "r2") == [] + read = envelope_read(crew.results_read("coordinator")["c1"]) + assert (read["status"], read["result"], read["error"]) == ( + RUN_COMPLETED, "X is about 42.", STEP_LIMIT_ERROR + ) + assert [e for e in events if e.type is EventType.ERROR] == [] + + +class TestTheTokenLimit: + """Spec 5.4: the run's input plus output tokens, checked after each model + call; past them the run ends at that answer, cancelled by its limit.""" + + async def test_past_it_the_run_ends_at_that_answer_cancelled(self, make_crew): + crew = make_crew( + limited(max_tokens=150), + coordinator=[calls(delegate("researcher", "Find X.", "c1")), says("Done.")], + researcher=[calls(use("contract_lookup", "r1", q="X"), text="Looking.", + usage=(60, 20)), + calls(use("contract_whoami", "r2"), text="X is about 42.", + usage=(80, 20)), + says("[never asked]")], + ) + + with no_blocking_calls(): + events = await crew.turn() + + assert crew.requests("researcher") == 2 + assert SEEN == [] and calls_to(events, "r2") == [] + assert envelope_read(crew.results_read("coordinator")["c1"]) == { + "success": False, "agent": "researcher-1", "run": "researcher-1#1", + "status": RUN_CANCELLED, "partial": True, "result": "X is about 42.", + "error": TOKEN_LIMIT_ERROR, "cancelled_by": "limit", + } + used = crew.ledger().totals(run="researcher-1#1") + assert (used.input, used.output, used.calls) == (140, 40, 2) From c24a2bec8bd0e05028be904ec6ecb58303e73037 Mon Sep 17 00:00:00 2001 From: Andrey Shiryaev <7615137+shoom1@users.noreply.github.com> Date: Tue, 17 Nov 2026 17:41:57 -0500 Subject: [PATCH 07/15] Sub-agents: steering a run before its next model call A message steered to a working run (RunControl.steer) is added after its last message, as the user's, before its next model call, and stays in its transcript: ADK appends it to the run's child session and the request, Deep Agents adds it to the run's state. It comes before the step limit's note. --- .../workflow/adk/run_control_plugin.py | 38 +++++++++-- .../workflow/deepagents/middleware.py | 13 +++- .../deepagents/test_run_control_middleware.py | 20 +++++- tests/workflow/test_subagents_contract.py | 65 +++++++++++++++++++ 4 files changed, 127 insertions(+), 9 deletions(-) diff --git a/src/agentic_cli/workflow/adk/run_control_plugin.py b/src/agentic_cli/workflow/adk/run_control_plugin.py index d7ff5901..ddfdfa71 100644 --- a/src/agentic_cli/workflow/adk/run_control_plugin.py +++ b/src/agentic_cli/workflow/adk/run_control_plugin.py @@ -4,13 +4,19 @@ for the run in progress (``get_active_run``: the run's own task, ``agents/delegate.py``), whose control the manager's ``Delegations`` holds: -- before each model call the call is counted (``RunControl.model_call``), - and the run's last allowed one gets ``STEP_LIMIT_NOTE`` after its last - message, in the request only: as a part of the last content when that is - the user's (a tool result, the task message), so no provider sees two - user messages in a row. Its tools stay declared: Claude refuses a request - whose messages hold tool calls or results when it defines no tools, and no - call that answer makes is run (below); +- before each model call, the messages steered to the run since its last + (``RunControl.take_steering``) go after its last message, each a user + event appended to the run's child session (through the callback + context's session service: the invocation's own session, which a session + loaded apart would fail ADK's revision check on) and a user content added + to the request, so they stay in its transcript; +- the call is counted (``RunControl.model_call``), and the run's last + allowed one gets ``STEP_LIMIT_NOTE`` after its last message, in the + request only: as a part of the last content when that is the user's (a + tool result, the task message, a steered message), so no provider sees + two user messages in a row. Its tools stay declared: Claude refuses a + request whose messages hold tool calls or results when it defines no + tools, and no call that answer makes is run (below); - after each, what it used (``workflow/usage.py::adk_tokens``, by its model's provider kind) goes to ``RunControl.used``; - on the run's last call (``RunControl.final_call``: its step limit's, or @@ -31,6 +37,7 @@ from collections.abc import Callable from typing import TYPE_CHECKING, Any, Optional +from google.adk.events import Event from google.adk.plugins.base_plugin import BasePlugin from google.genai import types @@ -66,6 +73,9 @@ async def before_model_callback( control = self._control() if control is None: return None + steered = control.take_steering() + if steered: + await _steer(callback_context, llm_request, steered) if control.model_call(): llm_request.contents = with_note(list(llm_request.contents or []), STEP_LIMIT_NOTE) return None @@ -86,6 +96,20 @@ async def after_model_callback( return None +async def _steer( + callback_context: CallbackContext, llm_request: LlmRequest, messages: list[str] +) -> None: + """``messages``, as the user's, in the run's child session and after the request's last content.""" + service = callback_context.get_invocation_context().session_service + session = callback_context.session + for message in messages: + content = types.Content(role="user", parts=[types.Part.from_text(text=message)]) + await service.append_event(session, Event( + invocation_id=callback_context.invocation_id, author="user", content=content, + )) + llm_request.contents.append(content) + + def with_note(contents: list[types.Content], note: str) -> list[types.Content]: """``contents`` with ``note`` after their last message, as the user's. diff --git a/src/agentic_cli/workflow/deepagents/middleware.py b/src/agentic_cli/workflow/deepagents/middleware.py index b61b3f13..bb1a97a8 100644 --- a/src/agentic_cli/workflow/deepagents/middleware.py +++ b/src/agentic_cli/workflow/deepagents/middleware.py @@ -902,7 +902,11 @@ class RunControlMiddleware(AgentMiddleware): own task, ``agents/delegate.py``), whose control the manager's ``Delegations`` holds: - - before each model call the call is counted (``RunControl.model_call``), + - before each model call (a node hook, ``abefore_model``), the messages + steered to the run since its last (``RunControl.take_steering``) are + added to its state after its last message, each a ``HumanMessage``, + so they stay in its transcript; + - the call is counted (``RunControl.model_call``), and the run's last allowed one gets ``STEP_LIMIT_NOTE`` after its last message, in the request only (``with_note``). Its tools stay bound: Claude refuses a request whose messages hold tool calls or results @@ -930,6 +934,13 @@ def __init__(self, delegations: Callable[[], Delegations]) -> None: def _control(self) -> RunControl | None: return self._delegations().control(get_active_run()) + async def abefore_model(self, state: Any, runtime: Runtime[Any]) -> dict[str, Any] | None: # noqa: ARG002 + control = self._control() + steered = control.take_steering() if control is not None else [] + if not steered: + return None + return {"messages": [HumanMessage(content=message) for message in steered]} + async def awrap_model_call( self, request: ModelRequest, diff --git a/tests/workflow/deepagents/test_run_control_middleware.py b/tests/workflow/deepagents/test_run_control_middleware.py index 937870ca..8fde1f9f 100644 --- a/tests/workflow/deepagents/test_run_control_middleware.py +++ b/tests/workflow/deepagents/test_run_control_middleware.py @@ -15,12 +15,14 @@ from langchain_core.messages import AIMessage, HumanMessage, ToolMessage # noqa: E402 -from agentic_cli.workflow.agents.control import STEP_LIMIT_NOTE # noqa: E402 +from agentic_cli.workflow.agents.control import STEP_LIMIT_NOTE, RunControl # noqa: E402 +from agentic_cli.workflow.agents.policy import AgentLimits # noqa: E402 from agentic_cli.workflow.deepagents.middleware import ( # noqa: E402 RunControlMiddleware, with_note, without_calls, ) +from agentic_cli.workflow.sessions import RunRef # noqa: E402 CALL = {"name": "lookup", "args": {"q": "X"}, "id": "r1", "type": "tool_call"} @@ -79,3 +81,19 @@ async def handler(request): return answer assert await middleware.awrap_model_call("the request", handler) is answer + + +async def test_the_messages_steered_since_the_last_call_join_the_runs_state(): + ref = RunRef(agent="researcher", instance="researcher-1", run="researcher-1#1", + parent_run=None, depth=1) + control = RunControl(ref, AgentLimits()) + middleware = RunControlMiddleware(lambda: SimpleNamespace(control=lambda run: control)) + control.steer("Also find Z.") + control.steer("Be brief.") + + update = await middleware.abefore_model({}, None) + + assert [(type(m), m.content) for m in update["messages"]] == [ + (HumanMessage, "Also find Z."), (HumanMessage, "Be brief."), + ] + assert await middleware.abefore_model({}, None) is None # given once diff --git a/tests/workflow/test_subagents_contract.py b/tests/workflow/test_subagents_contract.py index a6a46234..64b1c804 100644 --- a/tests/workflow/test_subagents_contract.py +++ b/tests/workflow/test_subagents_contract.py @@ -695,6 +695,19 @@ async def contract_block() -> dict: return {"success": True} +#: ``HELD["started"]`` is set when a ``contract_hold`` call starts, and +#: ``HELD["go"]`` lets it return (made per test). +HELD: dict[str, asyncio.Event] = {} + + +@register_tool(capabilities=EXEMPT, description="Hold until let go (a contract-test tool).") +async def contract_hold() -> dict: + """Wait, as a slow tool does, until the test lets it go.""" + HELD["started"].set() + await HELD["go"].wait() + return {"success": True} + + #: What ``contract_leave_behind`` did: ``LEFT["during"]`` is the answer to the #: question it asked in its turn, ``LEFT["go"]`` lets its task go on, #: ``LEFT["task"]`` is the task. @@ -790,6 +803,7 @@ async def make_crew(backend, project, monkeypatch): cleaned up after the test.""" SEEN.clear() BLOCKING["started"] = asyncio.Event() + HELD["started"], HELD["go"] = asyncio.Event(), asyncio.Event() made: list[Crew] = [] def make( @@ -2731,3 +2745,54 @@ async def test_past_it_the_run_ends_at_that_answer_cancelled(self, make_crew): } used = crew.ledger().totals(run="researcher-1#1") assert (used.input, used.output, used.calls) == (140, 40, 2) + + +class TestSteering: + """Spec 13: a message steered to a run while its tool call is in progress + is in its next model request, after its last message, as the user's, and + stays in its transcript: still there in the request after.""" + + async def test_a_steered_message_reaches_the_next_request_and_stays(self, make_crew): + crew = make_crew( + [agent("coordinator", sub_agents=("researcher",)), + agent("researcher", tools=(contract_hold, contract_lookup))], + coordinator=[calls(delegate("researcher", "Find X.", "c1")), says("Done.")], + researcher=[calls(use("contract_hold", "r1")), + calls(use("contract_lookup", "r2", q="Z")), + says("X is 42; Z is 42.")], + ) + + with no_blocking_calls(): + turn = crew.start() + await asyncio.wait_for(HELD["started"].wait(), 10) + crew.control("researcher-1#1").steer("Also find Z.") + HELD["go"].set() + await asyncio.wait_for(turn, 10) + + assert "Also find Z." not in crew.bodies("researcher")[0] + assert crew.last_message("researcher", 1) == "Also find Z." + assert "Also find Z." in crew.bodies("researcher")[2] + assert crew.message_count("researcher", 2) == crew.message_count("researcher", 1) + 2 + assert envelope_read(crew.results_read("coordinator")["c1"])["result"] == ( + "X is 42; Z is 42." + ) + + async def test_a_message_steered_before_the_last_allowed_call_comes_before_the_note( + self, make_crew + ): + crew = make_crew( + [agent("coordinator", sub_agents=("researcher",)), + agent("researcher", tools=(contract_hold,), limits=AgentLimits(max_model_calls=2))], + coordinator=[calls(delegate("researcher", "Find X.", "c1")), says("Done.")], + researcher=[calls(use("contract_hold", "r1")), says("X is 42.")], + ) + + turn = crew.start() + await asyncio.wait_for(HELD["started"].wait(), 10) + crew.control("researcher-1#1").steer("Be brief.") + HELD["go"].set() + await asyncio.wait_for(turn, 10) + + last = crew.bodies("researcher")[1] + assert last.index("Be brief.") < last.index(STEP_LIMIT_NOTE) + assert crew.last_message("researcher", 1).endswith(STEP_LIMIT_NOTE) From a3f60d4153f1e7b469ac6e9a017c0c54eedc9f7f Mon Sep 17 00:00:00 2001 From: Andrey Shiryaev <7615137+shoom1@users.noreply.github.com> Date: Tue, 17 Nov 2026 17:50:37 -0500 Subject: [PATCH 08/15] Docs: per-run control The CHANGELOG says the sub-agent policy's limits and runs per turn are enforced (the step, time and token limits, how each ends a run, the default policy's numbers among the behaviour a user will notice) and that one run can be cancelled alone and steered; CLAUDE.md's structure lines and the sub-agent passage describe RunControl, the run control plugin and middleware, the turn's run count and the withdrawn prompt; the README's sub-agent section gives the envelope's cancelled status and a run's limits, and its limits rows no longer say no run is stopped by them. --- CHANGELOG.md | 76 +++++++++++++++++++++++++++++++++++++--------------- CLAUDE.md | 15 ++++++----- README.md | 26 +++++++++++++----- 3 files changed, 83 insertions(+), 34 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d010250e..4cfb5344 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -177,6 +177,10 @@ the start of the entry's title. - On ADK `TASK_PROGRESS` comes only when a tool call changed the task list, and a list whose tasks are all done stays: `get_tasks` answers it, where 0.6 cleared it. (Changed: **On ADK, task progress is reported…**) +- A sub-agent run past 100 model calls ends with a partial answer, and a turn + starts at most 20 sub-agent runs; an app sets other numbers with + `subagents=SubAgentPolicy(...)`. (Added: **`SubAgentPolicy` and + `AgentLimits`…**) #### Settings that moved or changed meaning @@ -568,35 +572,52 @@ the start of the entry's title. ### Added - **`SubAgentPolicy` and `AgentLimits`: an app's sub-agent policy and a - run's limits** (`agentic_cli.workflow`, and `agentic_cli.workflow.agents` - with `DEFAULT_LIMITS`). Frozen dataclasses. `SubAgentPolicy` holds an - app's numbers for its sub-agents: `max_active` (4, the runs working at - once in a conversation, at any depth), `max_runs_per_turn` (20, the runs - one turn may start) and `limits`, every run's `AgentLimits` - (`DEFAULT_LIMITS`, `AgentLimits(max_model_calls=100)`, unless the app sets - its own). A policy's own `limits` replace `DEFAULT_LIMITS` whole: + run's limits, enforced on both backends** (`agentic_cli.workflow`, and + `agentic_cli.workflow.agents` with `DEFAULT_LIMITS`). Frozen dataclasses. + `SubAgentPolicy` holds an app's numbers for its sub-agents: `max_active` + (4, the runs working at once in a conversation, at any depth), + `max_runs_per_turn` (20: a turn starts at most that many runs, at any + depth; a `task` call past it starts no run, and its caller reads + `{"success": false, "error": "This turn has already started 20 sub-agent + runs, the most one turn may start. Answer with what you have."}`; + `task`'s description says "At most 20 runs per turn.") and `limits`, + every run's `AgentLimits` (`DEFAULT_LIMITS`, + `AgentLimits(max_model_calls=100)`, unless the app sets its own). A + policy's own `limits` replace `DEFAULT_LIMITS` whole: `SubAgentPolicy(limits=AgentLimits(timeout=60))` has no model-call limit, while `AgentLimits(timeout=60).over(DEFAULT_LIMITS)` keeps the 100 calls. `AgentLimits` holds a run's `max_model_calls`, `timeout` (seconds) and - `max_tokens` (input plus output), each None for no limit of its own, and - `over(base)` lays one over another field by field: a field left None - takes the base's. So an agent type's field left None keeps the policy's - limit, and a type may set its own, higher or lower, but cannot remove a - limit the policy sets. Construction refuses, with a `ValueError` naming - the field, a limit that is not a positive int (a timeout: a positive, - finite number; `True` and `False` are no numbers here) and a policy whose - `limits` is not an `AgentLimits`. + `max_tokens` (input plus output, as the usage ledger counts them), each + None for no limit of its own, and `over(base)` lays one over another + field by field: a field left None takes the base's. So an agent type's + field left None keeps the policy's limit, and a type may set its own, + higher or lower, but cannot remove a limit the policy sets. Each is + enforced: a run's last allowed model call is told to answer now with + what it has (its tools still listed, since Claude refuses tool calls in + a request that defines no tools; any call that answer makes is dropped, + never run), and the run completes with `"partial": true`, `"error": + "step limit reached"`; a run past its `timeout`, counted from when it + starts, is cancelled (`"status": "cancelled"`, `"cancelled_by": + "limit"`, `"error": "time limit reached"`), the text it wrote so far its + partial result, and a question or permission prompt it waited at is + withdrawn; a model call that takes a run past its `max_tokens` is its + last, its calls dropped, and the run is cancelled likewise (`"token + limit reached"`), that answer's text its result. Construction refuses, + with a `ValueError` naming the field, a limit that is not a positive int + (a timeout: a positive, finite number; `True` and `False` are no numbers + here) and a policy whose `limits` is not an `AgentLimits`. - **`AgentConfig.brief_required` and `AgentConfig.limits`.** `brief_required` (default `("objective",)`) names the brief fields the agent asks a delegation to fill: `objective`, `deliverable`, `constraints`, `known`, `done_when` or `title` (a brief always has its title and its objective); `limits` (default None) is the agent's own - `AgentLimits`, over the policy's field by field. Both come after - `inherit_context`, so a positional `AgentConfig(...)` still binds, and - the framework's agent YAML takes them: `brief_required: [objective, - deliverable]`, `limits: {max_model_calls: 30, timeout: 600, max_tokens: - 200000}` (each limit read as written, so `true` or `'30'` is refused, as - is a key that is no limit). `validate_agent_graph` raises + `AgentLimits`, over the policy's field by field: its runs work under + them. Both come after `inherit_context`, so a positional + `AgentConfig(...)` still binds, and the framework's agent YAML takes + them: `brief_required: [objective, deliverable]`, `limits: + {max_model_calls: 30, timeout: 600, max_tokens: 200000}` (each limit + read as written, so `true` or `'30'` is refused, as is a key that is no + limit). `validate_agent_graph` raises `AgentGraphError` for a `brief_required` that is not a tuple or list of those names, a `limits` that is not an `AgentLimits`, and either set on the root, which is never delegated to. A delegation's brief is read @@ -614,6 +635,19 @@ the start of the entry's title. `TypeError` where it is passed: the factory's before any backend is imported, the app's before it builds anything. LangGraph's delegation does not read it. +- **One sub-agent run can be cancelled alone, and steered** (provisional: + `agentic_cli.workflow.agents.control.RunControl`, and the manager's + delegations' `control(run)` and `cancel(run_id, by=, error=)`). Each run + works under a `RunControl`: `cancel(by=, error=)` stops the run alone + (`by` its parent, the user or a limit) while its siblings and the turn go + on, and its parent reads `{"status": "cancelled", "cancelled_by": ..., + "error": ..., "partial": , "result": ""}`; the run's record and its `AGENT_RUN` end say who cancelled it + (`cancelled_by`). Ctrl+C still stops the whole turn, every run + `interrupted`. `steer(message)` gives a working run a message, added + after its last message, as the user's, before its next model call, where + it stays (ADK: in its child session). A sub-agent's dialog is withdrawn + when its run is stopped, and the turn goes on with its events box. - **A sub-agent's questions and permission prompts name it, on both backends.** `UserInputRequest.run` is the sub-agent run that asks (a `RunRef`; None for the root's own), filled by `request_user_input` from diff --git a/CLAUDE.md b/CLAUDE.md index 80fcedaf..c3f2b7cb 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -42,7 +42,7 @@ agentic-cli/ │ │ ├── session_resume.py # What /resume shows: the picker (picker: each row's backend once one is another's; PickedConversation, the id a str naming its backend), the "Resumed:" line ("Resumed on :" on another backend), the replay of the last 10 messages │ │ ├── stored_conversations.py # StoredConversations: one look at every installed backend's stored conversations (the running workflow's own, each other backend's SessionReader, opened and closed with the look): rows merged newest first, each naming its backend; where(id), delete; a backend not read (its extra missing, its store failing) left out and named in notes; a failing store warned of in the log at each look the user asks for, once a run for the app's own (warned: the job monitor's, a finished job's) │ │ ├── session_args.py # --continue / --resume → SessionStart (BaseCLIApp.main() adds them; start: new, continue, resume; SessionArgumentParser: --resume without its id names --continue and /resume) -│ │ ├── message_processor.py # WorkflowEvent → ThinkingPromptSession rendering (a sub-agent run's events box lines and transcript tool results under its name, "researcher-2 › …": the event's run, _at_work; the main agent's unchanged); Ctrl+C stops the request being processed (its boxes end with it; "Operation cancelled..." once, then the background jobs it submitted that still run, named; CancelledError re-raised); tool questions as dialogs, one at a time (a sub-agent run's titled with its instance, "researcher-2 · Permission" or "researcher-2 asks", a question's text opening with its run_label); process_compact: /compact run as a turn (compact() as its event source, live events merged in); a success line for each memory write (save_memory, update_memory, delete_memory); a failed turn said once, from its ERROR as from a raise ("Rate limited: …" for rate_limited, "Send your message again" for a ConversationChangedError) +│ │ ├── message_processor.py # WorkflowEvent → ThinkingPromptSession rendering (a sub-agent run's events box lines and transcript tool results under its name, "researcher-2 › …": the event's run, _at_work; the main agent's unchanged); Ctrl+C stops the request being processed (its boxes end with it; "Operation cancelled..." once, then the background jobs it submitted that still run, named; CancelledError re-raised); tool questions as dialogs, one at a time (a sub-agent run's titled with its instance, "researcher-2 · Permission" or "researcher-2 asks", a question's text opening with its run_label; one whose asking task alone is cancelled, a run stopped by its limit or its parent, withdrawn and the events box back, the turn going on); process_compact: /compact run as a turn (compact() as its event source, live events merged in); a success line for each memory write (save_memory, update_memory, delete_memory); a failed turn said once, from its ERROR as from a raise ("Rate limited: …" for rate_limited, "Send your message again" for a ConversationChangedError) │ │ ├── settings_command.py # /settings: a Dialog with Save and Cancel; the fields that changed → apply_settings, then save_settings(keys=changed) (an override that cannot take `keys` fails there: "Settings applied but not saved: …") │ │ ├── settings_introspection.py # Pydantic field → thinking-prompt form field (built complete: they are frozen) │ │ ├── settings_ui.py # SettingsUI(app), what BaseCLIApp's _build_ui_items/apply_settings/save_settings delegate to (it calls the app's hooks: get_ui_setting_keys, get_theme, start_new_session; keeps nothing): the fields (the model pickers: the list, catalog.offered with model_services.role_models, as /models has it; a role's model the list leaves out offered first as " (current)", "Not offered ()" starting the description, so a Save changes no model untouched); a Save all or nothing, each key as settings_persistence declares (an orchestrator change, check_backend first, starts a new conversation on the new backend through the app's start_new_session() when the open one is fresh, ConversationCore.fresh read under the turn lock, else "(applies to the next /new)"; while the workflow is down a fresh one moves there, _move_here, decided again under the turn lock); Ctrl+C wherever a Save waits says "Operation cancelled..." once (_says_so_when_stopped; a new conversation's own, as /new says it) and undoes it; the save on a worker thread @@ -75,14 +75,14 @@ agentic-cli/ │ │ ├── tool_errors.py # tool_error_result / unknown_tool_result: ADK's error shapes, for ADK and Deep Agents │ │ ├── tool_output.py # cap_tool_result: a result over tool_result_max_chars cut (head and tail, a note; a string holding a JSON object cut as its dict and given back as JSON, json_object), its full output saved in ./.{app_name}/tool-output/ for read_file; both backends │ │ ├── summary_prompt.py # SUMMARY_PROMPT (LangChain's DEFAULT_SUMMARY_PROMPT, copied with its MIT notice: ADK runs without LangChain), SUMMARY_PREFIX, summary_prompt/with_focus; both backends -│ │ ├── sessions.py # SessionRef; SessionInfo (a session list's row; backend: a reader's rows and the CLI's name theirs) and session_title; ConversationChangedError (ADK's stale session); the active turn; the active sub-agent run (RunRef, root_run, get_active_run: None in the root's own calls); the active tool call (ToolCallRef); the turn's span (open_turn_scope/close_turn_scope, turn_has_ended: a task that outlived its turn; current_turn_scope: the span itself, the identity of what is kept for one turn); instance_of (a run's instance, None for the root's: a job's started_by) +│ │ ├── sessions.py # SessionRef; SessionInfo (a session list's row; backend: a reader's rows and the CLI's name theirs) and session_title; ConversationChangedError (ADK's stale session); the active turn; the active sub-agent run (RunRef, root_run, get_active_run: None in the root's own calls); the active tool call (ToolCallRef); the turn's span (open_turn_scope/close_turn_scope, turn_has_ended: a task that outlived its turn; current_turn_scope: the span itself, the identity of what is kept for one turn; runs_this_turn/count_run_this_turn: the sub-agent runs it started, at any depth); instance_of (a run's instance, None for the root's: a job's started_by) │ │ ├── mcp.py # MCPServerConfig → to_adk_toolset / to_langchain_connection │ │ ├── permissions/ # Framework-independent capability engine │ │ │ ├── engine.py # PermissionEngine (deny-wins, default-ASK; uncontained=, per_call=: capabilities approved for each call) │ │ │ ├── capabilities.py # Capability, EXEMPT │ │ │ ├── matchers.py # PathMatcher, URLMatcher, ShellMatcher, StringGlobMatcher │ │ │ └── rules.py, store.py, prompt.py (build_request(run=): a sub-agent's prompt opens with its run; is_permission_request: by its perm- id) -│ │ ├── agents/ # Sub-agents: runs.py: the RUN_* statuses, RunRecord, AgentRuns (a manager's runs by conversation: run_for names - and its run #1 per (conversation, parent run, call id), a new one once it ended; number_from: past the instances a conversation's store keeps, a count never lowered; observe records AGENT_RUN under the turn it is reported in; interrupt_open; a record's usage: what the run used, by model, from its end event or the ledger), run_title, result_head, run_instance and run_number (the one reader of a run id: researcher-2#1's instance and number), run_label (how a dialog names a run: researcher-2 (researcher, run 1)), SUBAGENT_ERROR_PREFIX (ADK's old words for a failed delegation, kept for callers), show_as_delegation(result, envelope) (a delegation's TOOL_RESULT shown alike on both backends: the result's first line, or Failed: ; metadata["result"] the envelope); a record's brief, started_by, mode and cancelled_by; delegate.py: Delegations (delegate(DelegationRequest) → Delegated: the one place a run starts and ends, on both backends: the brief read against the caller's own sub-agents, the run named (a turn's first run past the instances its conversation's store keeps: stored=, asked once per conversation per turn, again after a failed or stopped ask), its AGENT_RUN start and end observed and reported, the backend's hook (RunHook: AgentRun → RunAnswer) run in a task of its own with the run active and no tool call, the end by the answer (completed, partial for a cut, refused, failed for an error or a raise, with one recoverable ERROR failed: , or RunFailed's own words), interrupted on a cancel; the envelope as the result), DelegationRequest, AgentRun, RunAnswer, RunFailed, started_by; outcome.py: a sub-agent's refused or cut answer (outcome_of, the refusal notice as Deep Agents 0.7.34 words it, cut_off, cut_off_warning, OPENAI_REFUSAL_PREFIX: how ADK's OpenAI adapters word a refusal); policy.py: SubAgentPolicy (max_active, max_runs_per_turn, limits) and AgentLimits (max_model_calls, timeout, max_tokens; over: a type's limits over the policy's, field by field, None taking the base's), DEFAULT_LIMITS (100 model calls), frozen and checked as they are made (a ValueError naming the field), as_policy (the one reading of a subagents= argument: a TypeError for anything but a policy or None); brief.py: BRIEF_FIELDS, Brief, BriefError, read_brief (a task call's agent type and brief, against the types its caller may start: the error texts), task_message (a run's first message, a section per filled field; an inheriting type's ends with INHERITED_CONTEXT_NOTE), task_parameters and task_description (task's schema and description, the same for both backends; limit_sentences: the limits it states); envelope.py: envelope (a delegation run's result: success only for completed, a one-line error, cancelled_by for a cancelled run), read_envelope (a dict or its JSON text, else None; never raises), the limit and interrupted error texts +│ │ ├── agents/ # Sub-agents: runs.py: the RUN_* statuses, RunRecord, AgentRuns (a manager's runs by conversation: run_for names - and its run #1 per (conversation, parent run, call id), a new one once it ended; number_from: past the instances a conversation's store keeps, a count never lowered; observe records AGENT_RUN under the turn it is reported in; interrupt_open; a record's usage: what the run used, by model, from its end event or the ledger), run_title, result_head, run_instance and run_number (the one reader of a run id: researcher-2#1's instance and number), run_label (how a dialog names a run: researcher-2 (researcher, run 1)), SUBAGENT_ERROR_PREFIX (ADK's old words for a failed delegation, kept for callers), show_as_delegation(result, envelope) (a delegation's TOOL_RESULT shown alike on both backends: the result's first line, or Failed: ; metadata["result"] the envelope); a record's brief, started_by, mode and cancelled_by; delegate.py: Delegations (delegate(DelegationRequest) → Delegated: the one place a run starts and ends, on both backends: the brief read against the caller's own sub-agents, the run named (a turn's first run past the instances its conversation's store keeps: stored=, asked once per conversation per turn, again after a failed or stopped ask), its AGENT_RUN start and end observed and reported, the backend's hook (RunHook: AgentRun → RunAnswer) run in a task of its own with the run active and no tool call, the end by the answer (completed, partial for a cut or the step limit, refused, failed for an error or a raise, with one recoverable ERROR failed: , or RunFailed's own words, cancelled by its control with what the hook had), interrupted on its turn's cancel, which wins; the envelope as the result; each run under its RunControl, the type's limits over the policy's, kept while it works: control(run), cancel(run_id, by=, error=), the run alone; a call past max_runs_per_turn the error result RUNS_PER_TURN_ERROR, no run), DelegationRequest, AgentRun (control), RunAnswer, RunFailed, started_by; control.py: RunControl (one run's: cancel(by=, error=) its task, the first cancel winning, own_cancel for the hook that takes it and returns, timing: the time limit while the hook runs; model_call/at_step_limit/final_call: the step limit, STEP_LIMIT_NOTE on the last allowed call; used: the token limit, the run ending at that answer cancelled by it; steer/take_steering), STEP_LIMIT_NOTE; outcome.py: a sub-agent's refused or cut answer (outcome_of, the refusal notice as Deep Agents 0.7.34 words it, cut_off, cut_off_warning, OPENAI_REFUSAL_PREFIX: how ADK's OpenAI adapters word a refusal); policy.py: SubAgentPolicy (max_active, max_runs_per_turn, limits) and AgentLimits (max_model_calls, timeout, max_tokens; over: a type's limits over the policy's, field by field, None taking the base's), DEFAULT_LIMITS (100 model calls), frozen and checked as they are made (a ValueError naming the field), as_policy (the one reading of a subagents= argument: a TypeError for anything but a policy or None); brief.py: BRIEF_FIELDS, Brief, BriefError, read_brief (a task call's agent type and brief, against the types its caller may start: the error texts), task_message (a run's first message, a section per filled field; an inheriting type's ends with INHERITED_CONTEXT_NOTE), task_parameters and task_description (task's schema and description, the same for both backends; limit_sentences: the limits it states, "At most runs per turn."); envelope.py: envelope (a delegation run's result: success only for completed, a one-line error, cancelled_by for a cancelled run), read_envelope (a dict or its JSON text, else None; never raises), the limit and interrupted error texts │ │ ├── adk/ # ADK orchestrator │ │ │ ├── manager.py # GoogleADKWorkflowManager (the agents built from configs or, adk_config_path, by ADK from a native YAML (library-only: no BaseCLIApp starts one; loaded once per manager at the first _validate_agent_graph (_native_root: the settings' keys exported first; a retry, a model switch and a start after cleanup build on the same tree, whose toolsets the closed runner left reusable), its agents' models resolved leniently in _resolve_extra_models, the base's hook, its registered tools' services detected; configs passed with it ignored, adk_native_configs_ignored): the only difference; _do_initialize builds the app from the tree alone, _build_app → ADKBuild, through the hooks _plugin_chain (the whole chain, top to bottom, its head _init_plugins), _compaction_config (None for a root without a budget), _context_cache_config, _agent_model_refs; the event processor built from the build; a config-built agent's prompt as an instruction provider, sent as written: no `{name}` state injection; _compact_turn: ADK's compaction once, in the base's compact turn; supports_compact False once built for a root without a budget (_no_compact_support says why); the job resume hooks: _conversation_exists (the session read without its events, num_recent_events=0), _deliver_job_notice (the notice, for every app); _run_config: the agents' synchronous tools run in ADK's tool thread pool, 8 workers; _run_and_stream: a run that fails yields the turn's one ERROR, last, none after an ERROR already yielded; the agents: _create_agents builds each config's agent on its own (_agents, by name; no ADK sub_agents), a delegating one with a TaskTool (its own tool named task: AgentGraphError); a runner per sub-agent type (_agent_runners: NoAfterTurnCompactionRunner on App(name=child_app(app_name), root_agent=the type's agent, plugins=_agent_plugin_chain(agent), the app's context cache, no compaction) over the session service, closed with the main runner by _detach_backend, rebuilt by every initialization); _run_agent, the base's hook: the run's child session (_child_session: run.state, an inheriting run's copied events; never one the store keeps, whose instance numbering goes past: ADK's create_session refuses it, and the run fails), _stored_instances (the base's hook: the highest instance number of each type the conversation's child sessions keep), the type's runner on the task message with an abort signal set before it is closed, a run-mode ADKEventProcessor, the raw log's records reported as they come (_report_raw_log); a model's failure raised as the provider's (_plugin_cause), an overflow RunFailed, a reply that is no answer RunAnswer(error=), the shared keys it changed read back) │ │ │ ├── build.py # ADKBuild (root, reply_agents, plugins, compaction, cache, models); load_native_root (from_config at validation; what ADK cannot load, wrapped as AgentGraphError naming the file, ADK's error the cause; a root that is not an LlmAgent, a name used twice in the tree and a task-mode agent refused, AgentGraphError naming it; ensure_direct_anthropic); what the run reads of any tree: reply_agents (the root and the chat-mode agents it can transfer to), own_after_tool_agents (left out by the cap) @@ -103,14 +103,15 @@ agentic-cli/ │ │ │ ├── tool_result_cap_plugin.py # ToolResultCapPlugin: every tool result through cap_tool_result (after InterruptedCallsPlugin), but an agent's with after-tool callbacks of its own (skip_agents), which ADK skips once a plugin answered │ │ │ ├── context_cache_plugin.py # One Gemini cache attempt a turn │ │ │ ├── foreign_reasoning_plugin.py # No model is sent another provider's thoughts -│ │ │ ├── subagent_outcome_plugin.py # SubAgentOutcomePlugin: a sub-agent's final answer a model refused or cut, rewritten in place (the refusal notice; the text and the cut-off note) and marked (custom_metadata agentic_cli_outcome), which the run's event processor ends it by; what it reads: finish_reason, error_code, an OTHER stop's JSON reason, the text "OpenAI refusal: "; in each sub-agent type's runner's chain (_agent_plugin_chain), after the raw log; the root's answers untouched +│ │ │ ├── subagent_outcome_plugin.py # SubAgentOutcomePlugin: a sub-agent's final answer a model refused or cut, rewritten in place (the refusal notice; the text and the cut-off note) and marked (custom_metadata agentic_cli_outcome), which the run's event processor ends it by; what it reads: finish_reason, error_code, an OTHER stop's JSON reason, the text "OpenAI refusal: "; in each sub-agent type's runner's chain (_agent_plugin_chain), after the raw log and RunControlPlugin; the root's answers untouched +│ │ │ ├── run_control_plugin.py # RunControlPlugin: a sub-agent run's control at its model calls (Delegations.control of the active run): the messages steered to it appended to its child session and the request before each call, the call counted and the last allowed one given STEP_LIMIT_NOTE (with_note: a part of the last user content; its tools stay declared), each answer's usage (adk_tokens) to used, the run's last answer's function calls dropped (drop_calls: an empty text for calls alone); in each sub-agent type's chain, after the raw log, before SubAgentOutcomePlugin │ │ │ ├── log_filters.py # install_log_filters: what ADK would print over the CLI logged at debug instead (the warnings hook, filters by logger name: see Console Output); imports no ADK (the package loads LLMLoggingPlugin on first use); the plugin-manager filter reads overflow_plugin.OVERFLOW_PLUGIN_FAILED as a record comes; BaseCLIApp.run() installs them, once │ │ │ ├── call_clock.py # Every model call timed: CallClock (a clock per call, under its EventActions, held through an error until the answer a later plugin gives; the raw log keeps one too), CallSentPlugin (last: starts it as the request goes out), CallLatencyPlugin (second, after MainAgentPlugin: marks the answer, custom_metadata[LATENCY_KEY], which the event processor reads, call_latency; an answer already marked keeps its mark: mark_latency, the overflow retry's); no adapter sends it │ │ │ └── plugins.py # LLM traffic logging (raw_llm_logging): requests as sent (SentRequestLoggingPlugin, after the fit guard); each record names its agent's model, the agent and its sub-agent run (the active run); latency per model call (call_clock.CallClock: a clock under the call's EventActions, as the fit guard keeps its copies); usage records go to the file only (the stream's LLM_USAGE is the event processor's), counted as the stream's (adk_usage_event, by the agent's kind: kinds); the summary call and the overflow retry are not logged on ADK (a follow-up) │ │ ├── deepagents/ # Deep Agents orchestrator (deepagents extra); imports neither adk/ nor langgraph/ │ │ │ ├── manager.py # DeepAgentsWorkflowManager (turns, sessions, the release hooks: the agents and MCP sessions, the checkpointer and index; MCP, skills, the job resume hooks (_conversation_exists, _deliver_job_notice), _compact_turn; _run_agent, the base's hook: the type's graph (_agent_graphs) astreamed in the run's task with var_child_runnable_config cleared, so its chunks reach its own loop alone, through a run-mode processor and a RunCallback of its own; the answer the last AIMessage with text, its outcome mark, the shared keys it changed by Deep Agents' _is_unchanged rule (copied), an overflow RunFailed) -│ │ │ ├── agent_builder.py # build_agent_tree: one create_agent per AgentConfig, each on its own (graphs=: kept by name for _run_agent; the root's alone checkpointed); a delegating agent's task from task_tool.build_task_tool (delegations=), its own tool named task an AgentGraphError -│ │ │ ├── middleware.py # InterruptedCallsMiddleware (each call recorded and answered as the active run's), PermissionMiddleware, ToolResultCapMiddleware, ToolCallErrorMiddleware, ActiveToolCallMiddleware (each call the active tool call around its tool), ForeignReasoningMiddleware, ContextOverflowMiddleware, MemoryIndexMiddleware (the root's memory index first in the first human message of each request), SubAgentOutcomeMiddleware (outermost on every sub-agent's model side: a refused or cut final answer rewritten, its reasoning kept, and marked, response_metadata["agentic_cli"]["outcome"], beside the other marks; a call that raises passes); mark_latency/answer_latency: the run callback's mark of how long a call took, response_metadata["agentic_cli"]["latency_ms"]; only the gate has a synchronous tool or model wrapper (it denies the sync tool call), the rest wrap with the async ones (`InterruptedCallsMiddleware.before_agent` is a node hook, synchronous, run on async turns too): turns run through `astream`, and a synchronous run of a graph fails at the first without a sync wrapper, LangChain's NotImplementedError +│ │ │ ├── agent_builder.py # build_agent_tree: one create_agent per AgentConfig, each on its own (graphs=: kept by name for _run_agent; the root's alone checkpointed); a delegating agent's task from task_tool.build_task_tool (delegations=), its own tool named task an AgentGraphError; every sub-agent's RunControlMiddleware (delegations=), inside its SubAgentOutcomeMiddleware +│ │ │ ├── middleware.py # InterruptedCallsMiddleware (each call recorded and answered as the active run's), PermissionMiddleware, ToolResultCapMiddleware, ToolCallErrorMiddleware, ActiveToolCallMiddleware (each call the active tool call around its tool), ForeignReasoningMiddleware, ContextOverflowMiddleware, MemoryIndexMiddleware (the root's memory index first in the first human message of each request), SubAgentOutcomeMiddleware (outermost on every sub-agent's model side: a refused or cut final answer rewritten, its reasoning kept, and marked, response_metadata["agentic_cli"]["outcome"], beside the other marks; a call that raises passes), RunControlMiddleware (inside it: a sub-agent run's control at its model calls, Delegations.control of the active run: the messages steered to it added to its state before each call, abefore_model; the call counted and the last allowed one given STEP_LIMIT_NOTE, with_note, its tools still bound; each answer's usage, langchain_tokens, to used; the run's last answer's tool calls dropped, without_calls); mark_latency/answer_latency: the run callback's mark of how long a call took, response_metadata["agentic_cli"]["latency_ms"]; only the gate has a synchronous tool or model wrapper (it denies the sync tool call), the rest wrap with the async ones (`InterruptedCallsMiddleware.before_agent` is a node hook, synchronous, run on async turns too): turns run through `astream`, and a synchronous run of a graph fails at the first without a sync wrapper, LangChain's NotImplementedError │ │ │ ├── tools.py # to_langchain_tools: a callable → StructuredTool whose .func/.coroutine is it │ │ │ ├── task_tool.py # build_task_tool: the framework's task on Deep Agents (a StructuredTool over task_parameters' JSON schema, bound to the task declaration): a call → Delegations.delegate, whose shared-key changes and envelope (JSON, the ToolMessage) come back as one Command; SHARED_KEYS; inherited_messages (an inheriting run's history: the state's messages, the summary event applied, less the message that called task) │ │ │ ├── event_processor.py # DeepAgentsEventProcessor (stream → WorkflowEvent, each call's LLM_USAGE, with its latency (answer_latency), recorded in the conversation's usage ledger before on_event, a run's end with what it used; every event its processor's agent's and run's (run=: a processor for one sub-agent run, its text activity, no TASK_PROGRESS), from the root namespace's items only (a graph a tool runs streams in its own); the task call's TOOL_RESULT shown as on ADK, from its envelope: show_as_delegation); RunCallback (every model call timed, its answer marked with its latency before any middleware sees it; a summary's usage recorded in the conversation's ledger; what a node reports inside itself, through the turn's `LiveEvents`: required; `compact()` called outside a reporting context gets one nobody reads) @@ -250,7 +251,7 @@ Workflow: - **Tool error handling**: All tools return `{"success": bool, ...}` dicts. Never raise `ToolError`. An exception that still escapes a tool is a bug, but it costs one call rather than the turn: on ADK, `workflow/adk/tool_error_plugin.py::ToolErrorPlugin` turns it into an error dict; on Deep Agents, `workflow/deepagents/middleware.py::ToolCallErrorMiddleware`, inside the permission gate, gives the same result, `{"success": false, "error": " failed: : "}` cut to 500 characters (both use `workflow/tool_errors.py`). A call to a tool name the agent does not have gets ADK's own text, its first two lines (`unknown_tool_result`: "nope failed: ValueError: Tool 'nope' not found." and the agent's tools by name), logged `tool_not_found` at info (the model's mistake): on ADK the permission gate lets ADK's stand-in through (`is_unknown_tool`: a bare `BaseTool` described "Tool not found", which runs nothing; contract-tested) and `ToolErrorPlugin` answers its lookup error; on Deep Agents the gate answers it. It catches `Exception`, never `BaseException`, so cancelling still cancels. `task` raises nothing into it: a sub-agent's model or run failing (its summary or overflow included: its own tools' errors are results already) fails the run, whose envelope its parent reads (`error`: the provider's reason; on ADK out of ADK's plugin wrapper), reported at once through the turn's live events as one recoverable `ERROR`, ` failed: `, the run's: the coordinator carries on. A sub-agent's overflow (still too long after its summary or trim) fails its run, on both backends, in the words of ADK's overflow handler, `: the request no longer fits 's context window.` with `error_code` `CONTEXT_OVERFLOW` (`context.py::subagent_overflow_message`): ADK's `OverflowPlugin` answers the run's model call with it, Deep Agents' manager raises it (`RunFailed`). A refusal is no exception here (the framework adds no `ModelRefusalMiddleware`): a sub-agent whose final answer a model refused ends its run `refused`, and its parent reads, as its envelope's result, Deep Agents 0.7.34's notice ("The subagent stopped because a model refused the request. … Retrying the same request is unlikely to succeed; rephrase it or continue without it."), on both backends and whichever deepagents the pin installs (0.7.28 has no notice of its own; 0.7.34+ finds no refusal block left to word again); an answer cut at the output limit keeps its text, followed by `[cut off at the output limit]`, and its run ends `completed` and `partial`, with one recoverable warning ("'s answer was cut off at the output limit"); the answer's thoughts or reasoning are kept. ADK's `SubAgentOutcomePlugin` and Deep Agents' `SubAgentOutcomeMiddleware` rewrite and mark the answer, by `workflow/agents/outcome.py`. On ADK the plugin reads the answer's `finish_reason` (Claude's `refusal` and a Chat Completions `content_filter` arrive as `SAFETY`, `max_tokens` and `length` as `MAX_TOKENS`, Gemini's as themselves), the `error_code` ADK sets on an answer with no content (a Gemini prompt's `block_reason`), the `reason` an `OTHER` stop names in its JSON error message (ADK's OpenAI Responses adapter's `incomplete_details`, `content_filter` among them) and a text part `OpenAI refusal: ` (that adapter's refusal, and `OpenAICompatibleLlm`'s of a Chat Completions `refusal`, which ADK's class drops). On Deep Agents the middleware reads `response_metadata`'s `stop_reason` (ChatAnthropic), `finish_reason` (ChatOpenAI, ChatGoogleGenerativeAI), `incomplete_details.reason` (the Responses API) and `prompt_feedback.block_reason` (a Gemini prompt block), and a refusal the answer holds (a refusal block, standard or `non_standard`, or `additional_kwargs["refusal"]`). The root's own answers reach the user as their model gave them: on ADK a root's refusal with no answer (Claude's, Gemini's) is still the turn's one `ERROR` (" returned no answer"), and a root on OpenRouter or an OpenAI-compatible server replies "OpenAI refusal: ". On both backends the root's own failure leaves the run: the turn's one `ERROR`. A gate or error result goes back as the call's `ToolMessage` with `status="error"`. LangGraph's `ToolNode` runs with `handle_tool_errors=True`. - **Tool result cap**: every tool result passes `workflow/tool_output.py::cap_tool_result` (registered, MCP and skill tools, `job_result`, a delegation's envelope on either backend): one over `tool_result_max_chars` is cut to its shape and as much of its head and tail as fits (the kept length is bisected, since JSON escapes vary), with a note (under `truncated`, or appended to a string) pointing at its full output in `./.{app_name}/tool-output/`, written for `read_file` to page by lines (lines over 2,000 characters split). A string that holds a JSON object (`json_object`: a delegation's envelope, which both task tools write unescaped, `ensure_ascii=False`; a framework tool's dict in a Deep Agents `ToolMessage`) is cut as that dict and given back as its JSON text, so the parent reads JSON still, on both backends. On ADK, `workflow/adk/tool_result_cap_plugin.py::ToolResultCapPlugin` is registered after `InterruptedCallsPlugin`, since ADK stops at the first `after_tool_callback` that returns a value, and it leaves out an agent with `after_tool_callback`s of its own (a native YAML app's, `build.own_after_tool_agents`), which ADK would skip once the cap answered. ADK's Claude and OpenAI Responses adapters send only a result's `content`, else its `result`, so the plugin also puts the note there (`_note_where_sent`). On Deep Agents, `ToolResultCapMiddleware` sits between the permission gate and `ToolCallErrorMiddleware`, so an error result is capped too, and reads a `ToolMessage` (its text cut by the cap's string rule, text blocks joined into the first) and each `ToolMessage` of a `Command`. A call of the framework's `read_file` (by identity, as each gate resolves tools) on a saved output is cut without a second save. Saving never fails the call (`tool_output_not_saved` warns once per folder, then debug), and a cap that raises leaves the result uncut (`tool_result_cap_failed` at warning, its traceback at debug). - **Summarizing on ADK (main agent only)**: every app's App (a native ADK YAML app's too, when its root's model has a context budget) has ADK's `EventsCompactionConfig` with `workflow/adk/compaction.py::AgentCliSummarizer` at the root's trigger (`context_budget`, as on Deep Agents); ADK checks before every agent's model call, and `MainAgentPlugin` (the first plugin) records the running agent in a ContextVar, so the summarizer writes only for the root (a sub-agent's run, on its type's runner, has no compaction config at all: a sub-agent compacting the shared session lost its brief and looped, 100 requests in one turn, offline). The summarizer picks its own range before paying for anything (`summary_range`: the newest `keep` tokens and the current turn kept, a cut only where a user turn starts, never parting a call from its result, long-running calls excepted since ADK re-injects them, nor leaving a kept event stamped inside the range; none for a saving under 20% of the trigger, the seed left out of it), writes on the root's own model (`_simple_model(SUMMARY_MAX_TOKENS, agent=root)`, thinking off) with `workflow/summary_prompt.py`, the rendering sized to that model's window (the middle cut, `MIDDLE_OMITTED`, the seed kept whole), and returns **user-role** text starting `SUMMARY_PREFIX` (a model-role first message is one Claude refuses), which the fit guard folds, after the memory index when the request has one, into the next user text (`fold_summary`), so no request holds two user messages in a row. `last_kept_turns` and `last_error` are for its callers: a manual summarizer warns of nothing itself. It reports through the turn's live events (`_run_and_stream` iterates the runner through `live_events.merged` under `reporting(live)`); any failure is one recoverable `ERROR` a turn, never raised to ADK. `NoAfterTurnCompactionRunner` overrides ADK's private `Runner._run_post_invocation_compaction` (contract-tested), so the prompt never waits for a summary after the answer. `FitGuardPlugin` is the last plugin (but `SentRequestLoggingPlugin`, which logs a request as sent, and `CallSentPlugin`, which starts the call's clock) and `OverflowPlugin` the one before it (`MemoryIndexPlugin`, when the root has a memory tool and `memory_index_enabled` is on, the one before that: it puts the conversation's memory index snapshot first in the root's requests, never in the session): the guard leaves a request's oldest turns out when it is over its agent's budget (keeping the newest turn and what opens the conversation, the memory index then a summary: `protected_head`) and keeps each request as it came in (`request_as_seen`: one copy per model call, under the call's `EventActions`, which ADK passes to all three of its callbacks: each sub-agent run is an invocation of its own on a child session, but two runs of one type share that type's runner and its plugins, and a run drops only what its own cancelled calls left, as it ends), and the overflow handler, on a provider's overflow, summarizes now (the root, through `compact_session`, ADK's private `_run_compaction_for_token_threshold_config`; `_summarize_now` returns `WrittenSummary(text, kept_turns)`, and the retry is the index, the summary and those turns) or trims to half the budget (a sub-agent, or nothing to summarize), builds the retry from the guard's copy without the context cache, retries once on the agent's `canonical_model`, then answers the root with `LlmResponse(error_code="CONTEXT_OVERFLOW")`, never model text (ADK would store it as the reply), which `ADKEventProcessor` maps to the turn's `ERROR`; a retry that fails otherwise propagates, and `_run_and_stream` unwraps ADK's plugin-manager `RuntimeError` to the provider's error; a sub-agent's call that still does not fit is answered with an error response too, `CONTEXT_OVERFLOW` and `subagent_overflow_message`, which its run's processor keeps as the run's failure: the run ends `failed` with those words (`RunFailed`), its parent reads them in the envelope, and the user is warned once, by the framework's delegation (`agents/delegate.py`), as on Deep Agents. A native ADK YAML app gets all of it: only the building of its agents differs (`workflow/adk/build.py`). Its chat-mode sub-agents keep transferring, and an agent the root transfers to replies to the user (`build.reply_agents`: its text is the reply, recent_messages reads it, its overflow is the turn's clear error, its calls write the outside-content mark); the summary and the memory index stay the root's, so such an agent is trimmed by the fit guard, not summarized. An agent's own callbacks (a native app's) run after every plugin, and only when none answered: its before-model callbacks see the request after the fit guard, and the cap leaves out an agent with after-tool callbacks. A main agent whose model does not resolve through the catalog has no budget and no summary. -- **Sub-agents delegate and return**: on both backends a sub-agent run is a call of its parent's `task` tool (the framework's: `tools/_core/delegation.py` declares it, `workflow/agents/delegate.py` runs it) that returns in the same turn; only the root replies to the user (a sub-agent's `TEXT` carries `metadata["subagent"]`, and the CLI shows it as the events box's status line, under its run's name: `researcher-2 › …`; `/agents` lists a conversation's runs), and the next turn starts at the root; fact extraction reads only the user's and the root's text. `task` takes `agent_type` (one of the caller's own sub-agents) and a brief (`workflow/agents/brief.py`: `title`, `objective`, `deliverable`, `constraints`, `known`, `done_when`), its schema and description the same on both backends (`task_parameters`, `task_description`: a line per type with its description, "The agent." with a warning, `subagent_without_description`, for one without, and the fields `AgentConfig.brief_required` asks for); `read_brief` checks a call against them, and one that cannot start a run is the call's `{"success": false, "error": …}`, no run started or numbered. `Delegations.delegate` (the manager's `_delegations`) does the rest, alike on both: it names the run (`AgentRuns.run_for`), reports its `AGENT_RUN` start (title, brief, `started_by`, `mode`) and end through the turn's live events and the records, and runs the backend's hook, `_run_agent(AgentRun)`, in a task of its own, where the run is the active run and no tool call is, so each run ends at its own end. The run's first message is the task message (`task_message`); it starts from the conversation's `plan` and `tasks` (`AgentRun.state`), and the keys it changed come back to its caller's state (`RunAnswer.state`). It ends as the `RunAnswer` says: its last text (a reply that also called a tool included; none at all, an empty result shown `No answer`), `refused` or `partial` by the outcome mark, `failed` for an error or a raise (one recoverable `ERROR`, ` failed: `, or the hook's own words, `RunFailed`: an overflow's); and the call's result is the run's envelope as JSON (`workflow/agents/envelope.py`), shown by `show_as_delegation`. A cancel of the caller's task stops the run's task first and ends the run `interrupted`. `AgentConfig.inherit_context` sets what a run sees: False (the default) its task alone, True its parent's conversation too, read once as the run starts (the conversation after any summary, less the message that called `task`), before the task message, which then ends with `INHERITED_CONTEXT_NOTE` (whose conversation it reads, which message is its task); `validate_agent_graph` refuses a value that is not True or False, `inherit_context=True` on the root and, in 0.7.0, on an agent with sub-agents or below another sub-agent. On ADK (`workflow/adk/task_tool.py::TaskTool`) every config-built agent is built on its own, with no ADK `sub_agents`, so ADK offers none `transfer_to_agent`, and gets ADK's identity line ("You are an agent. Your internal name is …"); a delegating agent has one `TaskTool`. Each sub-agent type runs on its own runner (`App(name=child_app(app_name))`, the type's agent its root, `_agent_plugin_chain`: the main chain configured for a sub-agent, no memory index, no summary, `SubAgentOutcomePlugin`; every plugin's per-call state keyed by invocation) over the manager's session service, on a child session per run (`child_session_id`: `/`; an inheriting run's gets the conversation's events copied, `task_tool.inherited_events`), under an app no conversation list reads. On Deep Agents (`workflow/deepagents/task_tool.py::build_task_tool`) each type's graph is built on its own, and a run `astream`s it in its task with `var_child_runnable_config` cleared, so its chunks reach its own loop alone, never its parent's stream; an inheriting run's history is the parent's messages with Deep Agents' summary event applied (`SummarizationMiddleware._apply_event_to_messages`, private: `tests/workflow/deepagents/test_compact.py` pins it), and `ForeignReasoningMiddleware(kind, agent=...)` leaves out the reasoning of AI messages another agent wrote. A native ADK YAML app keeps transferring (chat-mode sub-agents); a task-mode agent in one is refused at validation, since ADK runs its delegation outside the tool pipeline and keeps the call open across turns. +- **Sub-agents delegate and return**: on both backends a sub-agent run is a call of its parent's `task` tool (the framework's: `tools/_core/delegation.py` declares it, `workflow/agents/delegate.py` runs it) that returns in the same turn; only the root replies to the user (a sub-agent's `TEXT` carries `metadata["subagent"]`, and the CLI shows it as the events box's status line, under its run's name: `researcher-2 › …`; `/agents` lists a conversation's runs), and the next turn starts at the root; fact extraction reads only the user's and the root's text. `task` takes `agent_type` (one of the caller's own sub-agents) and a brief (`workflow/agents/brief.py`: `title`, `objective`, `deliverable`, `constraints`, `known`, `done_when`), its schema and description the same on both backends (`task_parameters`, `task_description`: a line per type with its description, "The agent." with a warning, `subagent_without_description`, for one without, and the fields `AgentConfig.brief_required` asks for); `read_brief` checks a call against them, and one that cannot start a run is the call's `{"success": false, "error": …}`, no run started or numbered. `Delegations.delegate` (the manager's `_delegations`) does the rest, alike on both: it names the run (`AgentRuns.run_for`), reports its `AGENT_RUN` start (title, brief, `started_by`, `mode`) and end through the turn's live events and the records, and runs the backend's hook, `_run_agent(AgentRun)`, in a task of its own, where the run is the active run and no tool call is, so each run ends at its own end. The run's first message is the task message (`task_message`); it starts from the conversation's `plan` and `tasks` (`AgentRun.state`), and the keys it changed come back to its caller's state (`RunAnswer.state`). It ends as the `RunAnswer` says: its last text (a reply that also called a tool included; none at all, an empty result shown `No answer`), `refused` or `partial` by the outcome mark, `failed` for an error or a raise (one recoverable `ERROR`, ` failed: `, or the hook's own words, `RunFailed`: an overflow's); and the call's result is the run's envelope as JSON (`workflow/agents/envelope.py`), shown by `show_as_delegation`. A cancel of the caller's task stops the run's task first and ends the run `interrupted`. Each run works under its `RunControl` (`workflow/agents/control.py`, `AgentRun.control`), with its type's `AgentConfig.limits` over the policy's (`SubAgentPolicy.limits`, `DEFAULT_LIMITS`: 100 model calls): `Delegations.cancel(run_id, by=, error=)` cancels the run alone (its parent, the user or a limit), and the hook, seeing its own cancel (`own_cancel`), stops the run as a stopped turn's (ADK: its abort signal, its open calls sealed in its child session; Deep Agents: its stream closed) and returns what it has: the run ends `cancelled` with `cancelled_by` and that text, `partial`, while its siblings and the turn go on; the turn's own cancel still wins (`interrupted`). Past its `timeout` (counted from when its hook starts, `timing`) the run is cancelled by its limit (`time limit reached`); each model call is counted before it is made (`RunControlPlugin` in each sub-agent chain, `RunControlMiddleware` on each sub-agent's model side) and the last allowed one gets `STEP_LIMIT_NOTE` after its last message, its tools still declared (Claude refuses tool calls in a request that defines no tools); its answer's calls are dropped, never run, so the run completes `partial`, `step limit reached`; each call's tokens are counted after it, and past `max_tokens` that answer, its calls dropped, is the run's last, `cancelled` by its limit (`token limit reached`). A turn starts at most `max_runs_per_turn` runs, at any depth (`sessions.runs_this_turn`): a call past it is the error result, no run started; `task`'s description says so (`limit_sentences`). A message steered to a working run (`RunControl.steer`, through `Delegations.control(run)`) is added after its last message, as the user's, before its next model call, and stays in its transcript (ADK: appended to its child session; Deep Agents: added to its state). A dialog whose run is stopped is withdrawn, the turn going on (`MessageProcessor`). `AgentConfig.inherit_context` sets what a run sees: False (the default) its task alone, True its parent's conversation too, read once as the run starts (the conversation after any summary, less the message that called `task`), before the task message, which then ends with `INHERITED_CONTEXT_NOTE` (whose conversation it reads, which message is its task); `validate_agent_graph` refuses a value that is not True or False, `inherit_context=True` on the root and, in 0.7.0, on an agent with sub-agents or below another sub-agent. On ADK (`workflow/adk/task_tool.py::TaskTool`) every config-built agent is built on its own, with no ADK `sub_agents`, so ADK offers none `transfer_to_agent`, and gets ADK's identity line ("You are an agent. Your internal name is …"); a delegating agent has one `TaskTool`. Each sub-agent type runs on its own runner (`App(name=child_app(app_name))`, the type's agent its root, `_agent_plugin_chain`: the main chain configured for a sub-agent, no memory index, no summary, `RunControlPlugin` and `SubAgentOutcomePlugin`; every plugin's per-call state keyed by invocation) over the manager's session service, on a child session per run (`child_session_id`: `/`; an inheriting run's gets the conversation's events copied, `task_tool.inherited_events`), under an app no conversation list reads. On Deep Agents (`workflow/deepagents/task_tool.py::build_task_tool`) each type's graph is built on its own, and a run `astream`s it in its task with `var_child_runnable_config` cleared, so its chunks reach its own loop alone, never its parent's stream; an inheriting run's history is the parent's messages with Deep Agents' summary event applied (`SummarizationMiddleware._apply_event_to_messages`, private: `tests/workflow/deepagents/test_compact.py` pins it), and `ForeignReasoningMiddleware(kind, agent=...)` leaves out the reasoning of AI messages another agent wrote. A native ADK YAML app keeps transferring (chat-mode sub-agents); a task-mode agent in one is refused at validation, since ADK runs its delegation outside the tool pipeline and keeps the call open across turns. - **Token usage**: every model call the framework makes is one `LLM_USAGE`, on both backends, side calls included (`generate_simple`: `summarize`'s, `purpose` `tool`; `on_session_end`'s, `memory_extraction`, outside any turn; an app's own, `side_call`, or what its caller names with `workflow/usage.py::side_call`), its counts normalized where it is made (`normalized_tokens`: `prompt_tokens` every input token, cache reads and writes included; `completion_tokens` every output token, thinking included; ADK's read by its model's provider kind, `adk_usage_event`/`adk_tokens`, since Gemini and ADK's Claude adapter keep the thinking apart from the candidates and OpenAI's count it inside, an agent of no known kind read as apart; Deep Agents' by LangChain's one convention, `langchain_tokens`; the raw log's usage records alike), and timed (`latency_ms`: on ADK from the request to the answer, `workflow/adk/call_clock.py`'s plugins marking the answer's `custom_metadata`; on Deep Agents by the turn's `RunCallback`, which marks the answer's `response_metadata["agentic_cli"]`, beside the outcome mark; a side call, a summary and the overflow retry around their own request; no adapter sends either mark). Each is recorded in its conversation's ledger (`UsageLedger`; `BaseWorkflowManager.usage`/`usage_of`, in memory for the manager's life: a backend switch's new manager starts afresh, as with `agent_runs`) where it is made, before `on_event` (the event processors, ADK's summarizer, as soon as its call answers, Deep Agents' `RunCallback`, `_report_side_call`), under the run it is made in and its conversation's turn while one runs (as the manager counts them, `/compact` and job notices included: not `SessionInfo.turns`; none in another conversation's turn or from a task its turn outlived, which `_report_side_call` reports to no one); a sub-agent run's `AGENT_RUN` end carries what it used, by model (`metadata["usage"]`, `RunRecord.usage`). The CLI's status bar sums the events it sees (the open conversation's total, on any backend); `/status` shows the ledger by agent. LangGraph (deprecated) records no ledger. - **Tool registration**: Use `@register_tool(category=..., capabilities=..., description=...)` decorator. `capabilities=` is required — pass `EXEMPT` for tools that need no permission check or a list of `Capability(name, target_arg=...)` tuples the engine matches against rules. Tools are auto-discovered via the global `ToolRegistry`. A tool in `AgentConfig.tools` that the registry did not issue is denied at every call; building the agents names it once (`tool_not_registered`, per agent and tool: `BaseWorkflowManager._name_unregistered`): a plain callable, a `FunctionTool`/`StructuredTool` judged by the function it runs (as the gates unwrap it), an app's own tool class; ADK's own tool objects excepted (a built-in runs inside the model). `outside_content=True` (or a function of the call's arguments) declares that a call brings content from outside the user and the project into the conversation (a page, a document, a program's output): once the gate allows one, a memory write in that conversation is approved per call (see Permissions); an application's tools are unmarked unless they declare it, and a variant must declare the same flag as its tool. - **Async tools never block the event loop**: a synchronous tool runs on a worker thread on both backends; an async tool runs on the event loop itself, where a blocking call (DNS, a connect, a file lock's wait, a sleep, a subprocess wait, PDF parsing, page conversion, embedding) freezes the whole app, Ctrl+C included. An async tool runs its slow work with `asyncio.to_thread`. `tests/tools/test_async_tools_never_block.py` lists every async tool (the registry's, the factories' service-bound variants, Deep Agents' skill tools), so a new one fails until it is listed, and calls each through the loop guard (`tests/loop_guard.py`). diff --git a/README.md b/README.md index 3964e5f7..75f51b9a 100644 --- a/README.md +++ b/README.md @@ -1269,7 +1269,7 @@ configs = [coordinator, researcher, analyst] | `skills` | list[str] | Agent Skills: a skill folder's absolute path, or a name under `skills_dirs` (ADK and Deep Agents; never looked up in the working directory) | | `inherit_context` | bool | What a sub-agent sees when its parent delegates to it: its task alone (`False`, the default) or its parent's conversation too (`True`); see [Sub-agent context](#sub-agent-context) (ADK and Deep Agents) | | `brief_required` | tuple[str, ...] | The brief fields a delegation to this agent must fill (default `("objective",)`; `title` and `objective` are always required): any of `deliverable`, `constraints`, `known`, `done_when`. A `task` call that leaves one empty starts no run, and its caller reads which. Not on the root | -| `limits` | AgentLimits \| None | The agent's own per-run limits (`max_model_calls`, `timeout` in seconds, `max_tokens`), laid over the app's `SubAgentPolicy.limits` field by field. Configuration: validated and kept with the agent, but no run is stopped by them. Not on the root | +| `limits` | AgentLimits \| None | The agent's own per-run limits (`max_model_calls`, `timeout` in seconds, `max_tokens`), laid over the app's `SubAgentPolicy.limits` field by field: each of its runs works under them, and one past a limit ends (see [Sub-agent context](#sub-agent-context)). Not on the root | The agent graph is validated before anything is allocated — ahead of model discovery and service creation. Duplicate names, unknown `sub_agents` @@ -1307,9 +1307,11 @@ its run's envelope as the call's result, a JSON object: "status": "completed", "partial": false, "result": "X is 42.", "error": null} ``` -`status` is `completed` (`partial` for an answer cut at its output limit), -`refused`, `failed` (`error`: the provider's reason) or `interrupted`, and -`result` is the run's last text. Only the main agent replies to the user: a +`status` is `completed` (`partial` for an answer cut at its output limit, or +one its step limit ended: `error` `step limit reached`), `refused`, `failed` +(`error`: the provider's reason), `cancelled` (`cancelled_by`: `limit`, +`parent` or `user`, and `error` why) or `interrupted`, and `result` is the +run's last text. Only the main agent replies to the user: a sub-agent's own text shows in the events box under its run's name (and is left out of fact extraction), its envelope passes the [tool result cap](#tool-results), and the next turn starts at the main agent @@ -1369,6 +1371,17 @@ reviewer = AgentConfig(name="reviewer", prompt="Check what was said.", A sub-agent's request too long for its model fails its run alike, with the warning `: the request no longer fits 's context window.`, the words its parent reads as the run's error. +- **A run's limits.** `subagents=SubAgentPolicy(...)` (given to the app, a + manager or the factory) sets every run's `limits` + (`AgentLimits(max_model_calls=100)` by default; a `timeout` in seconds and + `max_tokens` too) and the runs one turn may start (`max_runs_per_turn`, + 20, at any depth); an agent's own `limits=AgentLimits(...)` lies over the + policy's, field by field. A run's last allowed model call is told to + answer with what it has, and the run completes `partial` (`step limit + reached`); past its time or its tokens it is `cancelled` (`time limit + reached`, `token limit reached`) with the text it wrote so far, a prompt + it waited at withdrawn; a `task` call past the runs a turn may start + starts no run, and the parent reads why. - **A sub-agent's job.** A long-running tool on a sub-agent (a job starter) returns the job's id at once, and the sub-agent answers its parent in the same turn. When the job finishes, the main agent is told, in a message of @@ -1468,7 +1481,7 @@ are `AgentConfig`'s, and an unknown one is an error: | `tools` | A list of names: a registered tool's name (`web_search`, or your own), or a dotted path `my_pkg.tools.fn` to a function registered with `@register_tool` | | `mcp_servers`, `skills` | As on `AgentConfig`: MCP servers (`name`, `transport`, `command`/`args` or `url`, ...) and skill names | | `sub_agents`, `inherit_context` | The agents it may delegate to, and what a sub-agent sees: `false` (its task alone, the default) or `true` (its parent's conversation too; see [Sub-agent context](#sub-agent-context)) | -| `brief_required`, `limits` | As on `AgentConfig`: `brief_required: [objective, deliverable]`, `limits: {max_model_calls: 30, timeout: 600, max_tokens: 200000}` (each limit read as written; validated and kept, but no run is stopped by them) | +| `brief_required`, `limits` | As on `AgentConfig`: `brief_required: [objective, deliverable]`, `limits: {max_model_calls: 30, timeout: 600, max_tokens: 200000}` (each limit read as written) | | `include_state_tools` | `true` by default: the plan and task tools are added | - **A tool is a name, resolved when the manager is built.** A bare name is @@ -2368,7 +2381,7 @@ agentic-cli/ │ │ ├── service_registry.py # Unified service ContextVar for tools │ │ ├── events.py # WorkflowEvent, EventType │ │ ├── config.py # AgentConfig -│ │ ├── agents/ # Sub-agents: delegate.py (the framework's task: the brief read, the run started and ended, its envelope), brief.py, envelope.py, runs.py, policy.py, outcome.py +│ │ ├── agents/ # Sub-agents: delegate.py (the framework's task: the brief read, the run started and ended, its envelope), control.py (a run's limits, its cancel alone, steering), brief.py, envelope.py, runs.py, policy.py, outcome.py │ │ ├── settings.py # WorkflowSettingsMixin │ │ ├── retry.py # is_rate_limit_error: a provider's 429 (the provider clients retry) │ │ ├── tool_summaries.py # Tool result one-liner summaries @@ -2398,6 +2411,7 @@ agentic-cli/ │ │ │ ├── plugins.py # LLMLoggingPlugin │ │ │ ├── log_filters.py # What ADK would print over the CLI, logged at debug (installed by run()) │ │ │ ├── permission_plugin.py # PermissionPlugin (capability gating) +│ │ │ ├── run_control_plugin.py # RunControlPlugin: a sub-agent run's limits and steering at its model calls │ │ │ ├── task_progress_plugin.py # TaskProgressPlugin (deprecated, unused) │ │ │ └── tool_result_cap_plugin.py # ToolResultCapPlugin (the tool result cap) │ │ ├── deepagents/ # The Deep Agents backend (deepagents extra) From 1ad3eed00dcc9317fa5c02e171fab86a544ca0cd Mon Sep 17 00:00:00 2001 From: Andrey Shiryaev <7615137+shoom1@users.noreply.github.com> Date: Tue, 17 Nov 2026 18:16:03 -0500 Subject: [PATCH 09/15] ADK: a steered run's trimmed request keeps its task message A message steered to a sub-agent run after a tool result starts a turn of its own, so the fit guard and the overflow handler's trim could leave out everything before it, the run's task message included, and the run would go on from the steered message alone. In a sub-agent type's chain both now keep the run's task message (its invocation's user content) whatever they leave out: an inheriting run's history goes first, then the turns after the task message, and the first kept turn's opening content joins the task message after the note, as one user content. --- .../workflow/adk/fit_guard_plugin.py | 58 +++++++++++++++++-- src/agentic_cli/workflow/adk/manager.py | 6 +- .../workflow/adk/overflow_plugin.py | 9 ++- tests/workflow/adk/test_fit_guard.py | 47 +++++++++++++++ tests/workflow/test_adk_fit_guard.py | 51 ++++++++++++++++ tests/workflow/test_adk_overflow.py | 52 +++++++++++++++++ 6 files changed, 215 insertions(+), 8 deletions(-) diff --git a/src/agentic_cli/workflow/adk/fit_guard_plugin.py b/src/agentic_cli/workflow/adk/fit_guard_plugin.py index cc31e75b..0c8e320f 100644 --- a/src/agentic_cli/workflow/adk/fit_guard_plugin.py +++ b/src/agentic_cli/workflow/adk/fit_guard_plugin.py @@ -18,6 +18,12 @@ kept user content starts with a note, ``FIT_NOTE``, as a part of its own: no new message, so no provider sees one more user message in a row. The session is untouched: the next request starts from the whole history again. +- In a sub-agent run's request (``keep_task``: a sub-agent type's chain) the + run's task message, its invocation's user content, is never left out + either: a message steered to the run after a tool result starts a turn, + and the turns between the task message and the first kept one go; that + turn's opening content joins the task message, after the note, as one + user content. - It reports ``CONTEXT_TRIMMED(source="fit_guard", turns_dropped=n)`` once a turn. - When the newest turn alone is over the budget, nothing it could drop would @@ -95,14 +101,19 @@ class FitGuardPlugin(BasePlugin): here (a native ADK YAML app's whose model did not resolve) is left alone. kinds: Each agent's provider kind, by name, for its characters per token. + keep_task: Whether each request's task message (its invocation's + user content) is kept whatever is left out: a sub-agent type's + chain, whose runs each start from one. """ def __init__( - self, budgets: Mapping[str, "ContextBudget"], kinds: Mapping[str, "ProviderKind"] + self, budgets: Mapping[str, "ContextBudget"], kinds: Mapping[str, "ProviderKind"], + *, keep_task: bool = False, ) -> None: super().__init__(name="fit_guard") self._budgets = dict(budgets) self._kinds = dict(kinds) + self._keep_task = keep_task # id(a model call's EventActions) → its request as it came in. self._seen: dict[int, _Held] = {} @@ -118,7 +129,8 @@ async def before_model_callback( self._seen[id(actions)] = _Held(actions, callback_context.invocation_id, ( list(llm_request.contents), config.model_copy() if config is not None else None )) - self._fit(llm_request, agent, budget, kind) + task = callback_context.user_content if self._keep_task else None + self._fit(llm_request, agent, budget, kind, task) llm_request.contents = fold_summary(llm_request.contents) return None @@ -166,15 +178,18 @@ def _release(self, callback_context: "CallbackContext") -> None: def _fit( self, llm_request: "LlmRequest", agent: str, budget: "ContextBudget", - kind: "ProviderKind", + kind: "ProviderKind", task: types.Content | None = None, ) -> None: - """Leave the oldest turns out of ``llm_request`` when it is over the budget.""" + """Leave the oldest turns out of ``llm_request`` when it is over the budget. + + ``task``, a sub-agent run's task message, is never left out. + """ estimate = estimate_request_tokens(llm_request, kind) if estimate <= budget.budget: return overhead = overhead_tokens(llm_request, kind) contents, dropped = drop_turns( - llm_request.contents, target_tokens=budget.trigger - overhead, kind=kind + llm_request.contents, target_tokens=budget.trigger - overhead, kind=kind, task=task ) if not dropped or overhead + _tokens(_contents_chars(contents), kind) > budget.budget: # The newest turn alone is over: the overflow handler answers. @@ -236,7 +251,8 @@ def fold_summary(contents: list[types.Content]) -> list[types.Content]: def drop_turns( - contents: list[types.Content], *, target_tokens: float, kind: "ProviderKind" + contents: list[types.Content], *, target_tokens: float, kind: "ProviderKind", + task: types.Content | None = None, ) -> tuple[list[types.Content], int]: """``contents`` without their oldest whole turns, under ``target_tokens`` if it can be. @@ -248,6 +264,12 @@ def drop_turns( the conversation. The first kept user content gets ``FIT_NOTE`` as a part before its own; ``contents`` themselves are left as they are. + ``task`` is a sub-agent run's task message (its invocation's user + content), which stays too: a message steered to the run after a tool + result starts a turn, and once the turns go past the task message, the + first kept one's opening content joins it, after the note, as one user + content. An inheriting run's history before it goes first. + Each content is measured once; what goes is subtracted from a running sum. @@ -260,6 +282,7 @@ def drop_turns( starts = [i for i in range(len(body)) if _starts_turn(body, i)] if not starts or starts[-1] == 0: return contents, 0 + kept = _task_at(body, task) sizes = [len(content.model_dump_json(exclude_none=True)) for content in contents] remaining = sum(sizes) + _NOTE_CHARS sizes = sizes[len(head):] @@ -268,9 +291,13 @@ def drop_turns( previous = 0 for dropped, cut in enumerate(cuts, start=1): remaining -= sum(sizes[previous:cut]) + if kept is not None and previous <= kept < cut: + remaining += sizes[kept] # the task message stays previous = cut if _tokens(remaining, kind) < target_tokens: break + if kept is not None and kept < cut: + return [*head, _joined(body[kept], body[cut]), *body[cut + 1:]], dropped return [*head, _noted(body[cut]), *body[cut + 1:]], dropped @@ -302,6 +329,25 @@ def _noted(content: types.Content) -> types.Content: *(content.parts or [])]}) +def _joined(task: types.Content, content: types.Content) -> types.Content: + """``content`` after ``task`` and ``FIT_NOTE``, as one user content.""" + return content.model_copy(update={"parts": [*(task.parts or []), + types.Part.from_text(text=FIT_NOTE), + *(content.parts or [])]}) + + +def _task_at(contents: list[types.Content], task: types.Content | None) -> int | None: + """Where ``task`` (a run's task message) is in ``contents``: the last user + content with its parts; None for none.""" + if task is None: + return None + found = [ + i for i, content in enumerate(contents) + if content.role == "user" and content.parts == task.parts + ] + return found[-1] if found else None + + def _starts_turn(contents: list[types.Content], i: int) -> bool: if not _users_text(contents[i]): return False diff --git a/src/agentic_cli/workflow/adk/manager.py b/src/agentic_cli/workflow/adk/manager.py index f67233ac..cdcceb1b 100644 --- a/src/agentic_cli/workflow/adk/manager.py +++ b/src/agentic_cli/workflow/adk/manager.py @@ -768,7 +768,10 @@ def _chain( from agentic_cli.workflow.adk.memory_index_plugin import MemoryIndexPlugin plugins.append(MemoryIndexPlugin(root=root, index_for=self._memory_index_now)) - fit_guard = FitGuardPlugin(self._budgets, kinds) + # A sub-agent type's chain (no main agent): a run's task message is + # never trimmed, whatever was steered to it after. + keep_task = root is None + fit_guard = FitGuardPlugin(self._budgets, kinds, keep_task=keep_task) plugins.append(OverflowPlugin( root=root, reply_agents=replies, @@ -777,6 +780,7 @@ def _chain( models=self._agent_model_refs(), summarize_now=self._summarize_now, fit_guard=fit_guard, + keep_task=keep_task, )) plugins.append(fit_guard) if self._llm_logging_plugin is not None: diff --git a/src/agentic_cli/workflow/adk/overflow_plugin.py b/src/agentic_cli/workflow/adk/overflow_plugin.py index a4da13dc..c0be77c5 100644 --- a/src/agentic_cli/workflow/adk/overflow_plugin.py +++ b/src/agentic_cli/workflow/adk/overflow_plugin.py @@ -17,7 +17,8 @@ main agent) never summarizes; nor does the main agent when the summary covers nothing the request holds. The request is then retried with its oldest whole turns left out down to half the budget - (``fit_guard_plugin.drop_turns``). + (``fit_guard_plugin.drop_turns``); a sub-agent run's task message, its + invocation's user content, is never among them (``keep_task``). - The retry is built from the request as the fit guard saw it (``FitGuardPlugin.request_as_seen``, this call's own copy, never a parallel call's), without the model's context cache: a model's adapter may have @@ -124,6 +125,9 @@ class OverflowPlugin(BasePlugin): when nothing was summarized; raises when the summary failed. fit_guard: The app's fit guard, whose copy of each request a retry is built from; without one, the request the callback is given. + keep_task: Whether a trimmed retry keeps its task message (its + invocation's user content) whatever it leaves out: a sub-agent + type's chain, whose runs each start from one. """ def __init__( @@ -136,8 +140,10 @@ def __init__( models: Mapping[str, str], summarize_now: Callable[["CallbackContext"], Awaitable["WrittenSummary | None"]], fit_guard: "FitGuardPlugin | None" = None, + keep_task: bool = False, ) -> None: super().__init__(name=OVERFLOW_PLUGIN) + self._keep_task = keep_task self._root = root # The agents whose overflow is the turn's clear error. self._replying = frozenset({*reply_agents, *([root] if root is not None else [])}) @@ -170,6 +176,7 @@ async def on_model_error_callback( request.contents, target_tokens=budget.budget // 2 - overhead_tokens(request, kind), kind=kind, + task=callback_context.user_content if self._keep_task else None, ) if not dropped: return self._does_not_fit(agent) diff --git a/tests/workflow/adk/test_fit_guard.py b/tests/workflow/adk/test_fit_guard.py index 64ced33f..716614d9 100644 --- a/tests/workflow/adk/test_fit_guard.py +++ b/tests/workflow/adk/test_fit_guard.py @@ -169,6 +169,53 @@ def test_one_turn_is_nothing_to_drop(self): assert (kept, dropped) == (contents, 0) +class TestASubAgentRunsTaskMessage: + """A sub-agent run's task message (``task=``, its invocation's user + content) is never left out: a message steered to the run after a tool + result starts a turn, and the turns between them go, never the task.""" + + TASK = "# Task: Find X.\n\n## Objective\nFind X." + + def test_the_turns_after_it_go_and_the_rest_joins_it(self): + task = user(self.TASK) + contents = [task, call("lookup", "c1"), result("lookup", "c1", page=LONG), + user("Also find Z."), call("lookup", "c2"), result("lookup", "c2", z=42)] + + kept, dropped = drop_turns(contents, target_tokens=0, kind=CLAUDE, task=task) + + assert dropped == 1 + # One user content: no provider sees two user messages in a row. + assert [part.text for part in kept[0].parts] == [self.TASK, FIT_NOTE, "Also find Z."] + assert kept[1:] == contents[4:] + + def test_an_inheriting_runs_history_goes_first(self): + task = user(self.TASK) + contents = [user(LONG), model("A1."), task, call("lookup", "c1"), + result("lookup", "c1", page=LONG), user("Also find Z."), + call("lookup", "c2"), result("lookup", "c2", z=42)] + + kept, dropped = drop_turns( + contents, target_tokens=tokens(contents[2:]) + NOTE_ROOM, kind=CLAUDE, task=task + ) + all_but, every = drop_turns(contents, target_tokens=0, kind=CLAUDE, task=task) + + assert dropped == 1 + assert [part.text for part in kept[0].parts] == [FIT_NOTE, self.TASK] + assert kept[1:] == contents[3:] + assert every == 2 + assert [part.text for part in all_but[0].parts] == [self.TASK, FIT_NOTE, "Also find Z."] + assert all_but[1:] == contents[6:] + + def test_without_it_the_oldest_turn_goes_whatever_it_is(self): + contents = [user(self.TASK), call("lookup", "c1"), result("lookup", "c1", page=LONG), + user("Also find Z.")] + + kept, dropped = drop_turns(contents, target_tokens=0, kind=CLAUDE) + + assert dropped == 1 + assert [part.text for part in kept[0].parts] == [FIT_NOTE, "Also find Z."] + + class TestFoldSummary: """A summarized conversation opens with the summary, a user content of its own: folded into the next user's text, no provider sees two user messages diff --git a/tests/workflow/test_adk_fit_guard.py b/tests/workflow/test_adk_fit_guard.py index 3efe0f01..b6e97513 100644 --- a/tests/workflow/test_adk_fit_guard.py +++ b/tests/workflow/test_adk_fit_guard.py @@ -24,10 +24,14 @@ pytest.importorskip("google.adk") from agentic_cli.config import BaseSettings # noqa: E402 +from agentic_cli.tools.registry import register_tool # noqa: E402 from agentic_cli.workflow.adk.fit_guard_plugin import FIT_NOTE, FitGuardPlugin # noqa: E402 from agentic_cli.workflow.adk.manager import GoogleADKWorkflowManager # noqa: E402 from agentic_cli.workflow.config import AgentConfig # noqa: E402 from agentic_cli.workflow.events import EventType # noqa: E402 +from agentic_cli.workflow.permissions import EXEMPT # noqa: E402 +from agentic_cli.workflow.service_registry import WORKFLOW, get_service # noqa: E402 +from agentic_cli.workflow.sessions import get_active_run # noqa: E402 from agentic_cli.workflow.summary_prompt import SUMMARY_PREFIX # noqa: E402 from tests.workflow.adk.fakes import FakeAPI, anthropic_message, chat_completion # noqa: E402 from tests.workflow.test_adk_context_cache import route_gemini # noqa: E402 @@ -236,6 +240,53 @@ def says(text: str, prompt_tokens: int = 100) -> dict: assert budget.budget == 19_000 +@register_tool(capabilities=EXEMPT, description="Read a long page and steer this run (a test tool).") +async def fit_guard_steered_read() -> dict: + """A long page; and a message steered to the run that read it, as its parent would.""" + get_service(WORKFLOW)._delegations.control(get_active_run()).steer("Also find Z.") + return {"success": True, "page": HUGE} + + +class TestASteeredSubAgent: + async def test_its_trimmed_request_keeps_its_task_message(self, project, monkeypatch): + """A message steered to a run after a long tool result starts a turn of + its own: over the run's budget, its next request leaves out the result, + never the task message before it, which the rest joins.""" + delegate = anthropic_message({"type": "tool_use", "id": "toolu_c1", "name": "task", + "input": {"agent_type": "researcher", "title": "Find X.", + "objective": "Find X."}}) + delegate["stop_reason"] = "tool_use" + coordinator = [delegate, anthropic_message({"type": "text", "text": "X is 42."})] + route(monkeypatch, anthropic, "AsyncAnthropic", FakeAPI(lambda request: coordinator.pop(0))) + server = serve(monkeypatch, Server(answered("", tool="fit_guard_steered_read"), + answered("X is 42; Z is 42."))) + manager = GoogleADKWorkflowManager( + agent_configs=[ + AgentConfig(name="coordinator", prompt="You coordinate.", + sub_agents=["researcher"], description="Leads.", + include_state_tools=False), + AgentConfig(name="researcher", prompt="You research.", description="Finds.", + model="local:small", tools=[fit_guard_steered_read], + include_state_tools=False), + ], + settings=BaseSettings(session_store="memory", model_providers=ENDPOINTS, + models=MODELS, default_model="claude-sonnet-4-6", + tool_result_max_chars=200_000), + ) + try: + events = await turn(manager, "Find X, please.") + finally: + await manager.cleanup() + + _, steered = server.bodies + sent = json.dumps(steered) + assert "word word word" not in sent # the long page went + assert "# Task: Find X." in sent + assert sent.index("# Task: Find X.") < sent.index(FIT_NOTE) < sent.index("Also find Z.") + (trimmed,) = trims(events) + assert (trimmed.metadata["agent"], trimmed.metadata["turns_dropped"]) == ("researcher", 1) + + # --- a switch to a smaller window after a summary (Review Focus 3) --------------------------- diff --git a/tests/workflow/test_adk_overflow.py b/tests/workflow/test_adk_overflow.py index d63ee04c..ac1286b1 100644 --- a/tests/workflow/test_adk_overflow.py +++ b/tests/workflow/test_adk_overflow.py @@ -43,6 +43,7 @@ from agentic_cli.config import BaseSettings # noqa: E402 from agentic_cli.models import ProviderKind # noqa: E402 +from agentic_cli.tools.registry import register_tool # noqa: E402 from agentic_cli.workflow.adk.fit_guard_plugin import FIT_NOTE # noqa: E402 from agentic_cli.workflow.adk.manager import GoogleADKWorkflowManager # noqa: E402 from agentic_cli.workflow.config import AgentConfig # noqa: E402 @@ -53,6 +54,9 @@ subagent_overflow_message, ) from agentic_cli.workflow.events import EventType # noqa: E402 +from agentic_cli.workflow.permissions import EXEMPT # noqa: E402 +from agentic_cli.workflow.service_registry import WORKFLOW, get_service # noqa: E402 +from agentic_cli.workflow.sessions import get_active_run # noqa: E402 from agentic_cli.workflow.summary_prompt import SUMMARY_PREFIX # noqa: E402 from tests.models.fakes import openrouter_spec # noqa: E402 from tests.workflow.adk.fakes import ( # noqa: E402 @@ -812,6 +816,54 @@ async def test_an_inheriting_ones_second_overflow_is_still_one_warning( assert texts(events)[-1] == "It could not." +@register_tool(capabilities=EXEMPT, description="Look X up and steer this run (a test tool).") +async def overflow_steered_lookup() -> dict: + """A long finding; and a message steered to the run that looked, as its parent would.""" + get_service(WORKFLOW)._delegations.control(get_active_run()).steer("Also find Z.") + return {"success": True, "found": LONG} + + +class TestASteeredSubAgentsOverflow: + async def test_its_retry_keeps_its_task_message(self, project, monkeypatch): + """A message steered to a run after a tool result starts a turn of its + own: the retry of its refused request leaves out the turns before + it, never the task message, which the rest joins.""" + _, status, body = SHAPES["claude-400"] + monkeypatch.setenv("ANTHROPIC_API_KEY", "test-key") + looks = claude_says("") + looks["content"] = [{"type": "tool_use", "id": "toolu_r1", + "name": "overflow_steered_lookup", "input": {}}] + looks["stop_reason"] = "tool_use" + api = Team(coordinator=[delegate(), claude_says("X is 42.")], + researcher=[looks, httpx.Response(status, json=body), + claude_says("X is 42; Z is 42.")]) + route(monkeypatch, anthropic, "AsyncAnthropic", api) + manager = GoogleADKWorkflowManager( + agent_configs=[ + AgentConfig(name="coordinator", prompt="You coordinate.", + sub_agents=["researcher"], description="Leads.", + include_state_tools=False), + AgentConfig(name="researcher", prompt="You research.", + description="Finds facts.", tools=[overflow_steered_lookup], + include_state_tools=False), + ], + settings=BaseSettings(session_store="memory", default_model="claude-sonnet-4-6", + prompt_caching_enabled=False), + ) + try: + events = await turn(manager, "Find X, please.") + finally: + await manager.cleanup() + + refused, retry = (r.content.decode() for r in api.requests[2:4]) + assert "word word" in refused and "Also find Z." in refused + assert "word word" not in retry + assert "# Task: Find X." in retry + assert retry.index("# Task: Find X.") < retry.index(FIT_NOTE) < retry.index("Also find Z.") + assert errors(events) == [] + assert texts(events)[-1] == "X is 42." + + async def test_the_handler_comes_before_the_fit_guard(project, monkeypatch): monkeypatch.setenv("ANTHROPIC_API_KEY", "test-key") manager = GoogleADKWorkflowManager( From b497c2724e55dcbb51839431fcbf61634b622ade Mon Sep 17 00:00:00 2001 From: Andrey Shiryaev <7615137+shoom1@users.noreply.github.com> Date: Tue, 17 Nov 2026 18:18:04 -0500 Subject: [PATCH 10/15] ADK: a steered message is stored before the answer it prompted ADK stamps a model call's answer before the call's callbacks run, so the message RunControlPlugin appends to a run's child session in before_model_callback was newer than the answer that followed it, and a durable store, which reads a session's events back by time, put it after that answer, between a call and its result. The plugin now stamps each event of the run from a steer on just after the steered message (two microseconds, past what the store keeps of a time), and lets go of its record as the run ends. --- .../workflow/adk/run_control_plugin.py | 61 +++++++++++++++--- tests/workflow/adk/test_child_sessions.py | 63 +++++++++++++++++++ 2 files changed, 116 insertions(+), 8 deletions(-) diff --git a/src/agentic_cli/workflow/adk/run_control_plugin.py b/src/agentic_cli/workflow/adk/run_control_plugin.py index ddfdfa71..00414074 100644 --- a/src/agentic_cli/workflow/adk/run_control_plugin.py +++ b/src/agentic_cli/workflow/adk/run_control_plugin.py @@ -9,7 +9,11 @@ event appended to the run's child session (through the callback context's session service: the invocation's own session, which a session loaded apart would fail ADK's revision check on) and a user content added - to the request, so they stay in its transcript; + to the request, so they stay in its transcript. ADK stamps the call's + answer before this callback runs, so each event of the run from then on + that is not later than the steered message is stamped just after it + (``on_event_callback``): a durable store reads a session's events back by + time, and would put the message after the answer it prompted; - the call is counted (``RunControl.model_call``), and the run's last allowed one gets ``STEP_LIMIT_NOTE`` after its last message, in the request only: as a part of the last content when that is the user's (a @@ -25,8 +29,10 @@ alone keeps an empty text, which ADK takes as the run's last answer (``MODEL_RETURNED_NO_CONTENT``, no failure for a run). -It changes the request and the answer in place and returns None, as -``ForeignReasoningPlugin`` does, so every plugin after it still runs. It sits +It changes the request, the answer and an event's time in place and +returns None, as ``ForeignReasoningPlugin`` does, so every plugin after it +still runs; what it keeps is kept by invocation, and let go of as the run +ends (two runs of one type share their runner, and this plugin). It sits before ``SubAgentOutcomePlugin``, which then reads an answer whose calls were dropped as the run's final one. The root's calls (no active run) and a run without a control are left alone. @@ -46,11 +52,17 @@ if TYPE_CHECKING: from google.adk.agents.callback_context import CallbackContext + from google.adk.agents.invocation_context import InvocationContext from google.adk.models.llm_request import LlmRequest from google.adk.models.llm_response import LlmResponse from agentic_cli.workflow.agents.control import RunControl +#: How much later than a steered message the run's next events are stamped, +#: at least: past what a durable store keeps of a time (``DatabaseSessionService`` +#: keeps microseconds), so it reads them back in the order they came. +_STAMP_STEP = 2e-6 + class RunControlPlugin(BasePlugin): """A sub-agent run's limits at its model calls (see the module docstring). @@ -66,6 +78,9 @@ def __init__(self, control: Callable[[], RunControl | None], kind: str | None) - super().__init__(name="run_control") self._control = control self._kind = kind + # Each invocation's last steered message's time, or the latest of + # its events stamped since: its next events come after it. + self._stamped: dict[str, float] = {} async def before_model_callback( self, *, callback_context: CallbackContext, llm_request: LlmRequest @@ -75,7 +90,9 @@ async def before_model_callback( return None steered = control.take_steering() if steered: - await _steer(callback_context, llm_request, steered) + self._stamped[callback_context.invocation_id] = await _steer( + callback_context, llm_request, steered + ) if control.model_call(): llm_request.contents = with_note(list(llm_request.contents or []), STEP_LIMIT_NOTE) return None @@ -95,19 +112,47 @@ async def after_model_callback( drop_calls(llm_response) return None + async def on_event_callback( + self, *, invocation_context: InvocationContext, event: Event + ) -> Optional[Event]: + # An event ADK stamped before a message was steered (the answer to + # the call it was steered at) is stamped after it. + last = self._stamped.get(event.invocation_id) + if last is None: + return None + if event.timestamp < last + _STAMP_STEP: + event.timestamp = last + _STAMP_STEP + self._stamped[event.invocation_id] = event.timestamp + return None + + async def after_run_callback(self, *, invocation_context: InvocationContext) -> None: + self._stamped.pop(invocation_context.invocation_id, None) + return None + + async def on_run_error_callback( + self, *, invocation_context: InvocationContext, error: Exception + ) -> None: + self._stamped.pop(invocation_context.invocation_id, None) + return None + async def _steer( callback_context: CallbackContext, llm_request: LlmRequest, messages: list[str] -) -> None: - """``messages``, as the user's, in the run's child session and after the request's last content.""" +) -> float: + """``messages``, as the user's, in the run's child session and after the + request's last content; the time the last one is stamped with.""" service = callback_context.get_invocation_context().session_service session = callback_context.session + stamped = 0.0 for message in messages: content = types.Content(role="user", parts=[types.Part.from_text(text=message)]) - await service.append_event(session, Event( + event = Event( invocation_id=callback_context.invocation_id, author="user", content=content, - )) + ) + await service.append_event(session, event) llm_request.contents.append(content) + stamped = event.timestamp + return stamped def with_note(contents: list[types.Content], note: str) -> list[types.Content]: diff --git a/tests/workflow/adk/test_child_sessions.py b/tests/workflow/adk/test_child_sessions.py index 33e2c267..5042a646 100644 --- a/tests/workflow/adk/test_child_sessions.py +++ b/tests/workflow/adk/test_child_sessions.py @@ -17,6 +17,8 @@ - A model switch between turns rebuilds the runners and keeps the transcripts, the records and the numbering. - No child session lists, or is found, as a conversation. +- A message steered to a run is stored where the run read it: after the + tool result before it, before the answer it prompted, on every store. Turns run the real manager on ``FakeAPI`` (Claude), on the memory store and on sqlite. @@ -37,14 +39,19 @@ from google.genai import types # noqa: E402 from agentic_cli.config import BaseSettings # noqa: E402 +from agentic_cli.tools.registry import register_tool # noqa: E402 from agentic_cli.workflow.adk import sessions as adk_sessions # noqa: E402 from agentic_cli.workflow.adk.manager import GoogleADKWorkflowManager # noqa: E402 from agentic_cli.workflow.adk.sessions import child_app # noqa: E402 +from agentic_cli.workflow.permissions import EXEMPT # noqa: E402 +from agentic_cli.workflow.service_registry import WORKFLOW, get_service # noqa: E402 +from agentic_cli.workflow.sessions import get_active_run # noqa: E402 from agentic_cli.workflow.session_readers import open_session_reader # noqa: E402 from tests.loop_guard import no_blocking_calls # noqa: E402 from tests.workflow.adk.fakes import FakeAPI # noqa: E402 from tests.workflow.test_adk_delegation import ( # noqa: E402,F401 Team, + calls, delegation, project, route, @@ -488,3 +495,59 @@ async def test_no_reader_or_look_shows_one(self, project, monkeypatch): assert [row.session_id for row in listed] == ["s"] assert (info, exists) == (None, False) assert [(row.session_id, row.backend) for row in read] == [("s", "adk")] + + +@register_tool(capabilities=EXEMPT, description="Hold, and steer this run (a test tool).") +async def child_sessions_steered_hold() -> dict: + """A message steered to the run that called it, as its parent would, while it works.""" + get_service(WORKFLOW)._delegations.control(get_active_run()).steer("Also find Z.") + return {"success": True} + + +def what_happened(session) -> list[str]: + """Each of a session's events, as what it holds: a text, a call, a result.""" + told: list[str] = [] + for event in session.events: + for part in (event.content.parts if event.content is not None else ()) or (): + if part.function_call: + told.append(f"{event.author}: call {part.function_call.name}") + elif part.function_response: + told.append(f"{event.author}: result {part.function_response.name}") + elif part.text: + told.append(f"{event.author}: {part.text.splitlines()[0]}") + return told + + +class TestASteeredMessage: + @pytest.mark.parametrize("store", ["memory", "sqlite"]) + async def test_it_is_stored_between_the_result_and_the_answer_it_prompted( + self, project, monkeypatch, store + ): + """ADK stamps a model call's answer before the call's callbacks run, + so the message steered there was newer than the answer it prompted: + a durable store, which orders a session's events by time, read it + back after that answer.""" + route(monkeypatch, anthropic, "AsyncAnthropic", FakeAPI(Team( + coordinator=[delegation("toolu_c1"), says("Done.")], + researcher=[calls("child_sessions_steered_hold", "toolu_r1"), + says("X is 42; Z is 42.")], + ))) + manager = GoogleADKWorkflowManager( + agent_configs=team(researcher_tools=(child_sessions_steered_hold,)), + settings=BaseSettings( + session_store=store, default_model="claude-sonnet-4-6", default_user="u" + ), + ) + try: + await say(manager, "Find X.") + stored = await child(manager, "researcher-1") + finally: + await manager.cleanup() + + assert what_happened(stored) == [ + "user: # Task: Find X", + "researcher: call child_sessions_steered_hold", + "researcher: result child_sessions_steered_hold", + "user: Also find Z.", + "researcher: X is 42; Z is 42.", + ] From 568ef950be0dbe2128c8447180c7337303487ec9 Mon Sep 17 00:00:00 2001 From: Andrey Shiryaev <7615137+shoom1@users.noreply.github.com> Date: Tue, 17 Nov 2026 18:20:17 -0500 Subject: [PATCH 11/15] Sub-agents: a finishing answer past max_tokens completes its run An answer that crossed a run's max_tokens ended the run cancelled by its limit even when it made no tool call, so the run was ending anyway, and its parent read a failure and might redo finished work. RunControl.used now takes calls= (whether the answer makes tool calls, True when not said): only an answer past the limit that would go on is the run's last, cancelled by its limit, its calls dropped; one that makes none ends the run completed, its result whole. The tokens are counted either way. Both backends pass whether the answer makes calls. --- .../workflow/adk/run_control_plugin.py | 16 ++++++++-- src/agentic_cli/workflow/agents/control.py | 30 +++++++++++-------- .../workflow/deepagents/middleware.py | 14 ++++++--- tests/workflow/adk/test_run_control_plugin.py | 15 ++++++++++ .../deepagents/test_run_control_middleware.py | 24 +++++++++++++++ tests/workflow/test_agent_control.py | 14 +++++++++ tests/workflow/test_agent_delegate.py | 15 ++++++++++ tests/workflow/test_subagents_contract.py | 27 +++++++++++++++-- 8 files changed, 134 insertions(+), 21 deletions(-) diff --git a/src/agentic_cli/workflow/adk/run_control_plugin.py b/src/agentic_cli/workflow/adk/run_control_plugin.py index 00414074..1112da29 100644 --- a/src/agentic_cli/workflow/adk/run_control_plugin.py +++ b/src/agentic_cli/workflow/adk/run_control_plugin.py @@ -22,9 +22,13 @@ request whose messages hold tool calls or results when it defines no tools, and no call that answer makes is run (below); - after each, what it used (``workflow/usage.py::adk_tokens``, by its - model's provider kind) goes to ``RunControl.used``; + model's provider kind) goes to ``RunControl.used``, with whether the + answer makes function calls: one past the token limit that makes none + is the run's result, whole. A model that reports no usage is not limited + by tokens; - on the run's last call (``RunControl.final_call``: its step limit's, or - one past its token limit) the answer's function calls are dropped, so ADK + one past its token limit that makes calls) the answer's function calls + are dropped, so ADK runs none and the run ends with that answer; an answer that was calls alone keeps an empty text, which ADK takes as the run's last answer (``MODEL_RETURNED_NO_CONTENT``, no failure for a run). @@ -107,7 +111,7 @@ async def after_model_callback( return None if llm_response.usage_metadata is not None: tokens = adk_tokens(llm_response.usage_metadata, self._kind) - control.used(tokens.input, tokens.output) + control.used(tokens.input, tokens.output, calls=_calls(llm_response)) if control.final_call: drop_calls(llm_response) return None @@ -169,6 +173,12 @@ def with_note(contents: list[types.Content], note: str) -> list[types.Content]: return [*contents, types.Content(role="user", parts=[text])] +def _calls(llm_response: Any) -> bool: + """Whether ``llm_response`` makes function calls: the run would go on past it.""" + content = llm_response.content + return content is not None and any(part.function_call for part in content.parts or ()) + + def drop_calls(llm_response: Any) -> None: """Drop ``llm_response``'s function calls, in place: it is the run's last answer. diff --git a/src/agentic_cli/workflow/agents/control.py b/src/agentic_cli/workflow/agents/control.py index c607ad47..86d3106f 100644 --- a/src/agentic_cli/workflow/agents/control.py +++ b/src/agentic_cli/workflow/agents/control.py @@ -16,11 +16,13 @@ - The limits checked at the run's model calls: before each, ``model_call`` counts it and says whether it is the last allowed (``max_model_calls``), whose request ends with ``STEP_LIMIT_NOTE``; after each, ``used`` counts - its tokens, and past ``max_tokens`` the run is cancelled by its limit at - that answer. On the call that is the run's last (``final_call``) the - backend drops the answer's tool calls, so the run ends with that answer: - no call past a limit is made, and nothing the model asked for runs after - it. + its tokens, and an answer past ``max_tokens`` that asks for tools (the + run would go on) has the run cancelled by its limit at that answer; one + that asks for none ends the run as it would, its result. On the call that + is the run's last (``final_call``) the backend drops the answer's tool + calls, so the run ends with that answer: no call past a limit is made, + and nothing the model asked for runs after it. A model that reports no + usage is not limited by tokens. - ``steer(message)`` gives the run a message, which its next model call (``take_steering``) adds after its last message, as a user's. @@ -161,18 +163,22 @@ def model_call(self) -> bool: self._final = self.at_step_limit return self._final - def used(self, input_tokens: int, output_tokens: int) -> None: + def used(self, input_tokens: int, output_tokens: int, *, calls: bool = True) -> None: """Count what one of the run's model calls used, as ``workflow/usage.py`` counts it. - Past ``max_tokens`` the run is cancelled by its limit at this answer: - ``cancelled`` is set and the answer is the run's last - (``final_call``), so it ends with it rather than losing it. + Past ``max_tokens``, an answer that makes tool calls (``calls``: the + run would go on past it) is the run's last, cancelled by its limit: + ``cancelled`` is set and the call is the run's last + (``final_call``), so it ends with that answer rather than losing it. + An answer that makes none ends the run anyway: it is its result, + whole, and nothing is cancelled. Its tokens are counted either way. """ self._tokens += input_tokens + output_tokens limit = self.limits.max_tokens - if limit is not None and self._tokens > limit and self.cancelled is None: - self.cancelled = (LIMIT, TOKEN_LIMIT_ERROR) - self._final = True + if limit is None or self._tokens <= limit or self.cancelled is not None or not calls: + return + self.cancelled = (LIMIT, TOKEN_LIMIT_ERROR) + self._final = True @property def at_step_limit(self) -> bool: diff --git a/src/agentic_cli/workflow/deepagents/middleware.py b/src/agentic_cli/workflow/deepagents/middleware.py index bb1a97a8..1ab8f3f3 100644 --- a/src/agentic_cli/workflow/deepagents/middleware.py +++ b/src/agentic_cli/workflow/deepagents/middleware.py @@ -912,10 +912,13 @@ class RunControlMiddleware(AgentMiddleware): Claude refuses a request whose messages hold tool calls or results when it defines no tools, and no call that answer makes is run (below); - after each, what it used (``workflow/usage.py::langchain_tokens``) goes - to ``RunControl.used``; + to ``RunControl.used``, with whether the answer makes tool calls: one + past the token limit that makes none is the run's result, whole. A + model that reports no usage counts none, so it is not limited by + tokens; - on the run's last call (``RunControl.final_call``: its step limit's, - or one past its token limit) the answer's tool calls are dropped - (``without_calls``), so the agent ends with that answer. + or one past its token limit that makes calls) the answer's tool calls + are dropped (``without_calls``), so the agent ends with that answer. The summarization inside it counts the note; the outcome middleware outside it reads an answer whose calls were dropped as the run's final @@ -954,7 +957,10 @@ async def awrap_model_call( response = await handler(request) for answer in _answers(response): tokens = langchain_tokens(answer.usage_metadata) - control.used(tokens.input, tokens.output) + control.used( + tokens.input, tokens.output, + calls=bool(answer.tool_calls or answer.invalid_tool_calls), + ) if control.final_call: response = _mapped(response, without_calls) return response diff --git a/tests/workflow/adk/test_run_control_plugin.py b/tests/workflow/adk/test_run_control_plugin.py index dc843091..8f5e5e1d 100644 --- a/tests/workflow/adk/test_run_control_plugin.py +++ b/tests/workflow/adk/test_run_control_plugin.py @@ -119,6 +119,21 @@ async def test_a_call_past_the_token_limit_is_the_runs_last(self): assert control.cancelled == ("limit", TOKEN_LIMIT_ERROR) assert answer.content == model(text("Found it.")) + async def test_a_finishing_answer_past_the_token_limit_is_left_as_it_is(self): + control = RunControl(REF, AgentLimits(max_tokens=100)) + plugin = RunControlPlugin(lambda: control, "anthropic") + usage = types.GenerateContentResponseUsageMetadata( + prompt_token_count=90, candidates_token_count=20 + ) + content = model(text("Found it.")) + answer = LlmResponse(content=content, usage_metadata=usage) + + await plugin.before_model_callback(callback_context=None, llm_request=LlmRequest()) + await plugin.after_model_callback(callback_context=None, llm_response=answer) + + assert (control.cancelled, control.final_call) == (None, False) + assert answer.content is content + async def test_a_partial_answer_counts_nothing(self): control = RunControl(REF, AgentLimits(max_tokens=1)) plugin = RunControlPlugin(lambda: control, "anthropic") diff --git a/tests/workflow/deepagents/test_run_control_middleware.py b/tests/workflow/deepagents/test_run_control_middleware.py index 8fde1f9f..61ec3148 100644 --- a/tests/workflow/deepagents/test_run_control_middleware.py +++ b/tests/workflow/deepagents/test_run_control_middleware.py @@ -16,6 +16,7 @@ from langchain_core.messages import AIMessage, HumanMessage, ToolMessage # noqa: E402 from agentic_cli.workflow.agents.control import STEP_LIMIT_NOTE, RunControl # noqa: E402 +from agentic_cli.workflow.agents.envelope import TOKEN_LIMIT_ERROR # noqa: E402 from agentic_cli.workflow.agents.policy import AgentLimits # noqa: E402 from agentic_cli.workflow.deepagents.middleware import ( # noqa: E402 RunControlMiddleware, @@ -83,6 +84,29 @@ async def handler(request): assert await middleware.awrap_model_call("the request", handler) is answer +REF = RunRef(agent="researcher", instance="researcher-1", run="researcher-1#1", + parent_run=None, depth=1) +USAGE = {"input_tokens": 90, "output_tokens": 20, "total_tokens": 110} + + +@pytest.mark.parametrize("calls", [True, False]) +async def test_an_answer_past_the_token_limit_is_the_last_only_when_it_would_go_on(calls): + control = RunControl(REF, AgentLimits(max_tokens=100)) + middleware = RunControlMiddleware(lambda: SimpleNamespace(control=lambda run: control)) + answer = AIMessage("Found it.", tool_calls=[CALL] if calls else [], usage_metadata=USAGE) + + async def handler(request): + return answer + + kept = await middleware.awrap_model_call("the request", handler) + + if calls: + assert control.cancelled == ("limit", TOKEN_LIMIT_ERROR) + assert (kept.content, kept.tool_calls) == ("Found it.", []) + else: + assert (control.cancelled, kept) == (None, answer) + + async def test_the_messages_steered_since_the_last_call_join_the_runs_state(): ref = RunRef(agent="researcher", instance="researcher-1", run="researcher-1#1", parent_run=None, depth=1) diff --git a/tests/workflow/test_agent_control.py b/tests/workflow/test_agent_control.py index 411b6c95..24c9aede 100644 --- a/tests/workflow/test_agent_control.py +++ b/tests/workflow/test_agent_control.py @@ -249,6 +249,20 @@ def test_without_a_limit_any_number_is_fine(self): assert made.cancelled is None + async def test_an_answer_past_it_that_makes_no_call_ends_the_run_as_it_would(self): + made = control(max_tokens=100) + task, _ = await a_run(made) + + made.used(60, 20) + made.used(30, 10, calls=False) + + # It is the run's last answer anyway: its result, whole. + assert (made.cancelled, made.final_call) == (None, False) + # Counted all the same: an answer past it that would go on is the last. + made.used(1, 1) + assert (made.cancelled, made.final_call) == (("limit", TOKEN_LIMIT_ERROR), True) + task.cancel() + class TestSteering: def test_messages_are_taken_oldest_first_once(self): diff --git a/tests/workflow/test_agent_delegate.py b/tests/workflow/test_agent_delegate.py index 015a24c6..2b2736d8 100644 --- a/tests/workflow/test_agent_delegate.py +++ b/tests/workflow/test_agent_delegate.py @@ -919,6 +919,21 @@ async def hook(run: AgentRun) -> RunAnswer: ) assert statuses(events) == [("agent_run", RUN_STARTED), ("agent_run", RUN_CANCELLED)] + async def test_a_finishing_answer_over_its_tokens_completes_it_whole(self): + async def hook(run: AgentRun) -> RunAnswer: + run.control.used(80, 20) + run.control.used(90, 30, calls=False) + return RunAnswer(text="Found it.") + + policy = SubAgentPolicy(limits=AgentLimits(max_tokens=150)) + result, events = await delegated(delegations(hook, policy=policy), request()) + + assert result.result == { + "success": True, "agent": "researcher-1", "run": "researcher-1#1", + "status": RUN_COMPLETED, "partial": False, "result": "Found it.", "error": None, + } + assert statuses(events) == [("agent_run", RUN_STARTED), ("agent_run", RUN_COMPLETED)] + # -- the runs one turn may start ------------------------------------------------------ diff --git a/tests/workflow/test_subagents_contract.py b/tests/workflow/test_subagents_contract.py index 64b1c804..91e2cd68 100644 --- a/tests/workflow/test_subagents_contract.py +++ b/tests/workflow/test_subagents_contract.py @@ -2719,8 +2719,10 @@ async def test_a_last_answer_of_calls_alone_leaves_the_text_before_it(self, make class TestTheTokenLimit: - """Spec 5.4: the run's input plus output tokens, checked after each model - call; past them the run ends at that answer, cancelled by its limit.""" + """A run's input plus output tokens, checked after each model call: an + answer past them that asks for tools is the run's last, cancelled by its + limit, its calls dropped; one that asks for none ends the run as it + would, its result whole.""" async def test_past_it_the_run_ends_at_that_answer_cancelled(self, make_crew): crew = make_crew( @@ -2746,6 +2748,27 @@ async def test_past_it_the_run_ends_at_that_answer_cancelled(self, make_crew): used = crew.ledger().totals(run="researcher-1#1") assert (used.input, used.output, used.calls) == (140, 40, 2) + async def test_a_finishing_answer_past_it_completes_the_run_whole(self, make_crew): + crew = make_crew( + limited(max_tokens=150), + coordinator=[calls(delegate("researcher", "Find X.", "c1")), says("Done.")], + researcher=[calls(use("contract_lookup", "r1", q="X"), text="Looking.", + usage=(60, 20)), + says("X is 42.", usage=(80, 20))], + ) + + events = await crew.turn() + + assert envelope_read(crew.results_read("coordinator")["c1"]) == { + "success": True, "agent": "researcher-1", "run": "researcher-1#1", + "status": RUN_COMPLETED, "partial": False, "result": "X is 42.", "error": None, + } + (record,) = crew.records() + assert (record.status, record.cancelled_by, record.error) == (RUN_COMPLETED, None, None) + assert [e for e in events if e.type is EventType.ERROR] == [] + used = crew.ledger().totals(run="researcher-1#1") + assert (used.input, used.output, used.calls) == (140, 40, 2) + class TestSteering: """Spec 13: a message steered to a run while its tool call is in progress From f569df2e4ae36a2428190389d71a4010aa9b92d5 Mon Sep 17 00:00:00 2001 From: Andrey Shiryaev <7615137+shoom1@users.noreply.github.com> Date: Tue, 17 Nov 2026 18:21:52 -0500 Subject: [PATCH 12/15] Sub-agents: a run's control keeps its last call, and leaves a turn's cancel alone model_call() set final_call from the step limit alone, so a call after one the token limit made the last was no longer the last; it is now kept once set. cancel() cancelled the run's task even while the turn's cancel (Ctrl+C) was unwinding it, and a time limit firing then cut the run's cleanup short and made the hook take the turn's cancel for the run's own; it now records the cancel and leaves that task to its turn. The time limit's clock test gets a wider margin (a 1 s limit) for a loaded runner. --- src/agentic_cli/workflow/agents/control.py | 17 ++++++--- tests/workflow/test_agent_control.py | 41 ++++++++++++++++++++-- 2 files changed, 51 insertions(+), 7 deletions(-) diff --git a/src/agentic_cli/workflow/agents/control.py b/src/agentic_cli/workflow/agents/control.py index 86d3106f..e6f1bb0e 100644 --- a/src/agentic_cli/workflow/agents/control.py +++ b/src/agentic_cli/workflow/agents/control.py @@ -97,7 +97,8 @@ def cancel(self, *, by: str, error: str) -> None: """Cancel the run's task: ``by`` its parent, the user or a limit, for ``error``. Does nothing once the run is cancelled (the first cancel wins) or - its task has ended. + its task has ended, and cancels no task its turn is cancelling + already (the run ends as the turn's). Raises: ValueError: ``by`` is not ``parent``, ``user`` or ``limit``. @@ -148,19 +149,25 @@ def _out_of_time(self) -> None: def _cancel_task(self) -> None: assert self._task is not None + if self._task.cancelling(): + # Its turn is unwinding it already (Ctrl+C): one more cancel + # would cut its cleanup short, and the run is the turn's. + return self._cancelled_task = True self._task.cancel() # -- the limits at its model calls ------------------------------------------- def model_call(self) -> bool: - """Count a model call the run is about to make; True when it is the last allowed. + """Count a model call the run is about to make; True when it is the run's last. - That call's request ends with ``STEP_LIMIT_NOTE``, and its answer is - the run's last (``final_call``). + The last allowed (``max_model_calls``), or any call after one the + token limit made the last, should a backend make one. That call's + request ends with ``STEP_LIMIT_NOTE``, and its answer is the run's + last (``final_call``). """ self._calls += 1 - self._final = self.at_step_limit + self._final = self._final or self.at_step_limit return self._final def used(self, input_tokens: int, output_tokens: int, *, calls: bool = True) -> None: diff --git a/tests/workflow/test_agent_control.py b/tests/workflow/test_agent_control.py index 24c9aede..c9e66584 100644 --- a/tests/workflow/test_agent_control.py +++ b/tests/workflow/test_agent_control.py @@ -102,6 +102,32 @@ async def test_a_cancel_before_the_task_is_bound_cancels_it_then(self): await task assert made.cancelled == ("user", "stopped") + async def test_a_task_its_turn_is_unwinding_is_not_cancelled_again(self): + """A limit that fires while the turn's cancel (Ctrl+C) unwinds the run + adds no cancel of its own, which would cut the run's cleanup short: + the hook sees the turn's cancel alone.""" + made = control() + seen: dict = {} + + async def run() -> None: + try: + await asyncio.Event().wait() + except asyncio.CancelledError: + seen["own"] = made.own_cancel() + seen["cancelling"] = asyncio.current_task().cancelling() + raise + + task = asyncio.create_task(run()) + made.bind(task) + await asyncio.sleep(0) + + task.cancel() # the turn's, not yet delivered + made.cancel(by="limit", error=TIME_LIMIT_ERROR) + + with pytest.raises(asyncio.CancelledError): + await task + assert seen == {"own": False, "cancelling": 1} + def test_who_cancels_is_the_parent_the_user_or_a_limit(self): with pytest.raises(ValueError, match="parent, user or limit"): control().cancel(by="someone", error="why") @@ -188,10 +214,10 @@ async def run() -> str: assert made.cancelled is None async def test_the_clock_starts_with_the_block(self): - made = control(timeout=0.2) + made = control(timeout=1.0) async def run() -> str: - await asyncio.sleep(0.3) # waiting before it works: not counted + await asyncio.sleep(1.2) # waiting before it works: not counted with made.timing(): await asyncio.sleep(0.05) return "done" @@ -243,6 +269,17 @@ async def test_past_it_the_run_ends_at_that_answer_cancelled_by_its_limit(self): assert not task.cancelled() and not task.done() task.cancel() + def test_once_past_it_every_call_is_the_last(self): + """The token limit makes the call in progress the run's last; a call + after it (should a backend make one) is the last too.""" + made = control(max_tokens=100) + made.model_call() + made.used(90, 20) + + made.model_call() + + assert made.final_call is True + def test_without_a_limit_any_number_is_fine(self): made = control() made.used(10**9, 10**9) From 2eb56172fa9f844266e236c3e686350da43a2663 Mon Sep 17 00:00:00 2001 From: Andrey Shiryaev <7615137+shoom1@users.noreply.github.com> Date: Tue, 17 Nov 2026 18:23:41 -0500 Subject: [PATCH 13/15] Tests: cancels that meet, a stopped tool, and a model that reports no usage Pins what held under review: a parent run cancelled alone ends its working child interrupted; the turn's cancel wins while the hook cleans up after its own; a run cancelled already is not cancelled again. The contract scenarios check that the cancelled run's tool was stopped and that its sibling was working when the cancel landed. On both backends a model that reports no usage is not limited by tokens. --- tests/workflow/adk/test_run_control_plugin.py | 11 ++ .../deepagents/test_run_control_middleware.py | 12 ++ tests/workflow/test_agent_delegate.py | 137 +++++++++++++++++- tests/workflow/test_subagents_contract.py | 4 + 4 files changed, 159 insertions(+), 5 deletions(-) diff --git a/tests/workflow/adk/test_run_control_plugin.py b/tests/workflow/adk/test_run_control_plugin.py index 8f5e5e1d..42cf25d5 100644 --- a/tests/workflow/adk/test_run_control_plugin.py +++ b/tests/workflow/adk/test_run_control_plugin.py @@ -134,6 +134,17 @@ async def test_a_finishing_answer_past_the_token_limit_is_left_as_it_is(self): assert (control.cancelled, control.final_call) == (None, False) assert answer.content is content + async def test_an_answer_with_no_usage_is_not_limited_by_tokens(self): + control = RunControl(REF, AgentLimits(max_tokens=1)) + plugin = RunControlPlugin(lambda: control, "anthropic") + answer = LlmResponse(content=model(text("Found it."), call("lookup"))) + + await plugin.before_model_callback(callback_context=None, llm_request=LlmRequest()) + await plugin.after_model_callback(callback_context=None, llm_response=answer) + + assert (control.cancelled, control.final_call) == (None, False) + assert answer.content == model(text("Found it."), call("lookup")) + async def test_a_partial_answer_counts_nothing(self): control = RunControl(REF, AgentLimits(max_tokens=1)) plugin = RunControlPlugin(lambda: control, "anthropic") diff --git a/tests/workflow/deepagents/test_run_control_middleware.py b/tests/workflow/deepagents/test_run_control_middleware.py index 61ec3148..0e4bb3a2 100644 --- a/tests/workflow/deepagents/test_run_control_middleware.py +++ b/tests/workflow/deepagents/test_run_control_middleware.py @@ -107,6 +107,18 @@ async def handler(request): assert (control.cancelled, kept) == (None, answer) +async def test_an_answer_with_no_usage_is_not_limited_by_tokens(): + control = RunControl(REF, AgentLimits(max_tokens=1)) + middleware = RunControlMiddleware(lambda: SimpleNamespace(control=lambda run: control)) + answer = AIMessage("Found it.", tool_calls=[CALL]) + + async def handler(request): + return answer + + assert await middleware.awrap_model_call("the request", handler) is answer + assert (control.cancelled, control.final_call) == (None, False) + + async def test_the_messages_steered_since_the_last_call_join_the_runs_state(): ref = RunRef(agent="researcher", instance="researcher-1", run="researcher-1#1", parent_run=None, depth=1) diff --git a/tests/workflow/test_agent_delegate.py b/tests/workflow/test_agent_delegate.py index 2b2736d8..c7d9a46e 100644 --- a/tests/workflow/test_agent_delegate.py +++ b/tests/workflow/test_agent_delegate.py @@ -697,10 +697,12 @@ async def hook(run: AgentRun) -> RunAnswer: async def stopped( - made: Delegations, working: asyncio.Event, *, by: str, error: str + made: Delegations, working: asyncio.Event, *, by: str, error: str, + asked: DelegationRequest | None = None, run: str = "researcher-1#1", ) -> tuple[Any, list[WorkflowEvent], bool]: - """A delegation in a turn of ``CONVERSATION`` whose run is cancelled once - it works: its result, what it reported, and what ``cancel`` returned.""" + """A delegation (``asked``, else the researcher's) in a turn of + ``CONVERSATION`` whose run ``run`` is cancelled once it works: its result, + what it reported, and what ``cancel`` returned.""" live = LiveEvents() out: dict[str, Any] = {} @@ -708,9 +710,9 @@ async def source(): token = set_active_turn(CONVERSATION) try: with live_events.reporting(live): - running = asyncio.create_task(made.delegate(request())) + running = asyncio.create_task(made.delegate(asked or request())) await working.wait() - out["cancelled"] = made.cancel("researcher-1#1", by=by, error=error) + out["cancelled"] = made.cancel(run, by=by, error=error) out["result"] = await running finally: reset_active_turn(token) @@ -849,6 +851,131 @@ async def caller(): RUN_INTERRUPTED, INTERRUPTED_ERROR, None ) + async def test_the_turns_cancel_while_the_hook_cleans_up_after_its_own_wins(self): + """The run's own cancel taken, and its turn stopped while the hook + cleans up after it: the run is the turn's, interrupted.""" + working, cleaning = asyncio.Event(), asyncio.Event() + + async def hook(run: AgentRun) -> RunAnswer: + working.set() + try: + await asyncio.Event().wait() + except asyncio.CancelledError: + if not run.control.own_cancel(): + raise + cleaning.set() + await asyncio.sleep(0.2) # stopping its work + return RunAnswer(text="Half done.") + return RunAnswer() # pragma: no cover + + runs = AgentRuns() + made = delegations(hook, runs=runs) + + async def caller(): + token = set_active_turn(CONVERSATION) + try: + with live_events.reporting(LiveEvents()): + await made.delegate(request()) + finally: + reset_active_turn(token) + + task = asyncio.create_task(caller()) + await asyncio.wait_for(working.wait(), 5) + token = set_active_turn(CONVERSATION) + try: + assert made.cancel("researcher-1#1", by="parent", error="no longer needed") + finally: + reset_active_turn(token) + await asyncio.wait_for(cleaning.wait(), 5) + task.cancel() + with pytest.raises(asyncio.CancelledError): + await task + + (record,) = runs.records(CONVERSATION) + assert (record.status, record.cancelled_by) == (RUN_INTERRUPTED, None) + + async def test_a_run_cancelled_already_is_not_cancelled_again(self): + working, cleaning = asyncio.Event(), asyncio.Event() + out: dict[str, bool] = {} + made: Delegations + + async def hook(run: AgentRun) -> RunAnswer: + working.set() + try: + await asyncio.Event().wait() + except asyncio.CancelledError: + if not run.control.own_cancel(): + raise + cleaning.set() + await asyncio.sleep(0.05) + return RunAnswer(text="Half done.") + return RunAnswer() # pragma: no cover + + async def body() -> Any: + running = asyncio.create_task(made.delegate(request())) + await working.wait() + out["first"] = made.cancel("researcher-1#1", by="parent", error="stop") + await cleaning.wait() + out["again"] = made.cancel("researcher-1#1", by="user", error="stop it") + return await running + + made = delegations(hook) + token = set_active_turn(CONVERSATION) + try: + with live_events.reporting(LiveEvents()): + result = await asyncio.wait_for(body(), 5) + finally: + reset_active_turn(token) + + assert out == {"first": True, "again": False} + assert (result.result["cancelled_by"], result.result["error"]) == ("parent", "stop") + + async def test_a_parent_cancelled_alone_ends_its_working_child_interrupted(self): + """A parent run cancelled by its control while its child works: the + child's caller (the parent's call) is stopped, so the child is the + parent's, interrupted; the parent ends cancelled with what it had.""" + child_working = asyncio.Event() + made: Delegations + + async def hook(run: AgentRun) -> RunAnswer: + if run.ref.agent == "middle": + try: + # As a backend's task tool does: the delegation in a call of its own. + await asyncio.create_task(made.delegate(request( + {"agent_type": "leaf", "title": "Look", "objective": "Look X up."}, + caller=run.ref, caller_agent="middle", call_id="m1", + ))) + except asyncio.CancelledError: + if not run.control.own_cancel(): + raise + return RunAnswer(text="Planned half.") + return RunAnswer(text="Planned.") # pragma: no cover + child_working.set() + await asyncio.Event().wait() + return RunAnswer() # pragma: no cover + + runs = AgentRuns() + made = delegations(hook, runs=runs) + working = asyncio.Event() + + async def started() -> None: + await child_working.wait() + working.set() + + watcher = asyncio.create_task(started()) + result, _, cancelled = await stopped( + made, working, by="parent", error="no longer needed", + asked=request({"agent_type": "middle", "title": "Plan", "objective": "Plan X."}), + run="middle-1#1", + ) + await watcher + + assert cancelled is True + assert (result.result["status"], result.result["result"]) == (RUN_CANCELLED, "Planned half.") + assert {r.ref.instance: (r.status, r.cancelled_by) for r in runs.records(CONVERSATION)} == { + "middle-1": (RUN_CANCELLED, "parent"), "leaf-1": (RUN_INTERRUPTED, None), + } + class TestTheTimeLimit: async def test_past_it_the_run_is_cancelled_by_its_limit(self): diff --git a/tests/workflow/test_subagents_contract.py b/tests/workflow/test_subagents_contract.py index 91e2cd68..837f544c 100644 --- a/tests/workflow/test_subagents_contract.py +++ b/tests/workflow/test_subagents_contract.py @@ -2528,6 +2528,9 @@ async def test_stopping_one_of_two_parallel_runs_lets_the_other_finish(self, mak "error": "no longer needed", "cancelled_by": "parent", } assert envelope_read(read["c2"])["result"] == "Checked." + # The checker was working when the cancel landed: its tool saw it. + assert json.loads(crew.results_read("checker")["k1"]) == {"success": True} + assert BLOCKING["stopped"].is_set() # the researcher's tool was stopped assert {r.ref.instance: (r.status, r.cancelled_by) for r in crew.records()} == { "researcher-1": (RUN_CANCELLED, "parent"), "checker-1": (RUN_COMPLETED, None), } @@ -2561,6 +2564,7 @@ async def test_a_run_past_its_time_is_cancelled_with_what_it_wrote(self, make_cr RUN_CANCELLED, "limit", TIME_LIMIT_ERROR ) assert [e.metadata["status"] for e in runs_of(events)] == [RUN_STARTED, RUN_CANCELLED] + assert BLOCKING["stopped"].is_set() # its tool was stopped with it class TestALimitAtAPrompt: From 304b72b219381b53f73dc5b1619ac0fb4ca0459d Mon Sep 17 00:00:00 2001 From: Andrey Shiryaev <7615137+shoom1@users.noreply.github.com> Date: Tue, 17 Nov 2026 18:25:08 -0500 Subject: [PATCH 14/15] Sub-agents: texts name the user's cancel, and a stopped prompt in either placement The hooks' docstrings and the message processor named a limit and a parent as who stops a run alone; Delegations.cancel(by="user") stops one too. The comment before the dialog no longer says that any raise means the turn is unwinding, since a cancel of the asking task alone is not. The contract scenarios say what they test rather than citing a document that does not ship. The real-session withdrawal test runs in both dialog placements. --- src/agentic_cli/cli/message_processor.py | 20 +++++++------- src/agentic_cli/workflow/adk/manager.py | 7 ++--- src/agentic_cli/workflow/base_manager.py | 9 ++++--- .../workflow/deepagents/manager.py | 8 +++--- tests/cli/test_a_stopped_runs_prompt.py | 26 +++++++++++-------- tests/workflow/test_subagents_contract.py | 21 ++++++++------- 6 files changed, 50 insertions(+), 41 deletions(-) diff --git a/src/agentic_cli/cli/message_processor.py b/src/agentic_cli/cli/message_processor.py index af514fcb..fcfc059a 100644 --- a/src/agentic_cli/cli/message_processor.py +++ b/src/agentic_cli/cli/message_processor.py @@ -694,8 +694,8 @@ async def _run_turn( request's processing opened end with it, out of the transcript, and the cancel is re-raised; the request (``process`` / ``process_resume``) says ``CANCELLED_LINE`` once. A question whose - asking task alone is cancelled (a sub-agent run stopped by its limit - or its parent while its prompt is on screen) has its dialog + asking task alone is cancelled (a sub-agent run stopped by its limit, + its parent or the user while its prompt is on screen) has its dialog withdrawn, and the turn goes on with its events box back. Errors reported as ``EventType.ERROR`` are rendered as they arrive. A @@ -759,19 +759,21 @@ async def _handle_input(request: "UserInputRequest") -> str: # permission prompt as a denial the user never saw. async with self._asking: _finish_events_box() - # If the dialog raises, the turn is unwinding (cancelled, or - # the dialog failed): reopening the events box then would - # leave a panel on screen that nothing downstream will ever - # finish. The placement is read now: /settings may have - # changed it since the session started with its own. + # The events box comes back after the answer. A dialog that + # raises because the turn is unwinding (Ctrl+C, or the dialog + # failed) leaves it closed: reopened then, it would be a + # panel on screen that nothing downstream will ever finish. + # A cancel of the asking task alone (below) is no unwinding. + # The placement is read now: /settings may have changed it + # since the session started with its own. try: response = await self._prompt_user_input( request, ui, settings.dialog_placement ) except asyncio.CancelledError: # The asking task alone was stopped (a sub-agent run's - # limit, its parent), not the turn: the dialog is - # withdrawn and the turn goes on, so its box comes back. + # limit, its parent, the user), not the turn: the dialog + # is withdrawn and the turn goes on, so its box comes back. if proc_task is not None and not proc_task.cancelling(): _open_events_box() raise diff --git a/src/agentic_cli/workflow/adk/manager.py b/src/agentic_cli/workflow/adk/manager.py index cdcceb1b..e7167235 100644 --- a/src/agentic_cli/workflow/adk/manager.py +++ b/src/agentic_cli/workflow/adk/manager.py @@ -1484,9 +1484,10 @@ async def _run_agent(self, run: AgentRun) -> RunAnswer: so do the raw log's records of its calls. As a turn's runner is, it is stopped with its abort signal set first, so ADK seals the calls it leaves open, in its child session, before the cancel goes on. - A cancel of the run alone (its control's: a limit, its parent) stops - it so too, and it returns what it has: the last text it wrote and the - shared keys it changed; ``Delegations`` ends it cancelled. + A cancel of the run alone (its control's: a limit, its parent or the + user) stops it so too, and it returns what it has: the last text it + wrote and the shared keys it changed; ``Delegations`` ends it + cancelled. Returns: Its last answer with text, that answer's outcome mark, the shared diff --git a/src/agentic_cli/workflow/base_manager.py b/src/agentic_cli/workflow/base_manager.py index 8063e512..c0b6bae0 100644 --- a/src/agentic_cli/workflow/base_manager.py +++ b/src/agentic_cli/workflow/base_manager.py @@ -623,10 +623,11 @@ async def _run_agent(self, run: AgentRun) -> RunAnswer: turn's live events as they are made, and returns its last answer, its outcome and the shared state it changed. A failure raises (the provider's error, or ``RunFailed``). A cancel stops the run; the - run's own (``run.control.own_cancel()``: a limit's, its parent's) - returns what it has, its last text and the shared state it changed, - and any other (its turn's) raises. ``run.control`` keeps its limits - at its model calls (each backend's in its sub-agents' stacks). + run's own (``run.control.own_cancel()``: a limit's, its parent's, + the user's) returns what it has, its last text and the shared state + it changed, and any other (its turn's) raises. ``run.control`` + keeps its limits at its model calls (each backend's in its + sub-agents' stacks). Raises: NotImplementedError: This backend runs no sub-agent. diff --git a/src/agentic_cli/workflow/deepagents/manager.py b/src/agentic_cli/workflow/deepagents/manager.py index d05872e5..cf87526a 100644 --- a/src/agentic_cli/workflow/deepagents/manager.py +++ b/src/agentic_cli/workflow/deepagents/manager.py @@ -730,10 +730,10 @@ async def _run_agent(self, run: AgentRun) -> RunAnswer: turn's live events as they are made, through a processor made for the run. Its input is the shared state it starts from and its messages: an inheriting run's history, then the task message. A - cancel of the run alone (its control's: a limit, its parent) closes - its stream, which stops its graph, and it returns what it has: the - last text it wrote and the shared keys it changed, as of its last - finished step; ``Delegations`` ends it cancelled. + cancel of the run alone (its control's: a limit, its parent or the + user) closes its stream, which stops its graph, and it returns what + it has: the last text it wrote and the shared keys it changed, as of + its last finished step; ``Delegations`` ends it cancelled. Returns: Its last non-empty answer, as Deep Agents' own ``task`` read one diff --git a/tests/cli/test_a_stopped_runs_prompt.py b/tests/cli/test_a_stopped_runs_prompt.py index 687b9e1c..5395afdf 100644 --- a/tests/cli/test_a_stopped_runs_prompt.py +++ b/tests/cli/test_a_stopped_runs_prompt.py @@ -1,12 +1,12 @@ """A sub-agent run stopped while its prompt is on screen, the turn going on. -A run's limit (its time limit, while the user is slow to answer) or its -parent cancels the run alone: the task awaiting its question is cancelled, -not the turn's. The dialog is withdrawn (thinking-prompt closes a dialog -whose awaiter is cancelled), the turn's events box comes back, since the -turn goes on, and the turn's next question reaches the user. A cancel of the -turn itself (Ctrl+C) still leaves the box closed: the turn is unwinding -(``test_turn_boundary.py``). +A run's limit (its time limit, while the user is slow to answer), its +parent or the user cancels the run alone: the task awaiting its question is +cancelled, not the turn's. The dialog is withdrawn (thinking-prompt closes a +dialog whose awaiter is cancelled, in either placement), the turn's events +box comes back, since the turn goes on, and the turn's next question +reaches the user. A cancel of the turn itself (Ctrl+C) still leaves the box +closed: the turn is unwinding (``test_turn_boundary.py``). """ from __future__ import annotations @@ -15,6 +15,7 @@ from contextlib import suppress from types import SimpleNamespace +import pytest from prompt_toolkit.application import create_app_session from prompt_toolkit.input import create_pipe_input from prompt_toolkit.output import DummyOutput @@ -44,8 +45,8 @@ def clear_input_callback(self, token=None) -> None: self.callback = None -def _settings() -> SimpleNamespace: - return SimpleNamespace(verbose_thinking=False, default_user="u", dialog_placement="box") +def _settings(placement: str = "box") -> SimpleNamespace: + return SimpleNamespace(verbose_thinking=False, default_user="u", dialog_placement=placement) def _controller(workflow: _Workflow) -> SimpleNamespace: @@ -98,7 +99,8 @@ async def turn(): assert [box.finish.call_count for box in ui.boxes] == [1, 1, 1] -async def test_on_a_real_session_the_dialog_is_withdrawn_and_the_next_one_shown(): +@pytest.mark.parametrize("placement", ["box", "inline"]) +async def test_on_a_real_session_the_dialog_is_withdrawn_and_the_next_one_shown(placement): workflow = _Workflow() seen: dict = {} @@ -125,7 +127,9 @@ async def turn(): turn_done = asyncio.Event() async def handler(_line: str) -> None: - await MessageProcessor()._run_turn(source, _controller(workflow), ui, _settings()) + await MessageProcessor()._run_turn( + source, _controller(workflow), ui, _settings(placement) + ) turn_done.set() running = asyncio.create_task(ui.run_async(handler)) diff --git a/tests/workflow/test_subagents_contract.py b/tests/workflow/test_subagents_contract.py index 837f544c..cdb23374 100644 --- a/tests/workflow/test_subagents_contract.py +++ b/tests/workflow/test_subagents_contract.py @@ -2500,7 +2500,8 @@ async def contract_await_a_cancelled_run() -> dict: class TestCancellingOneRun: - """Spec 13: stopping one run while its siblings finish.""" + """One run stopped alone, by its parent, while its sibling works: the + sibling finishes, and the coordinator reads both envelopes.""" async def test_stopping_one_of_two_parallel_runs_lets_the_other_finish(self, make_crew): crew = make_crew( @@ -2568,10 +2569,10 @@ async def test_a_run_past_its_time_is_cancelled_with_what_it_wrote(self, make_cr class TestALimitAtAPrompt: - """Review Focus 2: a limit that fires while the run waits at a permission - prompt (the user slow to answer): the prompt is withdrawn, the call is - answered as not run, the run ends cancelled by its limit, the turn goes - on with its envelope, and the prompts after it still reach the user.""" + """A limit that fires while the run waits at a permission prompt (the + user slow to answer): the prompt is withdrawn, the call is answered as + not run, the run ends cancelled by its limit, the turn goes on with its + envelope, and the prompts after it still reach the user.""" async def test_the_prompt_is_withdrawn_and_the_turn_goes_on(self, make_crew): crew = make_crew( @@ -2642,8 +2643,8 @@ def calls_to(events: list[WorkflowEvent], call_id: str) -> list[WorkflowEvent]: class TestTheStepLimit: - """Spec 5.4: the run's last allowed model call is told to answer now, and - no call it makes runs; the run completes partial.""" + """The run's last allowed model call is told to answer now, and no call + it makes runs; the run completes partial.""" async def test_the_last_allowed_call_is_told_and_the_run_completes_partial(self, make_crew): crew = make_crew( @@ -2775,9 +2776,9 @@ async def test_a_finishing_answer_past_it_completes_the_run_whole(self, make_cre class TestSteering: - """Spec 13: a message steered to a run while its tool call is in progress - is in its next model request, after its last message, as the user's, and - stays in its transcript: still there in the request after.""" + """A message steered to a run while its tool call is in progress is in + its next model request, after its last message, as the user's, and stays + in its transcript: still there in the request after.""" async def test_a_steered_message_reaches_the_next_request_and_stays(self, make_crew): crew = make_crew( From 69e7c753f1891c85246358648be27318e6680a02 Mon Sep 17 00:00:00 2001 From: Andrey Shiryaev <7615137+shoom1@users.noreply.github.com> Date: Tue, 17 Nov 2026 18:25:50 -0500 Subject: [PATCH 15/15] Docs: the token limit ends only a run that would go on, and a steered run keeps its task The CHANGELOG, the README and CLAUDE.md say that an answer past max_tokens that asks for tools is the run's last, cancelled by its limit, while one that asks for none ends the run completed, its result whole, and that a model which reports no usage is not limited by tokens. CLAUDE.md also says that a sub-agent run's task message is never trimmed on ADK, that a steered message's later events are stamped after it, and that the user's cancel withdraws a run's prompt too. --- CHANGELOG.md | 15 +++++++++------ CLAUDE.md | 12 ++++++------ README.md | 10 ++++++---- 3 files changed, 21 insertions(+), 16 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4cfb5344..53871992 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -600,12 +600,15 @@ the start of the entry's title. starts, is cancelled (`"status": "cancelled"`, `"cancelled_by": "limit"`, `"error": "time limit reached"`), the text it wrote so far its partial result, and a question or permission prompt it waited at is - withdrawn; a model call that takes a run past its `max_tokens` is its - last, its calls dropped, and the run is cancelled likewise (`"token - limit reached"`), that answer's text its result. Construction refuses, - with a `ValueError` naming the field, a limit that is not a positive int - (a timeout: a positive, finite number; `True` and `False` are no numbers - here) and a policy whose `limits` is not an `AgentLimits`. + withdrawn; a model call that takes a run past its `max_tokens` and asks + for tools is its last, its calls dropped, and the run is cancelled + likewise (`"token limit reached"`), that answer's text its result, while + one that asks for none ends the run as it would, completed, its result + whole (a model that reports no usage is not limited by tokens). + Construction refuses, with a `ValueError` naming the field, a limit that + is not a positive int (a timeout: a positive, finite number; `True` and + `False` are no numbers here) and a policy whose `limits` is not an + `AgentLimits`. - **`AgentConfig.brief_required` and `AgentConfig.limits`.** `brief_required` (default `("objective",)`) names the brief fields the agent asks a delegation to fill: `objective`, `deliverable`, diff --git a/CLAUDE.md b/CLAUDE.md index c3f2b7cb..527f63c3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -42,7 +42,7 @@ agentic-cli/ │ │ ├── session_resume.py # What /resume shows: the picker (picker: each row's backend once one is another's; PickedConversation, the id a str naming its backend), the "Resumed:" line ("Resumed on :" on another backend), the replay of the last 10 messages │ │ ├── stored_conversations.py # StoredConversations: one look at every installed backend's stored conversations (the running workflow's own, each other backend's SessionReader, opened and closed with the look): rows merged newest first, each naming its backend; where(id), delete; a backend not read (its extra missing, its store failing) left out and named in notes; a failing store warned of in the log at each look the user asks for, once a run for the app's own (warned: the job monitor's, a finished job's) │ │ ├── session_args.py # --continue / --resume → SessionStart (BaseCLIApp.main() adds them; start: new, continue, resume; SessionArgumentParser: --resume without its id names --continue and /resume) -│ │ ├── message_processor.py # WorkflowEvent → ThinkingPromptSession rendering (a sub-agent run's events box lines and transcript tool results under its name, "researcher-2 › …": the event's run, _at_work; the main agent's unchanged); Ctrl+C stops the request being processed (its boxes end with it; "Operation cancelled..." once, then the background jobs it submitted that still run, named; CancelledError re-raised); tool questions as dialogs, one at a time (a sub-agent run's titled with its instance, "researcher-2 · Permission" or "researcher-2 asks", a question's text opening with its run_label; one whose asking task alone is cancelled, a run stopped by its limit or its parent, withdrawn and the events box back, the turn going on); process_compact: /compact run as a turn (compact() as its event source, live events merged in); a success line for each memory write (save_memory, update_memory, delete_memory); a failed turn said once, from its ERROR as from a raise ("Rate limited: …" for rate_limited, "Send your message again" for a ConversationChangedError) +│ │ ├── message_processor.py # WorkflowEvent → ThinkingPromptSession rendering (a sub-agent run's events box lines and transcript tool results under its name, "researcher-2 › …": the event's run, _at_work; the main agent's unchanged); Ctrl+C stops the request being processed (its boxes end with it; "Operation cancelled..." once, then the background jobs it submitted that still run, named; CancelledError re-raised); tool questions as dialogs, one at a time (a sub-agent run's titled with its instance, "researcher-2 · Permission" or "researcher-2 asks", a question's text opening with its run_label; one whose asking task alone is cancelled, a run stopped by its limit, its parent or the user, withdrawn and the events box back, the turn going on); process_compact: /compact run as a turn (compact() as its event source, live events merged in); a success line for each memory write (save_memory, update_memory, delete_memory); a failed turn said once, from its ERROR as from a raise ("Rate limited: …" for rate_limited, "Send your message again" for a ConversationChangedError) │ │ ├── settings_command.py # /settings: a Dialog with Save and Cancel; the fields that changed → apply_settings, then save_settings(keys=changed) (an override that cannot take `keys` fails there: "Settings applied but not saved: …") │ │ ├── settings_introspection.py # Pydantic field → thinking-prompt form field (built complete: they are frozen) │ │ ├── settings_ui.py # SettingsUI(app), what BaseCLIApp's _build_ui_items/apply_settings/save_settings delegate to (it calls the app's hooks: get_ui_setting_keys, get_theme, start_new_session; keeps nothing): the fields (the model pickers: the list, catalog.offered with model_services.role_models, as /models has it; a role's model the list leaves out offered first as " (current)", "Not offered ()" starting the description, so a Save changes no model untouched); a Save all or nothing, each key as settings_persistence declares (an orchestrator change, check_backend first, starts a new conversation on the new backend through the app's start_new_session() when the open one is fresh, ConversationCore.fresh read under the turn lock, else "(applies to the next /new)"; while the workflow is down a fresh one moves there, _move_here, decided again under the turn lock); Ctrl+C wherever a Save waits says "Operation cancelled..." once (_says_so_when_stopped; a new conversation's own, as /new says it) and undoes it; the save on a worker thread @@ -82,14 +82,14 @@ agentic-cli/ │ │ │ ├── capabilities.py # Capability, EXEMPT │ │ │ ├── matchers.py # PathMatcher, URLMatcher, ShellMatcher, StringGlobMatcher │ │ │ └── rules.py, store.py, prompt.py (build_request(run=): a sub-agent's prompt opens with its run; is_permission_request: by its perm- id) -│ │ ├── agents/ # Sub-agents: runs.py: the RUN_* statuses, RunRecord, AgentRuns (a manager's runs by conversation: run_for names - and its run #1 per (conversation, parent run, call id), a new one once it ended; number_from: past the instances a conversation's store keeps, a count never lowered; observe records AGENT_RUN under the turn it is reported in; interrupt_open; a record's usage: what the run used, by model, from its end event or the ledger), run_title, result_head, run_instance and run_number (the one reader of a run id: researcher-2#1's instance and number), run_label (how a dialog names a run: researcher-2 (researcher, run 1)), SUBAGENT_ERROR_PREFIX (ADK's old words for a failed delegation, kept for callers), show_as_delegation(result, envelope) (a delegation's TOOL_RESULT shown alike on both backends: the result's first line, or Failed: ; metadata["result"] the envelope); a record's brief, started_by, mode and cancelled_by; delegate.py: Delegations (delegate(DelegationRequest) → Delegated: the one place a run starts and ends, on both backends: the brief read against the caller's own sub-agents, the run named (a turn's first run past the instances its conversation's store keeps: stored=, asked once per conversation per turn, again after a failed or stopped ask), its AGENT_RUN start and end observed and reported, the backend's hook (RunHook: AgentRun → RunAnswer) run in a task of its own with the run active and no tool call, the end by the answer (completed, partial for a cut or the step limit, refused, failed for an error or a raise, with one recoverable ERROR failed: , or RunFailed's own words, cancelled by its control with what the hook had), interrupted on its turn's cancel, which wins; the envelope as the result; each run under its RunControl, the type's limits over the policy's, kept while it works: control(run), cancel(run_id, by=, error=), the run alone; a call past max_runs_per_turn the error result RUNS_PER_TURN_ERROR, no run), DelegationRequest, AgentRun (control), RunAnswer, RunFailed, started_by; control.py: RunControl (one run's: cancel(by=, error=) its task, the first cancel winning, own_cancel for the hook that takes it and returns, timing: the time limit while the hook runs; model_call/at_step_limit/final_call: the step limit, STEP_LIMIT_NOTE on the last allowed call; used: the token limit, the run ending at that answer cancelled by it; steer/take_steering), STEP_LIMIT_NOTE; outcome.py: a sub-agent's refused or cut answer (outcome_of, the refusal notice as Deep Agents 0.7.34 words it, cut_off, cut_off_warning, OPENAI_REFUSAL_PREFIX: how ADK's OpenAI adapters word a refusal); policy.py: SubAgentPolicy (max_active, max_runs_per_turn, limits) and AgentLimits (max_model_calls, timeout, max_tokens; over: a type's limits over the policy's, field by field, None taking the base's), DEFAULT_LIMITS (100 model calls), frozen and checked as they are made (a ValueError naming the field), as_policy (the one reading of a subagents= argument: a TypeError for anything but a policy or None); brief.py: BRIEF_FIELDS, Brief, BriefError, read_brief (a task call's agent type and brief, against the types its caller may start: the error texts), task_message (a run's first message, a section per filled field; an inheriting type's ends with INHERITED_CONTEXT_NOTE), task_parameters and task_description (task's schema and description, the same for both backends; limit_sentences: the limits it states, "At most runs per turn."); envelope.py: envelope (a delegation run's result: success only for completed, a one-line error, cancelled_by for a cancelled run), read_envelope (a dict or its JSON text, else None; never raises), the limit and interrupted error texts +│ │ ├── agents/ # Sub-agents: runs.py: the RUN_* statuses, RunRecord, AgentRuns (a manager's runs by conversation: run_for names - and its run #1 per (conversation, parent run, call id), a new one once it ended; number_from: past the instances a conversation's store keeps, a count never lowered; observe records AGENT_RUN under the turn it is reported in; interrupt_open; a record's usage: what the run used, by model, from its end event or the ledger), run_title, result_head, run_instance and run_number (the one reader of a run id: researcher-2#1's instance and number), run_label (how a dialog names a run: researcher-2 (researcher, run 1)), SUBAGENT_ERROR_PREFIX (ADK's old words for a failed delegation, kept for callers), show_as_delegation(result, envelope) (a delegation's TOOL_RESULT shown alike on both backends: the result's first line, or Failed: ; metadata["result"] the envelope); a record's brief, started_by, mode and cancelled_by; delegate.py: Delegations (delegate(DelegationRequest) → Delegated: the one place a run starts and ends, on both backends: the brief read against the caller's own sub-agents, the run named (a turn's first run past the instances its conversation's store keeps: stored=, asked once per conversation per turn, again after a failed or stopped ask), its AGENT_RUN start and end observed and reported, the backend's hook (RunHook: AgentRun → RunAnswer) run in a task of its own with the run active and no tool call, the end by the answer (completed, partial for a cut or the step limit, refused, failed for an error or a raise, with one recoverable ERROR failed: , or RunFailed's own words, cancelled by its control with what the hook had), interrupted on its turn's cancel, which wins; the envelope as the result; each run under its RunControl, the type's limits over the policy's, kept while it works: control(run), cancel(run_id, by=, error=), the run alone; a call past max_runs_per_turn the error result RUNS_PER_TURN_ERROR, no run), DelegationRequest, AgentRun (control), RunAnswer, RunFailed, started_by; control.py: RunControl (one run's: cancel(by=, error=) its task, the first cancel winning, own_cancel for the hook that takes it and returns, timing: the time limit while the hook runs; model_call/at_step_limit/final_call: the step limit, STEP_LIMIT_NOTE on the last allowed call; used: the token limit, an answer past it that makes calls the run's last, cancelled by it, one that makes none its result (calls=); model_call once final stays final; a cancel leaves a task its turn is cancelling alone; steer/take_steering), STEP_LIMIT_NOTE; outcome.py: a sub-agent's refused or cut answer (outcome_of, the refusal notice as Deep Agents 0.7.34 words it, cut_off, cut_off_warning, OPENAI_REFUSAL_PREFIX: how ADK's OpenAI adapters word a refusal); policy.py: SubAgentPolicy (max_active, max_runs_per_turn, limits) and AgentLimits (max_model_calls, timeout, max_tokens; over: a type's limits over the policy's, field by field, None taking the base's), DEFAULT_LIMITS (100 model calls), frozen and checked as they are made (a ValueError naming the field), as_policy (the one reading of a subagents= argument: a TypeError for anything but a policy or None); brief.py: BRIEF_FIELDS, Brief, BriefError, read_brief (a task call's agent type and brief, against the types its caller may start: the error texts), task_message (a run's first message, a section per filled field; an inheriting type's ends with INHERITED_CONTEXT_NOTE), task_parameters and task_description (task's schema and description, the same for both backends; limit_sentences: the limits it states, "At most runs per turn."); envelope.py: envelope (a delegation run's result: success only for completed, a one-line error, cancelled_by for a cancelled run), read_envelope (a dict or its JSON text, else None; never raises), the limit and interrupted error texts │ │ ├── adk/ # ADK orchestrator │ │ │ ├── manager.py # GoogleADKWorkflowManager (the agents built from configs or, adk_config_path, by ADK from a native YAML (library-only: no BaseCLIApp starts one; loaded once per manager at the first _validate_agent_graph (_native_root: the settings' keys exported first; a retry, a model switch and a start after cleanup build on the same tree, whose toolsets the closed runner left reusable), its agents' models resolved leniently in _resolve_extra_models, the base's hook, its registered tools' services detected; configs passed with it ignored, adk_native_configs_ignored): the only difference; _do_initialize builds the app from the tree alone, _build_app → ADKBuild, through the hooks _plugin_chain (the whole chain, top to bottom, its head _init_plugins), _compaction_config (None for a root without a budget), _context_cache_config, _agent_model_refs; the event processor built from the build; a config-built agent's prompt as an instruction provider, sent as written: no `{name}` state injection; _compact_turn: ADK's compaction once, in the base's compact turn; supports_compact False once built for a root without a budget (_no_compact_support says why); the job resume hooks: _conversation_exists (the session read without its events, num_recent_events=0), _deliver_job_notice (the notice, for every app); _run_config: the agents' synchronous tools run in ADK's tool thread pool, 8 workers; _run_and_stream: a run that fails yields the turn's one ERROR, last, none after an ERROR already yielded; the agents: _create_agents builds each config's agent on its own (_agents, by name; no ADK sub_agents), a delegating one with a TaskTool (its own tool named task: AgentGraphError); a runner per sub-agent type (_agent_runners: NoAfterTurnCompactionRunner on App(name=child_app(app_name), root_agent=the type's agent, plugins=_agent_plugin_chain(agent), the app's context cache, no compaction) over the session service, closed with the main runner by _detach_backend, rebuilt by every initialization); _run_agent, the base's hook: the run's child session (_child_session: run.state, an inheriting run's copied events; never one the store keeps, whose instance numbering goes past: ADK's create_session refuses it, and the run fails), _stored_instances (the base's hook: the highest instance number of each type the conversation's child sessions keep), the type's runner on the task message with an abort signal set before it is closed, a run-mode ADKEventProcessor, the raw log's records reported as they come (_report_raw_log); a model's failure raised as the provider's (_plugin_cause), an overflow RunFailed, a reply that is no answer RunAnswer(error=), the shared keys it changed read back) │ │ │ ├── build.py # ADKBuild (root, reply_agents, plugins, compaction, cache, models); load_native_root (from_config at validation; what ADK cannot load, wrapped as AgentGraphError naming the file, ADK's error the cause; a root that is not an LlmAgent, a name used twice in the tree and a task-mode agent refused, AgentGraphError naming it; ensure_direct_anthropic); what the run reads of any tree: reply_agents (the root and the chat-mode agents it can transfer to), own_after_tool_agents (left out by the cap) │ │ │ ├── task_tool.py # TaskTool: the framework's task on ADK (a BaseTool; its declaration task_parameters' JSON schema, parameters_json_schema; its description task_description; bound to the task declaration, an exact TaskTool only): a call → Delegations.delegate, the run's shared-key changes written to the caller's state, the envelope returned as JSON text (ADK's OpenAI Responses adapter sends only a dict's result); SHARED_KEYS (plan, tasks, the outside-content mark); inherited_events (an inheriting run's history: the session's root-visible events, copied) │ │ │ ├── compaction.py # AgentCliSummarizer (main agent only; summary_range, render_events; its usage normalized, timed and recorded in the conversation's ledger, ledgers, as soon as the call answers: an empty summary's too; on_written: a summary written drops the conversation's memory index snapshot), MainAgentPlugin (the running agent, first in every chain), NoAfterTurnCompactionRunner, compact_session -│ │ │ ├── fit_guard_plugin.py # FitGuardPlugin: a request over its agent's budget has its oldest turns left out (drop_turns); what opens the conversation, the memory index then a summary (protected_head, never dropped), folded into the next user text (fold_summary); request_as_seen -│ │ │ ├── overflow_plugin.py # OverflowPlugin (OVERFLOW_PLUGIN_FAILED: ADK's wrapper of its errors, which the manager unwraps): a provider's overflow summarized (the root; the retry: the summary and the turns it kept) or trimmed, retried once (the retry timed around its own request: call_clock.mark_latency), then CONTEXT_OVERFLOW: overflow_message for an agent that replies (reply_agents), subagent_overflow_message for a sub-agent's run (root None on its runner), which fails it +│ │ │ ├── fit_guard_plugin.py # FitGuardPlugin: a request over its agent's budget has its oldest turns left out (drop_turns); what opens the conversation, the memory index then a summary (protected_head, never dropped), folded into the next user text (fold_summary); in a sub-agent type's chain (keep_task) a run's task message, its invocation's user content, never dropped either, the first kept turn joining it (a message steered after a tool result starts a turn); request_as_seen +│ │ │ ├── overflow_plugin.py # OverflowPlugin (OVERFLOW_PLUGIN_FAILED: ADK's wrapper of its errors, which the manager unwraps): a provider's overflow summarized (the root; the retry: the summary and the turns it kept) or trimmed, retried once (the retry timed around its own request: call_clock.mark_latency), then CONTEXT_OVERFLOW: overflow_message for an agent that replies (reply_agents), subagent_overflow_message for a sub-agent's run (root None on its runner), which fails it; a sub-agent's trimmed retry keeps its task message (keep_task) │ │ │ ├── memory_index_plugin.py # MemoryIndexPlugin: the conversation's memory index first in the root's requests (before the overflow handler and the fit guard, which keep and fold it) │ │ │ ├── sessions.py # A conversation's row in its session state (agentic_cli.title, agentic_cli.turns), saved with each user turn (run_async(state_delta=)); typed_prompts; ServiceSessions: the session hooks over a session service (the manager's and its reader's); make_session_service, session_db_url; open_sessions (a reader's store: empty without ADK's sessions table, looked at read-only); CHILD_APP_SUFFIX, child_app (--agents: the sub-agent runs' app, which no conversation list reads), child_session_id (/, a ValueError past ADK's 128 characters), delete_children (a conversation's child sessions, events and all: ServiceSessions.delete runs it after the conversation's own delete, whatever that found), stored_instances (the highest instance number of each type a conversation's child sessions keep) │ │ │ ├── event_processor.py # ADKEventProcessor (each call's LLM_USAGE normalized by its model's provider kind, kinds (an agent without one: an unknown kind's), with its latency (call_clock's mark), and recorded in the conversation's ledger before on_event, a run's end with what it used; reply_agents: the agents whose text is the reply; another's, a sub-agent's, marked as activity; a reply that is no answer, NO_ANSWER_CODES, → the turn's ERROR; a failed result, an MCP isError one too, → a failed TOOL_RESULT naming its error, as on Deep Agents; TASK_PROGRESS after a tool call that changed the task list, its state delta's tasks, as on Deep Agents: start_turn forgets the list reported; every event names its run, the agent's own at depth 0, TOOL_CALL and TOOL_RESULT their tool_call_id; a task call's TOOL_RESULT shown as on Deep Agents, from its envelope: show_as_delegation; run=: a processor for one sub-agent run, on its child session, every event that run's, a sub-agent's text activity, no TASK_PROGRESS (the root's reports the list as the run returns), its last answer with text, its outcome mark and its failure kept (answer, outcome, failure: an overflow, a reply that is no answer but an empty one) for _run_agent) @@ -104,7 +104,7 @@ agentic-cli/ │ │ │ ├── context_cache_plugin.py # One Gemini cache attempt a turn │ │ │ ├── foreign_reasoning_plugin.py # No model is sent another provider's thoughts │ │ │ ├── subagent_outcome_plugin.py # SubAgentOutcomePlugin: a sub-agent's final answer a model refused or cut, rewritten in place (the refusal notice; the text and the cut-off note) and marked (custom_metadata agentic_cli_outcome), which the run's event processor ends it by; what it reads: finish_reason, error_code, an OTHER stop's JSON reason, the text "OpenAI refusal: "; in each sub-agent type's runner's chain (_agent_plugin_chain), after the raw log and RunControlPlugin; the root's answers untouched -│ │ │ ├── run_control_plugin.py # RunControlPlugin: a sub-agent run's control at its model calls (Delegations.control of the active run): the messages steered to it appended to its child session and the request before each call, the call counted and the last allowed one given STEP_LIMIT_NOTE (with_note: a part of the last user content; its tools stay declared), each answer's usage (adk_tokens) to used, the run's last answer's function calls dropped (drop_calls: an empty text for calls alone); in each sub-agent type's chain, after the raw log, before SubAgentOutcomePlugin +│ │ │ ├── run_control_plugin.py # RunControlPlugin: a sub-agent run's control at its model calls (Delegations.control of the active run): the messages steered to it appended to its child session and the request before each call (the run's events from then on stamped after them, on_event_callback: ADK stamps an answer before its call's callbacks, and a durable store reads events back by time), the call counted and the last allowed one given STEP_LIMIT_NOTE (with_note: a part of the last user content; its tools stay declared), each answer's usage (adk_tokens) to used, with whether it makes calls, the run's last answer's function calls dropped (drop_calls: an empty text for calls alone); in each sub-agent type's chain, after the raw log, before SubAgentOutcomePlugin │ │ │ ├── log_filters.py # install_log_filters: what ADK would print over the CLI logged at debug instead (the warnings hook, filters by logger name: see Console Output); imports no ADK (the package loads LLMLoggingPlugin on first use); the plugin-manager filter reads overflow_plugin.OVERFLOW_PLUGIN_FAILED as a record comes; BaseCLIApp.run() installs them, once │ │ │ ├── call_clock.py # Every model call timed: CallClock (a clock per call, under its EventActions, held through an error until the answer a later plugin gives; the raw log keeps one too), CallSentPlugin (last: starts it as the request goes out), CallLatencyPlugin (second, after MainAgentPlugin: marks the answer, custom_metadata[LATENCY_KEY], which the event processor reads, call_latency; an answer already marked keeps its mark: mark_latency, the overflow retry's); no adapter sends it │ │ │ └── plugins.py # LLM traffic logging (raw_llm_logging): requests as sent (SentRequestLoggingPlugin, after the fit guard); each record names its agent's model, the agent and its sub-agent run (the active run); latency per model call (call_clock.CallClock: a clock under the call's EventActions, as the fit guard keeps its copies); usage records go to the file only (the stream's LLM_USAGE is the event processor's), counted as the stream's (adk_usage_event, by the agent's kind: kinds); the summary call and the overflow retry are not logged on ADK (a follow-up) @@ -251,7 +251,7 @@ Workflow: - **Tool error handling**: All tools return `{"success": bool, ...}` dicts. Never raise `ToolError`. An exception that still escapes a tool is a bug, but it costs one call rather than the turn: on ADK, `workflow/adk/tool_error_plugin.py::ToolErrorPlugin` turns it into an error dict; on Deep Agents, `workflow/deepagents/middleware.py::ToolCallErrorMiddleware`, inside the permission gate, gives the same result, `{"success": false, "error": " failed: : "}` cut to 500 characters (both use `workflow/tool_errors.py`). A call to a tool name the agent does not have gets ADK's own text, its first two lines (`unknown_tool_result`: "nope failed: ValueError: Tool 'nope' not found." and the agent's tools by name), logged `tool_not_found` at info (the model's mistake): on ADK the permission gate lets ADK's stand-in through (`is_unknown_tool`: a bare `BaseTool` described "Tool not found", which runs nothing; contract-tested) and `ToolErrorPlugin` answers its lookup error; on Deep Agents the gate answers it. It catches `Exception`, never `BaseException`, so cancelling still cancels. `task` raises nothing into it: a sub-agent's model or run failing (its summary or overflow included: its own tools' errors are results already) fails the run, whose envelope its parent reads (`error`: the provider's reason; on ADK out of ADK's plugin wrapper), reported at once through the turn's live events as one recoverable `ERROR`, ` failed: `, the run's: the coordinator carries on. A sub-agent's overflow (still too long after its summary or trim) fails its run, on both backends, in the words of ADK's overflow handler, `: the request no longer fits 's context window.` with `error_code` `CONTEXT_OVERFLOW` (`context.py::subagent_overflow_message`): ADK's `OverflowPlugin` answers the run's model call with it, Deep Agents' manager raises it (`RunFailed`). A refusal is no exception here (the framework adds no `ModelRefusalMiddleware`): a sub-agent whose final answer a model refused ends its run `refused`, and its parent reads, as its envelope's result, Deep Agents 0.7.34's notice ("The subagent stopped because a model refused the request. … Retrying the same request is unlikely to succeed; rephrase it or continue without it."), on both backends and whichever deepagents the pin installs (0.7.28 has no notice of its own; 0.7.34+ finds no refusal block left to word again); an answer cut at the output limit keeps its text, followed by `[cut off at the output limit]`, and its run ends `completed` and `partial`, with one recoverable warning ("'s answer was cut off at the output limit"); the answer's thoughts or reasoning are kept. ADK's `SubAgentOutcomePlugin` and Deep Agents' `SubAgentOutcomeMiddleware` rewrite and mark the answer, by `workflow/agents/outcome.py`. On ADK the plugin reads the answer's `finish_reason` (Claude's `refusal` and a Chat Completions `content_filter` arrive as `SAFETY`, `max_tokens` and `length` as `MAX_TOKENS`, Gemini's as themselves), the `error_code` ADK sets on an answer with no content (a Gemini prompt's `block_reason`), the `reason` an `OTHER` stop names in its JSON error message (ADK's OpenAI Responses adapter's `incomplete_details`, `content_filter` among them) and a text part `OpenAI refusal: ` (that adapter's refusal, and `OpenAICompatibleLlm`'s of a Chat Completions `refusal`, which ADK's class drops). On Deep Agents the middleware reads `response_metadata`'s `stop_reason` (ChatAnthropic), `finish_reason` (ChatOpenAI, ChatGoogleGenerativeAI), `incomplete_details.reason` (the Responses API) and `prompt_feedback.block_reason` (a Gemini prompt block), and a refusal the answer holds (a refusal block, standard or `non_standard`, or `additional_kwargs["refusal"]`). The root's own answers reach the user as their model gave them: on ADK a root's refusal with no answer (Claude's, Gemini's) is still the turn's one `ERROR` (" returned no answer"), and a root on OpenRouter or an OpenAI-compatible server replies "OpenAI refusal: ". On both backends the root's own failure leaves the run: the turn's one `ERROR`. A gate or error result goes back as the call's `ToolMessage` with `status="error"`. LangGraph's `ToolNode` runs with `handle_tool_errors=True`. - **Tool result cap**: every tool result passes `workflow/tool_output.py::cap_tool_result` (registered, MCP and skill tools, `job_result`, a delegation's envelope on either backend): one over `tool_result_max_chars` is cut to its shape and as much of its head and tail as fits (the kept length is bisected, since JSON escapes vary), with a note (under `truncated`, or appended to a string) pointing at its full output in `./.{app_name}/tool-output/`, written for `read_file` to page by lines (lines over 2,000 characters split). A string that holds a JSON object (`json_object`: a delegation's envelope, which both task tools write unescaped, `ensure_ascii=False`; a framework tool's dict in a Deep Agents `ToolMessage`) is cut as that dict and given back as its JSON text, so the parent reads JSON still, on both backends. On ADK, `workflow/adk/tool_result_cap_plugin.py::ToolResultCapPlugin` is registered after `InterruptedCallsPlugin`, since ADK stops at the first `after_tool_callback` that returns a value, and it leaves out an agent with `after_tool_callback`s of its own (a native YAML app's, `build.own_after_tool_agents`), which ADK would skip once the cap answered. ADK's Claude and OpenAI Responses adapters send only a result's `content`, else its `result`, so the plugin also puts the note there (`_note_where_sent`). On Deep Agents, `ToolResultCapMiddleware` sits between the permission gate and `ToolCallErrorMiddleware`, so an error result is capped too, and reads a `ToolMessage` (its text cut by the cap's string rule, text blocks joined into the first) and each `ToolMessage` of a `Command`. A call of the framework's `read_file` (by identity, as each gate resolves tools) on a saved output is cut without a second save. Saving never fails the call (`tool_output_not_saved` warns once per folder, then debug), and a cap that raises leaves the result uncut (`tool_result_cap_failed` at warning, its traceback at debug). - **Summarizing on ADK (main agent only)**: every app's App (a native ADK YAML app's too, when its root's model has a context budget) has ADK's `EventsCompactionConfig` with `workflow/adk/compaction.py::AgentCliSummarizer` at the root's trigger (`context_budget`, as on Deep Agents); ADK checks before every agent's model call, and `MainAgentPlugin` (the first plugin) records the running agent in a ContextVar, so the summarizer writes only for the root (a sub-agent's run, on its type's runner, has no compaction config at all: a sub-agent compacting the shared session lost its brief and looped, 100 requests in one turn, offline). The summarizer picks its own range before paying for anything (`summary_range`: the newest `keep` tokens and the current turn kept, a cut only where a user turn starts, never parting a call from its result, long-running calls excepted since ADK re-injects them, nor leaving a kept event stamped inside the range; none for a saving under 20% of the trigger, the seed left out of it), writes on the root's own model (`_simple_model(SUMMARY_MAX_TOKENS, agent=root)`, thinking off) with `workflow/summary_prompt.py`, the rendering sized to that model's window (the middle cut, `MIDDLE_OMITTED`, the seed kept whole), and returns **user-role** text starting `SUMMARY_PREFIX` (a model-role first message is one Claude refuses), which the fit guard folds, after the memory index when the request has one, into the next user text (`fold_summary`), so no request holds two user messages in a row. `last_kept_turns` and `last_error` are for its callers: a manual summarizer warns of nothing itself. It reports through the turn's live events (`_run_and_stream` iterates the runner through `live_events.merged` under `reporting(live)`); any failure is one recoverable `ERROR` a turn, never raised to ADK. `NoAfterTurnCompactionRunner` overrides ADK's private `Runner._run_post_invocation_compaction` (contract-tested), so the prompt never waits for a summary after the answer. `FitGuardPlugin` is the last plugin (but `SentRequestLoggingPlugin`, which logs a request as sent, and `CallSentPlugin`, which starts the call's clock) and `OverflowPlugin` the one before it (`MemoryIndexPlugin`, when the root has a memory tool and `memory_index_enabled` is on, the one before that: it puts the conversation's memory index snapshot first in the root's requests, never in the session): the guard leaves a request's oldest turns out when it is over its agent's budget (keeping the newest turn and what opens the conversation, the memory index then a summary: `protected_head`) and keeps each request as it came in (`request_as_seen`: one copy per model call, under the call's `EventActions`, which ADK passes to all three of its callbacks: each sub-agent run is an invocation of its own on a child session, but two runs of one type share that type's runner and its plugins, and a run drops only what its own cancelled calls left, as it ends), and the overflow handler, on a provider's overflow, summarizes now (the root, through `compact_session`, ADK's private `_run_compaction_for_token_threshold_config`; `_summarize_now` returns `WrittenSummary(text, kept_turns)`, and the retry is the index, the summary and those turns) or trims to half the budget (a sub-agent, or nothing to summarize), builds the retry from the guard's copy without the context cache, retries once on the agent's `canonical_model`, then answers the root with `LlmResponse(error_code="CONTEXT_OVERFLOW")`, never model text (ADK would store it as the reply), which `ADKEventProcessor` maps to the turn's `ERROR`; a retry that fails otherwise propagates, and `_run_and_stream` unwraps ADK's plugin-manager `RuntimeError` to the provider's error; a sub-agent's call that still does not fit is answered with an error response too, `CONTEXT_OVERFLOW` and `subagent_overflow_message`, which its run's processor keeps as the run's failure: the run ends `failed` with those words (`RunFailed`), its parent reads them in the envelope, and the user is warned once, by the framework's delegation (`agents/delegate.py`), as on Deep Agents. A native ADK YAML app gets all of it: only the building of its agents differs (`workflow/adk/build.py`). Its chat-mode sub-agents keep transferring, and an agent the root transfers to replies to the user (`build.reply_agents`: its text is the reply, recent_messages reads it, its overflow is the turn's clear error, its calls write the outside-content mark); the summary and the memory index stay the root's, so such an agent is trimmed by the fit guard, not summarized. An agent's own callbacks (a native app's) run after every plugin, and only when none answered: its before-model callbacks see the request after the fit guard, and the cap leaves out an agent with after-tool callbacks. A main agent whose model does not resolve through the catalog has no budget and no summary. -- **Sub-agents delegate and return**: on both backends a sub-agent run is a call of its parent's `task` tool (the framework's: `tools/_core/delegation.py` declares it, `workflow/agents/delegate.py` runs it) that returns in the same turn; only the root replies to the user (a sub-agent's `TEXT` carries `metadata["subagent"]`, and the CLI shows it as the events box's status line, under its run's name: `researcher-2 › …`; `/agents` lists a conversation's runs), and the next turn starts at the root; fact extraction reads only the user's and the root's text. `task` takes `agent_type` (one of the caller's own sub-agents) and a brief (`workflow/agents/brief.py`: `title`, `objective`, `deliverable`, `constraints`, `known`, `done_when`), its schema and description the same on both backends (`task_parameters`, `task_description`: a line per type with its description, "The agent." with a warning, `subagent_without_description`, for one without, and the fields `AgentConfig.brief_required` asks for); `read_brief` checks a call against them, and one that cannot start a run is the call's `{"success": false, "error": …}`, no run started or numbered. `Delegations.delegate` (the manager's `_delegations`) does the rest, alike on both: it names the run (`AgentRuns.run_for`), reports its `AGENT_RUN` start (title, brief, `started_by`, `mode`) and end through the turn's live events and the records, and runs the backend's hook, `_run_agent(AgentRun)`, in a task of its own, where the run is the active run and no tool call is, so each run ends at its own end. The run's first message is the task message (`task_message`); it starts from the conversation's `plan` and `tasks` (`AgentRun.state`), and the keys it changed come back to its caller's state (`RunAnswer.state`). It ends as the `RunAnswer` says: its last text (a reply that also called a tool included; none at all, an empty result shown `No answer`), `refused` or `partial` by the outcome mark, `failed` for an error or a raise (one recoverable `ERROR`, ` failed: `, or the hook's own words, `RunFailed`: an overflow's); and the call's result is the run's envelope as JSON (`workflow/agents/envelope.py`), shown by `show_as_delegation`. A cancel of the caller's task stops the run's task first and ends the run `interrupted`. Each run works under its `RunControl` (`workflow/agents/control.py`, `AgentRun.control`), with its type's `AgentConfig.limits` over the policy's (`SubAgentPolicy.limits`, `DEFAULT_LIMITS`: 100 model calls): `Delegations.cancel(run_id, by=, error=)` cancels the run alone (its parent, the user or a limit), and the hook, seeing its own cancel (`own_cancel`), stops the run as a stopped turn's (ADK: its abort signal, its open calls sealed in its child session; Deep Agents: its stream closed) and returns what it has: the run ends `cancelled` with `cancelled_by` and that text, `partial`, while its siblings and the turn go on; the turn's own cancel still wins (`interrupted`). Past its `timeout` (counted from when its hook starts, `timing`) the run is cancelled by its limit (`time limit reached`); each model call is counted before it is made (`RunControlPlugin` in each sub-agent chain, `RunControlMiddleware` on each sub-agent's model side) and the last allowed one gets `STEP_LIMIT_NOTE` after its last message, its tools still declared (Claude refuses tool calls in a request that defines no tools); its answer's calls are dropped, never run, so the run completes `partial`, `step limit reached`; each call's tokens are counted after it, and past `max_tokens` that answer, its calls dropped, is the run's last, `cancelled` by its limit (`token limit reached`). A turn starts at most `max_runs_per_turn` runs, at any depth (`sessions.runs_this_turn`): a call past it is the error result, no run started; `task`'s description says so (`limit_sentences`). A message steered to a working run (`RunControl.steer`, through `Delegations.control(run)`) is added after its last message, as the user's, before its next model call, and stays in its transcript (ADK: appended to its child session; Deep Agents: added to its state). A dialog whose run is stopped is withdrawn, the turn going on (`MessageProcessor`). `AgentConfig.inherit_context` sets what a run sees: False (the default) its task alone, True its parent's conversation too, read once as the run starts (the conversation after any summary, less the message that called `task`), before the task message, which then ends with `INHERITED_CONTEXT_NOTE` (whose conversation it reads, which message is its task); `validate_agent_graph` refuses a value that is not True or False, `inherit_context=True` on the root and, in 0.7.0, on an agent with sub-agents or below another sub-agent. On ADK (`workflow/adk/task_tool.py::TaskTool`) every config-built agent is built on its own, with no ADK `sub_agents`, so ADK offers none `transfer_to_agent`, and gets ADK's identity line ("You are an agent. Your internal name is …"); a delegating agent has one `TaskTool`. Each sub-agent type runs on its own runner (`App(name=child_app(app_name))`, the type's agent its root, `_agent_plugin_chain`: the main chain configured for a sub-agent, no memory index, no summary, `RunControlPlugin` and `SubAgentOutcomePlugin`; every plugin's per-call state keyed by invocation) over the manager's session service, on a child session per run (`child_session_id`: `/`; an inheriting run's gets the conversation's events copied, `task_tool.inherited_events`), under an app no conversation list reads. On Deep Agents (`workflow/deepagents/task_tool.py::build_task_tool`) each type's graph is built on its own, and a run `astream`s it in its task with `var_child_runnable_config` cleared, so its chunks reach its own loop alone, never its parent's stream; an inheriting run's history is the parent's messages with Deep Agents' summary event applied (`SummarizationMiddleware._apply_event_to_messages`, private: `tests/workflow/deepagents/test_compact.py` pins it), and `ForeignReasoningMiddleware(kind, agent=...)` leaves out the reasoning of AI messages another agent wrote. A native ADK YAML app keeps transferring (chat-mode sub-agents); a task-mode agent in one is refused at validation, since ADK runs its delegation outside the tool pipeline and keeps the call open across turns. +- **Sub-agents delegate and return**: on both backends a sub-agent run is a call of its parent's `task` tool (the framework's: `tools/_core/delegation.py` declares it, `workflow/agents/delegate.py` runs it) that returns in the same turn; only the root replies to the user (a sub-agent's `TEXT` carries `metadata["subagent"]`, and the CLI shows it as the events box's status line, under its run's name: `researcher-2 › …`; `/agents` lists a conversation's runs), and the next turn starts at the root; fact extraction reads only the user's and the root's text. `task` takes `agent_type` (one of the caller's own sub-agents) and a brief (`workflow/agents/brief.py`: `title`, `objective`, `deliverable`, `constraints`, `known`, `done_when`), its schema and description the same on both backends (`task_parameters`, `task_description`: a line per type with its description, "The agent." with a warning, `subagent_without_description`, for one without, and the fields `AgentConfig.brief_required` asks for); `read_brief` checks a call against them, and one that cannot start a run is the call's `{"success": false, "error": …}`, no run started or numbered. `Delegations.delegate` (the manager's `_delegations`) does the rest, alike on both: it names the run (`AgentRuns.run_for`), reports its `AGENT_RUN` start (title, brief, `started_by`, `mode`) and end through the turn's live events and the records, and runs the backend's hook, `_run_agent(AgentRun)`, in a task of its own, where the run is the active run and no tool call is, so each run ends at its own end. The run's first message is the task message (`task_message`); it starts from the conversation's `plan` and `tasks` (`AgentRun.state`), and the keys it changed come back to its caller's state (`RunAnswer.state`). It ends as the `RunAnswer` says: its last text (a reply that also called a tool included; none at all, an empty result shown `No answer`), `refused` or `partial` by the outcome mark, `failed` for an error or a raise (one recoverable `ERROR`, ` failed: `, or the hook's own words, `RunFailed`: an overflow's); and the call's result is the run's envelope as JSON (`workflow/agents/envelope.py`), shown by `show_as_delegation`. A cancel of the caller's task stops the run's task first and ends the run `interrupted`. Each run works under its `RunControl` (`workflow/agents/control.py`, `AgentRun.control`), with its type's `AgentConfig.limits` over the policy's (`SubAgentPolicy.limits`, `DEFAULT_LIMITS`: 100 model calls): `Delegations.cancel(run_id, by=, error=)` cancels the run alone (its parent, the user or a limit), and the hook, seeing its own cancel (`own_cancel`), stops the run as a stopped turn's (ADK: its abort signal, its open calls sealed in its child session; Deep Agents: its stream closed) and returns what it has: the run ends `cancelled` with `cancelled_by` and that text, `partial`, while its siblings and the turn go on; the turn's own cancel still wins (`interrupted`). Past its `timeout` (counted from when its hook starts, `timing`) the run is cancelled by its limit (`time limit reached`); each model call is counted before it is made (`RunControlPlugin` in each sub-agent chain, `RunControlMiddleware` on each sub-agent's model side) and the last allowed one gets `STEP_LIMIT_NOTE` after its last message, its tools still declared (Claude refuses tool calls in a request that defines no tools); its answer's calls are dropped, never run, so the run completes `partial`, `step limit reached`; each call's tokens are counted after it, and past `max_tokens` an answer that makes tool calls is the run's last, its calls dropped, `cancelled` by its limit (`token limit reached`), while one that makes none ends the run as it would, `completed`, its result whole (a model that reports no usage is not limited by tokens). A turn starts at most `max_runs_per_turn` runs, at any depth (`sessions.runs_this_turn`): a call past it is the error result, no run started; `task`'s description says so (`limit_sentences`). A message steered to a working run (`RunControl.steer`, through `Delegations.control(run)`) is added after its last message, as the user's, before its next model call, and stays in its transcript (ADK: appended to its child session, the run's later events stamped after it so a durable store reads them back in order; Deep Agents: added to its state); a sub-agent run's task message is never trimmed, on ADK neither by the fit guard nor by the overflow handler's retry, whatever was steered after it. A dialog whose run is stopped is withdrawn, the turn going on (`MessageProcessor`). `AgentConfig.inherit_context` sets what a run sees: False (the default) its task alone, True its parent's conversation too, read once as the run starts (the conversation after any summary, less the message that called `task`), before the task message, which then ends with `INHERITED_CONTEXT_NOTE` (whose conversation it reads, which message is its task); `validate_agent_graph` refuses a value that is not True or False, `inherit_context=True` on the root and, in 0.7.0, on an agent with sub-agents or below another sub-agent. On ADK (`workflow/adk/task_tool.py::TaskTool`) every config-built agent is built on its own, with no ADK `sub_agents`, so ADK offers none `transfer_to_agent`, and gets ADK's identity line ("You are an agent. Your internal name is …"); a delegating agent has one `TaskTool`. Each sub-agent type runs on its own runner (`App(name=child_app(app_name))`, the type's agent its root, `_agent_plugin_chain`: the main chain configured for a sub-agent, no memory index, no summary, `RunControlPlugin` and `SubAgentOutcomePlugin`; every plugin's per-call state keyed by invocation) over the manager's session service, on a child session per run (`child_session_id`: `/`; an inheriting run's gets the conversation's events copied, `task_tool.inherited_events`), under an app no conversation list reads. On Deep Agents (`workflow/deepagents/task_tool.py::build_task_tool`) each type's graph is built on its own, and a run `astream`s it in its task with `var_child_runnable_config` cleared, so its chunks reach its own loop alone, never its parent's stream; an inheriting run's history is the parent's messages with Deep Agents' summary event applied (`SummarizationMiddleware._apply_event_to_messages`, private: `tests/workflow/deepagents/test_compact.py` pins it), and `ForeignReasoningMiddleware(kind, agent=...)` leaves out the reasoning of AI messages another agent wrote. A native ADK YAML app keeps transferring (chat-mode sub-agents); a task-mode agent in one is refused at validation, since ADK runs its delegation outside the tool pipeline and keeps the call open across turns. - **Token usage**: every model call the framework makes is one `LLM_USAGE`, on both backends, side calls included (`generate_simple`: `summarize`'s, `purpose` `tool`; `on_session_end`'s, `memory_extraction`, outside any turn; an app's own, `side_call`, or what its caller names with `workflow/usage.py::side_call`), its counts normalized where it is made (`normalized_tokens`: `prompt_tokens` every input token, cache reads and writes included; `completion_tokens` every output token, thinking included; ADK's read by its model's provider kind, `adk_usage_event`/`adk_tokens`, since Gemini and ADK's Claude adapter keep the thinking apart from the candidates and OpenAI's count it inside, an agent of no known kind read as apart; Deep Agents' by LangChain's one convention, `langchain_tokens`; the raw log's usage records alike), and timed (`latency_ms`: on ADK from the request to the answer, `workflow/adk/call_clock.py`'s plugins marking the answer's `custom_metadata`; on Deep Agents by the turn's `RunCallback`, which marks the answer's `response_metadata["agentic_cli"]`, beside the outcome mark; a side call, a summary and the overflow retry around their own request; no adapter sends either mark). Each is recorded in its conversation's ledger (`UsageLedger`; `BaseWorkflowManager.usage`/`usage_of`, in memory for the manager's life: a backend switch's new manager starts afresh, as with `agent_runs`) where it is made, before `on_event` (the event processors, ADK's summarizer, as soon as its call answers, Deep Agents' `RunCallback`, `_report_side_call`), under the run it is made in and its conversation's turn while one runs (as the manager counts them, `/compact` and job notices included: not `SessionInfo.turns`; none in another conversation's turn or from a task its turn outlived, which `_report_side_call` reports to no one); a sub-agent run's `AGENT_RUN` end carries what it used, by model (`metadata["usage"]`, `RunRecord.usage`). The CLI's status bar sums the events it sees (the open conversation's total, on any backend); `/status` shows the ledger by agent. LangGraph (deprecated) records no ledger. - **Tool registration**: Use `@register_tool(category=..., capabilities=..., description=...)` decorator. `capabilities=` is required — pass `EXEMPT` for tools that need no permission check or a list of `Capability(name, target_arg=...)` tuples the engine matches against rules. Tools are auto-discovered via the global `ToolRegistry`. A tool in `AgentConfig.tools` that the registry did not issue is denied at every call; building the agents names it once (`tool_not_registered`, per agent and tool: `BaseWorkflowManager._name_unregistered`): a plain callable, a `FunctionTool`/`StructuredTool` judged by the function it runs (as the gates unwrap it), an app's own tool class; ADK's own tool objects excepted (a built-in runs inside the model). `outside_content=True` (or a function of the call's arguments) declares that a call brings content from outside the user and the project into the conversation (a page, a document, a program's output): once the gate allows one, a memory write in that conversation is approved per call (see Permissions); an application's tools are unmarked unless they declare it, and a variant must declare the same flag as its tool. - **Async tools never block the event loop**: a synchronous tool runs on a worker thread on both backends; an async tool runs on the event loop itself, where a blocking call (DNS, a connect, a file lock's wait, a sleep, a subprocess wait, PDF parsing, page conversion, embedding) freezes the whole app, Ctrl+C included. An async tool runs its slow work with `asyncio.to_thread`. `tests/tools/test_async_tools_never_block.py` lists every async tool (the registry's, the factories' service-bound variants, Deep Agents' skill tools), so a new one fails until it is listed, and calls each through the loop guard (`tests/loop_guard.py`). diff --git a/README.md b/README.md index 75f51b9a..a052023a 100644 --- a/README.md +++ b/README.md @@ -1378,10 +1378,12 @@ reviewer = AgentConfig(name="reviewer", prompt="Check what was said.", 20, at any depth); an agent's own `limits=AgentLimits(...)` lies over the policy's, field by field. A run's last allowed model call is told to answer with what it has, and the run completes `partial` (`step limit - reached`); past its time or its tokens it is `cancelled` (`time limit - reached`, `token limit reached`) with the text it wrote so far, a prompt - it waited at withdrawn; a `task` call past the runs a turn may start - starts no run, and the parent reads why. + reached`); past its time, or past its tokens with an answer that asks for + tools, it is `cancelled` (`time limit reached`, `token limit reached`) + with the text it wrote so far, a prompt it waited at withdrawn (an answer + past its tokens that asks for none is its result, and the run completes; + a model that reports no usage is not limited by tokens); a `task` call + past the runs a turn may start starts no run, and the parent reads why. - **A sub-agent's job.** A long-running tool on a sub-agent (a job starter) returns the job's id at once, and the sub-agent answers its parent in the same turn. When the job finishes, the main agent is told, in a message of