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
helpers/AGENTS.md
View file

@ -18,17 +18,23 @@
- Project metadata defaults must remain backwards-compatible; missing `include_agents_md` is treated as enabled and project instruction file content is injected with an explicit source path.
- Do not hardcode secrets, provider keys, local absolute paths, or environment-specific values.
- Use `RepairableException` for errors an agent may be able to fix.
- This directory is a file-documented DOX profile: every direct `*.py` helper 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 helper purpose, public classes/functions, cross-module contracts, persistence or side effects, path/security assumptions, important dependencies, and verification guidance.
- When a helper 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 helper deletion or rename.
## Work Guidance
- Prefer cohesive helper modules over adding unrelated utilities to large files.
- Keep imports acyclic where possible; defer imports inside functions only when needed to avoid startup cycles.
- For changes touching auth, CSRF, files, plugins, tunnels, WebSockets, or model calls, read the caller and tests before editing.
- During the DOX pass, verify that every direct `*.py` file has a matching `*.py.dox.md` and that changed helper behavior is described there.
## Verification
- Run targeted tests for changed helper modules.
- Run security regression tests for auth, CSRF, filesystem, WebSocket, tunnel, upload, or image-serving changes.
- Check file-level documentation coverage with a script or shell loop that verifies each `helpers/*.py` has a matching `helpers/*.py.dox.md`.
## Child DOX Index

71
helpers/api.py.dox.md Normal file
View file

@ -0,0 +1,71 @@
# api.py DOX
## Purpose
- Own the `api.py` helper module.
- This module defines API handler registration, request security gates, CSRF checks, and watchdog registration.
- Keep this file-level DOX profile synchronized with `api.py` because this directory is intentionally flat.
## Ownership
- `api.py` owns the runtime implementation.
- `api.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `ApiHandler` (no explicit base class)
- `requires_loopback(cls) -> bool`
- `requires_api_key(cls) -> bool`
- `requires_auth(cls) -> bool`
- `get_methods(cls) -> list[str]`
- `requires_csrf(cls) -> bool`
- `async process(self, input: Input, request: Request) -> Output`
- `async handle_request(self, request: Request) -> Response`
- `use_context(self, ctxid: str, create_if_not_exists: bool=...)`
- Top-level functions:
- `requires_api_key(f)`
- `requires_loopback(f)`
- `requires_auth(f)`
- `csrf_protect(f)`
- `register_api_route(app: Flask, lock: ThreadLockType) -> None`
- `register_watchdogs()`
- Notable constants/configuration names: `CACHE_AREA`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- `ApiHandler` defines `process(...)`.
- `ApiHandler` defines `get_methods(...)`.
- `ApiHandler` defines `requires_auth(...)`.
- `ApiHandler` defines `requires_csrf(...)`.
- `ApiHandler` defines `requires_api_key(...)`.
- `ApiHandler` defines `requires_loopback(...)`.
- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, WebSocket state, plugin state, settings/state persistence, secret handling.
- Imported dependency areas include: `abc`, `flask`, `functools`, `helpers`, `helpers.errors`, `helpers.network`, `helpers.print_style`, `json`, `pathlib`, `threading`, `typing`, `werkzeug.wrappers.response`.
## Key Concepts
- Important called helpers/classes observed in the source: `wraps`, `app.add_url_rule`, `watchdog.add_watchdog`, `cls.requires_auth`, `_use_context`, `login.get_credentials_hash`, `files.get_abs_path`, `handler_cls.requires_csrf`, `handler_cls.requires_api_key`, `handler_cls.requires_auth`, `handler_cls.requires_loopback`, `cache.add`, `PrintStyle.debug`, `cache.clear`, `get_settings`, `f`, `is_loopback_address`, `Response`, `redirect`, `files.is_in_dir`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_api_chat_lifetime.py`
- `tests/test_browser_agent_regressions.py`
- `tests/test_download_toast_regressions.py`
- `tests/test_fasta2a_client.py`
- `tests/test_fastmcp_openapi_security.py`
- `tests/test_host_browser_connector.py`
- `tests/test_image_get_security.py`
- `tests/test_model_config_api_keys.py`
## Child DOX Index
No child DOX files.

47
helpers/attachment_manager.py.dox.md Normal file
View file

@ -0,0 +1,47 @@
# attachment_manager.py DOX
## Purpose
- Own the `attachment_manager.py` helper module.
- This module tracks uploaded or generated attachments associated with chat contexts.
- Keep this file-level DOX profile synchronized with `attachment_manager.py` because this directory is intentionally flat.
## Ownership
- `attachment_manager.py` owns the runtime implementation.
- `attachment_manager.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `AttachmentManager` (no explicit base class)
- `is_allowed_file(self, filename: str) -> bool`
- `get_file_type(self, filename: str) -> str`
- `get_file_extension(filename: str) -> str`
- `validate_mime_type(self, file) -> bool`
- `save_file(self, file: FileStorage, name: str) -> Tuple[str, Dict]`
- `generate_image_preview(self, image_path: str, max_size: int=...) -> Optional[str]`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, filesystem writes, settings/state persistence.
- Imported dependency areas include: `PIL`, `base64`, `helpers.print_style`, `helpers.security`, `io`, `os`, `typing`, `werkzeug.datastructures`.
## Key Concepts
- Important called helpers/classes observed in the source: `os.makedirs`, `self.get_file_extension`, `set.union`, `filename.rsplit.lower`, `safe_filename`, `os.path.join`, `self.get_file_type`, `file.save`, `ValueError`, `self.generate_image_preview`, `PrintStyle.error`, `img.thumbnail`, `io.BytesIO`, `img.save`, `base64.b64encode.decode`, `mime_type.split`, `img.convert`, `filename.rsplit`, `base64.b64encode`, `buffer.getvalue`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- 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.

50
helpers/backup.py.dox.md Normal file
View file

@ -0,0 +1,50 @@
# backup.py DOX
## Purpose
- Own the `backup.py` helper module.
- This module builds, inspects, previews, tests, and restores Agent Zero backup archives.
- Keep this file-level DOX profile synchronized with `backup.py` because this directory is intentionally flat.
## Ownership
- `backup.py` owns the runtime implementation.
- `backup.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `BackupService` (no explicit base class)
- `get_default_backup_metadata(self) -> Dict[str, Any]`
- `async test_patterns(self, metadata: Dict[str, Any], max_files: int=...) -> List[Dict[str, Any]]`
- `async create_backup(self, include_patterns: List[str], exclude_patterns: List[str], include_hidden: bool=..., backup_name: str=...) -> str`
- `async inspect_backup(self, backup_file) -> Dict[str, Any]`
- `async preview_restore(self, backup_file, restore_include_patterns: Optional[List[str]]=..., restore_exclude_patterns: Optional[List[str]]=..., overwrite_policy: str=..., clean_before_restore: bool=..., user_edited_metadata: Optional[Dict[str, Any]]=...) -> Dict[str, Any]`
- `async restore_backup(self, backup_file, restore_include_patterns: Optional[List[str]]=..., restore_exclude_patterns: Optional[List[str]]=..., overwrite_policy: str=..., clean_before_restore: bool=..., user_edited_metadata: Optional[Dict[str, Any]]=...) -> Dict[str, Any]`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, settings/state persistence, secret handling.
- Imported dependency areas include: `datetime`, `helpers`, `helpers.localization`, `helpers.print_style`, `json`, `os`, `pathspec`, `platform`, `tempfile`, `typing`, `zipfile`.
## Key Concepts
- Important called helpers/classes observed in the source: `self._get_agent_zero_version`, `files.get_abs_path`, `Localization.get.now_iso`, `self._get_default_patterns`, `self._parse_patterns`, `self.agent_zero_root.rstrip`, `patterns.split`, `join`, `file_path.lstrip`, `backed_up_agent_root.rstrip`, `current_agent_root.rstrip`, `self._patterns_to_string`, `self._get_explicit_patterns`, `tempfile.mkdtemp`, `os.path.join`, `self._translate_patterns`, `git.get_git_info`, `line.strip`, `line.startswith`, `getpass.getuser`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_download_toast_regressions.py`
- `tests/test_office_document_store.py`
- `tests/test_self_update_tag_filter.py`
## Child DOX Index
No child DOX files.

46
helpers/browser.py.dox.md Normal file
View file

@ -0,0 +1,46 @@
# browser.py DOX
## Purpose
- Own the `browser.py` helper module.
- This module holds shared browser helper state used by browser-facing integrations.
- Keep this file-level DOX profile synchronized with `browser.py` because this directory is intentionally flat.
## Ownership
- `browser.py` owns the runtime implementation.
- `browser.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, filesystem deletion.
## 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
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_a0_connector_prompt_gating.py`
- `tests/test_browser_agent_regressions.py`
- `tests/test_download_toast_regressions.py`
- `tests/test_host_browser_connector.py`
- `tests/test_oauth_gemini_api.py`
- `tests/test_oauth_providers.py`
- `tests/test_oauth_static.py`
- `tests/test_oauth_xai_grok.py`
## Child DOX Index
No child DOX files.

64
helpers/cache.py.dox.md Normal file
View file

@ -0,0 +1,64 @@
# cache.py DOX
## Purpose
- Own the `cache.py` helper module.
- This module provides in-process cache areas with optional global and area toggles.
- Keep this file-level DOX profile synchronized with `cache.py` because this directory is intentionally flat.
## Ownership
- `cache.py` owns the runtime implementation.
- `cache.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `CacheEntry` (no explicit base class)
- Top-level functions:
- `toggle_global(enabled: bool) -> None`
- `toggle_area(area: str, enabled: bool) -> None`
- `has(area: str, key: Any) -> bool`
- `add(area: str, key: Any, data: Any) -> None`
- `get(area: str, key: Any, default: Any=...) -> Any`
- `remove(area: str, key: Any) -> None`
- `clear(area: str) -> None`
- `trim_cache(area: str, seconds: float=...) -> None`
- `clear_all() -> None`
- `_is_enabled(area: str) -> bool`
- `_create_entry(value: Any) -> CacheEntry`
- `_touch_entry(entry: CacheEntry) -> None`
- `_get_matching_areas(area: str) -> list[str]`
- `determine_cache_key(agent, *additional)`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem deletion, plugin state, settings/state persistence.
- Imported dependency areas include: `dataclasses`, `fnmatch`, `threading`, `time`, `typing`.
## Key Concepts
- Important called helpers/classes observed in the source: `threading.RLock`, `dataclass`, `CacheEntry`, `time.time`, `_is_enabled`, `_touch_entry`, `_create_entry`, `_cache.pop`, `_get_matching_areas`, `_cache.clear`, `agent.context.get_data`, `area_cache.pop`, `fnmatch.fnmatch`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_browser_agent_regressions.py`
- `tests/test_file_tree_visualize.py`
- `tests/test_office_canvas_setup.py`
- `tests/test_office_document_store.py`
- `tests/test_self_update_tag_filter.py`
- `tests/test_time_travel.py`
- `tests/test_webui_extension_surfaces.py`
- `tests/test_whatsapp_bridge_manager.py`
## Child DOX Index
No child DOX files.

43
helpers/call_llm.py.dox.md Normal file
View file

@ -0,0 +1,43 @@
# call_llm.py DOX
## Purpose
- Own the `call_llm.py` helper module.
- This module wraps LiteLLM/model calls with examples, streaming, and extension hooks.
- Keep this file-level DOX profile synchronized with `call_llm.py` because this directory is intentionally flat.
## Ownership
- `call_llm.py` owns the runtime implementation.
- `call_llm.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `Example` (`TypedDict`)
- Top-level functions:
- `async call_llm(system: str, model: BaseChatModel | BaseLLM, message: str, examples: list[Example]=..., callback: Callable[[str], None] | None=...)`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: model calls.
- Imported dependency areas include: `langchain.prompts`, `langchain.schema`, `langchain_core.language_models.chat_models`, `langchain_core.language_models.llms`, `langchain_core.messages`, `typing`.
## Key Concepts
- Important called helpers/classes observed in the source: `ChatPromptTemplate.from_messages`, `FewShotChatMessagePromptTemplate`, `few_shot_prompt.format`, `chain.astream`, `HumanMessage`, `AIMessage`, `SystemMessage`, `callback`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- 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.

60
helpers/chat_media.py.dox.md Normal file
View file

@ -0,0 +1,60 @@
# chat_media.py DOX
## Purpose
- Own the `chat_media.py` helper module.
- This module materializes, stores, and resolves chat-scoped image/media artifacts.
- Keep this file-level DOX profile synchronized with `chat_media.py` because this directory is intentionally flat.
## Ownership
- `chat_media.py` owns the runtime implementation.
- `chat_media.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `ChatImage` (no explicit base class)
- Top-level functions:
- `screenshot_dir(context_id: str, source: str) -> Path`
- `artifact_dir(context_id: str, category: ImageCategory=..., source: str=...) -> Path`
- `save_image_bytes(context_id: str, payload: bytes, mime_type: str=..., category: ImageCategory=..., source: str=..., preferred_name: str=..., max_bytes: int | None=...) -> ChatImage`
- `save_image_base64(context_id: str, data: str, mime_type: str=..., category: ImageCategory=..., source: str=..., preferred_name: str=..., max_bytes: int | None=...) -> ChatImage`
- `save_image_file(context_id: str, path: str | Path, category: ImageCategory=..., source: str=..., preferred_name: str=..., max_bytes: int | None=...) -> ChatImage`
- `save_image_data_url(context_id: str, data_url: str, category: ImageCategory=..., source: str=..., preferred_name: str=..., max_bytes: int | None=...) -> ChatImage`
- `materialize_image_ref(context_id: str, url: str, source: str=..., preferred_name: str=..., max_bytes: int | None=...) -> str`
- `is_chat_scoped_path(context_id: str, path: str | Path) -> bool`
- `infer_source(value: str=..., preferred_name: str=...) -> str`
- `category_for_source(source: str) -> ImageCategory`
- `_guess_image_mime(path: Path) -> str`
- `_is_data_image_url(value: str) -> bool`
- `_split_image_data_url(data_url: str) -> tuple[str, str]`
- Notable constants/configuration names: `DEFAULT_MAX_IMAGE_BYTES`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion.
- Imported dependency areas include: `__future__`, `dataclasses`, `helpers`, `pathlib`, `time`, `typing`, `uuid`.
## Key Concepts
- Important called helpers/classes observed in the source: `dataclass`, `artifact_dir`, `bytes`, `media_artifacts.normalize_mime`, `media_artifacts.guess_extension`, `media_artifacts.safe_filename`, `Path`, `time.strftime`, `path.parent.mkdir`, `path.write_bytes`, `ChatImage`, `media_artifacts.decode_base64_payload`, `save_image_bytes`, `image_path.read_bytes`, `_split_image_data_url`, `save_image_base64`, `str.strip`, `category_for_source`, `_is_data_image_url`, `images.resolve_ref`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_browser_agent_regressions.py`
- `tests/test_host_browser_connector.py`
- `tests/test_tool_action_contracts.py`
- `tests/test_vision_load_image_refs.py`
## Child DOX Index
No child DOX files.

54
helpers/cli_tunnel.py.dox.md Normal file
View file

@ -0,0 +1,54 @@
# cli_tunnel.py DOX
## Purpose
- Own the `cli_tunnel.py` helper module.
- This module provides shared download and install mechanics for CLI-based tunnel providers.
- Keep this file-level DOX profile synchronized with `cli_tunnel.py` because this directory is intentionally flat.
## Ownership
- `cli_tunnel.py` owns the runtime implementation.
- `cli_tunnel.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `CliTunnelHelper` (`TunnelHelper`)
- `start(self)`
- `stop(self)`
- Top-level functions:
- `executable_name(name)`
- `chmod_executable(path)`
- `notify_download(notify, message, data=...)`
- `notify_download_complete(notify, message, data=...)`
- `download_file(url, destination, notify=...)`
- `platform_parts()`
- `extract_named_members_from_tar(archive_path, destination_dir, member_names)`
- `extract_named_members_from_zip(archive_path, destination_dir, member_names)`
- Notable constants/configuration names: `RUNTIME_BIN_DIR`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, network calls, subprocess/runtime control, tunnel state.
- Imported dependency areas include: `collections`, `flaredantic`, `helpers`, `helpers.tunnel_common`, `os`, `pathlib`, `platform`, `queue`, `shutil`, `subprocess`, `tarfile`, `tempfile`, `threading`, `time`, `urllib.request`, `zipfile`.
## Key Concepts
- Important called helpers/classes observed in the source: `Path`, `files.get_abs_path`, `callable`, `destination.parent.mkdir`, `notify_download`, `tempfile.mkstemp`, `os.close`, `platform.system.lower`, `platform.machine.lower`, `destination_dir.mkdir`, `path.chmod`, `notify`, `temp_path.replace`, `notify_download_complete`, `RuntimeError`, `archive.getmembers`, `zipfile.ZipFile`, `archive.infolist`, `super.__init__`, `self.url_pattern.search`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_tunnel_remote_link.py`
## Child DOX Index
No child DOX files.

43
helpers/cloudflare_tunnel.py.dox.md Normal file
View file

@ -0,0 +1,43 @@
# cloudflare_tunnel.py DOX
## Purpose
- Own the `cloudflare_tunnel.py` helper module.
- This module implements Cloudflare tunnel provider lifecycle behavior.
- Keep this file-level DOX profile synchronized with `cloudflare_tunnel.py` because this directory is intentionally flat.
## Ownership
- `cloudflare_tunnel.py` owns the runtime implementation.
- `cloudflare_tunnel.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `CloudflareTunnel` (`FlaredanticTunnelHelper`)
- `build_tunnel(self)`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: settings/state persistence, tunnel state.
- Imported dependency areas include: `flaredantic`, `helpers.tunnel_common`.
## Key Concepts
- Important called helpers/classes observed in the source: `FlareConfig`, `FlareTunnel`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_tunnel_remote_link.py`
## Child DOX Index
No child DOX files.

54
helpers/context.py.dox.md Normal file
View file

@ -0,0 +1,54 @@
# context.py DOX
## Purpose
- Own the `context.py` helper module.
- This module provides compatibility helpers for reading and writing `AgentContext` data.
- Keep this file-level DOX profile synchronized with `context.py` because this directory is intentionally flat.
## Ownership
- `context.py` owns the runtime implementation.
- `context.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Top-level functions:
- `_ensure_context() -> Dict[str, Any]`: Make sure a context dict exists, and return it.
- `set_context_data(key: str, value: Any)`: Set context data for the current async/task context.
- `delete_context_data(key: str)`: Delete a key from the current async/task context.
- `get_context_data(key: Optional[str]=..., default: T=...) -> T`: Get a key from the current context, or the full dict if key is None.
- `clear_context_data()`: Completely clear the context dict.
- Notable constants/configuration names: `T`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem deletion, scheduler state.
- Imported dependency areas include: `contextvars`, `typing`.
## Key Concepts
- Important called helpers/classes observed in the source: `TypeVar`, `ContextVar`, `_ensure_context`, `cast`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_a0_connector_prompt_gating.py`
- `tests/test_api_chat_lifetime.py`
- `tests/test_browser_agent_regressions.py`
- `tests/test_document_query_plugin.py`
- `tests/test_error_retry_plugin.py`
- `tests/test_extensions_stress.py`
- `tests/test_file_tree_visualize.py`
- `tests/test_history_compression_wait.py`
## Child DOX Index
No child DOX files.

41
helpers/context_utils.py.dox.md Normal file
View file

@ -0,0 +1,41 @@
# context_utils.py DOX
## Purpose
- Own the `context_utils.py` helper module.
- This module provides context managers/utilities for current context binding.
- Keep this file-level DOX profile synchronized with `context_utils.py` because this directory is intentionally flat.
## Ownership
- `context_utils.py` owns the runtime implementation.
- `context_utils.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Top-level functions:
- `use_context(lock: ThreadLockType, ctxid: str, create_if_not_exists: bool=...)`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: WebSocket state, settings/state persistence.
- Imported dependency areas include: `threading`, `typing`.
## Key Concepts
- Important called helpers/classes observed in the source: `AgentContext.use`, `AgentContext.first`, `AgentContext`, `Exception`, `initialize_agent`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- 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.

48
helpers/crypto.py.dox.md Normal file
View file

@ -0,0 +1,48 @@
# crypto.py DOX
## Purpose
- Own the `crypto.py` helper module.
- This module hashes, verifies, encrypts, and decrypts data for signed or protected payloads.
- Keep this file-level DOX profile synchronized with `crypto.py` because this directory is intentionally flat.
## Ownership
- `crypto.py` owns the runtime implementation.
- `crypto.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Top-level functions:
- `hash_data(data: str, password: str)`
- `verify_data(data: str, hash: str, password: str)`
- `_generate_private_key()`
- `_generate_public_key(private_key: rsa.RSAPrivateKey)`
- `_decode_public_key(public_key: str) -> rsa.RSAPublicKey`
- `encrypt_data(data: str, public_key_pem: str)`
- `_encrypt_data(data: bytes, public_key: rsa.RSAPublicKey)`
- `decrypt_data(data: str, private_key: rsa.RSAPrivateKey)`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: secret handling.
- Imported dependency areas include: `cryptography.hazmat.primitives`, `cryptography.hazmat.primitives.asymmetric`, `hashlib`, `hmac`, `os`.
## Key Concepts
- Important called helpers/classes observed in the source: `hmac.new.hexdigest`, `rsa.generate_private_key`, `private_key.public_key.public_bytes.hex`, `bytes.fromhex`, `serialization.load_pem_public_key`, `_encrypt_data`, `public_key.encrypt`, `b.hex`, `private_key.decrypt`, `b.decode`, `hash_data`, `TypeError`, `data.encode`, `_decode_public_key`, `padding.OAEP`, `hmac.new`, `private_key.public_key.public_bytes`, `password.encode`, `padding.MGF1`, `hashes.SHA256`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- 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.

55
helpers/defer.py.dox.md Normal file
View file

@ -0,0 +1,55 @@
# defer.py DOX
## Purpose
- Own the `defer.py` helper module.
- This module runs deferred or child async tasks on managed event-loop threads.
- Keep this file-level DOX profile synchronized with `defer.py` because this directory is intentionally flat.
## Ownership
- `defer.py` owns the runtime implementation.
- `defer.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `EventLoopThread` (no explicit base class)
- `terminate(self)`
- `run_coroutine(self, coro)`
- `ChildTask` (no explicit base class)
- `DeferredTask` (no explicit base class)
- `start_task(self, func: Callable[..., Coroutine[Any, Any, Any]], *args, **kwargs)`
- `is_ready(self) -> bool`
- `result_sync(self, timeout: Optional[float]=...) -> Any`
- `async result(self, timeout: Optional[float]=...) -> Any`
- `kill(self, terminate_thread: bool=...) -> None`
- `kill_children(self) -> None`
- `is_alive(self) -> bool`
- `restart(self, terminate_thread: bool=...) -> None`
- Notable constants/configuration names: `T`, `THREAD_BACKGROUND`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: scheduler state.
- Imported dependency areas include: `asyncio`, `concurrent.futures`, `dataclasses`, `threading`, `typing`.
## Key Concepts
- Important called helpers/classes observed in the source: `TypeVar`, `threading.Lock`, `self._start`, `asyncio.set_event_loop`, `self.loop.run_forever`, `loop.is_running`, `asyncio.run_coroutine_threadsafe`, `EventLoopThread`, `self._start_task`, `self.kill`, `self.event_loop_thread.run_coroutine`, `self.kill_children`, `asyncio.get_running_loop`, `func`, `asyncio.iscoroutine`, `Future`, `asyncio.wrap_future`, `asyncio.current_task`, `asyncio.new_event_loop`, `threading.Thread`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_office_document_store.py`
## Child DOX Index
No child DOX files.

74
helpers/dirty_json.py
View file

@ -214,7 +214,7 @@ class DirtyJson:
def _parse_key(self):
self._skip_whitespace()
if self.current_char in ['"', "'"]:
return self._parse_string()
return self._parse_string(is_key=True)
else:
return self._parse_unquoted_key()
@ -260,11 +260,18 @@ class DirtyJson:
self._pop_stack()
return
def _parse_string(self):
def _parse_string(self, is_key: bool = False):
result = ""
quote_char = self.current_char
self._advance() # Skip opening quote
while self.current_char is not None and self.current_char != quote_char:
while self.current_char is not None:
if self.current_char == quote_char:
if self._is_closing_quote(is_key):
break
result += self.current_char
self._advance()
continue
if self.current_char == "\\":
self._advance()
if self.current_char in ['"', "'", "\\", "/", "b", "f", "n", "r", "t"]:
@ -298,6 +305,67 @@ class DirtyJson:
self._advance() # Skip closing quote
return result
def _is_closing_quote(self, is_key: bool) -> bool:
next_index = self._skip_padding_from(self.index + 1)
if next_index >= len(self.json_string):
return True
next_char = self.json_string[next_index]
if is_key:
return next_char in [":", ",", "}", "]"]
if next_char in [",", "}", "]"]:
return True
return self._looks_like_missing_comma_before_key(next_index)
def _looks_like_missing_comma_before_key(self, index: int) -> bool:
if not self.stack or not isinstance(self.stack[-1], dict):
return False
if index >= len(self.json_string) or self.json_string[index] not in ['"', "'"]:
return False
quote_char = self.json_string[index]
index += 1
while index < len(self.json_string):
char = self.json_string[index]
if char == "\\":
index += 2
continue
if char == quote_char:
next_index = self._skip_padding_from(index + 1)
return (
next_index < len(self.json_string)
and self.json_string[next_index] == ":"
)
if char in ["\n", "\r", "{", "}", "[", "]", ","]:
return False
index += 1
return False
def _skip_padding_from(self, index: int) -> int:
while index < len(self.json_string):
char = self.json_string[index]
if char.isspace():
index += 1
elif char == "/" and index + 1 < len(self.json_string):
next_char = self.json_string[index + 1]
if next_char == "/":
index += 2
while index < len(self.json_string) and self.json_string[index] != "\n":
index += 1
elif next_char == "*":
end = self.json_string.find("*/", index + 2)
if end == -1:
return len(self.json_string)
index = end + 2
else:
break
else:
break
return index
def _parse_multiline_string(self):
result = ""
quote_char = self.current_char

51
helpers/dirty_json.py.dox.md Normal file
View file

