vrr/agent-zero
2
0
Fork 0
mirror of https://github.com/agent0ai/agent-zero.git synced 2026-07-09 17:08:29 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

Add file-level DOX docs & update AGENTS indexes

Browse source 
Add comprehensive file-level DOX documentation across the repo and update directory AGENTS.md indexes. Many new `*.py.dox.md` files were added under api, helpers, tools, plugins, extensions, webui, and other dirs to document endpoint purpose, ownership, runtime contracts, work guidance, and verification. Several AGENTS.md files were created or updated (agents profiles, api, docker, extensions, helpers, plugins, skills, webui components, etc.) to list child DOX files and clarify documentation/work guidance. Also add example and bundled profile DOX files (agent0, default, developer, hacker, researcher) and minor updates to helpers/dirty_json.py and its tests. These changes improve on-disk documentation coverage and establish the convention that each direct runtime file should have a matching `*.dox.md` describing its contracts and verification steps.
This commit is contained in:
frdel 2026-06-08 12:41:53 +02:00
parent 08306be650
commit e138e33ca9
312 changed files with 13246 additions and 10 deletions
Download patch file Download diff file Expand all files Collapse all files

6
tools/AGENTS.md
View file

@ -18,17 +18,23 @@
- Use `await self.agent.handle_intervention(...)` when a long-running or external result should respect pause/intervention flow.
- Sanitize or mask secrets before logging, returning, or storing tool outputs.
- Do not perform destructive filesystem or network actions without the tool contract making that behavior explicit.
- This directory is a file-documented DOX profile: every direct `*.py` tool module must have a same-directory `*.py.dox.md` file named by appending `.dox.md` to the full Python filename.
- The `*.py.dox.md` file owns tool purpose, tool arguments/concepts, output and `break_loop` behavior, side effects, important helper dependencies, prompt-contract notes, and verification guidance.
- When a tool module is added, removed, renamed, or behaviorally changed, update its matching `*.py.dox.md` in the same change.
- Do not leave stale file-level DOX after tool deletion or rename.
## Work Guidance
- Keep tool output concise enough for message history while preserving actionable detail.
- Put reusable parsing, provider, filesystem, or network logic in `helpers/`.
- Update prompt tool instructions when changing tool names, arguments, or behavior.
- During the DOX pass, verify that every direct `*.py` file has a matching `*.py.dox.md` and that changed tool behavior is described there.
## Verification
- Run targeted tool tests after changing a tool or its prompt contract.
- Run prompt/snapshot tests when tool instructions or output shape changes.
- Check file-level documentation coverage with a script or shell loop that verifies each `tools/*.py` has a matching `tools/*.py.dox.md`.
## Child DOX Index

51
tools/a2a_chat.py.dox.md Normal file
View file

