diff --git a/CHANGELOG.md b/CHANGELOG.md index c1a4c2ee..d010250e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -697,7 +697,9 @@ the start of the entry's title. starts and ends every run (`workflow/agents/delegate.py`), each at its own end, so of two parallel delegations the faster ends first. Each manager records its runs by conversation (`BaseWorkflowManager.agent_runs`, - provisional: `records(ref)`, `record(ref, id)`; a record has the brief, + provisional: `records(ref)`, `record(ref, id)`, `number_from(ref, counts)` + to number a conversation's instances past the ones its store keeps; a + record has the brief, `started_by`, `mode` and, for a cancelled run, `cancelled_by`); a run a stopped or failed turn leaves open is recorded `interrupted`. `get_active_run()` (exported @@ -1541,6 +1543,23 @@ the start of the entry's title. ### Changed +- **On ADK, a conversation's sub-agent transcripts are deleted with it, and no + run reuses one.** Each sub-agent run's transcript is a child + session of its conversation (app `--agents`, id `/`), which no conversation list, `/resume` picker or + `--continue` shows. Deleting the conversation deletes them, events and + all, whoever deletes it: `delete_session`, a `SessionReader` + (`/sessions --delete` on another backend's conversation), `/new` on the + memory store, and a conversation already gone leaves none behind + (`adk/sessions.py::delete_children`). Instances are numbered per manager, + so each turn's first run is numbered past the instances the + conversation's store keeps (`BaseWorkflowManager._stored_instances`, + asked once per conversation per turn; `AgentRuns.number_from`), whoever + ran them: a manager before a restart or a switch of backend or store, or + another process that had the conversation between two turns. + `researcher-2` follows a stored `researcher-1`, whose transcript stays as + it was. A run whose instance the store keeps all the same fails rather + than replace it. - **One `task` tool on both backends, which takes a brief.** **Breaking:** ADK offered one tool per sub-agent (`researcher(request=...)`) and Deep Agents its own `task(description=, subagent_type=)`; now every agent diff --git a/CLAUDE.md b/CLAUDE.md index 3f6d96c2..80fcedaf 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -49,9 +49,9 @@ agentic-cli/ │ │ ├── waiting_jobs.py # Which finished jobs wait to be told in the open conversation: one rule (JobRecord.awaiting_resume, then its own, no conversation's, or a gone conversation's: can_resume, then the other installed backends' readers, opens_anywhere: one another backend keeps is not gone, its job waits for it) for the deliveries, ↻N and the startup line │ │ └── usage_tracker.py # Token usage / status bar: ctx = the main agent's last prompt over its context_trigger (a call with a purpose, a sub-agent's, a summary's or a side call's, never moves it); the token segment the open conversation's total, every call of its turns; format_usage: /status's rows by agent and /agents 's tokens by model │ ├── workflow/ -│ │ ├── base_manager.py # BaseWorkflowManager (abstract; subagents=: its SubAgentPolicy, subagent_policy, read-only, kept for its life; _delegations: its Delegations (agents/delegate.py), made on first use over agent_runs, the policy, the agents' configs, the usage ledgers and _run_agent, the backend's hook that runs one sub-agent run; _load_models: load the catalog, then resolve every model (the configs', then _resolve_extra_models: a backend's agents built without configs, leniently), once, no retry (the background refresh started after a successful init checks the models the settings name); _compute_budgets right after it, before any service is built: each agent's context numbers, ContextBudgetError for a window too small to work in, for a backend that says _manages_context (ADK, whoever built its agents, and Deep Agents; LangGraph has none); the lifecycle: cleanup, reinitialize and the one release, _release_resources: the base's state reset, the backend's hooks _detach_backend/_detach_store (skipped while _keeping keeps the store), the services detached and their closes started on a worker thread, then every closer and the services waited for last (shielded), in one shielded task; the turn: _turn, every turn's entry (log context, _turn_admission, _workflow_context; the sub-agent runs it leaves open, a cancel's or a failure's, recorded interrupted as it ends: agent_runs, workflow/agents/runs.py), and the templates over the backend's hooks: resume_with_job_result (the job's result read on a worker thread, job_notice → _deliver_job_notice), can_resume (_record_resumable, _conversation_exists), compact (→ _compact_turn), supports_job_resume/supports_compact derived from them; services (services.py's ServiceSet behind the forwards: _services, _build_services(_into), _get_service_tool_map, _close_services, _keeping) and the hand-over: lend_services → initialize_services(services=loan) → give_services (no turn while a manager holds services it does not own); service detection, tool assembly; context_budget/root_agent_name; the usage ledgers (usage: the open conversation's, usage_of; _turn counts each turn in its conversation's and gives a run a cancel leaves open what it used) and side calls (_report_side_call: generate_simple's usage, its purpose from usage.side_call, summarize's tool, on_session_end's memory_extraction outside any turn, recorded in its conversation's ledger and, in a turn, reported through its live events, never to a turn that has ended: turn_has_ended); summarize and fact extraction: a prompt over the default model's room, at the resolved max_tokens, cut in the middle, never under MIN_PROMPT_ROOM, _fit_prompt; the memory index behind the forwards _memory_index_now/_memory_index_cached/_memory_index_cap/_forget_memory_index and _index_snapshots (memory_index.py's MemoryIndex; the release clears it)) +│ │ ├── base_manager.py # BaseWorkflowManager (abstract; subagents=: its SubAgentPolicy, subagent_policy, read-only, kept for its life; _delegations: its Delegations (agents/delegate.py), made on first use over agent_runs, the policy, the agents' configs, the usage ledgers, _run_agent, the backend's hook that runs one sub-agent run, and _stored_instances, the one that says how many instances of each type a conversation's store keeps (the base: none); _load_models: load the catalog, then resolve every model (the configs', then _resolve_extra_models: a backend's agents built without configs, leniently), once, no retry (the background refresh started after a successful init checks the models the settings name); _compute_budgets right after it, before any service is built: each agent's context numbers, ContextBudgetError for a window too small to work in, for a backend that says _manages_context (ADK, whoever built its agents, and Deep Agents; LangGraph has none); the lifecycle: cleanup, reinitialize and the one release, _release_resources: the base's state reset, the backend's hooks _detach_backend/_detach_store (skipped while _keeping keeps the store), the services detached and their closes started on a worker thread, then every closer and the services waited for last (shielded), in one shielded task; the turn: _turn, every turn's entry (log context, _turn_admission, _workflow_context; the sub-agent runs it leaves open, a cancel's or a failure's, recorded interrupted as it ends: agent_runs, workflow/agents/runs.py), and the templates over the backend's hooks: resume_with_job_result (the job's result read on a worker thread, job_notice → _deliver_job_notice), can_resume (_record_resumable, _conversation_exists), compact (→ _compact_turn), supports_job_resume/supports_compact derived from them; services (services.py's ServiceSet behind the forwards: _services, _build_services(_into), _get_service_tool_map, _close_services, _keeping) and the hand-over: lend_services → initialize_services(services=loan) → give_services (no turn while a manager holds services it does not own); service detection, tool assembly; context_budget/root_agent_name; the usage ledgers (usage: the open conversation's, usage_of; _turn counts each turn in its conversation's and gives a run a cancel leaves open what it used) and side calls (_report_side_call: generate_simple's usage, its purpose from usage.side_call, summarize's tool, on_session_end's memory_extraction outside any turn, recorded in its conversation's ledger and, in a turn, reported through its live events, never to a turn that has ended: turn_has_ended); summarize and fact extraction: a prompt over the default model's room, at the resolved max_tokens, cut in the middle, never under MIN_PROMPT_ROOM, _fit_prompt; the memory index behind the forwards _memory_index_now/_memory_index_cached/_memory_index_cap/_forget_memory_index and _index_snapshots (memory_index.py's MemoryIndex; the release clears it)) │ │ ├── factory.py # create_workflow_manager_from_settings (_BACKENDS: orchestrator → "module:Class" + extra, imported when chosen; orchestrator=: another backend than the settings'; session_store=: the store a manager is built for, BaseWorkflowManager.session_store, the settings' by default; subagents=: the SubAgentPolicy the manager gets, checked before a backend is imported); orchestrator_of; check_backend (an unknown name, a missing extra) -│ │ ├── session_readers.py # SessionReader: a backend's stored conversations read without its manager (list/info/exists/delete/aclose, rows naming the backend), opened from the settings and a store (open_session_reader: the backend's own session code, adk/sessions.py::open_sessions and deepagents/sessions.py::open_sessions, imported on a worker thread; no agents, models or services; a sqlite store not made yet reads empty and is not made, Deep Agents not even imported for it; a database without its backend's tables, looked at read-only, reads empty, nothing written to it: no table, no journal mode); none for the memory store or LangGraph; ImportError (the install hint) for a missing extra; reader_backends +│ │ ├── session_readers.py # SessionReader: a backend's stored conversations read without its manager (list/info/exists/delete/aclose, rows naming the backend; delete deletes what the manager's does, ADK's sub-agent transcripts with the conversation), opened from the settings and a store (open_session_reader: the backend's own session code, adk/sessions.py::open_sessions and deepagents/sessions.py::open_sessions, imported on a worker thread; no agents, models or services; a sqlite store not made yet reads empty and is not made, Deep Agents not even imported for it; a database without its backend's tables, looked at read-only, reads empty, nothing written to it: no table, no journal mode); none for the memory store or LangGraph; ImportError (the install hint) for a missing extra; reader_backends │ │ ├── service_registry.py # get_service/require_service + ContextVar registry; the registry keys and KNOWN_SERVICE_KEYS, read from services.py's table │ │ ├── services.py # The services a manager builds: SERVICES, one ServiceSpec each (key, build, close, tools, declarable, always, built_with, rebind; builders import lazily); ServiceSet: one manager's (build_into, publish, carried, release, tool_map, not_owned: borrowed or given away, never closed there); ServiceLoan: a hand-over between managers (rebind: the engine's workflow/per_call, the KB's summarizer) │ │ ├── memory_index.py # MemoryIndex: the memory index the root's requests carry, one snapshot per conversation (now: taken once, off the event loop; cached: never reading; forget: /resume, a summary and /compact; clear: the release; cap: memory_index_max_bytes, or a tenth of the root's budget: MEMORY_INDEX_BUDGET_SHARE, MEMORY_INDEX_MIN_BYTES); reads the manager's settings, memory store, the root's memory tools (_root_memory_tools) and its room live, through callables, and takes a snapshot at the manager's _memory_index_cap (limit=), so a subclass's cap is the one asked; imports no backend @@ -75,23 +75,23 @@ agentic-cli/ │ │ ├── tool_errors.py # tool_error_result / unknown_tool_result: ADK's error shapes, for ADK and Deep Agents │ │ ├── tool_output.py # cap_tool_result: a result over tool_result_max_chars cut (head and tail, a note; a string holding a JSON object cut as its dict and given back as JSON, json_object), its full output saved in ./.{app_name}/tool-output/ for read_file; both backends │ │ ├── summary_prompt.py # SUMMARY_PROMPT (LangChain's DEFAULT_SUMMARY_PROMPT, copied with its MIT notice: ADK runs without LangChain), SUMMARY_PREFIX, summary_prompt/with_focus; both backends -│ │ ├── sessions.py # SessionRef; SessionInfo (a session list's row; backend: a reader's rows and the CLI's name theirs) and session_title; ConversationChangedError (ADK's stale session); the active turn; the active sub-agent run (RunRef, root_run, get_active_run: None in the root's own calls); the active tool call (ToolCallRef); the turn's span (open_turn_scope/close_turn_scope, turn_has_ended: a task that outlived its turn); instance_of (a run's instance, None for the root's: a job's started_by) +│ │ ├── sessions.py # SessionRef; SessionInfo (a session list's row; backend: a reader's rows and the CLI's name theirs) and session_title; ConversationChangedError (ADK's stale session); the active turn; the active sub-agent run (RunRef, root_run, get_active_run: None in the root's own calls); the active tool call (ToolCallRef); the turn's span (open_turn_scope/close_turn_scope, turn_has_ended: a task that outlived its turn; current_turn_scope: the span itself, the identity of what is kept for one turn); instance_of (a run's instance, None for the root's: a job's started_by) │ │ ├── mcp.py # MCPServerConfig → to_adk_toolset / to_langchain_connection │ │ ├── permissions/ # Framework-independent capability engine │ │ │ ├── engine.py # PermissionEngine (deny-wins, default-ASK; uncontained=, per_call=: capabilities approved for each call) │ │ │ ├── capabilities.py # Capability, EXEMPT │ │ │ ├── matchers.py # PathMatcher, URLMatcher, ShellMatcher, StringGlobMatcher │ │ │ └── rules.py, store.py, prompt.py (build_request(run=): a sub-agent's prompt opens with its run; is_permission_request: by its perm- id) -│ │ ├── agents/ # Sub-agents: runs.py: the RUN_* statuses, RunRecord, AgentRuns (a manager's runs by conversation: run_for names - and its run #1 per (conversation, parent run, call id), a new one once it ended; 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, its AGENT_RUN start and end observed and reported, the backend's hook (RunHook: AgentRun → RunAnswer) run in a task of its own with the run active and no tool call, the end by the answer (completed, partial for a cut, refused, failed for an error or a raise, with one recoverable ERROR failed: , or RunFailed's own words), interrupted on a cancel; the envelope as the result), DelegationRequest, AgentRun, RunAnswer, RunFailed, started_by; outcome.py: a sub-agent's refused or cut answer (outcome_of, the refusal notice as Deep Agents 0.7.34 words it, cut_off, cut_off_warning, OPENAI_REFUSAL_PREFIX: how ADK's OpenAI adapters word a refusal); policy.py: SubAgentPolicy (max_active, max_runs_per_turn, limits) and AgentLimits (max_model_calls, timeout, max_tokens; over: a type's limits over the policy's, field by field, None taking the base's), DEFAULT_LIMITS (100 model calls), frozen and checked as they are made (a ValueError naming the field), as_policy (the one reading of a subagents= argument: a TypeError for anything but a policy or None); brief.py: BRIEF_FIELDS, Brief, BriefError, read_brief (a task call's agent type and brief, against the types its caller may start: the error texts), task_message (a run's first message, a section per filled field; an inheriting type's ends with INHERITED_CONTEXT_NOTE), task_parameters and task_description (task's schema and description, the same for both backends; limit_sentences: the limits it states); envelope.py: envelope (a delegation run's result: success only for completed, a one-line error, cancelled_by for a cancelled run), read_envelope (a dict or its JSON text, else None; never raises), the limit and interrupted error texts +│ │ ├── agents/ # Sub-agents: runs.py: the RUN_* statuses, RunRecord, AgentRuns (a manager's runs by conversation: run_for names - and its run #1 per (conversation, parent run, call id), a new one once it ended; number_from: past the instances a conversation's store keeps, a count never lowered; observe records AGENT_RUN under the turn it is reported in; interrupt_open; a record's usage: what the run used, by model, from its end event or the ledger), run_title, result_head, run_instance and run_number (the one reader of a run id: researcher-2#1's instance and number), run_label (how a dialog names a run: researcher-2 (researcher, run 1)), SUBAGENT_ERROR_PREFIX (ADK's old words for a failed delegation, kept for callers), show_as_delegation(result, envelope) (a delegation's TOOL_RESULT shown alike on both backends: the result's first line, or Failed: ; metadata["result"] the envelope); a record's brief, started_by, mode and cancelled_by; delegate.py: Delegations (delegate(DelegationRequest) → Delegated: the one place a run starts and ends, on both backends: the brief read against the caller's own sub-agents, the run named (a turn's first run past the instances its conversation's store keeps: stored=, asked once per conversation per turn, again after a failed or stopped ask), its AGENT_RUN start and end observed and reported, the backend's hook (RunHook: AgentRun → RunAnswer) run in a task of its own with the run active and no tool call, the end by the answer (completed, partial for a cut, refused, failed for an error or a raise, with one recoverable ERROR failed: , or RunFailed's own words), interrupted on a cancel; the envelope as the result), DelegationRequest, AgentRun, RunAnswer, RunFailed, started_by; outcome.py: a sub-agent's refused or cut answer (outcome_of, the refusal notice as Deep Agents 0.7.34 words it, cut_off, cut_off_warning, OPENAI_REFUSAL_PREFIX: how ADK's OpenAI adapters word a refusal); policy.py: SubAgentPolicy (max_active, max_runs_per_turn, limits) and AgentLimits (max_model_calls, timeout, max_tokens; over: a type's limits over the policy's, field by field, None taking the base's), DEFAULT_LIMITS (100 model calls), frozen and checked as they are made (a ValueError naming the field), as_policy (the one reading of a subagents= argument: a TypeError for anything but a policy or None); brief.py: BRIEF_FIELDS, Brief, BriefError, read_brief (a task call's agent type and brief, against the types its caller may start: the error texts), task_message (a run's first message, a section per filled field; an inheriting type's ends with INHERITED_CONTEXT_NOTE), task_parameters and task_description (task's schema and description, the same for both backends; limit_sentences: the limits it states); envelope.py: envelope (a delegation run's result: success only for completed, a one-line error, cancelled_by for a cancelled run), read_envelope (a dict or its JSON text, else None; never raises), the limit and interrupted error texts │ │ ├── adk/ # ADK orchestrator -│ │ │ ├── manager.py # GoogleADKWorkflowManager (the agents built from configs or, adk_config_path, by ADK from a native YAML (library-only: no BaseCLIApp starts one; loaded once per manager at the first _validate_agent_graph (_native_root: the settings' keys exported first; a retry, a model switch and a start after cleanup build on the same tree, whose toolsets the closed runner left reusable), its agents' models resolved leniently in _resolve_extra_models, the base's hook, its registered tools' services detected; configs passed with it ignored, adk_native_configs_ignored): the only difference; _do_initialize builds the app from the tree alone, _build_app → ADKBuild, through the hooks _plugin_chain (the whole chain, top to bottom, its head _init_plugins), _compaction_config (None for a root without a budget), _context_cache_config, _agent_model_refs; the event processor built from the build; a config-built agent's prompt as an instruction provider, sent as written: no `{name}` state injection; _compact_turn: ADK's compaction once, in the base's compact turn; supports_compact False once built for a root without a budget (_no_compact_support says why); the job resume hooks: _conversation_exists (the session read without its events, num_recent_events=0), _deliver_job_notice (the notice, for every app); _run_config: the agents' synchronous tools run in ADK's tool thread pool, 8 workers; _run_and_stream: a run that fails yields the turn's one ERROR, last, none after an ERROR already yielded; the agents: _create_agents builds each config's agent on its own (_agents, by name; no ADK sub_agents), a delegating one with a TaskTool (its own tool named task: AgentGraphError); a runner per sub-agent type (_agent_runners: NoAfterTurnCompactionRunner on App(name=child_app(app_name), root_agent=the type's agent, plugins=_agent_plugin_chain(agent), the app's context cache, no compaction) over the session service, closed with the main runner by _detach_backend, rebuilt by every initialization); _run_agent, the base's hook: the run's child session (_child_session: run.state, an inheriting run's copied events; one an earlier process left, replaced), 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) +│ │ │ ├── manager.py # GoogleADKWorkflowManager (the agents built from configs or, adk_config_path, by ADK from a native YAML (library-only: no BaseCLIApp starts one; loaded once per manager at the first _validate_agent_graph (_native_root: the settings' keys exported first; a retry, a model switch and a start after cleanup build on the same tree, whose toolsets the closed runner left reusable), its agents' models resolved leniently in _resolve_extra_models, the base's hook, its registered tools' services detected; configs passed with it ignored, adk_native_configs_ignored): the only difference; _do_initialize builds the app from the tree alone, _build_app → ADKBuild, through the hooks _plugin_chain (the whole chain, top to bottom, its head _init_plugins), _compaction_config (None for a root without a budget), _context_cache_config, _agent_model_refs; the event processor built from the build; a config-built agent's prompt as an instruction provider, sent as written: no `{name}` state injection; _compact_turn: ADK's compaction once, in the base's compact turn; supports_compact False once built for a root without a budget (_no_compact_support says why); the job resume hooks: _conversation_exists (the session read without its events, num_recent_events=0), _deliver_job_notice (the notice, for every app); _run_config: the agents' synchronous tools run in ADK's tool thread pool, 8 workers; _run_and_stream: a run that fails yields the turn's one ERROR, last, none after an ERROR already yielded; the agents: _create_agents builds each config's agent on its own (_agents, by name; no ADK sub_agents), a delegating one with a TaskTool (its own tool named task: AgentGraphError); a runner per sub-agent type (_agent_runners: NoAfterTurnCompactionRunner on App(name=child_app(app_name), root_agent=the type's agent, plugins=_agent_plugin_chain(agent), the app's context cache, no compaction) over the session service, closed with the main runner by _detach_backend, rebuilt by every initialization); _run_agent, the base's hook: the run's child session (_child_session: run.state, an inheriting run's copied events; never one the store keeps, whose instance numbering goes past: ADK's create_session refuses it, and the run fails), _stored_instances (the base's hook: the highest instance number of each type the conversation's child sessions keep), the type's runner on the task message with an abort signal set before it is closed, a run-mode ADKEventProcessor, the raw log's records reported as they come (_report_raw_log); a model's failure raised as the provider's (_plugin_cause), an overflow RunFailed, a reply that is no answer RunAnswer(error=), the shared keys it changed read back) │ │ │ ├── build.py # ADKBuild (root, reply_agents, plugins, compaction, cache, models); load_native_root (from_config at validation; what ADK cannot load, wrapped as AgentGraphError naming the file, ADK's error the cause; a root that is not an LlmAgent, a name used twice in the tree and a task-mode agent refused, AgentGraphError naming it; ensure_direct_anthropic); what the run reads of any tree: reply_agents (the root and the chat-mode agents it can transfer to), own_after_tool_agents (left out by the cap) │ │ │ ├── task_tool.py # TaskTool: the framework's task on ADK (a BaseTool; its declaration task_parameters' JSON schema, parameters_json_schema; its description task_description; bound to the task declaration, an exact TaskTool only): a call → Delegations.delegate, the run's shared-key changes written to the caller's state, the envelope returned as JSON text (ADK's OpenAI Responses adapter sends only a dict's result); SHARED_KEYS (plan, tasks, the outside-content mark); inherited_events (an inheriting run's history: the session's root-visible events, copied) │ │ │ ├── compaction.py # AgentCliSummarizer (main agent only; summary_range, render_events; its usage normalized, timed and recorded in the conversation's ledger, ledgers, as soon as the call answers: an empty summary's too; on_written: a summary written drops the conversation's memory index snapshot), MainAgentPlugin (the running agent, first in every chain), NoAfterTurnCompactionRunner, compact_session │ │ │ ├── fit_guard_plugin.py # FitGuardPlugin: a request over its agent's budget has its oldest turns left out (drop_turns); what opens the conversation, the memory index then a summary (protected_head, never dropped), folded into the next user text (fold_summary); request_as_seen │ │ │ ├── overflow_plugin.py # OverflowPlugin (OVERFLOW_PLUGIN_FAILED: ADK's wrapper of its errors, which the manager unwraps): a provider's overflow summarized (the root; the retry: the summary and the turns it kept) or trimmed, retried once (the retry timed around its own request: call_clock.mark_latency), then CONTEXT_OVERFLOW: overflow_message for an agent that replies (reply_agents), subagent_overflow_message for a sub-agent's run (root None on its runner), which fails it │ │ │ ├── memory_index_plugin.py # MemoryIndexPlugin: the conversation's memory index first in the root's requests (before the overflow handler and the fit guard, which keep and fold it) -│ │ │ ├── sessions.py # A conversation's row in its session state (agentic_cli.title, agentic_cli.turns), saved with each user turn (run_async(state_delta=)); typed_prompts; ServiceSessions: the session hooks over a session service (the manager's and its reader's); make_session_service, session_db_url; open_sessions (a reader's store: empty without ADK's sessions table, looked at read-only); CHILD_APP_SUFFIX, child_app (--agents: the sub-agent runs' app, which no conversation list reads), child_session_id (/, a ValueError past ADK's 128 characters) +│ │ │ ├── sessions.py # A conversation's row in its session state (agentic_cli.title, agentic_cli.turns), saved with each user turn (run_async(state_delta=)); typed_prompts; ServiceSessions: the session hooks over a session service (the manager's and its reader's); make_session_service, session_db_url; open_sessions (a reader's store: empty without ADK's sessions table, looked at read-only); CHILD_APP_SUFFIX, child_app (--agents: the sub-agent runs' app, which no conversation list reads), child_session_id (/, a ValueError past ADK's 128 characters), delete_children (a conversation's child sessions, events and all: ServiceSessions.delete runs it after the conversation's own delete, whatever that found), stored_instances (the highest instance number of each type a conversation's child sessions keep) │ │ │ ├── event_processor.py # ADKEventProcessor (each call's LLM_USAGE normalized by its model's provider kind, kinds (an agent without one: an unknown kind's), with its latency (call_clock's mark), and recorded in the conversation's ledger before on_event, a run's end with what it used; reply_agents: the agents whose text is the reply; another's, a sub-agent's, marked as activity; a reply that is no answer, NO_ANSWER_CODES, → the turn's ERROR; a failed result, an MCP isError one too, → a failed TOOL_RESULT naming its error, as on Deep Agents; TASK_PROGRESS after a tool call that changed the task list, its state delta's tasks, as on Deep Agents: start_turn forgets the list reported; every event names its run, the agent's own at depth 0, TOOL_CALL and TOOL_RESULT their tool_call_id; a task call's TOOL_RESULT shown as on Deep Agents, from its envelope: show_as_delegation; run=: a processor for one sub-agent run, on its child session, every event that run's, a sub-agent's text activity, no TASK_PROGRESS (the root's reports the list as the run returns), its last answer with text, its outcome mark and its failure kept (answer, outcome, failure: an overflow, a reply that is no answer but an empty one) for _run_agent) │ │ │ ├── model_factory.py # build_adk_model: ResolvedModel → ADK model, config, planner │ │ │ ├── openai_compatible.py # OpenAICompatibleLlm (the configured providers: openrouter and openai_compatible kinds; reasoning text; OpenRouter's reasoning_details kept on the thought part (thought_signature, with the model that wrote them) and sent back on that turn's assistant message to that model only; a Chat Completions refusal, streamed or not, as the text ADK's Responses adapter makes of one, "OpenAI refusal: "; no field sent as null; OpenRouter's cache writes, which ADK's usage mapping drops, kept on the usage as cache_creation_input_tokens) @@ -265,7 +265,7 @@ Workflow: - **Code that may run on the host is approved per call**: CPython has no in-process sandbox, so `execute_python` runs inside the OS sandbox or not at all by default (`os_sandbox_strict` true: no backend, a failed wrap, or a sandbox tool that fails as it starts (the runner's first stderr line, `_STARTED_MARKER`, never came) is a refusal that keeps its cause and ends with `executor.how_to_run`: sandbox-exec, bwrap and Ubuntu 24.04's user namespaces, none on Windows, and the opt-out where it lives, `exec_policy.sandbox_opt_out`: `~/.{app_name}/settings.json` or the env variable, since the project file and `/settings` cannot set it), and the module set is chosen from the path a call takes (`executor.py::_choose_run`, then `validate_code(allowed_modules=)`). The engine never imports `tools/`: `BaseWorkflowManager` passes `PermissionEngine(uncontained=tools.exec_policy.uncontained_exec_capabilities)`, called with the settings at each check (a settings change applies at once). For a capability it names, `engine.unstorable_reason` is `UNCONTAINED` (the one decision, shared with the prompt: only "Allow once" and "Deny", with its note), and `_evaluate` skips allow rules from grants (`SESSION`, and `PROJECT`, the user's `project_grants.json`), so a grant from when the code ran contained approves nothing; a `USER` rule still applies. A prompt for `*.exec` shows all of the code (the dialog body scrolls). - **No harness-level turn replay**: ADK persists a turn's input during invocation setup, and Deep Agents' checkpointer at the turn's first step, so the CLI never re-invokes an event source. Retries belong to the provider client (`HttpRetryOptions`). `MessageProcessor` returns a typed `TurnResult`. A turn that fails yields one `ERROR` and returns, on both backends (the base `process()`'s contract; `WorkflowEvent.turn_failed`: the error's text, `rate_limited`, `error_type`); an `ERROR` the turn already yielded that is not recoverable is its one; a cancel still raises, and a turn that cannot start (initialization, admission, or its conversation cannot be read) raises before any event. The CLI says a rate limit from the event as it does from a manager that raises. - **Interrupted calls**: Ctrl+C stops the whole turn (loop, model calls, tools, sub-agents), and every call the model made gets exactly one result (`workflow/interrupts.py`, the texts and `OpenCalls`, each manager's record, kept by conversation and by the run that made each call (the root's own, or a sub-agent's: a provider that numbers its call ids per agent gives a sub-agent's call its parent's delegation's id): a call's result as it finished, a call `asking` at its permission prompt, both gates marking it; a conversation whose turn the user cancelled): a finished call keeps its result, a running one or a delegation is `INTERRUPTED_BY_USER`, one at its prompt `NOT_RUN`, one whose job was submitted the job's state (`job_started`); a cancel with no call open leaves `MARKER` as the main agent's reply; a call nothing answered (a crash, an old session) is `INTERRUPTED`. On ADK the turn runs with `abort_signal`, set by `live_events.merged(on_stop=)` before the runner is cancelled, so ADK seals the invocation in its own branches; `merged` waits for its source to close, a repeated cancel too (up to `STOP_GRACE`), and `process()`/`resume_with_job_result()` close their inner generators with `aclosing`, so a run never outlives its turn. `adk/interrupted_calls_plugin.py::InterruptedCallsPlugin` (before `ToolResultCapPlugin`, every app) sets the active tool call around each call (`before_tool_callback`, so a question marks it `asking`), records results with their `state_delta`/`artifact_delta` in `after_tool_callback` (not a long-running starter's `None`: its job answers it), keeps the cap's cut of one (`ToolResultCapPlugin.on_cut`, so a seal sends that cut and its full output is saved once) and rewrites the seals (`error_code` `INVOCATION_ABORTED`, contract-tested) in `on_event_callback`, carrying those deltas, each seal answered from the record of the active run (a sub-agent run's runner stops, and seals its child session, in the run's own task). ADK's seals pair a result with a call by id alone, so a call whose id another call's result used, on another branch of the session (a native ADK YAML app's agents), is left open: the manager answers those as the stopped turn ends, before it clears the record, the same way (`_answer_unsealed`, shielded; `unsealed`, once ADK's seals are written), so a call that finished keeps its result. `left_open` answers leftovers when `process()` starts (every app: a task-mode agent's delegation, which ADK keeps open on purpose, is refused at build, and ADK's client calls for a human, `adk_request_confirmation`/`_credential`/`_input`, are answered as interrupted, since the manager offers no way to answer them), a result pairing with a call on its own branch only; one a stop left because its answers could not be written is answered `INTERRUPTED_BY_USER` (the manager records the stop). On Deep Agents `InterruptedCallsMiddleware` takes `PatchToolCallsMiddleware`'s place, first in every stack: it records each final `ToolMessage` with the rest of its `Command` update (outermost tool wrapper) and answers open calls in `before_agent`, returning those updates too; the root adds `MARKER` before the new input when the message before it is no reply (a `HumanMessage` or a tool result). Background jobs are not part of the turn: they keep running. Nor is a synchronous tool's function (a sandbox cell, `compile_document`, `execute_python`): it runs in a worker thread on both backends (ADK's tool thread pool, LangChain's executor), which Python cannot stop, so its call is answered at once but the function runs on to its end, keeps its sandbox session busy (the session's next call waits for it) and holds the process's exit until it returns (the sandbox's cleanup stops a cell). So is a knowledge-base ingest's store step (`kb_ingest_text`, `kb_ingest_file`, `ingest_arxiv_paper`: `KnowledgeBase._store` runs `ingest_document` in `asyncio.to_thread`): a cancelled ingest is answered `INTERRUPTED_BY_USER` and still stores its document, so a model that retries it stores a second copy; a cancelled `sidecar` or `backfill_sidecars` keeps its lock or flag until its thread's call ends (`memory/kb/manager.py::_Threads`). -- **Session identity**: durable sessions are addressed by `SessionRef(app_name, user_id, session_id)` (`workflow/sessions.py`). Every session hook (`session_exists`/`list_sessions`/`session_info`/`delete_session`/`recent_messages`/`load_session`) takes an optional `user_id`, defaulting to `settings.default_user` only when the caller omits it. `list_sessions(limit=)` returns `SessionInfo` rows, newest first, and `session_info` one conversation's or None: the title is the first prompt (`session_title`), the turns what the user typed (a job's notice or resume, a delegated request and a summary are none), `updated` when it last changed. ADK keeps the title and the turns in two session-state keys saved with each user turn (`workflow/adk/sessions.py`, `run_async(state_delta=)`; a conversation from before them is read from its events and never written back, which would move it in the list), Deep Agents keeps them in a session index, a LangGraph store beside the checkpointer (`workflow/deepagents/sessions.py`: each row written as a turn starts, its input counted, then from the newest root checkpoint as it ends and after `/compact`, so a listing reads no checkpoint; a database from before the index scanned once per app and user), LangGraph knows only the id; ADK's `delete_session` looks the session up first, so an unknown id is False. Backends without a session store leave `supports_sessions` False, and the base hooks raise `NotImplementedError` rather than answering with a misleading `False`/`[]`. Deep Agents keys each conversation's checkpointer thread by the whole triple (`workflow/deepagents/sessions.py::thread_id`, `json.dumps([app_name, user_id, session_id])`) and stores it in each checkpoint's metadata, so the backfill's scan filters by app and user and keeps the root namespace; sub-agents are compiled with `checkpointer=False` and store none (an older version's sit under `tools:`, and `delete_session` removes them with the thread and the row, returning False for an unknown id). A backend's conversations are read without its manager through its `SessionReader` (`workflow/session_readers.py::open_session_reader`: the backend's own session code over its store, opened from the settings), so the CLI lists, opens and deletes the conversations of every installed backend (`cli/stored_conversations.py`): each row names its backend (`SessionInfo.backend`), and a conversation another backend keeps opens there (no index joins the stores, and an id two backends keep is two conversations). +- **Session identity**: durable sessions are addressed by `SessionRef(app_name, user_id, session_id)` (`workflow/sessions.py`). Every session hook (`session_exists`/`list_sessions`/`session_info`/`delete_session`/`recent_messages`/`load_session`) takes an optional `user_id`, defaulting to `settings.default_user` only when the caller omits it. `list_sessions(limit=)` returns `SessionInfo` rows, newest first, and `session_info` one conversation's or None: the title is the first prompt (`session_title`), the turns what the user typed (a job's notice or resume, a delegated request and a summary are none), `updated` when it last changed. ADK keeps the title and the turns in two session-state keys saved with each user turn (`workflow/adk/sessions.py`, `run_async(state_delta=)`; a conversation from before them is read from its events and never written back, which would move it in the list), Deep Agents keeps them in a session index, a LangGraph store beside the checkpointer (`workflow/deepagents/sessions.py`: each row written as a turn starts, its input counted, then from the newest root checkpoint as it ends and after `/compact`, so a listing reads no checkpoint; a database from before the index scanned once per app and user), LangGraph knows only the id; ADK's `delete_session` looks the session up first, so an unknown id is False. ADK keeps each sub-agent run's transcript in a child session of its conversation (`adk/sessions.py`: app `child_app(app_name)`, `--agents`, id `/`, the conversation's user), under an app no listing reads, so none lists or opens as a conversation (`list_sessions`, `session_info`, `session_exists`, a reader's, the CLI's look, `--continue`; `recent_messages` reads the conversation's own session); `ServiceSessions.delete` (the manager's `delete_session` and a reader's, so `/sessions --delete` and the memory store's `/new` too) deletes them, events and all, after the conversation's own delete and whatever that found (`delete_children`: `/` and no further `/`). Instances are numbered per manager, so a manager numbers a conversation's past the ones its store keeps (`_stored_instances`, the highest number of each type, read from the child session ids; `Delegations` asks it once per conversation per turn, before the turn's first run, and again after an ask that failed: another process may have run the conversation between two turns; `AgentRuns.number_from`, which never lowers a count): after a restart, a switch of backend or store, or another process's turns, the next run is never a second `researcher-1` (a model switch keeps the manager, and its numbering), and a stored transcript is never replaced (ADK's `create_session` refuses its id: the run fails). Deep Agents stores no sub-agent transcript, so its manager keeps the base's none. Backends without a session store leave `supports_sessions` False, and the base hooks raise `NotImplementedError` rather than answering with a misleading `False`/`[]`. Deep Agents keys each conversation's checkpointer thread by the whole triple (`workflow/deepagents/sessions.py::thread_id`, `json.dumps([app_name, user_id, session_id])`) and stores it in each checkpoint's metadata, so the backfill's scan filters by app and user and keeps the root namespace; sub-agents are compiled with `checkpointer=False` and store none (an older version's sit under `tools:`, and `delete_session` removes them with the thread and the row, returning False for an unknown id). A backend's conversations are read without its manager through its `SessionReader` (`workflow/session_readers.py::open_session_reader`: the backend's own session code over its store, opened from the settings), so the CLI lists, opens and deletes the conversations of every installed backend (`cli/stored_conversations.py`): each row names its backend (`SessionInfo.backend`), and a conversation another backend keeps opens there (no index joins the stores, and an id two backends keep is two conversations). - **Active turn**: the in-flight `(user, session)` is a `ContextVar` (`workflow/sessions.py::get_active_turn`), set with a token by `_workflow_context()`, which every turn enters through `_turn()` — concurrent turns on one manager stay isolated and nesting restores the outer turn. The tool call in progress is another (`get_active_tool_call()`, a `ToolCallRef(call_id, name)`), set by Deep Agents' `ActiveToolCallMiddleware`, innermost in the tool stack (after the gate and the error middleware, so only a call the gate let through runs as one); on ADK, `InterruptedCallsPlugin.before_tool_callback` sets it around each call (ADK's stand-in for an unknown tool name excepted) and its `after_tool_callback` resets it. The sub-agent run in progress is a third (`get_active_run()`, a `RunRef`; None in the root's own calls), set by `Delegations.delegate` in the run's own task (`workflow/agents/delegate.py`), on both backends, where the run's runner or graph runs (with no tool call active there): a sub-agent's model calls, tool calls, permission checks and questions see it. `JobManager.submit(resume_on_complete=True)` takes `call_id` from the active tool call when the tool passed none, and `call_name` when that is None too; every `submit` records the sub-agent run in progress as the job's `started_by` (`instance_of(get_active_run())`). - **Job notifications**: both backends tell a finished job through the base's `resume_with_job_result` (a template: the record names its conversation, a turn of it (`_turn`), the conversation there (`_conversation_exists`), the job's result read on a worker thread (`JobManager.result` takes the jobs directory's cross-process lock), the notice `job_notice`, told by the backend's `_deliver_job_notice`; `can_resume` makes the same checks without the turn), and the CLI resumes where `supports_job_resume` and `can_resume` say so. On ADK a finished job is told to the conversation (the root, or a native app's agent the root transferred it to) as one user-role text, `tools/jobs/resume.py::job_notice` (the Deep Agents notice below), whoever started it: its call already has a result (the root's "pending", or a sub-agent's job id), and a second result for the call itself made ADK's rearranger send the call, that result and nothing between, so the root answered without the turns since. A native ADK YAML app's job is told the same way (it used to answer its pending call as a `FunctionResponse`, and needed `record.call_id`); a call still open (a starter that returned nothing) is answered first (`_answer_left_open`). A sub-agent's long-running tools are not wrapped (`_build_agent` wraps the root's only): ADK pauses the whole invocation on a pending long-running call, inside a delegation too, so a sub-agent's starter returns the job id as an ordinary result. ADK's `recent_messages` leaves the notice out by its header, since ADK keeps no mark on a message. The CLI delivers only the jobs that wait for the current conversation, by one rule (`cli/waiting_jobs.py`) for the deliveries, the status bar's `↻N` and the line startup says: a finished job flagged `resume_on_complete` whose delivery is still `PENDING` (`JobRecord.awaiting_resume`: not one being delivered), that is this conversation's, or has none, or whose conversation is gone, `can_resume` saying so and no other installed backend's store keeping it (`waiting_jobs.opens_anywhere`, `BaseCLIApp._kept_elsewhere`) (those two told it is unavailable): another conversation's waits until it is opened, `/resume` (`resume_session`) telling them when `job_auto_resume` is on, startup only naming them (`_name_its_waiting_jobs`: outside the input handler Ctrl+C cannot stop a turn); the status bar's `↻N` counts them whatever the setting (`↻N: /jobs resume` when it is off; its `can_resume` answers kept 30 s, forgotten after `/sessions --delete`, a conversation `/new` drops on the memory store, or a new conversation on another backend). On Deep Agents a finished job's result cannot be the pending call's second result (the call already has its `pending` one, and Anthropic and OpenAI take one result per call), so `resume_with_job_result` runs a turn whose input is one `HumanMessage`: `tools/jobs/resume.py::JOB_NOTICE_HEADER`, the ask (`job_notice_ask`: for the root's own job `JOB_NOTICE_ASK`, tell the user what it means: without it a model may say nothing; for a sub-agent's, `JOB_NOTICE_ASK_FOR`, the same ask naming the sub-agent), then `job_result_payload(record, result)` as JSON, a line each (`job_notice`), marked `response_metadata={"agentic_cli": {"kind": "job_result", "job_id": ...}}` (`workflow/deepagents/sessions.py::job_notification`). No provider adapter sends that field; `recent_messages`, and so fact extraction, leaves the message out; the checkpoint keeps it for the model. The root agent receives every job, a sub-agent's too (its run ended when its `task` returned), and the notice names the sub-agent whose call started it (`JobRecord.started_by`, its instance, from the active run at submit; `job_notice_ask`: "A background job researcher-2 started has finished…", the root's own `JOB_NOTICE_ASK`). `can_resume` needs the record's session and user and the conversation's thread, not a call id. - **Resource ownership**: one release, `BaseWorkflowManager._release_resources` (cleanup, reinitialize and a failed initialization's rollback run it): it resets the base's state (`_initialized`, budgets, index snapshots, the catalog detached), takes the backend's closers from `_detach_backend()` (ADK: the runner, which closes the agents' MCP toolsets; Deep Agents: the agents' MCP sessions, handed over to a fresh `MCPSessions`) and `_detach_store()` (ADK: the session service; Deep Agents: the checkpointer, the session index and their connections), detaches the services through `_cleanup_managers` (the release's services hook: a backend's override runs; outside a release, as in LangGraph's cleanup, it closes them in place) and starts closing them on a worker thread (their closers block: `docker rm -f`, a kernel shutdown, the jobs directory's lock; on the loop they froze the app), then runs the closers (backend, store, catalog, then the services' close waited for last under a shield of its own: a hanging service close holds none of the rest, and a shutdown's cancel cancels no close not yet started) in one task awaited under a shield, each isolated (`_aclose_owned` for a duck-typed `aclose()`/`close()`): a cancel stops only the wait. The hooks are synchronous: one that returns an awaitable is closed and fails the release with a `TypeError`, after the rest is released. An override of `_release_resources` reads `self._keeping_store` to know whether a switch keeps the store. `cleanup()` is idempotent; `WorkflowController.close()` is the single shutdown path (cancel init → shut executor → clean manager). `reinitialize(preserve_sessions=True)` (a model switch) runs inside `_keeping(True)` (`_carrying_services` is its other name): the store is not detached and the services are carried, since session grants, sandbox kernels, jobs, knowledge bases and the conversations belong to the conversation, not the model, so neither the release nor a failed attempt's rollback closes them (a retry continues the conversation); the backend's own resources (ADK's runner, Deep Agents' MCP sessions) close and reopen. `_release_resources(keep_session_service=/keep_checkpointer=)` keeps the store, with a `DeprecationWarning`, until 0.8.0. LangGraph keeps its own `cleanup`/`reinitialize`. A run's services can move to a manager of either backend: `loan = old.lend_services()` (the table's services `old` owns, but itself), `await new.initialize_services(services=loan)` (borrowed, published, only what is missing built; no release of `new` closes them, so a failed, cancelled or abandoned start leaves `old` owning and using them), `await old.give_services(loan)` (between turns: inside one of `old`'s it raises `RuntimeError`; under `old`'s lifecycle and turn locks and `new`'s lifecycle lock: `new` owns them, each row's `rebind` moves the permission engine's `workflow`/`per_call` and the knowledge base's summarizer to it, and `old`'s release drops them unclosed). A manager holding services it does not own runs no turn (`_turn_admission` raises `RuntimeError`): the engine's per-call check reads its owner's outside-content marks, so `new` runs none before the give and `old` none after it until its release. The CLI's `WorkflowController.switch_backend` (a conversation opened or started on another backend) hands the run's services over so: lend, start, give, publish at once, release the old one. diff --git a/README.md b/README.md index d12a21ef..3964e5f7 100644 --- a/README.md +++ b/README.md @@ -1351,11 +1351,12 @@ reviewer = AgentConfig(name="reviewer", prompt="Check what was said.", agent built from a config is offered `transfer_to_agent`; each sub-agent type runs on a runner of its own, each run on a child session (app `--agents`, id `/`), which - `/sessions` never lists; an inheriting run's child session starts with - the conversation's events. **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. + `/sessions` never lists and which is deleted with its conversation; an + inheriting run's child session starts with the conversation's events. + **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 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 diff --git a/src/agentic_cli/workflow/adk/manager.py b/src/agentic_cli/workflow/adk/manager.py index 8c6d5dc8..7829e14e 100644 --- a/src/agentic_cli/workflow/adk/manager.py +++ b/src/agentic_cli/workflow/adk/manager.py @@ -72,6 +72,7 @@ child_app, child_session_id, make_session_service, + stored_instances, turn_state, ) from agentic_cli.workflow.adk.task_tool import SHARED_KEYS, TaskTool @@ -1479,6 +1480,8 @@ async def _run_agent(self, run: AgentRun) -> RunAnswer: RunFailed: Its request no longer fits its model's window (the overflow handler's answer). 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``). """ @@ -1540,23 +1543,33 @@ async def _child_session( ) -> None: """Make ``run``'s child session: the state it starts from, and an inheriting run's history. - An instance's session left by an earlier process (instances are - numbered per manager, so a new one numbers ``researcher-1`` again) - is replaced: nothing reads it. + Its instance is new to the conversation's store: instances are + numbered past the ones it keeps (``_stored_instances``). One it + keeps all the same is never replaced: ADK refuses to make it + (``AlreadyExistsError``), and the run fails with that. """ service = self._session_service - stale = await service.get_session( - app_name=app, user_id=user_id, session_id=session_id, - config=GetSessionConfig(num_recent_events=0), - ) - if stale is not None: - await service.delete_session(app_name=app, user_id=user_id, session_id=session_id) session = await service.create_session( app_name=app, user_id=user_id, session_id=session_id, state=dict(run.state) ) for event in run.history or (): await service.append_event(session, event) + async def _stored_instances(self, conversation: SessionRef) -> dict[str, int]: + """The highest instance number of each type ``conversation``'s child sessions keep. + + The base's hook (``Delegations`` asks it once per conversation per + turn): another manager's runs (before a restart or a switch of + backend or store, or another process's between two turns) are in + the store, and this one numbers past them. + """ + if self._session_service is None: + return {} + return await stored_instances( + self._session_service, conversation.app_name, conversation.user_id, + conversation.session_id, + ) + def _report_raw_log(self) -> None: """Report what the raw LLM log holds (a sub-agent run's calls) to the turn's live events. diff --git a/src/agentic_cli/workflow/adk/sessions.py b/src/agentic_cli/workflow/adk/sessions.py index bb39648b..ea05ebd6 100644 --- a/src/agentic_cli/workflow/adk/sessions.py +++ b/src/agentic_cli/workflow/adk/sessions.py @@ -30,7 +30,10 @@ ``child_session_id(conversation, instance)`` (``/``), the conversation's user. Under its own app name it never lists as a conversation. ADK keys a session by at most ``MAX_KEY`` characters, so a -longer id is refused before anything is stored. +longer id is refused before anything is stored. A conversation's children +are deleted with it (``delete_children``: ``ServiceSessions.delete``, the +manager's and its reader's), and each turn numbers its instances past the +ones they keep (``stored_instances``), so none is ever another run's. """ from __future__ import annotations @@ -82,6 +85,76 @@ def child_session_id(conversation: str, instance: str) -> str: return session_id +async def _children( + service: "BaseSessionService", app_name: str, user_id: str, conversation: str +) -> list[str]: + """The ids of ``conversation``'s child sessions, ``user_id``'s, in + ``app_name``'s child app. + + Each is ``/``, an instance id holding no ``/``: + a conversation whose own id goes on past a ``/`` (``s/x``) has children + of its own, which are not ``s``'s. Read with ADK's public listing, which + returns each session without its events. + """ + prefix = f"{conversation}/" + listed = await service.list_sessions(app_name=child_app(app_name), user_id=user_id) + return [ + session.id for session in getattr(listed, "sessions", None) or () + if session.id.startswith(prefix) and "/" not in session.id[len(prefix):] + ] + + +async def delete_children( + service: "BaseSessionService", app_name: str, user_id: str, conversation: str +) -> int: + """Delete ``conversation``'s child sessions: its sub-agent instances' transcripts. + + Every session of ``app_name``'s child app (``child_app``) that is + ``user_id``'s and ``conversation``'s (``/``); + their events go with them (ADK's session store deletes a session's + events with it). What a conversation's delete leaves of it otherwise. + + Args: + service: The session service the conversation is in. + app_name: The conversation's app (not the child app). + user_id: The conversation's user. + conversation: The conversation's id. + + Returns: + How many it deleted. + """ + children = await _children(service, app_name, user_id, conversation) + for session_id in children: + await service.delete_session( + app_name=child_app(app_name), user_id=user_id, session_id=session_id + ) + return len(children) + + +async def stored_instances( + service: "BaseSessionService", app_name: str, user_id: str, conversation: str +) -> dict[str, int]: + """The highest instance number of each agent type ``conversation``'s child sessions keep. + + Read from their ids (``/-``, ``AgentRuns``' + instance ids): what another manager ran there (before a restart, or in + another process between two turns), which this one numbers past. An id + that names no such instance is left out. + + Args: + service: The session service the conversation is in. + app_name: The conversation's app (not the child app). + user_id: The conversation's user. + conversation: The conversation's id. + """ + counts: dict[str, int] = {} + for session_id in await _children(service, app_name, user_id, conversation): + agent, _, number = session_id.rpartition("/")[2].rpartition("-") + if agent and number.isascii() and number.isdigit(): + counts[agent] = max(counts.get(agent, 0), int(number)) + return counts + + def typed_prompts(events: list["Event"]) -> list[str]: """The texts the user typed, oldest first.""" prompts: list[str] = [] @@ -227,11 +300,13 @@ async def row_of(session_id: str) -> SessionInfo | None: return rows async def delete(self, ref: SessionRef) -> bool: - """Delete ``ref``'s session; False if there was none. + """Delete ``ref``'s session and its sub-agents' transcripts; False if there was none. ADK's own delete answers nothing, for an unknown id too, so the session is looked up first, without its events - (``num_recent_events=0``). + (``num_recent_events=0``). Its child sessions (``delete_children``) + are deleted after it, whatever the look found: a conversation + already gone may have left some. The answer is the conversation's. """ from google.adk.sessions.base_session_service import GetSessionConfig @@ -239,12 +314,12 @@ async def delete(self, ref: SessionRef) -> bool: app_name=ref.app_name, user_id=ref.user_id, session_id=ref.session_id, config=GetSessionConfig(num_recent_events=0), ) - if stored is None: - return False - await self._service.delete_session( - app_name=ref.app_name, user_id=ref.user_id, session_id=ref.session_id, - ) - return True + if stored is not None: + await self._service.delete_session( + app_name=ref.app_name, user_id=ref.user_id, session_id=ref.session_id, + ) + await delete_children(self._service, ref.app_name, ref.user_id, ref.session_id) + return stored is not None def session_db_url(settings: Any, store: str) -> str | None: diff --git a/src/agentic_cli/workflow/agents/delegate.py b/src/agentic_cli/workflow/agents/delegate.py index 139865d3..f4a67445 100644 --- a/src/agentic_cli/workflow/agents/delegate.py +++ b/src/agentic_cli/workflow/agents/delegate.py @@ -9,8 +9,11 @@ a brief that cannot start a run is the call's error result, and nothing else happens (no run, no record, no event); - names the run (``AgentRuns.run_for``: its instance ``-`` and its run - ``#1``, under the caller's run) and reports its ``AGENT_RUN`` - ``started``: the title, the call, the brief, who started it, ``blocking``; + ``#1``, under the caller's run; a turn's first run is numbered + past the instances its conversation's store keeps, which ``stored`` says + once per conversation per turn) and reports its ``AGENT_RUN`` + ``started``: the title, the call, the brief, who started it, + ``blocking``; - runs it through the backend's hook (``BaseWorkflowManager._run_agent``) in an asyncio task of its own, in which the run is the active run (``get_active_run``) and no tool call is (``get_active_tool_call``): the @@ -65,6 +68,7 @@ from agentic_cli.workflow.sessions import ( RunRef, SessionRef, + current_turn_scope, get_active_turn, set_active_run, set_active_tool_call, @@ -172,6 +176,9 @@ class Delegated: RunHook = Callable[[AgentRun], Awaitable[RunAnswer]] +#: How many instances of each type a conversation's store already keeps, by +#: type: the highest instance number (``BaseWorkflowManager._stored_instances``). +StoredInstances = Callable[[SessionRef], Awaitable[Mapping[str, int]]] class RunFailed(Exception): @@ -201,6 +208,12 @@ class Delegations: 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. + 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 + named, so what another manager ran there (before a restart, or + in another process between two turns) is numbered past. None: + every conversation is numbered from 1. """ def __init__( @@ -211,12 +224,20 @@ def __init__( types: Mapping[str, AgentConfig], hook: RunHook, ledgers: UsageLedgers | None = None, + stored: StoredInstances | None = None, ) -> None: self._runs = runs self.policy = policy self._types = dict(types) self._hook = hook self._ledgers = ledgers + self._stored = stored + # Each conversation's turn its stored instances were last read in + # (its span, ``current_turn_scope``: held here, so no later turn's + # can be the same object), and the lock a turn's parallel first runs + # wait at while one reads them. + self._numbered: dict[SessionRef, object] = {} + self._numbering = asyncio.Lock() def sub_agents(self, agent: str) -> dict[str, AgentConfig]: """The types ``agent`` may start, by name, in its ``sub_agents``' order.""" @@ -236,6 +257,7 @@ async def delegate(self, request: DelegationRequest) -> Delegated: except BriefError as error: return Delegated(result={"success": False, "error": str(error)}, state={}, run=None) conversation = get_active_turn() + await self._number_past_stored(conversation) ref = self._runs.run_for(conversation, request.caller, request.call_id, config.name) self._emit(WorkflowEvent.agent_run( ref, RUN_STARTED, call_id=request.call_id, title=run_title(brief.title), @@ -282,6 +304,39 @@ async def delegate(self, request: DelegationRequest) -> Delegated: result = envelope(ref, RUN_COMPLETED, result=answer.text, partial=partial) return Delegated(result=result, state=dict(answer.state), run=ref) + async def _number_past_stored(self, conversation: SessionRef | None) -> None: + """Number ``conversation``'s instances past the ones its store keeps. + + Asked once per conversation per turn (``stored``), before the turn's + first run is named; the turn's parallel first runs wait for that one + ask. Each turn asks again: between two turns another process may + have run the conversation (it holds it while its turn runs: + ``ConversationLock``), and ``AgentRuns.number_from`` never lowers a + count. A store that cannot be read is warned of in the log and asked + again at the next run, and this one is numbered from what the + manager knows (a stored instance it meets is its backend's to + refuse); a cancel leaves it to be asked again too. With no turn's + span open (``current_turn_scope``), every run asks. + """ + if self._stored is None or conversation is None: + return + turn = current_turn_scope() + if turn is not None and self._numbered.get(conversation) is turn: + return + async with self._numbering: + if turn is not None and self._numbered.get(conversation) is turn: + return + try: + counts = await self._stored(conversation) + except Exception as error: # noqa: BLE001 - the run goes on: the next one asks again + logger.warning("subagent_instances_unread", session_id=conversation.session_id, + error=truncate(str(error), _MAX_LOGGED_ERROR)) + logger.debug("subagent_instances_unread", exc_info=error) + return + self._runs.number_from(conversation, counts) + if turn is not None: + self._numbered[conversation] = turn + async def _in_run( self, ref: RunRef, diff --git a/src/agentic_cli/workflow/agents/runs.py b/src/agentic_cli/workflow/agents/runs.py index 6d60afe3..f03ee8dd 100644 --- a/src/agentic_cli/workflow/agents/runs.py +++ b/src/agentic_cli/workflow/agents/runs.py @@ -1,7 +1,8 @@ """A manager's sub-agent runs, kept by conversation. Each run is named readably within its conversation: its instance -``-`` (``researcher-2``, numbered per agent) and its run +``-`` (``researcher-2``, numbered per agent, past the instances +the conversation's store already keeps: ``number_from``) and its run ``#`` (each instance runs once: ``#1``). The framework names a run as it starts it (``agents/delegate.py::Delegations``) with ``run_for``, keyed by (conversation, parent run, the parent's call id): the same key @@ -201,6 +202,22 @@ def run_for( self._runs[key] = ref return ref + def number_from(self, conversation: SessionRef | None, counts: Mapping[str, int]) -> None: + """Number ``conversation``'s next instances of each agent past ``counts``. + + ``counts[agent]`` is the highest instance number of ``agent`` the + conversation's store already keeps (another manager's: before a + restart or a switch of backend or store, or another process's between + two turns), so ``run_for``'s next instance of it + is ``-`` at the earliest. A count is never + lowered: an instance this manager numbered already stays numbered, + and an open run keeps its name. + """ + for agent, count in counts.items(): + key = (conversation, agent) + if count > self._numbered.get(key, 0): + self._numbered[key] = count + def observe(self, event: WorkflowEvent) -> None: """Record what a run's ``AGENT_RUN`` event says, under the turn it is reported in. diff --git a/src/agentic_cli/workflow/base_manager.py b/src/agentic_cli/workflow/base_manager.py index c11b79b4..b161432c 100644 --- a/src/agentic_cli/workflow/base_manager.py +++ b/src/agentic_cli/workflow/base_manager.py @@ -584,9 +584,9 @@ def _delegations(self) -> Delegations: """This manager's delegations (``workflow/agents/delegate.py``), made on first use. From the agent configs, the policy (``subagent_policy``) and the - backend's hook (``_run_agent``): each ``task`` call of a delegating - agent hands its brief to ``delegate``, which names, runs, ends and - records the run. + backend's hooks (``_run_agent``, ``_stored_instances``): each + ``task`` call of a delegating agent hands its brief to ``delegate``, + which names, runs, ends and records the run. """ delegations = self.__dict__.get("_delegations_made") if delegations is None: @@ -596,9 +596,23 @@ def _delegations(self) -> Delegations: types={config.name: config for config in self._agent_configs}, hook=self._run_agent, ledgers=self._usage_ledgers, + stored=self._stored_instances, ) return delegations + async def _stored_instances(self, conversation: SessionRef) -> Mapping[str, int]: + """How many instances of each agent type ``conversation``'s store keeps (a backend hook). + + The highest stored instance number of each type, by type: what a + store holds of another manager's runs (before a restart or a switch + of backend or store, or another process's between two turns), which + this manager's numbering goes past (``Delegations``, once per + conversation per turn). The base keeps no + sub-agent transcript, and so keeps none (Deep Agents: a sub-agent is + compiled without a checkpointer). + """ + return {} + async def _run_agent(self, run: AgentRun) -> RunAnswer: """Run one sub-agent run to its end: the backend's hook (``Delegations``'s). diff --git a/src/agentic_cli/workflow/sessions.py b/src/agentic_cli/workflow/sessions.py index c6515a33..575d1d0b 100644 --- a/src/agentic_cli/workflow/sessions.py +++ b/src/agentic_cli/workflow/sessions.py @@ -195,6 +195,18 @@ def turn_has_ended() -> bool: return scope is not None and scope.ended +def current_turn_scope() -> object | None: + """This context's turn span, as an identity; None outside any. + + One object for the whole turn, in every context copied from inside it + (the tasks it starts, at any depth), and a new one for the next turn: + what is remembered for one turn only is kept with it and compared by + ``is`` (``Delegations`` reads a conversation's stored instances once per + turn). + """ + return _turn_scope.get() + + @dataclass(frozen=True, slots=True) class ToolCallRef: """One tool call of a turn, as the model made it. diff --git a/tests/cli/test_conversations_across_backends.py b/tests/cli/test_conversations_across_backends.py index d2796a6d..b80791c9 100644 --- a/tests/cli/test_conversations_across_backends.py +++ b/tests/cli/test_conversations_across_backends.py @@ -364,3 +364,43 @@ async def test_one_no_backend_keeps_is_not_found(self, readers): await app.process_input("/sessions --delete=zzz") assert said(app.session, "add_error") == ["Session 'zzz' not found."] + + +class TestASubAgentsTranscriptIsNoRow: + """On the real ADK manager (sqlite), each sub-agent run's transcript is a + child session of its conversation's (``adk/sessions.py::child_app``): + neither the app's list (what the picker and ``/sessions`` show) nor + ``--continue``'s newest conversation is ever one.""" + + async def test_the_list_and_continue_name_the_conversation_alone(self, project, monkeypatch): + import anthropic + + from agentic_cli.cli import AppInfo + from agentic_cli.cli.app import BaseCLIApp + from agentic_cli.workflow.adk.manager import GoogleADKWorkflowManager + from tests.workflow.adk.fakes import FakeAPI + from tests.workflow.test_adk_delegation import Team, delegation, route, says, team + + route(monkeypatch, anthropic, "AsyncAnthropic", FakeAPI(Team( + coordinator=[delegation("toolu_c1"), says("Done.")], researcher=[says("X is 42.")], + ))) + app_settings = BaseSettings(session_store="sqlite", default_model="claude-sonnet-4-6") + manager = GoogleADKWorkflowManager(agent_configs=team(), settings=app_settings) + await manager.initialize_services() + app = app_on(manager, app_settings) + try: + await app.process_input("Have the researcher find X.") + listed = await app.list_conversations() + finally: + await manager.cleanup() + app._conversation.release() + + later = BaseCLIApp( # the next start, before its workflow is built + app_info=AppInfo(name="Transcripts test", version="0"), + agent_configs=team(), settings=app_settings, + ) + hold, passed_over = await later._newest_stored() + later._conversation.abandon(hold) + + assert [(row.session_id, row.backend) for row in listed] == [(app.session_id, "adk")] + assert (hold.session_id, hold.place.backend, passed_over) == (app.session_id, "adk", []) diff --git a/tests/cli/test_memory_store_one_conversation.py b/tests/cli/test_memory_store_one_conversation.py index 93d46084..d607b8bf 100644 --- a/tests/cli/test_memory_store_one_conversation.py +++ b/tests/cli/test_memory_store_one_conversation.py @@ -984,6 +984,40 @@ async def test_adk_drops_it_and_its_job_is_told_unavailable(self, project, monke "unavailable — fetch the result with /jobs j1.", ] + async def test_adk_drops_its_sub_agents_transcripts_with_it(self, project, monkeypatch): + """Each sub-agent run's transcript is a child session of the + conversation's (``adk/sessions.py::child_app``): ``/new`` drops them + with the conversation it leaves.""" + from agentic_cli.workflow.adk.manager import GoogleADKWorkflowManager + from agentic_cli.workflow.adk.sessions import child_app + from tests.workflow.test_adk_delegation import Team, delegation, team + + serve(monkeypatch, Team( + coordinator=[delegation("toolu_c1"), says("Done.")], researcher=[says("X is 42.")], + )) + app_settings = BaseSettings(session_store="memory", default_model="claude-sonnet-4-6") + manager = GoogleADKWorkflowManager(agent_configs=team(), settings=app_settings) + await manager.initialize_services() + app = app_on(manager, app_settings) + + async def children() -> list[str]: + listed = await manager._session_service.list_sessions( + app_name=child_app(manager.app_name), user_id=app_settings.default_user, + ) + return [session.id for session in listed.sessions] + + try: + old = app.session_id + await app.process_input("Have the researcher find X.") + before = await children() + await app.start_new_session() + after = await children() + finally: + await manager.cleanup() + + assert before == [f"{old}/researcher-1"] + assert after == [] + async def test_deep_agents_drops_it(self, project, monkeypatch): pytest.importorskip("deepagents") from agentic_cli.workflow.deepagents import manager as deepagents_manager diff --git a/tests/workflow/adk/test_child_sessions.py b/tests/workflow/adk/test_child_sessions.py new file mode 100644 index 00000000..33e2c267 --- /dev/null +++ b/tests/workflow/adk/test_child_sessions.py @@ -0,0 +1,490 @@ +"""ADK's sub-agent transcripts live and die with their conversation. + +Each sub-agent run's transcript is a child session in the conversation's own +session service (``adk/sessions.py``): app ``child_app(app)``, session +``/``, the conversation's user. + +- Deleting the conversation deletes its children (``delete_children``, which + ``ServiceSessions.delete`` calls after the conversation's own delete, + whatever that found), so the manager's ``delete_session`` and a + ``SessionReader``'s leave none behind, on every store; their events go + with them. +- A manager numbers a conversation's instances past the ones its store + keeps (``_stored_instances``, asked once per conversation per turn), so + neither a new manager (a restart) nor one whose turns another process's + came between makes a second ``researcher-1``, and a stored transcript is + never replaced: a run whose instance is stored fails. +- A model switch between turns rebuilds the runners and keeps the + transcripts, the records and the numbering. +- No child session lists, or is found, as a conversation. + +Turns run the real manager on ``FakeAPI`` (Claude), on the memory store and +on sqlite. +""" + +from __future__ import annotations + +import contextlib +import sqlite3 + +import anthropic +import pytest + +pytest.importorskip("google.adk") + +from google.adk.events import Event # noqa: E402 +from google.adk.sessions import DatabaseSessionService, InMemorySessionService # noqa: E402 +from google.genai import types # noqa: E402 + +from agentic_cli.config import BaseSettings # noqa: E402 +from agentic_cli.workflow.adk import sessions as adk_sessions # noqa: E402 +from agentic_cli.workflow.adk.manager import GoogleADKWorkflowManager # noqa: E402 +from agentic_cli.workflow.adk.sessions import child_app # noqa: E402 +from agentic_cli.workflow.session_readers import open_session_reader # noqa: E402 +from tests.loop_guard import no_blocking_calls # noqa: E402 +from tests.workflow.adk.fakes import FakeAPI # noqa: E402 +from tests.workflow.test_adk_delegation import ( # noqa: E402,F401 + Team, + delegation, + project, + route, + says, + team, +) + +APP = "app" + + +@pytest.fixture(params=["memory", "sqlite"]) +async def service(request, tmp_path): + """A session service of each kind ADK keeps conversations in.""" + if request.param == "memory": + made = InMemorySessionService() + else: + made = DatabaseSessionService(db_url=f"sqlite+aiosqlite:///{tmp_path / 'sessions.db'}") + yield made + if request.param == "sqlite": + await made.close() + + +async def stored_ids(service, app_name: str, user_id: str = "u") -> list[str]: + listed = await service.list_sessions(app_name=app_name, user_id=user_id) + return sorted(session.id for session in listed.sessions) + + +def manager_on(store: str) -> GoogleADKWorkflowManager: + return GoogleADKWorkflowManager( + agent_configs=team(), + settings=BaseSettings( + session_store=store, default_model="claude-sonnet-4-6", default_user="u" + ), + ) + + +async def say(manager, text: str, session_id: str = "s") -> list: + return [event async for event in manager.process(text, "u", session_id=session_id)] + + +def two_delegations() -> Team: + """The coordinator delegates once in each of two conversations.""" + return Team( + coordinator=[delegation("toolu_c1"), says("Done."), delegation("toolu_c1"), says("Done.")], + researcher=[says("X is 42."), says("Y is 7.")], + ) + + +def sqlite_rows(manager, query: str, *args) -> list[tuple]: + """Rows of the sqlite file the manager's sessions are in.""" + with sqlite3.connect(manager._settings.sessions_dir / "sessions.db") as db: + return db.execute(query, args).fetchall() + + +class TestDeleteChildren: + async def test_it_deletes_the_conversations_children_alone(self, service): + for app_name, user_id, session_id in [ + (child_app(APP), "u", "s/researcher-1"), + (child_app(APP), "u", "s/researcher-2"), + (child_app(APP), "u", "s/writer-1"), + (child_app(APP), "u", "t/researcher-1"), # another conversation's + (child_app(APP), "u", "s/x/researcher-1"), # the conversation "s/x"'s + (child_app(APP), "v", "s/researcher-1"), # another user's + (APP, "u", "s"), # the conversation itself + ]: + await service.create_session(app_name=app_name, user_id=user_id, session_id=session_id) + + deleted = await adk_sessions.delete_children(service, APP, "u", "s") + + assert deleted == 3 + assert await stored_ids(service, child_app(APP)) == ["s/x/researcher-1", "t/researcher-1"] + assert await stored_ids(service, child_app(APP), "v") == ["s/researcher-1"] + assert await stored_ids(service, APP) == ["s"] + + async def test_none_is_none(self, service): + assert await adk_sessions.delete_children(service, APP, "u", "s") == 0 + + async def test_their_events_go_with_them(self, tmp_path): + database = tmp_path / "sessions.db" + + def events() -> int: + with contextlib.closing(sqlite3.connect(database)) as db: + return db.execute("select count(*) from events").fetchone()[0] + + service = DatabaseSessionService(db_url=f"sqlite+aiosqlite:///{database}") + try: + child = await service.create_session( + app_name=child_app(APP), user_id="u", session_id="s/researcher-1" + ) + await service.append_event(child, Event( + author="researcher", + content=types.Content(role="model", parts=[types.Part(text="X is 42.")]), + )) + before = events() + + await adk_sessions.delete_children(service, APP, "u", "s") + finally: + await service.close() + + assert (before, events()) == (1, 0) + + +class TestDeletingTheConversation: + @pytest.mark.parametrize("store", ["memory", "sqlite"]) + async def test_its_delete_deletes_its_runs_transcripts(self, store, project, monkeypatch): + route(monkeypatch, anthropic, "AsyncAnthropic", FakeAPI(two_delegations())) + manager = manager_on(store) + try: + await say(manager, "Find X.", "s") + await say(manager, "Find Y.", "t") + before = await stored_ids(manager._session_service, child_app(manager.app_name)) + deleted = await manager.delete_session("s", user_id="u") + after = await stored_ids(manager._session_service, child_app(manager.app_name)) + finally: + await manager.cleanup() + + assert before == ["s/researcher-1", "t/researcher-1"] + assert deleted is True + assert after == ["t/researcher-1"] + + async def test_a_conversation_already_gone_leaves_none_behind(self, project, monkeypatch): + route(monkeypatch, anthropic, "AsyncAnthropic", FakeAPI(two_delegations())) + manager = manager_on("memory") + try: + await say(manager, "Find X.") + service = manager._session_service + await service.delete_session(app_name=manager.app_name, user_id="u", session_id="s") + deleted = await manager.delete_session("s", user_id="u") + after = await stored_ids(service, child_app(manager.app_name)) + finally: + await manager.cleanup() + + assert (deleted, after) == (False, []) # the answer is still about the conversation + + async def test_a_readers_delete_deletes_them_too(self, project, monkeypatch): + """``/sessions --delete`` of a conversation on a backend that is not running.""" + route(monkeypatch, anthropic, "AsyncAnthropic", FakeAPI(two_delegations())) + manager = manager_on("sqlite") + try: + await say(manager, "Find X.", "s") + await say(manager, "Find Y.", "t") + finally: + await manager.cleanup() + + async with await open_session_reader("adk", manager._settings) as reader: + deleted = await reader.delete("s") + + assert deleted is True + assert sqlite_rows(manager, "select app_name, id from sessions order by id") == [ + (manager.app_name, "t"), (child_app(manager.app_name), "t/researcher-1"), + ] + assert {app for (app,) in sqlite_rows(manager, "select distinct session_id from events")} == { + "t", "t/researcher-1", + } + + async def test_a_delete_blocks_no_event_loop(self, project, monkeypatch): + route(monkeypatch, anthropic, "AsyncAnthropic", FakeAPI(two_delegations())) + manager = manager_on("sqlite") + try: + await say(manager, "Find X.") + with no_blocking_calls(): + deleted = await manager.delete_session("s", user_id="u") + after = await stored_ids(manager._session_service, child_app(manager.app_name)) + finally: + await manager.cleanup() + + assert (deleted, after) == (True, []) + + +def texts_of(session) -> list[str]: + """The texts a session's events hold, in order.""" + return [ + part.text for event in session.events if event.content is not None + for part in event.content.parts or () if part.text + ] + + +async def child(manager, instance: str, conversation: str = "s"): + return await manager._session_service.get_session( + app_name=child_app(manager.app_name), user_id="u", session_id=f"{conversation}/{instance}" + ) + + +def instances(manager, conversation: str = "s") -> list[tuple[str, str]]: + """The conversation's runs this manager recorded: (run, status), in start order.""" + return [ + (record.ref.run, record.status) + for record in manager.agent_runs.records(manager.session_ref(conversation, "u")) + ] + + +def both(*answers: dict) -> dict: + """One answer that makes every call ``answers`` make.""" + return {**answers[0], "content": [block for answer in answers for block in answer["content"]]} + + +class TestStoredInstances: + async def test_the_highest_stored_number_of_each_type(self, service): + for session_id in [ + "s/researcher-1", "s/researcher-3", "s/writer-2", + "t/researcher-7", # another conversation's + "s/x/researcher-9", # the conversation "s/x"'s + "s/notes", "s/writer-two", # no instance of the framework's + ]: + await service.create_session( + app_name=child_app(APP), user_id="u", session_id=session_id + ) + + counts = await adk_sessions.stored_instances(service, APP, "u", "s") + + assert counts == {"researcher": 3, "writer": 2} + + async def test_none_is_none(self, service): + assert await adk_sessions.stored_instances(service, APP, "u", "s") == {} + + +class TestNumberedPastTheStored: + """Instances are numbered per manager: each turn numbers past the + instances the conversation's store keeps (``_stored_instances``), which + another manager may have run (before a restart or a switch of backend + or store, or in another process between two turns), so a stored + transcript is never another run's.""" + + async def test_a_restart_numbers_past_them_and_keeps_their_transcripts( + self, project, monkeypatch + ): + route(monkeypatch, anthropic, "AsyncAnthropic", FakeAPI(two_delegations())) + first = manager_on("sqlite") + try: + await say(first, "Find X.") + finally: + await first.cleanup() + + second = manager_on("sqlite") + try: + await say(second, "Find Y.") + runs = instances(second) + earlier, later = await child(second, "researcher-1"), await child(second, "researcher-2") + finally: + await second.cleanup() + + assert runs == [("researcher-2#1", "completed")] + assert texts_of(earlier)[1:] == ["X is 42."] + assert texts_of(later)[1:] == ["Y is 7."] + + async def test_parallel_first_runs_after_a_restart_are_both_numbered_past_them( + self, project, monkeypatch + ): + route(monkeypatch, anthropic, "AsyncAnthropic", FakeAPI(Team( + coordinator=[ + delegation("toolu_c1"), says("Done."), + both(delegation("toolu_c1"), delegation("toolu_c2")), says("Both done."), + ], + researcher=[says("X is 42."), says("Y is 7."), says("Z is 3.")], + ))) + first = manager_on("sqlite") + try: + await say(first, "Find X.") + finally: + await first.cleanup() + + second = manager_on("sqlite") + asked: list = [] + looked = second._stored_instances + + async def counted(conversation): + asked.append(conversation) + return await looked(conversation) + + second._stored_instances = counted + try: + await say(second, "Find Y and Z.") + runs = sorted(run for run, _ in instances(second)) + stored = await stored_ids(second._session_service, child_app(second.app_name)) + finally: + await second.cleanup() + + assert runs == ["researcher-2#1", "researcher-3#1"] + assert stored == ["s/researcher-1", "s/researcher-2", "s/researcher-3"] + assert asked == [second.session_ref("s", "u")] + + async def test_turns_another_manager_ran_in_between_are_numbered_past( + self, project, monkeypatch + ): + """Two processes take turns on one conversation (each holds it while + it runs a turn: ``ConversationLock``): each turn's first run is + numbered past what the other stored in between.""" + route(monkeypatch, anthropic, "AsyncAnthropic", FakeAPI(Team( + coordinator=[delegation("toolu_c1"), says("Done.")] * 3, + researcher=[says("X is 42."), says("Y is 7."), says("Z is 3.")], + ))) + one, two = manager_on("sqlite"), manager_on("sqlite") + try: + await say(one, "Find X.") + await say(two, "Find Y.") + await say(one, "Find Z.") + runs = {"one": instances(one), "two": instances(two)} + last = await child(one, "researcher-3") + finally: + await one.cleanup() + await two.cleanup() + + assert runs == { + "one": [("researcher-1#1", "completed"), ("researcher-3#1", "completed")], + "two": [("researcher-2#1", "completed")], + } + assert texts_of(last)[1:] == ["Z is 3."] + + async def test_a_stored_transcript_is_never_replaced(self, project, monkeypatch): + """A run whose instance the store already keeps (here: a store that + could not tell what it keeps) fails, and the transcript stays.""" + route(monkeypatch, anthropic, "AsyncAnthropic", FakeAPI(two_delegations())) + first = manager_on("sqlite") + try: + await say(first, "Find X.") + finally: + await first.cleanup() + + second = manager_on("sqlite") + + async def keeps_none(conversation): + return {} + + second._stored_instances = keeps_none + try: + await say(second, "Find Y.") + (record,) = second.agent_runs.records(second.session_ref("s", "u")) + kept = await child(second, "researcher-1") + finally: + await second.cleanup() + + assert (record.ref.run, record.status) == ("researcher-1#1", "failed") + assert record.error == "Session with id s/researcher-1 already exists." + assert texts_of(kept)[1:] == ["X is 42."] + + async def test_the_look_blocks_no_event_loop(self, project, monkeypatch): + route(monkeypatch, anthropic, "AsyncAnthropic", FakeAPI(two_delegations())) + first = manager_on("sqlite") + try: + await say(first, "Find X.") + finally: + await first.cleanup() + + second = manager_on("sqlite") + try: + await second.initialize_services() + with no_blocking_calls(): + counts = await second._stored_instances(second.session_ref("s", "u")) + finally: + await second.cleanup() + + assert counts == {"researcher": 1} + + +class TestAModelSwitchBetweenTurns: + """A model switch between turns: ``/settings`` reinitializes the manager + in place (``reinitialize(preserve_sessions=True)``).""" + + async def test_the_runners_are_rebuilt_and_the_transcripts_and_records_stay( + self, project, monkeypatch + ): + answers = two_delegations() + route(monkeypatch, anthropic, "AsyncAnthropic", FakeAPI(answers)) + manager = manager_on("memory") + try: + await say(manager, "Find X.") + before = manager._agent_runners["researcher"] + await manager.reinitialize(model="claude-haiku-4-5", preserve_sessions=True) + after = manager._agent_runners["researcher"] + await say(manager, "Find Y.") + runs = instances(manager) + earlier, later = await child(manager, "researcher-1"), await child(manager, "researcher-2") + finally: + await manager.cleanup() + + assert after is not before + assert [body["model"] for body in answers.bodies("researcher")] == [ + "claude-sonnet-4-6", "claude-haiku-4-5", + ] + assert runs == [("researcher-1#1", "completed"), ("researcher-2#1", "completed")] + assert texts_of(earlier)[1:] == ["X is 42."] + assert texts_of(later)[1:] == ["Y is 7."] + + async def test_a_new_managers_first_run_on_the_new_model_is_numbered_past_the_stored( + self, project, monkeypatch + ): + answers = two_delegations() + route(monkeypatch, anthropic, "AsyncAnthropic", FakeAPI(answers)) + first = manager_on("sqlite") + try: + await say(first, "Find X.") + finally: + await first.cleanup() + + second = manager_on("sqlite") + try: + await second.initialize_services() + await second.reinitialize(model="claude-haiku-4-5", preserve_sessions=True) + await say(second, "Find Y.") + runs = instances(second) + finally: + await second.cleanup() + + assert runs == [("researcher-2#1", "completed")] + assert [body["model"] for body in answers.bodies("researcher")] == [ + "claude-sonnet-4-6", "claude-haiku-4-5", + ] + + +class TestNeverListed: + """A child session is under the conversation's child app, so none lists, + or is found, as a conversation: not by a reader (``/sessions`` and the + picker on a backend that is not running), nor by the CLI's look at every + backend's conversations (``cli/stored_conversations.py``), the running + manager's or the readers'.""" + + async def test_no_reader_or_look_shows_one(self, project, monkeypatch): + from agentic_cli.cli.stored_conversations import StoredConversations + + route(monkeypatch, anthropic, "AsyncAnthropic", FakeAPI(two_delegations())) + manager = manager_on("sqlite") + try: + await say(manager, "Find X.") + async with StoredConversations( + manager._settings, "sqlite", workflow=manager, backend="adk" + ) as look: + running = await look.rows() + found = await look.where("s/researcher-1") + finally: + await manager.cleanup() + + async with await open_session_reader("adk", manager._settings) as reader: + listed = await reader.list() + info = await reader.info("s/researcher-1") + exists = await reader.exists("s/researcher-1") + async with StoredConversations(manager._settings, "sqlite") as look: # no manager runs + read = await look.rows() + + assert [(row.session_id, row.backend) for row in running] == [("s", "adk")] + assert found == [] + assert [row.session_id for row in listed] == ["s"] + assert (info, exists) == (None, False) + assert [(row.session_id, row.backend) for row in read] == [("s", "adk")] diff --git a/tests/workflow/test_agent_delegate.py b/tests/workflow/test_agent_delegate.py index 01334987..bac2b2d6 100644 --- a/tests/workflow/test_agent_delegate.py +++ b/tests/workflow/test_agent_delegate.py @@ -10,7 +10,8 @@ from __future__ import annotations import asyncio -from collections.abc import Awaitable, Callable +import contextlib +from collections.abc import Awaitable, Callable, Iterator from typing import Any import pytest @@ -25,6 +26,7 @@ AgentRuns, SubAgentPolicy, ) +from agentic_cli.workflow.agents import delegate as delegate_module from agentic_cli.workflow.agents.brief import INHERITED_CONTEXT_NOTE, Brief, task_message from agentic_cli.workflow.agents.delegate import ( AgentRun, @@ -43,8 +45,10 @@ RunRef, SessionRef, ToolCallRef, + close_turn_scope, get_active_run, get_active_tool_call, + open_turn_scope, reset_active_tool_call, reset_active_turn, set_active_tool_call, @@ -445,3 +449,216 @@ async def test_a_delegation_blocks_no_event_loop(): result, _ = await delegated(delegations(hook), request()) assert result.result["status"] == RUN_COMPLETED + + +def storing(*answers: Any) -> tuple[Callable[[SessionRef], Awaitable[dict[str, int]]], list[SessionRef]]: + """A ``stored`` that answers each ask with the next of ``answers`` (an + exception is raised, an ``asyncio.Event`` waited on, then the next + answer given); the conversations it was asked about. Each ask yields to + the loop before it answers, as a store's read does, so parallel runs + meet while one asks.""" + asked: list[SessionRef] = [] + left = list(answers) + + async def stored(conversation: SessionRef) -> dict[str, int]: + asked.append(conversation) + answer = left.pop(0) + if isinstance(answer, asyncio.Event): + await answer.wait() + answer = left.pop(0) + await asyncio.sleep(0) + if isinstance(answer, BaseException): + raise answer + return answer + + return stored, asked + + +@contextlib.contextmanager +def a_turn() -> Iterator[None]: + """A turn of ``CONVERSATION``, as a manager's has it: the active turn, + its span open, its live events reported.""" + token = set_active_turn(CONVERSATION) + span = open_turn_scope() + try: + with live_events.reporting(LiveEvents()): + yield + finally: + close_turn_scope(span) + reset_active_turn(token) + + +async def in_turn(made: Delegations, *asked: DelegationRequest) -> list[Any]: + """Each of ``asked`` delegated at once in a turn of ``CONVERSATION``; their results.""" + with a_turn(): + return list(await asyncio.gather(*(made.delegate(one) for one in asked))) + + +@pytest.fixture +def logged(monkeypatch) -> list[dict]: + """Every log call of ``agents/delegate.py``, with its level.""" + events: list[dict] = [] + + class Recorder: + def __getattr__(self, level: str): + def log(event: str, **fields) -> None: + events.append({"event": event, "log_level": level, **fields}) + + return log + + monkeypatch.setattr(delegate_module, "logger", Recorder()) + return events + + +class TestNumberedPastTheStored: + """A conversation's store may keep instances another manager ran (a + restart, a switch of backend or store, another process that had the + conversation between turns): ``stored`` says how many of each type, + asked once per conversation per turn, before the turn's first run is + named.""" + + async def test_the_first_run_is_numbered_past_them(self): + hook, _ = answering() + stored, asked = storing({"researcher": 2}) + + (result,) = await in_turn(delegations(hook, stored=stored), request()) + + assert (result.result["agent"], result.run.run) == ("researcher-3", "researcher-3#1") + assert asked == [CONVERSATION] + + async def test_it_is_asked_once_per_conversation_per_turn(self): + """A turn's runs ask once; the next turn asks again, since another + process may have run the conversation in between.""" + hook, _ = answering() + stored, asked = storing({"researcher": 2}, {"researcher": 7}) + made = delegations(hook, stored=stored) + + with a_turn(): + first = [await made.delegate(request(call_id=c)) for c in ("c1", "c2")] + later = await in_turn(made, request(call_id="c3")) + + assert [r.result["agent"] for r in first + later] == [ + "researcher-3", "researcher-4", "researcher-8", + ] + assert asked == [CONVERSATION, CONVERSATION] + + async def test_parallel_first_runs_ask_once_and_both_are_numbered_past_them(self): + hook, _ = answering() + stored, asked = storing({"researcher": 2}) + + results = await in_turn( + delegations(hook, stored=stored), request(call_id="c1"), request(call_id="c2") + ) + + assert sorted(r.result["agent"] for r in results) == ["researcher-3", "researcher-4"] + assert asked == [CONVERSATION] + + async def test_a_brief_that_cannot_start_a_run_asks_nothing(self): + hook, _ = answering() + stored, asked = storing() + + (result,) = await in_turn( + delegations(hook, stored=stored), request({"agent_type": "researcher"}) + ) + + assert (result.run, asked) == (None, []) + + async def test_a_store_that_cannot_be_read_is_asked_again_at_the_next_run(self): + hook, _ = answering() + stored, asked = storing(RuntimeError("database is locked"), {"researcher": 5}) + made = delegations(hook, stored=stored) + + with a_turn(): + results = [await made.delegate(request(call_id=c)) for c in ("c1", "c2")] + + assert [r.result["agent"] for r in results] == ["researcher-1", "researcher-6"] + assert asked == [CONVERSATION, CONVERSATION] + + async def test_a_store_that_cannot_be_read_is_warned_of_in_the_log(self, logged): + hook, _ = answering() + failure = RuntimeError("database is locked") + stored, _ = storing(failure) + + (result,) = await in_turn(delegations(hook, stored=stored), request()) + + assert result.result["status"] == RUN_COMPLETED + assert [e for e in logged if e["log_level"] == "warning"] == [{ + "event": "subagent_instances_unread", "log_level": "warning", + "session_id": CONVERSATION.session_id, "error": "database is locked", + }] + assert [ + e["exc_info"] for e in logged + if (e["event"], e["log_level"]) == ("subagent_instances_unread", "debug") + ] == [failure] + + async def test_an_ask_a_cancel_stopped_starts_no_run_and_is_asked_again(self): + hook, ran = answering() + waiting = asyncio.Event() + stored, asked = storing(waiting, {"researcher": 1}) + runs = AgentRuns() + made = delegations(hook, runs=runs, stored=stored) + + with a_turn(): + stopped = asyncio.create_task(made.delegate(request(call_id="c1"))) + while not asked: + await asyncio.sleep(0) + stopped.cancel() + with pytest.raises(asyncio.CancelledError): + await stopped + result = await made.delegate(request(call_id="c2")) + + assert result.result["agent"] == "researcher-2" + assert asked == [CONVERSATION, CONVERSATION] + assert [run.ref.run for run in ran] == ["researcher-2#1"] + assert [record.ref.run for record in runs.records(CONVERSATION)] == ["researcher-2#1"] + + async def test_without_a_turns_span_every_run_asks(self): + """A conversation active with no turn's span open (a caller that set + the active turn alone) has no turn to remember the ask for.""" + hook, _ = answering() + stored, asked = storing({"researcher": 2}, {"researcher": 2}) + made = delegations(hook, stored=stored) + + token = set_active_turn(CONVERSATION) + try: + with live_events.reporting(LiveEvents()): + results = [await made.delegate(request(call_id=c)) for c in ("c1", "c2")] + finally: + reset_active_turn(token) + + assert [r.result["agent"] for r in results] == ["researcher-3", "researcher-4"] + assert asked == [CONVERSATION, CONVERSATION] + + async def test_the_managers_delegations_ask_its_stored_instances(self): + """``BaseWorkflowManager._stored_instances``: the base keeps none; a + backend that stores transcripts says how many of each type.""" + from agentic_cli.workflow.base_manager import BaseWorkflowManager + from tests.conftest import MockContext + + class Storing(BaseWorkflowManager): + backend_type = "storing" + + def _get_state_tools(self) -> list: + return [] + + async def _do_initialize(self) -> None: + return None + + async def process(self, message, user_id, session_id=None): # pragma: no cover + yield WorkflowEvent.text(message) + + async def _run_agent(self, run: AgentRun) -> RunAnswer: + return RunAnswer(text="X is 42.") + + with MockContext(google_api_key="test-key") as context: + manager = Storing(list(TYPES.values()), settings=context.settings) + base = await BaseWorkflowManager._stored_instances(manager, CONVERSATION) + + async def stored(conversation: SessionRef) -> dict[str, int]: + return {"researcher": 4} + + manager._stored_instances = stored + (result,) = await in_turn(manager._delegations, request()) + + assert base == {} + assert result.result["agent"] == "researcher-5" diff --git a/tests/workflow/test_agent_runs.py b/tests/workflow/test_agent_runs.py index 90fb76a5..935012e0 100644 --- a/tests/workflow/test_agent_runs.py +++ b/tests/workflow/test_agent_runs.py @@ -134,6 +134,52 @@ def test_a_run_id_names_its_instance(self): assert [run_instance(ref.run) for ref in (middle, leaf)] == ["middle-1", "leaf-1"] +class TestNumberFrom: + """A conversation's store may keep instances an earlier manager numbered + (a restart, a switch of backend or store): ``number_from`` numbers the + next ones past them.""" + + def test_the_next_instance_is_numbered_past_the_count(self): + runs = AgentRuns() + + runs.number_from(ONE, {"researcher": 3}) + + assert runs.run_for(ONE, None, "c1", "researcher").run == "researcher-4#1" + + def test_another_agent_or_conversation_is_not_moved(self): + runs = AgentRuns() + + runs.number_from(ONE, {"researcher": 3}) + + assert runs.run_for(ONE, None, "c1", "writer").run == "writer-1#1" + assert runs.run_for(TWO, None, "c1", "researcher").run == "researcher-1#1" + + def test_a_count_is_never_lowered(self): + runs = AgentRuns() + for call_id in ("c1", "c2", "c3"): + runs.run_for(ONE, None, call_id, "researcher") + + runs.number_from(ONE, {"researcher": 1}) + + assert runs.run_for(ONE, None, "c4", "researcher").run == "researcher-4#1" + + def test_an_open_run_keeps_its_name(self): + runs = AgentRuns() + open_run = runs.run_for(ONE, None, "c1", "researcher") + + runs.number_from(ONE, {"researcher": 5}) + + assert runs.run_for(ONE, None, "c1", "researcher") is open_run + assert runs.run_for(ONE, None, "c2", "researcher").run == "researcher-6#1" + + def test_no_conversation_is_one_too(self): + runs = AgentRuns() + + runs.number_from(None, {"researcher": 2}) + + assert runs.run_for(None, None, "c1", "researcher").run == "researcher-3#1" + + class TestObserve: def test_a_start_is_recorded(self): runs = AgentRuns() diff --git a/tests/workflow/test_session_readers.py b/tests/workflow/test_session_readers.py index 9fdc6d4e..76d9b776 100644 --- a/tests/workflow/test_session_readers.py +++ b/tests/workflow/test_session_readers.py @@ -220,6 +220,7 @@ async def test_the_other_backends_file_keeps_its_tables_and_journal_mode( assert await reader.list() == [] assert await reader.info("s1") is None assert await reader.exists("s1") is False + assert await reader.delete("s1") is False assert (_tables(shared), _journal_mode(shared)) == (tables, mode) assert await _left_after(before) == set() diff --git a/tests/workflow/test_subagents_contract.py b/tests/workflow/test_subagents_contract.py index 9b9f1f99..65c8ffc6 100644 --- a/tests/workflow/test_subagents_contract.py +++ b/tests/workflow/test_subagents_contract.py @@ -2331,3 +2331,85 @@ async def test_a_delegation_blocks_no_event_loop(self, make_crew): events = await crew.turn() assert [e.metadata["status"] for e in runs_of(events)] == [RUN_STARTED, RUN_COMPLETED] + + +async def transcripts(crew: Crew) -> list[str]: + """The sub-agent instances whose transcript the conversation's store keeps. + + ADK keeps each run's transcript in a child session of the conversation's + (``adk/sessions.py``: app ``child_app(app)``, session + ``/``). Deep Agents keeps one only as a + checkpoint: a thread of the conversation's own (``[app, user, session, + ]``) or a namespace under its thread; a sub-agent is compiled + without a checkpointer, so there is none. + """ + conversation = crew.conversation + if crew.backend == "adk": + from agentic_cli.workflow.adk.sessions import child_app + + listed = await crew.manager._session_service.list_sessions( + app_name=child_app(conversation.app_name), user_id=conversation.user_id, + ) + prefix = f"{conversation.session_id}/" + return sorted( + session.id.removeprefix(prefix) for session in listed.sessions + if session.id.startswith(prefix) + ) + found: set[str] = set() + own = [conversation.app_name, conversation.user_id, conversation.session_id] + async for saved in crew.manager._checkpointer.alist(None): + configurable = saved.config["configurable"] + thread = json.loads(configurable["thread_id"]) + if thread[:3] != own: + continue + if len(thread) > 3: + found.add(str(thread[3])) + elif configurable.get("checkpoint_ns"): + found.add(configurable["checkpoint_ns"]) + return sorted(found) + + +class TestARunsTranscriptIsNoConversation: + """A sub-agent run's transcript belongs to its conversation: it never + lists or opens as a conversation of its own, and deleting the + conversation deletes it. (Only ADK keeps one, so only ADK numbers a new + manager's instances past the ones a conversation's store keeps: + ``tests/workflow/adk/test_child_sessions.py``.)""" + + @staticmethod + def two_runs(make_crew) -> Crew: + return make_crew( + team(), + coordinator=[calls(delegate("researcher", "Find X.", "c1"), + delegate("researcher", "Find Y.", "c2")), + says("Done.")], + researcher=[says("X is 42."), says("Y is 7.")], + ) + + async def test_deleting_the_conversation_deletes_every_runs_transcript(self, make_crew): + crew = self.two_runs(make_crew) + manager = crew.manager + + await crew.turn() + kept = await transcripts(crew) + deleted = await manager.delete_session(SESSION, user_id=USER) + + # Deep Agents keeps no sub-agent transcript (no checkpointer). + assert kept == (["researcher-1", "researcher-2"] if crew.backend == "adk" else []) + assert deleted is True + assert await transcripts(crew) == [] + assert await manager.list_sessions(user_id=USER) == [] + + async def test_none_lists_or_opens_as_a_conversation(self, make_crew): + crew = self.two_runs(make_crew) + manager = crew.manager + + await crew.turn() + + assert [row.session_id for row in await manager.list_sessions(user_id=USER)] == [SESSION] + for instance in ("researcher-1", "researcher-2"): + assert await manager.session_info(f"{SESSION}/{instance}", user_id=USER) is None + assert await manager.session_exists(f"{SESSION}/{instance}", user_id=USER) is False + assert await manager.recent_messages(SESSION, user_id=USER) == [ + {"role": "user", "content": "Go."}, {"role": "assistant", "content": "Done."}, + ]