@ -0,0 +1,51 @@
# dirty_json.py DOX
## Purpose
- Own the `dirty_json.py` helper module.
- This module parses and serializes relaxed JSON-like model output.
- Keep this file-level DOX profile synchronized with `dirty_json.py` because this directory is intentionally flat.
## Ownership
- `dirty_json.py` owns the runtime implementation.
- `dirty_json.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `DirtyJson` (no explicit base class)
- `parse_string(json_string)`
- `parse(self, json_string)`
- `feed(self, chunk)`
- `get_start_pos(self, input_str: str) -> int`
- Top-level functions:
- `try_parse(json_string: str)`
- `parse(json_string: str)`
- `stringify(obj, **kwargs)`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem writes, settings/state persistence.
- Imported dependency areas include: `json`.
## Key Concepts
- Important called helpers/classes observed in the source: `DirtyJson.parse_string`, `json.dumps`, `json.loads`, `self._reset`, `self.stack.pop`, `DirtyJson`, `parser.parse`, `self.get_start_pos`, `self._parse`, `self._advance`, `self._skip_whitespace`, `self._parse_object_content`, `self._parse_array_content`, `self._skip_padding_from`, `self._looks_like_missing_comma_before_key`, `result.strip`, `self.current_char.isspace`, `self._parse_value`, `self._continue_parsing`, `self._parse_object`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_dirty_json.py`
- `tests/test_projects.py`
## Child DOX Index
No child DOX files.

53
helpers/docker.py.dox.md Normal file
View file

@ -0,0 +1,53 @@
# docker.py DOX
## Purpose
- Own the `docker.py` helper module.
- This module manages Docker container operations used by runtime helpers.
- Keep this file-level DOX profile synchronized with `docker.py` because this directory is intentionally flat.
## Ownership
- `docker.py` owns the runtime implementation.
- `docker.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `DockerContainerManager` (no explicit base class)
- `init_docker(self)`
- `cleanup_container(self) -> None`
- `get_image_containers(self)`
- `start_container(self) -> None`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, filesystem deletion, subprocess/runtime control, WebSocket state.
- Imported dependency areas include: `atexit`, `docker`, `helpers.errors`, `helpers.files`, `helpers.log`, `helpers.print_style`, `time`, `typing`.
## Key Concepts
- Important called helpers/classes observed in the source: `self.init_docker`, `PrintStyle.standard`, `self.client.containers.run`, `time.sleep`, `docker.from_env`, `self.container.stop`, `self.container.remove`, `existing_container.start`, `self.logger.log`, `format_error`, `PrintStyle.error`, `PrintStyle.hint`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_browser_agent_regressions.py`
- `tests/test_default_prompt_budget.py`
- `tests/test_docker_release_plan.py`
- `tests/test_document_query_plugin.py`
- `tests/test_host_browser_connector.py`
- `tests/test_model_search.py`
- `tests/test_office_canvas_setup.py`
- `tests/test_office_document_store.py`
## Child DOX Index
No child DOX files.

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

@ -0,0 +1,41 @@
# document_query.py DOX
## Purpose
- Own the `document_query.py` helper module.
- This module provides compatibility exports for document query behavior.
- 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
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: plugin state.
- Imported dependency areas include: `plugins._document_query.helpers.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
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- 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.

48
helpers/dotenv.py.dox.md Normal file
View file

@ -0,0 +1,48 @@
# dotenv.py DOX
## Purpose
- Own the `dotenv.py` helper module.
- This module loads and updates `.env` configuration values.
- Keep this file-level DOX profile synchronized with `dotenv.py` because this directory is intentionally flat.
## Ownership
- `dotenv.py` owns the runtime implementation.
- `dotenv.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Top-level functions:
- `load_dotenv()`
- `get_dotenv_file_path()`
- `get_dotenv_value(key: str, default: Any=...)`
- `save_dotenv_value(key: str, value: str)`
- Notable constants/configuration names: `KEY_AUTH_LOGIN`, `KEY_AUTH_PASSWORD`, `KEY_RFC_PASSWORD`, `KEY_ROOT_PASSWORD`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, filesystem writes, secret handling.
- Imported dependency areas include: `dotenv`, `files`, `os`, `re`, `typing`.
## Key Concepts
- Important called helpers/classes observed in the source: `_load_dotenv`, `get_abs_path`, `os.getenv`, `get_dotenv_file_path`, `load_dotenv`, `os.path.isfile`, `f.readlines`, `f.seek`, `f.writelines`, `f.truncate`, `f.write`, `re.match`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/email_parser_test.py`
- `tests/test_model_config_api_keys.py`
- `tests/test_timezone_regressions.py`
## Child DOX Index
No child DOX files.

40
helpers/duckduckgo_search.py.dox.md Normal file
View file

@ -0,0 +1,40 @@
# duckduckgo_search.py DOX
## Purpose
- Own the `duckduckgo_search.py` helper module.
- This module queries DuckDuckGo search through the configured helper path.
- Keep this file-level DOX profile synchronized with `duckduckgo_search.py` because this directory is intentionally flat.
## Ownership
- `duckduckgo_search.py` owns the runtime implementation.
- `duckduckgo_search.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Top-level functions:
- `search(query: str, results=..., region=..., time=...) -> list[str]`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Imported dependency areas include: `duckduckgo_search`.
## Key Concepts
- Important called helpers/classes observed in the source: `DDGS`, `ddgs.text`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- 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.

39
helpers/email_client.py.dox.md Normal file
View file

@ -0,0 +1,39 @@
# email_client.py DOX
## Purpose
- Own the `email_client.py` helper module.
- This module provides shared email client plumbing for mail integrations.
- Keep this file-level DOX profile synchronized with `email_client.py` because this directory is intentionally flat.
## Ownership
- `email_client.py` owns the runtime implementation.
- `email_client.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, WebSocket state, settings/state persistence, secret handling.
## 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
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/email_parser_test.py`
## Child DOX Index
No child DOX files.

58
helpers/ephemeral_images.py.dox.md Normal file
View file

@ -0,0 +1,58 @@
# ephemeral_images.py DOX
## Purpose
- Own the `ephemeral_images.py` helper module.
- This module stores temporary image payloads by reference for safe short-lived access.
- Keep this file-level DOX profile synchronized with `ephemeral_images.py` because this directory is intentionally flat.
## Ownership
- `ephemeral_images.py` owns the runtime implementation.
- `ephemeral_images.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `EphemeralImage` (no explicit base class)
- `data_url(self) -> str`
- `display_name(self) -> str`
- Top-level functions:
- `put_image_bytes(context_id: str, mime: str, payload: bytes, name: str=..., ttl_seconds: float=...) -> str`
- `put_image(context_id: str, mime: str, data: str, name: str=..., ttl_seconds: float=...) -> str`
- `is_ref(value: object) -> bool`
- `display_ref(ref: str) -> str`
- `get_image(ref: str, context_id: str=...) -> EphemeralImage | None`
- `consume_image(ref: str, context_id: str=...) -> EphemeralImage | None`
- `delete_image(ref: str) -> None`
- `clear_context(context_id: str) -> None`
- `_resolve_image(ref: str, context_id: str=..., consume: bool) -> EphemeralImage | None`
- `_compact_base64(data: str) -> str`
- `_normalize_mime(mime: str) -> str`
- `_prune_expired_locked(now: float | None=...) -> None`
- Notable constants/configuration names: `REF_PREFIX`, `DEFAULT_TTL_SECONDS`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem deletion.
- Imported dependency areas include: `__future__`, `base64`, `dataclasses`, `threading`, `time`, `uuid`.
## Key Concepts
- Important called helpers/classes observed in the source: `dataclass`, `threading.RLock`, `base64.b64encode.decode`, `put_image`, `_compact_base64`, `base64.b64decode`, `_normalize_mime`, `time.time`, `EphemeralImage`, `str.strip.startswith`, `str.strip`, `_resolve_image`, `join`, `str.strip.lower`, `ValueError`, `_prune_expired_locked`, `is_ref`, `_store.pop`, `value.startswith`, `display_ref`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_browser_agent_regressions.py`
## Child DOX Index
No child DOX files.

54
helpers/errors.py.dox.md Normal file
View file

@ -0,0 +1,54 @@
# errors.py DOX
## Purpose
- Own the `errors.py` helper module.
- This module defines framework exceptions and safe error formatting.
- Keep this file-level DOX profile synchronized with `errors.py` because this directory is intentionally flat.
## Ownership
- `errors.py` owns the runtime implementation.
- `errors.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `RepairableException` (`Exception`)
- `InterventionException` (`Exception`)
- `HandledException` (`Exception`)
- Top-level functions:
- `handle_error(e: Exception)`
- `error_text(e: Exception)`
- `format_error(e: Exception, start_entries=..., end_entries=..., error_message_position: Literal['top', 'bottom', 'none']=...)`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Imported dependency areas include: `asyncio`, `re`, `traceback`, `typing`.
## Key Concepts
- Important called helpers/classes observed in the source: `join`, `traceback_text.split`, `traceback.format_exception`, `re.match`, `type`, `line.strip.startswith`, `trimmed_lines.strip`, `error_message.strip`, `line.strip`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_browser_agent_regressions.py`
- `tests/test_fasta2a_client.py`
- `tests/test_host_browser_connector.py`
- `tests/test_office_desktop_state.py`
- `tests/test_office_document_store.py`
- `tests/test_skills_runtime.py`
- `tests/test_speech_plugin_split.py`
- `tests/test_time_travel.py`
## Child DOX Index
No child DOX files.

63
helpers/extension.py.dox.md Normal file
View file

@ -0,0 +1,63 @@
# extension.py DOX
## Purpose
- Own the `extension.py` helper module.
- This module discovers and dispatches Python and WebUI extension hooks.
- Keep this file-level DOX profile synchronized with `extension.py` because this directory is intentionally flat.
## Ownership
- `extension.py` owns the runtime implementation.
- `extension.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `_Unset` (no explicit base class)
- `Extension` (no explicit base class)
- `execute(self, **kwargs) -> None | Awaitable[None]`
- Top-level functions:
- `_log_extension_call(name: str)`
- `extensible(func)`: Make a function emit two implicit extension points around its execution.
- `async call_extensions_async(extension_point: str, agent: 'Agent|None'=..., **kwargs)`
- `call_extensions_sync(extension_point: str, agent: 'Agent|None'=..., **kwargs)`
- `get_webui_extensions(agent: 'Agent | None', extension_point: str, filters: list[str] | None=...)`
- `_get_extension_classes(extension_point: str, agent: 'Agent|None'=..., **kwargs) -> list[Type[Extension]]`
- `_get_file_from_module(module_name: str) -> str`
- `_get_extensions(folder: str)`
- `register_extensions_watchdogs()`
- Notable constants/configuration names: `DEFAULT_EXTENSIONS_FOLDER`, `USER_EXTENSIONS_FOLDER`, `_EXTENSIONS_CACHE_AREA`, `_CLASSES_CACHE_AREA`, `_UNSET`, `_EXTENSIONS_LOG_COUNTS`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- `Extension` defines `execute(...)`.
- Observed side-effect areas: filesystem reads, WebSocket state, plugin state.
- Imported dependency areas include: `abc`, `functools`, `helpers`, `helpers.print_style`, `inspect`, `os`, `typing`.
## Key Concepts
- Important called helpers/classes observed in the source: `_Unset`, `inspect.iscoroutinefunction`, `wraps`, `_log_extension_call`, `_get_extension_classes`, `subagents.get_paths`, `cache.determine_cache_key`, `cache.add`, `files.get_abs_path`, `modules.load_classes_from_folder`, `watchdog.add_watchdog`, `os.path.join`, `_get_agent`, `_prepare_inputs`, `_process_result`, `call_extensions_sync`, `cls.execute`, `files.deabsolute_path`, `_get_file_from_module`, `module_name.split`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_a0_connector_prompt_gating.py`
- `tests/test_api_chat_lifetime.py`
- `tests/test_browser_agent_regressions.py`
- `tests/test_error_retry_plugin.py`
- `tests/test_extensions_stress.py`
- `tests/test_history_compression_wait.py`
- `tests/test_model_config_api_keys.py`
- `tests/test_oauth_codex.py`
## Child DOX Index
No child DOX files.

48
helpers/extract_tools.py.dox.md Normal file
View file

@ -0,0 +1,48 @@
# extract_tools.py DOX
## Purpose
- Own the `extract_tools.py` helper module.
- This module normalizes and repairs model-emitted tool-call JSON.
- Keep this file-level DOX profile synchronized with `extract_tools.py` because this directory is intentionally flat.
## Ownership
- `extract_tools.py` owns the runtime implementation.
- `extract_tools.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Top-level functions:
- `json_parse_dirty(json: str) -> dict[str, Any] | None`
- `normalize_tool_request(tool_request: Any) -> tuple[str, dict]`
- `extract_json_root_string(content: str) -> str | None`
- `extract_json_object_string(content)`
- `extract_json_string(content)`
- `fix_json_string(json_string)`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: settings/state persistence.
- Imported dependency areas include: `dirty_json`, `helpers.modules`, `re`, `regex`, `typing`.
## Key Concepts
- Important called helpers/classes observed in the source: `extract_json_object_string`, `content.find`, `DirtyJson`, `content.rfind`, `regex.search`, `re.sub`, `json.strip`, `ValueError`, `tool_name.split`, `parser.parse`, `match.group`, `match.group.replace`, `DirtyJson.parse_string`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_stream_tool_early_stop.py`
- `tests/test_tool_request_normalization.py`
## Child DOX Index
No child DOX files.

38
helpers/faiss_monkey_patch.py.dox.md Normal file
View file

@ -0,0 +1,38 @@
# faiss_monkey_patch.py DOX
## Purpose
- Own the `faiss_monkey_patch.py` helper module.
- This module applies compatibility patches for FAISS behavior.
- Keep this file-level DOX profile synchronized with `faiss_monkey_patch.py` because this directory is intentionally flat.
## Ownership
- `faiss_monkey_patch.py` owns the runtime implementation.
- `faiss_monkey_patch.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Imported dependency areas include: `numpy`, `sys`, `types`, `warnings`.
## Key Concepts
- Important called helpers/classes observed in the source: `types.ModuleType`, `SimpleNamespace`, `warnings.catch_warnings`, `warnings.simplefilter`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- 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.

50
helpers/fasta2a_client.py.dox.md Normal file
View file

@ -0,0 +1,50 @@
# fasta2a_client.py DOX
## Purpose
- Own the `fasta2a_client.py` helper module.
- This module connects Agent Zero to external A2A agents.
- Keep this file-level DOX profile synchronized with `fasta2a_client.py` because this directory is intentionally flat.
## Ownership
- `fasta2a_client.py` owns the runtime implementation.
- `fasta2a_client.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `AgentConnection` (no explicit base class)
- `async get_agent_card(self) -> Dict[str, Any]`
- `async send_message(self, message: str, attachments: Optional[List[str]]=..., context_id: Optional[str]=..., metadata: Optional[Dict[str, Any]]=...) -> Dict[str, Any]`
- `async get_task(self, task_id: str) -> Dict[str, Any]`
- `async wait_for_completion(self, task_id: str, poll_interval: int=..., max_wait: int=...) -> Dict[str, Any]`
- `async close(self)`
- Top-level functions:
- `async connect_to_agent(agent_url: str, timeout: int=...) -> AgentConnection`: Create a connection to a remote agent.
- `is_client_available() -> bool`: Check if FastA2A client is available.
- Notable constants/configuration names: `_PRINTER`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem writes, network calls, WebSocket state, settings/state persistence, secret handling, scheduler state.
- Imported dependency areas include: `helpers.print_style`, `typing`, `uuid`.
## Key Concepts
- Important called helpers/classes observed in the source: `PrintStyle`, `AgentConnection`, `PrintStyle.warning`, `agent_url.rstrip`, `httpx.AsyncClient`, `A2AClient`, `TimeoutError`, `connection.get_agent_card`, `RuntimeError`, `agent_url.startswith`, `os.getenv`, `self._http_client.aclose`, `self.close`, `response.raise_for_status`, `response.json`, `self.get_agent_card`, `uuid.uuid4`, `self._a2a_client.send_message`, `self._a2a_client.get_task`, `self.get_task`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- 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.

52
helpers/fasta2a_server.py.dox.md Normal file
View file

@ -0,0 +1,52 @@
# fasta2a_server.py DOX
## Purpose
- Own the `fasta2a_server.py` helper module.
- This module serves Agent Zero through a dynamic A2A proxy.
- Keep this file-level DOX profile synchronized with `fasta2a_server.py` because this directory is intentionally flat.
## Ownership
- `fasta2a_server.py` owns the runtime implementation.
- `fasta2a_server.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `AgentZeroWorker` (`Worker`)
- `async run_task(self, params: Any) -> None`
- `async cancel_task(self, params: Any) -> None`
- `build_message_history(self, history: List[Any]) -> List[Message]`
- `build_artifacts(self, result: Any) -> List[Artifact]`
- `DynamicA2AProxy` (no explicit base class)
- `get_instance()`
- `reconfigure(self, token: str)`
- Top-level functions:
- `is_available()`: Check if FastA2A is available and properly configured.
- `get_proxy()`: Get the FastA2A proxy instance.
- Notable constants/configuration names: `_PRINTER`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem writes, filesystem deletion, settings/state persistence, secret handling, scheduler state.
- Imported dependency areas include: `agent`, `asyncio`, `atexit`, `contextlib`, `helpers`, `helpers.persist_chat`, `helpers.print_style`, `initialize`, `starlette.requests`, `threading`, `typing`, `uuid`.
## Key Concepts
- Important called helpers/classes observed in the source: `PrintStyle`, `DynamicA2AProxy.get_instance`, `super.__init__`, `join`, `UserMessage`, `threading.Lock`, `atexit.register`, `self._configure`, `settings.get_settings`, `path.startswith`, `self._convert_message`, `initialize_agent`, `AgentContext`, `context.log.log`, `context.communicate`, `context.reset`, `AgentContext.remove`, `remove_chat`, `self.storage.update_task`, `self._register_shutdown`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- 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
helpers/file_browser.py.dox.md Normal file
View file

@ -0,0 +1,51 @@
# file_browser.py DOX
## Purpose
- Own the `file_browser.py` helper module.
- This module builds safe file-browser views over allowed filesystem roots.
- Keep this file-level DOX profile synchronized with `file_browser.py` because this directory is intentionally flat.
## Ownership
- `file_browser.py` owns the runtime implementation.
- `file_browser.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `FileBrowser` (no explicit base class)
- `save_file_b64(self, current_path: str, filename: str, base64_content: str)`
- `save_files(self, files: List, current_path: str=...) -> Tuple[List[str], List[str]]`
- `delete_file(self, file_path: str) -> bool`
- `rename_item(self, file_path: str, new_name: str) -> bool`
- `create_folder(self, parent_path: str, folder_name: str) -> bool`
- `save_text_file(self, file_path: str, content: str) -> bool`
- `get_files(self, current_path: str=...) -> Dict`
- `get_full_path(self, file_path: str, allow_dir: bool=...) -> str`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, subprocess/runtime control, settings/state persistence.
- Imported dependency areas include: `base64`, `datetime`, `helpers`, `helpers.localization`, `helpers.print_style`, `helpers.security`, `os`, `pathlib`, `shutil`, `subprocess`, `typing`.
## Key Concepts
- Important called helpers/classes observed in the source: `Path`, `files.get_abs_path`, `self._get_file_extension`, `file.seek`, `file.tell`, `resolve`, `os.makedirs`, `os.path.exists`, `full_path.with_name`, `new_path.exists`, `os.rename`, `target_dir.exists`, `filename.rsplit.lower`, `subprocess.run`, `result.stdout.strip.split`, `self._get_files_via_ls`, `files.exists`, `ValueError`, `str.startswith`, `file.write`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_download_toast_regressions.py`
- `tests/test_office_document_store.py`
## Child DOX Index
No child DOX files.

63
helpers/file_tree.py.dox.md Normal file
View file

@ -0,0 +1,63 @@
# file_tree.py DOX
## Purpose
- Own the `file_tree.py` helper module.
- This module renders bounded file-tree summaries for prompts and UI surfaces.
- Keep this file-level DOX profile synchronized with `file_tree.py` because this directory is intentionally flat.
## Ownership
- `file_tree.py` owns the runtime implementation.
- `file_tree.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `_TreeEntry` (no explicit base class)
- `as_dict(self) -> dict[str, Any]`
- Top-level functions:
- `_from_timestamp(timestamp: float) -> datetime`
- `file_tree(relative_path: str, max_depth: int=..., max_lines: int=..., folders_first: bool=..., max_folders: int=..., max_files: int=..., sort: tuple[Literal['name', 'created', 'modified'], Literal['asc', 'desc']]=..., ignore: str | None=..., output_mode: Literal['string', 'flat', 'nested']=...) -> str | list[dict]`: Render a directory tree relative to the repository base path.
- `_normalize_relative_path(path: str) -> str`
- `_directory_has_visible_entries(directory: str, root_abs_path: str, ignore_spec: PathSpec, cache: dict[str, bool], max_depth_remaining: int) -> bool`
- `_create_summary_comment(parent: _TreeEntry, noun: str, count: int) -> _TreeEntry`
- `_create_global_limit_comment(parent: _TreeEntry, hidden_children: Sequence[_TreeEntry]) -> _TreeEntry`
- `_create_folder_unprocessed_comment(folder_node: _TreeEntry, folder_path: str, abs_root: str, ignore_spec: Optional[PathSpec]) -> Optional[_TreeEntry]`
- `_prune_to_visible(node: _TreeEntry, visible_ids: set[int]) -> None`
- `_mark_last_flags(node: _TreeEntry) -> None`
- `_refresh_render_metadata(node: _TreeEntry) -> None`
- `_resolve_ignore_patterns(ignore: str | None, root_abs_path: str) -> Optional[PathSpec]`
- `_list_directory_children(directory: str, root_abs_path: str, ignore_spec: Optional[PathSpec], max_depth_remaining: int, cache: dict[str, bool]) -> tuple[list[os.DirEntry], list[os.DirEntry]]`
- `_apply_sorting_and_limits(folders: list[_TreeEntry], files: list[_TreeEntry], folders_first: bool, sort: tuple[str, str], max_folders: int | None, max_files: int | None, directory_node: _TreeEntry) -> list[_TreeEntry]`
- `_format_line(node: _TreeEntry) -> str`
- `_build_tree_items_flat(items: Sequence[_TreeEntry]) -> list[dict]`
- `_to_nested_structure(items: Sequence[_TreeEntry]) -> list[dict]`
- `_iter_depth_first(items: Sequence[_TreeEntry]) -> Iterable[_TreeEntry]`
- Notable constants/configuration names: `SORT_BY_NAME`, `SORT_BY_CREATED`, `SORT_BY_MODIFIED`, `SORT_ASC`, `SORT_DESC`, `OUTPUT_MODE_STRING`, `OUTPUT_MODE_FLAT`, `OUTPUT_MODE_NESTED`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, subprocess/runtime control, WebSocket state.
- Imported dependency areas include: `__future__`, `collections`, `dataclasses`, `datetime`, `helpers`, `helpers.localization`, `os`, `pathspec`, `typing`.
## Key Concepts
- Important called helpers/classes observed in the source: `dataclass`, `datetime.fromtimestamp`, `files_helper.get_abs_path`, `files_helper.get_abs_path_dockerized`, `_resolve_ignore_patterns`, `os.stat`, `_TreeEntry`, `deque`, `queue.clear`, `_mark_last_flags`, `_refresh_render_metadata`, `path.replace`, `normalized.startswith`, `join`, `_create_global_limit_comment`, `ignore.startswith`, `PathSpec.from_lines`, `segments.reverse`, `os.path.exists`, `FileNotFoundError`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_file_tree_visualize.py`
- `tests/test_skills_runtime.py`
## Child DOX Index
No child DOX files.

82
helpers/files.py.dox.md Normal file
View file

@ -0,0 +1,82 @@
# files.py DOX
## Purpose
- Own the `files.py` helper module.
- This module owns repository/user path helpers and file read/write/parsing primitives.
- Keep this file-level DOX profile synchronized with `files.py` because this directory is intentionally flat.
## Ownership
- `files.py` owns the runtime implementation.
- `files.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `VariablesPlugin` (`ABC`)
- `get_variables(self, file: str, backup_dirs: list[str] | None=..., **kwargs) -> dict[str, Any]`
- Top-level functions:
- `load_plugin_variables(file: str, backup_dirs: list[str] | None=..., **kwargs) -> dict[str, Any]`
- `parse_file(_filename: str, _directories: list[str] | None=..., _encoding=..., **kwargs)`
- `read_prompt_file(_file: str, _directories: list[str] | None=..., _encoding=..., **kwargs)`
- `evaluate_text_conditions(_content: str, **kwargs)`
- `read_file(relative_path: str, encoding=...)`
- `read_file_json(relative_path: str, encoding=...)`
- `read_file_yaml(relative_path: str, encoding=...)`
- `read_file_bin(relative_path: str)`
- `read_file_base64(relative_path)`
- `is_probably_binary_bytes(data: bytes, threshold: float=...) -> bool`: Binary detection.
- `is_probably_binary_file(file_path: str, sample_size: int=..., threshold: float=...) -> bool`: Binary detection by reading only the first ~sample_size bytes of a file.
- `replace_placeholders_text(_content: str, **kwargs)`
- `replace_placeholders_json(_content: str, **kwargs)`
- `replace_placeholders_dict(_content: dict, **kwargs)`
- `process_includes(_content: str, _directories: list[str], _source_file: str=..., _source_dir: str=..., **kwargs)`
- `_get_dirs_after(_directories: list[str], _source_dir: str) -> list[str]`: Return directories after _source_dir in the priority list.
- `find_file_in_dirs(_filename: str, _directories: list[str])`: This function searches for a filename in a list of directories in order.
- `get_unique_filenames_in_dirs(dir_paths: list[str], pattern: str=..., type: Literal['file', 'dir', 'any']=...)`
- `find_existing_paths_by_pattern(pattern: str)`
- `remove_code_fences(text)`
- `is_full_json_template(text)`
- `write_file(relative_path: str, content: str, encoding: str=...)`
- `delete_file(relative_path: str)`
- `write_file_bin(relative_path: str, content: bytes)`
- `write_file_base64(relative_path: str, content: str)`
- `delete_dir(relative_path: str)`
- `move_dir(old_path: str, new_path: str)`
- `move_dir_safe(src, dst, rename_format=...)`
- `create_dir_safe(dst, rename_format=...)`
- `create_dir(relative_path: str)`
- Notable constants/configuration names: `AGENTS_DIR`, `PLUGINS_DIR`, `PROJECTS_DIR`, `EXTENSIONS_DIR`, `USER_DIR`, `TEMP_DIR`, `API_DIR`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, subprocess/runtime control, plugin state, settings/state persistence, secret handling.
- Imported dependency areas include: `abc`, `base64`, `fnmatch`, `glob`, `helpers`, `helpers.strings`, `json`, `mimetypes`, `os`, `re`, `shutil`, `simpleeval`, `tempfile`, `typing`, `zipfile`.
## Key Concepts
- Important called helpers/classes observed in the source: `os.path.dirname`, `os.path.abspath`, `find_file_in_dirs`, `is_full_json_template`, `remove_code_fences`, `evaluate_text_conditions`, `replace_placeholders_text`, `process_includes`, `re.compile`, `_process`, `get_abs_path`, `is_probably_binary_bytes`, `replace_value`, `re.sub`, `os.path.normpath`, `FileNotFoundError`, `result.sort`, `glob.glob`, `matches.sort`, `re.fullmatch`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_a0_connector_prompt_gating.py`
- `tests/test_browser_agent_regressions.py`
- `tests/test_default_prompt_budget.py`
- `tests/test_document_query_plugin.py`
- `tests/test_download_toast_regressions.py`
- `tests/test_file_tree_visualize.py`
- `tests/test_host_browser_connector.py`
- `tests/test_image_get_security.py`
## Child DOX Index
No child DOX files.

45
helpers/functions.py.dox.md Normal file
View file

@ -0,0 +1,45 @@
# functions.py DOX
## Purpose
- Own the `functions.py` helper module.
- This module provides safe generic callable execution helpers.
- Keep this file-level DOX profile synchronized with `functions.py` because this directory is intentionally flat.
## Ownership
- `functions.py` owns the runtime implementation.
- `functions.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Top-level functions:
- `safe_call(func, *args, **kwargs)`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Imported dependency areas include: `inspect`.
## Key Concepts
- Important called helpers/classes observed in the source: `inspect.signature`, `func`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_a0_connector_prompt_gating.py`
- `tests/test_browser_agent_regressions.py`
- `tests/test_error_retry_plugin.py`
- `tests/test_oauth_codex.py`
- `tests/test_oauth_providers.py`
## Child DOX Index
No child DOX files.

70
helpers/git.py.dox.md Normal file
View file

@ -0,0 +1,70 @@
# git.py DOX
## Purpose
- Own the `git.py` helper module.
- This module reads local and remote Git release/commit metadata safely.
- Keep this file-level DOX profile synchronized with `git.py` because this directory is intentionally flat.
## Ownership
- `git.py` owns the runtime implementation.
- `git.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `GitHeadInfo` (no explicit base class)
- `GitReleaseInfo` (no explicit base class)
- `GitRemoteReleaseInfo` (no explicit base class)
- `GitRemoteReleasesResult` (no explicit base class)
- `GitRemoteCommitsInfo` (no explicit base class)
- `GitRepoReleaseInfo` (no explicit base class)
- Top-level functions:
- `strip_auth_from_url(url: str) -> str`: Remove any authentication info from URL.
- `extract_author_repo(url: str) -> tuple[str, str]`
- `_format_git_timestamp(timestamp: int) -> str`
- `_split_describe_version(describe: str) -> tuple[str, int]`
- `_format_release_version(branch: str, short_tag: str, commits_since_tag: int, commit_hash: str) -> str`
- `get_remote_releases(author: str, repo: str) -> GitRemoteReleasesResult`
- `get_remote_commits_since_local(repo_path: str) -> GitRemoteCommitsInfo`
- `get_repo_release_info(repo_path: str) -> GitRepoReleaseInfo`
- `get_git_info()`
- `get_version()`
- `is_official_agent_zero_repo() -> bool`: Return True when origin points to agent0ai/agent-zero.
- `clone_repo(url: str, dest: str, token: str | None=...)`: Clone a git repository. Uses http.extraHeader for token auth (never stored in URL/config).
- `update_repo(repo_path: str) -> Repo`
- `get_repo_status(repo_path: str) -> dict`: Get Git repository status, ignoring A0 project metadata files.
- Notable constants/configuration names: `A0_IGNORE_PATTERNS`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem writes, filesystem deletion, network calls, subprocess/runtime control, plugin state, settings/state persistence, secret handling.
- Imported dependency areas include: `base64`, `dataclasses`, `datetime`, `git`, `giturlparse`, `helpers`, `helpers.localization`, `os`, `re`, `subprocess`, `urllib.parse`.
## Key Concepts
- Important called helpers/classes observed in the source: `urlparse`, `urlunparse`, `parse`, `strip`, `repo.endswith`, `datetime.fromtimestamp.strftime`, `describe.strip`, `re.fullmatch`, `files.get_base_dir`, `get_repo_release_info`, `os.environ.copy`, `subprocess.run`, `Repo`, `repo.active_branch.tracking_branch`, `strip_auth_from_url`, `ValueError`, `match.group`, `branch.upper`, `author.strip`, `repo.strip`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_docker_release_plan.py`
- `tests/test_git_version_label.py`
- `tests/test_model_config_api_keys.py`
- `tests/test_model_config_project_presets.py`
- `tests/test_model_search.py`
- `tests/test_oauth_github_copilot.py`
- `tests/test_oauth_providers.py`
- `tests/test_onboarding_static.py`
## Child DOX Index
No child DOX files.

40
helpers/guids.py.dox.md Normal file
View file

@ -0,0 +1,40 @@
# guids.py DOX
## Purpose
- Own the `guids.py` helper module.
- This module generates framework IDs.
- Keep this file-level DOX profile synchronized with `guids.py` because this directory is intentionally flat.
## Ownership
- `guids.py` owns the runtime implementation.
- `guids.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Top-level functions:
- `generate_id(length: int=...) -> str`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Imported dependency areas include: `random`, `string`.
## Key Concepts
- Important called helpers/classes observed in the source: `join`, `random.choices`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- 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.