@ -0,0 +1,51 @@
# a2a_chat.py DOX
## Purpose
- Own the `a2a_chat.py` agent tool.
- This module lets the agent message an external A2A agent and extract the assistant reply.
- Keep this file-level DOX profile synchronized with `a2a_chat.py` because this directory is intentionally flat.
## Ownership
- `a2a_chat.py` owns the runtime implementation.
- `a2a_chat.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `A2AChatTool` (`Tool`)
- `async execute(self, **kwargs)`
- Top-level functions:
- `_session_key(agent_url: str) -> str`: Keep root and explicit /a2a URLs in the same conversation cache.
- `_text_from_part(part: Any) -> str`
- `_text_from_message(message: Any) -> str`
- `_extract_latest_assistant_text(task_response: Any) -> str`
- Notable constants/configuration names: `A2A_EMPTY_RESPONSE_ERROR`.
## Runtime Contracts
- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.
- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.
- `A2AChatTool` is a `Tool`.
- `A2AChatTool` defines `execute(...)`.
- Observed side-effect areas: filesystem writes, scheduler state.
- Imported dependency areas include: `helpers.fasta2a_client`, `helpers.print_style`, `helpers.tool`, `typing`.
## Key Concepts
- Important called helpers/classes observed in the source: `agent_url.rstrip`, `normalized.endswith`, `_text_from_message`, `normalized.rstrip`, `message.strip`, `join`, `_session_key`, `value.strip`, `_text_from_part`, `is_client_available`, `Response`, `self.agent.get_data`, `sessions.pop`, `_extract_latest_assistant_text`, `PrintStyle.error`, `connect_to_agent`, `conn.send_message`, `conn.wait_for_completion`, `self.agent.set_data`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Keep tool output concise, model-readable, and safe for history persistence.
- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.
- Respect intervention flow for long-running, external, or user-visible operations.
## Verification
- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.
- Related tests observed by source search:
- `tests/test_tool_action_contracts.py`
## Child DOX Index
No child DOX files.

46
tools/call_subordinate.py.dox.md Normal file
View file

@ -0,0 +1,46 @@
# call_subordinate.py DOX
## Purpose
- Own the `call_subordinate.py` agent tool.
- This module delegates work to a subordinate Agent Zero profile and returns its result.
- Keep this file-level DOX profile synchronized with `call_subordinate.py` because this directory is intentionally flat.
## Ownership
- `call_subordinate.py` owns the runtime implementation.
- `call_subordinate.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `Delegation` (`Tool`)
- `async execute(self, message=..., reset=..., **kwargs)`
- `get_log_object(self)`
## Runtime Contracts
- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.
- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.
- `Delegation` is a `Tool`.
- `Delegation` defines `execute(...)`.
- Observed side-effect areas: filesystem writes, settings/state persistence.
- Imported dependency areas include: `agent`, `extensions.python.hist_add_tool_result`, `helpers.tool`, `initialize`.
## Key Concepts
- Important called helpers/classes observed in the source: `self.agent.get_data`, `subordinate.hist_add_user_message`, `subordinate.history.new_topic`, `Response`, `self.agent.context.log.log`, `initialize_agent`, `Agent`, `sub.set_data`, `self.agent.set_data`, `UserMessage`, `subordinate.monologue`, `self.agent.read_prompt`, `str.lower.strip`, `str.lower`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Keep tool output concise, model-readable, and safe for history persistence.
- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.
- Respect intervention flow for long-running, external, or user-visible operations.
## Verification
- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.
- Related tests observed by source search:
- `tests/test_default_prompt_budget.py`
## Child DOX Index
No child DOX files.

41
tools/document_query.py.dox.md Normal file
View file

@ -0,0 +1,41 @@
# document_query.py DOX
## Purpose
- Own the `document_query.py` agent tool.
- This module loads and queries documents through the document query plugin compatibility path.
- Keep this file-level DOX profile synchronized with `document_query.py` because this directory is intentionally flat.
## Ownership
- `document_query.py` owns the runtime implementation.
- `document_query.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
## Runtime Contracts
- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.
- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.
- Observed side-effect areas: plugin state.
- Imported dependency areas include: `plugins._document_query.tools.document_query`.
## Key Concepts
- This module is primarily declarative or delegates behavior through classes/imported objects.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Keep tool output concise, model-readable, and safe for history persistence.
- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.
- Respect intervention flow for long-running, external, or user-visible operations.
## Verification
- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.
- Related tests observed by source search:
- `tests/test_document_query_fallback.py`
- `tests/test_document_query_plugin.py`
## Child DOX Index
No child DOX files.

44
tools/notify_user.py.dox.md Normal file
View file

@ -0,0 +1,44 @@
# notify_user.py DOX
## Purpose
- Own the `notify_user.py` agent tool.
- This module sends a user-facing notification from the agent.
- Keep this file-level DOX profile synchronized with `notify_user.py` because this directory is intentionally flat.
## Ownership
- `notify_user.py` owns the runtime implementation.
- `notify_user.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `NotifyUserTool` (`Tool`)
- `async execute(self, **kwargs)`
## Runtime Contracts
- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.
- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.
- `NotifyUserTool` is a `Tool`.
- `NotifyUserTool` defines `execute(...)`.
- Imported dependency areas include: `agent`, `helpers.notification`, `helpers.tool`.
## Key Concepts
- Important called helpers/classes observed in the source: `AgentContext.get_notification_manager.add_notification`, `Response`, `NotificationType`, `NotificationPriority`, `AgentContext.get_notification_manager`, `self.agent.read_prompt`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Keep tool output concise, model-readable, and safe for history persistence.
- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.
- Respect intervention flow for long-running, external, or user-visible operations.
## Verification
- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.
- Related tests observed by source search:
- `tests/test_tool_action_contracts.py`
## Child DOX Index
No child DOX files.

53
tools/response.py.dox.md Normal file
View file

