vrr/agent-zero
2
0
Fork 0
mirror of https://github.com/agent0ai/agent-zero.git synced 2026-10-20 11:15:50 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
agent-zero/plugins/_code_execution/AGENTS.md
Alessandro c58061f0ee Keep terminal I/O from blocking shared event loops 
Use nonblocking POSIX PTY reads and buffered, cooperative writes so a full
terminal or stale readiness notification cannot stall other chats. Discard
a shell on cancellation only while command bytes remain unsent, preserving
shell state after a fully drained send.

Use best-effort synchronous destruction instead of reentering asyncio;
explicit close retains the existing awaited cleanup and signal escalation.

Add isolated regression checks for payload integrity, loop responsiveness,
partial and complete-send cancellation, descriptor reuse, cross-thread
cleanup, and destruction. Document the terminal lifecycle contracts.

Validation: 28 focused terminal, parallel-lifetime, and pager tests passed.
Four real Codex II chats also completed concurrent Linux terminal, Python,
and Node workloads with 29.87 seconds of overlap and intact shell state.
2026-10-06 18:49:30 +02:00

2.6 KiB
Raw Blame History

Code Execution Plugin DOX

Purpose

  • Own terminal, Python, and Node.js code execution through persistent local or SSH-backed sessions.

Ownership

  • tools/ owns the code execution and input tools.
  • helpers/ owns local shell, SSH shell, and TTY session management.
  • prompts/ owns execution prompt and runtime response fragments.
  • default_config.yaml, plugin.yaml, extensions/, and webui/ own settings, metadata, hooks, and UI config.

Local Contracts

  • extensions/webui/get_process_step_types/code-exe-types.js registers code_exe as a process-step type so raw-log grouping matches the plugin's message renderer.

  • 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.

  • POSIX PTY I/O is nonblocking. The existing write/drain interface buffers partial writes and yields while the terminal is full; cancellation discards the shell only while POSIX input bytes remain unsent. Fully drained sends retain the shell and its state.

  • TTY destruction uses best-effort kill, never nested event-loop execution; explicit close retains awaited cleanup.

  • Local and SSH session wrappers must synchronously release their owned process or connection resources when discarded.

  • Explicitly target local versus SSH execution runtimes.

  • The tool's allow_running flag is framework-set (for example by the input tool's terminal dispatch); it is not a model-facing arg and stays undocumented in prompts.

  • Do not hardcode secrets, SSH credentials, or local user paths.

Work Guidance

  • Preserve long-running command output retrieval and busy-session guards when changing execution flow.

Verification

  • Smoke-test terminal, Python, Node.js, output polling, and reset paths after tool changes.

Child DOX Index

No child DOX files.