109
helpers/history.py.dox.md Normal file
View file

@ -0,0 +1,109 @@
# history.py DOX
## Purpose
- Own the `history.py` helper module.
- This module owns chat history message records and model-output conversion.
- Keep this file-level DOX profile synchronized with `history.py` because this directory is intentionally flat.
## Ownership
- `history.py` owns the runtime implementation.
- `history.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `RawMessage` (`TypedDict`)
- `OutputMessage` (`TypedDict`)
- `Record` (no explicit base class)
- `get_tokens(self) -> int`
- `async compress(self) -> bool`
- `output(self) -> list[OutputMessage]`
- `async summarize(self) -> str`
- `to_dict(self) -> dict`
- `from_dict(data: dict, history: 'History')`
- `output_langchain(self)`
- `output_text(self, human_label=..., ai_label=...)`
- `Message` (`Record`)
- `get_tokens(self) -> int`
- `calculate_tokens(self)`
- `set_summary(self, summary: str)`
- `async compress(self)`
- `output(self)`
- `output_langchain(self)`
- `output_text(self, human_label=..., ai_label=...)`
- `to_dict(self)`
- `Topic` (`Record`)
- `get_tokens(self)`
- `add_message(self, ai: bool, content: MessageContent, tokens: int=..., id: str=...) -> Message`
- `output(self) -> list[OutputMessage]`
- `async summarize(self)`
- `compress_large_messages(self, message_ratio: float=...) -> bool`
- `async compress(self) -> bool`
- `async compress_attention(self, ratio: float=...) -> bool`
- `async summarize_messages(self, messages: list[Message])`
- `Bulk` (`Record`)
- `get_tokens(self)`
- `output(self, human_label: str=..., ai_label: str=...) -> list[OutputMessage]`
- `async compress(self)`
- `async summarize(self)`
- `to_dict(self)`
- `from_dict(data: dict, history: 'History')`
- `History` (`Record`)
- `get_tokens(self) -> int`
- `is_over_limit(self)`
- `get_bulks_tokens(self) -> int`
- `get_topics_tokens(self) -> int`
- `get_current_topic_tokens(self) -> int`
- `add_message(self, ai: bool, content: MessageContent, tokens: int=..., id: str=...) -> Message`
- `new_topic(self)`
- `output(self) -> list[OutputMessage]`
- Top-level functions:
- `deserialize_history(json_data: str, agent) -> History`
- `_stringify_output(output: OutputMessage, ai_label=..., human_label=...)`
- `_stringify_content(content: MessageContent) -> str`
- `_output_content_langchain(content: MessageContent)`
- `group_outputs_abab(outputs: list[OutputMessage]) -> list[OutputMessage]`
- `group_messages_abab(messages: list[BaseMessage]) -> list[BaseMessage]`
- `output_langchain(messages: list[OutputMessage])`
- `output_text(messages: list[OutputMessage], ai_label=..., human_label=...)`
- `_merge_outputs(a: MessageContent, b: MessageContent) -> MessageContent`
- `_merge_properties(a: Dict[str, MessageContent], b: Dict[str, MessageContent]) -> Dict[str, MessageContent]`
- `_is_raw_message(obj: object) -> bool`
- `_is_embedded_data(obj: object) -> bool`
- `_json_dumps(obj)`
- `_json_loads(obj)`
- Notable constants/configuration names: `BULK_MERGE_COUNT`, `TOPICS_MERGE_COUNT`, `CURRENT_TOPIC_RATIO`, `HISTORY_TOPIC_RATIO`, `HISTORY_BULK_RATIO`, `CURRENT_TOPIC_ATTENTION_COMPRESSION`, `HISTORY_TOPIC_ATTENTION_COMPRESSION`, `LARGE_MESSAGE_TO_CURRENT_TOPIC_RATIO`, `LARGE_MESSAGE_TO_HISTORY_TOPIC_RATIO`, `RAW_MESSAGE_OUTPUT_TEXT_TRIM`, `COMPRESSION_TARGET_RATIO`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem writes, filesystem deletion, model calls, plugin state, settings/state persistence, secret handling.
- Imported dependency areas include: `abc`, `asyncio`, `collections`, `collections.abc`, `enum`, `helpers`, `json`, `langchain_core.messages`, `math`, `plugins._model_config.helpers.model_config`, `typing`, `uuid`.
## Key Concepts
- Important called helpers/classes observed in the source: `History`, `_is_raw_message`, `_json_dumps`, `group_messages_abab`, `join`, `make_list`, `cast`, `a.copy`, `json.dumps`, `json.loads`, `globals.from_dict`, `output_langchain`, `output_text`, `self.output_text`, `tokens.approximate_tokens`, `self.calculate_tokens`, `Message`, `get_chat_model_config`, `large_msgs.sort`, `self.compress_large_messages`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_browser_agent_regressions.py`
- `tests/test_chat_compaction.py`
- `tests/test_error_retry_plugin.py`
- `tests/test_history_compression_wait.py`
- `tests/test_mcp_handler_multimodal.py`
- `tests/test_memory_quality.py`
- `tests/test_model_config_project_presets.py`
- `tests/test_office_document_store.py`
## Child DOX Index
No child DOX files.

48
helpers/images.py.dox.md Normal file
View file

@ -0,0 +1,48 @@
# images.py DOX
## Purpose
- Own the `images.py` helper module.
- This module resolves, compresses, and serializes image references for model inputs.
- Keep this file-level DOX profile synchronized with `images.py` because this directory is intentionally flat.
## Ownership
- `images.py` owns the runtime implementation.
- `images.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Top-level functions:
- `prepare_content(content: Any) -> Any`
- `is_local_ref(url: str) -> bool`
- `to_data_url(url: str) -> str`
- `resolve_ref(url: str) -> Path`
- `compress_image(image_data: bytes, max_pixels: int=..., quality: int=...) -> bytes`: Compress an image by scaling it down and converting to JPEG with quality settings.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, network calls, settings/state persistence.
- Imported dependency areas include: `PIL`, `base64`, `io`, `math`, `mimetypes`, `pathlib`, `typing`, `urllib.parse`.
## Key Concepts
- Important called helpers/classes observed in the source: `url.lower`, `lowered.startswith`, `resolve_ref`, `base64.b64encode.decode`, `Path.expanduser`, `raw_path.startswith`, `FileNotFoundError`, `io.BytesIO`, `img.save`, `output.getvalue`, `prepare_content`, `url.startswith`, `mimetypes.guess_type`, `ValueError`, `url.lower.startswith`, `unquote`, `seen.add`, `math.sqrt`, `img.resize`, `img.convert`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_browser_agent_regressions.py`
- `tests/test_image_get_security.py`
- `tests/test_vision_load_image_refs.py`
## Child DOX Index
No child DOX files.

53
helpers/integration_commands.py.dox.md Normal file
View file

@ -0,0 +1,53 @@
# integration_commands.py DOX
## Purpose
- Own the `integration_commands.py` helper module.
- This module parses external integration slash commands such as project/config/send controls.
- Keep this file-level DOX profile synchronized with `integration_commands.py` because this directory is intentionally flat.
## Ownership
- `integration_commands.py` owns the runtime implementation.
- `integration_commands.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Top-level functions:
- `extract_command_line(text: str) -> str`
- `parse_command(text: str) -> tuple[str, str] | None`
- `try_handle_command(context: 'AgentContext', text: str) -> str | None`
- `_handle_queue(context: 'AgentContext', args: str) -> str`
- `_handle_project(context: 'AgentContext', args: str) -> str`
- `_handle_config(context: 'AgentContext', args: str) -> str`
- `_format_project_entry(item: dict) -> str`
- `_describe_project(items: list[dict], current_name: str) -> str`
- `_describe_override(override: dict | None) -> str`
- `_strip_quotes(value: str) -> str`
- `_normalize_lookup(value: str) -> str`
- `_match_named_item(items: list[dict], desired: str, keys: tuple[str, ...]) -> tuple[dict | None, list[dict]]`
- Notable constants/configuration names: `_CLEAR_VALUES`, `_SUPPORTED_COMMANDS`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem writes, model calls, plugin state, settings/state persistence.
- Imported dependency areas include: `__future__`, `helpers`, `helpers.persist_chat`, `helpers.state_monitor_integration`, `plugins._model_config.helpers`, `re`, `typing`.
## Key Concepts
- Important called helpers/classes observed in the source: `splitlines`, `extract_command_line`, `line.partition`, `command.strip.lower`, `parse_command`, `mq.get_queue`, `args.strip.lower`, `mq.send_all_aggregated`, `mark_dirty_for_context`, `_strip_quotes`, `_match_named_item`, `projects.activate_project`, `model_config.is_chat_override_allowed`, `context.get_data`, `context.set_data`, `save_tmp_chat`, `str.strip`, `value.strip`, `value.lower.strip`, `re.sub`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- 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.

46
helpers/job_loop.py.dox.md Normal file
View file

@ -0,0 +1,46 @@
# job_loop.py DOX
## Purpose
- Own the `job_loop.py` helper module.
- This module runs periodic scheduler and maintenance loops.
- Keep this file-level DOX profile synchronized with `job_loop.py` because this directory is intentionally flat.
## Ownership
- `job_loop.py` owns the runtime implementation.
- `job_loop.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Top-level functions:
- `async run_loop()`
- `async scheduler_tick()`
- `pause_loop()`
- `resume_loop()`
- Notable constants/configuration names: `SLEEP_TIME`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: scheduler state.
- Imported dependency areas include: `asyncio`, `datetime`, `helpers`, `helpers.print_style`, `helpers.task_scheduler`, `time`.
## Key Concepts
- Important called helpers/classes observed in the source: `time.time`, `runtime.is_development`, `scheduler.tick`, `call_extensions_async`, `resume_loop`, `asyncio.sleep`, `runtime.call_development_function`, `PrintStyle.error`, `scheduler_tick`, `errors.format_error`, `PrintStyle`, `errors.error_text`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_api_chat_lifetime.py`
## Child DOX Index
No child DOX files.

52
helpers/kvp.py.dox.md Normal file
View file

@ -0,0 +1,52 @@
# kvp.py DOX
## Purpose
- Own the `kvp.py` helper module.
- This module provides runtime and persistent key-value storage helpers.
- Keep this file-level DOX profile synchronized with `kvp.py` because this directory is intentionally flat.
## Ownership
- `kvp.py` owns the runtime implementation.
- `kvp.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Top-level functions:
- `_persistent_dir() -> str`
- `_validate_key(key: str) -> None`
- `_key_to_path(key: str) -> str`
- `get_runtime(key: str, default: Any=...) -> Any`
- `set_runtime(key: str, value: Any) -> None`
- `remove_runtime(key: str) -> None`
- `find_runtime(pattern: str) -> list[str]`
- `get_persistent(key: str, default: Any=...) -> Any`
- `set_persistent(key: str, value: Any) -> None`
- `remove_persistent(key: str) -> None`
- `find_persistent(pattern: str) -> list[str]`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, settings/state persistence.
- Imported dependency areas include: `fnmatch`, `glob`, `helpers.files`, `json`, `os`, `tempfile`, `threading`, `typing`.
## Key Concepts
- Important called helpers/classes observed in the source: `threading.RLock`, `get_abs_path`, `_validate_key`, `os.path.join`, `_key_to_path`, `os.path.dirname`, `_persistent_dir`, `ValueError`, `_runtime_store.pop`, `os.makedirs`, `tempfile.mkstemp`, `glob.glob`, `keys.sort`, `os.replace`, `os.unlink`, `os.path.isdir`, `json.load`, `os.fdopen`, `json.dump`, `f.flush`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_browser_agent_regressions.py`
## Child DOX Index
No child DOX files.

50
helpers/localization.py.dox.md Normal file
View file

@ -0,0 +1,50 @@
# localization.py DOX
## Purpose
- Own the `localization.py` helper module.
- This module loads and resolves localized UI/application text.
- Keep this file-level DOX profile synchronized with `localization.py` because this directory is intentionally flat.
## Ownership
- `localization.py` owns the runtime implementation.
- `localization.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `Localization` (no explicit base class)
- `get(cls, *args, **kwargs)`
- `get_timezone(self) -> str`
- `get_tzinfo(self)`
- `get_offset_minutes(self) -> int`
- `apply_process_timezone(self) -> None`
- `now(self) -> datetime`
- `now_iso(self, sep: str=..., timespec: str=...) -> str`
- `localize_naive_datetime(self, dt: datetime) -> datetime`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem writes, settings/state persistence.
- Imported dependency areas include: `datetime`, `helpers.dotenv`, `helpers.print_style`, `os`, `pytz`, `time`.
## Key Concepts
- Important called helpers/classes observed in the source: `get_dotenv_value`, `pytz.timezone`, `datetime.now`, `now_in_tz.utcoffset`, `self.now.isoformat`, `self.get_tzinfo`, `cls`, `self.set_timezone`, `self._compute_offset_minutes`, `self.apply_process_timezone`, `tzinfo.localize`, `PrintStyle.debug`, `save_dotenv_value`, `localtime_str.strip.replace`, `local_datetime_obj.astimezone`, `utc_dt.astimezone`, `local_datetime_obj.isoformat`, `dt.astimezone`, `local_dt.isoformat`, `time.tzset`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_timezone_regressions.py`
## Child DOX Index
No child DOX files.

68
helpers/log.py.dox.md Normal file
View file

@ -0,0 +1,68 @@
# log.py DOX
## Purpose
- Own the `log.py` helper module.
- This module owns chat log items, outputs, truncation, and dirty-state integration.
- Keep this file-level DOX profile synchronized with `log.py` because this directory is intentionally flat.
## Ownership
- `log.py` owns the runtime implementation.
- `log.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `LogItem` (no explicit base class)
- `update(self, type: Type | None=..., heading: str | None=..., content: str | None=..., kvps: dict | None=..., update_progress: ProgressUpdate | None=..., **kwargs)`
- `stream(self, heading: str | None=..., content: str | None=..., **kwargs)`
- `output(self)`
- `LogOutput` (no explicit base class)
- `Log` (no explicit base class)
- `log(self, type: Type, heading: str | None=..., content: str | None=..., kvps: dict | None=..., update_progress: ProgressUpdate | None=..., id: Optional[str]=..., **kwargs) -> LogItem`
- `set_progress(self, progress: str, no: int=..., active: bool=...)`
- `set_initial_progress(self)`
- `output(self, start=..., end=...)`
- `reset(self)`
- Top-level functions:
- `_lazy_mark_dirty_all(reason: str | None=...) -> None`
- `_lazy_mark_dirty_for_context(context_id: str, reason: str | None=...) -> None`
- `_truncate_heading(text: str | None) -> str`
- `_truncate_progress(text: str | None) -> str`
- `_truncate_key(text: str) -> str`
- `_truncate_value(val: T) -> T`
- `_truncate_content(text: str | None, type: Type) -> str`
- Notable constants/configuration names: `_MARK_DIRTY_ALL`, `_MARK_DIRTY_FOR_CONTEXT`, `T`, `HEADING_MAX_LEN`, `CONTENT_MAX_LEN`, `RESPONSE_CONTENT_MAX_LEN`, `KEY_MAX_LEN`, `VALUE_MAX_LEN`, `PROGRESS_MAX_LEN`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem writes, filesystem deletion, settings/state persistence, secret handling, scheduler state.
- Imported dependency areas include: `collections`, `copy`, `dataclasses`, `helpers.secrets`, `helpers.strings`, `json`, `threading`, `time`, `typing`, `uuid`.
## Key Concepts
- Important called helpers/classes observed in the source: `TypeVar`, `dataclass`, `_MARK_DIRTY_ALL`, `_MARK_DIRTY_FOR_CONTEXT`, `truncate_text_by_ratio`, `cast`, `threading.RLock`, `self.set_initial_progress`, `self._update_item`, `self._notify_state_monitor`, `_lazy_mark_dirty_all`, `_lazy_mark_dirty_for_context`, `self._mask_recursive`, `_truncate_progress`, `self.set_progress`, `LogOutput`, `_truncate_value`, `json.dumps`, `time.time`, `self.log._update_item`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_browser_agent_regressions.py`
- `tests/test_chat_compaction.py`
- `tests/test_error_retry_plugin.py`
- `tests/test_fasta2a_client.py`
- `tests/test_file_tree_visualize.py`
- `tests/test_history_compression_wait.py`
- `tests/test_http_auth_csrf.py`
- `tests/test_mcp_handler_multimodal.py`
## Child DOX Index
No child DOX files.

49
helpers/login.py.dox.md Normal file
View file

@ -0,0 +1,49 @@
# login.py DOX
## Purpose
- Own the `login.py` helper module.
- This module checks login requirements and credential hashes.
- Keep this file-level DOX profile synchronized with `login.py` because this directory is intentionally flat.
## Ownership
- `login.py` owns the runtime implementation.
- `login.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Top-level functions:
- `get_credentials_hash()`
- `is_login_required()`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: secret handling.
- Imported dependency areas include: `hashlib`, `helpers`.
## Key Concepts
- Important called helpers/classes observed in the source: `dotenv.get_dotenv_value`, `hashlib.sha256.hexdigest`, `hashlib.sha256`, `encode`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_http_auth_csrf.py`
- `tests/test_oauth_gemini_api.py`
- `tests/test_oauth_github_copilot.py`
- `tests/test_oauth_providers.py`
- `tests/test_oauth_xai_grok.py`
- `tests/test_tunnel_remote_link.py`
- `tests/test_ws_security.py`
## Child DOX Index
No child DOX files.

90
helpers/mcp_handler.py.dox.md Normal file
View file

@ -0,0 +1,90 @@
# mcp_handler.py DOX
## Purpose
- Own the `mcp_handler.py` helper module.
- This module loads MCP server configuration and exposes MCP tools to agents.
- Keep this file-level DOX profile synchronized with `mcp_handler.py` because this directory is intentionally flat.
## Ownership
- `mcp_handler.py` owns the runtime implementation.
- `mcp_handler.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `MCPTool` (`Tool`)
- `get_log_object(self) -> LogItem`
- `async execute(self, **kwargs)`
- `async before_execution(self, **kwargs)`
- `async after_execution(self, response: Response, **kwargs)`
- `MCPServerRemote` (`BaseModel`)
- `get_error(self) -> str`
- `get_log(self) -> str`
- `get_tools(self) -> List[dict[str, Any]]`
- `has_tool(self, tool_name: str) -> bool`
- `async call_tool(self, tool_name: str, input_data: Dict[str, Any]) -> CallToolResult`
- `update(self, config: dict[str, Any]) -> 'MCPServerRemote'`
- `async initialize(self) -> 'MCPServerRemote'`
- `MCPServerLocal` (`BaseModel`)
- `get_error(self) -> str`
- `get_log(self) -> str`
- `get_tools(self) -> List[dict[str, Any]]`
- `has_tool(self, tool_name: str) -> bool`
- `async call_tool(self, tool_name: str, input_data: Dict[str, Any]) -> CallToolResult`
- `update(self, config: dict[str, Any]) -> 'MCPServerLocal'`
- `async initialize(self) -> 'MCPServerLocal'`
- `MCPConfig` (`BaseModel`)
- `get_instance(cls) -> 'MCPConfig'`
- `wait_for_lock(cls)`
- `update(cls, config_str: str) -> Any`
- `normalize_config(cls, servers: Any)`
- `get_server_log(self, server_name: str) -> str`
- `get_servers_status(self) -> list[dict[str, Any]]`
- `get_server_detail(self, server_name: str) -> dict[str, Any]`
- `is_initialized(self) -> bool`
- `MCPClientBase` (`ABC`)
- `async update_tools(self) -> 'MCPClientBase'`
- `has_tool(self, tool_name: str) -> bool`
- `get_tools(self) -> List[dict[str, Any]]`
- `async call_tool(self, tool_name: str, input_data: Dict[str, Any]) -> CallToolResult`
- `get_log(self)`
- `MCPClientLocal` (`MCPClientBase`)
- `CustomHTTPClientFactory` (`ABC`)
- `MCPClientRemote` (`MCPClientBase`)
- `get_session_id(self) -> Optional[str]`
- Top-level functions:
- `_mcp_get(item: Any, key: str, default: Any=...) -> Any`
- `normalize_name(name: str) -> str`
- `_determine_server_type(config_dict: dict) -> str`: Determine the server type based on configuration, with backward compatibility.
- `_is_streaming_http_type(server_type: str) -> bool`: Check if the server type is a streaming HTTP variant.
- `initialize_mcp(mcp_servers_config: str)`
- Notable constants/configuration names: `MCP_MEDIA_TOKENS_ESTIMATE`, `MAX_MCP_RESOURCE_TEXT_CHARS`, `T`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- `MCPTool` is a `Tool`.
- `MCPTool` defines `execute(...)`.
- Observed side-effect areas: filesystem writes, network calls, WebSocket state, settings/state persistence, secret handling.
- Imported dependency areas include: `abc`, `anyio.streams.memory`, `asyncio`, `contextlib`, `datetime`, `helpers`, `helpers.log`, `helpers.print_style`, `helpers.tool`, `httpx`, `json`, `mcp`, `mcp.client.sse`, `mcp.client.stdio`, `mcp.client.streamable_http`, `mcp.shared.message`.
## Key Concepts
- Important called helpers/classes observed in the source: `TypeVar`, `name.strip.lower`, `re.sub`, `Field`, `PrivateAttr`, `threading.Lock`, `config_dict.lower`, `server_type.lower`, `MCPConfig.get_instance.is_initialized`, `self.agent.context.log.log`, `str.strip`, `media_artifacts.guess_extension`, `callable`, `self._content_item_dump`, `join`, `Response`, `self.get_log_object`, `self._raw_tool_response`, `additional.pop`, `self._coerce_media_token_estimate`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_mcp_handler_multimodal.py`
## Child DOX Index
No child DOX files.

54
helpers/mcp_server.py.dox.md Normal file
View file

@ -0,0 +1,54 @@
# mcp_server.py DOX
## Purpose
- Own the `mcp_server.py` helper module.
- This module serves Agent Zero chats through a dynamic MCP proxy.
- Keep this file-level DOX profile synchronized with `mcp_server.py` because this directory is intentionally flat.
## Ownership
- `mcp_server.py` owns the runtime implementation.
- `mcp_server.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `ToolResponse` (`BaseModel`)
- `ToolError` (`BaseModel`)
- `DynamicMcpProxy` (no explicit base class)
- `get_instance()`
- `reconfigure(self, token: str)`
- Top-level functions:
- `async send_message(message: Annotated[str, Field(description='The message to send to the remote Agent Zero Instance', title='message')], attachments: Annotated[list[str], Field(description='Optional: A list of attachments (file paths or web urls) to send to the remote Agent Zero Instance with the message. Default: Empty list', title='attachments')] | None=..., chat_id: Annotated[str, Field(description='Optional: ID of the chat. Used to continue a chat. This value is returned in response to sending previous message. Default: Empty string', title='chat_id')] | None=..., persistent_chat: Annotated[bool, Field(description='Optional: Whether to use a persistent chat. If true, the chat will be saved and can be continued later. Default: False.', title='persistent_chat')] | None=...) -> Annotated[Union[ToolResponse, ToolError], Field(description='The response from the remote Agent Zero Instance', title='response')]`
- `async finish_chat(chat_id: Annotated[str, Field(description='ID of the chat to be finished. This value is returned in response to sending previous message.', title='chat_id')]) -> Annotated[Union[ToolResponse, ToolError], Field(description='The response from the remote Agent Zero Instance', title='response')]`
- `async _run_chat(context: AgentContext, message: str, attachments: list[str] | None=...)`
- `async mcp_middleware(request: Request, call_next)`: Middleware to check if MCP server is enabled.
- Notable constants/configuration names: `_PRINTER`, `SEND_MESSAGE_DESCRIPTION`, `FINISH_CHAT_DESCRIPTION`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, network calls, settings/state persistence, secret handling, scheduler state.
- Imported dependency areas include: `agent`, `asyncio`, `contextvars`, `fastmcp`, `fastmcp.server.http`, `helpers`, `helpers.persist_chat`, `helpers.print_style`, `initialize`, `openai`, `os`, `pydantic`, `starlette.exceptions`, `starlette.middleware`, `starlette.middleware.base`, `starlette.requests`.
## Key Concepts
- Important called helpers/classes observed in the source: `PrintStyle`, `contextvars.ContextVar`, `FastMCP`, `mcp_server.tool`, `Field`, `settings.get_settings`, `initialize_agent`, `AgentContext`, `ToolError`, `ToolResponse`, `context.reset`, `AgentContext.remove`, `remove_chat`, `context.communicate`, `threading.RLock`, `self.reconfigure`, `StreamableHTTPSessionManager`, `mcp_server._get_additional_http_routes`, `create_base_app`, `PrintStyle.error`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_default_prompt_budget.py`
- `tests/test_fasta2a_client.py`
- `tests/test_ws_security.py`
## Child DOX Index
No child DOX files.

60
helpers/media_artifacts.py.dox.md Normal file
View file

@ -0,0 +1,60 @@
# media_artifacts.py DOX
## Purpose
- Own the `media_artifacts.py` helper module.
- This module validates, decodes, names, and normalizes media artifact payloads.
- Keep this file-level DOX profile synchronized with `media_artifacts.py` because this directory is intentionally flat.
## Ownership
- `media_artifacts.py` owns the runtime implementation.
- `media_artifacts.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `MediaArtifactError` (`ValueError`)
- `EmptyBase64Data` (`MediaArtifactError`)
- `InvalidBase64Data` (`MediaArtifactError`)
- `ArtifactTooLarge` (`MediaArtifactError`)
- `Base64Payload` (no explicit base class)
- `ImageDataUrl` (no explicit base class)
- `SavedArtifact` (no explicit base class)
- Top-level functions:
- `compact_base64(data: str) -> str`
- `estimated_base64_decoded_size(data: str) -> int`
- `decode_base64_payload(data: str, max_bytes: int | None=...) -> Base64Payload`
- `normalize_mime(mime_type: str, default: str=..., required_prefix: str=...) -> str`
- `guess_extension(mime_type: str, fallback: str=...) -> str`
- `filename_from_uri(uri: str) -> str`
- `safe_filename(value: str, default: str=..., default_extension: str=...) -> str`
- `image_data_url_from_base64(data: str, mime_type: str=..., max_bytes: int | None=...) -> ImageDataUrl`
- `save_base64_artifact(data: str, mime_type: str=..., directory_parts: tuple[str, ...], preferred_name: str=..., default_filename: str=..., max_bytes: int | None=...) -> SavedArtifact`
- Notable constants/configuration names: `DEFAULT_MAX_ARTIFACT_SIZE_BYTES`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, filesystem writes, network calls.
- Imported dependency areas include: `__future__`, `base64`, `binascii`, `dataclasses`, `helpers`, `mimetypes`, `pathlib`, `urllib.parse`, `uuid`.
## Key Concepts
- Important called helpers/classes observed in the source: `dataclass`, `join`, `compact_base64`, `Base64Payload`, `str.strip.lower`, `str.strip`, `urlparse`, `decode_base64_payload`, `normalize_mime`, `ImageDataUrl`, `guess_extension`, `safe_filename`, `Path`, `artifact_dir.mkdir`, `path.write_bytes`, `SavedArtifact`, `super.__init__`, `EmptyBase64Data`, `estimated_base64_decoded_size`, `base64.b64decode`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_mcp_handler_multimodal.py`
- `tests/test_media_artifacts.py`
## Child DOX Index
No child DOX files.

53
helpers/message_queue.py.dox.md Normal file
View file

@ -0,0 +1,53 @@
# message_queue.py DOX
## Purpose
- Own the `message_queue.py` helper module.
- This module stores and drains queued user messages for a context.
- Keep this file-level DOX profile synchronized with `message_queue.py` because this directory is intentionally flat.
## Ownership
- `message_queue.py` owns the runtime implementation.
- `message_queue.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Top-level functions:
- `get_queue(context: 'AgentContext') -> list`: Get current queue from context.data.
- `_get_next_seq(context: 'AgentContext') -> int`: Get next sequence number.
- `_sync_output(context: 'AgentContext')`: Sync queue to output_data for frontend polling.
- `add(context: 'AgentContext', text: str, attachments: list[str] | None=..., item_id: str | None=...) -> dict`: Add message to queue. Attachments should be filenames, will be converted to full paths.
- `remove(context: 'AgentContext', item_id: str | None=...) -> int`: Remove item(s). If item_id is None, clears all. Returns remaining count.
- `pop_first(context: 'AgentContext') -> dict | None`: Remove and return first item.
- `pop_item(context: 'AgentContext', item_id: str) -> dict | None`: Remove and return specific item.
- `has_queue(context: 'AgentContext') -> bool`: Check if queue has items.
- `log_user_message(context: 'AgentContext', message: str, attachment_paths: list[str], message_id: str | None=..., source: str=...)`: Log user message to console and UI. Used by message API and queue processing.
- `send_message(context: 'AgentContext', item: dict, source: str=...)`: Send a single queued message (log + communicate).
- `send_next(context: 'AgentContext') -> bool`: Send next queued message. Returns True if sent, False if queue empty.
- `send_all_aggregated(context: 'AgentContext') -> int`: Aggregate and send all queued messages as one. Returns count of items sent.
- Notable constants/configuration names: `QUEUE_KEY`, `QUEUE_SEQ_KEY`, `UPLOAD_FOLDER`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, filesystem deletion, settings/state persistence.
- Imported dependency areas include: `helpers`, `helpers.print_style`, `os`, `typing`, `uuid`.
## Key Concepts
- Important called helpers/classes observed in the source: `context.set_data`, `get_queue`, `context.set_output_data`, `_sync_output`, `queue.pop`, `context.log.log`, `log_user_message`, `context.communicate`, `pop_first`, `has_queue`, `join`, `context.get_data`, `att.startswith`, `_get_next_seq`, `uuid.uuid4`, `UserMessage`, `send_message`, `guids.generate_id`, `os.path.basename`, `PrintStyle`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- 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.

