From 9a8b376464b2d45a77b00d6592cbcb57c0ec5ec7 Mon Sep 17 00:00:00 2001 From: Andrey Shiryaev <7615137+shoom1@users.noreply.github.com> Date: Fri, 13 Nov 2026 22:37:33 -0500 Subject: [PATCH 1/5] Runs: one end decision; ADK ends a returned delegation from the record A delegation that finished beside a slower one in the same model step had no result event on ADK when the turn was stopped or failed first: ADK hands a step's parallel function responses back in one event, after the last one returns. Its result sat in the record (OpenCalls, under its parent's run) until the turn cleared it, and the base's _turn then marked the run interrupted with no result, where Deep Agents ends it completed. The manager now ends each such run from the record before clearing it (_end_returned_runs, on the stop path after unsealed and on the failure path), through ADKEventProcessor.end_returned_run, so refused and partial still come from the run's outcome mark. The timing difference itself is ADK's and is named in the processor's docstring and the CHANGELOG. The run-end decision both processors wrote out is now one helper, agents/runs.py::run_ended, which the ADK processor, the Deep Agents processor and the new path share. The contract scenario of the two parallel delegations asserts each run's end on both backends. --- CHANGELOG.md | 7 +- .../workflow/adk/event_processor.py | 114 ++++++++++-------- .../workflow/adk/interrupted_calls_plugin.py | 27 ++++- src/agentic_cli/workflow/adk/manager.py | 34 +++++- src/agentic_cli/workflow/agents/runs.py | 51 ++++++++ .../workflow/deepagents/event_processor.py | 48 +++----- tests/workflow/test_subagents_contract.py | 7 +- 7 files changed, 189 insertions(+), 99 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9938da67..466c35f0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -631,7 +631,12 @@ the start of the entry's title. `interrupted`, with the first 200 characters of its result), and each manager records its runs by conversation (`BaseWorkflowManager.agent_runs`, provisional: `records(ref)`, `record(ref, id)`); a run a stopped or failed - turn leaves open is recorded `interrupted`. `get_active_run()` (exported + turn leaves open is recorded `interrupted`. On ADK a delegation that + finished beside a slower one in the same model step ends with the slower + one's (ADK hands a step's parallel function responses back in one event, + after the last), where Deep Agents ends each at its own result; a turn + stopped or failed before then ends it from the record, with its result, + not `interrupted`. `get_active_run()` (exported from `agentic_cli.workflow` with `RunRef` and `root_run`) is the sub-agent run whose call is in progress, None in the root's own: a sub-agent's tools, permission checks and questions see it. A consumer that does not diff --git a/src/agentic_cli/workflow/adk/event_processor.py b/src/agentic_cli/workflow/adk/event_processor.py index 8d954c59..54ad5df3 100644 --- a/src/agentic_cli/workflow/adk/event_processor.py +++ b/src/agentic_cli/workflow/adk/event_processor.py @@ -17,21 +17,11 @@ from agentic_cli.workflow.adk.call_clock import call_latency from agentic_cli.workflow.adk.interrupted_calls_plugin import ABORTED from agentic_cli.workflow.adk.subagent_outcome_plugin import OUTCOME_KEY -from agentic_cli.workflow.agents.outcome import ( - CUT, - REFUSAL_ERROR, - REFUSED, - cut_off_warning, -) +from agentic_cli.workflow.agents.outcome import cut_off_warning from agentic_cli.workflow.agents.runs import ( - RUN_COMPLETED, - RUN_FAILED, - RUN_INTERRUPTED, - RUN_REFUSED, RUN_STARTED, - SUBAGENT_ERROR_PREFIX, AgentRuns, - result_head, + run_ended, run_title, show_as_delegation, ) @@ -132,18 +122,28 @@ class ADKEventProcessor: delegates to one of the calling agent's own single-turn sub-agents (``delegates``, by the caller, the event's author: ADK names the tool after the sub-agent) is followed by the ``AGENT_RUN`` that starts the - sub-agent's run, and its result by the one that ends it: ``failed`` for - ADK's answer for a sub-agent that failed (``Error running sub-agent: - …``) or an error result (``success`` false: the tool raised), with its - error, ``interrupted`` for the seal of a stopped turn, ``refused`` when - ``SubAgentOutcomePlugin`` marked the run's last answer refused, else - ``completed`` (``partial``, and followed by one warning, - ``cut_off_warning``, when it marked the answer cut); the result itself is - shown as on Deep Agents (``agents/runs.py::show_as_delegation``: the - answer's first line, a failed one as a failed result). Any other call is - an ordinary tool call, with no run: a name the caller has no such - sub-agent for runs none (ADK answers an unknown tool). Each ``AGENT_RUN`` - is recorded in ``runs`` as it is made, before ``on_event``. + sub-agent's run, and its result by the one that ends it, as on Deep + Agents (``agents/runs.py::run_ended``): ``failed`` for ADK's answer for + a sub-agent that failed (``Error running sub-agent: …``) or the + framework's error result (a dict that says ``success`` false: the tool + raised, the gate denied it), with its error, ``interrupted`` for the + seal of a stopped turn, ``refused`` when ``SubAgentOutcomePlugin`` + marked the run's last answer refused, else ``completed`` (``partial``, + and followed by one warning, ``cut_off_warning``, when it marked the + answer cut). The sub-agent's answer, which ADK keeps under ``result``, + is never read for success. The result itself is shown as on Deep Agents + (``agents/runs.py::show_as_delegation``: the answer's first line, a + failed one as a failed result). Any other call is an ordinary tool call, + with no run: a name the caller has no such sub-agent for runs none (ADK + answers an unknown tool). Each ``AGENT_RUN`` is recorded in ``runs`` as + it is made, before ``on_event``. + + A delegation that finished beside a slower one in the same model step + ends later than on Deep Agents, which ends each run at its own result: + ADK hands a step's parallel function responses back in one event, after + the last one returns, so the finished run ends with the slower one's. A + turn stopped or failed before then ends it from the record + (``end_returned_run``), with its result, as that event would have. Args: model: The default model, which usage names for an agent ``models`` @@ -415,40 +415,48 @@ def _delegation_run( ) elif response is not None and response.name in own and response.id: child = self.runs.run_for(get_active_turn(), parent, response.id, response.name) - text = _result_text(response.response) - usage = self._run_usage(child) - outcome = self._outcomes.pop(child.run or "", None) - succeeded, error = _outcome(response.response) - if sealed: - event = WorkflowEvent.agent_run( - child, RUN_INTERRUPTED, call_id=response.id, result=result_head(text), - usage=usage, - ) - elif text.startswith(SUBAGENT_ERROR_PREFIX): - event = WorkflowEvent.agent_run( - child, RUN_FAILED, call_id=response.id, result="", - error=text.removeprefix(SUBAGENT_ERROR_PREFIX), usage=usage, - ) - elif not succeeded: - event = WorkflowEvent.agent_run( - child, RUN_FAILED, call_id=response.id, result="", error=error or text, - usage=usage, - ) - elif outcome == REFUSED: - event = WorkflowEvent.agent_run( - child, RUN_REFUSED, call_id=response.id, result=result_head(text), - error=REFUSAL_ERROR, usage=usage, - ) - else: - event = WorkflowEvent.agent_run( - child, RUN_COMPLETED, call_id=response.id, result=result_head(text), - partial=outcome == CUT, usage=usage, - ) + event = self._ended(child, response.id, response.response, sealed=sealed) else: return None self.runs.observe(event) return event + def end_returned_run(self, ref: RunRef, call_id: str, response: Any) -> WorkflowEvent: + """End ``ref``'s run with what its delegation returned, which no event brought; recorded. + + ADK hands a model step's parallel function responses back in one + event, after the last one returns, so a delegation that finished + beside a slower one has no result event until then. A turn stopped + or failed before it ends that run from the record with this + (``GoogleADKWorkflowManager``): as its result would have ended it, + refused or partial from its outcome mark. + + Args: + ref: The run. + call_id: Its parent's call that started it. + response: What the call returned, as ADK stores it (text under + ``result``). + """ + event = self._ended(ref, call_id, response, sealed=False) + self.runs.observe(event) + return event + + def _ended(self, child: RunRef, call_id: str, response: Any, *, sealed: bool) -> WorkflowEvent: + """The ``AGENT_RUN`` that ``response``, a delegation's result, ends ``child``'s run with. + + ``agents/runs.py::run_ended``'s decision: the framework's error + result (a dict that says it failed: the tool raised, the gate denied + it) fails it, never the sub-agent's answer, which ADK keeps under + ``result``. + """ + succeeded, error = _outcome(response) + return run_ended( + child, call_id, _result_text(response), + failed=not succeeded, error=error, + outcome=self._outcomes.pop(child.run or "", None), + usage=self._run_usage(child), sealed=sealed, + ) + def process_part(self, part: Any, session_id: str) -> WorkflowEvent | None: """Process a single part from the agent response. diff --git a/src/agentic_cli/workflow/adk/interrupted_calls_plugin.py b/src/agentic_cli/workflow/adk/interrupted_calls_plugin.py index a2165e9c..e787e17d 100644 --- a/src/agentic_cli/workflow/adk/interrupted_calls_plugin.py +++ b/src/agentic_cli/workflow/adk/interrupted_calls_plugin.py @@ -89,6 +89,12 @@ class _Finished: artifact_delta: dict[str, Any] cut: Any = None + @property + def read(self) -> Any: + """What the model reads of the result: the cap's cut, else the result + (never cut again, which would save its full output a second time).""" + return self.result if self.cut is None else self.cut + class InterruptedCallsPlugin(BasePlugin): """Answer the calls a cancelled turn leaves open (``workflow/interrupts.py``). @@ -222,18 +228,27 @@ def _branch(tool_context: Any) -> str | None: def _from_record(open_calls: OpenCalls, call_id: str | None, run: str | None, actions: Any) -> Any: """A stopped turn's call answered from the record, as ``run``'s. - A finished call keeps what the model would have read: the cap's cut, or - the result as it was (never cut again, which would save its full output - a second time); the state it changed goes into ``actions``, stored with - the answer as with its result. Any other is answered as - ``OpenCalls.answer`` says. + A finished call keeps what the model would have read (``_Finished.read``); + the state it changed goes into ``actions``, stored with the answer as + with its result. Any other is answered as ``OpenCalls.answer`` says. """ answer = open_calls.answer(call_id, by_user=True, run=run) if not isinstance(answer, _Finished): return answer actions.state_delta.update(answer.state_delta) actions.artifact_delta.update(answer.artifact_delta) - return answer.result if answer.cut is None else answer.cut + return answer.read + + +def returned(open_calls: OpenCalls, call_id: str | None, run: str | None) -> dict[str, Any] | None: + """What the call ``call_id`` of ``run`` returned, from the record; None if it did not finish. + + As ADK stores the result (text under ``result``), and as the model reads + it (the cap's cut): what the manager ends a delegation's run with when + no event brought its result (``ADKEventProcessor.end_returned_run``). + """ + finished = open_calls.recorded(call_id, run=run) + return _as_response(finished.read) if isinstance(finished, _Finished) else None def _as_response(result: Any) -> dict[str, Any]: diff --git a/src/agentic_cli/workflow/adk/manager.py b/src/agentic_cli/workflow/adk/manager.py index c00a32e2..ca0e5d4e 100644 --- a/src/agentic_cli/workflow/adk/manager.py +++ b/src/agentic_cli/workflow/adk/manager.py @@ -51,6 +51,7 @@ from agentic_cli.workflow.adk.interrupted_calls_plugin import ( InterruptedCallsPlugin, left_open, + returned, unsealed, ) from agentic_cli.workflow.adk.model_factory import build_adk_model, generate_text @@ -63,6 +64,7 @@ turn_state, ) from agentic_cli.workflow.adk.tool_result_cap_plugin import ToolResultCapPlugin +from agentic_cli.workflow.agents.runs import RUN_STARTED from agentic_cli.workflow.outside_content import ( BEFORE_0_7_0, JOB_RESULT, @@ -1134,9 +1136,11 @@ async def _answer_unsealed(self, ref: SessionRef) -> None: call by id alone, so a call whose id a sub-agent's result used is left open (``interrupted_calls_plugin.unsealed``): answered here, a finished one keeps its result and one at its prompt was not run. - Run shielded, so a second Ctrl+C neither loses the answers nor - clears the record before they are read. Answers that cannot be - written are given at the next turn (``left_open``), from no record. + Then each open run whose delegation returned ends with its result + (``_end_returned_runs``), before the record is cleared. Run + shielded, so a second Ctrl+C neither loses the answers nor clears + the record before they are read. Answers that cannot be written are + given at the next turn (``left_open``), from no record. """ try: session = await self._session_service.get_session( @@ -1157,8 +1161,28 @@ async def _answer_unsealed(self, ref: SessionRef) -> None: "unsealed_calls_not_answered", error_type=type(error).__name__, exc_info=error, ) finally: + self._end_returned_runs(ref) self._open_calls.clear(ref) + def _end_returned_runs(self, ref: SessionRef) -> None: + """End, from the record, each open run whose delegation returned; before the record is cleared. + + ADK hands a model step's parallel function responses back in one + event, after the last one returns, so a delegation that finished + beside a slower one has no result event when the turn is stopped or + fails first. Its result is in the record, under its parent's run: + its run ends as that result says (``end_returned_run``: refused or + partial from its outcome mark), and not ``interrupted`` with the + runs the turn leaves open (the base's ``_turn``). Called after + ``unsealed``, which names each branch's run while it is open. + """ + for record in self.agent_runs.records(ref): + if record.status != RUN_STARTED or not record.call_id: + continue + response = returned(self._open_calls, record.call_id, record.ref.parent_run) + if response is not None: + self._event_processor.end_returned_run(record.ref, record.call_id, response) + def _seed_outside_content(self, ref: SessionRef, session: Session) -> dict[str, Any]: """Seed the marks from the session's state; the state delta a turn writes. @@ -1313,7 +1337,8 @@ async def _run_and_stream( # id alone): it is answered here, from the record, before the # record is cleared. One a failure left open is answered at # the next turn (left_open) as interrupted: the state it - # changed, which ADK stores with its result, is gone. + # changed, which ADK stores with its result, is gone. Either + # way a delegation that returned ends its run with its result. ref = self.session_ref(session_id, user_id) if aborted.is_set(): # Should those answers not be written, left_open gives @@ -1321,6 +1346,7 @@ async def _run_and_stream( self._open_calls.cancelled(ref) await asyncio.shield(self._answer_unsealed(ref)) else: + self._end_returned_runs(ref) self._open_calls.clear(ref) # Drain any remaining LLM events after processing completes diff --git a/src/agentic_cli/workflow/agents/runs.py b/src/agentic_cli/workflow/agents/runs.py index 0c2e9b34..df0a55f5 100644 --- a/src/agentic_cli/workflow/agents/runs.py +++ b/src/agentic_cli/workflow/agents/runs.py @@ -25,6 +25,7 @@ from datetime import datetime from typing import Any +from agentic_cli.workflow.agents.outcome import CUT, REFUSAL_ERROR, REFUSED from agentic_cli.workflow.events import EventType, WorkflowEvent from agentic_cli.workflow.sessions import RunRef, SessionRef, get_active_turn from agentic_cli.workflow.tool_summaries import delegation_summary @@ -72,6 +73,56 @@ def run_label(ref: RunRef | None) -> str | None: return f"{ref.instance} ({ref.agent}, run {ref.run.rpartition('#')[2]})" +def run_ended( + ref: RunRef, + call_id: str | None, + answer: str, + *, + failed: bool = False, + error: str | None = None, + outcome: str | None = None, + usage: dict[str, dict[str, int]] | None = None, + sealed: bool = False, +) -> WorkflowEvent: + """The ``AGENT_RUN`` that ends ``ref``'s run, decided as on every backend. + + ``answer`` is the delegation's result as its parent read it; ``failed`` + says it is the framework's own error result (``error``: its error), and + ``outcome`` is the mark the backend's hook put on the run's last answer + (``agents/outcome.py``). The run ends: + + - ``interrupted`` for the seal of a call a stopped turn left open + (``sealed``), with its result; + - ``failed`` for ``Error running sub-agent: `` (its error the + reason), or for the framework's error result (its error, else the + answer); + - ``refused`` when the outcome is ``REFUSED``; + - else ``completed``, ``partial`` when the outcome is ``CUT``. + """ + if sealed: + return WorkflowEvent.agent_run( + ref, RUN_INTERRUPTED, call_id=call_id, result=result_head(answer), usage=usage, + ) + if answer.startswith(SUBAGENT_ERROR_PREFIX): + return WorkflowEvent.agent_run( + ref, RUN_FAILED, call_id=call_id, result="", + error=answer.removeprefix(SUBAGENT_ERROR_PREFIX), usage=usage, + ) + if failed: + return WorkflowEvent.agent_run( + ref, RUN_FAILED, call_id=call_id, result="", error=error or answer, usage=usage, + ) + if outcome == REFUSED: + return WorkflowEvent.agent_run( + ref, RUN_REFUSED, call_id=call_id, result=result_head(answer), + error=REFUSAL_ERROR, usage=usage, + ) + return WorkflowEvent.agent_run( + ref, RUN_COMPLETED, call_id=call_id, result=result_head(answer), + partial=outcome == CUT, usage=usage, + ) + + def show_as_delegation(result: WorkflowEvent, answer: str, ended: WorkflowEvent) -> None: """Show a delegation's ``TOOL_RESULT`` as every backend shows it. diff --git a/src/agentic_cli/workflow/deepagents/event_processor.py b/src/agentic_cli/workflow/deepagents/event_processor.py index 4d407978..5a0e5471 100644 --- a/src/agentic_cli/workflow/deepagents/event_processor.py +++ b/src/agentic_cli/workflow/deepagents/event_processor.py @@ -59,15 +59,11 @@ from agentic_cli.constants import truncate from agentic_cli.tools._core.delegation import TASK_TOOL from agentic_cli.tools._core.tasks import task_progress_data -from agentic_cli.workflow.agents.outcome import CUT, REFUSAL_ERROR, REFUSED, cut_off_warning +from agentic_cli.workflow.agents.outcome import cut_off_warning from agentic_cli.workflow.agents.runs import ( - RUN_COMPLETED, - RUN_FAILED, - RUN_REFUSED, RUN_STARTED, - SUBAGENT_ERROR_PREFIX, AgentRuns, - result_head, + run_ended, run_title, show_as_delegation, ) @@ -359,39 +355,23 @@ def _started(self, call: dict, parent: RunRef) -> WorkflowEvent | None: def _ended(self, message: ToolMessage, run: RunRef) -> WorkflowEvent | None: """The ``AGENT_RUN`` the result of a ``task`` call ``run`` made ends, recorded; else None. - ``failed`` for ``Error running sub-agent: `` (its ``error`` - the reason) or another error result (an error message, or one that - says ``success`` false: its error), ``refused`` when - ``SubAgentOutcomeMiddleware`` marked the run's last answer refused, - else ``completed`` (``partial`` when it marked the answer cut). + ``agents/runs.py::run_ended``'s decision, as on ADK: ``failed`` for + ``Error running sub-agent: `` (its ``error`` the reason) or + another error result (an error message, or one that says ``success`` + false: its error), ``refused`` when ``SubAgentOutcomeMiddleware`` + marked the run's last answer refused, else ``completed`` (``partial`` + when it marked the answer cut). """ child = self._delegated.pop((run.run, message.tool_call_id), None) if child is None: return None - outcome = self._outcomes.pop(child.run or "", None) - text = message.text - usage = self._ledgers.ledger(get_active_turn()).run_usage(child.run or "") _, succeeded, error = _result_of(message) - if text.startswith(SUBAGENT_ERROR_PREFIX): - event = WorkflowEvent.agent_run( - child, RUN_FAILED, call_id=message.tool_call_id, result="", - error=text.removeprefix(SUBAGENT_ERROR_PREFIX), usage=usage, - ) - elif not succeeded: - event = WorkflowEvent.agent_run( - child, RUN_FAILED, call_id=message.tool_call_id, result="", - error=error or text, usage=usage, - ) - elif outcome == REFUSED: - event = WorkflowEvent.agent_run( - child, RUN_REFUSED, call_id=message.tool_call_id, result=result_head(text), - error=REFUSAL_ERROR, usage=usage, - ) - else: - event = WorkflowEvent.agent_run( - child, RUN_COMPLETED, call_id=message.tool_call_id, result=result_head(text), - partial=outcome == CUT, usage=usage, - ) + event = run_ended( + child, message.tool_call_id, message.text, + failed=not succeeded, error=error, + outcome=self._outcomes.pop(child.run or "", None), + usage=self._ledgers.ledger(get_active_turn()).run_usage(child.run or ""), + ) self._runs.observe(event) return event diff --git a/tests/workflow/test_subagents_contract.py b/tests/workflow/test_subagents_contract.py index b7fee5d1..9870865a 100644 --- a/tests/workflow/test_subagents_contract.py +++ b/tests/workflow/test_subagents_contract.py @@ -1014,7 +1014,8 @@ async def test_after_ctrl_c_a_finished_sibling_of_a_delegation_keeps_its_result( async def test_after_ctrl_c_a_finished_delegation_keeps_its_result(self, make_crew): """Two delegations run side by side, each sub-agent using the other's call id: the one that finished keeps its sub-agent's answer, the - other is answered as the user's, each once.""" + other is answered as the user's, each once. The finished one's run + ends completed with its result, the other's interrupted.""" crew = make_crew( [ agent("coordinator", sub_agents=("researcher", "waiter")), @@ -1034,8 +1035,12 @@ async def test_after_ctrl_c_a_finished_delegation_keeps_its_result(self, make_cr await until(lambda: crew.recorded("c1")) finally: await crew.stop(turn) + ended = [(r.ref.run, r.status, r.result) for r in crew.records()] await crew.turn("Never mind.") + assert ended == [ + ("researcher-1#1", RUN_COMPLETED, "X is 42."), ("waiter-1#1", RUN_INTERRUPTED, ""), + ] assert sorted(crew.result_ids("coordinator")) == ["c1", "c2"] answered = crew.results_read("coordinator") assert answered["c1"] == "X is 42." From 742eeec43d81532384a5e2e7a6750daed9243816 Mon Sep 17 00:00:00 2001 From: Andrey Shiryaev <7615137+shoom1@users.noreply.github.com> Date: Fri, 13 Nov 2026 22:39:07 -0500 Subject: [PATCH 2/5] Deep Agents: a sub-agent's answer is never read for success Deep Agents' processor parsed a task call's result text as JSON, so a sub-agent whose answer was JSON saying {"success": false, ...} ended its run failed and showed "Failed: ...", while ADK, which keeps the answer under "result", completed it. The rule is now the same on both: a run fails on "Error running sub-agent: ..." or the framework's own error result (on Deep Agents an error ToolMessage, the gate's or the error middleware's), and the answer itself is never read for success (_delegation_result), for the run's end and for its TOOL_RESULT. A contract scenario runs that answer on both backends (run completed, result shown as the answer); the unit test that ended such an answer failed now gives the framework's error shape (status "error"), and a new one checks the answer case. --- CHANGELOG.md | 6 ++- CLAUDE.md | 2 +- src/agentic_cli/workflow/agents/runs.py | 4 ++ .../workflow/deepagents/event_processor.py | 39 ++++++++++++++----- .../workflow/deepagents/test_run_identity.py | 19 ++++++++- tests/workflow/test_subagents_contract.py | 25 ++++++++++++ 6 files changed, 81 insertions(+), 14 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 466c35f0..0494b9de 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -628,7 +628,11 @@ the start of the entry's title. run's start and end are an event of their own, `EventType.AGENT_RUN` (`WorkflowEvent.agent_run`; `metadata["status"]` `started`, with its title, the first line of its request, then `completed`, `failed` or - `interrupted`, with the first 200 characters of its result), and each + `interrupted`, with the first 200 characters of its result; a run fails + on `Error running sub-agent: …` or the framework's own error result, an + error `ToolMessage` on Deep Agents, the error dict of a raised or denied + call on ADK, and the sub-agent's answer is never read for success, so an + answer that is JSON saying it failed completes), and each manager records its runs by conversation (`BaseWorkflowManager.agent_runs`, provisional: `records(ref)`, `record(ref, id)`); a run a stopped or failed turn leaves open is recorded `interrupted`. On ADK a delegation that diff --git a/CLAUDE.md b/CLAUDE.md index d546a5af..3a40c988 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -112,7 +112,7 @@ agentic-cli/ │ │ │ ├── agent_builder.py # build_agent_tree: one create_agent per AgentConfig, bottom-up; task via SubAgentMiddleware (inherit_context = a fork) │ │ │ ├── middleware.py # InterruptedCallsMiddleware (each call recorded and answered as the active run's), PermissionMiddleware, ToolResultCapMiddleware, ToolCallErrorMiddleware (a failed task call: ADK's "Error running sub-agent: " and a live recoverable ERROR, an overflow's in ADK's words), ActiveToolCallMiddleware (a task call to one of the agent's own sub-agents is also the active run of the sub-agent it starts), 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 │ │ │ ├── tools.py # to_langchain_tools: a callable → StructuredTool whose .func/.coroutine is it -│ │ │ ├── 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; by agent and run: a namespace's run from the tasks stream's task call; AGENT_RUN at a task call to one of the caller's own sub-agents (any other type runs none: no run) and at its result (failed: an error result; refused, or partial with one warning, by SubAgentOutcomeMiddleware's mark), recorded in the manager's runs; the task call's TOOL_RESULT shown as on ADK: show_as_delegation; a failed turn names the innermost failure no task call answered); 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) +│ │ │ ├── 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; by agent and run: a namespace's run from the tasks stream's task call; AGENT_RUN at a task call to one of the caller's own sub-agents (any other type runs none: no run) and at its result (failed: an error ToolMessage, the sub-agent's answer never read for success, as on ADK; refused, or partial with one warning, by SubAgentOutcomeMiddleware's mark), recorded in the manager's runs; the task call's TOOL_RESULT shown as on ADK: show_as_delegation; a failed turn names the innermost failure no task call answered); 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) │ │ │ ├── sessions.py # thread_id(SessionRef), CheckpointSessions (rows from an index in the store beside the checkpointer, written as a turn starts (its input counted: a killed process still lists it), then from the newest root checkpoint as it ends and after /compact; a database from before it scanned once per app and user), job notifications; open_sessions: a store's conversations for a reader, without the manager (empty without the checkpoints table, looked at read-only before any setup) │ │ │ ├── summarization.py # Each agent's thresholds from its budget (the manager's _budgets, given to build_agent_tree(budgets=); context_budget when none); NoArchiveBackend; history filters; compact()'s cut, summary and event (marked: the count reported before it is no trigger, _should_summarize); OverflowMapped: the summary model's overflows as ContextOverflowError, inside its retry; a request's count includes the memory index (index=), and a summary written drops its snapshot before the request goes on (on_written=) │ │ │ ├── mcp_tools.py # MCPSessions: one owner task per (agent, server); the mcp identity map; a call fails once its session ends (_while_open: mcp's stdio client can leave one unanswered) diff --git a/src/agentic_cli/workflow/agents/runs.py b/src/agentic_cli/workflow/agents/runs.py index df0a55f5..3cbf4a00 100644 --- a/src/agentic_cli/workflow/agents/runs.py +++ b/src/agentic_cli/workflow/agents/runs.py @@ -98,6 +98,10 @@ def run_ended( answer); - ``refused`` when the outcome is ``REFUSED``; - else ``completed``, ``partial`` when the outcome is ``CUT``. + + The sub-agent's answer is never read for success: each backend tells + ``failed`` from its own error result alone, so an answer that looks + like a failed result completed. """ if sealed: return WorkflowEvent.agent_run( diff --git a/src/agentic_cli/workflow/deepagents/event_processor.py b/src/agentic_cli/workflow/deepagents/event_processor.py index 5a0e5471..1f10890d 100644 --- a/src/agentic_cli/workflow/deepagents/event_processor.py +++ b/src/agentic_cli/workflow/deepagents/event_processor.py @@ -31,7 +31,8 @@ call the ``tasks`` stream announced; a turn's own ``ERROR`` names none. A ``task`` call to one of the calling agent's own sub-agents is followed by the ``AGENT_RUN`` that starts its run, and its result by the one that ends it -(``failed`` for an error result, with its error), the result shown as on ADK +(``failed`` for the framework's error result, with its error: the +sub-agent's answer is never read for success), the result shown as on ADK (``agents/runs.py::show_as_delegation``), each recorded as it is made, before ``on_event``. A ``task`` call to any other type runs no sub-agent (Deep Agents answers that it does not exist): it is an ordinary tool call, with no @@ -303,9 +304,9 @@ def _tools_output(self, agent: str, run: RunRef, values: dict) -> list[WorkflowE for message in values.get("messages") or (): if isinstance(message, ToolMessage): self._answered(message, run) - result = self._tool_result(message, run) - events.append(result) ended = self._ended(message, run) + result = self._tool_result(message, run, delegation=ended is not None) + events.append(result) if ended is not None: show_as_delegation(result, message.text, ended) events.append(ended) @@ -357,15 +358,16 @@ def _ended(self, message: ToolMessage, run: RunRef) -> WorkflowEvent | None: ``agents/runs.py::run_ended``'s decision, as on ADK: ``failed`` for ``Error running sub-agent: `` (its ``error`` the reason) or - another error result (an error message, or one that says ``success`` - false: its error), ``refused`` when ``SubAgentOutcomeMiddleware`` - marked the run's last answer refused, else ``completed`` (``partial`` - when it marked the answer cut). + the framework's other error results (an error message: its error), + ``refused`` when ``SubAgentOutcomeMiddleware`` marked the run's last + answer refused, else ``completed`` (``partial`` when it marked the + answer cut). The sub-agent's answer is never read for success + (``_delegation_result``). """ child = self._delegated.pop((run.run, message.tool_call_id), None) if child is None: return None - _, succeeded, error = _result_of(message) + _, succeeded, error = _delegation_result(message) event = run_ended( child, message.tool_call_id, message.text, failed=not succeeded, error=error, @@ -375,11 +377,14 @@ def _ended(self, message: ToolMessage, run: RunRef) -> WorkflowEvent | None: self._runs.observe(event) return event - def _tool_result(self, message: ToolMessage, run: RunRef) -> WorkflowEvent: + def _tool_result( + self, message: ToolMessage, run: RunRef, *, delegation: bool = False + ) -> WorkflowEvent: + """``TOOL_RESULT`` for ``message``; a ``delegation``'s read as ``_delegation_result``.""" name = ( message.name or self._call_names.get((run.run, message.tool_call_id)) or "unknown" ) - result, success, error = _result_of(message) + result, success, error = (_delegation_result if delegation else _result_of)(message) event = WorkflowEvent.tool_result(name, result, success=success, error=error) event.metadata["tool_call_id"] = message.tool_call_id return event @@ -473,6 +478,20 @@ def _result_of(message: ToolMessage) -> tuple[Any, bool, str | None]: return result, success, error +def _delegation_result(message: ToolMessage) -> tuple[Any, bool, str | None]: + """A delegation's result, whether it succeeded, and its error, as on ADK. + + Only the framework's own error result fails: an error message (the + gate's denial, ``ToolCallErrorMiddleware``'s ``Error running sub-agent: + …``), read as ``_result_of`` reads one. Anything else is the sub-agent's + answer, text never read for success (ADK keeps it under ``result``): an + answer that is JSON saying it failed completed. + """ + if message.status == "error": + return _result_of(message) + return message.content, True, None + + def _delegation_call(payload: dict) -> dict | None: """The ``task`` call a tools task runs, naming its sub-agent; else None. diff --git a/tests/workflow/deepagents/test_run_identity.py b/tests/workflow/deepagents/test_run_identity.py index 9ed81f6e..c0b13ec7 100644 --- a/tests/workflow/deepagents/test_run_identity.py +++ b/tests/workflow/deepagents/test_run_identity.py @@ -144,13 +144,15 @@ def test_an_error_result_ends_it_failed(self): assert ended.metadata["status"] == RUN_FAILED assert (ended.metadata["error"], ended.metadata["result"]) == ("overloaded", "") - def test_a_result_that_says_it_failed_ends_it_failed(self): + def test_the_frameworks_error_result_ends_it_failed_with_its_error(self): + """The gate's or the error middleware's result: an error message + whose JSON holds the error.""" processor = _processor() processor.process((), "updates", _delegating()) _, ended = processor.process((), "updates", _tools_update(ToolMessage( json.dumps({"success": False, "error": "researcher failed: boom"}), - tool_call_id="c1", name="task", + tool_call_id="c1", name="task", status="error", ))) assert ended.metadata["status"] == RUN_FAILED @@ -158,6 +160,19 @@ def test_a_result_that_says_it_failed_ends_it_failed(self): "researcher failed: boom", "", ) + def test_an_answer_that_says_it_failed_completes_it(self): + """The sub-agent's answer is text, never read for success.""" + answer = json.dumps({"success": False, "error": "no X here"}) + processor = _processor() + processor.process((), "updates", _delegating()) + + result, ended = processor.process((), "updates", _tools_update(ToolMessage( + answer, tool_call_id="c1", name="task", + ))) + + assert (ended.metadata["status"], ended.metadata["result"]) == (RUN_COMPLETED, answer) + assert (result.metadata["result"], result.metadata["success"]) == (answer, True) + def test_a_long_result_is_cut(self): processor = _processor() processor.process((), "updates", _delegating()) diff --git a/tests/workflow/test_subagents_contract.py b/tests/workflow/test_subagents_contract.py index 9870865a..67c25b78 100644 --- a/tests/workflow/test_subagents_contract.py +++ b/tests/workflow/test_subagents_contract.py @@ -1379,6 +1379,31 @@ async def test_a_failed_delegation_shows_why(self, make_crew): else: assert "overloaded" in reason + async def test_an_answer_that_looks_like_a_failed_result_is_an_answer(self, make_crew): + """A sub-agent's answer is text, never read for success: JSON that + says it failed completes the run, and is shown as its answer.""" + answer = json.dumps({"success": False, "error": "no X here"}) + crew = make_crew( + team(), + coordinator=[calls(delegate("researcher", "Find X.", "c1")), says("Done.")], + researcher=[says(answer)], + ) + + events = await crew.turn() + + (result,) = [ + e for e in events + if e.type is EventType.TOOL_RESULT and e.metadata.get("tool_call_id") == "c1" + ] + (ended,) = runs_of(events, RUN_COMPLETED) + assert crew.results_read("coordinator")["c1"] == answer + assert (ended.run, ended.metadata["result"]) == (RESEARCHER, answer) + assert "error" not in ended.metadata + assert (result.content, result.metadata["success"]) == (answer, True) + assert "error" not in result.metadata + (record,) = crew.records() + assert (record.status, record.result, record.error) == (RUN_COMPLETED, answer, None) + class TestRawLog: async def test_each_record_names_its_agent_and_its_run(self, make_crew, monkeypatch): From 28a32be1a27993bd483fdcc952ac709c3081a82e Mon Sep 17 00:00:00 2001 From: Andrey Shiryaev <7615137+shoom1@users.noreply.github.com> Date: Fri, 13 Nov 2026 22:40:17 -0500 Subject: [PATCH 3/5] Runs: one reader of the run-id format A run id is #, and three places read it: run_instance, the dialogs' run_label and /agents' run number, the last two each splitting the id themselves. run_number(run) now sits beside run_instance, and run_label and /agents use it. /agents finds the run or instance through AgentRuns.record instead of matching ids itself: a run's id shows that run, an instance's each of its runs. --- CLAUDE.md | 2 +- src/agentic_cli/cli/agents_command.py | 14 ++++++++++---- src/agentic_cli/workflow/agents/runs.py | 11 ++++++++++- 3 files changed, 21 insertions(+), 6 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 3a40c988..c80252f4 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -81,7 +81,7 @@ 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; 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_label (how a dialog names a run: researcher-2 (researcher, run 1)), SUBAGENT_ERROR_PREFIX, show_as_delegation (a delegation's TOOL_RESULT shown alike on both backends); 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) +│ │ ├── 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; 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, show_as_delegation (a delegation's TOOL_RESULT shown alike on both backends); 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) │ │ ├── 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) │ │ │ ├── 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), delegated_agents (each agent's single-turn sub-agents, by its name), own_after_tool_agents (left out by the cap) diff --git a/src/agentic_cli/cli/agents_command.py b/src/agentic_cli/cli/agents_command.py index 0e7fea06..9885fd20 100644 --- a/src/agentic_cli/cli/agents_command.py +++ b/src/agentic_cli/cli/agents_command.py @@ -28,6 +28,7 @@ from agentic_cli.cli.commands import Command, CommandCategory from agentic_cli.cli.usage_tracker import format_tokens, format_usage from agentic_cli.workflow.agents import RUN_COMPLETED, RUN_STARTED +from agentic_cli.workflow.agents.runs import run_number if TYPE_CHECKING: from agentic_cli.workflow.agents import RunRecord @@ -60,17 +61,22 @@ async def execute(self, args: str, app: Any) -> None: if workflow is None: return conversation = workflow.session_ref(getattr(app, "session_id", None)) - records = workflow.agent_runs.records(conversation) + runs = workflow.agent_runs + records = runs.records(conversation) ledger = workflow.usage_of(conversation) parts = self.parse_args(args).positional.split() if parts: wanted = parts[0] - mine = [r for r in records if wanted in (r.ref.instance, r.ref.run)] - if not mine: + found = runs.record(conversation, wanted) + if found is None: app.session.add_warning( f"No sub-agent {wanted} in this conversation. Type /agents for the list." ) return + # A run's id shows that run; an instance's, each of its runs. + mine = [found] if found.ref.run == wanted else [ + r for r in records if r.ref.instance == found.ref.instance + ] app.session.add_rich(_one(mine, ledger)) return if not records: @@ -173,7 +179,7 @@ def _status(record: "RunRecord") -> str: def _run_number(record: "RunRecord") -> str: """The run's number within its instance: ``#1`` of ``researcher-2#1``.""" - return "#" + (record.ref.run or "").rpartition("#")[2] + return "#" + run_number(record.ref.run or "") def _tokens(totals: "UsageTotals") -> str: diff --git a/src/agentic_cli/workflow/agents/runs.py b/src/agentic_cli/workflow/agents/runs.py index 3cbf4a00..f1009bb5 100644 --- a/src/agentic_cli/workflow/agents/runs.py +++ b/src/agentic_cli/workflow/agents/runs.py @@ -70,7 +70,7 @@ def run_label(ref: RunRef | None) -> str | None: """ if ref is None or ref.is_root: return None - return f"{ref.instance} ({ref.agent}, run {ref.run.rpartition('#')[2]})" + return f"{ref.instance} ({ref.agent}, run {run_number(ref.run)})" def run_ended( @@ -199,6 +199,15 @@ def run_instance(run: str) -> str: return run.rpartition("#")[0] +def run_number(run: str) -> str: + """A run's number within its instance, as its id writes it (``researcher-2#1``: ``1``). + + The other half of the id ``AgentRuns.run_for`` gives: how a dialog + (``run_label``) and ``/agents`` number a run. + """ + return run.rpartition("#")[2] + + class AgentRuns: """A manager's sub-agent runs, kept by conversation, in memory for the process.""" From d755b50910fb8505df34d8c86119f4b1a781c1a0 Mon Sep 17 00:00:00 2001 From: Andrey Shiryaev <7615137+shoom1@users.noreply.github.com> Date: Fri, 13 Nov 2026 22:44:01 -0500 Subject: [PATCH 4/5] Tests: consent claims reach their model; a refused request names its run The consent scenario now checks that each approval claim reached the model it was meant to sway (the user's turn the coordinator, the brief the researcher's first request, contract_says_approved's result a later one), so the "only the user approves" result is not won by a claim that never arrived. The question scenario scans every coordinator request whole for the question (Crew.bodies), with the researcher's as the positive control, instead of the delegation's result alone. A unit test pins that request_user_input fills request.run before it can refuse the request (no callback, or a turn that has ended): with the fill moved after those checks both cases fail. Test text says the rule itself instead of citing the spec or the plan, the contract module's docstring keeps to the line length, and Crew.result_ids says what it holds on ADK, which merges a call's answers as it builds the request. --- tests/test_input_callback.py | 3 +- tests/tools/test_job_notice.py | 2 +- tests/tools/test_jobs.py | 2 +- tests/workflow/test_input_request_run.py | 40 +++++++++++++++++- tests/workflow/test_subagents_contract.py | 51 +++++++++++++++++------ 5 files changed, 81 insertions(+), 17 deletions(-) diff --git a/tests/test_input_callback.py b/tests/test_input_callback.py index 7d705cbd..e4d7e66b 100644 --- a/tests/test_input_callback.py +++ b/tests/test_input_callback.py @@ -65,7 +65,8 @@ async def test_no_callback_raises(self): class TestOnlyInsideItsTurn: """A task a turn started copies the turn's context, the callback with it; - once the turn has ended, the callback does not answer it (spec 9).""" + once the turn has ended, the callback does not answer it: no dialog + opens outside a turn.""" async def test_a_task_that_outlives_its_turn_cannot_ask(self): manager = _manager() diff --git a/tests/tools/test_job_notice.py b/tests/tools/test_job_notice.py index b9011c7b..5fa09b68 100644 --- a/tests/tools/test_job_notice.py +++ b/tests/tools/test_job_notice.py @@ -1,7 +1,7 @@ """What a finished job's notice asks of the root agent: who started the job. A job a sub-agent started is told to the root (that run has ended), so the -notice names the sub-agent instead of "you" (spec 9). +notice names the sub-agent instead of "you": the root did not start it. """ from __future__ import annotations diff --git a/tests/tools/test_jobs.py b/tests/tools/test_jobs.py index 4047bdc5..6c4c129c 100644 --- a/tests/tools/test_jobs.py +++ b/tests/tools/test_jobs.py @@ -598,7 +598,7 @@ def _active_run(ref): class TestTheRunThatStartedIt: - """``started_by``: the sub-agent instance whose call submitted the job (spec 9).""" + """``started_by``: the sub-agent instance whose call submitted the job; None for the root's.""" def test_a_sub_agents_job_records_its_instance(self, jm: JobManager): from agentic_cli.workflow.sessions import RunRef diff --git a/tests/workflow/test_input_request_run.py b/tests/workflow/test_input_request_run.py index 6b2213c4..fa21cb8f 100644 --- a/tests/workflow/test_input_request_run.py +++ b/tests/workflow/test_input_request_run.py @@ -9,11 +9,17 @@ from __future__ import annotations +import asyncio + +import pytest + from agentic_cli.workflow.agents import run_label from agentic_cli.workflow.base_manager import BaseWorkflowManager -from agentic_cli.workflow.events import UserInputRequest +from agentic_cli.workflow.events import UserInputRequest, UserInputUnavailable from agentic_cli.workflow.sessions import ( RunRef, + close_turn_scope, + open_turn_scope, reset_active_run, root_run, set_active_run, @@ -103,6 +109,36 @@ async def test_a_run_the_caller_gave_is_kept(self): (asked,) = manager.asked assert asked.run == LEAF + @pytest.mark.parametrize("refused_by", ["no callback", "its turn has ended"]) + async def test_a_refused_request_is_given_its_run_first(self, refused_by): + """The run is filled before the request can be refused, so whoever + catches the refusal can still say which run asked.""" + manager = _Asking() + request = _request() + token = set_active_run(RESEARCHER) + try: + if refused_by == "no callback": + manager.clear_input_callback() + asking = manager.request_user_input(request) + else: + go = asyncio.Event() + + async def later() -> str: + await go.wait() + return await manager.request_user_input(request) + + span = open_turn_scope() + asking = asyncio.create_task(later()) # copies the turn's context + close_turn_scope(span) + go.set() + with pytest.raises(UserInputUnavailable): + await asking + finally: + reset_active_run(token) + + assert manager.asked == [] + assert request.run == RESEARCHER + class TestRunLabel: def test_a_sub_agent_run_is_its_instance_its_agent_and_its_number(self): @@ -115,5 +151,5 @@ def test_the_root_has_none(self): def test_a_depth_0_agent_has_none(self): """An agent the root transfers to (a native ADK YAML app's) replies - as the root does: no run, so no label (the header's R1).""" + as the root does: it is no sub-agent run (``run`` None), so no label.""" assert run_label(RunRef("helper", "helper", None, None, 0)) is None diff --git a/tests/workflow/test_subagents_contract.py b/tests/workflow/test_subagents_contract.py index 67c25b78..0a13814e 100644 --- a/tests/workflow/test_subagents_contract.py +++ b/tests/workflow/test_subagents_contract.py @@ -4,10 +4,11 @@ Deep Agents (``ScriptedChat``) and expects the same events, run records and results: the two backends behave alike. A scenario's model answers are written once, in backend-neutral steps (``says``; ``calls`` with ``delegate`` -and ``use``), which the harness turns into each backend's: on ADK a delegation is a call of the tool named after -the sub-agent (``request``), on Deep Agents a ``task`` call -(``description``, ``subagent_type``). Each agent's prompt is -``You are .``, by which ADK's fake API tells the agents apart. +and ``use``), which the harness turns into each backend's: on ADK a +delegation is a call of the tool named after the sub-agent (``request``), on +Deep Agents a ``task`` call (``description``, ``subagent_type``). Each +agent's prompt is ``You are .``, by which ADK's fake API tells the +agents apart. Offline: no provider is reached and no catalog lists (``tests/conftest.py``). """ @@ -323,6 +324,7 @@ class Crew: _result_ids: Callable[[str, int], list[str]] | None = None _answers: Callable[[str, str], Awaitable[list[str]]] | None = None _last_message: Callable[[str, int], str] | None = None + _bodies: Callable[[str], list[str]] | None = None async def turn(self, text: str = "Go.") -> list[WorkflowEvent]: """One turn of the conversation, run to its end; its events.""" @@ -366,10 +368,19 @@ def last_message(self, agent: str, call: int = -1) -> str: def result_ids(self, agent: str, call: int = -1) -> list[str]: """The call ids of the tool results ``agent``'s model request ``call`` - held, one per result, in order: a call answered twice is there twice.""" + held, one per result, in order. On Deep Agents a call answered twice + is there twice; ADK merges a call's answers as it builds the request + (a later one takes the earlier one's place), so a second answer there + is seen in its session (``answers``), not here.""" assert self._result_ids is not None return self._result_ids(agent, call) + def bodies(self, agent: str) -> list[str]: + """Each of ``agent``'s model requests whole, as text: every message + it held (ADK: the JSON body sent; Deep Agents: each message's JSON).""" + assert self._bodies is not None + return self._bodies(agent) + async def answers(self, agent: str, call_id: str) -> list[str]: """The answers ``agent``'s call ``call_id`` has after a stopped turn, one per answer, as text: a call answered twice is there twice. @@ -431,9 +442,12 @@ def last_message(name: str, call: int) -> str: block.get("text", "") for block in content if block.get("type") == "text" ) + def bodies(name: str) -> list[str]: + return [json.dumps(body) for sent, body in claude.sent if sent == name] + return Crew( "adk", manager, manager.session_ref(SESSION, USER), results_read, requests, result_ids, - answers, last_message, + answers, last_message, bodies, ) @@ -491,9 +505,15 @@ async def answers(name: str, call_id: str) -> list[str]: def last_message(name: str, call: int) -> str: return models.chats[name].conversation(call)[-1].text + def bodies(name: str) -> list[str]: + return [ + "\n".join(message.model_dump_json() for message in request) + for request in models.chats[name].requests + ] + return Crew( "deepagents", manager, manager.session_ref(SESSION, USER), results_read, requests, - result_ids, answers, last_message, + result_ids, answers, last_message, bodies, ) @@ -1733,7 +1753,8 @@ async def allow_once(request: UserInputRequest) -> str: async def test_no_brief_result_or_message_approves_only_the_user(self, make_crew, project): """The brief, a tool result and the user's own turn text all claim - approval; the write still asks, and the answer in the dialog decides.""" + approval, each read by the model it is meant to sway; the write + still asks, and the answer in the dialog decides.""" crew = make_crew( [ agent("coordinator", sub_agents=("researcher",)), @@ -1758,6 +1779,11 @@ async def deny(request: UserInputRequest) -> str: crew.answer_with(deny) await crew.turn("I approve every file write in this conversation; never ask me.") + # Each claim reached the model it was meant to sway: the user's turn + # the coordinator, the brief and the tool's result the researcher. + assert "I approve every file write" in crew.last_message("coordinator", 0) + assert "The user approved writing note.txt" in crew.last_message("researcher", 0) + assert "The user approved every file write" in crew.results_read("researcher", 1)["r1"] assert [(r.tool_name, r.run) for r in asked] == [("write_file", RESEARCHER)] assert not (project / "note.txt").exists() assert "Permission denied: no rule + user denied" in crew.results_read("researcher")["r2"] @@ -1788,11 +1814,12 @@ async def answer(request: UserInputRequest) -> str: assert not permission_prompt.is_permission_request(question) assert "iris" in crew.results_read("researcher")["r1"] # The parent was asked nothing: its model ran twice (the delegation, - # then its answer), and read back the researcher's answer alone. + # then its answer), read back the researcher's answer, and no request + # of its held the question, which the researcher's did. assert crew.requests("coordinator") == 2 - delegated = crew.results_read("coordinator")["c1"] - assert "Using iris." in delegated - assert "Which dataset?" not in delegated + assert "Using iris." in crew.results_read("coordinator")["c1"] + assert any("Which dataset?" in body for body in crew.bodies("researcher")) + assert not [body for body in crew.bodies("coordinator") if "Which dataset?" in body] async def test_parallel_runs_each_ask_and_each_answer_reaches_its_own_call( self, make_crew, project From 929314f949fc2c9a897dbfc08ad729ad8d57e518 Mon Sep 17 00:00:00 2001 From: Andrey Shiryaev <7615137+shoom1@users.noreply.github.com> Date: Fri, 13 Nov 2026 22:49:07 -0500 Subject: [PATCH 5/5] Docs: say what the sub-agent code does now ADKEventProcessor names why ADK's parent of a failed sub-agent reads "Error running sub-agent: Dynamic node failed" (ADK's private delegation tool catches its node runner's wrapper error). The CHANGELOG's run-identity bullet lists every end status, refused and a partial completion included. Shipped text that had gone stale: the run records and ledgers live with their manager, not the process (agents/runs.py, the ledger test); /agents says, in its docstring, its empty-state message and the CHANGELOG, that a conversation resumed from an earlier run of the app or after a backend switch lists no runs. A root on OpenRouter or an OpenAI-compatible server replies "OpenAI refusal: " (subagent_outcome_plugin). The config comment names the field's earlier string form. Deep Agents before 0.7.34 handed a refused sub-agent's last non-empty text, not an empty result (CHANGELOG, SubAgentOutcomeMiddleware). unsealed's guard says what it checks and what the durable store's stale check covers. job_for_call's "every run" meant every start of the app. inherit_context is refused below another sub-agent too (CHANGELOG, README). usage.py keeps two blank lines between top-level blocks. CLAUDE.md: the structure lines name run_ended, end_returned_run, _end_returned_runs and returned, the Interrupted-calls paragraph says a returned delegation ends with its result, format_usage serves /agents too, /agents' records live with the manager, and the Testing section names the shared sub-agent contract suite. --- CHANGELOG.md | 27 ++++++++++++------- CLAUDE.md | 15 ++++++----- README.md | 5 ++-- src/agentic_cli/cli/agents_command.py | 14 +++++++--- .../workflow/adk/event_processor.py | 8 ++++-- .../workflow/adk/interrupted_calls_plugin.py | 10 ++++--- src/agentic_cli/workflow/adk/manager.py | 2 +- .../workflow/adk/subagent_outcome_plugin.py | 6 +++-- src/agentic_cli/workflow/agents/runs.py | 6 +++-- src/agentic_cli/workflow/config.py | 2 +- .../workflow/deepagents/middleware.py | 11 ++++---- src/agentic_cli/workflow/interrupts.py | 12 ++++----- src/agentic_cli/workflow/usage.py | 2 +- tests/cli/test_agents_command.py | 10 +++---- tests/workflow/test_usage_ledger.py | 4 +-- 15 files changed, 80 insertions(+), 54 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0494b9de..102f3fe1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -584,9 +584,12 @@ the start of the entry's title. shows what it has used so far) and time. `/agents ` shows one instance (`researcher-2`) or run (`researcher-2#1`): its type, parent and title, then each run's status and time, the first lines of its result, its error - and its tokens by model. During a turn each line of the events box names - the sub-agent run at work (`researcher-2 › Calling: web_fetch`), as its - tool results in the transcript do; the main agent's lines are unchanged. + and its tokens by model. The runs are the manager's records, kept in + memory with it: a conversation resumed from an earlier run of the app, or + after a backend switch, lists none. During a turn each line of the events + box names the sub-agent run at work (`researcher-2 › Calling: web_fetch`), + as its tool results in the transcript do; the main agent's lines are + unchanged. - **Token usage by run and agent, on both backends.** Every model call the framework makes is one `LLM_USAGE`, side calls included (`generate_simple`: web_fetch's and the knowledge base's summaries, `purpose` `tool`; the memory @@ -627,8 +630,9 @@ the start of the entry's title. and `TOOL_RESULT` carry `tool_call_id`, as Deep Agents' did. A sub-agent run's start and end are an event of their own, `EventType.AGENT_RUN` (`WorkflowEvent.agent_run`; `metadata["status"]` `started`, with its title, - the first line of its request, then `completed`, `failed` or - `interrupted`, with the first 200 characters of its result; a run fails + the first line of its request, then `completed` (`partial` for an answer + cut at its output limit), `refused`, `failed` or `interrupted`, with the + first 200 characters of its result; a run fails on `Error running sub-agent: …` or the framework's own error result, an error `ToolMessage` on Deep Agents, the error dict of a raised or denied call on ADK, and the sub-agent's answer is never read for success, so an @@ -1225,9 +1229,11 @@ the start of the entry's title. model, and `ForeignReasoningMiddleware` leaves out the reasoning of AI messages another agent wrote, so a fork is never sent its coordinator's. `validate_agent_graph` raises `AgentGraphError` for `inherit_context=True` - on the root or on an agent with sub-agents of its own (in 0.7.0: Deep + on the root, on an agent with sub-agents of its own (in 0.7.0: Deep Agents tells a fork that delegating "will be refused", which a - coordinator would believe), and for a value that is not True or False. + coordinator would believe) or on an agent below another sub-agent (it is + for the main agent's own sub-agents), and for a value that is not True or + False. - **`BaseWorkflowManager.context_budget(agent_name=None)` and `root_agent_name`**: an agent's context numbers as its backend summarizes and trims by them, the root agent's by default. A frozen `ContextBudget` @@ -2825,9 +2831,10 @@ step; each entry says what to use instead. the stream (`WorkflowEvent.run`) and in `llm_events.jsonl` (`run`: agent, instance, run, parent run, depth), on both backends. - **A sub-agent's refused or cut answer is said so, on both backends.** A - sub-agent whose model refused reached its parent as an empty result with - no warning (ADK; Deep Agents before 0.7.34), and an answer cut at the - output limit passed as complete. Now the parent reads Deep Agents + sub-agent whose model refused reached its parent with no warning: as an + empty result on ADK, and on Deep Agents before 0.7.34 as the sub-agent's + last non-empty text (empty when it had written none); and an answer cut at + the output limit passed as complete. Now the parent reads Deep Agents 0.7.34's notice ("The subagent stopped because a model refused the request. … rephrase it or continue without it.") whichever deepagents is installed, and the run ends `refused`; a cut answer keeps its text (and diff --git a/CLAUDE.md b/CLAUDE.md index c80252f4..feee29d8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -36,7 +36,7 @@ agentic-cli/ │ │ ├── conversation.py # ConversationCore: the conversation the turns run in (its id, turned, its lock at its Place: the backend and store, the store the run's for its whole life (Place.kept: not the memory store, where the CLI keeps one conversation at a time and NOT_KEPT says why nothing else opens), the backend recorded as the app starts, for a new conversation on another backend, and on a /settings change of the orchestrator while the workflow is down, its next start builds afresh and nothing of the conversation is stored (SettingsUI._move_here, WorkflowController.next_start_builds), never read from the settings in between; deferred: an id this run made (the start's, /new's, an orchestrator change's) is in no store, so it is held from its first write, hold_to_write under the turn lock before a turn, a job's notice or /compact (_held_to_write; a run in which no turn runs makes no lock file: a line typed while the workflow is down takes the hold before its retried start; a lock that cannot be taken, an OSError, leaves it unheld, said once, and the write goes on); fresh: nothing of it stored, opened_empty (an id this run made, or one a load found empty) and not written (no turn of it ran on a ready workflow), the one condition for another backend); switch: the one protocol (/new on any backend, /resume, startup, the same id in another place while the workflow is down): the target's lock taken (another process's refused), memories proposed, the workflow loads it (a stored one gone: not made, or, made already in another place, opened empty: gone), then made at once (lock, id, task list, usage counters) or let go, a workflow that took it given the old one back; made before the load when there is no other conversation to stay in (the same id, or another place: a new or stored conversation on another backend); a Ctrl+C at any await leaves one conversation held; switch_now: the deprecated session_id setter's part; turn_lock: what writes to the conversation and every switch take it; run_turn, compact and run_job_resume: a turn (echoed, held to write, turned, written once it reached a ready workflow; run_turn says whether it ran, whatever the processor returns), /compact and a finished job's notice under it, on TurnParts (the app's parts as they are); deliver_finished_jobs: each job that waits here (cli/waiting_jobs.py's rule, which waiting_jobs names them by, the other backends' look through TurnParts.kept_elsewhere), every JobManager call on a worker thread, a delivery claimed only once it can reach the agent (process_resume(claim=), after the readiness check and can_resume; _claim_delivery: a claim a Ctrl+C stopped is handed back, JobManager.release_resume), a failure before the claim said once per job and conversation when the CLI tells jobs on its own (telling_on_its_own); to_drop/drop_left: the conversations /new left on the memory store that the store may still hold (the workflow down, a lookup or delete that raised), dropped through TurnParts.drop under the turn lock once a workflow is ready, before a turn, /compact or a delivery uses it (after a turn or /compact that started it), one try per point, done once the store has it no more (a workflow without supports_sessions has none), the open one skipped; a delivery with none to drop takes no turn lock │ │ ├── conversation_lock.py # ConversationLock: one process per stored conversation (flock under /locks/; ConversationCore holds it and refuses one held elsewhere; /sessions --delete too, through conversation_held) │ │ ├── builtin_commands.py # /help (by category; /help : its usage and examples), /status (the main agent's context rows: context_budget; why the workflow did not start: app.workflow_error; tokens by agent: the main agent, each sub-agent with its runs, the side calls by purpose, from the manager's usage ledger), /models (ModelsCommand: the list, each model's facts and sources, Status for an entry left out, the providers in use; /models searches the full listings; refresh), /sessions (every installed backend's, a Backend column; --delete= on the backend that keeps it, --backend= for an id two keep; on the memory store NOT_KEPT, no table, --delete refused), /resume [] (sessions; refused on the memory store), /jobs (resume: finished jobs), /compact [focus], /new [backend] (an unknown backend or a missing extra refused: check_backend), ... -│ │ ├── agents_command.py # /agents: the open conversation's sub-agent runs (agent_runs.records under workflow.session_ref(app.session_id)) in a table, each followed by the runs it started (instance, type, status: running, completed (partial) for a cut answer, the end as recorded; run, title, tokens in/out from the usage ledger, usage_of, live for a running run; time); /agents : one instance or run (type, parent, title; each run's status and time, its result's first lines, its error, its tokens by model); a module of its own, as /memory's +│ │ ├── agents_command.py # /agents: the open conversation's sub-agent runs (agent_runs.records under workflow.session_ref(app.session_id)) in a table, each followed by the runs it started (instance, type, status: running, completed (partial) for a cut answer, the end as recorded; run, title, tokens in/out from the usage ledger, usage_of, live for a running run; time); /agents : one instance or run (type, parent, title; each run's status and time, its result's first lines, its error, its tokens by model); the records live in memory with the manager, so a conversation resumed after a restart or a backend switch lists none; a module of its own, as /memory's │ │ ├── memory_command.py # /memory: the list (a picker like /resume's), one memory (Delete, History), /memory , history (Restore), inbox (Accept/Discard/Skip), stale; proposals_line; Enter's button is Close or Skip, and Delete acts only on the memory as shown │ │ ├── workflow_controller.py # WorkflowController (lazy/background init; the session store of every manager of the run, store, fixed at its first start; the backend it runs, backend: the settings' orchestrator at its first start, then switch_backend's (a conversation on another backend, new or opened: the new manager started first on the run's services lent, given over by the old one and published at once, the old one released in the controller's task, a cancel stops only the wait; a failed start or give leaves the old one with its services; while down, a manager a failed reinitialization kept lends its services to the next build, _lender, and is released once they are given); reinitialize, a model switch, always in place; the status bar names the main agent's model) │ │ ├── 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 @@ -47,7 +47,7 @@ agentic-cli/ │ │ ├── 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 │ │ ├── waiting_jobs.py # Which finished jobs wait to be told in the open conversation: one rule (JobRecord.awaiting_resume, then its own, no conversation's, or a gone conversation's: can_resume, then the other installed backends' readers, opens_anywhere: one another backend keeps is not gone, its job waits for it) for the deliveries, ↻N and the startup line -│ │ └── usage_tracker.py # Token usage / status bar: ctx = the main agent's last prompt over its context_trigger (a call with a purpose, a sub-agent's, a summary's or a side call's, never moves it); the token segment the open conversation's total, every call of its turns; format_usage: /status's rows by agent +│ │ └── usage_tracker.py # Token usage / status bar: ctx = the main agent's last prompt over its context_trigger (a call with a purpose, a sub-agent's, a summary's or a side call's, never moves it); the token segment the open conversation's total, every call of its turns; format_usage: /status's rows by agent and /agents 's tokens by model │ ├── workflow/ │ │ ├── base_manager.py # BaseWorkflowManager (abstract; _load_models: load the catalog, then resolve every model (the configs', then _resolve_extra_models: a backend's agents built without configs, leniently), once, no retry (the background refresh started after a successful init checks the models the settings name); _compute_budgets right after it, before any service is built: each agent's context numbers, ContextBudgetError for a window too small to work in, for a backend that says _manages_context (ADK, whoever built its agents, and Deep Agents; LangGraph has none); the lifecycle: cleanup, reinitialize and the one release, _release_resources: the base's state reset, the backend's hooks _detach_backend/_detach_store (skipped while _keeping keeps the store), the services detached and their closes started on a worker thread, then every closer and the services waited for last (shielded), in one shielded task; the turn: _turn, every turn's entry (log context, _turn_admission, _workflow_context; the sub-agent runs it leaves open, a cancel's or a failure's, recorded interrupted as it ends: agent_runs, workflow/agents/runs.py), and the templates over the backend's hooks: resume_with_job_result (the job's result read on a worker thread, job_notice → _deliver_job_notice), can_resume (_record_resumable, _conversation_exists), compact (→ _compact_turn), supports_job_resume/supports_compact derived from them; services (services.py's ServiceSet behind the forwards: _services, _build_services(_into), _get_service_tool_map, _close_services, _keeping) and the hand-over: lend_services → initialize_services(services=loan) → give_services (no turn while a manager holds services it does not own); service detection, tool assembly; context_budget/root_agent_name; the usage ledgers (usage: the open conversation's, usage_of; _turn counts each turn in its conversation's and gives a run a cancel leaves open what it used) and side calls (_report_side_call: generate_simple's usage, its purpose from usage.side_call, summarize's tool, on_session_end's memory_extraction outside any turn, recorded in its conversation's ledger and, in a turn, reported through its live events, never to a turn that has ended: turn_has_ended); summarize and fact extraction: a prompt over the default model's room, at the resolved max_tokens, cut in the middle, never under MIN_PROMPT_ROOM, _fit_prompt; the memory index behind the forwards _memory_index_now/_memory_index_cached/_memory_index_cap/_forget_memory_index and _index_snapshots (memory_index.py's MemoryIndex; the release clears it)) │ │ ├── factory.py # create_workflow_manager_from_settings (_BACKENDS: orchestrator → "module:Class" + extra, imported when chosen; orchestrator=: another backend than the settings'; session_store=: the store a manager is built for, BaseWorkflowManager.session_store, the settings' by default); orchestrator_of; check_backend (an unknown name, a missing extra) @@ -81,9 +81,9 @@ 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; 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, show_as_delegation (a delegation's TOOL_RESULT shown alike on both backends); 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) +│ │ ├── 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; 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, run_ended (the one run-end decision, both processors': failed only on Error running sub-agent: … or the framework's own error result, the sub-agent's answer never read for success; refused or partial by the outcome mark), show_as_delegation (a delegation's TOOL_RESULT shown alike on both backends); 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) │ │ ├── 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) +│ │ │ ├── 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; _end_returned_runs: before the turn clears its record (a stop, after unsealed; a failure), each open run whose delegation returned ends with its result, not interrupted) │ │ │ ├── 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), delegated_agents (each agent's single-turn sub-agents, by its name), own_after_tool_agents (left out by the cap) │ │ │ ├── branches.py # A sub-agent run on ADK: the branch it runs on (@, dot-nested under its parent's): delegations, branch_run, parent_branch_run │ │ │ ├── delegation.py # Sub-agents as single_turn tools of their parent; binding those tools to task @@ -92,12 +92,12 @@ agentic-cli/ │ │ │ ├── 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 for an agent that replies (reply_agents), a sub-agent's text answer otherwise │ │ │ ├── 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) -│ │ │ ├── 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, its branch's (adk/branches.py) or the agent's own at depth 0, TOOL_CALL and TOOL_RESULT their tool_call_id, and a delegation's call (to one of the caller's own single-turn sub-agents: any other call is no run) and result an AGENT_RUN: started, then completed (partial, and one warning, for an answer SubAgentOutcomePlugin marked cut), failed ("Error running sub-agent: …", or an error result), refused (marked refused) or interrupted (a stopped turn's seal), recorded in the manager's runs; the delegation's TOOL_RESULT shown as on Deep Agents: show_as_delegation) +│ │ │ ├── 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, its branch's (adk/branches.py) or the agent's own at depth 0, TOOL_CALL and TOOL_RESULT their tool_call_id, and a delegation's call (to one of the caller's own single-turn sub-agents: any other call is no run) and result an AGENT_RUN: started, then, by run_ended, completed (partial, and one warning, for an answer SubAgentOutcomePlugin marked cut), failed ("Error running sub-agent: …", or the framework's error dict: the answer, under result, is never read for success), refused (marked refused) or interrupted (a stopped turn's seal), recorded in the manager's runs; end_returned_run: a delegation that finished beside a slower one, which ADK hands back only with it (a step's parallel results come in one event, after the last), ended from the record when the turn stops or fails first; the delegation's TOOL_RESULT shown as on Deep Agents: show_as_delegation) │ │ │ ├── model_factory.py # build_adk_model: ResolvedModel → ADK model, config, planner │ │ │ ├── openai_compatible.py # OpenAICompatibleLlm (the configured providers: openrouter and openai_compatible kinds; reasoning text; OpenRouter's reasoning_details kept on the thought part (thought_signature, with the model that wrote them) and sent back on that turn's assistant message to that model only; a Chat Completions refusal, streamed or not, as the text ADK's Responses adapter makes of one, "OpenAI refusal: "; no field sent as null; OpenRouter's cache writes, which ADK's usage mapping drops, kept on the usage as cache_creation_input_tokens) │ │ │ ├── anthropic_llm.py # DirectAnthropicLlm: bare claude-* strings → direct API (registered once per process, when a native YAML app is loaded: ensure_direct_anthropic) │ │ │ ├── permission_plugin.py # PermissionPlugin (gates tool calls; marks the conversation when an allowed call brings outside content, written to the session state at the model calls of the agents that reply); tool_definition: a tool object's registry identity, the gate's and the tool result cap's -│ │ │ ├── interrupted_calls_plugin.py # InterruptedCallsPlugin: a cancelled turn's seals worded (finished results kept, as the cap cut them), each seal answered as the run its branch names, each running call marked by its branch and id; unsealed: the calls ADK's seals missed (they pair by id alone), answered as the turn stops, from the record, as their branch's run's; left_open: a crash's calls answered at the next turn (a result pairs with a call on its own branch only; a job's state only for the root's own call, a sub-agent's run being numbered no more), and a stop's whose answers could not be written, as the user's +│ │ │ ├── interrupted_calls_plugin.py # InterruptedCallsPlugin: a cancelled turn's seals worded (finished results kept, as the cap cut them), each seal answered as the run its branch names, each running call marked by its branch and id; unsealed: the calls ADK's seals missed (they pair by id alone), answered as the turn stops, from the record, as their branch's run's; left_open: a crash's calls answered at the next turn (a result pairs with a call on its own branch only; a job's state only for the root's own call, a sub-agent's run being numbered no more), and a stop's whose answers could not be written, as the user's; returned: a finished call's result from the record, as ADK stores it and the model reads it │ │ │ ├── task_progress_plugin.py # TaskProgressPlugin: deprecated and unused (DeprecationWarning; the event processor reports task progress), removed in 0.8.0 │ │ │ ├── tool_error_plugin.py # Tool exception → error result (turn survives); a call to an unknown tool name → ADK's own text (is_unknown_tool: ADK's stand-in, which the gate lets through), recorded in OpenCalls since ADK skips its after-tool callbacks, so a cancelled turn keeps it │ │ │ ├── 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 @@ -263,7 +263,7 @@ Workflow: - **HITL callback is context-local**: `set_input_callback()` stores into a per-manager `ContextVar`, so a second consumer installing its callback cannot capture a running turn's prompt, and one consumer's `clear_input_callback()` cannot unregister another's. `MessageProcessor` cancels and awaits its consumer task **before** clearing the callback, so no tool is left asking a question nobody owns. And the callback answers only inside its turn: a task a turn started (`asyncio.create_task` copies the context, the callback with it) that asks after the turn ended gets `UserInputUnavailable` (`request_user_input`; the turn's span, `workflow/sessions.py::open_turn_scope`/`close_turn_scope`, opened and closed by `_workflow_context`, which the copy carries), as with no approver: a question goes unanswered and a permission ASK is denied by the engine's no-approver rule. - **Code that may run on the host is approved per call**: CPython has no in-process sandbox, so `execute_python` runs inside the OS sandbox or not at all by default (`os_sandbox_strict` true: no backend, a failed wrap, or a sandbox tool that fails as it starts (the runner's first stderr line, `_STARTED_MARKER`, never came) is a refusal that keeps its cause and ends with `executor.how_to_run`: sandbox-exec, bwrap and Ubuntu 24.04's user namespaces, none on Windows, and the opt-out where it lives, `exec_policy.sandbox_opt_out`: `~/.{app_name}/settings.json` or the env variable, since the project file and `/settings` cannot set it), and the module set is chosen from the path a call takes (`executor.py::_choose_run`, then `validate_code(allowed_modules=)`). The engine never imports `tools/`: `BaseWorkflowManager` passes `PermissionEngine(uncontained=tools.exec_policy.uncontained_exec_capabilities)`, called with the settings at each check (a settings change applies at once). For a capability it names, `engine.unstorable_reason` is `UNCONTAINED` (the one decision, shared with the prompt: only "Allow once" and "Deny", with its note), and `_evaluate` skips allow rules from grants (`SESSION`, and `PROJECT`, the user's `project_grants.json`), so a grant from when the code ran contained approves nothing; a `USER` rule still applies. A prompt for `*.exec` shows all of the code (the dialog body scrolls). - **No harness-level turn replay**: ADK persists a turn's input during invocation setup, and Deep Agents' checkpointer at the turn's first step, so the CLI never re-invokes an event source. Retries belong to the provider client (`HttpRetryOptions`). `MessageProcessor` returns a typed `TurnResult`. A turn that fails yields one `ERROR` and returns, on both backends (the base `process()`'s contract; `WorkflowEvent.turn_failed`: the error's text, `rate_limited`, `error_type`); an `ERROR` the turn already yielded that is not recoverable is its one; a cancel still raises, and a turn that cannot start (initialization, admission, or its conversation cannot be read) raises before any event. The CLI says a rate limit from the event as it does from a manager that raises. -- **Interrupted calls**: Ctrl+C stops the whole turn (loop, model calls, tools, sub-agents), and every call the model made gets exactly one result (`workflow/interrupts.py`, the texts and `OpenCalls`, each manager's record, kept by conversation and by the run that made each call (the root's own, or a sub-agent's: a provider that numbers its call ids per agent gives a sub-agent's call its parent's delegation's id): a call's result as it finished, a call `asking` at its permission prompt, both gates marking it; a conversation whose turn the user cancelled): a finished call keeps its result, a running one or a delegation is `INTERRUPTED_BY_USER`, one at its prompt `NOT_RUN`, one whose job was submitted the job's state (`job_started`); a cancel with no call open leaves `MARKER` as the main agent's reply; a call nothing answered (a crash, an old session) is `INTERRUPTED`. On ADK the turn runs with `abort_signal`, set by `live_events.merged(on_stop=)` before the runner is cancelled, so ADK seals the invocation in its own branches; `merged` waits for its source to close, a repeated cancel too (up to `STOP_GRACE`), and `process()`/`resume_with_job_result()` close their inner generators with `aclosing`, so a run never outlives its turn. `adk/interrupted_calls_plugin.py::InterruptedCallsPlugin` (before `ToolResultCapPlugin`, every app) sets the active tool call around each call (`before_tool_callback`, so a question marks it `asking`), records results with their `state_delta`/`artifact_delta` in `after_tool_callback` (not a long-running starter's `None`: its job answers it), keeps the cap's cut of one (`ToolResultCapPlugin.on_cut`, so a seal sends that cut and its full output is saved once) and rewrites the seals (`error_code` `INVOCATION_ABORTED`, contract-tested) in `on_event_callback`, carrying those deltas, each seal answered from the record of the run its branch names (a seal is written outside that run). ADK's seals pair a result with a call by id alone, so a call whose id a sub-agent's result used is left open: the manager answers those as the stopped turn ends, before it clears the record, the same way (`_answer_unsealed`, shielded; `unsealed`, once ADK's seals are written), so a call that finished beside a delegation keeps its result. `left_open` answers leftovers when `process()` starts (every app: a task-mode agent's delegation, which ADK keeps open on purpose, is refused at build, and ADK's client calls for a human, `adk_request_confirmation`/`_credential`/`_input`, are answered as interrupted, since the manager offers no way to answer them), a result pairing with a call on its own branch only; one a stop left because its answers could not be written is answered `INTERRUPTED_BY_USER` (the manager records the stop). On Deep Agents `InterruptedCallsMiddleware` takes `PatchToolCallsMiddleware`'s place, first in every stack: it records each final `ToolMessage` with the rest of its `Command` update (outermost tool wrapper) and answers open calls in `before_agent`, returning those updates too; the root adds `MARKER` before the new input when the message before it is no reply (a `HumanMessage` or a tool result). Background jobs are not part of the turn: they keep running. Nor is a synchronous tool's function (a sandbox cell, `compile_document`, `execute_python`): it runs in a worker thread on both backends (ADK's tool thread pool, LangChain's executor), which Python cannot stop, so its call is answered at once but the function runs on to its end, keeps its sandbox session busy (the session's next call waits for it) and holds the process's exit until it returns (the sandbox's cleanup stops a cell). So is a knowledge-base ingest's store step (`kb_ingest_text`, `kb_ingest_file`, `ingest_arxiv_paper`: `KnowledgeBase._store` runs `ingest_document` in `asyncio.to_thread`): a cancelled ingest is answered `INTERRUPTED_BY_USER` and still stores its document, so a model that retries it stores a second copy; a cancelled `sidecar` or `backfill_sidecars` keeps its lock or flag until its thread's call ends (`memory/kb/manager.py::_Threads`). +- **Interrupted calls**: Ctrl+C stops the whole turn (loop, model calls, tools, sub-agents), and every call the model made gets exactly one result (`workflow/interrupts.py`, the texts and `OpenCalls`, each manager's record, kept by conversation and by the run that made each call (the root's own, or a sub-agent's: a provider that numbers its call ids per agent gives a sub-agent's call its parent's delegation's id): a call's result as it finished, a call `asking` at its permission prompt, both gates marking it; a conversation whose turn the user cancelled): a finished call keeps its result, a running one or a delegation is `INTERRUPTED_BY_USER`, one at its prompt `NOT_RUN`, one whose job was submitted the job's state (`job_started`); a cancel with no call open leaves `MARKER` as the main agent's reply; a call nothing answered (a crash, an old session) is `INTERRUPTED`. On ADK the turn runs with `abort_signal`, set by `live_events.merged(on_stop=)` before the runner is cancelled, so ADK seals the invocation in its own branches; `merged` waits for its source to close, a repeated cancel too (up to `STOP_GRACE`), and `process()`/`resume_with_job_result()` close their inner generators with `aclosing`, so a run never outlives its turn. `adk/interrupted_calls_plugin.py::InterruptedCallsPlugin` (before `ToolResultCapPlugin`, every app) sets the active tool call around each call (`before_tool_callback`, so a question marks it `asking`), records results with their `state_delta`/`artifact_delta` in `after_tool_callback` (not a long-running starter's `None`: its job answers it), keeps the cap's cut of one (`ToolResultCapPlugin.on_cut`, so a seal sends that cut and its full output is saved once) and rewrites the seals (`error_code` `INVOCATION_ABORTED`, contract-tested) in `on_event_callback`, carrying those deltas, each seal answered from the record of the run its branch names (a seal is written outside that run). ADK's seals pair a result with a call by id alone, so a call whose id a sub-agent's result used is left open: the manager answers those as the stopped turn ends, before it clears the record, the same way (`_answer_unsealed`, shielded; `unsealed`, once ADK's seals are written), so a call that finished beside a delegation keeps its result; then a delegation that returned without its result event (ADK hands a step's parallel results back after the last) ends its run with that result, not `interrupted` (`_end_returned_runs`). `left_open` answers leftovers when `process()` starts (every app: a task-mode agent's delegation, which ADK keeps open on purpose, is refused at build, and ADK's client calls for a human, `adk_request_confirmation`/`_credential`/`_input`, are answered as interrupted, since the manager offers no way to answer them), a result pairing with a call on its own branch only; one a stop left because its answers could not be written is answered `INTERRUPTED_BY_USER` (the manager records the stop). On Deep Agents `InterruptedCallsMiddleware` takes `PatchToolCallsMiddleware`'s place, first in every stack: it records each final `ToolMessage` with the rest of its `Command` update (outermost tool wrapper) and answers open calls in `before_agent`, returning those updates too; the root adds `MARKER` before the new input when the message before it is no reply (a `HumanMessage` or a tool result). Background jobs are not part of the turn: they keep running. Nor is a synchronous tool's function (a sandbox cell, `compile_document`, `execute_python`): it runs in a worker thread on both backends (ADK's tool thread pool, LangChain's executor), which Python cannot stop, so its call is answered at once but the function runs on to its end, keeps its sandbox session busy (the session's next call waits for it) and holds the process's exit until it returns (the sandbox's cleanup stops a cell). So is a knowledge-base ingest's store step (`kb_ingest_text`, `kb_ingest_file`, `ingest_arxiv_paper`: `KnowledgeBase._store` runs `ingest_document` in `asyncio.to_thread`): a cancelled ingest is answered `INTERRUPTED_BY_USER` and still stores its document, so a model that retries it stores a second copy; a cancelled `sidecar` or `backfill_sidecars` keeps its lock or flag until its thread's call ends (`memory/kb/manager.py::_Threads`). - **Session identity**: durable sessions are addressed by `SessionRef(app_name, user_id, session_id)` (`workflow/sessions.py`). Every session hook (`session_exists`/`list_sessions`/`session_info`/`delete_session`/`recent_messages`/`load_session`) takes an optional `user_id`, defaulting to `settings.default_user` only when the caller omits it. `list_sessions(limit=)` returns `SessionInfo` rows, newest first, and `session_info` one conversation's or None: the title is the first prompt (`session_title`), the turns what the user typed (a job's notice or resume, a delegated request and a summary are none), `updated` when it last changed. ADK keeps the title and the turns in two session-state keys saved with each user turn (`workflow/adk/sessions.py`, `run_async(state_delta=)`; a conversation from before them is read from its events and never written back, which would move it in the list), Deep Agents keeps them in a session index, a LangGraph store beside the checkpointer (`workflow/deepagents/sessions.py`: each row written as a turn starts, its input counted, then from the newest root checkpoint as it ends and after `/compact`, so a listing reads no checkpoint; a database from before the index scanned once per app and user), LangGraph knows only the id; ADK's `delete_session` looks the session up first, so an unknown id is False. Backends without a session store leave `supports_sessions` False, and the base hooks raise `NotImplementedError` rather than answering with a misleading `False`/`[]`. Deep Agents keys each conversation's checkpointer thread by the whole triple (`workflow/deepagents/sessions.py::thread_id`, `json.dumps([app_name, user_id, session_id])`) and stores it in each checkpoint's metadata, so the backfill's scan filters by app and user and keeps the root namespace; sub-agents are compiled with `checkpointer=False` and store none (an older version's sit under `tools:`, and `delete_session` removes them with the thread and the row, returning False for an unknown id). A backend's conversations are read without its manager through its `SessionReader` (`workflow/session_readers.py::open_session_reader`: the backend's own session code over its store, opened from the settings), so the CLI lists, opens and deletes the conversations of every installed backend (`cli/stored_conversations.py`): each row names its backend (`SessionInfo.backend`), and a conversation another backend keeps opens there (no index joins the stores, and an id two backends keep is two conversations). - **Active turn**: the in-flight `(user, session)` is a `ContextVar` (`workflow/sessions.py::get_active_turn`), set with a token by `_workflow_context()`, which every turn enters through `_turn()` — concurrent turns on one manager stay isolated and nesting restores the outer turn. The tool call in progress is another (`get_active_tool_call()`, a `ToolCallRef(call_id, name)`), set by Deep Agents' `ActiveToolCallMiddleware`, innermost in the tool stack (after the gate and the error middleware, so only a call the gate let through runs as one); on ADK, `InterruptedCallsPlugin.before_tool_callback` sets it around each call (ADK's stand-in for an unknown tool name excepted) and its `after_tool_callback` resets it. The sub-agent run in progress is a third (`get_active_run()`, a `RunRef`; None in the root's own calls), set on ADK by `MainAgentPlugin.before_agent_callback` from the agent's invocation branch, and the parent's set again by its `after_agent_callback` and `on_agent_error_callback` (ADK runs a delegated sub-agent inside its parent's call, whose after-tool callbacks are the parent's), and on Deep Agents by `ActiveToolCallMiddleware` around a `task` call to one of the agent's own sub-agents (the whole sub-agent runs inside it): a sub-agent's model calls, tool calls, permission checks and questions see it. `JobManager.submit(resume_on_complete=True)` takes `call_id` from the active tool call when the tool passed none, and `call_name` when that is None too; every `submit` records the sub-agent run in progress as the job's `started_by` (`instance_of(get_active_run())`). - **Job notifications**: both backends tell a finished job through the base's `resume_with_job_result` (a template: the record names its conversation, a turn of it (`_turn`), the conversation there (`_conversation_exists`), the job's result read on a worker thread (`JobManager.result` takes the jobs directory's cross-process lock), the notice `job_notice`, told by the backend's `_deliver_job_notice`; `can_resume` makes the same checks without the turn), and the CLI resumes where `supports_job_resume` and `can_resume` say so. On ADK a finished job is told to the conversation (the root, or a native app's agent the root transferred it to) as one user-role text, `tools/jobs/resume.py::job_notice` (the Deep Agents notice below), whoever started it: its call already has a result (the root's "pending", or a sub-agent's job id), and a second result for the call itself made ADK's rearranger send the call, that result and nothing between, so the root answered without the turns since. A native ADK YAML app's job is told the same way (it used to answer its pending call as a `FunctionResponse`, and needed `record.call_id`); a call still open (a starter that returned nothing) is answered first (`_answer_left_open`). A sub-agent's long-running tools are not wrapped (`_build_agent` wraps the root's only): ADK pauses the whole invocation on a pending long-running call, inside a delegation too, so a sub-agent's starter returns the job id as an ordinary result. ADK's `recent_messages` leaves the notice out by its header, since ADK keeps no mark on a message. The CLI delivers only the jobs that wait for the current conversation, by one rule (`cli/waiting_jobs.py`) for the deliveries, the status bar's `↻N` and the line startup says: a finished job flagged `resume_on_complete` whose delivery is still `PENDING` (`JobRecord.awaiting_resume`: not one being delivered), that is this conversation's, or has none, or whose conversation is gone, `can_resume` saying so and no other installed backend's store keeping it (`waiting_jobs.opens_anywhere`, `BaseCLIApp._kept_elsewhere`) (those two told it is unavailable): another conversation's waits until it is opened, `/resume` (`resume_session`) telling them when `job_auto_resume` is on, startup only naming them (`_name_its_waiting_jobs`: outside the input handler Ctrl+C cannot stop a turn); the status bar's `↻N` counts them whatever the setting (`↻N: /jobs resume` when it is off; its `can_resume` answers kept 30 s, forgotten after `/sessions --delete`, a conversation `/new` drops on the memory store, or a new conversation on another backend). On Deep Agents a finished job's result cannot be the pending call's second result (the call already has its `pending` one, and Anthropic and OpenAI take one result per call), so `resume_with_job_result` runs a turn whose input is one `HumanMessage`: `tools/jobs/resume.py::JOB_NOTICE_HEADER`, the ask (`job_notice_ask`: for the root's own job `JOB_NOTICE_ASK`, tell the user what it means: without it a model may say nothing; for a sub-agent's, `JOB_NOTICE_ASK_FOR`, the same ask naming the sub-agent), then `job_result_payload(record, result)` as JSON, a line each (`job_notice`), marked `response_metadata={"agentic_cli": {"kind": "job_result", "job_id": ...}}` (`workflow/deepagents/sessions.py::job_notification`). No provider adapter sends that field; `recent_messages`, and so fact extraction, leaves the message out; the checkpoint keeps it for the model. The root agent receives every job, a sub-agent's too (its run ended when its `task` returned), and the notice names the sub-agent whose call started it (`JobRecord.started_by`, its instance, from the active run at submit; `job_notice_ask`: "A background job researcher-2 started has finished…", the root's own `JOB_NOTICE_ASK`). `can_resume` needs the record's session and user and the conversation's thread, not a call id. @@ -292,6 +292,7 @@ Available session methods: - **Provider fakes**: model requests never reach a provider. Every offline test runs with the dead base URLs (the root conftest's autouse `_dead_provider_urls`, `tests/network_guard.py::dead_base_urls`: each built-in provider SDK's host variable at a dead local port, with `NO_PROXY` for it, and the variables that would override it removed: ChatAnthropic's and ChatOpenAI's host and proxy, LangSmith's gateway, the Vertex AI switches; a test marked `llm` keeps the real environment), so a built-in provider's client that a test did not route fails at once, locally; a test that needs an SDK's own default host deletes the variable itself. A configured provider's host is its settings entry's, so routing alone protects it; a child process given its own environment (`child_env`) runs without the guard, as does a module- or session-scoped fixture. No run uploads LangSmith traces: the root conftest's `pytest_configure` removes the tracing switches once (langsmith caches its environment reads), and the live tests' key file never sets them. `tests/workflow/adk/fakes.py::FakeAPI` serves an ADK-built model's client (`serve()`) and records the bodies it sends; a native ADK YAML app's bare `claude-*` model builds its client from the binding ADK's `anthropic_llm` module made at import, which patching `anthropic.AsyncAnthropic` misses: `route_anthropic` routes both bindings; `tests/workflow/langchain_fakes.py`'s `route*` helpers send a LangChain chat model's client to it, with the SSE replies a LangGraph or Deep Agents turn needs. A test-first run against the old code must fail offline too, so stub any client the old code would build - **Session fakes**: a session fake is `tests/cli/dialog_fakes.py::autospec_session()` (`create_autospec(ThinkingPromptSession)`), so a call to a method thinking-prompt lacks fails; `edited_dialog(edits)` is a real `Dialog` whose fields hold the user's edits (patch the module's `Dialog`). The render tests' `RecordingSession` and `RecordingThinkingBox` (`tests/event_replay.py`) are checked against the real classes by `tests/test_session_fakes_contract.py`. Turns on a real console run `tests/cli/console_app.py` over a pty (`tests/cli/test_console_turns.py`) - **Deep Agents fakes**: `tests/workflow/deepagents/fakes.py::ScriptedChat` answers each model call from a script and records the requests, so a test drives a whole agent tree offline; patch `agentic_cli.workflow.deepagents.manager.build_chat_model` with `ScriptedModels(agent=[...])`. Turns through the real provider adapters are in `tests/integration/test_deepagents_turns.py` (on `FakeAPI`), and MCP tests start the stdio server `tests/workflow/deepagents/mcp_server.py` through `test_mcp.py`'s `servers` fixture, which checks that no server outlives its test. The shared contract tests (`test_lifecycle_races.py`, `test_resource_ownership.py`, `test_model_switch_keeps_services.py`, `test_backend_isolation.py`) cover Deep Agents beside ADK, and a backend change runs them +- **Sub-agent contract suite**: `tests/workflow/test_subagents_contract.py` runs every sub-agent behaviour both backends share as one scenario on each, ADK through `FakeAPI` (Claude) and Deep Agents through `ScriptedChat`, and expects the same events, run records and results. A scenario's model answers are written once, in backend-neutral steps (`says`, `calls` with `delegate` and `use`, `fails`), which its harness turns into each backend's (`make_crew`: the team's manager on the backend; `Crew`: a turn, one stopped as Ctrl+C does, the run records, the usage ledger and what each agent's model was sent). A difference a library forces is asserted per backend, with a comment naming it. A behaviour both backends share gets a scenario there - **Deprecated LangGraph**: the suite tests it until 0.8.0, so `pyproject.toml`'s pytest `filterwarnings` ignores its `DeprecationWarning` (`pytest.warns` still records it). `tests/cli/test_langgraph_deprecation.py` checks the warning and, on a real console over a pty, that the CLI shows its own notice instead - **MockEmbeddingService** (`agentic_cli.memory`): keyword-only knowledge bases without ML dependencies; `tests/memory/fake_embeddings.py::FakeEmbeddingService` stores deterministic vectors and searches by meaning, no `kb` extra needed - **`kb` extra tests**: import sentence_transformers or trafilatura with `require_kb_module(name)` (`tests/memory/kb_extra.py`), not `pytest.importorskip`. Without the extra the test skips; CI's `kb-extra` job installs it and sets `KB_REQUIRE_EXTRA=1`, so a missing library fails there instead of skipping. No offline test loads an embedding model. diff --git a/README.md b/README.md index 204ad3c6..5401edbe 100644 --- a/README.md +++ b/README.md @@ -1279,8 +1279,9 @@ references, self-references, delegation cycles, a sub-agent shared by two parents, and **more than one root** raise `AgentGraphError` naming the offending agents. Exactly one agent may be unreferenced: the runner starts from a single root, so agents under any other root would never run. -`inherit_context=True` on the root or on an agent with sub-agents of its own, -and an `inherit_context` that is not True or False, raise it too, and on ADK, +`inherit_context=True` on the root, on an agent with sub-agents of its own or +on an agent below another sub-agent, and an `inherit_context` that is not True +or False, raise it too, and on ADK, when the agents are built, so does a sub-agent named like one of its parent's tools. Agents are built in dependency order, so declaration order does not matter. Then every agent's model is resolved, with the default model, before diff --git a/src/agentic_cli/cli/agents_command.py b/src/agentic_cli/cli/agents_command.py index 9885fd20..85cdef5e 100644 --- a/src/agentic_cli/cli/agents_command.py +++ b/src/agentic_cli/cli/agents_command.py @@ -11,8 +11,10 @@ The runs are the manager's records (``BaseWorkflowManager.agent_runs``, ``workflow/agents/runs.py``) and the tokens its usage ledger's -(``usage_of``), so a run still going shows what it has used so far. They -are this process's runs, one run per instance. +(``usage_of``), so a run still going shows what it has used so far. Both +live in memory with the manager: a conversation resumed from an earlier run +of the app, or after a backend switch (a new manager), lists none. Each +instance runs once. """ from __future__ import annotations @@ -36,6 +38,12 @@ #: How many lines of a run's result ``/agents `` shows. RESULT_LINES = 3 +#: What ``/agents`` says for a conversation with no run recorded. +NO_RUNS = ( + "No sub-agent runs in this conversation yet. Runs are kept while the app " + "runs, by its backend: a conversation resumed from an earlier run of the " + "app, or after a backend switch, lists none." +) def _now() -> datetime: @@ -80,7 +88,7 @@ async def execute(self, args: str, app: Any) -> None: app.session.add_rich(_one(mine, ledger)) return if not records: - app.session.add_message("system", "No sub-agent runs in this conversation yet.") + app.session.add_message("system", NO_RUNS) return app.session.add_rich(_table(records, ledger)) diff --git a/src/agentic_cli/workflow/adk/event_processor.py b/src/agentic_cli/workflow/adk/event_processor.py index 54ad5df3..2ec358f7 100644 --- a/src/agentic_cli/workflow/adk/event_processor.py +++ b/src/agentic_cli/workflow/adk/event_processor.py @@ -68,8 +68,12 @@ class ADKEventProcessor: delegation tool hands its parent "Error running sub-agent: …" and the parent carries on. ADK records the provider's reason on the sub-agent's error event, which becomes a recoverable ``ERROR``, " failed: - ", so the user is told why. With neither a root nor reply agents, - nothing is marked. + ", so the user is told why. The parent does not read that + reason, unlike on Deep Agents: ADK's private delegation tool + (``_SingleTurnAgentTool``) catches the wrapper error its node runner + raises, so the parent reads "Error running sub-agent: Dynamic node + failed". With neither a root nor reply agents, nothing is + marked. A call's ``LLM_USAGE`` is credited to the agent that made it, the event's author: ``metadata["agent"]``, that agent's own model (``models``; the diff --git a/src/agentic_cli/workflow/adk/interrupted_calls_plugin.py b/src/agentic_cli/workflow/adk/interrupted_calls_plugin.py index e787e17d..d12b6c79 100644 --- a/src/agentic_cli/workflow/adk/interrupted_calls_plugin.py +++ b/src/agentic_cli/workflow/adk/interrupted_calls_plugin.py @@ -312,9 +312,13 @@ def unsealed(events: list[Event], open_calls: OpenCalls, runs: AgentRuns) -> lis other ``INTERRUPTED_BY_USER``. The manager writes them before the turn clears its record. - Only once ADK has sealed the stopped invocation (its seals are the - session's last events): seals written after these answers would answer - a call twice. ``left_open`` answers, at the next turn, what is left. + Only once ADK has sealed the stopped invocation: seals written after + these answers would answer a call twice. The check is that the + session's last event is a seal, which is also so between two of ADK's + seal appends; a read made there is caught by the durable store's stale + check (an append to a session changed since it was read fails, and + ``left_open`` answers the call at the next turn), not by this check. + ``left_open`` answers, at the next turn, what is left. """ if not events or events[-1].error_code != ABORTED: return [] diff --git a/src/agentic_cli/workflow/adk/manager.py b/src/agentic_cli/workflow/adk/manager.py index ca0e5d4e..31fc1a1a 100644 --- a/src/agentic_cli/workflow/adk/manager.py +++ b/src/agentic_cli/workflow/adk/manager.py @@ -1165,7 +1165,7 @@ async def _answer_unsealed(self, ref: SessionRef) -> None: self._open_calls.clear(ref) def _end_returned_runs(self, ref: SessionRef) -> None: - """End, from the record, each open run whose delegation returned; before the record is cleared. + """End each open run whose delegation returned, from the record, before it is cleared. ADK hands a model step's parallel function responses back in one event, after the last one returns, so a delegation that finished diff --git a/src/agentic_cli/workflow/adk/subagent_outcome_plugin.py b/src/agentic_cli/workflow/adk/subagent_outcome_plugin.py index 2dd92d81..addcca53 100644 --- a/src/agentic_cli/workflow/adk/subagent_outcome_plugin.py +++ b/src/agentic_cli/workflow/adk/subagent_outcome_plugin.py @@ -31,8 +31,10 @@ after the raw log, which records the answer as the model gave it. An answer that calls tools is not final and is left alone, as is every answer of the root and of an agent the root transfers to (no active run): they reach the -user as their model gave them (a refusal with no answer is the turn's failure, -as before). +user as their model gave them (a Claude or Gemini refusal with no answer is the +turn's failure, " returned no answer"; a root on OpenRouter or an +OpenAI-compatible server replies "OpenAI refusal: ", as +``OpenAICompatibleLlm`` words a Chat Completions refusal). """ from __future__ import annotations diff --git a/src/agentic_cli/workflow/agents/runs.py b/src/agentic_cli/workflow/agents/runs.py index f1009bb5..e099d4b2 100644 --- a/src/agentic_cli/workflow/agents/runs.py +++ b/src/agentic_cli/workflow/agents/runs.py @@ -15,7 +15,9 @@ ``interrupt_open``, for the runs a turn leaves open when it is stopped or fails, when no event can reach its consumer any more. A conversation is a ``SessionRef``, or None for a processor driven outside a manager. All of it -is in memory, for the process. +is in memory, for as long as its manager lives: a backend switch builds a +new manager, and the runs recorded before it do not follow (as with its +usage ledgers). """ from __future__ import annotations @@ -209,7 +211,7 @@ def run_number(run: str) -> str: class AgentRuns: - """A manager's sub-agent runs, kept by conversation, in memory for the process.""" + """A manager's sub-agent runs, kept by conversation, in memory for the manager's life.""" def __init__(self) -> None: # (conversation, parent run, call id) -> the run that call started. diff --git a/src/agentic_cli/workflow/config.py b/src/agentic_cli/workflow/config.py index ae52b76e..eb19dda7 100644 --- a/src/agentic_cli/workflow/config.py +++ b/src/agentic_cli/workflow/config.py @@ -277,7 +277,7 @@ def _check_inherit_context(config_map: dict[str, AgentConfig], root: str) -> Non Raises: AgentGraphError: Naming the agent(s) and what to change. """ - # Not coerced: "fresh", a value of the field's unreleased predecessor, is + # Not coerced: "fresh", a value of this field's earlier string form, is # truthy, and would show a sub-agent the whole conversation. unknown = [ f"{name!r} ({config.inherit_context!r})" diff --git a/src/agentic_cli/workflow/deepagents/middleware.py b/src/agentic_cli/workflow/deepagents/middleware.py index 36b2ee9c..527e9e87 100644 --- a/src/agentic_cli/workflow/deepagents/middleware.py +++ b/src/agentic_cli/workflow/deepagents/middleware.py @@ -876,11 +876,12 @@ async def awrap_model_call( class SubAgentOutcomeMiddleware(AgentMiddleware): """A sub-agent's refused or cut final answer, said so (``workflow/agents/outcome.py``). - Deep Agents' ``task`` hands the parent the sub-agent's last text: a - refusal reached it as an empty result (before deepagents 0.7.34, which - words its own notice), and an answer cut at the output limit as a - complete one. Outermost on each sub-agent's model side (never the - root's, whose answers reach the user as its model gave them), this + Deep Agents' ``task`` hands the parent the sub-agent's last non-empty + text: a refusal reached it as the text before it, empty when there was + none (before deepagents 0.7.34, which words its own notice), and an + answer cut at the output limit as a complete one. Outermost on each + sub-agent's model side (never the root's, whose answers reach the user + as its model gave them), this rewrites a final answer (one without tool calls) that a model refused (a refusal block, Claude's ``refusal`` stop, OpenAI's ``content_filter``, a Gemini block of the answer or of the prompt: ``marked_answer`` says what diff --git a/src/agentic_cli/workflow/interrupts.py b/src/agentic_cli/workflow/interrupts.py index d657a16c..107e0573 100644 --- a/src/agentic_cli/workflow/interrupts.py +++ b/src/agentic_cli/workflow/interrupts.py @@ -81,12 +81,12 @@ def job_for_call(call_id: str | None, *, started_by: str | None = None) -> Any | Only a job of the active turn's conversation (its session and user), and none outside a turn: the job store holds all the user's jobs, from every - run, and a provider that numbers its call ids (``call_0``, ...) repeats - them in every conversation. And only a job ``started_by`` started: the - caller names the run whose call it is by its instance (None for the - root's own call), as ``JobRecord.started_by`` records it, since such a - provider repeats them across agents too, and a sub-agent's job must not - answer its parent's call. A caller that cannot name the run (ADK's + start of the app, and a provider that numbers its call ids (``call_0``, + ...) repeats them in every conversation. And only a job ``started_by`` + started: the caller names the run whose call it is by its instance (None + for the root's own call), as ``JobRecord.started_by`` records it, since + such a provider repeats them across agents too, and a sub-agent's job + must not answer its parent's call. A caller that cannot name the run (ADK's ``left_open``, for a sub-agent's call) asks for no job. Looked up among the jobs the manager holds (``JobManager.snapshot``), with diff --git a/src/agentic_cli/workflow/usage.py b/src/agentic_cli/workflow/usage.py index 5e790889..c2b953d2 100644 --- a/src/agentic_cli/workflow/usage.py +++ b/src/agentic_cli/workflow/usage.py @@ -234,7 +234,6 @@ def llm_usage_event( ) - def adk_usage_event( model: str, usage: Any, @@ -264,6 +263,7 @@ def adk_usage_event( latency_ms=latency_ms, ) + # -- what a side call is for ---------------------------------------------------- diff --git a/tests/cli/test_agents_command.py b/tests/cli/test_agents_command.py index e139c3a9..b98e0545 100644 --- a/tests/cli/test_agents_command.py +++ b/tests/cli/test_agents_command.py @@ -19,7 +19,7 @@ from rich.console import Console from agentic_cli.cli import agents_command -from agentic_cli.cli.agents_command import AgentsCommand +from agentic_cli.cli.agents_command import NO_RUNS, AgentsCommand from agentic_cli.cli.commands import CommandCategory, CommandRegistry from agentic_cli.config import BaseSettings from agentic_cli.workflow.adk.manager import GoogleADKWorkflowManager @@ -155,9 +155,7 @@ async def test_every_run_each_followed_by_the_runs_it_started(self, manager): async def test_a_conversation_without_runs_says_so(self, manager): session = await agents(manager) - session.add_message.assert_called_once_with( - "system", "No sub-agent runs in this conversation yet." - ) + session.add_message.assert_called_once_with("system", NO_RUNS) session.add_rich.assert_not_called() async def test_another_conversations_runs_are_not_listed(self, manager): @@ -165,9 +163,7 @@ async def test_another_conversations_runs_are_not_listed(self, manager): session = await agents(manager, session_id="s2") - session.add_message.assert_called_once_with( - "system", "No sub-agent runs in this conversation yet." - ) + session.add_message.assert_called_once_with("system", NO_RUNS) async def test_a_title_is_shown_as_written(self, manager): """Titles are the model's words: markup in one is text, never style.""" diff --git a/tests/workflow/test_usage_ledger.py b/tests/workflow/test_usage_ledger.py index 42fbfff6..b69b2171 100644 --- a/tests/workflow/test_usage_ledger.py +++ b/tests/workflow/test_usage_ledger.py @@ -1,8 +1,8 @@ """Token usage: the ledger that keeps a conversation's model calls, a row each. Each manager keeps a ledger per conversation (``UsageLedgers``), in memory for -the process; it answers totals by run, agent, model, purpose and turn. A side -call's caller says what it is for (``side_call``). +the manager's life; it answers totals by run, agent, model, purpose and turn. +A side call's caller says what it is for (``side_call``). """ from __future__ import annotations