@ -0,0 +1,53 @@
# response.py DOX
## Purpose
- Own the `response.py` agent tool.
- This module emits the final or intermediate agent response to the user.
- Keep this file-level DOX profile synchronized with `response.py` because this directory is intentionally flat.
## Ownership
- `response.py` owns the runtime implementation.
- `response.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `ResponseTool` (`Tool`)
- `async execute(self, **kwargs)`
- `async before_execution(self, **kwargs)`
- `async after_execution(self, response, **kwargs)`
## Runtime Contracts
- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.
- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.
- `ResponseTool` is a `Tool`.
- `ResponseTool` defines `execute(...)`.
- Imported dependency areas include: `helpers.tool`.
## Key Concepts
- Important called helpers/classes observed in the source: `Response`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Keep tool output concise, model-readable, and safe for history persistence.
- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.
- Respect intervention flow for long-running, external, or user-visible operations.
## Verification
- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.
- Related tests observed by source search:
- `tests/chunk_parser_test.py`
- `tests/rate_limiter_test.py`
- `tests/test_browser_agent_regressions.py`
- `tests/test_chat_compaction.py`
- `tests/test_dirty_json.py`
- `tests/test_download_toast_regressions.py`
- `tests/test_fasta2a_client.py`
- `tests/test_fastmcp_openapi_security.py`
## Child DOX Index
No child DOX files.

63
tools/scheduler.py.dox.md Normal file
View file

@ -0,0 +1,63 @@
# scheduler.py DOX
## Purpose
- Own the `scheduler.py` agent tool.
- This module creates, updates, lists, runs, waits for, and deletes scheduled/planned/adhoc tasks.
- Keep this file-level DOX profile synchronized with `scheduler.py` because this directory is intentionally flat.
## Ownership
- `scheduler.py` owns the runtime implementation.
- `scheduler.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `SchedulerTool` (`Tool`)
- `async execute(self, **kwargs)`
- `async list_tasks(self, **kwargs) -> Response`
- `async find_task_by_name(self, **kwargs) -> Response`
- `async show_task(self, **kwargs) -> Response`
- `async run_task(self, **kwargs) -> Response`
- `async delete_task(self, **kwargs) -> Response`
- `async update_task(self, **kwargs) -> Response`
- `async create_scheduled_task(self, **kwargs) -> Response`
- Top-level functions:
- `_current_action(tool: Tool, kwargs: dict) -> str`
- `_normalize_timezone(value: Any) -> str | None`
- `_schedule_timezone(kwargs: dict) -> str | None`
- `_task_schedule_from_input(schedule: Any, timezone: str | None=...) -> TaskSchedule`
- `_validate_task_schedule(task_schedule: TaskSchedule) -> str`
- `_task_plan_from_input(plan: Any) -> tuple[TaskPlan | None, str]`
- Notable constants/configuration names: `DEFAULT_WAIT_TIMEOUT`, `LOCAL_TIMEZONE_ALIASES`.
## Runtime Contracts
- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.
- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.
- `SchedulerTool` is a `Tool`.
- `SchedulerTool` defines `execute(...)`.
- Observed side-effect areas: filesystem writes, filesystem deletion, settings/state persistence, secret handling, scheduler state.
- Imported dependency areas include: `agent`, `asyncio`, `datetime`, `helpers`, `helpers.localization`, `helpers.projects`, `helpers.task_scheduler`, `helpers.tool`, `json`, `pytz`, `random`, `re`, `typing`.
## Key Concepts
- Important called helpers/classes observed in the source: `str.strip.lower.replace`, `str.strip`, `_normalize_timezone`, `TaskSchedule`, `task_schedule.to_crontab`, `timezone_name.lower`, `Localization.get.get_timezone`, `pytz.timezone`, `schedule.split`, `re.match`, `parse_datetime`, `TaskPlan.create`, `_current_action`, `get_context_project_name`, `TaskScheduler.get.get_tasks`, `Response`, `TaskScheduler.get.find_task_by_name`, `TaskScheduler.get.get_task_by_uuid`, `scheduler.get_task_by_uuid`, `self._resolve_project_metadata`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Keep tool output concise, model-readable, and safe for history persistence.
- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.
- Respect intervention flow for long-running, external, or user-visible operations.
## Verification
- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.
- Related tests observed by source search:
- `tests/test_task_scheduler_timezone.py`
- `tests/test_timezone_regressions.py`
- `tests/test_tool_action_contracts.py`
- `tests/test_tool_request_normalization.py`
## Child DOX Index
No child DOX files.

46
tools/search_engine.py.dox.md Normal file
View file