50
helpers/messages.py.dox.md Normal file
View file

@ -0,0 +1,50 @@
# messages.py DOX
## Purpose
- Own the `messages.py` helper module.
- This module truncates message payloads for display and storage safety.
- Keep this file-level DOX profile synchronized with `messages.py` because this directory is intentionally flat.
## Ownership
- `messages.py` owns the runtime implementation.
- `messages.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Top-level functions:
- `truncate_text(agent, output, threshold=...)`
- `truncate_dict_by_ratio(agent, data: dict | list | str, threshold_chars: int, truncate_to: int)`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, filesystem writes, settings/state persistence.
- Imported dependency areas include: `json`.
## Key Concepts
- Important called helpers/classes observed in the source: `agent.read_prompt`, `process_item`, `json.dumps`, `truncate_text`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/email_parser_test.py`
- `tests/test_browser_agent_regressions.py`
- `tests/test_chat_compaction.py`
- `tests/test_document_query_fallback.py`
- `tests/test_download_toast_regressions.py`
- `tests/test_fasta2a_client.py`
- `tests/test_mcp_handler_multimodal.py`
- `tests/test_oauth_codex.py`
## Child DOX Index
No child DOX files.

50
helpers/microsoft_tunnel.py.dox.md Normal file
View file

@ -0,0 +1,50 @@
# microsoft_tunnel.py DOX
## Purpose
- Own the `microsoft_tunnel.py` helper module.
- This module implements Microsoft Dev Tunnel provider behavior.
- Keep this file-level DOX profile synchronized with `microsoft_tunnel.py` because this directory is intentionally flat.
## Ownership
- `microsoft_tunnel.py` owns the runtime implementation.
- `microsoft_tunnel.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `AgentZeroMicrosoftTunnel` (`MicrosoftTunnel`)
- `notify(self, event, message, data=...)`
- `agent_zero_notifications(self)`
- `MicrosoftDevTunnel` (`FlaredanticTunnelHelper`)
- `build_tunnel(self)`
- `start(self)`
- Top-level functions:
- `default_microsoft_tunnel_id()`
- Notable constants/configuration names: `MICROSOFT_TUNNEL_ID_ENV_KEYS`, `MICROSOFT_TUNNEL_TIMEOUT`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, network calls, settings/state persistence, tunnel state.
- Imported dependency areas include: `flaredantic`, `getpass`, `hashlib`, `helpers`, `helpers.tunnel_common`, `os`, `socket`.
## Key Concepts
- Important called helpers/classes observed in the source: `join`, `strip`, `hashlib.sha256.hexdigest`, `self.notify`, `callable`, `self._notify_progress`, `self._run_cmd`, `MicrosoftConfig`, `AgentZeroMicrosoftTunnel`, `getpass.getuser`, `socket.gethostname`, `files.get_abs_path`, `super.notify`, `parent`, `super.start`, `hashlib.sha256`, `MicrosoftTunnelError`, `default_microsoft_tunnel_id`, `RuntimeError`, `seed.encode`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_tunnel_remote_link.py`
## Child DOX Index
No child DOX files.

52
helpers/migration.py.dox.md Normal file
View file

@ -0,0 +1,52 @@
# migration.py DOX
## Purpose
- Own the `migration.py` helper module.
- This module migrates legacy user data and runtime layout at startup.
- Keep this file-level DOX profile synchronized with `migration.py` because this directory is intentionally flat.
## Ownership
- `migration.py` owns the runtime implementation.
- `migration.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Top-level functions:
- `startup_migration() -> None`
- `migrate_user_data() -> None`: Migrate user data from /tmp and other locations to /usr.
- `convert_agents_json_yaml() -> None`
- `_move_dir(src: str, dst: str, overwrite: bool=...) -> None`: Move a directory from src to dst if src exists and dst does not.
- `_move_file(src: str, dst: str, overwrite: bool=...) -> None`: Move a file from src to dst if src exists and dst does not.
- `_migrate_memory(base_path: str=...) -> None`: Migrate memory subdirectories.
- `_merge_dir_contents(src_parent: str, dst_parent: str) -> None`: Moves all items from src_parent to dst_parent.
- `_cleanup_obsolete() -> None`: Remove directories that are no longer needed.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, settings/state persistence, secret handling, scheduler state.
- Imported dependency areas include: `helpers`, `helpers.print_style`, `json`, `os`.
## Key Concepts
- Important called helpers/classes observed in the source: `migrate_user_data`, `convert_agents_json_yaml`, `extension.call_extensions_sync`, `_move_dir`, `_move_file`, `_migrate_memory`, `_merge_dir_contents`, `_cleanup_obsolete`, `subagents.get_agents_roots`, `files.get_subdirectories`, `files.list_files`, `files.deabsolute_path`, `files.exists`, `files.move_dir`, `files.move_file`, `files.get_abs_path`, `os.path.isdir`, `os.path.join`, `files.delete_dir`, `os.path.isfile`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_browser_agent_regressions.py`
- `tests/test_office_canvas_setup.py`
- `tests/test_office_document_store.py`
- `tests/test_speech_plugin_split.py`
## Child DOX Index
No child DOX files.

53
helpers/modules.py.dox.md Normal file
View file

@ -0,0 +1,53 @@
# modules.py DOX
## Purpose
- Own the `modules.py` helper module.
- This module imports modules and classes dynamically with namespace cache control.
- Keep this file-level DOX profile synchronized with `modules.py` because this directory is intentionally flat.
## Ownership
- `modules.py` owns the runtime implementation.
- `modules.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Top-level functions:
- `import_module(file_path: str) -> ModuleType`
- `load_classes_from_folder(folder: str, name_pattern: str, base_class: Type[T], one_per_file: bool=...) -> list[Type[T]]`
- `load_classes_from_file(file: str, base_class: type[T], one_per_file: bool=...) -> list[type[T]]`
- `purge_namespace(namespace: str)`
- Notable constants/configuration names: `T`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, filesystem deletion.
- Imported dependency areas include: `fnmatch`, `helpers.files`, `importlib`, `importlib.util`, `inspect`, `os`, `re`, `sys`, `types`, `typing`.
## Key Concepts
- Important called helpers/classes observed in the source: `TypeVar`, `get_abs_path`, `os.path.basename.replace`, `importlib.util.spec_from_file_location`, `importlib.util.module_from_spec`, `spec.loader.exec_module`, `import_module`, `inspect.getmembers`, `to_delete.sort`, `importlib.invalidate_caches`, `ImportError`, `os.path.join`, `os.path.basename`, `issubclass`, `os.listdir`, `name.startswith`, `n.count`, `fnmatch`, `file_name.endswith`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_a0_connector_prompt_gating.py`
- `tests/test_browser_agent_regressions.py`
- `tests/test_docker_release_plan.py`
- `tests/test_error_retry_plugin.py`
- `tests/test_file_tree_visualize.py`
- `tests/test_git_version_label.py`
- `tests/test_mcp_handler_multimodal.py`
- `tests/test_memory_quality.py`
## Child DOX Index
No child DOX files.

55
helpers/network.py.dox.md Normal file
View file

@ -0,0 +1,55 @@
# network.py DOX
## Purpose
- Own the `network.py` helper module.
- This module validates public URLs and fetches remote resources safely.
- Keep this file-level DOX profile synchronized with `network.py` because this directory is intentionally flat.
## Ownership
- `network.py` owns the runtime implementation.
- `network.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `HttpFetchResult` (no explicit base class)
- `UnsafeUrlError` (`ValueError`)
- Top-level functions:
- `_build_request_headers() -> dict[str, str]`
- `_normalize_content_type(content_type: str | None) -> str | None`
- `resolve_host_ips(hostname: str) -> tuple[ipaddress._BaseAddress, ...]`
- `validate_public_http_url(url: str) -> tuple[ipaddress._BaseAddress, ...]`
- `fetch_public_http_resource(url: str, max_bytes: int, max_redirects: int=..., timeout: tuple[float, float]=...) -> HttpFetchResult`
- `is_loopback_address(address: str) -> bool`: Check whether *address* resolves to a loopback interface.
- Notable constants/configuration names: `SAFE_HTTP_SCHEMES`, `DEFAULT_FETCH_TIMEOUT`, `DEFAULT_HTTP_USER_AGENT`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: network calls, secret handling.
- Imported dependency areas include: `__future__`, `dataclasses`, `ipaddress`, `os`, `requests`, `socket`, `struct`, `urllib.parse`.
## Key Concepts
- Important called helpers/classes observed in the source: `frozenset`, `dataclass`, `strip`, `urlparse`, `parsed.hostname.rstrip.lower`, `resolve_host_ips`, `requests.Session`, `ValueError`, `content_type.split.strip.lower`, `socket.getaddrinfo`, `ipaddress.ip_address`, `seen.add`, `UnsafeUrlError`, `hostname.endswith`, `validate_public_http_url`, `socket.inet_pton`, `_checkers`, `parsed.hostname.rstrip`, `os.getenv`, `content_type.split.strip`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_oauth_gemini_api.py`
- `tests/test_oauth_github_copilot.py`
- `tests/test_oauth_xai_grok.py`
- `tests/test_plugin_scan_prompt.py`
- `tests/test_tunnel_remote_link.py`
## Child DOX Index
No child DOX files.

62
helpers/notification.py.dox.md Normal file
View file

@ -0,0 +1,62 @@
# notification.py DOX
## Purpose
- Own the `notification.py` helper module.
- This module owns notification data models and notification manager state.
- Keep this file-level DOX profile synchronized with `notification.py` because this directory is intentionally flat.
## Ownership
- `notification.py` owns the runtime implementation.
- `notification.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `NotificationType` (`Enum`)
- `NotificationPriority` (`Enum`)
- `NotificationItem` (no explicit base class)
- `mark_read(self)`
- `output(self)`
- `NotificationManager` (no explicit base class)
- `send_notification(type: NotificationType, priority: NotificationPriority, message: str, title: str=..., detail: str=..., display_time: int=..., group: str=..., id: str=...) -> NotificationItem`
- `add_notification(self, type: NotificationType, priority: NotificationPriority, message: str, title: str=..., detail: str=..., display_time: int=..., group: str=..., id: str=...) -> NotificationItem`
- `get_recent_notifications(self, seconds: int=...) -> list[NotificationItem]`
- `output(self, start: int | None=..., end: int | None=...) -> list[dict]`
- `output_all(self) -> list[dict]`
- `mark_read_by_ids(self, notification_ids: list[str]) -> int`
- `update_item(self, no: int, **kwargs) -> None`
- `mark_all_read(self)`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem deletion, settings/state persistence.
- Imported dependency areas include: `dataclasses`, `datetime`, `enum`, `helpers.localization`, `threading`, `uuid`.
## Key Concepts
- Important called helpers/classes observed in the source: `self.manager.update_item`, `threading.RLock`, `AgentContext.get_notification_manager.add_notification`, `mark_dirty_all`, `self._update_item`, `NotificationType`, `Localization.get.serialize_datetime`, `uuid.uuid4`, `Localization.get.now`, `timedelta`, `n.output`, `AgentContext.get_notification_manager`, `next`, `NotificationPriority`, `NotificationItem`, `self._enforce_limit`, `seen.add`, `notifications.output`, `nid.strip`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_download_toast_regressions.py`
- `tests/test_multi_tab_isolation.py`
- `tests/test_self_update_tag_filter.py`
- `tests/test_snapshot_parity.py`
- `tests/test_snapshot_schema_v1.py`
- `tests/test_state_monitor.py`
- `tests/test_state_sync_handler.py`
- `tests/test_state_sync_welcome_screen.py`
## Child DOX Index
No child DOX files.

42
helpers/performance.py.dox.md Normal file
View file

@ -0,0 +1,42 @@
# performance.py DOX
## Purpose
- Own the `performance.py` helper module.
- This module provides lightweight performance tracing helpers.
- Keep this file-level DOX profile synchronized with `performance.py` because this directory is intentionally flat.
## Ownership
- `performance.py` owns the runtime implementation.
- `performance.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Top-level functions:
- `trace_performance(show_all=..., color=..., unicode=...)`: Decorator that profiles a function and prints a call tree when it finishes.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Imported dependency areas include: `functools`, `inspect`, `pyinstrument`.
## Key Concepts
- Important called helpers/classes observed in the source: `inspect.iscoroutinefunction`, `functools.wraps`, `Profiler`, `profiler.start`, `profiler.stop`, `func`, `profiler.output_text`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_extensions_stress.py`
- `tests/test_ws_manager.py`
## Child DOX Index
No child DOX files.

41
helpers/perplexity_search.py.dox.md Normal file
View file

@ -0,0 +1,41 @@
# perplexity_search.py DOX
## Purpose
- Own the `perplexity_search.py` helper module.
- This module queries Perplexity search using configured model/provider credentials.
- Keep this file-level DOX profile synchronized with `perplexity_search.py` because this directory is intentionally flat.
## Ownership
- `perplexity_search.py` owns the runtime implementation.
- `perplexity_search.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Top-level functions:
- `perplexity_search(query: str, model_name=..., api_key=..., base_url=...)`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: secret handling.
- Imported dependency areas include: `models`, `openai`.
## Key Concepts
- Important called helpers/classes observed in the source: `OpenAI`, `client.chat.completions.create`, `models.get_api_key`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- 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.

65
helpers/persist_chat.py.dox.md Normal file
View file

@ -0,0 +1,65 @@
# persist_chat.py DOX
## Purpose
- Own the `persist_chat.py` helper module.
- This module persists and reloads chat contexts and message artifacts.
- Keep this file-level DOX profile synchronized with `persist_chat.py` because this directory is intentionally flat.
## Ownership
- `persist_chat.py` owns the runtime implementation.
- `persist_chat.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Top-level functions:
- `_fallback_datetime_iso() -> str`
- `_parse_persisted_datetime(value: str | None) -> datetime`
- `get_chat_folder_path(ctxid: str)`: Get the folder path for any context (chat or task).
- `get_chat_msg_files_folder(ctxid: str)`
- `save_tmp_chat(context: AgentContext)`: Save context to the chats folder
- `save_tmp_chats()`: Save all contexts to the chats folder
- `load_tmp_chats()`: Load all contexts from the chats folder
- `_get_chat_file_path(ctxid: str)`
- `_convert_v080_chats()`
- `load_json_chats(jsons: list[str])`: Load contexts from JSON strings
- `export_json_chat(context: AgentContext)`: Export context as JSON string
- `remove_chat(ctxid)`: Remove a chat or task context
- `remove_msg_files(ctxid)`: Remove all message files for a chat or task context
- `_serialize_context(context: AgentContext)`
- `_serialize_agent(agent: Agent)`
- `_serialize_log(log: Log)`
- `_deserialize_context(data)`
- `_deserialize_agents(agents: list[dict[str, Any]], config: AgentConfig, context: AgentContext) -> Agent`
- `_deserialize_log(data: dict[str, Any]) -> 'Log'`
- `_safe_json_serialize(obj, **kwargs)`
- Notable constants/configuration names: `CHATS_FOLDER`, `LOG_SIZE`, `CHAT_FILE_NAME`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, settings/state persistence, scheduler state.
- Imported dependency areas include: `agent`, `collections`, `datetime`, `helpers`, `helpers.localization`, `helpers.log`, `initialize`, `json`, `typing`, `uuid`.
## Key Concepts
- Important called helpers/classes observed in the source: `datetime.fromtimestamp.isoformat`, `datetime.fromisoformat`, `files.get_abs_path`, `_get_chat_file_path`, `files.make_dirs`, `_serialize_context`, `_safe_json_serialize`, `files.write_file`, `_convert_v080_chats`, `files.list_files`, `get_chat_folder_path`, `files.delete_dir`, `get_chat_msg_files_folder`, `agent.history.serialize`, `initialize_agent`, `_deserialize_log`, `AgentContext`, `_deserialize_agents`, `Log`, `log.set_initial_progress`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_api_chat_lifetime.py`
- `tests/test_browser_agent_regressions.py`
- `tests/test_persist_chat_log_ids.py`
- `tests/test_tool_action_contracts.py`
## Child DOX Index
No child DOX files.

81
helpers/plugins.py.dox.md Normal file
View file

@ -0,0 +1,81 @@
# plugins.py DOX
## Purpose
- Own the `plugins.py` helper module.
- This module discovers plugins, resolves plugin config/toggles, runs hooks, and tracks plugin updates.
- Keep this file-level DOX profile synchronized with `plugins.py` because this directory is intentionally flat.
## Ownership
- `plugins.py` owns the runtime implementation.
- `plugins.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `PluginAssetFile` (`TypedDict`)
- `PluginMetadata` (`BaseModel`)
- `PluginListItem` (`BaseModel`)
- `PluginUpdateInfo` (`BaseModel`)
- Top-level functions:
- `register_watchdogs()`
- `after_plugin_change(plugin_names: list[str] | None=..., python_change: bool=...)`
- `refresh_plugin_modules(plugin_names: list[str] | None=...)`
- `clear_plugin_cache(plugin_names: list[str] | None=...)`
- `get_plugin_roots(plugin_name: str=...) -> List[str]`: Plugin root directories, ordered by priority (user first).
- `get_plugins_list()`
- `get_enhanced_plugins_list(custom: bool=..., builtin: bool=..., plugin_names: list[str] | None=...) -> List[PluginListItem]`: Discover plugins by directory convention. First root wins on ID conflict.
- `get_custom_plugins_updates(plugin_names: list[str] | None=...) -> List[PluginUpdateInfo]`
- `get_plugin_meta(plugin_name: str)`
- `find_plugin_dir(plugin_name: str)`
- `uninstall_plugin(plugin_name)`
- `delete_plugin(plugin_name: str)`
- `get_plugin_paths(*subpaths) -> List[str]`
- `get_enabled_plugin_paths(agent: Agent | None, *subpaths) -> List[str]`
- `get_enabled_plugins(agent: Agent | None)`
- `determined_toggle_from_paths(default: bool, paths: Iterator[str])`
- `get_toggle_state(plugin_name: str) -> ToggleState`
- `toggle_plugin(plugin_name: str, enabled: bool, project_name: str=..., agent_profile: str=..., clear_overrides: bool=...)`
- `get_plugin_config(plugin_name: str, agent: Agent | None=..., project_name: str | None=..., agent_profile: str | None=...)`
- `get_default_plugin_config(plugin_name: str)`
- `save_plugin_config(plugin_name: str, project_name: str, agent_profile: str, settings: dict)`
- `find_plugin_asset(plugin_name: str, *subpaths, project_name=..., agent_profile=...)`
- `find_plugin_assets(*subpaths, plugin_name: str=..., project_name: str=..., agent_profile: str=..., only_first: bool=...) -> list[PluginAssetFile]`
- `determine_plugin_asset_path(plugin_name: str, project_name: str, agent_profile: str, *subpaths)`
- `send_frontend_reload_notification(plugin_names: list[str] | None=...)`: If the plugin changed has webui extensions, notify frontend to reload the page
- `call_plugin_hook(plugin_name: str, hook_name: str, default: Any=..., *args, **kwargs)`
- `_apply_defaults_from_env(plugin_name: str, config: dict[str, Any])`
- Notable constants/configuration names: `_META_TARGET_RE`, `META_FILE_NAME`, `CONFIG_FILE_NAME`, `CONFIG_DEFAULT_FILE_NAME`, `DISABLED_FILE_NAME`, `ENABLED_FILE_NAME`, `TOGGLE_FILE_PATTERN`, `HOOKS_SCRIPT`, `HOOKS_CACHE_AREA`, `PLUGINS_LIST_CACHE_AREA`, `ENABLED_PLUGINS_LIST_CACHE_AREA`, `ENABLED_PLUGINS_PATHS_CACHE_AREA`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, WebSocket state, plugin state, settings/state persistence, secret handling.
- Imported dependency areas include: `__future__`, `asyncio`, `glob`, `helpers`, `helpers.defer`, `helpers.watchdog`, `json`, `pathlib`, `pydantic`, `re`, `regex`, `time`, `typing`.
## Key Concepts
- Important called helpers/classes observed in the source: `re.compile`, `Field`, `watchdog.add_watchdog`, `clear_plugin_cache`, `send_frontend_reload_notification`, `DeferredTask.start_task`, `get_plugin_roots`, `result.sort`, `cache.add`, `get_enhanced_plugins_list`, `find_plugin_dir`, `files.get_abs_path`, `files.exists`, `call_plugin_hook`, `delete_plugin`, `files.delete_dir`, `after_plugin_change`, `get_enabled_plugins`, `get_plugins_list`, `get_plugin_meta`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_a0_connector_computer_use_metadata.py`
- `tests/test_a0_connector_prompt_gating.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_error_retry_plugin.py`
- `tests/test_host_browser_connector.py`
## Child DOX Index
No child DOX files.

40
helpers/print_catch.py.dox.md Normal file
View file

@ -0,0 +1,40 @@
# print_catch.py DOX
## Purpose
- Own the `print_catch.py` helper module.
- This module captures printed output from async callables.
- Keep this file-level DOX profile synchronized with `print_catch.py` because this directory is intentionally flat.
## Ownership
- `print_catch.py` owns the runtime implementation.
- `print_catch.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Top-level functions:
- `capture_prints_async(func: Callable[..., Awaitable[Any]], *args, **kwargs) -> Tuple[Awaitable[Any], Callable[[], str]]`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Imported dependency areas include: `asyncio`, `io`, `sys`, `typing`.
## Key Concepts
- Important called helpers/classes observed in the source: `io.StringIO`, `captured_output.getvalue`, `wrapped_func`, `func`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- 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.

