Skip to content

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.py
index 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 = 8
DEFAULT_TIMEOUT_SECONDS = 300
POLL_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 False
job.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.context
job_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.md
index 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 Guidance
diff --git a/plugins/_code_execution/AGENTS.md b/plugins/_code_execution/AGENTS.md
index 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.py
index 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 paused
runtime_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()
+ raise
self.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.md
index 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.py
new file mode 100644
index 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()