@ -0,0 +1,46 @@
# search_engine.py DOX
## Purpose
- Own the `search_engine.py` agent tool.
- This module runs web search through the configured search helper.
- Keep this file-level DOX profile synchronized with `search_engine.py` because this directory is intentionally flat.
## Ownership
- `search_engine.py` owns the runtime implementation.
- `search_engine.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `SearchEngine` (`Tool`)
- `async execute(self, query=..., **kwargs)`
- `async searxng_search(self, question)`
- `format_result_searxng(self, result, source)`
- Notable constants/configuration names: `SEARCH_ENGINE_RESULTS`.
## Runtime Contracts
- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.
- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.
- `SearchEngine` is a `Tool`.
- `SearchEngine` defines `execute(...)`.
- Imported dependency areas include: `asyncio`, `helpers`, `helpers.errors`, `helpers.print_style`, `helpers.searxng`, `helpers.tool`, `os`.
## Key Concepts
- Important called helpers/classes observed in the source: `Response`, `self.format_result_searxng`, `join.strip`, `self.searxng_search`, `self.agent.handle_intervention`, `searxng`, `handle_error`, `join`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Keep tool output concise, model-readable, and safe for history persistence.
- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.
- Respect intervention flow for long-running, external, or user-visible operations.
## Verification
- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.
- No direct test reference was found by name search; choose the nearest behavioral test or perform a focused smoke check.
## Child DOX Index
No child DOX files.

51
tools/skills_tool.py.dox.md Normal file
View file

@ -0,0 +1,51 @@
# skills_tool.py DOX
## Purpose
- Own the `skills_tool.py` agent tool.
- This module searches, loads, and lists Agent Zero skills for the agent.
- Keep this file-level DOX profile synchronized with `skills_tool.py` because this directory is intentionally flat.
## Ownership
- `skills_tool.py` owns the runtime implementation.
- `skills_tool.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `SkillsTool` (`Tool`)
- `get_log_object(self)`
- `async before_execution(self, **kwargs)`
- `async execute(self, **kwargs) -> Response`
- Top-level functions:
- `max_loaded_skills() -> int`
- Notable constants/configuration names: `DATA_NAME_LOADED_SKILLS`.
## Runtime Contracts
- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.
- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.
- `SkillsTool` is a `Tool`.
- `SkillsTool` defines `execute(...)`.
- Observed side-effect areas: filesystem reads, filesystem deletion, settings/state persistence.
- Imported dependency areas include: `__future__`, `helpers`, `helpers.print_style`, `helpers.tool`, `pathlib`, `typing`.
## Key Concepts
- Important called helpers/classes observed in the source: `str.strip.lower.replace`, `skill_name.strip`, `super.get_log_object`, `self._normalize_skill_name`, `self.get_log_object`, `skills_helper.list_skills`, `join`, `skills_helper.search_skills`, `skills_helper.find_skill`, `skill.path.resolve`, `Path`, `resolved.read_text`, `skill_name.startswith`, `skill_name.endswith`, `self._current_action`, `self.agent.context.log.log`, `Response`, `strip`, `loaded.remove`, `target.is_absolute`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Keep tool output concise, model-readable, and safe for history persistence.
- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.
- Respect intervention flow for long-running, external, or user-visible operations.
## Verification
- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.
- Related tests observed by source search:
- `tests/test_document_query_plugin.py`
- `tests/test_tool_action_contracts.py`
## Child DOX Index
No child DOX files.

48
tools/unknown.py.dox.md Normal file
View file