54
helpers/print_style.py.dox.md Normal file
View file

@ -0,0 +1,54 @@
# print_style.py DOX
## Purpose
- Own the `print_style.py` helper module.
- This module formats console/debug output consistently.
- Keep this file-level DOX profile synchronized with `print_style.py` because this directory is intentionally flat.
## Ownership
- `print_style.py` owns the runtime implementation.
- `print_style.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `PrintStyle` (no explicit base class)
- `get(self, *args, sep=..., **kwargs)`
- `print(self, *args, sep=..., end=..., flush=...)`
- `stream(self, *args, sep=..., flush=...)`
- `is_last_line_empty(self)`
- `standard(*args, sep=..., end=..., flush=...)`
- `hint(*args, sep=..., end=..., flush=...)`
- `info(*args, sep=..., end=..., flush=...)`
- `success(*args, sep=..., end=..., flush=...)`
- Top-level functions:
- `_get_runtime()`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, WebSocket state, secret handling.
- Imported dependency areas include: `atexit`, `collections.abc`, `datetime`, `html`, `os`, `strings`, `sys`, `webcolors`.
## Key Concepts
- Important called helpers/classes observed in the source: `atexit.register`, `self._get_rgb_color_code`, `join`, `html.escape.replace`, `sep.join`, `self._format_args`, `sanitize_string`, `self._add_padding_if_needed`, `end.endswith`, `self._log_html`, `sys.stdin.readlines`, `PrintStyle._prefixed_args`, `files.get_abs_path`, `os.makedirs`, `datetime.now.strftime`, `os.path.join`, `f.write`, `self.secrets_mgr.mask_values`, `self._get_styled_text`, `self._get_html_styled_text`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_print_style.py`
- `tests/test_tool_action_contracts.py`
- `tests/test_ws_manager.py`
## Child DOX Index
No child DOX files.

54
helpers/process.py.dox.md Normal file
View file

@ -0,0 +1,54 @@
# process.py DOX
## Purpose
- Own the `process.py` helper module.
- This module manages process reload, restart, exit, and server references.
- Keep this file-level DOX profile synchronized with `process.py` because this directory is intentionally flat.
## Ownership
- `process.py` owns the runtime implementation.
- `process.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Top-level functions:
- `set_server(server)`
- `get_server(server)`
- `stop_server()`
- `reload()`
- `restart_process()`
- `exit_process()`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: subprocess/runtime control.
- Imported dependency areas include: `helpers`, `helpers.print_style`, `os`, `sys`.
## Key Concepts
- Important called helpers/classes observed in the source: `stop_server`, `runtime.is_dockerized`, `PrintStyle.standard`, `os.execv`, `sys.exit`, `_server.shutdown`, `exit_process`, `restart_process`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_api_chat_lifetime.py`
- `tests/test_browser_agent_regressions.py`
- `tests/test_docker_release_plan.py`
- `tests/test_document_query_plugin.py`
- `tests/test_download_toast_regressions.py`
- `tests/test_git_version_label.py`
- `tests/test_image_get_security.py`
- `tests/test_model_config_project_presets.py`
## Child DOX Index
No child DOX files.

85
helpers/projects.py.dox.md Normal file
View file

@ -0,0 +1,85 @@
# projects.py DOX
## Purpose
- Own the `projects.py` helper module.
- This module owns project metadata, workspace creation, Git status, and project-scoped settings.
- Keep this file-level DOX profile synchronized with `projects.py` because this directory is intentionally flat.
## Ownership
- `projects.py` owns the runtime implementation.
- `projects.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `FileStructureInjectionSettings` (`TypedDict`)
- `SubAgentSettings` (`TypedDict`)
- `BasicProjectData` (`TypedDict`)
- `GitStatusData` (`TypedDict`)
- `EditProjectData` (`BasicProjectData`)
- Top-level functions:
- `get_projects_parent_folder()`
- `get_project_folder(name: str)`
- `get_project_meta(name: str, *sub_dirs)`
- `delete_project(name: str)`
- `create_project(name: str, data: BasicProjectData)`
- `clone_git_project(name: str, git_url: str, git_token: str, data: BasicProjectData)`: Clone a git repository as a new A0 project. Token is used only for cloning via http header.
- `load_project_header(name: str)`
- `_default_file_structure_settings()`
- `_normalizeBasicData(data: BasicProjectData) -> BasicProjectData`
- `_normalizeEditData(data: EditProjectData) -> EditProjectData`
- `_edit_data_to_basic_data(data: EditProjectData)`
- `_basic_data_to_edit_data(data: BasicProjectData) -> EditProjectData`
- `update_project(name: str, data: EditProjectData)`
- `load_basic_project_data(name: str) -> BasicProjectData`
- `load_edit_project_data(name: str) -> EditProjectData`
- `save_project_header(name: str, data: BasicProjectData)`
- `load_project_llm_data(name: str) -> dict`
- `save_project_llm_settings(name: str, llm_data: object)`
- `get_active_projects_list()`
- `_get_projects_list(parent_dir)`
- `activate_project(context_id: str, name: str, mark_dirty: bool=...)`
- `deactivate_project(context_id: str, mark_dirty: bool=...)`
- `reactivate_project_in_chats(name: str)`
- `deactivate_project_in_chats(name: str)`
- `build_system_prompt_vars(name: str)`
- `get_additional_instructions_files(name: str)`
- `get_project_instruction_files(name: str, include_agents_md: bool=...) -> list[tuple[str, str]]`
- `get_project_agents_md_instruction_file(name: str) -> tuple[str, str] | None`
- `_format_project_instruction_files(instruction_files: list[tuple[str, str]]) -> str`
- `_normalize_include_agents_md(value: object) -> bool`
- Notable constants/configuration names: `PROJECTS_PARENT_DIR`, `PROJECT_META_DIR`, `PROJECT_INSTRUCTIONS_DIR`, `PROJECT_KNOWLEDGE_DIR`, `PROJECT_HEADER_FILE`, `PROJECT_AGENTS_MD_FILES`, `CONTEXT_DATA_KEY_PROJECT`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, plugin state, settings/state persistence, secret handling.
- Imported dependency areas include: `helpers`, `helpers.print_style`, `os`, `typing`.
## Key Concepts
- Important called helpers/classes observed in the source: `files.get_abs_path`, `files.delete_dir`, `deactivate_project_in_chats`, `files.create_dir_safe`, `create_project_meta_folders`, `_normalizeBasicData`, `save_project_header`, `save_project_llm_settings`, `files.basename`, `dirty_json.parse`, `FileStructureInjectionSettings`, `cast`, `_normalizeEditData`, `load_edit_project_data`, `_edit_data_to_basic_data`, `save_project_variables`, `save_project_secrets`, `save_project_subagents`, `reactivate_project_in_chats`, `load_basic_project_data`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_model_config_project_presets.py`
- `tests/test_office_document_store.py`
- `tests/test_plugin_activation_ui.py`
- `tests/test_projects.py`
- `tests/test_skills_runtime.py`
- `tests/test_task_scheduler_timezone.py`
- `tests/test_time_travel.py`
- `tests/test_tool_action_contracts.py`
## Child DOX Index
No child DOX files.

61
helpers/providers.py.dox.md Normal file
View file

@ -0,0 +1,61 @@
# providers.py DOX
## Purpose
- Own the `providers.py` helper module.
- This module loads model provider configuration and provider metadata.
- Keep this file-level DOX profile synchronized with `providers.py` because this directory is intentionally flat.
## Ownership
- `providers.py` owns the runtime implementation.
- `providers.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `FieldOption` (`TypedDict`)
- `ProviderManager` (no explicit base class)
- `get_instance(cls)`
- `reload(cls)`
- `get_providers(self, provider_type: ModelType) -> List[FieldOption]`
- `get_raw_providers(self, provider_type: ModelType) -> List[Dict[str, str]]`
- `get_provider_config(self, provider_type: ModelType, provider_id: str) -> Optional[Dict[str, str]]`
- Top-level functions:
- `get_providers(provider_type: ModelType) -> List[FieldOption]`: Convenience function to get providers of a specific type.
- `get_raw_providers(provider_type: ModelType) -> List[Dict[str, str]]`: Return full metadata for providers of a given type.
- `get_provider_config(provider_type: ModelType, provider_id: str) -> Optional[Dict[str, str]]`: Return metadata for a single provider (None if not found).
- `reload_providers()`: Re-merge base + plugin provider configs. Call after plugin changes.
- Notable constants/configuration names: `PROVIDER_MANAGER_CACHE_AREA`, `PROVIDER_MANAGER_CACHE_KEY`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, filesystem deletion, plugin state, settings/state persistence.
- Imported dependency areas include: `helpers`, `typing`, `yaml`.
## Key Concepts
- Important called helpers/classes observed in the source: `ProviderManager.get_instance.get_providers`, `ProviderManager.get_instance.get_raw_providers`, `ProviderManager.get_instance.get_provider_config`, `ProviderManager.reload`, `cache.remove`, `cls.get_instance`, `inst._load_providers`, `files.get_abs_path`, `self._normalise_yaml`, `get_enabled_plugin_paths`, `provider_id.lower`, `self.get_raw_providers`, `cls`, `cache.add`, `self._load_providers`, `self._load_yaml`, `items.sort`, `ProviderManager.get_instance`, `lower`, `yaml.safe_load`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_fastmcp_openapi_security.py`
- `tests/test_model_config_api_keys.py`
- `tests/test_oauth_codex.py`
- `tests/test_oauth_gemini_api.py`
- `tests/test_oauth_github_copilot.py`
- `tests/test_oauth_providers.py`
- `tests/test_oauth_xai_grok.py`
- `tests/test_onboarding_static.py`
## Child DOX Index
No child DOX files.

45
helpers/rate_limiter.py.dox.md Normal file
View file

@ -0,0 +1,45 @@
# rate_limiter.py DOX
## Purpose
- Own the `rate_limiter.py` helper module.
- This module provides simple rate-limiting primitives.
- Keep this file-level DOX profile synchronized with `rate_limiter.py` because this directory is intentionally flat.
## Ownership
- `rate_limiter.py` owns the runtime implementation.
- `rate_limiter.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `RateLimiter` (no explicit base class)
- `add(self, **kwargs)`
- `async cleanup(self)`
- `async get_total(self, key: str) -> int`
- `async wait(self, callback: Callable[[str, str, int, int], Awaitable[bool]] | None=...)`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Imported dependency areas include: `asyncio`, `time`, `typing`.
## Key Concepts
- Important called helpers/classes observed in the source: `asyncio.Lock`, `time.time`, `self.cleanup`, `asyncio.sleep`, `self.get_total`, `callback`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_stream_tool_early_stop.py`
## Child DOX Index
No child DOX files.

48
helpers/rfc.py.dox.md Normal file
View file

@ -0,0 +1,48 @@
# rfc.py DOX
## Purpose
- Own the `rfc.py` helper module.
- This module implements remote function call dispatch and serialization.
- Keep this file-level DOX profile synchronized with `rfc.py` because this directory is intentionally flat.
## Ownership
- `rfc.py` owns the runtime implementation.
- `rfc.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `RFCInput` (`TypedDict`)
- `RFCCall` (`TypedDict`)
- Top-level functions:
- `async call_rfc(url: str, password: str, module: str, function_name: str, args: list, kwargs: dict)`
- `async handle_rfc(rfc_call: RFCCall, password: str)`
- `async _call_function(module: str, function_name: str, *args, **kwargs)`
- `_get_function(module: str, function_name: str)`
- `async _send_json_data(url: str, data)`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem writes, network calls, settings/state persistence, secret handling.
- Imported dependency areas include: `aiohttp`, `helpers`, `importlib`, `inspect`, `json`, `typing`.
## Key Concepts
- Important called helpers/classes observed in the source: `RFCInput`, `RFCCall`, `json.loads`, `_get_function`, `inspect.iscoroutinefunction`, `importlib.import_module`, `_send_json_data`, `crypto.verify_data`, `Exception`, `_call_function`, `func`, `aiohttp.ClientSession`, `json.dumps`, `crypto.hash_data`, `session.post`, `response.json`, `response.text`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- 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.

42
helpers/rfc_exchange.py.dox.md Normal file
View file

@ -0,0 +1,42 @@
# rfc_exchange.py DOX
## Purpose
- Own the `rfc_exchange.py` helper module.
- This module handles privileged RFC exchange data such as root password provisioning.
- Keep this file-level DOX profile synchronized with `rfc_exchange.py` because this directory is intentionally flat.
## Ownership
- `rfc_exchange.py` owns the runtime implementation.
- `rfc_exchange.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Top-level functions:
- `async get_root_password()`
- `_provide_root_password(public_key_pem: str)`
- `_get_root_password()`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Imported dependency areas include: `helpers`.
## Key Concepts
- Important called helpers/classes observed in the source: `runtime.is_dockerized`, `_get_root_password`, `crypto.encrypt_data`, `crypto._generate_private_key`, `crypto._generate_public_key`, `crypto.decrypt_data`, `dotenv.get_dotenv_value`, `runtime.call_development_function`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- 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.

70
helpers/rfc_files.py.dox.md Normal file
View file

@ -0,0 +1,70 @@
# rfc_files.py DOX
## Purpose
- Own the `rfc_files.py` helper module.
- This module exposes RFC-safe filesystem operations.
- Keep this file-level DOX profile synchronized with `rfc_files.py` because this directory is intentionally flat.
## Ownership
- `rfc_files.py` owns the runtime implementation.
- `rfc_files.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Top-level functions:
- `get_abs_path(*relative_paths)`: Convert relative paths to absolute paths based on the base directory.
- `read_file_bin(relative_path: str, backup_dirs=...) -> bytes`: Read binary file content.
- `read_file_base64(relative_path: str, backup_dirs=...) -> str`: Read file content and return as base64 string.
- `write_file_binary(relative_path: str, content: bytes) -> bool`: Write binary content to a file.
- `write_file_base64(relative_path: str, content: str) -> bool`: Write base64 content to a file.
- `delete_file(relative_path: str) -> bool`: Delete a file.
- `delete_directory(relative_path: str) -> bool`: Delete a directory recursively.
- `list_directory(relative_path: str, include_hidden: bool=...) -> list`: List directory contents.
- `make_directories(relative_path: str) -> bool`: Create directories recursively.
- `path_exists(relative_path: str) -> bool`: Check if a path exists.
- `file_exists(relative_path: str) -> bool`: Check if a file exists.
- `folder_exists(relative_path: str) -> bool`: Check if a folder exists.
- `get_subdirectories(relative_path: str, include: str | list[str]=..., exclude: str | list[str] | None=...) -> list[str]`: Get subdirectories in a directory.
- `zip_directory(relative_path: str) -> str`: Create a zip archive of a directory.
- `move_file(source_path: str, destination_path: str) -> bool`: Move a file from source to destination.
- `read_directory_as_zip(relative_path: str) -> bytes`: Read entire directory contents as a zip file.
- `find_file_in_dirs(file_path: str, backup_dirs: list[str]) -> str`: Find a file in the main directory or backup directories.
- `_read_file_binary_impl(file_path: str) -> str`: Implementation function to read a file in binary mode.
- `_write_file_binary_impl(file_path: str, b64_content: str) -> bool`: Implementation function to write binary content to a file.
- `_delete_file_impl(file_path: str) -> bool`: Implementation function to delete a file.
- `_delete_folder_impl(folder_path: str) -> bool`: Implementation function to delete a folder recursively.
- `_list_folder_impl(folder_path: str, include_hidden: bool=...) -> list`: Implementation function to list folder contents.
- `_make_dirs_impl(folder_path: str) -> bool`: Implementation function to create directories.
- `_path_exists_impl(file_path: str) -> bool`: Implementation function to check if path exists.
- `_file_exists_impl(file_path: str) -> bool`: Implementation function to check if file exists.
- `_folder_exists_impl(folder_path: str) -> bool`: Implementation function to check if folder exists.
- `_get_subdirectories_impl(folder_path: str, include: str | list[str], exclude: str | list[str] | None) -> list[str]`: Implementation function to get subdirectories.
- `_zip_dir_impl(folder_path: str) -> str`: Implementation function to create a zip archive of a directory.
- `_move_file_impl(source_path: str, destination_path: str) -> bool`: Implementation function to move a file.
- `_read_directory_impl(dir_path: str) -> str`: Implementation function to zip a directory and return base64 encoded zip.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion.
- Imported dependency areas include: `base64`, `fnmatch`, `helpers`, `os`, `shutil`, `tempfile`, `zipfile`.
## Key Concepts
- Important called helpers/classes observed in the source: `os.path.abspath`, `os.path.join`, `find_file_in_dirs`, `runtime.call_development_function_sync`, `base64.b64decode`, `get_abs_path`, `base64.b64encode.decode`, `FileNotFoundError`, `os.path.exists`, `os.path.basename`, `os.path.isfile`, `Exception`, `os.makedirs`, `os.remove`, `os.path.isdir`, `shutil.rmtree`, `os.listdir`, `items.sort`, `tempfile.NamedTemporaryFile`, `zipfile.ZipFile`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- 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.

69
helpers/runtime.py.dox.md Normal file
View file

@ -0,0 +1,69 @@
# runtime.py DOX
## Purpose
- Own the `runtime.py` helper module.
- This module owns runtime identity, environment flags, and startup arguments.
- Keep this file-level DOX profile synchronized with `runtime.py` because this directory is intentionally flat.
## Ownership
- `runtime.py` owns the runtime implementation.
- `runtime.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Top-level functions:
- `initialize()`
- `get_arg(name: str)`
- `has_arg(name: str)`
- `is_dockerized() -> bool`
- `is_development() -> bool`
- `get_local_url()`
- `get_runtime_id() -> str`
- `get_persistent_id() -> str`
- `async call_development_function(func: Callable[..., Awaitable[T]], *args, **kwargs) -> T`
- `async call_development_function(func: Callable[..., T], *args, **kwargs) -> T`
- `async call_development_function(func: Union[Callable[..., T], Callable[..., Awaitable[T]]], *args, **kwargs) -> T`
- `async handle_rfc(rfc_call: rfc.RFCCall)`
- `_get_rfc_password() -> str`
- `_get_rfc_url() -> str`
- `call_development_function_sync(func: Union[Callable[..., T], Callable[..., Awaitable[T]]], *args, **kwargs) -> T`
- `get_web_ui_port()`
- `get_tunnel_api_port()`
- `get_platform()`
- `is_windows()`
- `get_terminal_executable()`
- Notable constants/configuration names: `T`, `R`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, filesystem writes, subprocess/runtime control, settings/state persistence, secret handling, tunnel state.
- Imported dependency areas include: `argparse`, `asyncio`, `helpers`, `inspect`, `nest_asyncio`, `pathlib`, `queue`, `secrets`, `sys`, `threading`, `typing`.
## Key Concepts
- Important called helpers/classes observed in the source: `nest_asyncio.apply`, `TypeVar`, `argparse.ArgumentParser`, `parser.add_argument`, `parser.parse_known_args`, `vars`, `is_dockerized`, `dotenv.get_dotenv_value`, `is_development`, `settings.get_settings`, `url.endswith`, `queue.Queue`, `threading.Thread`, `thread.start`, `thread.join`, `thread.is_alive`, `result_queue.get_nowait`, `cast`, `is_windows`, `get_arg`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_a0_connector_computer_use_metadata.py`
- `tests/test_a0_connector_prompt_gating.py`
- `tests/test_browser_agent_regressions.py`
- `tests/test_default_prompt_budget.py`
- `tests/test_document_query_plugin.py`
- `tests/test_host_browser_connector.py`
- `tests/test_http_auth_csrf.py`
- `tests/test_image_get_security.py`
## Child DOX Index
No child DOX files.

43
helpers/searxng.py.dox.md Normal file
View file

@ -0,0 +1,43 @@
# searxng.py DOX
## Purpose
- Own the `searxng.py` helper module.
- This module queries SearXNG search.
- Keep this file-level DOX profile synchronized with `searxng.py` because this directory is intentionally flat.
## Ownership
- `searxng.py` owns the runtime implementation.
- `searxng.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Top-level functions:
- `async search(query: str)`
- `async _search(query: str)`
- Notable constants/configuration names: `URL`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: network calls, settings/state persistence.
- Imported dependency areas include: `aiohttp`, `helpers`.
## Key Concepts
- Important called helpers/classes observed in the source: `runtime.call_development_function`, `aiohttp.ClientSession`, `session.post`, `response.json`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- 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.

62
helpers/secrets.py.dox.md Normal file
View file

@ -0,0 +1,62 @@
# secrets.py DOX
## Purpose
- Own the `secrets.py` helper module.
- This module loads, aliases, masks, and streams secret values safely.
- Keep this file-level DOX profile synchronized with `secrets.py` because this directory is intentionally flat.
## Ownership
- `secrets.py` owns the runtime implementation.
- `secrets.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `EnvLine` (no explicit base class)
- `StreamingSecretsFilter` (no explicit base class)
- `process_chunk(self, chunk: str) -> str`
- `finalize(self) -> str`
- `SecretsManager` (no explicit base class)
- `get_instance(cls, *secrets_files) -> 'SecretsManager'`
- `read_secrets_raw(self) -> str`
- `load_secrets(self) -> Dict[str, str]`
- `save_secrets(self, secrets_content: str)`
- `save_secrets_with_merge(self, submitted_content: str)`
- `get_keys(self) -> List[str]`
- `get_secrets_for_prompt(self) -> str`
- `create_streaming_filter(self) -> 'StreamingSecretsFilter'`
- Top-level functions:
- `alias_for_key(key: str, placeholder: str=...) -> str`
- `get_secrets_manager(context: 'AgentContext|None'=...) -> SecretsManager`
- `get_project_secrets_manager(project_name: str, merge_with_global: bool=...) -> SecretsManager`
- `get_default_secrets_manager() -> SecretsManager`
- Notable constants/configuration names: `ALIAS_PATTERN`, `DEFAULT_SECRETS_FILE`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, WebSocket state, settings/state persistence, secret handling.
- Imported dependency areas include: `dataclasses`, `dotenv.parser`, `helpers`, `helpers.errors`, `helpers.extension`, `io`, `os`, `re`, `threading`, `time`, `typing`.
## Key Concepts
- Important called helpers/classes observed in the source: `key.upper`, `placeholder.format`, `SecretsManager.get_instance`, `self._replace_full_values`, `self._longest_suffix_prefix`, `threading.RLock`, `join`, `files.write_file`, `self._invalidate_all_caches`, `self.load_secrets`, `self.read_secrets_raw`, `self.parse_env_lines`, `self._serialize_env_lines`, `StreamingSecretsFilter`, `re.sub`, `self.parse_env_content`, `parse_stream`, `AgentContext.current`, `projects.get_context_project_name`, `files.get_abs_path`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_plugin_scan_prompt.py`
- `tests/test_print_style.py`
- `tests/test_time_travel.py`
## Child DOX Index
No child DOX files.

45
helpers/security.py.dox.md Normal file
View file

@ -0,0 +1,45 @@
# security.py DOX
## Purpose
- Own the `security.py` helper module.
- This module contains small security helpers such as filename sanitization.
- Keep this file-level DOX profile synchronized with `security.py` because this directory is intentionally flat.
## Ownership
- `security.py` owns the runtime implementation.
- `security.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Top-level functions:
- `safe_filename(filename: str) -> Optional[str]`
- Notable constants/configuration names: `FORBIDDEN_CHARS_RE`, `WINDOWS_RESERVED`, `FILENAME_MAX_LENGTH`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, filesystem deletion.
- Imported dependency areas include: `pathlib`, `re`, `typing`, `unicodedata`.
## Key Concepts
- Important called helpers/classes observed in the source: `re.compile`, `frozenset`, `unicodedata.normalize`, `FORBIDDEN_CHARS_RE.sub`, `filename.lstrip.rstrip`, `Path`, `join`, `stem.upper`, `filename.lstrip`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_fastmcp_openapi_security.py`
- `tests/test_image_get_security.py`
- `tests/test_ws_security.py`
## Child DOX Index
No child DOX files.

77
helpers/self_update.py.dox.md Normal file
View file

