diff --git a/CHANGELOG.md b/CHANGELOG.md index 36360266..fe390f36 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -73,10 +73,14 @@ the start of the entry's title. capability…**; Added: **`task` is a reserved…**) - In an ADK app built from configs, a sub-agent is called through `task` and returns (no `transfer_to_agent`), seeing only its task unless - `inherit_context=True`; a synchronous tool must be safe in a worker thread - beside other calls; a prompt's `{name}` is not filled from session state. - (Changed: **ADK sub-agents are delegated…**, **On ADK, synchronous…**, **On - ADK, an agent's prompt…**) + `inherit_context=True`, and shares only the plan, the tasks and the + outside-content mark with its caller: any other session-state key an ADK + tool writes in a sub-agent run, `user:` and `app:` keys too, never + reaches the conversation; a synchronous tool must be safe in a worker + thread beside other calls; a prompt's `{name}` is not filled from session + state. + (Changed: **ADK sub-agents are delegated…**, **One `task` tool on both + backends…**, **On ADK, synchronous…**, **On ADK, an agent's prompt…**) - On both backends a coordinator delegates with `task(agent_type=, title=, objective=, ...)` and reads the run's envelope, a JSON object, as the call's result: a prompt that names a sub-agent's own tool @@ -610,11 +614,14 @@ the start of the entry's title. starts, is cancelled (`"status": "cancelled"`, `"cancelled_by": "limit"`, `"error": "time limit reached"`), the text it wrote so far its partial result, and a question or permission prompt it waited at is - withdrawn; a model call that takes a run past its `max_tokens` and asks - for tools is its last, its calls dropped, and the run is cancelled + withdrawn; a model call that takes a run past its `max_tokens` (checked + after each of its model calls, against the run's total as its usage + record counts it: its own calls, its tools' side calls such as + web_fetch's summary, and Deep Agents' summaries of its conversation) and + asks for tools is its last, its calls dropped, and the run is cancelled likewise (`"token limit reached"`), that answer's text its result, while one that asks for none ends the run as it would, completed, its result - whole (a model that reports no usage is not limited by tokens). + whole (a model that reports no usage counts none of its own). Construction refuses, with a `ValueError` naming the field, a limit that is not a positive int (a timeout: a positive, finite number; `True` and `False` are no numbers here) and a policy whose `limits` is not an @@ -682,7 +689,8 @@ the start of the entry's title. conversation's sub-agent runs, each followed by the runs it started: instance, type, status (`running`, `queued` waiting for a free working slot, `needs you` waiting on the user, `completed`, `completed (partial)` - for an answer cut at its output limit, `refused`, `failed`, `interrupted`), + for an answer cut at its output limit, `refused`, `failed`, `cancelled`, + `interrupted`), run, title, tokens in/out (from the usage ledger, so a run still going 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, @@ -736,12 +744,20 @@ the start of the entry's title. brief's title, the brief's filled fields (`brief`), who started it (`started_by`: `agent:`, `agent:root` for the main agent) and how it runs (`mode`: `blocking`, its caller waiting for it), then, while - it works, `queued` (waiting for a free working slot), `running` (once it - has one, and once the user has answered) and `input_required` (waiting - on the user), 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 when it cannot finish (a model call of its fails, its request no - longer fits its model's window, or its model gives no answer), and the + it works, `queued` (waiting for a free working slot: to start, or to + take its own back once the user has answered while another run works in + it), `running` (once it has one) and `input_required` (waiting on the + user), then `completed` (`partial` for an answer cut at its output + limit), `refused`, `failed`, `cancelled` (by its parent, the user or a + limit: `cancelled_by`) or `interrupted`, with the first 200 + characters of its result; a run fails when it cannot finish (a model + call of its fails, its request no longer fits its model's window, or, on + ADK, its model's last reply has nothing in it and ends for a reason that + is none of stop, a refusal or the output limit, such as a malformed + function call: ` returned no answer`; a refused or blocked reply + ends the run `refused`, an empty one cut at the output limit `completed` + and `partial`, and a run whose model wrote no text at all completes, its + result empty), and the sub-agent's answer is never read for success, so an answer that is JSON saying it failed completes), the same on both backends: the framework starts and ends every run (`workflow/agents/delegate.py`), each at its own @@ -1325,9 +1341,10 @@ the start of the entry's title. sees only the task its parent gives it; True also sees the parent's conversation as it stands, after any summary and without the parent's reasoning, the same way on both backends: the run starts from that - conversation, less the message that called `task`, then its task message, - which ends with a note (`agents/brief.py::INHERITED_CONTEXT_NOTE`) that the - conversation is its parent's and its task the message the note ends: + conversation (on Deep Agents less the message that called `task`, which + ADK's copy keeps), then its task message, which ends with a note + (`agents/brief.py::INHERITED_CONTEXT_NOTE`) that the conversation is its + parent's and its task the message the note ends: without it, Claude at times answered the user's request to the coordinator instead of its own. On ADK the conversation's events are copied into the run's child session; on Deep Agents they are the run's @@ -1627,10 +1644,16 @@ the start of the entry's title. its result is `{"success": false, "error": ...}` naming what to fix. A run starts from the conversation's `plan` and `tasks`, and the changes it makes to them reach its caller's state when it returns (the status bar's - task list moves then). On ADK each sub-agent type runs on a runner of its - own over the manager's session service, on a child session of the run - (app `--agents`, id `/`), which no - conversation list shows, and, an agent of its own there, its system + task list moves then). On ADK nothing else of a run's session state does + (with the outside-content mark, these are all a run and its caller + share): any other key an app's ADK tool writes in a sub-agent run stays + in the run's child session, and a `user:` or `app:` scoped one is kept + under the child app (`--agents`), so the conversation never + sees it, where in 0.6 such keys reached the conversation; nor does a run + read the conversation's other keys. On ADK each sub-agent type runs on a + runner of its own over the manager's session service, on a child session + of the run (app `--agents`, id `/`), + which no conversation list shows, and, an agent of its own there, its system instruction gets ADK's identity line after its prompt as the root's does (`You are an agent. Your internal name is "".`, then its description); on Deep Agents each type's graph runs apart from @@ -1641,7 +1664,8 @@ the start of the entry's title. "agent": "", "run": "", "status": "", "partial": , "result": "", "error": }`: a failed run's `error` is the provider's reason (where ADK said - "Dynamic node failed"), a refused run's `a model refused the + "Dynamic node failed"), its `result` the text it wrote before it + failed, a refused run's `a model refused the request` with the refusal notice as its `result`, an interrupted run's `interrupted before it finished`. No delegation is an error result any more ("Error running sub-agent: …" is gone): the envelope says how the @@ -2080,7 +2104,7 @@ the start of the entry's title. longer takes over the conversation on later turns. Sub-agents see only their task, where they saw the whole conversation (set `inherit_context=True` for that). - `inherit_context` is for the main agent's own sub-agents in 0.7.0: + `inherit_context` is for the main agent's own sub-agents: `validate_agent_graph` refuses it below another sub-agent, on every backend. A prompt that names `transfer_to_agent` should say to delegate to the agent diff --git a/CLAUDE.md b/CLAUDE.md index 23986d3d..627592e1 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -82,7 +82,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 (a working run's: RUN_QUEUED, RUN_RUNNING, RUN_INPUT_REQUIRED, RUN_WORKING_STATUSES; a record says running from its start), RunRecord, AgentRuns (a manager's runs by conversation: run_for names - and its run #1 per (conversation, parent run, call id), a new one once it ended; number_from: past the instances a conversation's store keeps, a count never lowered; observe records AGENT_RUN under the turn it is reported in; interrupt_open; a record's usage: what the run used, by model, from its end event or the ledger), run_title, result_head, run_instance and run_number (the one reader of a run id: researcher-2#1's instance and number), run_label (how a dialog names a run: researcher-2 (researcher, run 1)), SUBAGENT_ERROR_PREFIX (ADK's old words for a failed delegation, kept for callers), show_as_delegation(result, envelope) (a delegation's TOOL_RESULT shown alike on both backends: the result's first line, or Failed: ; metadata["result"] the envelope); a record's brief, started_by, mode and cancelled_by; delegate.py: Delegations (delegate(DelegationRequest) → Delegated: the one place a run starts and ends, on both backends: the brief read against the caller's own sub-agents, the run named (a turn's first run past the instances its conversation's store keeps: stored=, asked once per conversation per turn, again after a failed or stopped ask), its AGENT_RUN start and end observed and reported, the backend's hook (RunHook: AgentRun → RunAnswer) run in a task of its own with the run active and no tool call, the end by the answer (completed, partial for a cut or the step limit, refused, failed for an error or a raise, with one recoverable ERROR failed: , or RunFailed's own words, cancelled by its control with what the hook had), interrupted on its turn's cancel, which wins; the envelope as the result; each run under its RunControl, the type's limits over the policy's, kept while it works: control(run), cancel(run_id, by=, error=), the run alone; a call past max_runs_per_turn the error result RUNS_PER_TURN_ERROR, no run; each run in a working slot of its conversation's SlotPool, slots(conversation): policy.max_active slots, made on first use and kept, the root taking none: taken right before its hook and its time limit, queued then running while it waits for one, given back at its end, straight back to a caller that waits on it alone; a caller that delegates lends its slot while it waits for its children), DelegationRequest, AgentRun (control), RunAnswer, RunFailed, started_by, waiting_on_user (a sub-agent run waiting on the user: input_required, its slot lent, then running; nested waits once; request_user_input and the permission engine); slots.py: SlotPool (acquire(priority): a free slot, else a future in a heap by priority, RETURNING before NEW, then arrival; release; lent(slot): the slot lent while its run waits, nested lends once, taken back at RETURNING after, at most one take-back waiting for a slot and none once it is held (a wait that starts while one is queued takes it over, and one handed the slot withdraws any queued since), nothing taken back after a cancel; hand_back(slot, to): a child's slot to its parent waiting on it alone; free, waiting; a cancelled waiter leaves the heap, one handed a slot as it is cancelled hands it on; not asyncio.Semaphore), Slot (held, lent), RETURNING, NEW; control.py: RunControl (one run's: cancel(by=, error=) its task, the first cancel winning, own_cancel for the hook that takes it and returns, timing: the time limit while the hook runs; model_call/at_step_limit/final_call: the step limit, STEP_LIMIT_NOTE on the last allowed call; used: the token limit, an answer past it that makes calls the run's last, cancelled by it, one that makes none its result (calls=); model_call once final stays final; a cancel leaves a task its turn is cancelling alone; steer/take_steering), STEP_LIMIT_NOTE; outcome.py: a sub-agent's refused or cut answer (outcome_of, the refusal notice as Deep Agents 0.7.34 words it, cut_off, cut_off_warning, OPENAI_REFUSAL_PREFIX: how ADK's OpenAI adapters word a refusal); policy.py: SubAgentPolicy (max_active, max_runs_per_turn, limits) and AgentLimits (max_model_calls, timeout, max_tokens; over: a type's limits over the policy's, field by field, None taking the base's), DEFAULT_LIMITS (100 model calls), frozen and checked as they are made (a ValueError naming the field), as_policy (the one reading of a subagents= argument: a TypeError for anything but a policy or None); brief.py: BRIEF_FIELDS, Brief, BriefError, read_brief (a task call's agent type and brief, against the types its caller may start: the error texts), task_message (a run's first message, a section per filled field; an inheriting type's ends with INHERITED_CONTEXT_NOTE), task_parameters and task_description (task's schema and description, the same for both backends; limit_sentences: the limits it states, "At most sub-agents work at once; more calls in one response wait for a free slot. At most runs per turn."); envelope.py: envelope (a delegation run's result: success only for completed, a one-line error, cancelled_by for a cancelled run), read_envelope (a dict or its JSON text, else None; never raises), the limit and interrupted error texts +│ │ ├── agents/ # Sub-agents: runs.py: the RUN_* statuses (a working run's: RUN_QUEUED, RUN_RUNNING, RUN_INPUT_REQUIRED, RUN_WORKING_STATUSES; a record says running from its start), RunRecord, AgentRuns (a manager's runs by conversation: run_for names - and its run #1 per (conversation, parent run, call id), a new one once it ended; number_from: past the instances a conversation's store keeps, a count never lowered; observe records AGENT_RUN under the turn it is reported in; interrupt_open; a record's usage: what the run used, by model, from its end event or the ledger), run_title, result_head, run_instance and run_number (the one reader of a run id: researcher-2#1's instance and number), run_label (how a dialog names a run: researcher-2 (researcher, run 1)), SUBAGENT_ERROR_PREFIX (ADK's old words for a failed delegation, kept for callers), show_as_delegation(result, envelope) (a delegation's TOOL_RESULT shown alike on both backends: the result's first line, or Failed: ; metadata["result"] the envelope); a record's brief, started_by, mode and cancelled_by; delegate.py: Delegations (delegate(DelegationRequest) → Delegated: the one place a run starts and ends, on both backends: the brief read against the caller's own sub-agents, the run named (a turn's first run past the instances its conversation's store keeps: stored=, asked once per conversation per turn, again after a failed or stopped ask), its AGENT_RUN start and end observed and reported, the backend's hook (RunHook: AgentRun → RunAnswer) run in a task of its own with the run active and no tool call, the end by the answer (completed, partial for a cut or the step limit, refused, failed for an error or a raise, with one recoverable ERROR failed: , or RunFailed's own words, its result the text the run wrote before it failed (RunFailed(text=); a failed model call the hook's RunAnswer.error, failure_reason, with error_code its type, the warning's code), cancelled by its control with what the hook had), interrupted on its turn's cancel, which wins; the envelope as the result; each run under its RunControl, the type's limits over the policy's, kept while it works: control(run), cancel(run_id, by=, error=), the run alone; a call past max_runs_per_turn the error result RUNS_PER_TURN_ERROR, no run; each run in a working slot of its conversation's SlotPool, slots(conversation): policy.max_active slots, made on first use and kept, the root taking none: taken right before its hook and its time limit, queued then running while it waits for one, given back at its end, straight back to a caller that waits on it alone; a caller that delegates lends its slot while it waits for its children), DelegationRequest, AgentRun (control), RunAnswer, RunFailed, started_by, waiting_on_user (a sub-agent run waiting on the user: input_required, its slot lent, queued while its take-back waits for a slot, then running; nested waits once; request_user_input and the permission engine); slots.py: SlotPool (acquire(priority): a free slot, else a future in a heap by priority, RETURNING before NEW, then arrival; release; lent(slot, on_wait=): the slot lent while its run waits, nested lends once, taken back at RETURNING after (on_wait called when that has to wait), at most one take-back waiting for a slot and none once it is held (a wait that starts while one is queued takes it over, and one handed the slot withdraws any queued since), nothing taken back after a cancel, so a tool's caught timeout around a question leaves its run working without a slot, input_required until its next question is answered (running again, still without a slot) or its end; hand_back(slot, to): a child's slot to its parent waiting on it alone; free, waiting; a cancelled waiter leaves the heap, one handed a slot as it is cancelled hands it on; not asyncio.Semaphore), Slot (held, lent), RETURNING, NEW; control.py: RunControl (one run's: cancel(by=, error=) its task, the first cancel winning, own_cancel for the hook that takes it and returns, finish: the hook's work ended, no cancel after it (ADK's state read loses no answer), timing: the time limit while the hook runs; model_call/at_step_limit/final_call: the step limit, STEP_LIMIT_NOTE on the last allowed call; used: the token limit, against its own calls and side_tokens (its side calls and summaries, from the ledger), an answer past it that makes calls the run's last, cancelled by it, one that makes none its result (calls=); model_call once final stays final; a cancel leaves a task its turn is cancelling alone; steer/take_steering), STEP_LIMIT_NOTE; outcome.py: a sub-agent's refused or cut answer (outcome_of, the refusal notice as Deep Agents 0.7.34 words it, cut_off, cut_off_warning, OPENAI_REFUSAL_PREFIX: how ADK's OpenAI adapters word a refusal); policy.py: SubAgentPolicy (max_active, max_runs_per_turn, limits) and AgentLimits (max_model_calls, timeout, max_tokens; over: a type's limits over the policy's, field by field, None taking the base's), DEFAULT_LIMITS (100 model calls), frozen and checked as they are made (a ValueError naming the field), as_policy (the one reading of a subagents= argument: a TypeError for anything but a policy or None); brief.py: BRIEF_FIELDS, Brief, BriefError, read_brief (a task call's agent type and brief, against the types its caller may start: the error texts), task_message (a run's first message, a section per filled field; an inheriting type's ends with INHERITED_CONTEXT_NOTE), task_parameters and task_description (task's schema and description, the same for both backends; limit_sentences: the limits it states, "At most sub-agents work at once; more calls in one response wait for a free slot. At most runs per turn."); envelope.py: envelope (a delegation run's result: success only for completed, a one-line error, cancelled_by for a cancelled run), read_envelope (a dict or its JSON text, else None; never raises), the limit and interrupted error texts │ │ ├── adk/ # ADK orchestrator │ │ │ ├── manager.py # GoogleADKWorkflowManager (the agents built from configs or, adk_config_path, by ADK from a native YAML (library-only: no BaseCLIApp starts one; loaded once per manager at the first _validate_agent_graph (_native_root: the settings' keys exported first; a retry, a model switch and a start after cleanup build on the same tree, whose toolsets the closed runner left reusable), its agents' models resolved leniently in _resolve_extra_models, the base's hook, its registered tools' services detected; configs passed with it ignored, adk_native_configs_ignored): the only difference; _do_initialize builds the app from the tree alone, _build_app → ADKBuild, through the hooks _plugin_chain (the whole chain, top to bottom, its head _init_plugins), _compaction_config (None for a root without a budget), _context_cache_config, _agent_model_refs; the event processor built from the build; a config-built agent's prompt as an instruction provider, sent as written: no `{name}` state injection; _compact_turn: ADK's compaction once, in the base's compact turn; supports_compact False once built for a root without a budget (_no_compact_support says why); the job resume hooks: _conversation_exists (the session read without its events, num_recent_events=0), _deliver_job_notice (the notice, for every app); _run_config: the agents' synchronous tools run in ADK's tool thread pool, 8 workers; _run_and_stream: a run that fails yields the turn's one ERROR, last, none after an ERROR already yielded, and keeps the record of its calls that returned for the next turn (OpenCalls.failed; _answer_left_open forgets it once its answers are stored); the agents: _create_agents builds each config's agent on its own (_agents, by name; no ADK sub_agents), a delegating one with a TaskTool (its own tool named task: AgentGraphError); a runner per sub-agent type (_agent_runners: NoAfterTurnCompactionRunner on App(name=child_app(app_name), root_agent=the type's agent, plugins=_agent_plugin_chain(agent), the app's context cache, no compaction) over the session service, closed with the main runner by _detach_backend, rebuilt by every initialization); _run_agent, the base's hook: the run's child session (_child_session: run.state, an inheriting run's copied events; never one the store keeps, whose instance numbering goes past: ADK's create_session refuses it, and the run fails), _stored_instances (the base's hook: the highest instance number of each type the conversation's child sessions keep), the type's runner on the task message with an abort signal set before it is closed, a run-mode ADKEventProcessor, the raw log's records reported as they come (_report_raw_log); a model's failure raised as the provider's (_plugin_cause), an overflow RunFailed, a reply that is no answer RunAnswer(error=), the shared keys it changed read back) │ │ │ ├── build.py # ADKBuild (root, reply_agents, plugins, compaction, cache, models); load_native_root (from_config at validation; what ADK cannot load, wrapped as AgentGraphError naming the file, ADK's error the cause; a root that is not an LlmAgent, a name used twice in the tree and a task-mode agent refused, AgentGraphError naming it; ensure_direct_anthropic); what the run reads of any tree: reply_agents (the root and the chat-mode agents it can transfer to), own_after_tool_agents (left out by the cap) @@ -251,7 +251,7 @@ Workflow: - **Tool error handling**: All tools return `{"success": bool, ...}` dicts. Never raise `ToolError`. An exception that still escapes a tool is a bug, but it costs one call rather than the turn: on ADK, `workflow/adk/tool_error_plugin.py::ToolErrorPlugin` turns it into an error dict; on Deep Agents, `workflow/deepagents/middleware.py::ToolCallErrorMiddleware`, inside the permission gate, gives the same result, `{"success": false, "error": " failed: : "}` cut to 500 characters (both use `workflow/tool_errors.py`). A call to a tool name the agent does not have gets ADK's own text, its first two lines (`unknown_tool_result`: "nope failed: ValueError: Tool 'nope' not found." and the agent's tools by name), logged `tool_not_found` at info (the model's mistake): on ADK the permission gate lets ADK's stand-in through (`is_unknown_tool`: a bare `BaseTool` described "Tool not found", which runs nothing; contract-tested) and `ToolErrorPlugin` answers its lookup error; on Deep Agents the gate answers it. It catches `Exception`, never `BaseException`, so cancelling still cancels. `task` raises nothing into it: a sub-agent's model or run failing (its summary or overflow included: its own tools' errors are results already) fails the run, whose envelope its parent reads (`error`: the provider's reason; on ADK out of ADK's plugin wrapper), reported at once through the turn's live events as one recoverable `ERROR`, ` failed: `, the run's: the coordinator carries on. A sub-agent's overflow (still too long after its summary or trim) fails its run, on both backends, in the words of ADK's overflow handler, `: the request no longer fits 's context window.` with `error_code` `CONTEXT_OVERFLOW` (`context.py::subagent_overflow_message`): ADK's `OverflowPlugin` answers the run's model call with it, Deep Agents' manager raises it (`RunFailed`). A refusal is no exception here (the framework adds no `ModelRefusalMiddleware`): a sub-agent whose final answer a model refused ends its run `refused`, and its parent reads, as its envelope's result, Deep Agents 0.7.34's notice ("The subagent stopped because a model refused the request. … Retrying the same request is unlikely to succeed; rephrase it or continue without it."), on both backends and whichever deepagents the pin installs (0.7.28 has no notice of its own; 0.7.34+ finds no refusal block left to word again); an answer cut at the output limit keeps its text, followed by `[cut off at the output limit]`, and its run ends `completed` and `partial`, with one recoverable warning ("'s answer was cut off at the output limit"); the answer's thoughts or reasoning are kept. ADK's `SubAgentOutcomePlugin` and Deep Agents' `SubAgentOutcomeMiddleware` rewrite and mark the answer, by `workflow/agents/outcome.py`. On ADK the plugin reads the answer's `finish_reason` (Claude's `refusal` and a Chat Completions `content_filter` arrive as `SAFETY`, `max_tokens` and `length` as `MAX_TOKENS`, Gemini's as themselves), the `error_code` ADK sets on an answer with no content (a Gemini prompt's `block_reason`), the `reason` an `OTHER` stop names in its JSON error message (ADK's OpenAI Responses adapter's `incomplete_details`, `content_filter` among them) and a text part `OpenAI refusal: ` (that adapter's refusal, and `OpenAICompatibleLlm`'s of a Chat Completions `refusal`, which ADK's class drops). On Deep Agents the middleware reads `response_metadata`'s `stop_reason` (ChatAnthropic), `finish_reason` (ChatOpenAI, ChatGoogleGenerativeAI), `incomplete_details.reason` (the Responses API) and `prompt_feedback.block_reason` (a Gemini prompt block), and a refusal the answer holds (a refusal block, standard or `non_standard`, or `additional_kwargs["refusal"]`). The root's own answers reach the user as their model gave them: on ADK a root's refusal with no answer (Claude's, Gemini's) is still the turn's one `ERROR` (" returned no answer"), and a root on OpenRouter or an OpenAI-compatible server replies "OpenAI refusal: ". On both backends the root's own failure leaves the run: the turn's one `ERROR`. A gate or error result goes back as the call's `ToolMessage` with `status="error"`. LangGraph's `ToolNode` runs with `handle_tool_errors=True`. - **Tool result cap**: every tool result passes `workflow/tool_output.py::cap_tool_result` (registered, MCP and skill tools, `job_result`, a delegation's envelope on either backend): one over `tool_result_max_chars` is cut to its shape and as much of its head and tail as fits (the kept length is bisected, since JSON escapes vary), with a note (under `truncated`, or appended to a string) pointing at its full output in `./.{app_name}/tool-output/`, written for `read_file` to page by lines (lines over 2,000 characters split). A string that holds a JSON object (`json_object`: a delegation's envelope, which both task tools write unescaped, `ensure_ascii=False`; a framework tool's dict in a Deep Agents `ToolMessage`) is cut as that dict and given back as its JSON text, so the parent reads JSON still, on both backends. On ADK, `workflow/adk/tool_result_cap_plugin.py::ToolResultCapPlugin` is registered after `InterruptedCallsPlugin`, since ADK stops at the first `after_tool_callback` that returns a value, and it leaves out an agent with `after_tool_callback`s of its own (a native YAML app's, `build.own_after_tool_agents`), which ADK would skip once the cap answered. ADK's Claude and OpenAI Responses adapters send only a result's `content`, else its `result`, so the plugin also puts the note there (`_note_where_sent`). On Deep Agents, `ToolResultCapMiddleware` sits between the permission gate and `ToolCallErrorMiddleware`, so an error result is capped too, and reads a `ToolMessage` (its text cut by the cap's string rule, text blocks joined into the first) and each `ToolMessage` of a `Command`. A call of the framework's `read_file` (by identity, as each gate resolves tools) on a saved output is cut without a second save. Saving never fails the call (`tool_output_not_saved` warns once per folder, then debug), and a cap that raises leaves the result uncut (`tool_result_cap_failed` at warning, its traceback at debug). - **Summarizing on ADK (main agent only)**: every app's App (a native ADK YAML app's too, when its root's model has a context budget) has ADK's `EventsCompactionConfig` with `workflow/adk/compaction.py::AgentCliSummarizer` at the root's trigger (`context_budget`, as on Deep Agents); ADK checks before every agent's model call, and `MainAgentPlugin` (the first plugin) records the running agent in a ContextVar, so the summarizer writes only for the root (a sub-agent's run, on its type's runner, has no compaction config at all: a sub-agent compacting the shared session lost its brief and looped, 100 requests in one turn, offline). The summarizer picks its own range before paying for anything (`summary_range`: the newest `keep` tokens and the current turn kept, a cut only where a user turn starts, never parting a call from its result, long-running calls excepted since ADK re-injects them, nor leaving a kept event stamped inside the range; none for a saving under 20% of the trigger, the seed left out of it), writes on the root's own model (`_simple_model(SUMMARY_MAX_TOKENS, agent=root)`, thinking off) with `workflow/summary_prompt.py`, the rendering sized to that model's window (the middle cut, `MIDDLE_OMITTED`, the seed kept whole), and returns **user-role** text starting `SUMMARY_PREFIX` (a model-role first message is one Claude refuses), which the fit guard folds, after the memory index when the request has one, into the next user text (`fold_summary`), so no request holds two user messages in a row. `last_kept_turns` and `last_error` are for its callers: a manual summarizer warns of nothing itself. It reports through the turn's live events (`_run_and_stream` iterates the runner through `live_events.merged` under `reporting(live)`); any failure is one recoverable `ERROR` a turn, never raised to ADK. `NoAfterTurnCompactionRunner` overrides ADK's private `Runner._run_post_invocation_compaction` (contract-tested), so the prompt never waits for a summary after the answer. `FitGuardPlugin` is the last plugin (but `SentRequestLoggingPlugin`, which logs a request as sent, and `CallSentPlugin`, which starts the call's clock) and `OverflowPlugin` the one before it (`MemoryIndexPlugin`, when the root has a memory tool and `memory_index_enabled` is on, the one before that: it puts the conversation's memory index snapshot first in the root's requests, never in the session): the guard leaves a request's oldest turns out when it is over its agent's budget (keeping the newest turn and what opens the conversation, the memory index then a summary: `protected_head`) and keeps each request as it came in (`request_as_seen`: one copy per model call, under the call's `EventActions`, which ADK passes to all three of its callbacks: each sub-agent run is an invocation of its own on a child session, but two runs of one type share that type's runner and its plugins, and a run drops only what its own cancelled calls left, as it ends), and the overflow handler, on a provider's overflow, summarizes now (the root, through `compact_session`, ADK's private `_run_compaction_for_token_threshold_config`; `_summarize_now` returns `WrittenSummary(text, kept_turns)`, and the retry is the index, the summary and those turns) or trims to half the budget (a sub-agent, or nothing to summarize), builds the retry from the guard's copy without the context cache, retries once on the agent's `canonical_model`, then answers the root with `LlmResponse(error_code="CONTEXT_OVERFLOW")`, never model text (ADK would store it as the reply), which `ADKEventProcessor` maps to the turn's `ERROR`; a retry that fails otherwise propagates, and `_run_and_stream` unwraps ADK's plugin-manager `RuntimeError` to the provider's error; a sub-agent's call that still does not fit is answered with an error response too, `CONTEXT_OVERFLOW` and `subagent_overflow_message`, which its run's processor keeps as the run's failure: the run ends `failed` with those words (`RunFailed`), its parent reads them in the envelope, and the user is warned once, by the framework's delegation (`agents/delegate.py`), as on Deep Agents. A native ADK YAML app gets all of it: only the building of its agents differs (`workflow/adk/build.py`). Its chat-mode sub-agents keep transferring, and an agent the root transfers to replies to the user (`build.reply_agents`: its text is the reply, recent_messages reads it, its overflow is the turn's clear error, its calls write the outside-content mark); the summary and the memory index stay the root's, so such an agent is trimmed by the fit guard, not summarized. An agent's own callbacks (a native app's) run after every plugin, and only when none answered: its before-model callbacks see the request after the fit guard, and the cap leaves out an agent with after-tool callbacks. A main agent whose model does not resolve through the catalog has no budget and no summary. -- **Sub-agents delegate and return**: on both backends a sub-agent run is a call of its parent's `task` tool (the framework's: `tools/_core/delegation.py` declares it, `workflow/agents/delegate.py` runs it) that returns in the same turn; only the root replies to the user (a sub-agent's `TEXT` carries `metadata["subagent"]`, and the CLI shows it as the events box's status line, under its run's name: `researcher-2 › …`; `/agents` lists a conversation's runs), and the next turn starts at the root; fact extraction reads only the user's and the root's text. `task` takes `agent_type` (one of the caller's own sub-agents) and a brief (`workflow/agents/brief.py`: `title`, `objective`, `deliverable`, `constraints`, `known`, `done_when`), its schema and description the same on both backends (`task_parameters`, `task_description`: a line per type with its description, "The agent." with a warning, `subagent_without_description`, for one without, and the fields `AgentConfig.brief_required` asks for); `read_brief` checks a call against them, and one that cannot start a run is the call's `{"success": false, "error": …}`, no run started or numbered. `Delegations.delegate` (the manager's `_delegations`) does the rest, alike on both: it names the run (`AgentRuns.run_for`), reports its `AGENT_RUN` start (title, brief, `started_by`, `mode`) and end through the turn's live events and the records, and runs the backend's hook, `_run_agent(AgentRun)`, in a task of its own, where the run is the active run and no tool call is, so each run ends at its own end. The run's first message is the task message (`task_message`); it starts from the conversation's `plan` and `tasks` (`AgentRun.state`), and the keys it changed come back to its caller's state (`RunAnswer.state`). It ends as the `RunAnswer` says: its last text (a reply that also called a tool included; none at all, an empty result shown `No answer`), `refused` or `partial` by the outcome mark, `failed` for an error or a raise (one recoverable `ERROR`, ` failed: `, or the hook's own words, `RunFailed`: an overflow's); and the call's result is the run's envelope as JSON (`workflow/agents/envelope.py`), shown by `show_as_delegation`. A cancel of the caller's task stops the run's task first and ends the run `interrupted`. Each run works under its `RunControl` (`workflow/agents/control.py`, `AgentRun.control`), with its type's `AgentConfig.limits` over the policy's (`SubAgentPolicy.limits`, `DEFAULT_LIMITS`: 100 model calls): `Delegations.cancel(run_id, by=, error=)` cancels the run alone (its parent, the user or a limit), and the hook, seeing its own cancel (`own_cancel`), stops the run as a stopped turn's (ADK: its abort signal, its open calls sealed in its child session; Deep Agents: its stream closed) and returns what it has: the run ends `cancelled` with `cancelled_by` and that text, `partial`, while its siblings and the turn go on; the turn's own cancel still wins (`interrupted`). Past its `timeout` (counted from when its hook starts, `timing`) the run is cancelled by its limit (`time limit reached`); each model call is counted before it is made (`RunControlPlugin` in each sub-agent chain, `RunControlMiddleware` on each sub-agent's model side) and the last allowed one gets `STEP_LIMIT_NOTE` after its last message, its tools still declared (Claude refuses tool calls in a request that defines no tools); its answer's calls are dropped, never run, so the run completes `partial`, `step limit reached`; each call's tokens are counted after it, and past `max_tokens` an answer that makes tool calls is the run's last, its calls dropped, `cancelled` by its limit (`token limit reached`), while one that makes none ends the run as it would, `completed`, its result whole (a model that reports no usage is not limited by tokens). A turn starts at most `max_runs_per_turn` runs, at any depth (`sessions.runs_this_turn`): a call past it is the error result, no run started; `task`'s description says so (`limit_sentences`). At most `max_active` runs of a conversation work at once, at any depth (`workflow/agents/slots.py::SlotPool`, one per conversation, `Delegations.slots`; the root takes no slot): a run takes a slot right before its hook and its time limit start and gives it back at its end, however it ends; one that finds none waits `queued` (an `AGENT_RUN` and its record say so, then `running`), not counted against its `timeout`. A run lends its slot while it waits on its children (one lend for all it waits on at once; the child that ends last hands its slot straight back, so the tree in progress goes on ahead of the runs that have not started) or on the user (`waiting_on_user`: `input_required`, then `running`, in `request_user_input` and in the permission engine from before its one-prompt lock until after it: a run waiting for a slot while holding the lock would hold every other run's prompt), so nested fan-out never deadlocks; a cancel, queued or lending, leaves no waiter in the heap and no slot taken. A message steered to a working run (`RunControl.steer`, through `Delegations.control(run)`) is added after its last message, as the user's, before its next model call, and stays in its transcript (ADK: appended to its child session, the run's later events stamped after it so a durable store reads them back in order; Deep Agents: added to its state); a sub-agent run's task message is never trimmed, on ADK neither by the fit guard nor by the overflow handler's retry, whatever was steered after it. A dialog whose run is stopped is withdrawn, the turn going on (`MessageProcessor`). `AgentConfig.inherit_context` sets what a run sees: False (the default) its task alone, True its parent's conversation too, read once as the run starts (the conversation after any summary, less the message that called `task`), before the task message, which then ends with `INHERITED_CONTEXT_NOTE` (whose conversation it reads, which message is its task); `validate_agent_graph` refuses a value that is not True or False, `inherit_context=True` on the root and, in 0.7.0, on an agent with sub-agents or below another sub-agent. On ADK (`workflow/adk/task_tool.py::TaskTool`) every config-built agent is built on its own, with no ADK `sub_agents`, so ADK offers none `transfer_to_agent`, and gets ADK's identity line ("You are an agent. Your internal name is …"); a delegating agent has one `TaskTool`. Each sub-agent type runs on its own runner (`App(name=child_app(app_name))`, the type's agent its root, `_agent_plugin_chain`: the main chain configured for a sub-agent, no memory index, no summary, `RunControlPlugin` and `SubAgentOutcomePlugin`; every plugin's per-call state keyed by invocation) over the manager's session service, on a child session per run (`child_session_id`: `/`; an inheriting run's gets the conversation's events copied, `task_tool.inherited_events`), under an app no conversation list reads. On Deep Agents (`workflow/deepagents/task_tool.py::build_task_tool`) each type's graph is built on its own, and a run `astream`s it in its task with `var_child_runnable_config` cleared, so its chunks reach its own loop alone, never its parent's stream; an inheriting run's history is the parent's messages with Deep Agents' summary event applied (`SummarizationMiddleware._apply_event_to_messages`, private: `tests/workflow/deepagents/test_compact.py` pins it), and `ForeignReasoningMiddleware(kind, agent=...)` leaves out the reasoning of AI messages another agent wrote. A native ADK YAML app keeps transferring (chat-mode sub-agents); a task-mode agent in one is refused at validation, since ADK runs its delegation outside the tool pipeline and keeps the call open across turns. +- **Sub-agents delegate and return**: on both backends a sub-agent run is a call of its parent's `task` tool (the framework's: `tools/_core/delegation.py` declares it, `workflow/agents/delegate.py` runs it) that returns in the same turn; only the root replies to the user (a sub-agent's `TEXT` carries `metadata["subagent"]`, and the CLI shows it as the events box's status line, under its run's name: `researcher-2 › …`; `/agents` lists a conversation's runs), and the next turn starts at the root; fact extraction reads only the user's and the root's text. `task` takes `agent_type` (one of the caller's own sub-agents) and a brief (`workflow/agents/brief.py`: `title`, `objective`, `deliverable`, `constraints`, `known`, `done_when`), its schema and description the same on both backends (`task_parameters`, `task_description`: a line per type with its description, "The agent." with a warning, `subagent_without_description`, for one without, and the fields `AgentConfig.brief_required` asks for); `read_brief` checks a call against them, and one that cannot start a run is the call's `{"success": false, "error": …}`, no run started or numbered. `Delegations.delegate` (the manager's `_delegations`) does the rest, alike on both: it names the run (`AgentRuns.run_for`), reports its `AGENT_RUN` start (title, brief, `started_by`, `mode`) and end through the turn's live events and the records, and runs the backend's hook, `_run_agent(AgentRun)`, in a task of its own, where the run is the active run and no tool call is, so each run ends at its own end. The run's first message is the task message (`task_message`); it starts from the conversation's `plan` and `tasks` (`AgentRun.state`), and the keys it changed come back to its caller's state (`RunAnswer.state`). It ends as the `RunAnswer` says: its last text (a reply that also called a tool included; none at all, an empty result shown `No answer`), `refused` or `partial` by the outcome mark, `failed` for an error or a raise (one recoverable `ERROR`, ` failed: `, or the hook's own words, `RunFailed`: an overflow's; its result the text it wrote before it failed: a failed model call is the hook's `RunAnswer.error`, `failure_reason`, its warning's code `RunAnswer.error_code`, the error's type, and `RunFailed` carries `text=`); and the call's result is the run's envelope as JSON (`workflow/agents/envelope.py`), shown by `show_as_delegation`. A cancel of the caller's task stops the run's task first and ends the run `interrupted`. Each run works under its `RunControl` (`workflow/agents/control.py`, `AgentRun.control`), with its type's `AgentConfig.limits` over the policy's (`SubAgentPolicy.limits`, `DEFAULT_LIMITS`: 100 model calls): `Delegations.cancel(run_id, by=, error=)` cancels the run alone (its parent, the user or a limit), and the hook, seeing its own cancel (`own_cancel`), stops the run as a stopped turn's (ADK: its abort signal, its open calls sealed in its child session; Deep Agents: its stream closed) and returns what it has: the run ends `cancelled` with `cancelled_by` and that text, `partial`, while its siblings and the turn go on; the turn's own cancel still wins (`interrupted`). Past its `timeout` (counted from when its hook starts, `timing`) the run is cancelled by its limit (`time limit reached`); each model call is counted before it is made (`RunControlPlugin` in each sub-agent chain, `RunControlMiddleware` on each sub-agent's model side) and the last allowed one gets `STEP_LIMIT_NOTE` after its last message, its tools still declared (Claude refuses tool calls in a request that defines no tools); its answer's calls are dropped, never run, so the run completes `partial`, `step limit reached`; each call's tokens are counted after it, with what the run's other calls used (`RunControl(side_tokens=)`: its tools' side calls and its summaries, the ledger's rows of the run that are no agent step, `UsageLedger.by_purpose(run=)`), so the limit is the run's total as its usage record counts it, and past `max_tokens` an answer that makes tool calls is the run's last, its calls dropped, `cancelled` by its limit (`token limit reached`), while one that makes none ends the run as it would, `completed`, its result whole (a model that reports no usage counts none of its own). A turn starts at most `max_runs_per_turn` runs, at any depth (`sessions.runs_this_turn`): a call past it is the error result, no run started; `task`'s description says so (`limit_sentences`). At most `max_active` runs of a conversation work at once, at any depth (`workflow/agents/slots.py::SlotPool`, one per conversation, `Delegations.slots`; the root takes no slot): a run takes a slot right before its hook and its time limit start and gives it back at its end, however it ends; one that finds none waits `queued` (an `AGENT_RUN` and its record say so, then `running`), not counted against its `timeout`. A run lends its slot while it waits on its children (one lend for all it waits on at once; the child that ends last hands its slot straight back, so the tree in progress goes on ahead of the runs that have not started) or on the user (`waiting_on_user`: `input_required`, `queued` once answered while it waits for its slot back, then `running`, in `request_user_input` and in the permission engine from before its one-prompt lock until after it: a run waiting for a slot while holding the lock would hold every other run's prompt; a prompt no one can be shown, no input callback or its turn ended, lends nothing: `can_request_user_input`), so nested fan-out never deadlocks; a cancel, queued or lending, leaves no waiter in the heap and no slot taken. A message steered to a working run (`RunControl.steer`, through `Delegations.control(run)`) is added after its last message, as the user's, before its next model call, and stays in its transcript (ADK: appended to its child session, the run's later events stamped after it so a durable store reads them back in order; Deep Agents: added to its state); a sub-agent run's task message is never trimmed, on ADK neither by the fit guard nor by the overflow handler's retry, whatever was steered after it. A dialog whose run is stopped is withdrawn, the turn going on (`MessageProcessor`). `AgentConfig.inherit_context` sets what a run sees: False (the default) its task alone, True its parent's conversation too, read once as the run starts (the conversation after any summary; Deep Agents' less the message that called `task`, which ADK's copy keeps), before the task message, which then ends with `INHERITED_CONTEXT_NOTE` (whose conversation it reads, which message is its task); `validate_agent_graph` refuses a value that is not True or False, `inherit_context=True` on the root, on an agent with sub-agents and below another sub-agent. On ADK (`workflow/adk/task_tool.py::TaskTool`) every config-built agent is built on its own, with no ADK `sub_agents`, so ADK offers none `transfer_to_agent`, and gets ADK's identity line ("You are an agent. Your internal name is …"); a delegating agent has one `TaskTool`. Each sub-agent type runs on its own runner (`App(name=child_app(app_name))`, the type's agent its root, `_agent_plugin_chain`: the main chain configured for a sub-agent, no memory index, no summary, `RunControlPlugin` and `SubAgentOutcomePlugin`; every plugin's per-call state keyed by invocation) over the manager's session service, on a child session per run (`child_session_id`: `/`; an inheriting run's gets the conversation's events copied, `task_tool.inherited_events`), under an app no conversation list reads. On Deep Agents (`workflow/deepagents/task_tool.py::build_task_tool`) each type's graph is built on its own, and a run `astream`s it in its task with `var_child_runnable_config` cleared, so its chunks reach its own loop alone, never its parent's stream; an inheriting run's history is the parent's messages with Deep Agents' summary event applied (`SummarizationMiddleware._apply_event_to_messages`, private: `tests/workflow/deepagents/test_compact.py` pins it), and `ForeignReasoningMiddleware(kind, agent=...)` leaves out the reasoning of AI messages another agent wrote. A native ADK YAML app keeps transferring (chat-mode sub-agents); a task-mode agent in one is refused at validation, since ADK runs its delegation outside the tool pipeline and keeps the call open across turns. - **Token usage**: every model call the framework makes is one `LLM_USAGE`, on both backends, side calls included (`generate_simple`: `summarize`'s, `purpose` `tool`; `on_session_end`'s, `memory_extraction`, outside any turn; an app's own, `side_call`, or what its caller names with `workflow/usage.py::side_call`), its counts normalized where it is made (`normalized_tokens`: `prompt_tokens` every input token, cache reads and writes included; `completion_tokens` every output token, thinking included; ADK's read by its model's provider kind, `adk_usage_event`/`adk_tokens`, since Gemini and ADK's Claude adapter keep the thinking apart from the candidates and OpenAI's count it inside, an agent of no known kind read as apart; Deep Agents' by LangChain's one convention, `langchain_tokens`; the raw log's usage records alike), and timed (`latency_ms`: on ADK from the request to the answer, `workflow/adk/call_clock.py`'s plugins marking the answer's `custom_metadata`; on Deep Agents by the turn's `RunCallback`, which marks the answer's `response_metadata["agentic_cli"]`, beside the outcome mark; a side call, a summary and the overflow retry around their own request; no adapter sends either mark). Each is recorded in its conversation's ledger (`UsageLedger`; `BaseWorkflowManager.usage`/`usage_of`, in memory for the manager's life: a backend switch's new manager starts afresh, as with `agent_runs`) where it is made, before `on_event` (the event processors, ADK's summarizer, as soon as its call answers, Deep Agents' `RunCallback`, `_report_side_call`), under the run it is made in and its conversation's turn while one runs (as the manager counts them, `/compact` and job notices included: not `SessionInfo.turns`; none in another conversation's turn or from a task its turn outlived, which `_report_side_call` reports to no one); a sub-agent run's `AGENT_RUN` end carries what it used, by model (`metadata["usage"]`, `RunRecord.usage`). The CLI's status bar sums the events it sees (the open conversation's total, on any backend); `/status` shows the ledger by agent. LangGraph (deprecated) records no ledger. - **Tool registration**: Use `@register_tool(category=..., capabilities=..., description=...)` decorator. `capabilities=` is required — pass `EXEMPT` for tools that need no permission check or a list of `Capability(name, target_arg=...)` tuples the engine matches against rules. Tools are auto-discovered via the global `ToolRegistry`. A tool in `AgentConfig.tools` that the registry did not issue is denied at every call; building the agents names it once (`tool_not_registered`, per agent and tool: `BaseWorkflowManager._name_unregistered`): a plain callable, a `FunctionTool`/`StructuredTool` judged by the function it runs (as the gates unwrap it), an app's own tool class; ADK's own tool objects excepted (a built-in runs inside the model). `outside_content=True` (or a function of the call's arguments) declares that a call brings content from outside the user and the project into the conversation (a page, a document, a program's output): once the gate allows one, a memory write in that conversation is approved per call (see Permissions); an application's tools are unmarked unless they declare it, and a variant must declare the same flag as its tool. - **Async tools never block the event loop**: a synchronous tool runs on a worker thread on both backends; an async tool runs on the event loop itself, where a blocking call (DNS, a connect, a file lock's wait, a sleep, a subprocess wait, PDF parsing, page conversion, embedding) freezes the whole app, Ctrl+C included. An async tool runs its slow work with `asyncio.to_thread`. `tests/tools/test_async_tools_never_block.py` lists every async tool (the registry's, the factories' service-bound variants, Deep Agents' skill tools), so a new one fails until it is listed, and calls each through the loop guard (`tests/loop_guard.py`). diff --git a/README.md b/README.md index bedbc813..f265367c 100644 --- a/README.md +++ b/README.md @@ -385,8 +385,9 @@ What it supports: coordinator writes and the coordinator's plan and tasks; with `inherit_context=True` it also starts from the coordinator's conversation. Its run's envelope is the call's result, and the - coordinator answers the user. Two sub-agents can run at once. `task` is a - reserved tool name. + coordinator answers the user. Several sub-agent runs can work at once, + four by default (`SubAgentPolicy.max_active`, at any depth); a run past + them waits for a free slot. `task` is a reserved tool name. - **The permission gate on every call**: `PermissionMiddleware`, in every agent's stack, identifies each tool by the object the registry issued and asks through the input callback, for sub-agents' calls too. A tool that @@ -1355,17 +1356,23 @@ reviewer = AgentConfig(name="reviewer", prompt="Check what was said.", `--agents`, id `/`), which `/sessions` never lists and which is deleted with its conversation; an inheriting run's child session starts with the conversation's events. + Only the plan, the tasks and the outside-content mark pass between a run + and its caller: any other session-state key an app's ADK tool writes in a + sub-agent run stays in the run's child session, and a `user:` or `app:` + scoped one is kept under the child app, so the conversation never sees + it; nor does the run read the conversation's other keys. **On Deep Agents**, each sub-agent's graph runs apart from its parent's, in a task of its own; an inheriting run starts from the conversation's messages, which its own summarization compacts when they are too large for its model. -- **The limits in 0.7.0.** `inherit_context` is for sub-agents only, and +- **What the agent graph refuses.** `inherit_context` is for sub-agents only, and only for the main agent's own sub-agents that have none of their own. A coordinator cannot have a tool of its own named `task`. Each raises `AgentGraphError` at startup. - **A sub-agent's failure.** A sub-agent whose model call fails does not end the turn, on either backend: its run fails, its parent reads the - provider's reason in the envelope, the user sees a warning, + provider's reason in the envelope, with the text the run wrote before it + failed as its result, the user sees a warning, ` failed: ` (`researcher-1 failed: …`), and the parent answers. Only the main agent's own failure ends the turn. A sub-agent's request too long for its model fails its run alike, with the @@ -1377,16 +1384,25 @@ reviewer = AgentConfig(name="reviewer", prompt="Check what was said.", `max_tokens` too), the runs one turn may start (`max_runs_per_turn`, 20, at any depth) and the runs that work at once (`max_active`, 4, at any depth: a run past them waits for a free slot, and one waiting on its - children or the user lends its slot meanwhile); an agent's own + children or the user lends its slot meanwhile; once the user has answered, + it waits `queued` to take its slot back if another run works in it; a + tool that puts a timeout around a + question, `asyncio.wait_for` or `asyncio.timeout` around + `request_user_input`, and goes on when it fires gives its run's slot up + for the rest of the run, which works on without one and says + `input_required` until its next question is answered, then `running`, + still without a slot, or until it ends); an agent's own `limits=AgentLimits(...)` lies over the policy's, field by field. A run's last allowed model call is told to answer with what it has, and the run completes `partial` (`step limit reached`); past its time, or past its tokens with an answer that asks for tools, it is `cancelled` (`time limit reached`, `token limit reached`) with the text it wrote so far, a prompt it waited at withdrawn (an answer past its tokens that asks for none is - its result, and the run completes; a model that reports no usage is not - limited by tokens); a `task` call past the runs a turn may start starts - no run, and the parent reads why. + its result, and the run completes; its tokens are its total as its usage + record counts it, its tools' side calls and its summaries included, + checked after each of its model calls, and a model that reports no + usage counts none of its own); a `task` call past the runs a turn may + start starts no run, and the parent reads why. - **A sub-agent's job.** A long-running tool on a sub-agent (a job starter) returns the job's id at once, and the sub-agent answers its parent in the same turn. When the job finishes, the main agent is told, in a message of diff --git a/src/agentic_cli/workflow/adk/manager.py b/src/agentic_cli/workflow/adk/manager.py index d4c82cfa..dc25caaa 100644 --- a/src/agentic_cli/workflow/adk/manager.py +++ b/src/agentic_cli/workflow/adk/manager.py @@ -77,7 +77,7 @@ ) from agentic_cli.workflow.adk.task_tool import SHARED_KEYS, TaskTool from agentic_cli.workflow.adk.tool_result_cap_plugin import ToolResultCapPlugin -from agentic_cli.workflow.agents.delegate import AgentRun, RunAnswer, RunFailed +from agentic_cli.workflow.agents.delegate import AgentRun, RunAnswer, RunFailed, failure_reason from agentic_cli.workflow.context import OVERFLOW_ERROR_CODE from agentic_cli.tools._core.delegation import TASK_TOOL from agentic_cli.workflow.outside_content import ( @@ -1328,8 +1328,8 @@ async def process( async with self._turn(session_id, user_id) as ref: logger.info("processing_message", message_length=len(message)) session = await self._get_or_create_session(ref.user_id, ref.session_id) - # A crash, an old cancel, or a stop whose answers could not be - # written may have left calls without a result. + # A crash, an old cancel, a failed turn, or a stop whose answers + # could not be written may have left calls without a result. session = await self._answer_left_open(session) state_delta = { **turn_state(session, message), @@ -1503,21 +1503,24 @@ async def _run_agent(self, run: AgentRun) -> RunAnswer: A cancel of the run alone (its control's: a limit, its parent or the user) stops it so too, and it returns what it has: the last text it wrote and the shared keys it changed; ``Delegations`` ends it - cancelled. + cancelled. Once its stream has ended its work is done + (``RunControl.finish``): a cancel of the run alone while its state + is read back does nothing. Returns: Its last answer with text, that answer's outcome mark, the shared keys it changed (read back from its child session's state); or, - for a reply that is no answer, the error it is. + for a reply that is no answer, the error it is and its code; or, + for a model call that failed, the provider's reason (out of + ADK's plugin wrapper, ``_plugin_cause``) and its error's type, + each with the last text it wrote. Raises: RunFailed: Its request no longer fits its model's window - (the overflow handler's answer). + (the overflow handler's answer), with the last text it wrote. ValueError: Its child session's id is longer than ADK stores. AlreadyExistsError: The store keeps its instance already (a stored transcript is never replaced). - Exception: Its model call failed: the provider's error, out of - ADK's plugin wrapper (``_plugin_cause``). """ conversation = run.conversation if conversation is None: @@ -1556,18 +1559,25 @@ async def _run_agent(self, run: AgentRun) -> RunAnswer: # turn's) goes on. if not run.control.own_cancel(): raise - except RuntimeError as error: - cause = _plugin_cause(error) - if cause is error: - raise - raise cause from None + except Exception as error: # noqa: BLE001 - the run fails; its parent reads why + # A model call failed: the provider's error, out of ADK's plugin + # wrapper. The run fails with the text it wrote before it. + failure = _plugin_cause(error) if isinstance(error, RuntimeError) else error + logger.debug("subagent_failed", run=run.ref.run, exc_info=failure) + return RunAnswer( + text=processor.answer, error=failure_reason(failure), + error_code=type(failure).__name__, + ) finally: self._report_raw_log() + # Its work has ended: a limit or a stop landing during the read of + # its state below must not discard the answer it made. + run.control.finish() if processor.failure is not None and run.control.cancelled is None: error, code = processor.failure if code == OVERFLOW_ERROR_CODE: - raise RunFailed(error, code=code) - return RunAnswer(text=processor.answer, error=error) + raise RunFailed(error, code=code, text=processor.answer) + return RunAnswer(text=processor.answer, error=error, error_code=code) ended = await self._session_service.get_session( app_name=app, user_id=conversation.user_id, session_id=session_id, config=GetSessionConfig(num_recent_events=0), diff --git a/src/agentic_cli/workflow/adk/run_control_plugin.py b/src/agentic_cli/workflow/adk/run_control_plugin.py index 1112da29..efb96d72 100644 --- a/src/agentic_cli/workflow/adk/run_control_plugin.py +++ b/src/agentic_cli/workflow/adk/run_control_plugin.py @@ -22,10 +22,11 @@ request whose messages hold tool calls or results when it defines no tools, and no call that answer makes is run (below); - after each, what it used (``workflow/usage.py::adk_tokens``, by its - model's provider kind) goes to ``RunControl.used``, with whether the - answer makes function calls: one past the token limit that makes none - is the run's result, whole. A model that reports no usage is not limited - by tokens; + model's provider kind) goes to ``RunControl.used``, which checks the + run's total (with what its side calls used), with whether the answer + makes function calls: one past the token limit that makes none is the + run's result, whole. A call that reports no usage counts none of its + own; - on the run's last call (``RunControl.final_call``: its step limit's, or one past its token limit that makes calls) the answer's function calls are dropped, so ADK @@ -52,7 +53,7 @@ from google.genai import types from agentic_cli.workflow.agents.control import STEP_LIMIT_NOTE -from agentic_cli.workflow.usage import adk_tokens +from agentic_cli.workflow.usage import UsageTotals, adk_tokens if TYPE_CHECKING: from google.adk.agents.callback_context import CallbackContext @@ -109,9 +110,11 @@ async def after_model_callback( control = self._control() if control is None: return None - if llm_response.usage_metadata is not None: - tokens = adk_tokens(llm_response.usage_metadata, self._kind) - control.used(tokens.input, tokens.output, calls=_calls(llm_response)) + usage = llm_response.usage_metadata + # A call that reports no usage counts none of its own; the run's + # side calls still count. + tokens = adk_tokens(usage, self._kind) if usage is not None else UsageTotals() + control.used(tokens.input, tokens.output, calls=_calls(llm_response)) if control.final_call: drop_calls(llm_response) return None diff --git a/src/agentic_cli/workflow/agents/brief.py b/src/agentic_cli/workflow/agents/brief.py index e76b4480..544c93d3 100644 --- a/src/agentic_cli/workflow/agents/brief.py +++ b/src/agentic_cli/workflow/agents/brief.py @@ -72,16 +72,17 @@ #: is, and which message is its task (Deep Agents' ``_FORK_TASK_PREAMBLE``, #: told the way ADK shows that conversation). ``task_message`` ends an #: inheriting type's task message with it, on both backends: the run reads -#: its parent's conversation before that message. +#: its parent's conversation before that message. ADK's copy of it keeps the +#: call that handed the run its task and Deep Agents' leaves it out, so the +#: note says nothing of that call. INHERITED_CONTEXT_NOTE = ( "You are a sub-agent: another agent has handed you a task. The conversation " "before the task is that agent's, shown so you know what has been established: " "the user's messages in it were addressed to that agent, not to you, and what " - "that agent did is quoted, its call handing you this task included. Do not " - "carry out those messages yourself or answer as that agent. Your task is the " - "request that follows the conversation: complete it directly, and use the " - "specific facts, figures and identifiers already established in the " - "conversation rather than answering generically." + "that agent did is quoted. Do not carry out those messages yourself or answer " + "as that agent. Your task is the request that follows the conversation: " + "complete it directly, and use the specific facts, figures and identifiers " + "already established in the conversation rather than answering generically." ) diff --git a/src/agentic_cli/workflow/agents/control.py b/src/agentic_cli/workflow/agents/control.py index e6f1bb0e..f7494ecb 100644 --- a/src/agentic_cli/workflow/agents/control.py +++ b/src/agentic_cli/workflow/agents/control.py @@ -7,22 +7,26 @@ - ``cancel(by=, error=)`` cancels the run's task: its parent's stop, the user's, or a limit's. The first cancel wins, and a run that has ended is - not cancelled. The hook, handling the ``CancelledError`` in the run's - task, asks ``own_cancel`` whether it is the run's own: then it stops the - run as a stopped turn's run stops and returns what it has, and the run - ends ``cancelled``; any other cancel (the turn's: Ctrl+C) goes on. + not cancelled, nor one whose hook said its work has ended (``finish``) + while it still reads back what the run did. The hook, handling the + ``CancelledError`` in the run's task, asks ``own_cancel`` whether it is + the run's own: then it stops the run as a stopped turn's run stops and + returns what it has, and the run ends ``cancelled``; any other cancel + (the turn's: Ctrl+C) goes on. - The time limit (``timeout``) runs while the hook does (``timing``); past it the run is cancelled by its limit. - The limits checked at the run's model calls: before each, ``model_call`` counts it and says whether it is the last allowed (``max_model_calls``), whose request ends with ``STEP_LIMIT_NOTE``; after each, ``used`` counts - its tokens, and an answer past ``max_tokens`` that asks for tools (the - run would go on) has the run cancelled by its limit at that answer; one - that asks for none ends the run as it would, its result. On the call that - is the run's last (``final_call``) the backend drops the answer's tool - calls, so the run ends with that answer: no call past a limit is made, - and nothing the model asked for runs after it. A model that reports no - usage is not limited by tokens. + its tokens, and the run's total (its own calls' tokens and what its other + calls used, ``side_tokens``: its tools' side calls, its summaries, as its + usage record counts them) is checked: an answer past ``max_tokens`` that + asks for tools (the run would go on) has the run cancelled by its limit + at that answer; one that asks for none ends the run as it would, its + result. On the call that is the run's last (``final_call``) the backend + drops the answer's tool calls, so the run ends with that answer: no call + past a limit is made, and nothing the model asked for runs after it. A + model that reports no usage counts none of its own. - ``steer(message)`` gives the run a message, which its next model call (``take_steering``) adds after its last message, as a user's. @@ -32,7 +36,7 @@ from __future__ import annotations import asyncio -from collections.abc import Iterator +from collections.abc import Callable, Iterator from contextlib import contextmanager from typing import TYPE_CHECKING, Any @@ -61,6 +65,10 @@ class RunControl: Args: ref: The run. limits: Its limits: its type's over the policy's. + side_tokens: What the run's other model calls have used so far (its + tools' side calls, its summaries; not its own steps, which + ``used`` counts), input plus output tokens, as its usage record + counts them: counted with its own at each check. None: none. Attributes: ref: The run. @@ -69,9 +77,16 @@ class RunControl: (``parent``, ``user`` or ``limit``) and why, one line. """ - def __init__(self, ref: RunRef, limits: AgentLimits) -> None: + def __init__( + self, + ref: RunRef, + limits: AgentLimits, + *, + side_tokens: Callable[[], int] | None = None, + ) -> None: self.ref = ref self.limits = limits + self._side_tokens = side_tokens self.cancelled: tuple[str, str] | None = None self._steering: list[str] = [] self._calls = 0 @@ -81,6 +96,8 @@ def __init__(self, ref: RunRef, limits: AgentLimits) -> None: # Whether cancel() cancelled the task, and own_cancel() has not yet # taken that cancel. self._cancelled_task = False + # Whether the hook said the run's work has ended (finish()). + self._finished = False # -- the run's task -------------------------------------------------------- @@ -96,21 +113,37 @@ def bind(self, task: asyncio.Task[Any]) -> None: def cancel(self, *, by: str, error: str) -> None: """Cancel the run's task: ``by`` its parent, the user or a limit, for ``error``. - Does nothing once the run is cancelled (the first cancel wins) or - its task has ended, and cancels no task its turn is cancelling - already (the run ends as the turn's). + Does nothing once the run is cancelled (the first cancel wins), its + task has ended or its work has (``finish``), and cancels no task its + turn is cancelling already (the run ends as the turn's). Raises: ValueError: ``by`` is not ``parent``, ``user`` or ``limit``. """ if by not in CANCELLED_BY: raise ValueError(f"A run is cancelled by its parent, user or limit, not {by!r}.") - if self.cancelled is not None or (self._task is not None and self._task.done()): + if ( + self.cancelled is not None + or self._finished + or (self._task is not None and self._task.done()) + ): return self.cancelled = (by, error) if self._task is not None: self._cancel_task() + def finish(self) -> None: + """In the run's task: its work has ended, so no cancel stops it from now on. + + A hook calls it as the run's stream ends, before it reads back what + the run did (ADK reads its child session's state): a limit or a stop + that lands during that read would otherwise end the run + ``cancelled`` and lose an answer it has made. A cancel the run's + work already took (``own_cancel``) stays. The turn's cancel (Ctrl+C) + is not the control's, and still stops the read. + """ + self._finished = True + def own_cancel(self) -> bool: """In the run's task, handling a ``CancelledError``: whether it is the run's own cancel. @@ -173,16 +206,21 @@ def model_call(self) -> bool: def used(self, input_tokens: int, output_tokens: int, *, calls: bool = True) -> None: """Count what one of the run's model calls used, as ``workflow/usage.py`` counts it. - Past ``max_tokens``, an answer that makes tool calls (``calls``: the - run would go on past it) is the run's last, cancelled by its limit: - ``cancelled`` is set and the call is the run's last - (``final_call``), so it ends with that answer rather than losing it. - An answer that makes none ends the run anyway: it is its result, - whole, and nothing is cancelled. Its tokens are counted either way. + The run's total is its own calls' tokens and what its other calls + used (``side_tokens``). Past ``max_tokens``, an answer that makes + tool calls (``calls``: the run would go on past it) is the run's + last, cancelled by its limit: ``cancelled`` is set and the call is + the run's last (``final_call``), so it ends with that answer rather + than losing it. An answer that makes none ends the run anyway: it is + its result, whole, and nothing is cancelled. Its tokens are counted + either way. """ self._tokens += input_tokens + output_tokens limit = self.limits.max_tokens - if limit is None or self._tokens <= limit or self.cancelled is not None or not calls: + if limit is None or self.cancelled is not None or not calls: + return + side = self._side_tokens() if self._side_tokens is not None else 0 + if self._tokens + side <= limit: return self.cancelled = (LIMIT, TOKEN_LIMIT_ERROR) self._final = True diff --git a/src/agentic_cli/workflow/agents/delegate.py b/src/agentic_cli/workflow/agents/delegate.py index e5a38641..9f9bb050 100644 --- a/src/agentic_cli/workflow/agents/delegate.py +++ b/src/agentic_cli/workflow/agents/delegate.py @@ -45,9 +45,10 @@ A run that waits on the user (``waiting_on_user``: a question, a permission prompt, ``BaseWorkflowManager.request_user_input`` and the permission -engine) says ``input_required``, lends its slot for the wait, and says -``running`` once it has its slot back; a prompt no one can be shown (no -input callback) lends nothing. +engine) says ``input_required``, lends its slot for the wait, says +``queued`` once answered while it waits for its slot back (another run +works in it), and ``running`` once it has it; a prompt no one can be shown +(no input callback, or its turn ended) lends nothing. Each ``AGENT_RUN`` is recorded (``AgentRuns.observe``) as it is made and reported to the turn's live events, so it reaches the turn's stream while @@ -55,9 +56,10 @@ - ``failed`` when the hook raised (not a cancel) or answered an error: the parent's envelope carries the reason (the provider's, for a failed model - call), and the user is warned once, a recoverable ``ERROR``: - `` failed: ``, or the hook's own words (``RunFailed``: a - context overflow, ``context.subagent_overflow_message``); + call) and the text the run wrote before it failed, and the user is warned + once, a recoverable ``ERROR``: `` failed: ``, or the + hook's own words (``RunFailed``: a context overflow, + ``context.subagent_overflow_message``); - ``refused`` when a model refused its last answer (``agents/outcome.py``); - ``completed`` otherwise, ``partial`` for an answer cut at its output limit, followed by the cut's one warning (``outcome.cut_off_warning``), @@ -209,17 +211,23 @@ class RunAnswer: """What the backend hook returns for a run it ran to its end. Attributes: - text: Its last non-empty answer (``""`` for none). + text: Its last non-empty answer (``""`` for none), one it wrote + before it failed too: a failed run's envelope carries it. outcome: How that answer ended (``agents/outcome.py``: ``REFUSED``, ``CUT``), None when it ended as an answer should. - error: Why it failed, when it did; None when it answered. + error: Why it failed, when it did (the provider's reason for a + failed model call, ``failure_reason``); None when it answered. state: The shared state keys it changed, with their new values. + error_code: The failure's code, the user's warning's ``error_code``: + the provider error's type for a failed model call, the reply's + code for one that is no answer; None for none. """ text: str = "" outcome: str | None = None error: str | None = None state: Mapping[str, Any] = field(default_factory=dict) + error_code: str | None = None @dataclass(frozen=True) @@ -246,7 +254,8 @@ class Delegated: @dataclass class _Working: """A run at work, as its own task sees it: its slot in its conversation's - pool, the child runs it waits on (by run id), and its waits on the user.""" + pool, the child runs it waits on (by run id), its waits on the user, and + the working status it said last (``running`` from its start).""" ref: RunRef call_id: str @@ -255,20 +264,32 @@ class _Working: emit: Callable[[WorkflowEvent], None] children: set[str] = field(default_factory=set) asking: int = 0 + said: str = RUN_RUNNING def waits_on_only(self, child: str) -> bool: """Whether ``child`` is all the run waits on: its last child, the user not asked.""" return self.asking == 0 and self.children <= {child} + def say(self, status: str) -> None: + """Report ``status``, a working one, unless the run said it last.""" + if status != self.said: + self.said = status + self.emit(WorkflowEvent.agent_run(self.ref, status, call_id=self.call_id)) + @asynccontextmanager async def waiting_on_user(self) -> AsyncIterator[None]: - """``input_required``, its slot lent for the block, then ``running``; nested waits once.""" + """``input_required``, its slot lent for the block, ``queued`` while a take-back + waits for a slot, then ``running``; nested waits once. + + A wait that starts while an earlier one waits for the slot back + (two calls of one response that each ask) says ``input_required`` + again: the run waits on the user. + """ self.asking += 1 - if self.asking == 1: - self.emit(WorkflowEvent.agent_run(self.ref, RUN_INPUT_REQUIRED, call_id=self.call_id)) + self.say(RUN_INPUT_REQUIRED) stopped = False try: - async with self.pool.lent(self.slot): + async with self.pool.lent(self.slot, on_wait=lambda: self.say(RUN_QUEUED)): yield except asyncio.CancelledError: stopped = True @@ -276,7 +297,7 @@ async def waiting_on_user(self) -> AsyncIterator[None]: finally: self.asking -= 1 if self.asking == 0 and not stopped: - self.emit(WorkflowEvent.agent_run(self.ref, RUN_RUNNING, call_id=self.call_id)) + self.say(RUN_RUNNING) #: The run at work in this task (``_in_run`` sets it in the run's own task, @@ -290,11 +311,11 @@ async def waiting_on_user() -> AsyncIterator[None]: In a sub-agent run's own work, the run says ``input_required``, its slot works for another run meanwhile, and once the block ends it takes the - slot back, ahead of the runs that have not started, and says - ``running``; nested waits (a prompt waiting its turn behind another's, - then the prompt) count once. A wait a cancel ends takes nothing back: - the run is being stopped. Nothing in the root's own work, nor outside a - run. + slot back, ahead of the runs that have not started, saying ``queued`` + while it waits for it (another run holds it), and says ``running``; + nested waits (a prompt waiting its turn behind another's, then the + prompt) count once. A wait a cancel ends takes nothing back: the run is + being stopped. Nothing in the root's own work, nor outside a run. Only a wait that can block belongs in it: a lent slot goes to the first run queued for one, which may work its whole run in it before this run @@ -314,15 +335,26 @@ class RunFailed(Exception): A hook raises it for a failure it has words for (a sub-agent's context overflow, ``context.subagent_overflow_message``): its text is the - envelope's ``error`` and the user's warning, as given, and ``code`` that - warning's error code. Any other exception a hook lets out fails the run - with its text (its type's name, for none), warned of as `` - failed: `` with the type's name as its code. + envelope's ``error`` and the user's warning, as given, ``code`` that + warning's error code, and ``text`` the last text the run wrote before + it failed (``""`` for none), the envelope's ``result``. A failure in + the provider's words (a failed model call) a hook answers instead + (``RunAnswer.error``, ``failure_reason``, with the run's last text and + the provider error's type as ``RunAnswer.error_code``). + Any other exception a hook lets out fails the run with its text (its + type's name, for none), warned of as `` failed: `` + with the type's name as its code, and no result. """ - def __init__(self, error: str, *, code: str) -> None: + def __init__(self, error: str, *, code: str, text: str = "") -> None: super().__init__(error) self.code = code + self.text = text + + +def failure_reason(error: BaseException) -> str: + """A failure's reason, as a failed run's envelope gives it: its text, else its type's name.""" + return str(error) or type(error).__name__ class Delegations: @@ -335,7 +367,9 @@ class Delegations: sub-agents (``AgentConfig.sub_agents``). hook: Runs one run (``BaseWorkflowManager._run_agent``). ledgers: The manager's usage ledgers: a run's end carries what it - used, by model. None: an end carries no usage. + used, by model, and its token limit counts its side calls + (``RunControl``'s ``side_tokens``). None: an end carries no + usage, and a run's own calls alone count toward its limit. stored: How many instances of each type a conversation's store already keeps (``BaseWorkflowManager._stored_instances``), asked once per conversation per turn, before the turn's first run is @@ -414,7 +448,9 @@ async def delegate(self, request: DelegationRequest) -> Delegated: ref, RUN_STARTED, call_id=request.call_id, title=run_title(brief.title), brief=brief.fields(), started_by=started_by(request.caller), mode=BLOCKING, )) - control = RunControl(ref, self._limits(config)) + control = RunControl( + ref, self._limits(config), side_tokens=self._side_tokens(conversation, ref) + ) inner = asyncio.create_task( self._in_run(ref, config, brief, conversation, request, control), name=f"agent run {ref.run}", @@ -453,8 +489,9 @@ def cancel(self, run_id: str, *, by: str, error: str) -> bool: envelope (``cancelled``, with what it had of its work). Returns: - True when this cancelled it; False for no such working run, or - one cancelled already. + True when this cancelled it; False for no such working run, one + cancelled already, or one whose work has ended + (``RunControl.finish``). Raises: ValueError: ``by`` is not ``parent``, ``user`` or ``limit``. @@ -493,9 +530,11 @@ async def _ended( result=envelope(ref, RUN_INTERRUPTED, error=INTERRUPTED_ERROR), state={}, run=ref ) except RunFailed as error: - return self._failed(ref, call_id, str(error), warning=str(error), code=error.code) + return self._failed( + ref, call_id, str(error), warning=str(error), code=error.code, text=error.text + ) except Exception as error: # noqa: BLE001 - a sub-agent's failure is its parent's to read - reason = str(error) or type(error).__name__ + reason = failure_reason(error) logger.debug("subagent_failed", run=ref.run, exc_info=error) return self._failed( ref, call_id, reason, @@ -511,7 +550,7 @@ async def _ended( if answer.error is not None: return self._failed( ref, call_id, answer.error, warning=f"{ref.instance} failed: {answer.error}", - code=None, text=answer.text, state=answer.state, + code=answer.error_code, text=answer.text, state=answer.state, ) if answer.outcome == REFUSED: self._end(ref, call_id, RUN_REFUSED, text=answer.text, error=REFUSAL_ERROR) @@ -688,6 +727,22 @@ def _end( self._emit(end) return end + def _side_tokens( + self, conversation: SessionRef | None, ref: RunRef + ) -> Callable[[], int] | None: + """What ``ref``'s run's side calls have used so far, as its conversation's ledger + counts them: its tools' side calls and its summaries (``RunControl``'s + ``side_tokens``; its own steps it counts itself). None without ledgers.""" + if self._ledgers is None: + return None + ledger = self._ledgers.ledger(conversation) + + def spent() -> int: + side = ledger.by_purpose(run=ref.run or "") + return sum(totals.input + totals.output for totals in side.values()) + + return spent + def _usage(self, ref: RunRef) -> dict[str, dict[str, int]] | None: """What ``ref``'s run used, by model, from its conversation's ledger.""" if self._ledgers is None: diff --git a/src/agentic_cli/workflow/agents/runs.py b/src/agentic_cli/workflow/agents/runs.py index 2b6cfc1c..80bbb6b4 100644 --- a/src/agentic_cli/workflow/agents/runs.py +++ b/src/agentic_cli/workflow/agents/runs.py @@ -36,7 +36,8 @@ #: A working run's status: waiting for a free working slot, working, or #: waiting on the user (a question, a permission prompt). A record says #: ``running`` from its start; its events say ``queued`` when it must wait -#: for a slot, and ``running`` once it has one, and after the user answered. +#: for a slot (to start, or, once the user has answered, to take its own +#: back while another run works in it), and ``running`` once it has one. RUN_QUEUED = "queued" RUN_RUNNING = "running" RUN_INPUT_REQUIRED = "input_required" diff --git a/src/agentic_cli/workflow/agents/slots.py b/src/agentic_cli/workflow/agents/slots.py index 5a2f0f17..40807613 100644 --- a/src/agentic_cli/workflow/agents/slots.py +++ b/src/agentic_cli/workflow/agents/slots.py @@ -10,7 +10,8 @@ A run that waits on its child runs or on the user lends its slot meanwhile (``async with pool.lent(slot):``): another run works with it, and the run -takes one back at ``RETURNING`` when the wait is over. A child that ends +takes one back at ``RETURNING`` when the wait is over (``on_wait`` is +called when that take-back has to wait for a slot). A child that ends while its parent waits on it alone hands its slot straight to the parent (``hand_back``: whether the parent waits on anything else is its caller's to know), ahead of every waiter. Everything holding a slot is working, so @@ -31,7 +32,7 @@ import asyncio import heapq import itertools -from collections.abc import AsyncIterator +from collections.abc import AsyncIterator, Callable from contextlib import asynccontextmanager #: A run taking its slot back, after waiting on its children or the user. @@ -63,8 +64,11 @@ def __init__(self, pool: SlotPool) -> None: # The lends in progress (``SlotPool.lent``, nested): the slot is lent # on the first and taken back after the last. self._lends = 0 - # Its run's take-back waiting in the heap for a slot, while there - # is one (``SlotPool._take_back``). + # Its run's take-back waiting for a slot (``SlotPool._take_back``), + # from when it joins the heap until its wait ends: for a moment it + # may name one ``_give`` has handed a slot already (out of the heap, + # its task not yet resumed), whose take-back then keeps that slot or + # hands it on. self._back: _Waiter | None = None @property @@ -157,18 +161,29 @@ def hand_back(self, slot: Slot, to: Slot) -> None: self.release(slot) @asynccontextmanager - async def lent(self, slot: Slot) -> AsyncIterator[None]: + async def lent( + self, slot: Slot, *, on_wait: Callable[[], None] | None = None + ) -> AsyncIterator[None]: """Lend ``slot`` for the block, while its run waits on its children or the user. A lend of a held slot frees it for another run (of nested lends, the first); when the last ends, it is taken back at ``RETURNING`` (at once when a slot is free, else ahead of the runs that have not - started), unless a child handed it back already. A lend that starts - while another of the run's waits is taking the slot back keeps it - lent: that wait ends without it, and this one takes it back. A lend - that ends in a cancel takes nothing back: its run is being stopped, - and its ``release`` is then nothing. An error is no cancel: the run - goes on, with its slot back. + started), unless a child handed it back already. ``on_wait``, when + given, is called as that take-back starts to wait for a slot (none + is free): the run's wait is over, and it now waits for its slot. A + lend that starts while another of the run's waits is taking the slot + back keeps it lent: that wait ends without it, and this one takes it + back. A lend that ends in a cancel takes nothing back: its run is + being stopped, and its ``release`` is then nothing. So a cancel that + does not stop the run gives the slot up for the rest of it: an app's + tool that puts ``asyncio.wait_for`` or ``asyncio.timeout`` around a + question (``request_user_input``) and goes on when the timeout fires + leaves its run working without a slot (another run may have it, so + more than ``size`` work at once), and the run says + ``input_required`` until its next question is answered, when it says + ``running`` again, still without a slot, or until it ends. An error + is no cancel: the run goes on, with its slot back. Raises: ValueError: ``slot`` is another pool's. @@ -193,13 +208,13 @@ async def lent(self, slot: Slot) -> AsyncIterator[None]: except BaseException: slot._lends -= 1 if slot._lends == 0: - await self._take_back(slot) + await self._take_back(slot, on_wait) raise slot._lends -= 1 if slot._lends == 0: - await self._take_back(slot) + await self._take_back(slot, on_wait) - async def _take_back(self, slot: Slot) -> None: + async def _take_back(self, slot: Slot, on_wait: Callable[[], None] | None = None) -> None: """A lent ``slot`` held again, at ``RETURNING``; nothing for one handed back or released. A take-back in the heap the slot no longer needs (a child handed it @@ -210,11 +225,12 @@ async def _take_back(self, slot: Slot) -> None: slot, and a take-back queued meanwhile (a wait of the run that started and ended in between) is withdrawn. So a run's slot has at most one take-back waiting for a slot, and none once it is held. + ``on_wait`` is called if it has to wait. """ if slot._state != _LENT: return try: - took = await self._take(RETURNING, slot) + took = await self._take(RETURNING, slot, on_wait) except asyncio.CancelledError: if slot._state == _LENT and slot._lends == 0: slot._state = _RELEASED @@ -229,15 +245,23 @@ async def _take_back(self, slot: Slot) -> None: # being handed the slot: the slot is back, so it ends without one. self._withdraw(slot) - async def _take(self, priority: int, slot: Slot | None = None) -> bool: + async def _take( + self, + priority: int, + slot: Slot | None = None, + on_wait: Callable[[], None] | None = None, + ) -> bool: """Count one slot taken: a free one, else wait in the heap until one is handed over. False when the wait is ``slot``'s take-back and was withdrawn - (``_withdraw``): no slot was taken. + (``_withdraw``): no slot was taken. ``on_wait`` is called when it + has to wait, before its entry goes in the heap. """ if self._free > 0: self._free -= 1 return True + if on_wait is not None: + on_wait() future: asyncio.Future[bool] = asyncio.get_running_loop().create_future() entry = (priority, next(self._arrivals), future) heapq.heappush(self._waiters, entry) diff --git a/src/agentic_cli/workflow/base_manager.py b/src/agentic_cli/workflow/base_manager.py index 9baf83d6..a181b6a3 100644 --- a/src/agentic_cli/workflow/base_manager.py +++ b/src/agentic_cli/workflow/base_manager.py @@ -537,7 +537,11 @@ def can_request_user_input(self) -> bool: ``UserInputUnavailable`` at once. The permission engine asks this before a sub-agent run lends its working slot for a prompt: a prompt no one can be shown is denied without waiting, and the run keeps its - slot. + slot. A subclass that overrides ``request_user_input`` to ask + through another channel overrides this too, saying when that + channel can answer: else the engine takes its prompts for ones no + one can be shown, and a sub-agent run keeps its slot while it waits + for the answer. """ return self._user_input_callback.get() is not None and not turn_has_ended() @@ -638,13 +642,20 @@ async def _run_agent(self, run: AgentRun) -> RunAnswer: on ``run.message`` (after ``run.history`` for an inheriting one), from the shared state ``run.state``, reports the run's events to the turn's live events as they are made, and returns its last answer, - its outcome and the shared state it changed. A failure raises (the - provider's error, or ``RunFailed``). A cancel stops the run; the + its outcome and the shared state it changed. A failed model call is + answered (``RunAnswer.error``: the provider's reason, + ``failure_reason``; ``RunAnswer.error_code``: its error's type, the + warning's code) and a failure in the backend's own words raised + (``RunFailed``), each with the last text the run wrote, which its + envelope carries; any other exception it lets out fails the run with + no result. A cancel stops the run; the run's own (``run.control.own_cancel()``: a limit's, its parent's, the user's) returns what it has, its last text and the shared state - it changed, and any other (its turn's) raises. ``run.control`` - keeps its limits at its model calls (each backend's in its - sub-agents' stacks). + it changed, and any other (its turn's) raises. Once the run's work + has ended, before anything it awaits to read what the run did, it + calls ``run.control.finish()``, so a cancel of the run alone then + loses nothing. ``run.control`` keeps its limits at its model calls + (each backend's in its sub-agents' stacks). Raises: NotImplementedError: This backend runs no sub-agent. diff --git a/src/agentic_cli/workflow/config.py b/src/agentic_cli/workflow/config.py index 7c853413..a0885c0a 100644 --- a/src/agentic_cli/workflow/config.py +++ b/src/agentic_cli/workflow/config.py @@ -57,8 +57,8 @@ class AgentConfig: conversation as it stands, after any summarizing and without the parent's reasoning. A sub-agent works and returns its answer to its parent in the same turn on both backends; only the root - replies to the user. True only on sub-agents, and in 0.7.0 only - on the root's own sub-agents without sub-agents of their own + replies to the user. True only on sub-agents, and only on the + root's own sub-agents without sub-agents of their own (``validate_agent_graph`` checks it). brief_required: The brief fields a delegation to this agent must fill (``workflow/agents/brief.py``: ``objective``, @@ -212,10 +212,7 @@ def validate_agent_graph( 9. the root does not set ``inherit_context``: it has no parent's conversation; 10. ``inherit_context`` only on an agent without sub-agents, and only on - the root's own sub-agents. In 0.7.0 a forked Deep Agents coordinator - is told that delegating will be refused, which is false for ours, so - a real model might never delegate; and below another sub-agent ADK - would show it the main agent's whole conversation; + the root's own sub-agents; 11. each agent's ``brief_required`` is a tuple (or list) of brief field names: ``title``, or one of ``BRIEF_FIELDS``; 12. each agent's ``limits`` is None or an ``AgentLimits``; @@ -333,14 +330,12 @@ def _check_inherit_context(config_map: dict[str, AgentConfig], root: str) -> Non if inheriting: raise AgentGraphError( f"Agent(s) {', '.join(repr(n) for n in inheriting)} set " - "inherit_context=True and have sub-agents of their own: in 0.7.0, " + "inherit_context=True and have sub-agents of their own: " "inherit_context is for agents without sub-agents. Leave it False " "on a coordinator." ) - # ADK shows an inheriting agent the main agent's conversation, whatever its - # depth, so below a fresh coordinator it would see what its parent was kept - # from; Deep Agents' fork sees its parent's. 0.7.0 offers neither. + # Inheriting is for the main agent's own sub-agents (rule 10). nested = sorted({ sub for name, config in config_map.items() @@ -351,7 +346,7 @@ def _check_inherit_context(config_map: dict[str, AgentConfig], root: str) -> Non if nested: raise AgentGraphError( f"Agent(s) {', '.join(repr(n) for n in nested)} set inherit_context=True " - f"below another sub-agent: in 0.7.0, inherit_context is for the main " + f"below another sub-agent: inherit_context is for the main " f"agent's ({root!r}) own sub-agents. Leave it False, or make it a " f"sub-agent of {root!r}." ) diff --git a/src/agentic_cli/workflow/deepagents/manager.py b/src/agentic_cli/workflow/deepagents/manager.py index cf87526a..0af3e7cc 100644 --- a/src/agentic_cli/workflow/deepagents/manager.py +++ b/src/agentic_cli/workflow/deepagents/manager.py @@ -64,7 +64,7 @@ validate_agent_graph, ) from agentic_cli.workflow import live_events -from agentic_cli.workflow.agents.delegate import AgentRun, RunAnswer, RunFailed +from agentic_cli.workflow.agents.delegate import AgentRun, RunAnswer, RunFailed, failure_reason from agentic_cli.workflow.context import ( OVERFLOW_ERROR_CODE, CompactResult, @@ -739,14 +739,17 @@ async def _run_agent(self, run: AgentRun) -> RunAnswer: Its last non-empty answer, as Deep Agents' own ``task`` read one (Anthropic may end with an empty ``end_turn`` after its final tool call), that answer's outcome mark - (``SubAgentOutcomeMiddleware``), and the shared keys it changed. - Its answers are the messages after its task message - (``_own_messages``): an inheriting run's history is not its own. + (``SubAgentOutcomeMiddleware``), and the shared keys it changed; + or, for a model call that failed, the provider's reason and its + error's type, with the last text it wrote, as of its last + finished step. Its answers + are the messages after its task message (``_own_messages``): an + inheriting run's history is not its own. Raises: RunFailed: Its request no longer fits its model's window, still - after its summary (``subagent_overflow_message``). - Exception: Its model call failed (the provider's error). + after its summary (``subagent_overflow_message``), with the + last text it wrote. """ graph = self._agent_graphs[run.ref.agent] task = HumanMessage(content=run.message, id=f"agentic-cli-task-{uuid.uuid4().hex}") @@ -787,7 +790,9 @@ async def _run_agent(self, run: AgentRun) -> RunAnswer: # goes on. if not run.control.own_cancel(): raise - except Exception as error: + except Exception as error: # noqa: BLE001 - the run fails; its parent reads why + # The run fails with the text it wrote before it. + wrote = _last_text(_answers_in(final, task.id)) if is_context_overflow(error): model = self._resolved_models.get(run.ref.agent) raise RunFailed( @@ -795,12 +800,19 @@ async def _run_agent(self, run: AgentRun) -> RunAnswer: run.ref.agent, str(model.ref) if model is not None else "the model" ), code=OVERFLOW_ERROR_CODE, + text=wrote, ) from error - raise + # A model call failed: the provider's error. + logger.debug("subagent_failed", run=run.ref.run, exc_info=error) + return RunAnswer( + text=wrote, error=failure_reason(error), error_code=type(error).__name__ + ) finally: var_child_runnable_config.reset(detached) - own = _own_messages(final.get("messages") or [], task.id) - answers = [message for message in own if isinstance(message, AIMessage)] + # Its work has ended (nothing below waits; as ADK's, which reads its + # state back): no cancel of the run alone stops it now. + run.control.finish() + answers = _answers_in(final, task.id) return RunAnswer( text=_last_text(answers), outcome=answer_outcome(answers[-1]) if answers else None, @@ -963,6 +975,12 @@ def _own_messages(messages: list[Any], task_id: str | None) -> list[Any]: return [] +def _answers_in(values: dict[str, Any], task_id: str | None) -> list[AIMessage]: + """A run's own answers in its graph's ``values``: the AI messages after its task message.""" + own = _own_messages(values.get("messages") or [], task_id) + return [message for message in own if isinstance(message, AIMessage)] + + def _last_text(answers: list[AIMessage]) -> str: """The text of the last of ``answers`` that has any, as Deep Agents' ``task`` reads it.""" for message in reversed(answers): diff --git a/src/agentic_cli/workflow/deepagents/middleware.py b/src/agentic_cli/workflow/deepagents/middleware.py index 1ab8f3f3..ad3b5ea0 100644 --- a/src/agentic_cli/workflow/deepagents/middleware.py +++ b/src/agentic_cli/workflow/deepagents/middleware.py @@ -912,10 +912,10 @@ class RunControlMiddleware(AgentMiddleware): Claude refuses a request whose messages hold tool calls or results when it defines no tools, and no call that answer makes is run (below); - after each, what it used (``workflow/usage.py::langchain_tokens``) goes - to ``RunControl.used``, with whether the answer makes tool calls: one - past the token limit that makes none is the run's result, whole. A - model that reports no usage counts none, so it is not limited by - tokens; + to ``RunControl.used``, which checks the run's total (with what its + side calls used), with whether the answer makes tool calls: one past + the token limit that makes none is the run's result, whole. A model + that reports no usage counts none of its own; - on the run's last call (``RunControl.final_call``: its step limit's, or one past its token limit that makes calls) the answer's tool calls are dropped (``without_calls``), so the agent ends with that answer. diff --git a/src/agentic_cli/workflow/interrupts.py b/src/agentic_cli/workflow/interrupts.py index 480887cb..2c7c2951 100644 --- a/src/agentic_cli/workflow/interrupts.py +++ b/src/agentic_cli/workflow/interrupts.py @@ -235,8 +235,10 @@ def answer( """An open call's result: what it returned if it finished, else why it has none. The call is ``run``'s, in the active turn's conversation. It stays - recorded until that conversation's turn ends (``clear``): the step - that answers it may be stopped before it is saved. + recorded until a turn of that conversation ends with every call + answered (``clear``): the step that answers it may be stopped before + it is saved, and a failed turn keeps it (``failed``) for the next + turn to answer. Args: call_id: The call. diff --git a/src/agentic_cli/workflow/usage.py b/src/agentic_cli/workflow/usage.py index c2b953d2..d7f40ee7 100644 --- a/src/agentic_cli/workflow/usage.py +++ b/src/agentic_cli/workflow/usage.py @@ -470,10 +470,14 @@ def by_agent(self) -> dict[str, UsageTotals]: lambda row: row.agent, lambda row: row.purpose in AGENT_STEP_PURPOSES ) - def by_purpose(self) -> dict[str, UsageTotals]: - """The side calls, by purpose, in the order each was first made.""" + def by_purpose( + self, *, run: str | None = ... # type: ignore[assignment] + ) -> dict[str, UsageTotals]: + """The side calls, by purpose, in the order each was first made; one run's + when ``run`` is given (None: the root's own work's).""" return self._grouped( - lambda row: row.purpose, lambda row: row.purpose not in AGENT_STEP_PURPOSES + lambda row: row.purpose, + lambda row: row.purpose not in AGENT_STEP_PURPOSES and (run is ... or row.run == run), ) def by_model( diff --git a/tests/integration/test_interrupted_calls.py b/tests/integration/test_interrupted_calls.py index 4e378ddd..56e7d4a3 100644 --- a/tests/integration/test_interrupted_calls.py +++ b/tests/integration/test_interrupted_calls.py @@ -1,4 +1,4 @@ -"""A turn stopped by Ctrl+C, or cut off by a crash: every call gets one result. +"""A turn stopped by Ctrl+C, cut off by a crash, or failed: every call gets one result. Ctrl+C stops the whole turn: the agent loop, its model calls, its tool calls and its sub-agents. What the model is told afterwards, on both backends @@ -16,7 +16,10 @@ - a call a crash left open (no cancel ran) is answered on the next turn "Interrupted before it finished ...". ADK keeps a long-running call without a result in every later request, which Claude refuses; it drops - any other one and logs that over the UI on every request. + any other one and logs that over the UI on every request; +- a turn that fails keeps the results of its calls that returned, and the + next turn answers each with its own (a call that did not return is + answered as a crash's), never a later call of the same id. The fake Claude refuses, as the real API does, a request with a ``tool_use`` whose ``tool_result`` is missing. diff --git a/tests/workflow/adk/test_run_control_plugin.py b/tests/workflow/adk/test_run_control_plugin.py index 42cf25d5..f2fbe909 100644 --- a/tests/workflow/adk/test_run_control_plugin.py +++ b/tests/workflow/adk/test_run_control_plugin.py @@ -134,7 +134,7 @@ async def test_a_finishing_answer_past_the_token_limit_is_left_as_it_is(self): assert (control.cancelled, control.final_call) == (None, False) assert answer.content is content - async def test_an_answer_with_no_usage_is_not_limited_by_tokens(self): + async def test_an_answer_with_no_usage_counts_none_of_its_own_tokens(self): control = RunControl(REF, AgentLimits(max_tokens=1)) plugin = RunControlPlugin(lambda: control, "anthropic") answer = LlmResponse(content=model(text("Found it."), call("lookup"))) @@ -145,6 +145,17 @@ async def test_an_answer_with_no_usage_is_not_limited_by_tokens(self): assert (control.cancelled, control.final_call) == (None, False) assert answer.content == model(text("Found it."), call("lookup")) + async def test_an_answer_with_no_usage_still_counts_the_runs_side_calls(self): + control = RunControl(REF, AgentLimits(max_tokens=100), side_tokens=lambda: 120) + plugin = RunControlPlugin(lambda: control, "anthropic") + answer = LlmResponse(content=model(text("Found it."), call("lookup"))) + + await plugin.before_model_callback(callback_context=None, llm_request=LlmRequest()) + await plugin.after_model_callback(callback_context=None, llm_response=answer) + + assert control.cancelled == ("limit", TOKEN_LIMIT_ERROR) + assert answer.content == model(text("Found it.")) + async def test_a_partial_answer_counts_nothing(self): control = RunControl(REF, AgentLimits(max_tokens=1)) plugin = RunControlPlugin(lambda: control, "anthropic") diff --git a/tests/workflow/deepagents/test_run_control_middleware.py b/tests/workflow/deepagents/test_run_control_middleware.py index 0e4bb3a2..ae89c44a 100644 --- a/tests/workflow/deepagents/test_run_control_middleware.py +++ b/tests/workflow/deepagents/test_run_control_middleware.py @@ -107,7 +107,7 @@ async def handler(request): assert (control.cancelled, kept) == (None, answer) -async def test_an_answer_with_no_usage_is_not_limited_by_tokens(): +async def test_an_answer_with_no_usage_counts_none_of_its_own_tokens(): control = RunControl(REF, AgentLimits(max_tokens=1)) middleware = RunControlMiddleware(lambda: SimpleNamespace(control=lambda run: control)) answer = AIMessage("Found it.", tool_calls=[CALL]) @@ -119,6 +119,20 @@ async def handler(request): assert (control.cancelled, control.final_call) == (None, False) +async def test_an_answer_with_no_usage_still_counts_the_runs_side_calls(): + control = RunControl(REF, AgentLimits(max_tokens=100), side_tokens=lambda: 120) + middleware = RunControlMiddleware(lambda: SimpleNamespace(control=lambda run: control)) + answer = AIMessage("Found it.", tool_calls=[CALL]) + + async def handler(request): + return answer + + kept = await middleware.awrap_model_call("the request", handler) + + assert control.cancelled == ("limit", TOKEN_LIMIT_ERROR) + assert (kept.content, kept.tool_calls) == ("Found it.", []) + + async def test_the_messages_steered_since_the_last_call_join_the_runs_state(): ref = RunRef(agent="researcher", instance="researcher-1", run="researcher-1#1", parent_run=None, depth=1) diff --git a/tests/workflow/test_adk_model_errors.py b/tests/workflow/test_adk_model_errors.py index eda3bf85..bc8bf365 100644 --- a/tests/workflow/test_adk_model_errors.py +++ b/tests/workflow/test_adk_model_errors.py @@ -123,6 +123,51 @@ async def test_no_answer_ends_the_turn_with_an_error(monkeypatch, answer, model, assert not [event for event in events if event.type is EventType.TEXT] +async def test_a_sub_agents_reply_that_is_no_answer_fails_its_run_warned_with_its_code( + monkeypatch, +): + """The run fails, its parent reads why, and the user's warning carries + the reply's code, as the main agent's failed turn does.""" + import json + + from agentic_cli.workflow.agents import RUN_FAILED + + def coordinator(request) -> dict: + body = json.loads(request.content) + answer = anthropic_message(model="claude-sonnet-4-6") + if len(body["messages"]) == 1: + answer.update(stop_reason="tool_use", content=[{ + "type": "tool_use", "id": "c1", "name": "task", + "input": {"agent_type": "researcher", "title": "Find X", "objective": "Find X."}, + }]) + else: + answer["content"] = [{"type": "text", "text": "The researcher could not."}] + return answer + + route(monkeypatch, anthropic, "AsyncAnthropic", FakeAPI(coordinator)) + route_gemini(monkeypatch, FakeAPI(finished("MALFORMED_FUNCTION_CALL"))) + manager = adk( + [AgentConfig(name="coordinator", prompt="Delegate.", sub_agents=["researcher"]), + AgentConfig(name="researcher", prompt="Find.", description="Finds.", + model="gemini-2.5-flash")], + settings(default_model="claude-sonnet-4-6"), + ) + try: + events = [e async for e in manager.process("Find X.", user_id="u", session_id="s")] + finally: + await manager.cleanup() + + (warning,) = errors(events) + assert warning.content.startswith( + "researcher-1 failed: google:gemini-2.5-flash returned no answer" + ) + assert (warning.metadata["recoverable"], warning.metadata["error_code"]) == ( + True, "MALFORMED_FUNCTION_CALL" + ) + (record,) = manager.agent_runs.records(manager.session_ref("s", "u")) + assert record.status == RUN_FAILED + + async def test_a_reply_cut_at_its_limit_with_text_is_an_answer(monkeypatch): """Text before the limit is the answer, shown as it is.""" events = await turn_on( diff --git a/tests/workflow/test_agent_brief.py b/tests/workflow/test_agent_brief.py index fe0e88d7..27afa055 100644 --- a/tests/workflow/test_agent_brief.py +++ b/tests/workflow/test_agent_brief.py @@ -127,6 +127,9 @@ def test_its_text(self): "use the specific facts, figures and identifiers already established in the " "conversation rather than answering generically." ) + # True on both backends: Deep Agents' conversation leaves out the call + # that handed the run its task, which ADK's keeps. + assert "what that agent did is quoted. Do not carry out" in INHERITED_CONTEXT_NOTE class TestReadBrief: diff --git a/tests/workflow/test_agent_control.py b/tests/workflow/test_agent_control.py index c9e66584..f3db6338 100644 --- a/tests/workflow/test_agent_control.py +++ b/tests/workflow/test_agent_control.py @@ -91,6 +91,24 @@ async def run() -> str: assert made.cancelled is None + async def test_a_run_whose_work_has_ended_is_not_cancelled(self): + """Its hook said its work ended (``finish``) and still reads back what + the run did: neither a stop nor its time limit cancels it then.""" + made = control(timeout=0.05) + + async def run() -> str: + with made.timing(): + made.finish() + made.cancel(by="parent", error="no longer needed") + await asyncio.sleep(0.1) # reading what it did, past its time limit + return "its answer" + + task = asyncio.create_task(run()) + made.bind(task) + + assert await asyncio.wait_for(task, 5) == "its answer" + assert made.cancelled is None + async def test_a_cancel_before_the_task_is_bound_cancels_it_then(self): made = control() made.cancel(by="user", error="stopped") @@ -280,6 +298,21 @@ def test_once_past_it_every_call_is_the_last(self): assert made.final_call is True + async def test_the_runs_side_calls_count_with_its_own(self): + """``side_tokens``: what the run's tools' side calls and its summaries + used so far, as its usage record counts them.""" + side = {"tokens": 0} + made = RunControl(REF, AgentLimits(max_tokens=100), side_tokens=lambda: side["tokens"]) + task, _ = await a_run(made) + + made.used(40, 10) + assert made.cancelled is None + side["tokens"] = 45 # a side call its tool made meanwhile + made.used(5, 5) # 50 + 10 of its own, 45 besides: 105 + + assert (made.cancelled, made.final_call) == (("limit", TOKEN_LIMIT_ERROR), True) + task.cancel() + def test_without_a_limit_any_number_is_fine(self): made = control() made.used(10**9, 10**9) diff --git a/tests/workflow/test_agent_delegate.py b/tests/workflow/test_agent_delegate.py index 5e55cee8..10695514 100644 --- a/tests/workflow/test_agent_delegate.py +++ b/tests/workflow/test_agent_delegate.py @@ -67,7 +67,14 @@ set_active_tool_call, set_active_turn, ) -from agentic_cli.workflow.usage import UsageLedgers, UsageTotals, llm_usage_event +from agentic_cli.workflow.usage import ( + PURPOSE_SUBAGENT, + PURPOSE_SUMMARIZATION, + PURPOSE_TOOL, + UsageLedgers, + UsageTotals, + llm_usage_event, +) from tests.loop_guard import no_blocking_calls CONVERSATION = SessionRef("app", "u", "s") @@ -298,6 +305,25 @@ async def test_a_hook_that_answers_an_error_fails_it_with_its_text(self): ) assert events[-1].content == "researcher-1 failed: m returned no answer" + async def test_a_hook_that_answers_an_error_warns_with_its_code(self): + hook, _ = answering("Half an answer.", error="Error code: 400 - overloaded", + error_code="BadRequestError") + + result, events = await delegated(delegations(hook), request()) + + assert result.result["error"] == "Error code: 400 - overloaded" + warning = events[-1] + assert (warning.content, warning.metadata["error_code"]) == ( + "researcher-1 failed: Error code: 400 - overloaded", "BadRequestError" + ) + + async def test_an_error_answered_without_a_code_warns_with_none(self): + hook, _ = answering("Half an answer.", error="m returned no answer") + + _, events = await delegated(delegations(hook), request()) + + assert events[-1].metadata.get("error_code") is None + async def test_its_own_words_are_said_as_given(self): said = "researcher: the request no longer fits m's context window." @@ -309,6 +335,22 @@ async def hook(run: AgentRun) -> RunAnswer: assert result.result["error"] == said warning = events[-1] assert (warning.content, warning.metadata["error_code"]) == (said, "CONTEXT_OVERFLOW") + assert result.result["result"] == "" + + async def test_its_own_words_carry_the_text_it_wrote(self): + said = "researcher: the request no longer fits m's context window." + + async def hook(run: AgentRun) -> RunAnswer: + raise RunFailed(said, code="CONTEXT_OVERFLOW", text="X is about 42.") + + result, events = await delegated(delegations(hook), request()) + + assert (result.result["status"], result.result["result"], result.result["error"]) == ( + RUN_FAILED, "X is about 42.", said + ) + started, ended, warning = events + assert (ended.metadata["status"], ended.metadata["result"]) == (RUN_FAILED, "X is about 42.") + assert warning.content == said class TestTheRunsOwnTask: @@ -1001,6 +1043,36 @@ async def test_past_it_the_run_is_cancelled_by_its_limit(self): ) assert statuses(events) == [("agent_run", RUN_STARTED), ("agent_run", RUN_CANCELLED)] + async def test_a_run_whose_work_had_ended_keeps_its_answer(self): + """The hook's work ended (``RunControl.finish``) and it still reads + what the run did (ADK reads its child session's state) when the + time limit fires and its parent stops it: the run completes with its + answer and its state.""" + cancelled: list[bool] = [] + made: Delegations + + async def hook(run: AgentRun) -> RunAnswer: + run.control.finish() + cancelled.append(made.cancel("researcher-1#1", by="parent", error="no longer needed")) + await asyncio.sleep(0.15) # the read, past the time limit + return RunAnswer(text="X is 42.", state={"tasks": [{"description": "find X"}]}) + + types = { + **TYPES, + "researcher": AgentConfig(name="researcher", prompt="p", description="Finds.", + limits=AgentLimits(timeout=0.05)), + } + made = delegations(hook, types=types) + + result, events = await asyncio.wait_for(delegated(made, request()), 5) + + assert cancelled == [False] + assert (result.result["status"], result.result["result"], result.result["error"]) == ( + RUN_COMPLETED, "X is 42.", None + ) + assert result.state == {"tasks": [{"description": "find X"}]} + assert statuses(events) == [("agent_run", RUN_STARTED), ("agent_run", RUN_COMPLETED)] + class TestTheLimitsAtModelCalls: """What a backend's run reports to its control at each model call, and how the run ends.""" @@ -1051,6 +1123,39 @@ async def hook(run: AgentRun) -> RunAnswer: ) assert statuses(events) == [("agent_run", RUN_STARTED), ("agent_run", RUN_CANCELLED)] + async def test_its_side_calls_count_toward_its_tokens(self): + """The run's total is what its usage record counts: its tools' side + calls and its summaries, recorded under it, count with its own calls + (whose own rows are not counted twice); another run's do not.""" + ledgers = UsageLedgers() + other = RunRef(agent="leaf", instance="leaf-1", run="leaf-1#1", + parent_run=None, depth=1) + seen: list[Any] = [] + + def recorded(purpose: str, tokens: int, run: RunRef | None = None) -> None: + event = llm_usage_event("anthropic:claude", UsageTotals(input=tokens, calls=1)) + event.metadata["purpose"] = purpose + event.run = run # None: the run in progress + ledgers.record(event) + + async def hook(run: AgentRun) -> RunAnswer: + run.control.used(40, 10) + recorded(PURPOSE_SUBAGENT, 50) # that call's own row + recorded(PURPOSE_TOOL, 30) # its tool's side call + recorded(PURPOSE_SUMMARIZATION, 30) # a summary of its conversation + recorded(PURPOSE_TOOL, 500, run=other) + run.control.used(30, 0) # 80 of its own, 60 besides: 140 + seen.append(run.control.cancelled) + run.control.used(10, 5) # 155 + return RunAnswer(text="Found it.") + + policy = SubAgentPolicy(limits=AgentLimits(max_tokens=150)) + result, _ = await delegated(delegations(hook, policy=policy, ledgers=ledgers), request()) + + assert seen == [None] + assert (result.result["status"], result.result["cancelled_by"], + result.result["error"]) == (RUN_CANCELLED, "limit", TOKEN_LIMIT_ERROR) + async def test_a_finishing_answer_over_its_tokens_completes_it_whole(self): async def hook(run: AgentRun) -> RunAnswer: run.control.used(80, 20) @@ -1506,7 +1611,7 @@ class TestWaitingOnTheUser: """A sub-agent run that waits on the user (``waiting_on_user``: a question, a permission prompt) says ``input_required``, lends its slot meanwhile, and takes it back ahead of the runs that have not started - (``running``).""" + (``running``), ``queued`` while it waits for it.""" async def test_a_run_lends_its_slot_and_takes_it_back_ahead_of_new_runs(self): hook = Holding() @@ -1532,12 +1637,65 @@ async def asking(run: AgentRun) -> RunAnswer: assert runs.record(CONVERSATION, "researcher-1").status == RUN_INPUT_REQUIRED answered.set() await until(lambda: pool.waiting == 2) # researcher-1 wants it back; researcher-3 waits + # Answered, it waits on its slot, no longer on the user. + assert runs.record(CONVERSATION, "researcher-1").status == RUN_QUEUED hook.go["researcher-2"].set() await asyncio.wait_for(turn.task, 5) assert hook.working == ["researcher-2", "researcher-1 back", "researcher-3"] assert turn.of("researcher-1") == [ - RUN_STARTED, RUN_INPUT_REQUIRED, RUN_RUNNING, RUN_COMPLETED, + RUN_STARTED, RUN_INPUT_REQUIRED, RUN_QUEUED, RUN_RUNNING, RUN_COMPLETED, + ] + assert (pool.free, pool.waiting) == (1, 0) + + async def test_a_question_asked_while_it_waits_for_its_slot_back_is_input_required_again( + self, + ): + """Two calls of one response that each ask: the second asks while the + first, answered, waits for its slot back. The run waits on the user + again, and says so; once both are answered and its slot is back, it + is ``running``.""" + hook = Holding() + runs = AgentRuns() + first_answered, second_answered = asyncio.Event(), asyncio.Event() + second_asks = asyncio.Event() + + async def asks(answered: asyncio.Event) -> None: + async with waiting_on_user(): + await answered.wait() + + async def asking(run: AgentRun) -> RunAnswer: + if run.ref.instance != "researcher-1": + return await hook(run) + + async def second() -> None: + await second_asks.wait() + await asks(second_answered) + + await asyncio.gather(asks(first_answered), second()) + return RunAnswer(text="Asked twice.") + + made = delegations(asking, runs=runs, policy=SubAgentPolicy(max_active=1)) + pool = made.slots(CONVERSATION) + + turn = Turn(lambda: asyncio.gather( + *(made.delegate(request(call_id=call)) for call in ("c1", "c2")) + )) + await until(lambda: hook.working == ["researcher-2"]) + first_answered.set() + await until(lambda: pool.waiting == 1) # researcher-1 wants its slot back + assert runs.record(CONVERSATION, "researcher-1").status == RUN_QUEUED + second_asks.set() + await until(lambda: runs.record(CONVERSATION, "researcher-1").status + == RUN_INPUT_REQUIRED) + second_answered.set() + await until(lambda: pool.waiting == 1) + hook.go["researcher-2"].set() + await asyncio.wait_for(turn.task, 5) + + assert turn.of("researcher-1") == [ + RUN_STARTED, RUN_INPUT_REQUIRED, RUN_QUEUED, RUN_INPUT_REQUIRED, RUN_QUEUED, + RUN_RUNNING, RUN_COMPLETED, ] assert (pool.free, pool.waiting) == (1, 0) diff --git a/tests/workflow/test_agent_slots.py b/tests/workflow/test_agent_slots.py index 93e02a41..fffe25ed 100644 --- a/tests/workflow/test_agent_slots.py +++ b/tests/workflow/test_agent_slots.py @@ -336,6 +336,42 @@ async def waits() -> None: pool.release(other) assert (pool.free, pool.waiting) == (1, 0) + async def test_a_take_back_that_must_wait_says_so_as_it_starts_to(self): + """``on_wait``: the block is over, and no slot is free to take back.""" + pool = SlotPool(1) + slot = await pool.acquire() + said: list[str] = [] + over = asyncio.Event() + + async def waits() -> None: + async with pool.lent(slot, on_wait=lambda: said.append("waits")): + await over.wait() + said.append("back") + + lending = asyncio.create_task(waits()) + await until(lambda: slot.lent) + other = await pool.acquire() # works in the lent slot + over.set() + await until(lambda: pool.waiting == 1) + assert said == ["waits"] + pool.release(other) + await asyncio.wait_for(lending, 1) + + assert (said, slot.held) == (["waits", "back"], True) + + async def test_a_take_back_with_a_slot_free_or_handed_back_says_nothing(self): + pool = SlotPool(1) + slot = await pool.acquire() + said: list[str] = [] + + async with pool.lent(slot, on_wait=lambda: said.append("waits")): + pass # no other run took the lent slot + async with pool.lent(slot, on_wait=lambda: said.append("waits")): + child = await pool.acquire() + pool.hand_back(child, to=slot) + + assert (said, slot.held, pool.free) == ([], True, 0) + class TestHandBack: async def test_a_child_hands_its_slot_to_its_parent_waiting_on_it_alone(self): diff --git a/tests/workflow/test_subagent_context.py b/tests/workflow/test_subagent_context.py index 1e8ef154..c8501074 100644 --- a/tests/workflow/test_subagent_context.py +++ b/tests/workflow/test_subagent_context.py @@ -3,7 +3,7 @@ A sub-agent sees the request alone (``inherit_context=False``, the default) or its parent's conversation too (``True``). ``validate_agent_graph`` checks the field where it sits in the tree, for every backend: the root has no -parent to inherit from, and in 0.7.0 inheriting is for the main agent's own +parent to inherit from, and inheriting is for the main agent's own sub-agents, and only those without sub-agents of their own. What each mode sends a model is pinned per backend: ADK in @@ -70,15 +70,12 @@ def test_a_leaf_below_another_sub_agent_sees_the_request_alone(self): assert validate_agent_graph(tree(deep=False)).root_name == "lead" def test_inheriting_is_for_the_main_agents_own_sub_agents(self): - # On ADK an inheriting agent is shown the main agent's conversation, - # whatever its depth: below a fresh coordinator it would see what its - # parent was kept from. Deep Agents' fork sees its parent's. Neither - # is offered in 0.7.0. with pytest.raises(AgentGraphError) as exc: validate_agent_graph(tree("deep")) message = str(exc.value) assert "'deep'" in message and "'lead'" in message - assert "inherit_context" in message and "0.7.0" in message + assert "inherit_context" in message and "make it a sub-agent of 'lead'" in message + assert "0.7" not in message # shipped text names no version def test_a_middle_coordinator_sees_the_request_alone(self): assert validate_agent_graph(tree(middle=False)).root_name == "lead" @@ -106,7 +103,7 @@ def test_inheriting_is_for_agents_without_sub_agents(self): message = str(exc.value) assert "'middle'" in message assert "inherit_context" in message and "without sub-agents" in message - assert "0.7.0" in message + assert "Leave it False on a coordinator" in message and "0.7" not in message @pytest.mark.parametrize("value", ["fresh", "inherit", 1, None]) def test_a_value_that_is_not_a_bool_is_named(self, value): diff --git a/tests/workflow/test_subagents_contract.py b/tests/workflow/test_subagents_contract.py index d4a4e4b2..dee83da0 100644 --- a/tests/workflow/test_subagents_contract.py +++ b/tests/workflow/test_subagents_contract.py @@ -1381,6 +1381,8 @@ async def test_the_parent_reads_why_and_the_turn_goes_on(self, make_crew): assert (warning.metadata["recoverable"], warning.metadata["agent"], warning.run) == ( True, "researcher", RESEARCHER, ) + # Its code is the provider error's type, which the CLI shows after it. + assert warning.metadata["error_code"] == "BadRequestError" # The parent reads the provider's reason, on both backends. read = envelope_read(crew.results_read("coordinator")["c1"]) assert (read["success"], read["status"], read["result"]) == (False, RUN_FAILED, "") @@ -1395,6 +1397,60 @@ async def test_the_parent_reads_why_and_the_turn_goes_on(self, make_crew): ] assert crew.requests("coordinator") == 2 + async def test_the_text_a_run_wrote_before_it_failed_is_its_result(self, make_crew): + """Spec 5.3: a failed envelope carries whatever text the run produced.""" + crew = make_crew( + team(), + coordinator=[calls(delegate("researcher", "Find X.", "c1")), + says("The researcher got halfway.")], + researcher=[calls(use("contract_lookup", "r1", q="X"), text="X is about 42."), + fails("overloaded")], + ) + + events = await crew.turn() + + read = envelope_read(crew.results_read("coordinator")["c1"]) + assert (read["success"], read["status"], read["result"]) == ( + False, RUN_FAILED, "X is about 42." + ) + assert "overloaded" in read["error"] + (ended,) = runs_of(events, RUN_FAILED) + assert (ended.metadata["result"], ended.metadata["error"]) == ( + "X is about 42.", read["error"] + ) + (warning,) = [e for e in events if e.type is EventType.ERROR] + assert warning.content == f"researcher-1 failed: {read['error']}" + assert (warning.metadata["recoverable"], warning.metadata["error_code"]) == ( + True, "BadRequestError" + ) + (record,) = crew.records() + assert (record.status, record.result) == (RUN_FAILED, "X is about 42.") + + async def test_an_overflow_after_text_keeps_that_text_as_its_result(self, make_crew): + too_long = "prompt is too long: 208310 tokens > 200000 maximum" + crew = make_crew( + team(), + coordinator=[calls(delegate("researcher", "Find X.", "c1")), + says("The researcher got halfway.")], + # Enough for either backend's retry, should it make one. + researcher=[calls(use("contract_lookup", "r1", q="X"), text="X is about 42."), + fails(too_long), fails(too_long)], + summaries=[says("The researcher looked X up.")], + ) + + events = await crew.turn() + + read = envelope_read(crew.results_read("coordinator")["c1"]) + assert (read["status"], read["result"], read["error"]) == ( + RUN_FAILED, "X is about 42.", + "researcher: the request no longer fits anthropic:claude-sonnet-4-6's " + "context window.", + ) + (warning,) = [e for e in events if e.type is EventType.ERROR] + assert (warning.content, warning.metadata["error_code"]) == ( + read["error"], "CONTEXT_OVERFLOW" + ) + async def test_the_next_turn_runs(self, make_crew): crew = make_crew( team(), @@ -2581,6 +2637,55 @@ async def test_a_run_past_its_time_is_cancelled_with_what_it_wrote(self, make_cr assert [e.metadata["status"] for e in runs_of(events)] == [RUN_STARTED, RUN_CANCELLED] assert BLOCKING["stopped"].is_set() # its tool was stopped with it + @pytest.mark.parametrize("backend", ["adk"], indirect=True) + @pytest.mark.parametrize("stop", ["time limit", "parent"]) + async def test_on_adk_a_run_whose_work_ended_keeps_it_while_its_state_is_read( + self, make_crew, stop + ): + """ADK reads a run's shared state back from its child session once + its stream has ended. Its time limit firing during that read, or its + parent stopping it then, leaves the run completed with its answer + and the tasks it saved. Deep Agents reads nothing after its stream.""" + crew = make_crew( + [agent("coordinator", sub_agents=("researcher",), include_state_tools=True), + agent("researcher", include_state_tools=True, limits=AgentLimits(timeout=1.0))], + coordinator=[calls(delegate("researcher", "Find X.", "c1")), says("Done.")], + researcher=[calls(use("save_tasks", "r1", tasks=[ + {"description": "find X", "status": "completed"}, + ])), + says("X is 42.")], + ) + await crew.manager._ensure_initialized() + service = crew.manager._session_service + read = service.get_session + during: list[tuple[int, bool | None]] = [] + + async def slow_state_read(**kwargs: Any) -> Any: + config = kwargs.get("config") + if kwargs["app_name"].endswith("--agents") and config is not None \ + and config.num_recent_events == 0: + stopped = None + if stop == "parent": + stopped = crew.cancel("researcher-1#1", by="parent", error="no longer needed") + during.append((crew.requests("researcher"), stopped)) + # Past the run's time limit, which started with its work. + await asyncio.sleep(1.3 if stop == "time limit" else 0.05) + return await read(**kwargs) + + service.get_session = slow_state_read + events = await asyncio.wait_for(crew.turn(), 20) + + # The read came after the run's last answer; a stop then stops nothing. + assert during == [(2, False if stop == "parent" else None)] + assert envelope_read(crew.results_read("coordinator")["c1"]) == { + "success": True, "agent": "researcher-1", "run": "researcher-1#1", + "status": RUN_COMPLETED, "partial": False, "result": "X is 42.", "error": None, + } + (record,) = crew.records() + assert (record.status, record.cancelled_by) == (RUN_COMPLETED, None) + assert [e.metadata["status"] for e in runs_of(events)] == [RUN_STARTED, RUN_COMPLETED] + assert [task["description"] for task in (await crew.state())["tasks"]] == ["find X"] + class TestALimitAtAPrompt: """A limit that fires while the run waits at a permission prompt (the @@ -2788,6 +2893,37 @@ async def test_a_finishing_answer_past_it_completes_the_run_whole(self, make_cre used = crew.ledger().totals(run="researcher-1#1") assert (used.input, used.output, used.calls) == (140, 40, 2) + async def test_a_side_call_its_tool_makes_counts_and_limits_it_at_its_next_call( + self, make_crew + ): + """The run's total is what its usage record counts, its tools' side + calls included: 50 tokens of its own, then a summary of 110 that its + tool asked for, and its next answer (25) is past 150.""" + crew = make_crew( + [agent("coordinator", sub_agents=("researcher",)), + agent("researcher", tools=(contract_summarize, contract_whoami), + limits=AgentLimits(max_tokens=150))], + coordinator=[calls(delegate("researcher", "Find X.", "c1")), says("Done.")], + researcher=[calls(use("contract_summarize", "r1", text="A long page."), + text="Reading.", usage=(40, 10)), + calls(use("contract_whoami", "r2"), text="X is about 42.", + usage=(20, 5)), + says("[never asked]")], + side_calls=[says("A summary.", usage=(100, 10))], + ) + + events = await crew.turn() + + assert crew.requests("researcher") == 2 + assert SEEN == [] and calls_to(events, "r2") == [] + assert envelope_read(crew.results_read("coordinator")["c1"]) == { + "success": False, "agent": "researcher-1", "run": "researcher-1#1", + "status": RUN_CANCELLED, "partial": True, "result": "X is about 42.", + "error": TOKEN_LIMIT_ERROR, "cancelled_by": "limit", + } + used = crew.ledger().totals(run="researcher-1#1") + assert (used.input, used.output, used.calls) == (160, 25, 3) + class TestSteering: """A message steered to a run while its tool call is in progress is in @@ -3055,12 +3191,44 @@ async def answer(request: UserInputRequest) -> str: assert envelope_read(crew.results_read("coordinator")["c1"])["result"] == "Asked." assert (crew.slots().free, crew.slots().waiting) == (1, 0) + async def test_a_run_answered_while_its_slot_works_for_another_waits_queued(self, make_crew): + """The user answers the asker while the holder works in the asker's + lent slot: the asker no longer waits on the user but on its slot, + so it says ``queued`` until it has it back, then ``running``.""" + crew = asking_crew(make_crew, holder=calls(use("contract_hold", "h1"))) + answered = asyncio.Event() + + async def answer(request: UserInputRequest) -> str: + await HELD["started"].wait() # the holder works in the asker's slot + answered.set() + return "B" + + crew.answer_with(answer) + with no_blocking_calls(): + turn = crew.start() + try: + # Answered, the asker waits for its slot back, as the researcher does. + await until(lambda: answered.is_set() and crew.slots().waiting == 2) + assert [r.status for r in crew.records()] == [ + RUN_QUEUED, RUN_RUNNING, RUN_QUEUED, + ] + finally: + HELD["go"].set() + events = await asyncio.wait_for(turn, 10) + + assert [status for instance, status in working( + events, RUN_INPUT_REQUIRED, RUN_QUEUED, RUN_RUNNING + ) if instance == "asker-1"] == [RUN_INPUT_REQUIRED, RUN_QUEUED, RUN_RUNNING] + assert envelope_read(crew.results_read("coordinator")["c1"])["result"] == "Asked." + assert (crew.slots().free, crew.slots().waiting) == (1, 0) + async def test_two_runs_at_permission_prompts_with_one_slot_both_finish( self, make_crew, project ): """The permission engine shows one prompt at a time: a run waiting for its turn to ask lends its slot too, or the run asking first could - never take its slot back.""" + never take its slot back. researcher-2, answered while researcher-1 + works in the slot again, waits ``queued`` for it.""" crew = make_crew( [agent("coordinator", sub_agents=("researcher",)), agent("researcher", tools=("write_file",))], @@ -3091,7 +3259,7 @@ async def allow_once(request: UserInputRequest) -> str: ("researcher-2", RUN_QUEUED), ("researcher-1", RUN_INPUT_REQUIRED), ("researcher-2", RUN_RUNNING), ("researcher-2", RUN_INPUT_REQUIRED), ("researcher-1", RUN_RUNNING), - ("researcher-2", RUN_RUNNING), + ("researcher-2", RUN_QUEUED), ("researcher-2", RUN_RUNNING), ] assert (crew.slots().free, crew.slots().waiting) == (1, 0) diff --git a/tests/workflow/test_usage_ledger.py b/tests/workflow/test_usage_ledger.py index b69b2171..24a3a0d9 100644 --- a/tests/workflow/test_usage_ledger.py +++ b/tests/workflow/test_usage_ledger.py @@ -137,6 +137,13 @@ def test_grouped(self): "m": {"input": 110, "output": 11}, "small": {"input": 30, "output": 3}, } assert ledger.run_usage("nobody-1#1") == {} + # One run's side calls (a sub-agent run's token limit counts them). + assert ledger.by_purpose(run="researcher-1#1") == { + PURPOSE_TOOL: UsageTotals(input=30, output=3, calls=1), + } + assert ledger.by_purpose(run=None) == { + PURPOSE_SUMMARIZATION: UsageTotals(input=20, output=2, calls=1), + } def test_a_call_in_a_turn_carries_its_number(self): ledger = UsageLedger(CONVERSATION)