@ -0,0 +1,48 @@
# unknown.py DOX
## Purpose
- Own the `unknown.py` agent tool.
- This module handles unknown or malformed tool-call requests.
- Keep this file-level DOX profile synchronized with `unknown.py` because this directory is intentionally flat.
## Ownership
- `unknown.py` owns the runtime implementation.
- `unknown.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `Unknown` (`Tool`)
- `async execute(self, **kwargs)`
## Runtime Contracts
- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.
- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.
- `Unknown` is a `Tool`.
- `Unknown` defines `execute(...)`.
- Imported dependency areas include: `extensions.python.system_prompt._11_tools_prompt`, `helpers.tool`.
## Key Concepts
- Important called helpers/classes observed in the source: `Response`, `build_tools_prompt`, `self.agent.read_prompt`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Keep tool output concise, model-readable, and safe for history persistence.
- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.
- Respect intervention flow for long-running, external, or user-visible operations.
## Verification
- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.
- Related tests observed by source search:
- `tests/test_file_tree_visualize.py`
- `tests/test_oauth_providers.py`
- `tests/test_socketio_unknown_namespace.py`
- `tests/test_tunnel_remote_link.py`
- `tests/test_ws_manager.py`
## Child DOX Index
No child DOX files.

50
tools/vision_load.py.dox.md Normal file
View file

@ -0,0 +1,50 @@
# vision_load.py DOX
## Purpose
- Own the `vision_load.py` agent tool.
- This module loads images into model-visible content for vision-capable models.
- Keep this file-level DOX profile synchronized with `vision_load.py` because this directory is intentionally flat.
## Ownership
- `vision_load.py` owns the runtime implementation.
- `vision_load.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `VisionLoad` (`Tool`)
- `async execute(self, paths: list[str]=..., **kwargs) -> Response`
- `async after_execution(self, response: Response, **kwargs)`
- Notable constants/configuration names: `TOKENS_ESTIMATE`.
## Runtime Contracts
- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.
- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.
- `VisionLoad` is a `Tool`.
- `VisionLoad` defines `execute(...)`.
- Observed side-effect areas: filesystem writes, model calls, plugin state, settings/state persistence, secret handling.
- Imported dependency areas include: `helpers`, `helpers.print_style`, `helpers.tool`, `mimetypes`.
## Key Concepts
- Important called helpers/classes observed in the source: `self._get_max_embeds`, `Response`, `str.strip`, `self._context_id`, `chat_media.infer_source`, `chat_media.category_for_source`, `chat_media.save_image_base64`, `chat_media.save_image_data_url`, `chat_media.materialize_image_ref`, `str.strip.lower`, `ephemeral_images.is_ref`, `cls._is_data_image_url`, `self._is_data_image_url`, `plugins.get_plugin_config`, `images.to_data_url`, `normalized.startswith`, `ephemeral_images.display_ref`, `join`, `self.agent.hist_add_tool_result`, `history.RawMessage`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Keep tool output concise, model-readable, and safe for history persistence.
- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.
- Respect intervention flow for long-running, external, or user-visible operations.
## Verification
- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.
- Related tests observed by source search:
- `tests/test_browser_agent_regressions.py`
- `tests/test_host_browser_connector.py`
- `tests/test_office_desktop_state.py`
- `tests/test_vision_load_image_refs.py`
## Child DOX Index
No child DOX files.

54
tools/wait.py.dox.md Normal file
View file

@ -0,0 +1,54 @@
# wait.py DOX
## Purpose
- Own the `wait.py` agent tool.
- This module lets the agent wait for a managed duration while respecting intervention flow.
- Keep this file-level DOX profile synchronized with `wait.py` because this directory is intentionally flat.
## Ownership
- `wait.py` owns the runtime implementation.
- `wait.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `WaitTool` (`Tool`)
- `async execute(self, **kwargs) -> Response`
- `get_log_object(self)`
- `get_heading(self, text: str=..., done: bool=...)`
## Runtime Contracts
- Tool modules must define `helpers.tool.Tool` subclasses and return `helpers.tool.Response` from `execute(...)`.
- Update this file whenever tool arguments, output shape, `break_loop` behavior, intervention handling, prompt instructions, or side effects change.
- `WaitTool` is a `Tool`.
- `WaitTool` defines `execute(...)`.
- Observed side-effect areas: settings/state persistence.
- Imported dependency areas include: `asyncio`, `datetime`, `helpers.localization`, `helpers.print_style`, `helpers.tool`, `helpers.wait`.
## Key Concepts
- Important called helpers/classes observed in the source: `Localization.get.now`, `PrintStyle.info`, `self.agent.read_prompt`, `Response`, `self.agent.context.log.log`, `self.agent.handle_intervention`, `timedelta`, `managed_wait`, `Localization.get.localtime_str_to_utc_dt`, `wait_duration.total_seconds`, `Localization.get.serialize_datetime`, `self.get_heading`, `ValueError`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Keep tool output concise, model-readable, and safe for history persistence.
- Coordinate argument or behavior changes with prompt tool instructions and skill guidance.
- Respect intervention flow for long-running, external, or user-visible operations.
## Verification
- Run targeted tool and prompt-contract tests for changed behavior; smoke-test agent execution when no focused test exists.
- Related tests observed by source search:
- `tests/email_parser_test.py`
- `tests/rate_limiter_test.py`
- `tests/test_api_chat_lifetime.py`
- `tests/test_browser_agent_regressions.py`
- `tests/test_chat_compaction.py`
- `tests/test_default_prompt_budget.py`
- `tests/test_document_query_plugin.py`
- `tests/test_download_toast_regressions.py`
## Child DOX Index
No child DOX files.