@ -0,0 +1,77 @@
# self_update.py DOX
## Purpose
- Own the `self_update.py` helper module.
- This module manages self-update status, scheduling, tag selection, and durable scripts.
- Keep this file-level DOX profile synchronized with `self_update.py` because this directory is intentionally flat.
## Ownership
- `self_update.py` owns the runtime implementation.
- `self_update.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `PendingUpdateConfig` (`TypedDict`)
- `UpdateStatus` (`TypedDict`)
- `SelectorTagOption` (`TypedDict`)
- Top-level functions:
- `_now_iso() -> str`
- `get_update_file_path() -> Path`
- `get_status_file_path() -> Path`
- `get_log_file_path() -> Path`
- `get_durable_exe_dir() -> Path`
- `get_durable_self_update_manager_path() -> Path`
- `_load_yaml(path: Path) -> dict[str, Any] | None`
- `_write_yaml(path: Path, payload: dict[str, Any]) -> None`
- `load_pending_update() -> PendingUpdateConfig | None`
- `load_last_status() -> UpdateStatus | None`
- `get_log_text() -> str`
- `get_default_backup_dir(repo_dir: str | Path | None=...) -> Path`
- `get_repo_dir(repo_dir: str | Path | None=...) -> Path`
- `get_repo_self_update_manager_path(repo_dir: str | Path | None=...) -> Path`
- `_get_official_remote_url() -> str`
- `_run_git_raw(*args) -> str`
- `_run_git(repo_dir: str | Path, *args) -> str`
- `_normalize_describe_to_version(describe: str) -> str`
- `_split_describe_version(describe: str) -> tuple[str, int]`
- `_is_latest_selector_tag(tag: str) -> bool`
- `_get_tag_release_time_in_repo(repo_dir: str | Path, tag: str) -> str`
- `get_repo_version_info(repo_dir: str | Path | None=...) -> dict[str, str]`
- `_sanitize_filename(name: str, default_name: str) -> str`
- `_slugify_version(text: str) -> str`
- `build_default_backup_name(current_version: str, target_tag: str | None=...) -> str`
- `_resolve_backup_path(backup_path: str, repo_dir: str | Path | None=...) -> Path`
- `_is_excluded_self_update_branch(branch: str) -> bool`
- `_sort_branch_names(branches: list[str]) -> list[str]`
- `_get_remote_branch_names() -> list[str]`
- `_get_local_origin_branch_names(repo_dir: str | Path | None=...) -> list[str]`
- Notable constants/configuration names: `OFFICIAL_REPO_AUTHOR`, `OFFICIAL_REPO_NAME`, `BRANCH_OPTIONS`, `SUPPORTED_BRANCHES`, `BACKUP_CONFLICT_POLICIES`, `MIN_SELECTOR_VERSION`, `REMOTE_BRANCH_TAG_CACHE_TTL_SECONDS`, `REMOTE_BRANCH_LIST_CACHE_TTL_SECONDS`, `UPDATE_FILE_PATH`, `STATUS_FILE_PATH`, `LOG_FILE_PATH`, `DURABLE_EXE_DIR`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, filesystem writes, subprocess/runtime control, settings/state persistence.
- Imported dependency areas include: `__future__`, `datetime`, `helpers`, `helpers.localization`, `os`, `pathlib`, `re`, `subprocess`, `tempfile`, `time`, `typing`.
## Key Concepts
- Important called helpers/classes observed in the source: `Path`, `Localization.get.now_iso`, `yaml.loads`, `path.parent.mkdir`, `path.write_text`, `_load_yaml`, `get_log_file_path`, `path.read_text`, `subprocess.run`, `completed.stdout.strip`, `re.fullmatch`, `describe.strip`, `tag.strip`, `get_repo_dir`, `_run_git`, `_normalize_describe_to_version`, `strip`, `re.sub.strip`, `Localization.get.now.strftime`, `path.resolve`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_office_document_store.py`
- `tests/test_self_update_tag_filter.py`
## Child DOX Index
No child DOX files.

43
helpers/serveo_tunnel.py.dox.md Normal file
View file

@ -0,0 +1,43 @@
# serveo_tunnel.py DOX
## Purpose
- Own the `serveo_tunnel.py` helper module.
- This module implements Serveo tunnel provider behavior.
- Keep this file-level DOX profile synchronized with `serveo_tunnel.py` because this directory is intentionally flat.
## Ownership
- `serveo_tunnel.py` owns the runtime implementation.
- `serveo_tunnel.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `ServeoTunnelHelper` (`FlaredanticTunnelHelper`)
- `build_tunnel(self)`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: settings/state persistence, tunnel state.
- Imported dependency areas include: `flaredantic`, `helpers.tunnel_common`.
## Key Concepts
- Important called helpers/classes observed in the source: `ServeoConfig`, `ServeoTunnel`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_tunnel_remote_link.py`
## Child DOX Index
No child DOX files.

62
helpers/server_startup.py.dox.md Normal file
View file

@ -0,0 +1,62 @@
# server_startup.py DOX
## Purpose
- Own the `server_startup.py` helper module.
- This module runs Uvicorn startup with health checks and retry tracking.
- Keep this file-level DOX profile synchronized with `server_startup.py` because this directory is intentionally flat.
## Ownership
- `server_startup.py` owns the runtime implementation.
- `server_startup.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `StartupConfig` (no explicit base class)
- `from_env(cls) -> 'StartupConfig'`
- `StartupStageRecord` (no explicit base class)
- `StartupMonitor` (no explicit base class)
- `mark(self, stage: str, detail: str | None=...) -> None`
- `stage(self, stage: str, detail: str | None=...) -> Iterator[None]`
- `lifespan(self)`
- `attach_server(self, server: uvicorn.Server) -> None`
- `start_watchdog(self) -> None`
- `mark_ready(self, source: str=...) -> None`
- `is_ready(self) -> bool`
- `close(self) -> None`
- `_UvicornServerWrapper` (no explicit base class)
- `shutdown(self) -> None`
- Top-level functions:
- `_env_int(name: str, default: int, minimum: int=...) -> int`
- `_env_float(name: str, default: float, minimum: float=...) -> float`
- `get_health_probe_host(bind_host: str) -> str`
- `run_uvicorn_with_retries(host: str, port: int, build_asgi_app: Callable[[StartupMonitor], object], flush_callback: Callable[[str], None], access_log: bool=..., log_level: str=..., ws: str=..., startup_config: StartupConfig | None=...) -> None`
- `_run_server_attempt(host: str, health_host: str, port: int, startup_monitor: StartupMonitor, build_asgi_app: Callable[[StartupMonitor], object], flush_callback: Callable[[str], None], access_log: bool, log_level: str, ws: str) -> bool`
- `wait_for_health(host: str, port: int, startup_monitor: StartupMonitor) -> None`
- `_serve_uvicorn(server: uvicorn.Server) -> None`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem writes, network calls, subprocess/runtime control, settings/state persistence.
- Imported dependency areas include: `asyncio`, `collections`, `contextlib`, `dataclasses`, `faulthandler`, `helpers`, `helpers.print_style`, `os`, `sys`, `threading`, `time`, `typing`, `urllib.request`, `uvicorn`.
## Key Concepts
- Important called helpers/classes observed in the source: `dataclass`, `get_health_probe_host`, `PrintStyle.debug`, `RuntimeError`, `startup_monitor.start_watchdog`, `server.config.get_loop_factory`, `cls`, `time.monotonic`, `deque`, `threading.Event`, `threading.RLock`, `self.mark`, `threading.Thread`, `self._watchdog_thread.start`, `self._ready.is_set`, `self.snapshot`, `PrintStyle.error`, `join`, `StartupConfig.from_env`, `StartupMonitor`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- 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.

88
helpers/settings.py.dox.md Normal file
View file

@ -0,0 +1,88 @@
# settings.py DOX
## Purpose
- Own the `settings.py` helper module.
- This module defines settings models, defaults, validation, and serialization.
- Keep this file-level DOX profile synchronized with `settings.py` because this directory is intentionally flat.
## Ownership
- `settings.py` owns the runtime implementation.
- `settings.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `Settings` (`TypedDict`)
- `PartialSettings` (`Settings`)
- `FieldOption` (`TypedDict`)
- `SettingsField` (`TypedDict`)
- `SettingsSection` (`TypedDict`)
- `ModelProvider` (`ProvidersFO`)
- `SettingsOutputAdditional` (`TypedDict`)
- `SettingsOutput` (`TypedDict`)
- Top-level functions:
- `get_default_value(name: str, value: T) -> T`: Load setting value from .env with A0_SET_ prefix, falling back to default.
- `_ensure_option_present(options: list[OptionT] | None, current_value: str | None) -> list[OptionT]`: Ensure the currently selected value exists in a dropdown options list.
- `_is_valid_timezone(value: str) -> bool`
- `_normalize_timezone_setting(value: Any, default: str=...) -> str`
- `_normalize_time_format(value: Any, default: str=...) -> str`
- `_resolve_runtime_timezone(setting_value: str, browser_timezone: str | None=...) -> str`
- `_timezone_options() -> list[FieldOption]`
- `convert_out(settings: Settings) -> SettingsOutput`
- `_get_api_key_field(settings: Settings, provider: str, title: str) -> SettingsField`
- `convert_in(settings: Settings) -> Settings`
- `get_settings() -> Settings`
- `reload_settings() -> Settings`
- `set_runtime_settings_snapshot(settings: Settings) -> None`
- `set_settings(settings: Settings, apply: bool=..., browser_timezone: str | None=...)`
- `set_settings_delta(delta: dict, apply: bool=...)`
- `merge_settings(original: Settings, delta: dict) -> Settings`
- `normalize_settings(settings: Settings) -> Settings`
- `_adjust_to_version(settings: Settings, default: Settings)`
- `_load_sensitive_settings(settings: Settings)`
- `_read_settings_file() -> Settings | None`
- `_write_settings_file(settings: Settings)`
- `_remove_sensitive_settings(settings: Settings)`
- `_write_sensitive_settings(settings: Settings)`
- `get_default_settings() -> Settings`
- `_apply_timezone_setting(previous: Settings | None, browser_timezone: str | None=...) -> None`
- `_apply_settings(previous: Settings | None, browser_timezone: str | None=...)`
- `_env_to_dict(data: str)`
- `_dict_to_env(data_dict)`
- `set_root_password(password: str)`
- `get_runtime_config(set: Settings)`
- Notable constants/configuration names: `T`, `PASSWORD_PLACEHOLDER`, `API_KEY_PLACEHOLDER`, `TIMEZONE_AUTO`, `TIME_FORMAT_12H`, `TIME_FORMAT_24H`, `SETTINGS_FILE`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, network calls, subprocess/runtime control, model calls, WebSocket state, plugin state, settings/state persistence, secret handling, scheduler state.
- Imported dependency areas include: `base64`, `hashlib`, `helpers`, `helpers.notification`, `helpers.print_style`, `helpers.providers`, `helpers.secrets`, `json`, `models`, `os`, `pytz`, `re`, `subprocess`, `typing`.
## Key Concepts
- Important called helpers/classes observed in the source: `TypeVar`, `files.get_abs_path`, `dotenv.get_dotenv_value`, `opts.insert`, `str.strip`, `_is_valid_timezone`, `str.strip.lower`, `_normalize_timezone_setting`, `SettingsOutput`, `get_default_settings`, `_ensure_option_present`, `_resolve_runtime_timezone`, `get_default_secrets_manager`, `get_settings`, `normalize_settings`, `_load_sensitive_settings`, `settings.copy`, `_write_settings_file`, `reload_settings`, `set_settings`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_browser_agent_regressions.py`
- `tests/test_document_query_plugin.py`
- `tests/test_download_toast_regressions.py`
- `tests/test_fasta2a_client.py`
- `tests/test_mcp_handler_multimodal.py`
- `tests/test_model_config_api_keys.py`
- `tests/test_model_config_project_presets.py`
- `tests/test_oauth_static.py`
## Child DOX Index
No child DOX files.

83
helpers/skills.py.dox.md Normal file
View file

@ -0,0 +1,83 @@
# skills.py DOX
## Purpose
- Own the `skills.py` helper module.
- This module discovers, parses, filters, and resolves Agent Zero skills.
- Keep this file-level DOX profile synchronized with `skills.py` because this directory is intentionally flat.
## Ownership
- `skills.py` owns the runtime implementation.
- `skills.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `ActiveSkillEntry` (`TypedDict`)
- `CatalogSkill` (`TypedDict`)
- `Skill` (no explicit base class)
- Top-level functions:
- `get_skills_base_dir() -> Path`
- `get_skill_roots(agent: Agent | None=...) -> List[str]`
- `_is_hidden_path(path: Path) -> bool`
- `discover_skill_md_files(root: Path) -> List[Path]`: Recursively discover SKILL.md files under a root directory.
- `_coerce_list(value: Any) -> List[str]`
- `_normalize_name(name: str) -> str`
- `_read_text(path: Path) -> str`
- `split_frontmatter(markdown: str) -> Tuple[Dict[str, Any], str, List[str]]`: Splits a SKILL.md into (frontmatter_dict, body_text, errors).
- `_parse_frontmatter_fallback(frontmatter_text: str) -> Dict[str, Any]`
- `parse_frontmatter(frontmatter_text: str) -> Tuple[Dict[str, Any], List[str]]`: Parse YAML frontmatter with PyYAML when available,
- `skill_from_markdown(skill_md_path: Path, include_content: bool=..., validate: bool=...) -> Optional[Skill]`
- `list_skills(agent: Agent | None=..., include_content: bool=..., include_hidden: bool=...) -> List[Skill]`: List skills, optionally filtered by agent scope.
- `delete_skill(skill_path: str) -> None`: Delete a skill directory.
- `find_skill(skill_name: str, agent: Agent | None=..., include_content: bool=..., include_hidden: bool=...) -> Optional[Skill]`
- `load_skill_for_agent(skill_name: str, agent: Agent | None=...) -> str`: Load skill and format it as a complete string for agent context.
- `_get_skill_files(skill_dir: Path) -> str`: Get file tree for skill directory.
- `search_skills(query: str, limit: int=..., agent: Agent | None=..., include_hidden: bool=...) -> List[Skill]`
- `validate_skill(skill: Skill) -> List[str]`
- `validate_skill_md(skill_md_path: Path) -> List[str]`
- `_normalize_max_active_skills(value: Any) -> int`
- `get_max_active_skills(agent: Agent | None=..., project_name: str | None=...) -> int`
- `normalize_skills_config(config: dict[str, Any] | None) -> dict[str, Any]`
- `normalize_active_skills(raw: Any, limit: int | None=...) -> list[ActiveSkillEntry]`
- `normalize_hidden_skills(raw: Any) -> list[ActiveSkillEntry]`
- `normalize_skill_entries(raw: Any, limit: int | None=...) -> list[ActiveSkillEntry]`
- `list_skill_catalog(project_name: str=..., agent: Agent | None=...) -> list[CatalogSkill]`
- `get_scope_active_skills(agent: Agent | None) -> list[ActiveSkillEntry]`
- `get_scope_hidden_skills(agent: Agent | None) -> list[ActiveSkillEntry]`
- `get_chat_active_skills(context: Any | None) -> list[ActiveSkillEntry]`
- `get_chat_disabled_skills(context: Any | None) -> list[ActiveSkillEntry]`
- Notable constants/configuration names: `MAX_ACTIVE_SKILLS`, `ACTIVE_SKILLS_PLUGIN_NAME`, `AGENT_DATA_NAME_LOADED_SKILLS`, `CONTEXT_DATA_NAME_CHAT_ACTIVE_SKILLS`, `CONTEXT_DATA_NAME_CHAT_DISABLED_SKILLS`, `CONTEXT_DATA_NAME_CHAT_VISIBLE_SKILLS`, `_NAME_RE`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, filesystem deletion, plugin state, settings/state persistence, secret handling.
- Imported dependency areas include: `__future__`, `dataclasses`, `helpers`, `os`, `pathlib`, `re`, `typing`.
## Key Concepts
- Important called helpers/classes observed in the source: `dataclass`, `re.compile`, `field`, `Path`, `root.rglob`, `results.sort`, `re.sub`, `path.read_text`, `text.splitlines`, `join.strip`, `parse_frontmatter`, `frontmatter_text.splitlines`, `_parse_frontmatter_fallback`, `split_frontmatter`, `str.strip`, `_coerce_list`, `Skill`, `get_skill_roots`, `_filter_hidden_skills`, `files.get_abs_path`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_a0_connector_prompt_gating.py`
- `tests/test_browser_agent_regressions.py`
- `tests/test_document_query_plugin.py`
- `tests/test_fasta2a_client.py`
- `tests/test_office_canvas_setup.py`
- `tests/test_office_document_store.py`
- `tests/test_skills_runtime.py`
- `tests/test_time_travel.py`
## Child DOX Index
No child DOX files.

51
helpers/skills_cli.py.dox.md Normal file
View file

@ -0,0 +1,51 @@
# skills_cli.py DOX
## Purpose
- Own the `skills_cli.py` helper module.
- This module provides command-line skill listing, search, validation, and creation helpers.
- Keep this file-level DOX profile synchronized with `skills_cli.py` because this directory is intentionally flat.
## Ownership
- `skills_cli.py` owns the runtime implementation.
- `skills_cli.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `Skill` (no explicit base class)
- Top-level functions:
- `get_skills_dirs() -> List[Path]`: Get all skill directories
- `parse_skill_file(skill_path: Path) -> Optional[Skill]`: Parse a SKILL.md file and return a Skill object
- `list_skills() -> List[Skill]`: List all available skills
- `find_skill(name: str) -> Optional[Skill]`: Find a skill by name
- `search_skills(query: str) -> List[Skill]`: Search skills by name, description, or tags
- `validate_skill(skill: Skill) -> List[str]`: Validate a skill and return list of issues
- `create_skill(name: str, description: str=..., author: str=...) -> Path`: Create a new skill from template
- `print_skill_table(skills: List[Skill])`: Print skills in a formatted table
- `main()`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, filesystem writes, settings/state persistence, secret handling.
- Imported dependency areas include: `argparse`, `dataclasses`, `datetime`, `helpers`, `os`, `pathlib`, `re`, `sys`, `typing`, `yaml`.
## Key Concepts
- Important called helpers/classes observed in the source: `sys.path.insert`, `field`, `Path`, `get_skills_dirs`, `list_skills`, `query.lower`, `exists`, `custom_dir.mkdir`, `skill_dir.exists`, `skill_dir.mkdir`, `mkdir`, `skill_file.write_text`, `readme.write_text`, `argparse.ArgumentParser`, `parser.add_subparsers`, `subparsers.add_parser`, `list_parser.add_argument`, `create_parser.add_argument`, `show_parser.add_argument`, `validate_parser.add_argument`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- 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.

55
helpers/skills_import.py.dox.md Normal file
View file

@ -0,0 +1,55 @@
# skills_import.py DOX
## Purpose
- Own the `skills_import.py` helper module.
- This module plans and imports skill bundles into user, project, or profile scopes.
- Keep this file-level DOX profile synchronized with `skills_import.py` because this directory is intentionally flat.
## Ownership
- `skills_import.py` owns the runtime implementation.
- `skills_import.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `ImportPlanItem` (no explicit base class)
- `ImportResult` (no explicit base class)
- Top-level functions:
- `_is_within(child: Path, parent: Path) -> bool`
- `_derive_namespace(source: Path) -> str`
- `_candidate_skill_roots(source_dir: Path) -> List[Path]`: Heuristics to find likely skill roots inside a repo/pack:
- `_unzip_to_temp_dir(zip_path: Path) -> Path`: Extract a zip into a temp folder under tmp/skill_imports (inside Agent Zero base dir).
- `build_import_plan(source: Path, dest_root: Path, namespace: Optional[str]=...) -> Tuple[List[ImportPlanItem], Path]`: Build a copy plan for importing skills from a source folder.
- `_resolve_conflict(dest: Path, policy: ConflictPolicy) -> Tuple[Path, bool]`: Returns (final_dest_path, should_copy).
- `get_project_skills_folder(project_name: str) -> Path`: Get the skills folder path for a project.
- `get_agent_profile_skills_folder(profile_name: str) -> Path`
- `get_project_agent_profile_skills_folder(project_name: str, profile_name: str) -> Path`
- `resolve_skills_destination_root(project_name: Optional[str], agent_profile: Optional[str]) -> Path`
- `import_skills(source_path: str, namespace: Optional[str]=..., conflict: ConflictPolicy=..., dry_run: bool=..., project_name: Optional[str]=..., agent_profile: Optional[str]=...) -> ImportResult`: Import external Skills into usr/skills/<namespace>/...
- Notable constants/configuration names: `PROJECT_SKILLS_DIR`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, plugin state.
- Imported dependency areas include: `__future__`, `dataclasses`, `helpers`, `helpers.skills`, `os`, `pathlib`, `shutil`, `tempfile`, `time`, `typing`, `zipfile`.
## Key Concepts
- Important called helpers/classes observed in the source: `dataclass`, `strip`, `plugins.is_dir`, `Path`, `base_tmp.mkdir`, `time.strftime`, `target.mkdir`, `_candidate_skill_roots`, `Path.expanduser`, `resolve_skills_destination_root`, `dest_root.mkdir`, `build_import_plan`, `ImportResult`, `child.resolve.relative_to`, `direct.is_dir`, `discover_skill_md_files`, `plugins.iterdir`, `files.get_abs_path`, `zipfile.ZipFile`, `z.extractall`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- 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.

45
helpers/state_migration.py.dox.md Normal file
View file

@ -0,0 +1,45 @@
# state_migration.py DOX
## Purpose
- Own the `state_migration.py` helper module.
- This module moves retired state tree paths to current runtime locations.
- Keep this file-level DOX profile synchronized with `state_migration.py` because this directory is intentionally flat.
## Ownership
- `state_migration.py` owns the runtime implementation.
- `state_migration.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Top-level functions:
- `migrate_retired_state_tree(source: Path, destination: Path, owner: str, migrated: list[str], warnings: list[str], errors: list[str]) -> None`: Move retired plugin state into its plugin-owned state directory.
- `_move_path(source: Path, target: Path, migrated: list[str]) -> None`
- `_next_conflict_path(path: Path) -> Path`
- `_remove_empty_dir(path: Path, owner: str, warnings: list[str]) -> None`
- `_same_path(left: Path, right: Path) -> bool`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, filesystem writes, plugin state, settings/state persistence.
- Imported dependency areas include: `__future__`, `pathlib`, `shutil`.
## Key Concepts
- Important called helpers/classes observed in the source: `_same_path`, `final_target.parent.mkdir`, `shutil.move`, `path.with_name`, `_move_path`, `source.is_dir`, `target.is_dir`, `source.rmdir`, `target.exists`, `target.is_symlink`, `_next_conflict_path`, `candidate.exists`, `candidate.is_symlink`, `path.rmdir`, `source.exists`, `source.is_symlink`, `destination.mkdir`, `_remove_empty_dir`, `source.iterdir`, `left.resolve`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- 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.

59
helpers/state_monitor.py.dox.md Normal file
View file

@ -0,0 +1,59 @@
# state_monitor.py DOX
## Purpose
- Own the `state_monitor.py` helper module.
- This module tracks dirty state and connection projections for WebUI sync.
- Keep this file-level DOX profile synchronized with `state_monitor.py` because this directory is intentionally flat.
## Ownership
- `state_monitor.py` owns the runtime implementation.
- `state_monitor.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `ConnectionProjection` (no explicit base class)
- `StateMonitor` (no explicit base class)
- `bind_manager(self, manager: 'WsManager', handler_id: str | None=...) -> None`
- `register_sid(self, namespace: str, sid: str) -> None`
- `unregister_sid(self, namespace: str, sid: str) -> None`
- `mark_dirty_all(self, reason: str | None=...) -> None`
- `mark_dirty_for_context(self, context_id: str, reason: str | None=...) -> None`
- `update_projection(self, namespace: str, sid: str, request: StateRequestV1, seq_base: int) -> None`
- `mark_dirty(self, namespace: str, sid: str, reason: str | None=..., wave_id: str | None=...) -> None`
- Top-level functions:
- `get_state_monitor() -> StateMonitor`
- `_reset_state_monitor_for_testing() -> None`
- Notable constants/configuration names: `_STATE_MONITOR_HOLDER`, `_STATE_MONITOR_LOCK`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem deletion, WebSocket state, settings/state persistence, scheduler state.
- Imported dependency areas include: `__future__`, `asyncio`, `dataclasses`, `helpers`, `helpers.print_style`, `helpers.state_snapshot`, `helpers.ws`, `helpers.ws_manager`, `os`, `threading`, `time`, `typing`.
## Key Concepts
- Important called helpers/classes observed in the source: `threading.RLock`, `field`, `ws_debug`, `_ws_debug_enabled`, `context_id.strip`, `loop.call_soon_threadsafe`, `self._schedule_debounce_on_loop`, `asyncio.get_running_loop`, `asyncio.current_task`, `loop.is_closed`, `self._debounce_handles.pop`, `self._push_tasks.pop`, `self._projections.pop`, `self.mark_dirty`, `self._mark_dirty_on_loop`, `runtime.is_development`, `loop.call_later`, `StateMonitor`, `ConnectionProjection`, `handle.cancel`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_model_config_api_keys.py`
- `tests/test_multi_tab_isolation.py`
- `tests/test_state_monitor.py`
- `tests/test_state_sync_handler.py`
- `tests/test_state_sync_welcome_screen.py`
- `tests/test_ws_handlers.py`
## Child DOX Index
No child DOX files.

43
helpers/state_monitor_integration.py.dox.md Normal file
View file

@ -0,0 +1,43 @@
# state_monitor_integration.py DOX
## Purpose
- Own the `state_monitor_integration.py` helper module.
- This module bridges dirty-state calls into the shared state monitor.
- Keep this file-level DOX profile synchronized with `state_monitor_integration.py` because this directory is intentionally flat.
## Ownership
- `state_monitor_integration.py` owns the runtime implementation.
- `state_monitor_integration.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Top-level functions:
- `mark_dirty_all(reason: str | None=...) -> None`
- `mark_dirty_for_context(context_id: str, reason: str | None=...) -> None`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: settings/state persistence.
- Imported dependency areas include: `__future__`.
## Key Concepts
- Important called helpers/classes observed in the source: `get_state_monitor.mark_dirty_all`, `get_state_monitor.mark_dirty_for_context`, `get_state_monitor`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_model_config_api_keys.py`
## Child DOX Index
No child DOX files.

63
helpers/state_snapshot.py.dox.md Normal file
View file

