Agent Zero AI framework
Keep parallel terminal jobs alive until their commands finish
Alessandro98f943b853c8
diff --git a/helpers/parallel_tools.py b/helpers/parallel_tools.pyindex 264601746..6790a92c1 100644--- a/helpers/parallel_tools.py+++ b/helpers/parallel_tools.py@@ -32,7 +32,7 @@ CHILD_PARALLEL_TOOL_NAME_KEY = "parallel_tool_name"DEFAULT_MAX_CALLS = 8DEFAULT_TIMEOUT_SECONDS = 300POLL_INTERVAL_SECONDS = 0.5-DISALLOWED_PARALLEL_TOOLS = {"document_query", "response", "goal"}+DISALLOWED_PARALLEL_TOOLS = {"document_query", "response", "goal", "input"}TERMINAL_STATES = {"success", "error", "cancelled", "timeout"}JobState = Literal["pending", "running", "success", "error", "cancelled", "timeout"]@@ -102,7 +102,7 @@ def normalize_parallel_tool_calls(raw_calls: Any) -> list[NormalizedToolCall]:except ValueError as exc:raise ValueError(f"tool_calls[{index}] is not a valid tool call: {exc}") from exc- _ensure_parallel_tool_allowed(tool_name)+ _ensure_parallel_tool_allowed(tool_name, tool_args)calls.append(NormalizedToolCall(@@ -114,9 +114,17 @@ def normalize_parallel_tool_calls(raw_calls: Any) -> list[NormalizedToolCall]:return calls-def _ensure_parallel_tool_allowed(tool_name: str) -> None:+def _ensure_parallel_tool_allowed(tool_name: str, tool_args: dict[str, Any]) -> None:if tool_name == "parallel":raise ValueError("`parallel` cannot be nested inside another `parallel` call.")+ if (+ tool_name == "code_execution_tool"+ and str(tool_args.get("runtime", "")).strip().lower() in {"output", "reset"}+ ):+ raise ValueError(+ "Use `parallel` with job_ids to await/cancel a running code job; "+ "call session tools sequentially."+ )if tool_name in DISALLOWED_PARALLEL_TOOLS:raise ValueError(f"`{tool_name}` cannot be used inside `parallel`; call it sequentially."@@ -175,21 +183,24 @@ def is_parallel_worker(agent: "Agent | None") -> bool:return _parallel_worker_kind(agent) == "tool"+def get_parallel_worker_job(agent: "Agent") -> ParallelJob | None:+ if not is_parallel_worker(agent):+ return None+ context = agent.context+ parent_context_id = str(context.get_data(PARALLEL_WORKER_PARENT_CONTEXT_KEY) or "")+ job_id = str(context.get_data(PARALLEL_WORKER_JOB_KEY) or "")+ job = _get_job(parent_context_id, job_id)+ return job if job and job.kind == "tool" else None++def queue_parallel_parent_history(agent: "Agent",*,content: Any,tokens: int = 0,) -> bool:- if not is_parallel_worker(agent):- return False- context = agent.context- parent_context_id = str(- context.get_data(PARALLEL_WORKER_PARENT_CONTEXT_KEY) or ""- )- job_id = str(context.get_data(PARALLEL_WORKER_JOB_KEY) or "")- job = _get_job(parent_context_id, job_id)- if not job or job.kind != "tool":+ job = get_parallel_worker_job(agent)+ if not job:return Falsejob.parent_history.append((content, tokens))return True@@ -223,7 +234,7 @@ async def start_parallel_jobs(calls: list[NormalizedToolCall],) -> list[ParallelJob]:for call in calls:- _ensure_parallel_tool_allowed(call.tool_name)+ _ensure_parallel_tool_allowed(call.tool_name, call.tool_args)jobs: list[ParallelJob] = []context = agent.contextjob_store = _jobs_for_context(context)@@ -344,8 +355,7 @@ async def refresh_parallel_jobs(agent: "Agent") -> list[ParallelJob]:async def cleanup_parallel_job(agent: "Agent", job: ParallelJob) -> None:if job.deferred_task and job.deferred_task.is_alive():job.deferred_task.kill()- if job.kind == "tool":- await _remove_context(job.worker_context_id)+ # Direct workers remove their context in finally on their own event loop.async def collect_parallel_jobs(@@ -546,7 +556,7 @@ async def execute_tool_call(*,log_item: "LogItem | None" = None,) -> str:- _ensure_parallel_tool_allowed(tool_name)+ _ensure_parallel_tool_allowed(tool_name, tool_args)tool = _resolve_parallel_tool(agent, tool_name, tool_args, strict=True)if not tool:diff --git a/helpers/parallel_tools.py.dox.md b/helpers/parallel_tools.py.dox.mdindex 24899cb55..a5c670312 100644--- a/helpers/parallel_tools.py.dox.md+++ b/helpers/parallel_tools.py.dox.md@@ -25,7 +25,7 @@- Wrapped tool-call items must use the same shape as normal tool calls: a tool name plus arguments.- Normalization accepts full agent-reply-shaped objects when `tool_name` and `tool_args` are present; non-contract planning fields such as `thoughts` or `headline` are ignored.- `tool_calls` should be an array, but normalization also accepts a valid JSON string encoding of that array to recover provider/model stringification.-- Shared validation rejects `document_query`, `response`, and `goal` inside direct `parallel` workers: document parsing stays sequential, `response` ends the parent loop, and goals belong to the calling context. Validate the whole batch before registering jobs and recheck at direct dispatch. Retained subordinates keep their own state.+- Shared validation rejects `document_query`, `response`, `input`, and `goal` inside direct `parallel` workers: document parsing stays sequential, `response` ends the parent loop, and goals belong to the calling context. Validate the whole batch before registering jobs and recheck at direct dispatch. Retained subordinates keep their own state.- `call_subordinate` jobs first enforce the actual calling agent's delegation policy, then call the same creation and execution functions as direct delegation in `tools/call_subordinate.py`; this helper does not construct or prompt a second kind of subordinate.- Fresh parallel sibling calls create distinct `parent.number + 1` child agents. Their job snapshots expose stable `context_id` values that direct or parallel `reset=false` calls can continue after success or failure.- Jobs retain their actual parent agent so parallel calls made by A1 create A2 rather than falling back to a context's A0.@@ -40,7 +40,8 @@- Wrapped tool child logs use each tool's native `get_log_object()` output when available, preserving special log rendering (for example: `code_execution_tool` uses `code_exe`, `wait` uses `progress`, MCP tools use `mcp`, and regular tools use `tool`).- Direct parallel worker execution reuses the parent-visible child log item so tool `before_execution()` cannot create a second generic worker log or lose the native badge type.- Direct tools may explicitly queue model-visible history for their parent. Terminal collection records the outer `parallel` result first, promotes queued messages in job order, and only then removes disposable worker state; background jobs retain queued history until they are collected.-- Job IDs are stable handles for later await, collect, or cancel operations.+- Job IDs are stable handles for later await, collect, or cancel operations. Local code jobs keep their worker until the command completes; reject new-worker output/reset requests.+- `get_parallel_worker_job(...)` resolves only a registered direct worker. A stateful tool may publish its own model-facing progress to that job while retaining its original resource/event-loop owner; do not substitute arbitrary UI logs for model output.- Prompt extras must stay bounded and expose only job IDs, tool names, status, and compact result/error summaries.## Key Concepts@@ -48,7 +49,7 @@- The parent context stores in-flight jobs under a private data key; collected terminal jobs are removed from that registry.- `wait=True` starts jobs and awaits them before returning until all requested jobs finish or the wait timeout is reached; the timeout stops waiting but does not cancel running jobs.- `collect` returns already-finished job results without waiting; `await` waits for requested job IDs.-- Canceled jobs should be marked terminal and should stop their background `DeferredTask` when cancellation is possible.+- Canceled jobs should be marked terminal and should stop their background `DeferredTask` when cancellation is possible. Direct-worker finally owns context cleanup on its event loop; collection/cancellation must not race it with a second context reset.- `queue_parallel_parent_history(...)` accepts messages only from registered direct tool workers. `collect_parallel_jobs(...)` optionally promotes those messages while collecting terminal jobs; arbitrary worker history is never copied.## Work Guidancediff --git a/plugins/_code_execution/AGENTS.md b/plugins/_code_execution/AGENTS.mdindex d29c02f4a..62aa6986f 100644--- a/plugins/_code_execution/AGENTS.md+++ b/plugins/_code_execution/AGENTS.md@@ -14,6 +14,7 @@## Local Contracts- Keep session concurrency, timeout, streaming, and reset behavior predictable.+- A direct parallel code job retains its worker and loop-bound shell until the command ends or is cancelled. Output timeouts publish model-facing progress to the registered job and continue polling; callers use parallel job IDs. Close parallel shells explicitly on that worker loop on completion or cancellation, including partially connected shells. Top-level sessions retain their ordinary timeout/output/reset behavior.- Execute multi-line terminal input as one current-shell compound so intermediate prompts cannot mark queued work complete; preserve `cd`, exports, and other shell state.- Treat local process exit and SSH channel termination as definitive command completion even when no final prompt is emitted; recreate terminated sessions before their next command.- Terminal reset/close must not hang on foreground commands or shells that ignore SIGTERM.diff --git a/plugins/_code_execution/tools/code_execution_tool.py b/plugins/_code_execution/tools/code_execution_tool.pyindex 022d5975a..ad545c91f 100644--- a/plugins/_code_execution/tools/code_execution_tool.py+++ b/plugins/_code_execution/tools/code_execution_tool.py@@ -53,7 +53,18 @@ class State:class CodeExecution(Tool):async def execute(self, **kwargs) -> Response:+ from helpers.parallel_tools import get_parallel_worker_job+ job = get_parallel_worker_job(self.agent)+ try:+ return await self._execute(job)+ finally:+ state = getattr(self, "state", None)+ if job and state:+ for shell in state.shells.values():+ await shell.session.close()++ async def _execute(self, job) -> Response:await self.agent.handle_intervention() # wait for intervention and handle it, if pausedruntime_arg = self.args.get("runtime", "").lower().strip()@@ -86,6 +97,14 @@ class CodeExecution(Tool):"fw.code.runtime_wrong.md", runtime=runtime_arg)+ if job and runtime_arg in {"terminal", "python", "nodejs"}:+ while self.state.shells[session].running:+ job.result = response+ response = await self.get_terminal_output(+ cfg, session=session, reset_full_output=False,+ timeouts=cfg["output_timeouts"],+ )+if not response:response = self.agent.read_prompt("fw.code.info.md", info=self.agent.read_prompt("fw.code.no_output.md")@@ -149,7 +168,11 @@ class CodeExecution(Tool):shell = LocalInteractiveSession(cwd=cwd)shells[session] = ShellWrap(id=session, session=shell, running=False)- await shell.connect()+ try:+ await shell.connect()+ except BaseException:+ await shell.close()+ raiseself.state = State(shells=shells, ssh_enabled=ssh_enabled)self.agent.set_data("_cet_state", self.state)diff --git a/prompts/agent.system.tool.parallel.md b/prompts/agent.system.tool.parallel.mdindex fa9b6b02a..a4016649e 100644--- a/prompts/agent.system.tool.parallel.md+++ b/prompts/agent.system.tool.parallel.md@@ -12,6 +12,8 @@ Rules:- Call `goal` sequentially in the owning chat; direct parallel workers have a temporary context and cannot read or update the parent goal.- Call `response` only as a top-level tool so it ends the message loop; never wrap it inside `parallel.tool_calls`.- `call_subordinate` uses the same child lifecycle here as it does top-level; fresh siblings are next-level agents, and each job's `context_id` can be continued later with `reset: false`+- Local code jobs keep their own terminal alive until the command finishes or the job is cancelled. Use `wait: false` for long-running servers; await or cancel them with `job_ids`, including after an output timeout.+- Terminal session numbers are isolated per job. Do not send `input`, `runtime: output`, or `runtime: reset` as a new parallel call; use sequential terminal calls for persistent interactive sessions.- use `wait: false` only when you will collect results later with `job_ids`- if extras list running or ready parallel jobs, collect them before final synthesis- `timeout` only limits how long this call waits; running jobs continue and can be awaited again by `job_ids`diff --git a/tests/test_parallel_code_lifetime.py b/tests/test_parallel_code_lifetime.pynew file mode 100644index 000000000..e535db54f--- /dev/null+++ b/tests/test_parallel_code_lifetime.py@@ -0,0 +1,70 @@+import asyncio+from types import SimpleNamespace+from unittest.mock import AsyncMock++import pytest++from helpers import parallel_tools+from plugins._code_execution.tools import code_execution_tool as code++[email protected]("parallel,cancel", [(False, False), (True, False), (True, True)])+async def test_code_job_keeps_polling_after_output_timeout_without_reexecuting(monkeypatch, parallel, cancel):+ shell = SimpleNamespace(running=True, session=SimpleNamespace(close=AsyncMock()))+ job = SimpleNamespace(result=None) if parallel else None+ agent = SimpleNamespace(handle_intervention=AsyncMock())+ tool = object.__new__(code.CodeExecution)+ tool.agent = agent+ tool.args = {"runtime": "terminal", "session": 0, "code": "long command"}+ tool.state = SimpleNamespace(shells={0: shell})+ cfg = {"output_timeouts": {"first_output_timeout": 1}}+ monkeypatch.setattr(code, "_get_config", lambda _: cfg)+ monkeypatch.setattr(parallel_tools, "get_parallel_worker_job", lambda _: job)+ tool.execute_terminal_command = AsyncMock(return_value="START; output timeout")++ async def poll(*args, **kwargs):+ assert job.result == "START; output timeout"+ if cancel:+ raise asyncio.CancelledError()+ shell.running = False+ return "START; DONE"++ tool.get_terminal_output = AsyncMock(side_effect=poll)+ if cancel:+ with pytest.raises(asyncio.CancelledError):+ await tool.execute()+ else:+ result = await tool.execute()+ assert result.message == ("START; DONE" if parallel else "START; output timeout")+ tool.execute_terminal_command.assert_awaited_once()+ if parallel:+ tool.get_terminal_output.assert_awaited_once_with(+ cfg, session=0, reset_full_output=False, timeouts=cfg["output_timeouts"],+ )+ shell.session.close.assert_awaited_once()+ else:+ tool.get_terminal_output.assert_not_called()+ shell.session.close.assert_not_called()++[email protected]("tool_name,args", [+ ("input", {"session": 0, "keyboard": "yes"}),+ ("code_execution_tool", {"runtime": "output", "session": 0}),+ ("code_execution_tool", {"runtime": " RESET ", "session": 0}),+])+def test_parallel_session_followups_cannot_open_unrelated_workers(tool_name, args):+ with pytest.raises(ValueError, match="sequentially"):+ parallel_tools.normalize_parallel_tool_calls([{"tool": tool_name, "args": args}])+++async def test_cancelled_shell_connection_closes_partial_resources(monkeypatch):+ shell = SimpleNamespace(connect=AsyncMock(side_effect=asyncio.CancelledError()), close=AsyncMock())+ monkeypatch.setattr(code, "LocalInteractiveSession", lambda **kwargs: shell)+ tool = object.__new__(code.CodeExecution)+ tool.agent = SimpleNamespace(get_data=lambda _: None)+ tool.ensure_cwd = AsyncMock(return_value=None)+ with pytest.raises(asyncio.CancelledError):+ await tool.prepare_state({"ssh_enabled": False}, session=0)+ shell.close.assert_awaited_once()