@ -0,0 +1,63 @@
# state_snapshot.py DOX
## Purpose
- Own the `state_snapshot.py` helper module.
- This module builds and validates typed WebUI state snapshots.
- Keep this file-level DOX profile synchronized with `state_snapshot.py` because this directory is intentionally flat.
## Ownership
- `state_snapshot.py` owns the runtime implementation.
- `state_snapshot.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `SnapshotV1` (`TypedDict`)
- `StateRequestV1` (no explicit base class)
- `StateRequestValidationError` (`ValueError`)
- Top-level functions:
- `_annotation_to_isinstance_types(annotation: Any) -> tuple[type, ...]`: Convert type annotation to tuple suitable for isinstance().
- `_build_schema_from_typeddict(td: type) -> dict[str, tuple[type, ...]]`: Extract field names and isinstance-compatible types from TypedDict.
- `validate_snapshot_schema_v1(snapshot: Mapping[str, Any]) -> None`
- `_coerce_non_negative_int(value: Any, default: int=...) -> int`
- `_get_agent_profile_labels() -> dict[str, str]`
- `_apply_agent_profile_metadata(context_data: dict[str, Any], ctx: AgentContext, labels: dict[str, str]) -> None`
- `parse_state_request_payload(payload: Mapping[str, Any]) -> StateRequestV1`
- `_coerce_state_request_inputs(context: Any, log_from: Any, notifications_from: Any, timezone: Any) -> StateRequestV1`
- `advance_state_request_after_snapshot(request: StateRequestV1, snapshot: Mapping[str, Any]) -> StateRequestV1`
- `async build_snapshot_from_request(request: StateRequestV1) -> SnapshotV1`: Build a poll-shaped snapshot for both /poll and state_push.
- `_notify_timezone_changed(previous_timezone: str, current_timezone: str) -> None`
- `async build_snapshot(context: str | None, log_from: int, notifications_from: int, timezone: str | None) -> SnapshotV1`
- Notable constants/configuration names: `_SNAPSHOT_V1_SCHEMA`, `SNAPSHOT_SCHEMA_V1_KEYS`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: plugin state, settings/state persistence, secret handling, scheduler state.
- Imported dependency areas include: `__future__`, `agent`, `dataclasses`, `helpers.dotenv`, `helpers.localization`, `helpers.task_scheduler`, `pytz`, `types`, `typing`.
## Key Concepts
- Important called helpers/classes observed in the source: `dataclass`, `_build_schema_from_typeddict`, `get_origin`, `timezone.strip`, `StateRequestV1`, `localization.get_timezone`, `localization.set_timezone`, `ctxid.strip`, `_coerce_non_negative_int`, `AgentContext.get_notification_manager`, `notification_manager.output`, `_get_agent_profile_labels`, `ctxs.sort`, `tasks.sort`, `validate_snapshot_schema_v1`, `_coerce_state_request_inputs`, `super.__init__`, `get_args`, `_annotation_to_isinstance_types`, `TypeError`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_multi_tab_isolation.py`
- `tests/test_snapshot_parity.py`
- `tests/test_snapshot_schema_v1.py`
- `tests/test_state_monitor.py`
- `tests/test_state_sync_handler.py`
- `tests/test_state_sync_welcome_screen.py`
## Child DOX Index
No child DOX files.

49
helpers/strings.py.dox.md Normal file
View file

@ -0,0 +1,49 @@
# strings.py DOX
## Purpose
- Own the `strings.py` helper module.
- This module sanitizes, formats, truncates, and expands framework string content.
- Keep this file-level DOX profile synchronized with `strings.py` because this directory is intentionally flat.
## Ownership
- `strings.py` owns the runtime implementation.
- `strings.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Top-level functions:
- `sanitize_string(s: str, encoding: str=...) -> str`
- `calculate_valid_match_lengths(first: bytes | str, second: bytes | str, deviation_threshold: int=..., deviation_reset: int=..., ignore_patterns: list[bytes | str]=..., debug: bool=...) -> tuple[int, int]`
- `format_key(key: str) -> str`: Format a key string to be more readable.
- `dict_to_text(d: dict) -> str`
- `truncate_text(text: str, length: int, at_end: bool=..., replacement: str=...) -> str`
- `truncate_text_by_ratio(text: str, threshold: int, replacement: str=..., ratio: float=...) -> str`: Truncate text with replacement at a specified ratio position.
- `replace_file_includes(text: str, placeholder_pattern: str=...) -> str`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, filesystem deletion.
- Imported dependency areas include: `helpers`, `re`, `sys`, `time`.
## Key Concepts
- Important called helpers/classes observed in the source: `s.encode.decode`, `join`, `join.rstrip`, `re.sub`, `skip_ignored_patterns`, `match.group`, `s.encode`, `sys.stdout.write`, `sys.stdout.flush`, `time.sleep`, `c.isupper`, `result.islower`, `word.capitalize`, `files.fix_dev_path`, `files.read_file`, `re.match`, `formatted.split`, `c.isalnum`, `format_key`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_model_search.py`
- `tests/test_whatsapp_number_utils.py`
## Child DOX Index
No child DOX files.

61
helpers/subagents.py.dox.md Normal file
View file

@ -0,0 +1,61 @@
# subagents.py DOX
## Purpose
- Own the `subagents.py` helper module.
- This module discovers, merges, loads, and saves agent profile definitions.
- Keep this file-level DOX profile synchronized with `subagents.py` because this directory is intentionally flat.
## Ownership
- `subagents.py` owns the runtime implementation.
- `subagents.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `SubAgentListItem` (`BaseModel`)
- `post_validator(self)`
- `SubAgent` (`SubAgentListItem`)
- Top-level functions:
- `get_agents_list(project_name: str | None=...) -> list[SubAgentListItem]`
- `get_agents_dict(project_name: str | None=...) -> dict[str, SubAgentListItem]`
- `_get_agents_list_from_dir(dir: str, origin: Origin) -> dict[str, SubAgentListItem]`
- `load_agent_data(name: str, project_name: str | None=...) -> SubAgent`
- `save_agent_data(name: str, subagent: SubAgent) -> None`
- `delete_agent_data(name: str) -> None`
- `_load_agent_data_from_dir(dir: str, name: str, origin: Origin) -> SubAgent | None`
- `_merge_agents(base: SubAgent | None, override: SubAgent | None) -> SubAgent | None`
- `_merge_agent_list_items(base: SubAgentListItem, override: SubAgentListItem) -> SubAgentListItem`
- `get_agents_roots() -> list[str]`
- `get_all_agents_list() -> list[dict[str, str]]`
- `_merge_origins(base: list[Origin], override: list[Origin]) -> list[Origin]`
- `get_default_promp_file_names() -> list[str]`
- `get_available_agents_dict(project_name: str | None) -> dict[str, SubAgentListItem]`
- `get_paths(agent: 'Agent|None', *subpaths, must_exist_completely: bool=..., include_project: bool=..., include_user: bool=..., include_default: bool=..., include_plugins: bool=..., default_root: str=...) -> list[str]`: Returns list of file paths for the given agent and subpaths, searched in order of priority:
- Notable constants/configuration names: `GLOBAL_DIR`, `USER_DIR`, `DEFAULT_AGENTS_DIR`, `USER_AGENTS_DIR`, `PATHS_CACHE_AREA`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, plugin state, settings/state persistence.
- Imported dependency areas include: `helpers`, `json`, `os`, `pydantic`, `typing`.
## Key Concepts
- Important called helpers/classes observed in the source: `cache.toggle_area`, `model_validator`, `_get_agents_list_from_dir`, `plugins.get_enabled_plugin_paths`, `_merge_agent_dicts`, `files.get_subdirectories`, `_load_agent_data_from_dir`, `_merge_agent`, `files.write_file`, `files.delete_dir`, `SubAgent`, `SubAgentListItem`, `files.find_existing_paths_by_pattern`, `get_agents_roots`, `files.list_files`, `get_agents_dict`, `cache.determine_cache_key`, `cache.add`, `projects.get_project_meta`, `FileNotFoundError`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_skills_runtime.py`
## Child DOX Index
No child DOX files.

44
helpers/system_packages.py.dox.md Normal file
View file

@ -0,0 +1,44 @@
# system_packages.py DOX
## Purpose
- Own the `system_packages.py` helper module.
- This module runs apt operations with retry behavior.
- Keep this file-level DOX profile synchronized with `system_packages.py` because this directory is intentionally flat.
## Ownership
- `system_packages.py` owns the runtime implementation.
- `system_packages.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Top-level functions:
- `run_apt_with_retries(runner: Callable[[], subprocess.CompletedProcess[str]], lock_timeout_seconds: int=..., retry_seconds: int=...) -> subprocess.CompletedProcess[str]`: Run an apt/dpkg command, serializing in-process callers and waiting out apt locks.
- `is_apt_lock_error(result: subprocess.CompletedProcess[str]) -> bool`
- Notable constants/configuration names: `APT_LOCK_TIMEOUT_SECONDS`, `APT_LOCK_RETRY_SECONDS`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: subprocess/runtime control.
- Imported dependency areas include: `__future__`, `subprocess`, `threading`, `time`, `typing`.
## Key Concepts
- Important called helpers/classes observed in the source: `threading.RLock`, `lower`, `time.monotonic`, `runner`, `time.sleep`, `is_apt_lock_error`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_office_document_store.py`
## Child DOX Index
No child DOX files.

64
helpers/tailscale_tunnel.py.dox.md Normal file
View file

@ -0,0 +1,64 @@
# tailscale_tunnel.py DOX
## Purpose
- Own the `tailscale_tunnel.py` helper module.
- This module implements Tailscale tunnel install and provider lifecycle behavior.
- Keep this file-level DOX profile synchronized with `tailscale_tunnel.py` because this directory is intentionally flat.
## Ownership
- `tailscale_tunnel.py` owns the runtime implementation.
- `tailscale_tunnel.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `TailscaleTunnel` (`CliTunnelHelper`)
- `stop(self)`
- Top-level functions:
- `tailscale_arch()`
- `tailscale_archive_url()`
- `install_tailscale(notify=...)`
- `resolve_tailscaled_binary(binary_path)`
- `notify_info(notify, message, data=...)`
- `tailscale_socket_args(socket_path=...)`
- `tailscale_command(binary_path, args, socket_path=...)`
- `tailscale_status(binary_path, socket_path=...)`
- `tailscale_funnel_help(binary_path, socket_path=...)`
- `compact_output(lines)`
- `tailscale_daemon_hint(output)`
- `tailscale_daemon_ready(binary_path, socket_path)`
- `read_recent_tailscaled_log()`
- `start_tailscaled(binary_path, notify=...)`
- `stop_managed_tailscaled()`
- `tailscale_up_failure_message(output, timed_out=...)`
- `run_tailscale_up(binary_path, notify=..., timeout=..., socket_path=...)`
- `ensure_tailscale_funnel_command(binary_path, socket_path=...)`
- `ensure_tailscale_ready(binary_path, notify=...)`
- Notable constants/configuration names: `TAILSCALE_URL_RE`, `TAILSCALE_LOGIN_URL_RE`, `TAILSCALE_STABLE_PACKAGES_URL`, `TAILSCALE_UP_TIMEOUT`, `TAILSCALE_FUNNEL_TIMEOUT`, `TAILSCALE_FUNNEL_HTTPS_PORT`, `TAILSCALE_DAEMON_START_TIMEOUT`, `TAILSCALE_RUNTIME_DIR`, `TAILSCALE_STATE_DIR`, `TAILSCALE_SOCKET_PATH`, `TAILSCALE_DAEMON_LOG_PATH`, `TAILSCALE_DAEMON_PID_PATH`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, network calls, subprocess/runtime control, WebSocket state, settings/state persistence, tunnel state.
- Imported dependency areas include: `collections`, `flaredantic`, `helpers`, `helpers.cli_tunnel`, `json`, `os`, `pathlib`, `queue`, `re`, `shutil`, `subprocess`, `threading`, `time`, `urllib.parse`, `urllib.request`.
## Key Concepts
- Important called helpers/classes observed in the source: `re.compile`, `Path`, `files.get_abs_path`, `cli_tunnel.platform_parts`, `tailscale_arch`, `pattern.search`, `urllib.parse.urljoin`, `shutil.which`, `tailscale_archive_url`, `cli_tunnel.download_file`, `Path.with_name`, `sibling.exists`, `callable`, `subprocess.run`, `join`, `output.lower`, `tailscale_status`, `compact_output`, `resolve_tailscaled_binary`, `tailscale_daemon_ready`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_tunnel_remote_link.py`
## Child DOX Index
No child DOX files.

112
helpers/task_scheduler.py.dox.md Normal file
View file

@ -0,0 +1,112 @@
# task_scheduler.py DOX
## Purpose
- Own the `task_scheduler.py` helper module.
- This module models, serializes, schedules, runs, and persists scheduled tasks.
- Keep this file-level DOX profile synchronized with `task_scheduler.py` because this directory is intentionally flat.
## Ownership
- `task_scheduler.py` owns the runtime implementation.
- `task_scheduler.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `TaskState` (`str`, `Enum`)
- `TaskType` (`str`, `Enum`)
- `TaskSchedule` (`BaseModel`)
- `to_crontab(self) -> str`
- `TaskPlan` (`BaseModel`)
- `create(cls, todo: list[datetime] | None=..., in_progress: datetime | None=..., done: list[datetime] | None=...)`
- `add_todo(self, launch_time: datetime)`
- `set_in_progress(self, launch_time: datetime)`
- `set_done(self, launch_time: datetime)`
- `get_next_launch_time(self) -> datetime | None`
- `should_launch(self) -> datetime | None`
- `BaseTask` (`BaseModel`)
- `update(self, name: str | None=..., state: TaskState | None=..., system_prompt: str | None=..., prompt: str | None=..., attachments: list[str] | None=..., last_run: datetime | None=..., last_result: str | None=..., context_id: str | None=..., **kwargs)`
- `check_schedule(self, frequency_seconds: float=...) -> bool`
- `get_next_run(self) -> datetime | None`
- `is_dedicated(self) -> bool`
- `get_next_run_minutes(self) -> int | None`
- `async on_run(self)`
- `async on_finish(self)`
- `async on_error(self, error: str)`
- `AdHocTask` (`BaseTask`)
- `create(cls, name: str, system_prompt: str, prompt: str, token: str, attachments: list[str] | None=..., context_id: str | None=..., project_name: str | None=..., project_color: str | None=...)`
- `update(self, name: str | None=..., state: TaskState | None=..., system_prompt: str | None=..., prompt: str | None=..., attachments: list[str] | None=..., last_run: datetime | None=..., last_result: str | None=..., context_id: str | None=..., token: str | None=..., **kwargs)`
- `ScheduledTask` (`BaseTask`)
- `create(cls, name: str, system_prompt: str, prompt: str, schedule: TaskSchedule, attachments: list[str] | None=..., context_id: str | None=..., timezone: str | None=..., project_name: str | None=..., project_color: str | None=...)`
- `update(self, name: str | None=..., state: TaskState | None=..., system_prompt: str | None=..., prompt: str | None=..., attachments: list[str] | None=..., last_run: datetime | None=..., last_result: str | None=..., context_id: str | None=..., schedule: TaskSchedule | None=..., **kwargs)`
- `check_schedule(self, frequency_seconds: float=...) -> bool`
- `get_next_run(self) -> datetime | None`
- `PlannedTask` (`BaseTask`)
- `create(cls, name: str, system_prompt: str, prompt: str, plan: TaskPlan, attachments: list[str] | None=..., context_id: str | None=..., project_name: str | None=..., project_color: str | None=...)`
- `update(self, name: str | None=..., state: TaskState | None=..., system_prompt: str | None=..., prompt: str | None=..., attachments: list[str] | None=..., last_run: datetime | None=..., last_result: str | None=..., context_id: str | None=..., plan: TaskPlan | None=..., **kwargs)`
- `check_schedule(self, frequency_seconds: float=...) -> bool`
- `get_next_run(self) -> datetime | None`
- `async on_run(self)`
- `async on_finish(self)`
- `async on_success(self, result: str)`
- `async on_error(self, error: str)`
- `SchedulerTaskList` (`BaseModel`)
- `get(cls) -> 'SchedulerTaskList'`
- `async reload(self) -> 'SchedulerTaskList'`
- `async add_task(self, task: Union[ScheduledTask, AdHocTask, PlannedTask]) -> 'SchedulerTaskList'`
- `async save(self) -> 'SchedulerTaskList'`
- `async update_task_by_uuid(self, task_uuid: str, updater_func: Callable[[Union[ScheduledTask, AdHocTask, PlannedTask]], None], verify_func: Callable[[Union[ScheduledTask, AdHocTask, PlannedTask]], bool]=...) -> Union[ScheduledTask, AdHocTask, PlannedTask] | None`
- `get_tasks(self) -> list[Union[ScheduledTask, AdHocTask, PlannedTask]]`
- `get_tasks_by_context_id(self, context_id: str, only_running: bool=...) -> list[Union[ScheduledTask, AdHocTask, PlannedTask]]`
- `async get_due_tasks(self) -> list[Union[ScheduledTask, AdHocTask, PlannedTask]]`
- `TaskScheduler` (no explicit base class)
- `get(cls) -> 'TaskScheduler'`
- `cancel_running_task(self, task_uuid: str, terminate_thread: bool=...) -> bool`
- `cancel_tasks_by_context(self, context_id: str, terminate_thread: bool=...) -> bool`
- `async reload(self)`
- `get_tasks(self) -> list[Union[ScheduledTask, AdHocTask, PlannedTask]]`
- `get_tasks_by_context_id(self, context_id: str, only_running: bool=...) -> list[Union[ScheduledTask, AdHocTask, PlannedTask]]`
- `async add_task(self, task: Union[ScheduledTask, AdHocTask, PlannedTask]) -> 'TaskScheduler'`
- `async remove_task_by_uuid(self, task_uuid: str) -> 'TaskScheduler'`
- Top-level functions:
- `normalize_schedule_timezone(timezone_name: str | None) -> str`
- `_now() -> datetime`
- `_localize_task_datetime(dt: datetime) -> datetime`
- `serialize_datetime(dt: Optional[datetime]) -> Optional[str]`: Serialize a datetime object to ISO format string in the user's timezone.
- `parse_datetime(dt_str: Optional[str]) -> Optional[datetime]`: Parse ISO format datetime string with timezone awareness.
- `serialize_task_schedule(schedule: TaskSchedule) -> Dict[str, str]`: Convert TaskSchedule to a standardized dictionary format.
- `parse_task_schedule(schedule_data: Dict[str, str]) -> TaskSchedule`: Parse dictionary into TaskSchedule with validation.
- `serialize_task_plan(plan: TaskPlan) -> Dict[str, Any]`: Convert TaskPlan to a standardized dictionary format.
- `parse_task_plan(plan_data: Dict[str, Any]) -> TaskPlan`: Parse dictionary into TaskPlan with validation.
- `serialize_task(task: Union[ScheduledTask, AdHocTask, PlannedTask]) -> Dict[str, Any]`: Standardized serialization for task objects with proper handling of all complex types.
- `serialize_tasks(tasks: list[Union[ScheduledTask, AdHocTask, PlannedTask]]) -> list[Dict[str, Any]]`: Serialize a list of tasks to a list of dictionaries.
- `deserialize_task(task_data: Dict[str, Any], task_class: Optional[Type[T]]=...) -> T`: Deserialize dictionary into appropriate task object with validation.
- Notable constants/configuration names: `SCHEDULER_FOLDER`, `LOCAL_TIMEZONE_ALIASES`, `T`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion, network calls, settings/state persistence, secret handling, scheduler state.
- Imported dependency areas include: `agent`, `asyncio`, `crontab`, `datetime`, `enum`, `helpers`, `helpers.defer`, `helpers.files`, `helpers.localization`, `helpers.persist_chat`, `helpers.print_style`, `initialize`, `nest_asyncio`, `os`, `os.path`, `pydantic`.
## Key Concepts
- Important called helpers/classes observed in the source: `nest_asyncio.apply`, `TypeVar`, `str.strip`, `callable`, `datetime.now`, `tzinfo.localize`, `Field`, `PrivateAttr`, `Localization.get.serialize_datetime`, `normalize_schedule_timezone`, `Localization.get.get_timezone`, `pytz.timezone`, `now`, `localize`, `cls`, `_localize_task_datetime`, `self.todo.remove`, `self.get_next_launch_time`, `super.__init__`, `threading.RLock`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_task_scheduler_timezone.py`
- `tests/test_timezone_regressions.py`
- `tests/test_tool_action_contracts.py`
## Child DOX Index
No child DOX files.

40
helpers/timed_input.py.dox.md Normal file
View file

@ -0,0 +1,40 @@
# timed_input.py DOX
## Purpose
- Own the `timed_input.py` helper module.
- This module reads terminal input with timeout handling.
- Keep this file-level DOX profile synchronized with `timed_input.py` because this directory is intentionally flat.
## Ownership
- `timed_input.py` owns the runtime implementation.
- `timed_input.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Top-level functions:
- `timeout_input(prompt, timeout=...)`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Imported dependency areas include: `inputimeout`, `sys`.
## Key Concepts
- Important called helpers/classes observed in the source: `inputimeout`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- 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.

54
helpers/tokens.py.dox.md Normal file
View file

@ -0,0 +1,54 @@
# tokens.py DOX
## Purpose
- Own the `tokens.py` helper module.
- This module counts and approximates tokens and trims text to budgets.
- Keep this file-level DOX profile synchronized with `tokens.py` because this directory is intentionally flat.
## Ownership
- `tokens.py` owns the runtime implementation.
- `tokens.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Top-level functions:
- `count_tokens(text: str, encoding_name=...) -> int`
- `approximate_tokens(text: str) -> int`
- `sanitize_embedded_image_data_urls(text: str) -> str`
- `approximate_prompt_tokens(text: str) -> int`
- `trim_to_tokens(text: str, max_tokens: int, direction: Literal['start', 'end'], ellipsis: str=...) -> str`
- Notable constants/configuration names: `APPROX_BUFFER`, `TRIM_BUFFER`, `EMBEDDED_IMAGE_DATA_PLACEHOLDER`, `_EMBEDDED_IMAGE_DATA_URL_PATTERN`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: secret handling.
- Imported dependency areas include: `re`, `tiktoken`, `typing`.
## Key Concepts
- Important called helpers/classes observed in the source: `re.compile`, `tiktoken.get_encoding`, `encoding.encode`, `_EMBEDDED_IMAGE_DATA_URL_PATTERN.sub`, `approximate_tokens`, `count_tokens`, `sanitize_embedded_image_data_urls`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_chat_compaction.py`
- `tests/test_default_prompt_budget.py`
- `tests/test_history_compression_wait.py`
- `tests/test_mcp_handler_multimodal.py`
- `tests/test_oauth_codex.py`
- `tests/test_oauth_gemini_api.py`
- `tests/test_oauth_xai_grok.py`
- `tests/test_ws_security.py`
## Child DOX Index
No child DOX files.

58
helpers/tool.py.dox.md Normal file
View file

@ -0,0 +1,58 @@
# tool.py DOX
## Purpose
- Own the `tool.py` helper module.
- This module defines the base agent tool class and response contract.
- Keep this file-level DOX profile synchronized with `tool.py` because this directory is intentionally flat.
## Ownership
- `tool.py` owns the runtime implementation.
- `tool.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `Response` (no explicit base class)
- `Tool` (no explicit base class)
- `async execute(self, **kwargs) -> Response`
- `async set_progress(self, content: str | None)`
- `add_progress(self, content: str | None)`
- `async before_execution(self, **kwargs)`
- `async after_execution(self, response: Response, **kwargs)`
- `get_log_object(self)`
- `nice_key(self, key: str)`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- `Tool` defines `execute(...)`.
- Observed side-effect areas: settings/state persistence.
- Imported dependency areas include: `abc`, `agent`, `dataclasses`, `helpers.extension`, `helpers.print_style`, `helpers.strings`, `typing`.
## Key Concepts
- Important called helpers/classes observed in the source: `self.get_log_object`, `sanitize_string`, `self.agent.hist_add_tool_result`, `self.agent.context.log.log`, `key.split`, `join`, `call_extensions_async`, `response.message.strip`, `uuid.uuid4`, `PrintStyle`, `PrintStyle.stream`, `words.capitalize`, `word.lower`, `self.nice_key`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_a0_connector_prompt_gating.py`
- `tests/test_browser_agent_regressions.py`
- `tests/test_default_prompt_budget.py`
- `tests/test_dirty_json.py`
- `tests/test_document_query_plugin.py`
- `tests/test_fastmcp_openapi_security.py`
- `tests/test_host_browser_connector.py`
- `tests/test_mcp_handler_multimodal.py`
## Child DOX Index
No child DOX files.

51
helpers/tunnel_common.py.dox.md Normal file
View file

@ -0,0 +1,51 @@
# tunnel_common.py DOX
## Purpose
- Own the `tunnel_common.py` helper module.
- This module contains shared tunnel provider helper classes and event parsing.
- Keep this file-level DOX profile synchronized with `tunnel_common.py` because this directory is intentionally flat.
## Ownership
- `tunnel_common.py` owns the runtime implementation.
- `tunnel_common.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `TunnelHelper` (no explicit base class)
- `notify_starting(self, label)`
- `notify_url_ready(self, label, url)`
- `notify_stopped(self, label)`
- `FlaredanticTunnelHelper` (`TunnelHelper`)
- `build_tunnel(self)`
- `start(self)`
- `stop(self)`
- Top-level functions:
- `event_value(event)`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: tunnel state.
- Imported dependency areas include: `flaredantic`.
## Key Concepts
- Important called helpers/classes observed in the source: `callable`, `self._notify`, `self.notify_starting`, `self.build_tunnel`, `self.tunnel.start`, `self.notify_stopped`, `self.notify_callback`, `self.notify_url_ready`, `self.tunnel.stop`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_tunnel_remote_link.py`
## Child DOX Index
No child DOX files.

51
helpers/tunnel_manager.py.dox.md Normal file
View file

@ -0,0 +1,51 @@
# tunnel_manager.py DOX
## Purpose
- Own the `tunnel_manager.py` helper module.
- This module selects and coordinates configured tunnel providers.
- Keep this file-level DOX profile synchronized with `tunnel_manager.py` because this directory is intentionally flat.
## Ownership
- `tunnel_manager.py` owns the runtime implementation.
- `tunnel_manager.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `TunnelManager` (no explicit base class)
- `get_instance(cls)`
- `get_notifications(self)`
- `get_last_error(self)`
- `start_tunnel(self, port=..., provider=...)`
- `stop_tunnel(self)`
- `get_tunnel_url(self)`
- Top-level functions:
- `normalize_provider(provider)`
- Notable constants/configuration names: `SUPPORTED_TUNNEL_PROVIDERS`, `TUNNEL_PROVIDER_ALIASES`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: tunnel state.
- Imported dependency areas include: `collections`, `flaredantic`, `helpers.cloudflare_tunnel`, `helpers.microsoft_tunnel`, `helpers.print_style`, `helpers.serveo_tunnel`, `helpers.tailscale_tunnel`, `helpers.tunnel_common`, `threading`, `time`.
## Key Concepts
- Important called helpers/classes observed in the source: `strip.lower`, `threading.Lock`, `join`, `ValueError`, `deque`, `self.notifications.clear`, `ServeoTunnelHelper`, `self._ensure_subscribed`, `strip`, `notifier.subscribe`, `CloudflareTunnel`, `MicrosoftDevTunnel`, `TailscaleTunnel`, `normalize_provider`, `threading.Thread`, `tunnel_thread.start`, `cls`, `event_value`, `PrintStyle.error`, `self._append_notification`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_tunnel_remote_link.py`
## Child DOX Index
No child DOX files.

57
helpers/ui_server.py.dox.md Normal file
View file

@ -0,0 +1,57 @@
# ui_server.py DOX
## Purpose
- Own the `ui_server.py` helper module.
- This module configures and owns Flask/WebUI runtime route handlers.
- Keep this file-level DOX profile synchronized with `ui_server.py` because this directory is intentionally flat.
## Ownership
- `ui_server.py` owns the runtime implementation.
- `ui_server.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `UiServerRuntime` (no explicit base class)
- `create(cls) -> 'UiServerRuntime'`
- `refresh_runtime_settings(self) -> None`
- `register_http_routes(self) -> None`
- `register_transport_handlers(self) -> None`
- `build_asgi_app(self, startup_monitor: StartupMonitor)`
- `access_log_enabled(self) -> bool`
- `UiRouteHandlers` (no explicit base class)
- `async login_handler(self)`
- `async logout_handler(self)`
- `async serve_index(self)`
- `async serve_builtin_plugin_asset(self, plugin_name, asset_path)`
- `async serve_plugin_asset(self, plugin_name, asset_path)`
- `async serve_extension_asset(self, asset_path)`
- Top-level functions:
- `configure_process_environment() -> None`
- Notable constants/configuration names: `UPLOAD_LIMIT_BYTES`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, network calls, subprocess/runtime control, WebSocket state, plugin state, settings/state persistence, secret handling.
- Imported dependency areas include: `asyncio`, `dataclasses`, `datetime`, `flask`, `helpers`, `helpers.api`, `helpers.extension`, `helpers.files`, `helpers.print_style`, `helpers.server_startup`, `helpers.ws`, `helpers.ws_manager`, `logging`, `os`, `secrets`, `socketio`.
## Key Concepts
- Important called helpers/classes observed in the source: `logging.getLogger.setLevel`, `Localization.get.apply_process_timezone`, `field`, `Flask`, `threading.RLock`, `socketio.AsyncServer`, `WsManager`, `set_shared_ws_manager`, `cls`, `server_runtime.refresh_runtime_settings`, `settings_helper.get_settings`, `settings_helper.set_runtime_settings_snapshot`, `self.ws_manager.set_server_restart_broadcast`, `UiRouteHandlers`, `self.webapp.add_url_rule`, `register_api_route`, `register_ws_namespace`, `files.read_file`, `render_template_string`, `session.pop`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- 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.

41
helpers/update_check.py.dox.md Normal file
View file

@ -0,0 +1,41 @@
# update_check.py DOX
## Purpose
- Own the `update_check.py` helper module.
- This module checks available Agent Zero updates.
- Keep this file-level DOX profile synchronized with `update_check.py` because this directory is intentionally flat.
## Ownership
- `update_check.py` owns the runtime implementation.
- `update_check.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Top-level functions:
- `async check_version()`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: network calls, settings/state persistence.
- Imported dependency areas include: `hashlib`, `helpers`.
## Key Concepts
- Important called helpers/classes observed in the source: `git.get_version`, `git.is_official_agent_zero_repo`, `hashlib.sha256.hexdigest`, `httpx.AsyncClient`, `response.json`, `client.post`, `hashlib.sha256`, `runtime.get_persistent_id.encode`, `runtime.get_persistent_id`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- 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.

53
helpers/vector_db.py.dox.md Normal file
View file

@ -0,0 +1,53 @@
# vector_db.py DOX
## Purpose
- Own the `vector_db.py` helper module.
- This module wraps FAISS vector storage, retrieval, and comparator behavior.
- Keep this file-level DOX profile synchronized with `vector_db.py` because this directory is intentionally flat.
## Ownership
- `vector_db.py` owns the runtime implementation.
- `vector_db.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `MyFaiss` (`FAISS`)
- `get_by_ids(self, ids: Sequence[str]) -> List[Document]`
- `async aget_by_ids(self, ids: Sequence[str]) -> List[Document]`
- `get_all_docs(self) -> dict[str, Document]`
- `VectorDB` (no explicit base class)
- `async search_by_similarity_threshold(self, query: str, limit: int, threshold: float, filter: str=...)`
- `async search_by_metadata(self, filter: str, limit: int=...) -> list[Document]`
- `async insert_documents(self, docs: list[Document])`
- `async delete_documents_by_ids(self, ids: list[str])`
- Top-level functions:
- `format_docs_plain(docs: list[Document]) -> list[str]`
- `cosine_normalizer(val: float) -> float`
- `get_comparator(condition: str)`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem deletion.
- Imported dependency areas include: `agent`, `faiss`, `helpers`, `langchain.embeddings`, `langchain.storage`, `langchain_community.docstore.in_memory`, `langchain_community.vectorstores`, `langchain_community.vectorstores.utils`, `langchain_core.documents`, `simpleeval`, `typing`.
## Key Concepts
- Important called helpers/classes observed in the source: `self.get_by_ids`, `agent.get_embedding_model`, `self._get_embeddings`, `faiss.IndexFlatIP`, `MyFaiss`, `get_comparator`, `self.db.get_all_docs`, `InMemoryByteStore`, `CacheBackedEmbeddings.from_bytes_store`, `self.db.asearch`, `comparator`, `guids.generate_id`, `zip`, `self.db.add_documents`, `self.db.aget_by_ids`, `simple_eval`, `self.embeddings.embed_query`, `InMemoryDocstore`, `self.db.adelete`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- 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.

74
helpers/virtual_desktop.py.dox.md Normal file
View file

@ -0,0 +1,74 @@
# virtual_desktop.py DOX
## Purpose
- Own the `virtual_desktop.py` helper module.
- This module registers and proxies virtual desktop sessions.
- Keep this file-level DOX profile synchronized with `virtual_desktop.py` because this directory is intentionally flat.
## Ownership
- `virtual_desktop.py` owns the runtime implementation.
- `virtual_desktop.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `VirtualDesktopEndpoint` (no explicit base class)
- `VirtualDesktopRegistry` (no explicit base class)
- `register(self, endpoint: VirtualDesktopEndpoint) -> None`
- `unregister(self, token: str) -> None`
- `proxy_for_token(self, token: str) -> VirtualDesktopEndpoint | None`
- `resize(self, token: str, width: int, height: int) -> dict[str, Any]`
- Top-level functions:
- `register_session(token: str, host: str, port: int, owner: str=..., title: str=..., resize: ResizeCallback | None=...) -> None`
- `unregister_session(token: str) -> None`
- `proxy_for_token(token: str) -> VirtualDesktopEndpoint | None`
- `resize_session(token: str, width: int, height: int) -> dict[str, Any]`
- `get_registry() -> VirtualDesktopRegistry`
- `session_url(token: str, title: str=...) -> str`
- `collect_status() -> dict[str, Any]`
- `find_xpra_html_root() -> Path | None`
- `_package_installed(package: str) -> bool`
- `normalize_size(width: int | float | str, height: int | float | str, max_width: int=..., max_height: int=..., min_width: int=..., min_height: int=...) -> tuple[int, int]`
- `normalize_desktop_display_size(width: int | float | str, height: int | float | str, max_width: int=..., max_height: int=..., min_width: int=..., min_height: int=..., min_aspect_ratio: float=...) -> tuple[int, int]`
- `resize_display(display: int, width: int, height: int, max_width: int=..., max_height: int=..., window_class: str=..., keys: tuple[str, ...]=..., xauthority: str=..., home: str=...) -> dict[str, Any]`
- `_ensure_xrandr_mode(env: dict[str, str], width: int, height: int) -> None`
- `_select_xrandr_mode(env: dict[str, str], width: int, height: int) -> subprocess.CompletedProcess[str]`
- `_xrandr_output_modes(env: dict[str, str]) -> tuple[str, set[str]]`
- `current_display_size(display: int, xauthority: str=..., home: str=...) -> tuple[int, int] | None`
- `fit_window_until(display: int, width: int, height: int, window_class: str=..., keys: tuple[str, ...]=..., settle_seconds: float=..., timeout_seconds: float=..., process: subprocess.Popen[Any] | None=..., xauthority: str=..., home: str=...) -> None`
- `fit_window(display: int, width: int, height: int, window_class: str=..., keys: tuple[str, ...]=..., xauthority: str=..., home: str=...) -> bool`
- `has_window(display: int, window_class: str=..., name: str=..., xauthority: str=..., home: str=...) -> bool`
- `find_window(display: int, window_class: str=..., name: str=..., xauthority: str=..., home: str=...) -> str`
- `close_windows(display: int, names: tuple[str, ...]=..., window_class: str=..., xauthority: str=..., home: str=...) -> int`
- `_find_window(display: int, window_class: str=..., name: str=..., xauthority: str=..., home: str=...) -> str`
- `_display_env(display: int, xauthority: str=..., home: str=...) -> dict[str, str]`
- Notable constants/configuration names: `STATE_DIR`, `DEFAULT_WIDTH`, `DEFAULT_HEIGHT`, `MAX_WIDTH`, `MAX_HEIGHT`, `MIN_WIDTH`, `MIN_HEIGHT`, `MIN_DESKTOP_ASPECT_RATIO`, `SESSION_PATH`, `XPRA_HTML_ROOT_CANDIDATES`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, filesystem writes, network calls, subprocess/runtime control, plugin state, settings/state persistence, secret handling.
- Imported dependency areas include: `__future__`, `dataclasses`, `helpers`, `helpers.localization`, `math`, `os`, `pathlib`, `re`, `shutil`, `subprocess`, `threading`, `time`, `typing`, `urllib.parse`.
## Key Concepts
- Important called helpers/classes observed in the source: `Path`, `files.get_abs_path`, `get_registry.register`, `get_registry.unregister`, `get_registry.proxy_for_token`, `get_registry.resize`, `quote`, `urlencode`, `find_xpra_html_root`, `subprocess.run`, `normalize_size`, `shutil.which`, `_display_env`, `current_display_size`, `_ensure_xrandr_mode`, `_select_xrandr_mode`, `time.sleep`, `strip`, `_xrandr_output_modes`, `result.stdout.splitlines`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_office_canvas_setup.py`
- `tests/test_office_desktop_state.py`
- `tests/test_office_document_store.py`
## Child DOX Index
No child DOX files.

55
helpers/virtual_desktop_routes.py.dox.md Normal file
View file

@ -0,0 +1,55 @@
# virtual_desktop_routes.py DOX
## Purpose
- Own the `virtual_desktop_routes.py` helper module.
- This module installs virtual desktop gateway route hooks.
- Keep this file-level DOX profile synchronized with `virtual_desktop_routes.py` because this directory is intentionally flat.
## Ownership
- `virtual_desktop_routes.py` owns the runtime implementation.
- `virtual_desktop_routes.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `VirtualDesktopGateway` (no explicit base class)
- `async http(self, scope: Scope, receive: Receive, send: Send) -> None`
- `async resize(self, scope: Scope, receive: Receive, send: Send) -> None`
- `async proxy_http(self, scope: Scope, receive: Receive, send: Send, token: str, upstream_path: str) -> None`
- `async websocket(self, scope: Scope, receive: Receive, send: Send) -> None`
- `async open_websocket(self, endpoint: virtual_desktop.VirtualDesktopEndpoint, target: str, subprotocols: tuple[str, ...]) -> tuple[asyncio.StreamReader, asyncio.StreamWriter, WSConnection, str | None]`
- `async browser_to_xpra(self, websocket: WebSocket, upstream: WSConnection, writer: asyncio.StreamWriter) -> None`
- `async xpra_to_browser(self, websocket: WebSocket, upstream: WSConnection, reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None`
- `session_request(self, path: str) -> tuple[str, str] | None`
- Top-level functions:
- `install_route_hooks() -> None`
- `is_installed() -> bool`
- Notable constants/configuration names: `HOP_BY_HOP_HEADERS`, `XPRA_MENU_CUSTOM_PATCH`, `XPRA_WINDOW_OFFSET_WARNING`, `XPRA_WINDOW_OFFSET_WARNING_PATCH`, `XPRA_WINDOW_SCRIPT`, `XPRA_WINDOW_SCRIPT_PATCH`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem deletion, network calls, subprocess/runtime control, WebSocket state, settings/state persistence, secret handling.
- Imported dependency areas include: `__future__`, `asyncio`, `flask.sessions`, `helpers`, `http.client`, `http.cookies`, `starlette.requests`, `starlette.responses`, `starlette.types`, `starlette.websockets`, `urllib.parse`, `wsproto`, `wsproto.events`.
## Key Concepts
- Important called helpers/classes observed in the source: `self.relative_path`, `self.session_request`, `self.query`, `virtual_desktop.proxy_for_token`, `WebSocket`, `self.upstream_target`, `WSConnection`, `writer.write`, `rest.partition`, `unquote`, `quote`, `http.client.HTTPConnection`, `query_string.decode`, `urlsplit`, `location.startswith`, `path.startswith`, `parse_qs`, `login.get_credentials_hash`, `SecureCookieSessionInterface.get_signing_serializer`, `dict.get.decode`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_office_canvas_setup.py`
- `tests/test_office_document_store.py`
## Child DOX Index
No child DOX files.

49
helpers/wait.py.dox.md Normal file
View file

@ -0,0 +1,49 @@
# wait.py DOX
## Purpose
- Own the `wait.py` helper module.
- This module formats and runs managed waits with progress updates.
- 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.
- Top-level functions:
- `format_remaining_time(total_seconds: float) -> str`
- `async managed_wait(agent, target_time, is_duration_wait, log, get_heading_callback)`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Imported dependency areas include: `asyncio`, `helpers.localization`, `helpers.print_style`.
## Key Concepts
- Important called helpers/classes observed in the source: `divmod`, `join`, `Localization.get.now`, `total_seconds`, `agent.handle_intervention`, `asyncio.sleep`, `pause_duration.total_seconds`, `PrintStyle.info`, `get_heading_callback`, `format_remaining_time`, `Localization.get.serialize_datetime`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- 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.

72
helpers/watchdog.py.dox.md Normal file
View file

@ -0,0 +1,72 @@
# watchdog.py DOX
## Purpose
- Own the `watchdog.py` helper module.
- This module registers filesystem watchdogs with debouncing and path filtering.
- Keep this file-level DOX profile synchronized with `watchdog.py` because this directory is intentionally flat.
## Ownership
- `watchdog.py` owns the runtime implementation.
- `watchdog.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `_DispatchHandler` (no explicit base class)
- `dispatch(self, event: Any)`
- `_Watch` (no explicit base class)
- `_PendingBatch` (no explicit base class)
- `_WatchRegistry` (no explicit base class)
- `add(self, id: str, roots: list[str], patterns: list[str] | None, ignore_patterns: list[str] | None, events: WatchEvents, debounce: float, handler: WatchHandler) -> None`
- `remove(self, id: str) -> bool`
- `clear(self) -> None`
- `start(self) -> None`
- `stop(self) -> None`
- `dispatch(self, scheduled_root: str, event: Any) -> None`
- Top-level functions:
- `_normalize_root(root: str) -> str`
- `_normalize_roots(roots: list[str]) -> list[str]`
- `_normalize_patterns(patterns: list[str] | None, default: list[str] | None=...) -> list[str]`
- `_normalize_events(events: WatchEvents) -> frozenset[WatchEvent]`
- `_map_event_type(event_type: str) -> WatchEvent | None`
- `_normalize_debounce(debounce: float) -> float`
- `_covering_roots(roots: Iterable[str]) -> set[str]`
- `_is_same_or_nested(path: str, root: str) -> bool`
- `_is_under_watch(path: str, watch: _Watch) -> bool`
- `_compile_matcher(root: str, patterns: list[str], ignore_patterns: list[str]) -> PatternMatcher`
- `_compile_single_matcher(root: str, patterns: list[str]) -> PatternMatcher`
- `add_watchdog(id: str, roots: list[str], patterns: list[str] | None=..., ignore_patterns: list[str] | None=..., events: WatchEvents=..., debounce: float=..., handler: WatchHandler | None=...) -> None`
- `remove_watchdog(id: str) -> bool`
- `clear_watchdogs() -> None`
- `start_watchdog_daemon() -> None`
- `stop_watchdog_daemon() -> None`
- Notable constants/configuration names: `_DEFAULT_PATTERNS`, `_DEFAULT_IGNORE_PATTERNS`, `_VALID_EVENTS`, `_EVENT_ALIASES`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem reads, filesystem writes, filesystem deletion.
- Imported dependency areas include: `__future__`, `dataclasses`, `os`, `pathlib`, `threading`, `typing`, `watchdog.observers`.
## Key Concepts
- Important called helpers/classes observed in the source: `frozenset`, `dataclass`, `_WatchRegistry`, `_registry.start`, `os.path.abspath`, `_compile_single_matcher`, `_registry.add`, `_registry.remove`, `_registry.clear`, `_registry.stop`, `self.registry.dispatch`, `threading.RLock`, `self._ensure_watchdog_available`, `_normalize_roots`, `_normalize_patterns`, `_normalize_events`, `_normalize_debounce`, `self._stop_observer`, `_map_event_type`, `_covering_roots`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_model_config_api_keys.py`
- `tests/test_model_config_project_presets.py`
- `tests/test_time_travel.py`
## Child DOX Index
No child DOX files.

75
helpers/ws.py.dox.md Normal file
View file

@ -0,0 +1,75 @@
# ws.py DOX
## Purpose
- Own the `ws.py` helper module.
- This module defines WebSocket handler registration, origin validation, and security checks.
- Keep this file-level DOX profile synchronized with `ws.py` because this directory is intentionally flat.
## Ownership
- `ws.py` owns the runtime implementation.
- `ws.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `ConnectionNotFoundError` (`RuntimeError`)
- `_SecurityContext` (no explicit base class)
- `WsHandler` (no explicit base class)
- `namespace(self) -> str`
- `manager(self) -> 'WsManager'`
- `identifier(self) -> str`
- `bind_manager(self, manager: 'WsManager', namespace: str | None=...) -> None`
- `requires_loopback(cls) -> bool`
- `requires_api_key(cls) -> bool`
- `requires_auth(cls) -> bool`
- `requires_csrf(cls) -> bool`
- Top-level functions:
- `_ws_debug_enabled() -> bool`: Check A0_WS_DEBUG env var - lightweight, no heavy imports.
- `ws_debug(message: str) -> None`: Log *message* via :class:`PrintStyle` when ``A0_WS_DEBUG`` is active.
- `_default_port_for_scheme(scheme: str) -> int | None`
- `normalize_origin(value: Any) -> str | None`: Normalize an Origin/Referer header value to scheme://host[:port].
- `_parse_host_header(value: Any) -> tuple[str | None, int | None]`
- `validate_ws_origin(environ: dict[str, Any]) -> tuple[bool, str | None]`: Validate the browser Origin during the Socket.IO handshake.
- `_check_security(handler_cls: type[WsHandler], ctx: _SecurityContext) -> dict[str, Any] | None`: Return an error payload dict if the check fails, or ``None`` on success.
- `register_ws_namespace(socketio_server: socketio.AsyncServer, webapp: Flask, lock: ThreadLockType, manager: 'WsManager | None'=...) -> None`
- `_error_response(code: str, message: str, correlation_id: str) -> dict[str, Any]`
- Notable constants/configuration names: `NAMESPACE`, `CACHE_AREA`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- `WsHandler` defines `process(...)`.
- `WsHandler` defines `requires_auth(...)`.
- `WsHandler` defines `requires_csrf(...)`.
- `WsHandler` defines `requires_api_key(...)`.
- `WsHandler` defines `requires_loopback(...)`.
- Observed side-effect areas: filesystem reads, filesystem deletion, network calls, WebSocket state, plugin state, settings/state persistence, secret handling.
- Imported dependency areas include: `abc`, `dataclasses`, `flask`, `helpers`, `helpers.errors`, `helpers.network`, `helpers.print_style`, `os`, `pathlib`, `socketio`, `threading`, `typing`, `urllib.parse`, `uuid`.
## Key Concepts
- Important called helpers/classes observed in the source: `threading.Lock`, `os.getenv.strip.lower`, `_ws_debug_enabled`, `urlparse`, `normalize_origin`, `_parse_host_header`, `handler_cls.requires_loopback`, `handler_cls.requires_auth`, `handler_cls.requires_csrf`, `handler_cls.requires_api_key`, `socketio_server.on`, `PrintStyle.debug`, `value.strip`, `origin_parsed.hostname.lower`, `_default_port_for_scheme`, `req_host.lower`, `forwarded_host_raw.strip`, `forwarded_host_raw.split.strip`, `forwarded_proto_raw.strip`, `forwarded_proto_raw.split.strip.lower`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_a0_connector_computer_use_metadata.py`
- `tests/test_a0_connector_prompt_gating.py`
- `tests/test_browser_agent_regressions.py`
- `tests/test_docker_release_plan.py`
- `tests/test_download_toast_regressions.py`
- `tests/test_git_version_label.py`
- `tests/test_host_browser_connector.py`
- `tests/test_multi_tab_isolation.py`
## Child DOX Index
No child DOX files.

70
helpers/ws_manager.py.dox.md Normal file
View file

@ -0,0 +1,70 @@
# ws_manager.py DOX
## Purpose
- Own the `ws_manager.py` helper module.
- This module manages WebSocket connections, event validation, buffering, and dispatch.
- Keep this file-level DOX profile synchronized with `ws_manager.py` because this directory is intentionally flat.
## Ownership
- `ws_manager.py` owns the runtime implementation.
- `ws_manager.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
- `WsResult` (no explicit base class)
- `ok(cls, data: dict[str, Any] | None=..., correlation_id: str | None=..., duration_ms: float | None=...) -> 'WsResult'`
- `error(cls, code: str, message: str, details: Any | None=..., correlation_id: str | None=..., duration_ms: float | None=...) -> 'WsResult'`
- `as_result(self, handler_id: str, fallback_correlation_id: str | None, duration_ms: float | None=...) -> dict[str, Any]`
- `BufferedEvent` (no explicit base class)
- `ConnectionInfo` (no explicit base class)
- `_HandlerExecution` (no explicit base class)
- `WsManager` (no explicit base class)
- `register_diagnostic_watcher(self, namespace: str, sid: str) -> bool`
- `unregister_diagnostic_watcher(self, namespace: str, sid: str) -> None`
- `register_handlers(self, handlers_by_namespace: dict[str, Iterable[WsHandler]]) -> None`
- `iter_namespaces(self) -> list[str]`
- `async process_client_event(self, namespace: str, event_type: str, data: dict[str, Any], sid: str, handlers: list[WsHandler]) -> dict[str, Any]`
- `async handle_connect(self, namespace: str, sid: str, user_id: str | None=...) -> None`
- `async handle_disconnect(self, namespace: str, sid: str) -> None`
- `async route_event(self, namespace: str, event_type: str, data: dict[str, Any], sid: str, ack: Optional[Callable[[Any], None]]=..., include_handlers: Set[str] | None=..., exclude_handlers: Set[str] | None=..., allow_exclude: bool=..., handler_id: str | None=...) -> dict[str, Any]`
- Top-level functions:
- `validate_event_type(event_type: str) -> str`: Validate an event name: must be lowercase_snake_case and not reserved.
- `async send_data(event_type: str, data: dict[str, Any], endpoint_name: str=..., connection_id: str | None=...) -> None`: Convenience wrapper around :pymeth:`WsManager.send_data`.
- `_utcnow() -> datetime`
- `set_shared_ws_manager(manager: 'WsManager') -> None`
- `get_shared_ws_manager() -> 'WsManager'`
- Notable constants/configuration names: `_EVENT_NAME_PATTERN`, `_RESERVED_EVENT_NAMES`, `BUFFER_MAX_SIZE`, `BUFFER_TTL`, `DIAGNOSTIC_EVENT`, `LIFECYCLE_CONNECT_EVENT`, `LIFECYCLE_DISCONNECT_EVENT`, `STATE_PUSH_EVENT`, `SERVER_RESTART_EVENT`, `ERR_NO_HANDLERS`, `ERR_HANDLER_ERROR`, `ERR_INVALID_FILTER`, `ERR_INVALID_EVENT`, `ERR_CONNECTION_NOT_FOUND`, `ERR_TIMEOUT`.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem deletion, network calls, WebSocket state, settings/state persistence, scheduler state.
- Imported dependency areas include: `__future__`, `asyncio`, `collections`, `dataclasses`, `datetime`, `helpers`, `helpers.defer`, `helpers.print_style`, `helpers.ws`, `os`, `re`, `socketio`, `threading`, `time`, `typing`, `uuid`.
## Key Concepts
- Important called helpers/classes observed in the source: `re.compile`, `timedelta`, `get_shared_ws_manager`, `datetime.now`, `field`, `cls`, `TypeError`, `_EVENT_NAME_PATTERN.fullmatch`, `ValueError`, `manager.send_data`, `RuntimeError`, `defaultdict`, `runtime.is_development`, `ws_debug`, `self._ensure_dispatcher_loop`, `dispatcher_loop.is_closed`, `asyncio.run_coroutine_threadsafe`, `_utcnow.isoformat.replace`, `self._copy_diagnostic_watchers`, `self._lifecycle_tasks.add`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_browser_agent_regressions.py`
- `tests/test_host_browser_connector.py`
- `tests/test_state_sync_handler.py`
- `tests/test_state_sync_welcome_screen.py`
- `tests/test_tool_action_contracts.py`
- `tests/test_ws_handlers.py`
- `tests/test_ws_manager.py`
## Child DOX Index
No child DOX files.

52
helpers/yaml.py.dox.md Normal file
View file

@ -0,0 +1,52 @@
# yaml.py DOX
## Purpose
- Own the `yaml.py` helper module.
- This module wraps YAML loading/dumping and JSON conversion helpers.
- Keep this file-level DOX profile synchronized with `yaml.py` because this directory is intentionally flat.
## Ownership
- `yaml.py` owns the runtime implementation.
- `yaml.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Top-level functions:
- `loads(text: str)`
- `dumps(obj, **kwargs) -> str`
- `from_json(text: str, **yaml_dump_kwargs) -> str`
- `to_json(text: str, **json_dump_kwargs) -> str`
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem writes, settings/state persistence.
- Imported dependency areas include: `json`, `yaml`.
## Key Concepts
- Important called helpers/classes observed in the source: `yaml.safe_load`, `yaml.safe_dump`, `dumps`, `loads`, `json.dumps`, `json.loads`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
- Preserve public helper APIs used by core code and plugins unless every caller is updated.
- Keep path, auth, secret, persistence, network, and subprocess behavior explicit and bounded.
- Prefer adding cohesive helper functions here only when behavior is reused across modules.
## Verification
- Run targeted tests for changed helper behavior; run security regressions for auth, filesystem, WebSocket, tunnel, upload, or secret-handling helpers.
- Related tests observed by source search:
- `tests/test_a0_connector_prompt_gating.py`
- `tests/test_browser_agent_regressions.py`
- `tests/test_document_query_plugin.py`
- `tests/test_model_config_api_keys.py`
- `tests/test_model_config_project_presets.py`
- `tests/test_oauth_codex.py`
- `tests/test_oauth_providers.py`
- `tests/test_office_canvas_setup.py`
## Child DOX Index
No child DOX files.